ConVars (SourceMod Scripting)/ru

Квары - это консольные переменные. Они могут иметь числовое или строчное значение. Их значения могут быть изменены через консоль или с помощью .cfg файлов, а иногда сохраняются для всех сеансов сервера.

Введение

Квары доступны через Handle`s. Есть 2 способа получить Handle квара. Создать новый квар или найти существующий. Если вы создадите уже существующий квар, автоматически будет использоваться старый.

Примечание: Handle`s для кваров являются уникальными, их не нужно закрывать или присваивать INVALID_HANDLE. Они должны существовать пока SourceMod запущен.

Поиск кваров

Искать квары очень просто. Например, вы хотите найти mp_startmoney из Counter-Strike:Source:

new g_hStartMoney
 
public OnPluginStart()
{
	g_hStartMoney = FindConVar("mp_startmoney")
}

Примечание: FindConVar() вернет INVALID_HANDLE если квар не найден. Keep this in mind if you are trying to read ConVars from other plugins.

Создание кваров

Простейший квар требует всего 2 значения: имя и значение по умолчанию. Тем не менее, он может содержать описание:

new Handle:g_hEnabled
 
public OnPluginStart()
{
	g_hEnabled = CreateConVar("myplugin_enabled", "1", "Включение/Выключение плагина.")
}

Вы так же имеете возможностю ограничить значение. Например, давайте создадим квар названием myplugin_ratio, который не может быть выше 1,0 и ниже 0,1.

new Handle:g_hEnabled
 
public OnPluginStart()
{
	g_hEnabled = CreateConVar("myplugin_ratio",
			"0.6",
			"Sets a vote ratio",
			_,	/* Флаги (будут обсуждаться позже) */
			true,	/* Включить минимальное значение */
			0.1,
			true,	/* Включить максимальное значение */
			1.0)
}

Значение по умолчанию может иметь любой тип данных, и оно не ограничивает будущие типы данных, которые можно использовать. Тем не менее, минимальные и максимальные ограничения всегда должны быть числом с плавающей точкой (float).

Если вы создаете квар, который уже существует, вы получите Handle на этот квар. Кроме того, сами Handle будут идентичны, поскольку плагин будет владеть Handle. Описание, значение по умолчанию, или ограничения не будут изменены.

Использование/Изменение значений

Использовать квары очень просто. Например, мы хотим изменить mp_startmoney, но сохранить старое значение и восстановить его позже. Повторно используем наш код mp_startmoney от раздела Получение кваров:

new g_oldmoney
 
SetStartMoney(newmoney)
{
	g_oldmoney = GetConVarInt(g_hStartMoney)
	SetConVarInt(g_hStartMoney, newmoney)
}
 
RestoreStartMoney()
{
	SetConVarInt(g_hStartMoney, g_oldmoney)
}

Although there are different functions for value types (float, string, et cetera), the internal data is always stored the same way. For example, this code will work:

public GetStartMoney()
{
	decl String:buffer[128]
 
	GetConVarString(g_hStartMoney, buffer, sizeof(buffer))
 
	return StringToInt(buffer)
}

Even though mp_startmoney is an integer, it can still be retrieved as a string.

Flags

ConVars can have a number of flags to change their behaviour. A few of the important flags are:

• FCVAR_PROTECTED - Sensitive information (should not be exposed to clients or logs).
• FCVAR_NOTIFY - Clients are notified of changes.
• FCVAR_CHEAT - Can only be use if sv_cheats is 1.
• FCVAR_REPLICATED - Setting is forced to clients.

Let's say we wanted to toggle whether a cvar had FCVAR_CHEAT. The following two functions could be used:

UnsetCheatVar(Handle:hndl)
{
	new flags = GetConVarFlags(hndl)
	flags &= ~FCVAR_CHEAT
	SetConVarFlags(hndl, flags)
}
 
SetCheatVar(Handle:hndl)
{
	new flags = GetConVarFlags(hndl)
	flags |= FCVAR_CHEAT
	SetConVarFlags(hndl, flags)
}

Change Callbacks

As of Half-Life 2, it is possible to know when ConVars change. While this is a very powerful feature, you must be careful not to set a ConVar inside a ConVar change hook such that it re-invokes he same callback. This results in infinite recursion.

For example, let's say you want to detect when bot_quota changes and to prevent it from going below 2:

new Handle:g_hBotQuota
 
public OnPluginStart()
{
	g_hBotQuota = FindConVar("bot_quota")
	if (g_hBotQuota != INVALID_HANDLE)
	{
		HookConVarChange(g_hBotQuota, OnBotQuotaChange)
	}
}
 
public OnBotQuotaChange(Handle:cvar, const String:oldVal[], const String:newVal[])
{
	if (StringToInt(newVal) < 2)
	{
		SetConVarInt(cvar, 2)
	}
}

Note 1: You do not need to explicitly unhook ConVarChange functions on shutdown. These hooks are removed when your plugin unloads.

Note 2: You cannot prevent cvar changes from happening; you can only change the value again. If the engine or game mod already have a change function installed for a ConVar, that function will always be called first.