Difference between revisions of "ConVars (SourceMod Scripting)"

From AlliedModders Wiki
Jump to: navigation, search
m
m
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
ConVars are ''con''sole ''var''iables. They store string, float, or numerical values. These values can be changed via the console or .cfg files, and sometimes even persist across server sessions.
+
{{Languages|ConVars_(SourceMod_Scripting)}}
 +
This page for the new [[SourcePawn Transitional Syntax]]. For the old syntax see [https://wiki.alliedmods.net/index.php?title=ConVars_(SourceMod_Scripting)&oldid=6865 old version of page].
  
=Introduction=
+
'''ConVars''' are ''con''sole ''var''iables. They store string which can view as boolean, float, or numerical values. These values can be changed via the console or .cfg files, and sometimes even persist across server sessions.
ConVars are accessed through Handles. There are two ways to obtain a ConVar Handle. You can either create a new ConVar, or find an existing one. If you create a ConVar that already exists, it will automatically re-use the old one.
 
  
''Note: ConVar Handles are unique to the ConVar, and do not need to be freed or "uncreated."  They exist until SourceMod is unloaded.''
+
= Introduction =
 +
ConVars are accessed through own class named as [https://sm.alliedmods.net/new-api/convars/ConVar ConVar]. There are two ways to obtain a ConVar. You can either create a new ConVar, or find an existing one. If you create a ConVar that already exists, it will automatically re-use the old one.
  
==Finding ConVars==
+
== Finding ConVars ==
Finding ConVars is very simple. For example, let's say you want to use <tt>mp_startmoney</tt> from Counter-Strike:Source:
+
Finding ConVars is very simple. For example, let's say you want to use <tt>mp_startmoney</tt> from Counter-Strike:Source:
  
<pawn>new g_hStartMoney
+
<pawn>ConVar g_cvStartMoney;
  
public OnPluginStart()
+
public void OnPluginStart()
 
{
 
{
g_hStartMoney = FindConVar("mp_startmoney")
+
g_cvStartMoney = FindConVar("mp_startmoney");
 
}</pawn>
 
}</pawn>
  
''Note: FindConVar() will return ''<tt>INVALID_HANDLE</tt>'' if the ConVar is not found.  Keep this in mind if you are trying to read ConVars from other plugins.''
+
''Note: FindConVar() will return ''<tt>null</tt>'' if the ConVar is not found.  Keep this in mind if you are trying to read ConVars from other plugins.''
  
==Creating ConVars==
+
== Creating ConVars ==
A simple ConVar only requires two parameters, a name and a default value. However, it's a good idea to include a description:
+
A simple ConVar only requires two parameters, a name and a default value. However, it's a good idea to include a description:
  
<pawn>new Handle:g_hEnabled
+
<pawn>ConVar g_cvEnabled;
  
public OnPluginStart()
+
public void OnPluginStart()
 
{
 
{
g_hEnabled = CreateConVar("myplugin_enabled", "1", "Sets whether my plugin is enabled")
+
g_cvEnabled = CreateConVar("myplugin_enabled", "1", "Sets whether my plugin is enabled");
 
}</pawn>
 
}</pawn>
  
You can also specify value constraints. For example, let's create a cvar called <tt>myplugin_ratio</tt> which cannot go above 1.0 or below 0.1.
+
You can also specify value constraints. For example, let's create a cvar called <tt>myplugin_ratio</tt> which cannot go above 1.0 or below 0.1.
<pawn>new Handle:g_hEnabled
+
<pawn>ConVar g_cvRatio;
  
public OnPluginStart()
+
public void OnPluginStart()
 
{
 
{
g_hEnabled = CreateConVar("myplugin_ratio",
+
g_cvRatio = CreateConVar("myplugin_ratio",
 
"0.6",
 
"0.6",
 
"Sets a vote ratio",
 
"Sets a vote ratio",
Line 40: Line 41:
 
0.1,
 
0.1,
 
true, /* Has a maximum */
 
true, /* Has a maximum */
1.0)
+
1.0);
 
}</pawn>
 
}</pawn>
  
 
The default value can be any type of data, and it does not restrict future data types that can be used.  However, the minimum and maximum constraints always interpret the value as a float.
 
The default value can be any type of data, and it does not restrict future data types that can be used.  However, the minimum and maximum constraints always interpret the value as a float.
  
If you create a ConVar that already exists, you will receive a Handle to that ConVarFurthermore, the Handle itself will be identical, as neither plugin will own the HandleThe description, default value, or constraints will not be changed.
+
= Using/Changing Values =
 +
Managing ConVars is very simpleFor example, let's say we want to change <tt>mp_startmoney</tt>, but save the old value and restore it laterRe-using our <tt>mp_startmoney</tt> code from <tt>[[ConVars_(SourceMod_Scripting)#Finding _ConVars|FindConVar]]</tt>:
  
=Using/Changing Values=
+
<pawn>int g_oldmoney;
Managing ConVars is very simple.  For example, let's say we want to change <tt>mp_startmoney</tt>, but save the old value and restore it later.  Re-using our <tt>mp_startmoney</tt> code from <tt>FindConVar</tt>:
 
  
<pawn>new g_oldmoney
+
void SetStartMoney(int newmoney)
 
 
SetStartMoney(newmoney)
 
 
{
 
{
g_oldmoney = GetConVarInt(g_hStartMoney)
+
g_oldmoney = g_hStartMoney.IntValue;
SetConVarInt(g_hStartMoney, newmoney)
+
g_cvStartMoney.IntValue = newmoney;
 
}
 
}
  
RestoreStartMoney()
+
void RestoreStartMoney()
 
{
 
{
SetConVarInt(g_hStartMoney, g_oldmoney)
+
g_cvStartMoney.IntValue = g_oldmoney;
 
}</pawn>
 
}</pawn>
  
 
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:
 
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:
  
<pawn>public GetStartMoney()
+
<pawn>public int GetStartMoney()
 
{
 
{
decl String:buffer[128]
+
char buffer[128];
  
GetConVarString(g_hStartMoney, buffer, sizeof(buffer))
+
g_cvStartMoney.GetString(buffer, 128);
  
return StringToInt(buffer)
+
return StringToInt(buffer);
 
}</pawn>
 
}</pawn>
  
 
Even though <tt>mp_startmoney</tt> is an integer, it can still be retrieved as a string.
 
Even though <tt>mp_startmoney</tt> is an integer, it can still be retrieved as a string.
  
=Flags=
+
= Flags =
 
ConVars can have a number of flags to change their behaviour.  A few of the important flags are:
 
ConVars can have a number of flags to change their behaviour.  A few of the important flags are:
 
*<tt>FCVAR_PROTECTED</tt> - Sensitive information (should not be exposed to clients or logs).
 
*<tt>FCVAR_PROTECTED</tt> - Sensitive information (should not be exposed to clients or logs).
Line 84: Line 83:
  
 
Let's say we wanted to toggle whether a cvar had FCVAR_CHEAT.  The following two functions could be used:
 
Let's say we wanted to toggle whether a cvar had FCVAR_CHEAT.  The following two functions could be used:
<pawn>UnsetCheatVar(Handle:hndl)
+
<pawn>void UnsetCheatVar(ConVar convar)
 
{
 
{
new flags = GetConVarFlags(hndl)
+
int flags = convar.Flags;
flags &= ~FCVAR_CHEAT
+
flags &= ~FCVAR_CHEAT;
SetConVarFlags(hndl, flags)
+
convar.Flags = flags;
 
}
 
}
  
SetCheatVar(Handle:hndl)
+
void SetCheatVar(ConVar convar)
 
{
 
{
new flags = GetConVarFlags(hndl)
+
int flags = convar.Flags;
flags |= FCVAR_CHEAT
+
flags |= FCVAR_CHEAT;
SetConVarFlags(hndl, flags)
+
convar.Flags = flags;
 
}</pawn>
 
}</pawn>
  
=Change Callbacks=
+
= 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''.
+
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 the same callback.  This results in ''infinite recursion''.
  
 
For example, let's say you want to detect when <tt>bot_quota</tt> changes and to prevent it from going below 2:
 
For example, let's say you want to detect when <tt>bot_quota</tt> changes and to prevent it from going below 2:
  
<pawn>new Handle:g_hBotQuota
+
<pawn>ConVar g_hBotQuota;
  
public OnPluginStart()
+
public void OnPluginStart()
 
{
 
{
g_hBotQuota = FindConVar("bot_quota")
+
g_hBotQuota = FindConVar("bot_quota");
if (g_hBotQuota != INVALID_HANDLE)
+
if (g_hBotQuota != null)
 
{
 
{
HookConVarChange(g_hBotQuota, OnBotQuotaChange)
+
g_hBotQuota.AddChangeHook(OnBotQuotaChange);
 
}
 
}
 
}
 
}
  
public OnBotQuotaChange(Handle:cvar, const String:oldVal[], const String:newVal[])
+
public void OnBotQuotaChange(ConVar convar, char[] oldValue, char[] newValue)
 
{
 
{
if (StringToInt(newVal) < 2)
+
if (StringToInt(newValue) < 2)
 
{
 
{
SetConVarInt(cvar, 2)
+
convar.IntValue = 2;
 
}
 
}
 
}</pawn>
 
}</pawn>

Revision as of 21:31, 13 August 2015

Language: English  • русский

This page for the new SourcePawn Transitional Syntax. For the old syntax see old version of page.

ConVars are console variables. They store string which can view as boolean, float, or numerical values. These values can be changed via the console or .cfg files, and sometimes even persist across server sessions.

Introduction

ConVars are accessed through own class named as ConVar. There are two ways to obtain a ConVar. You can either create a new ConVar, or find an existing one. If you create a ConVar that already exists, it will automatically re-use the old one.

Finding ConVars

Finding ConVars is very simple. For example, let's say you want to use mp_startmoney from Counter-Strike:Source:

ConVar g_cvStartMoney;
 
public void OnPluginStart()
{
	g_cvStartMoney = FindConVar("mp_startmoney");
}

Note: FindConVar() will return null if the ConVar is not found. Keep this in mind if you are trying to read ConVars from other plugins.

Creating ConVars

A simple ConVar only requires two parameters, a name and a default value. However, it's a good idea to include a description:

ConVar g_cvEnabled;
 
public void OnPluginStart()
{
	g_cvEnabled = CreateConVar("myplugin_enabled", "1", "Sets whether my plugin is enabled");
}

You can also specify value constraints. For example, let's create a cvar called myplugin_ratio which cannot go above 1.0 or below 0.1.

ConVar g_cvRatio;
 
public void OnPluginStart()
{
	g_cvRatio = CreateConVar("myplugin_ratio",
			"0.6",
			"Sets a vote ratio",
			_,	/* Flags will be discussed later */
			true,	/* Has a minimum */
			0.1,
			true,	/* Has a maximum */
			1.0);
}

The default value can be any type of data, and it does not restrict future data types that can be used. However, the minimum and maximum constraints always interpret the value as a float.

Using/Changing Values

Managing ConVars is very simple. For example, let's say we want to change mp_startmoney, but save the old value and restore it later. Re-using our mp_startmoney code from FindConVar:

int g_oldmoney;
 
void SetStartMoney(int newmoney)
{
	g_oldmoney = g_hStartMoney.IntValue;
	g_cvStartMoney.IntValue = newmoney;
}
 
void RestoreStartMoney()
{
	g_cvStartMoney.IntValue = 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 int GetStartMoney()
{
	char buffer[128];
 
	g_cvStartMoney.GetString(buffer, 128);
 
	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:

void UnsetCheatVar(ConVar convar)
{
	int flags = convar.Flags;
	flags &= ~FCVAR_CHEAT;
	convar.Flags = flags;
}
 
void SetCheatVar(ConVar convar)
{
	int flags = convar.Flags;
	flags |= FCVAR_CHEAT;
	convar.Flags = 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 the 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:

ConVar g_hBotQuota;
 
public void OnPluginStart()
{
	g_hBotQuota = FindConVar("bot_quota");
	if (g_hBotQuota != null)
	{
		g_hBotQuota.AddChangeHook(OnBotQuotaChange);
	}
}
 
public void OnBotQuotaChange(ConVar convar, char[] oldValue, char[] newValue)
{
	if (StringToInt(newValue) < 2)
	{
		convar.IntValue = 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.