AlliedModders Wiki - User contributions [en]

Format Class Functions (SourceMod Scripting)

2016-07-26T03:07:08Z

Shavit: {Handle,Float,_} >> any

=Introduction=
Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, which looks like:

<pawn>char buffer[512];
Format(buffer, sizeof(buffer), "Your name is: %s", userName);</pawn>

If userName contains "<tt>Mark</tt>," the contents of <tt>buffer</tt> will then be: "<tt>Your name is: Mark</tt>." The prototype of these functions almost always contains the following parameters:
<pawn>const char[] fmt, any ...</pawn>

For example, observe the following two natives:
<pawn>native void Format(char[] buffer, int maxlength, const char[] fmt, any ...);
native void PrintToClient(int client, char[] fmt, any ...);</pawn>

Thus, <tt>PrintToClient</tt> is a format-class function. It can be used exactly as shown earlier:
<pawn>PrintToClient(client, "Your name is: %s", userName);</pawn>

=Format Specifiers=
A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:
*'''Numerical'''
**'''d''' or '''i''': Integer number as decimal
**'''u''': Unsigned integer number as decimal
**'''b''': Binary digits in the value
**'''f''': Floating-point number
**'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)
*'''Character(s)'''
**'''s''': String
**'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Usage_in_a_Plugin|Translations]])
**'''c''': Prints one character (UTF-8 compliant)
*'''Special'''
**'''L''': Requires a client index; expands to 1<2><3><> where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: <tt>Console</tt>

=Usage=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<pawn>float fNum = 5.0;
int iNum = 5;
char[] str = "5";

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</pawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Advanced Formatting=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

todo: examples

For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

=Making your function Format-Class=

Sourcemod allows you to make your function Format-class, ie. pass parameters to format string variables.
Here's an example:

<pawn>public void formatExample(const char[] myString, any ...)
{
int len = strlen(myString) + 255;
char[] myFormattedString = new char[len];
VFormat(myFormattedString, len, myString, 2);

PrintToServer(myFormattedString);
}</pawn>

Using the parameter "any ...", we can pass data(s) to format our string.
Now, in order to replace the Format Specifiers by our data(s), we use the API "VFormat", which documentation can be found here : [https://sm.alliedmods.net/new-api/].

The three first parameters passed in VFormat are pretty obvious since they are the as in the Format(..) API.

The 4th parameter indicate the "any ..." parameter position in your function prototype.

[[Category:SourceMod Scripting]]

Function Calling API (SourceMod Scripting)

2016-07-26T03:04:58Z

Shavit: Fix something I missed

SourceMod provides plugins with an API for calling functions. This API can be used to call public functions in any plugin, including public functions in the same plugin.

This article is split into two sections. The first is on generic function calling, which is used for single function calls. The second is on Forwards, which is used for calling multiple functions in one operation.

For more information on forwards, readers should see [[Writing_Extensions#Creating_Events.2FForwards|forwards in extensions]].

=Generic Calling=
There are four steps to calling a function in a plugin:
<ol>
<li>Obtaining a "call Handle." This is either in the form of a function ID, tagged with <tt>Function</tt>, or a Forward Handle, tagged with <tt>Handle</tt>.</li>
<li>Starting the call.
<li>Pushing parameters in increasing order in a way that matches the function prototype.</li>
<li>Ending the the call, which performs the call operation and returns the result.</li>
</ol>

For simplicity, let's consider calling a function in our own plugin. We have the following function:
<pawn>public void OnClientDied(int attacker, int victim, const char[] weapon, bool headshot)
{
char name[MAX_NAME_LENGTH];
GetClientName(victim, name, sizeof(name))

if (attacker != victim)
{
char other[MAX_NAME_LENGTH];
GetClientName(attacker, other, sizeof(other))
PrintToServer("<\"%s\"> killed by <\"%s\"> with \"%s\" (headshot: %d)", name, other, weapon, headshot)
} else if (!attacker) {
PrintToServer("<\"%s\"> killed by \"world\" with \"%s\" (headshot: %d)", name, weapon, headshot)
} else {
PrintToServer("<\"%s\"> killed by \"self\" with \"%s\" (headshot: %d)", name, weapon, headshot)
}
}</pawn>

An indirect way to call this function would be:
<pawn>
public void EventHandler(Event event, const char[] name, bool dontBroadcast)
{
if (StrEqual(name, "player_death"))
{
char weapon[64];
int result;

event.GetString("weapon", weapon, sizeof(weapon));

/* Start function call */
Call_StartFunction(null, OnClientDied);

/* Push parameters one at a time */
Call_PushCell(GetClientOfUserId(event.GetInt("attacker")));
Call_PushCell(GetClientOfUserId(event.GetInt("userid")));
Call_PushString(weapon);
Call_PushCell(GetEventInt(event, "headshot"));

/* Finish the call, get the result */
Call_Finish(result);
}
}</pawn>

This basic example shows starting and completing a function call. However, the real use of function calling is with forwards, which is covered in the next section.

=Forwards=
Forwards are much more advantageous over single function calls. They are expandable containers, so you can store and complete many calls with very little action. Furthermore, they also adjust themselves when contained plugins are unloaded. Lastly, they are type-checked; each forward's parameter types must be known in advance, and if you push a mismatching type, the call will not complete.

Forwards must be created using the following types:
*<tt>Param_Any</tt> - Any parameter type can be pushed
*<tt>Param_Cell</tt> - A non-Float cell can be pushed
*<tt>Param_Float</tt> - A Float cell can be pushed
*<tt>Param_String</tt> - A string can be pushed
*<tt>Param_Array</tt> - An array can be pushed
*<tt>Param_VarArgs</tt> - This and all further parameters can be any type, but will be by reference. This cannot be the first parameter type, and if it is used, it must be the last parameter type.
*<tt>Param_CellByRef</tt> - A non-Float cell by reference
*<tt>Param_FloatByRef</tt> - A Float cell by reference

Strings and arrays are implicitly by-reference. When pushing variable argument parameters, if anything is pushed by-value, it will be internally automatically converted to by-reference.

Since Forwards will call multiple functions in a row, it needs to know how to interpret the return values of functions. There are four predefined methods:
*<tt>ET_Ignore</tt> - All return values will be ignored; 0 will be returned at the end.
*<tt>ET_Single</tt> - Only the last return value will be returned.
*<tt>ET_Event</tt> - Function should return an <tt>Action</tt> value (<tt>core.inc</tt>). <tt>Plugin_Stop</tt> acts as <tt>Plugin_Handled</tt>. The highest value is returned.
*<tt>ET_Hook</tt> - Function should return an <tt>Action</tt> value. <tt>Plugin_Stop</tt> ends the forward call immediately.

Let's write a simple example. Our plugin, Plugin A, wants to tell other plugins when a player dies. It has two ways of doing this, either via a ''global'' forward or a ''private'' forward. A global forward acts upon all functions in all plugins that match a single name. A private forward lets you explicitly manage which functions are in the container.

==Global Forwards==
Global forwards are very simple to use. After creation, they do not need to be maintained. An example plugin below creates a global forward with the following prototype:
<pawn>forward void OnClientDied(int attacker, int victim, const char[] weapon, bool headshot);</pawn>

Implementation:
<pawn>Handle g_DeathForward;

public void OnPluginStart()
{
g_DeathForward = CreateGlobalForward("OnClientDied", ET_Event, Param_Cell, Param_Cell, Param_String, Param_Cell)
HookEvent("player_death", EventHandler)
}

public Action EventHandler(Event event, const char[] name, bool dontBroadcast)
{
char weapon[64];
Action result;

event.GetString("weapon", weapon, sizeof(weapon));

/* Start function call */
Call_StartForward(g_DeathForward);

/* Push parameters one at a time */
Call_PushCell(GetClientOfUserId(event.GetInt("attacker")));
Call_PushCell(GetClientOfUserId(event.GetInt("userid")));
Call_PushString(weapon);
Call_PushCell(GetEventInt(event, "headshot"));

/* Finish the call, get the result */
Call_Finish(result);

return result;
}</pawn>

==Private Forwards==
Private forwards require you to manually add functions to its container. This can leave you with much more flexibility. Like global forwards, they automatically remove functions from unloaded plugins.

Usually, this is done using dynamic natives; a plugin will expose a function to add to its own forwards. For example:
<pawn>typedef OnClientDiedFunc = function Action (int attacker, int victim, const char[] weapon, bool headshot);

/**
* Calls the target function when a client dies.
*
* @param func OnClientDiedFunc function.
* @noreturn
*/
native void HookClientDeath(OnClientDiedFunc func);</pawn>

An implementation of this might look like:
<pawn>public void OnPluginStart()
{
g_DeathForward = CreateForward(ET_Event, Param_Cell, Param_Cell, Param_String, Param_Cell)
CreateNative("HookClientDeath", Native_HookClientDeath)
HookEvent("player_death", EventHandler)
}

public int Native_HookClientDeath(Handle plugin, int numParams)
{
AddToForward(g_DeathForward, plugin, view_as<Function>(GetNativeCell(1)))
}</pawn>

Note that the code to call the forward does not need to change at all.

A complete implementation of a private forward may look like this:
<pawn>typedef MyFunction = function void (int client);
native void My_NativeEx(MyFunction func);</pawn>

<pawn>Handle g_hDeathFwd;

// typedef MyFunction = function void (int client);
// native void My_NativeEx(MyFunction func);
public APLRes AskPluginLoad2(Handle plugin, bool late, const char[] error, int err_max)
{
CreateNative("My_NativeEx", My_Native);
return APLRes_Success;
}

public void OnPluginStart()
{
HookEvent("player_death", Event_Death);
g_hDeathFwd = CreateForward(ET_Ignore, Param_Cell);
}

public int My_Native(Handle plugin, int numParams)
{
AddToForward(g_hDeathFwd, plugin, view_as<Function>(GetNativeCell(1)));
}

public Action Event_Death(Event event, const char[] name, bool dontBroadcast)
{
int client = GetClientOfUserId(event.GetInt("userid"));
Call_StartForward(g_hDeathFwd);
Call_PushCell(client);
Call_Finish();
}</pawn>

[[Category:SourceMod Scripting]]

Function Calling API (SourceMod Scripting)

2016-07-26T03:04:05Z

Shavit: Update example code to transitional syntax

SourceMod provides plugins with an API for calling functions. This API can be used to call public functions in any plugin, including public functions in the same plugin.

This article is split into two sections. The first is on generic function calling, which is used for single function calls. The second is on Forwards, which is used for calling multiple functions in one operation.

For more information on forwards, readers should see [[Writing_Extensions#Creating_Events.2FForwards|forwards in extensions]].

=Generic Calling=
There are four steps to calling a function in a plugin:
<ol>
<li>Obtaining a "call Handle." This is either in the form of a function ID, tagged with <tt>Function</tt>, or a Forward Handle, tagged with <tt>Handle</tt>.</li>
<li>Starting the call.
<li>Pushing parameters in increasing order in a way that matches the function prototype.</li>
<li>Ending the the call, which performs the call operation and returns the result.</li>
</ol>

For simplicity, let's consider calling a function in our own plugin. We have the following function:
<pawn>public void OnClientDied(int attacker, int victim, const char[] weapon, bool headshot)
{
char name[MAX_NAME_LENGTH];
GetClientName(victim, name, sizeof(name))

if (attacker != victim)
{
char other[MAX_NAME_LENGTH];
GetClientName(attacker, other, sizeof(other))
PrintToServer("<\"%s\"> killed by <\"%s\"> with \"%s\" (headshot: %d)", name, other, weapon, headshot)
} else if (!attacker) {
PrintToServer("<\"%s\"> killed by \"world\" with \"%s\" (headshot: %d)", name, weapon, headshot)
} else {
PrintToServer("<\"%s\"> killed by \"self\" with \"%s\" (headshot: %d)", name, weapon, headshot)
}
}</pawn>

An indirect way to call this function would be:
<pawn>
public void EventHandler(Event event, const char[] name, bool dontBroadcast)
{
if (StrEqual(name, "player_death"))
{
char weapon[64];
int result;

event.GetString("weapon", weapon, sizeof(weapon));

/* Start function call */
Call_StartFunction(null, OnClientDied);

/* Push parameters one at a time */
Call_PushCell(GetClientOfUserId(event.GetInt("attacker")));
Call_PushCell(GetClientOfUserId(event.GetInt("userid")));
Call_PushString(weapon);
Call_PushCell(GetEventInt(event, "headshot"));

/* Finish the call, get the result */
Call_Finish(result);
}
}</pawn>

This basic example shows starting and completing a function call. However, the real use of function calling is with forwards, which is covered in the next section.

=Forwards=
Forwards are much more advantageous over single function calls. They are expandable containers, so you can store and complete many calls with very little action. Furthermore, they also adjust themselves when contained plugins are unloaded. Lastly, they are type-checked; each forward's parameter types must be known in advance, and if you push a mismatching type, the call will not complete.

Forwards must be created using the following types:
*<tt>Param_Any</tt> - Any parameter type can be pushed
*<tt>Param_Cell</tt> - A non-Float cell can be pushed
*<tt>Param_Float</tt> - A Float cell can be pushed
*<tt>Param_String</tt> - A string can be pushed
*<tt>Param_Array</tt> - An array can be pushed
*<tt>Param_VarArgs</tt> - This and all further parameters can be any type, but will be by reference. This cannot be the first parameter type, and if it is used, it must be the last parameter type.
*<tt>Param_CellByRef</tt> - A non-Float cell by reference
*<tt>Param_FloatByRef</tt> - A Float cell by reference

Strings and arrays are implicitly by-reference. When pushing variable argument parameters, if anything is pushed by-value, it will be internally automatically converted to by-reference.

Since Forwards will call multiple functions in a row, it needs to know how to interpret the return values of functions. There are four predefined methods:
*<tt>ET_Ignore</tt> - All return values will be ignored; 0 will be returned at the end.
*<tt>ET_Single</tt> - Only the last return value will be returned.
*<tt>ET_Event</tt> - Function should return an <tt>Action</tt> value (<tt>core.inc</tt>). <tt>Plugin_Stop</tt> acts as <tt>Plugin_Handled</tt>. The highest value is returned.
*<tt>ET_Hook</tt> - Function should return an <tt>Action</tt> value. <tt>Plugin_Stop</tt> ends the forward call immediately.

Let's write a simple example. Our plugin, Plugin A, wants to tell other plugins when a player dies. It has two ways of doing this, either via a ''global'' forward or a ''private'' forward. A global forward acts upon all functions in all plugins that match a single name. A private forward lets you explicitly manage which functions are in the container.

==Global Forwards==
Global forwards are very simple to use. After creation, they do not need to be maintained. An example plugin below creates a global forward with the following prototype:
<pawn>forward void OnClientDied(int attacker, int victim, const char[] weapon, bool headshot);</pawn>

Implementation:
<pawn>Handle g_DeathForward;

public void OnPluginStart()
{
g_DeathForward = CreateGlobalForward("OnClientDied", ET_Event, Param_Cell, Param_Cell, Param_String, Param_Cell)
HookEvent("player_death", EventHandler)
}

public Action EventHandler(Event event, const char[] name, bool dontBroadcast)
{
char weapon[64];
Action result;

event.GetString("weapon", weapon, sizeof(weapon));

/* Start function call */
Call_StartForward(g_DeathForward);

/* Push parameters one at a time */
Call_PushCell(GetClientOfUserId(event.GetInt("attacker")));
Call_PushCell(GetClientOfUserId(event.GetInt("userid")));
Call_PushString(weapon);
Call_PushCell(GetEventInt(event, "headshot"));

/* Finish the call, get the result */
Call_Finish(result);

return result;
}</pawn>

==Private Forwards==
Private forwards require you to manually add functions to its container. This can leave you with much more flexibility. Like global forwards, they automatically remove functions from unloaded plugins.

Usually, this is done using dynamic natives; a plugin will expose a function to add to its own forwards. For example:
<pawn>typedef OnClientDiedFunc = function Action (int attacker, int victim, const char[] weapon, bool headshot);

/**
* Calls the target function when a client dies.
*
* @param func OnClientDiedFunc function.
* @noreturn
*/
native void HookClientDeath(OnClientDiedFunc func);</pawn>

An implementation of this might look like:
<pawn>public void OnPluginStart()
{
g_DeathForward = CreateForward(ET_Event, Param_Cell, Param_Cell, Param_String, Param_Cell)
CreateNative("HookClientDeath", Native_HookClientDeath)
HookEvent("player_death", EventHandler)
}

public int Native_HookClientDeath(Handle plugin, int numParams)
{
AddToForward(g_DeathForward, plugin, Function:GetNativeCell(1))
}</pawn>

Note that the code to call the forward does not need to change at all.

A complete implementation of a private forward may look like this:
<pawn>typedef MyFunction = function void (int client);
native void My_NativeEx(MyFunction func);</pawn>

<pawn>Handle g_hDeathFwd;

// typedef MyFunction = function void (int client);
// native void My_NativeEx(MyFunction func);
public APLRes AskPluginLoad2(Handle plugin, bool late, const char[] error, int err_max)
{
CreateNative("My_NativeEx", My_Native);
return APLRes_Success;
}

public void OnPluginStart()
{
HookEvent("player_death", Event_Death);
g_hDeathFwd = CreateForward(ET_Ignore, Param_Cell);
}

public int My_Native(Handle plugin, int numParams)
{
AddToForward(g_hDeathFwd, plugin, Function:GetNativeCell(1));
}

public Action Event_Death(Event event, const char[] name, bool dontBroadcast)
{
int client = GetClientOfUserId(event.GetInt("userid"));
Call_StartForward(g_hDeathFwd);
Call_PushCell(client);
Call_Finish();
}</pawn>

[[Category:SourceMod Scripting]]

SQL (SourceMod Scripting)

2016-07-26T02:52:13Z

Shavit: Update example code to transitional syntax

This article is an introduction to using SourceMod's SQL features. It is not an introduction or tutorial about SQL or any specific SQL implementation.

SourceMod's SQL layer is formally called ''DBI'', or the '''D'''ata'''b'''ase '''I'''nterface. The interface is a generic abstraction of common SQL functions. To connect to a specific database implementation (such as MySQL, or sqLite), a SourceMod DBI "driver" must be loaded. Currently, there are drivers for MySQL and SQLite

SourceMod automatically detects and loads drivers on demand (if they exist, of course). All database natives are in <tt>scripting/include/dbi.inc</tt>. The C++ API is in <tt>public/IDBDriver.h</tt>.

=Connecting=
There are two ways to connect to a database. The first is through named configurations. Named configurations are preset configurations listed in <tt>configs/databases.cfg</tt>. SourceMod specifies that if SQL is being used, there should always be one configuration named "default."

An example of such a configuration looks like:
<pre> "default"
{
"host" "localhost"
"database" "sourcemod"
"user" "root"
"pass" ""
//"timeout" "0"
//"port" "0"
}</pre>

Connections based on named configurations can be instantiated with either <tt>SQL_Connect</tt> or <tt>SQL_DefConnect</tt>.

The other option is to use <tt>SQL_ConnectCustom</tt> and manually specify all connection parameters by passing a keyvalue handle containing them.

Example of a typical connection:
<pawn>char error[255];
Database db = SQL_DefConnect(error, sizeof(error));

if (db == null)
{
PrintToServer("Could not connect: %s", error);
}
else
{
delete db;
}</pawn>

=Queries=

==No Results==
The simplest queries are ones which do not return results -- for example, CREATE, DROP, UPDATE, INSERT, and DELETE. For such queries it is recommended to use <tt>SQL_FastQuery()</tt>. The name does not imply that the query will be faster, but rather, it is faster to write code using this function. For example, given that <tt>db</tt> is a valid database Handle:

<pawn>if (!SQL_FastQuery(db, "UPDATE stats SET players = players + 1"))
{
char error[255];
SQL_GetError(db, error, sizeof(error));
PrintToServer("Failed to query (error: %s)", error);
}</pawn>

==Results==
If a query returns a result set and the results must be processed, you must use <tt>SQL_Query()</tt>. Unlike <tt>SQL_FastQuery()</tt>, this function returns a Handle which must be closed.

An example of a query which will produce results is:
<pawn>DBResultSet query = SQL_Query(db, "SELECT userid FROM vb_user WHERE username = 'BAILOPAN'");
if (query == null)
{
char error[255];
SQL_GetError(db, error, sizeof(error));
PrintToServer("Failed to query (error: %s)", error);
}
else
{
/* Process results here!
*/

/* Free the Handle */
delete query;
}</pawn>

=Prepared Statements=
Prepared statements are another method of querying. The idea behind a prepared statement is that you construct a query "template" once, and re-use it as many times as needed. Prepared statements have the following benefits:
*A good SQL implementation will be able to cache the query better if it is a prepared statement.
*You don't have to rebuild the entire query string every execution.
*You don't have to allocate a new query structure on every execution.
*Input is "always" secure (more on this later).

A prepared statement has "markers" for inputs. For example, let's consider a function that takes in a database Handle and a name, and retrieves some info from a table:
<pawn>int GetSomeInfo(Database db, const char[] name)
{
DBResultSet hQuery;
char query[100];

/* Create enough space to make sure our string is quoted properly */
int buffer_len = strlen(name) * 2 + 1;
char[] new_name = new char[buffer_len];

/* Ask the SQL driver to make sure our string is safely quoted */
SQL_EscapeString(db, name, new_name, buffer_len);

/* Build the query */
Format(query, sizeof(query), "SELECT userid FROM vb_user WHERE username = '%s'", new_name);

/* Execute the query */
if ((hQuery = SQL_Query(query)) == null)
{
return 0;
}

/* Get some info here
*/

delete hQuery;
}</pawn>

Observe a version with prepared statements:
<pawn>DBStatement hUserStmt = null;
int GetSomeInfo(Database db, const char[] name)
{
/* Check if we haven't already created the statement */
if (hUserStmt == null)
{
char error[255];
hUserStmt = SQL_PrepareQuery(db, "SELECT userid FROM vb_user WHERE username = ?", error, sizeof(error));
if (hUserStmt == null)
{
return 0;
}
}

SQL_BindParamString(hUserStmt, 0, name, false);
if (!SQL_Execute(hUserStmt))
{
return 0;
}

/**
* Get some info here
*/
}</pawn>

The important differences:
*The input string (<tt>name</tt>) did not need to be backticked (quoted). The SQL engine automatically performs all type safety and insertion checks.
*There was no need for quotation marks around the parameter marker, <tt>?</tt>, even though it accepted a string.
*We only needed to create the statement Handle once; after that it can live for the lifetime of the database connection.

=Processing Results=
Processing results is done in the same manner for both normal queries and prepared statements. The important functions are:
*<tt>SQL_GetRowCount()</tt> - Returns the number of rows.
*<tt>SQL_FetchRow()</tt> - Fetches the next row if one is available.
*<tt>SQL_Fetch[Int|String|Float]()</tt> - Fetches data from a field in the current row.

Let's consider a sample table that looks like this:
<pawn>CREATE TABLE users (
name VARCHAR(64) NOT NULL PRIMARY KEY,
age INT UNSIGNED NOT NULL
);</pawn>

The following example has code that will print out all users matching a certain age. There is an example for both prepared statements and normal queries.
<pawn>void PrintResults(Handle query)
{
/* Even if we have just one row, you must call SQL_FetchRow() first */
char name[MAX_NAME_LENGTH];
while (SQL_FetchRow(query))
{
SQL_FetchString(query, 0, name, sizeof(name));
PrintToServer("Name \"%s\" was found.", name);
}
}

bool GetByAge_Query(Database db, int age)
{
char query[100];
Format(query, sizeof(query), "SELECT name FROM users WHERE age = %d", age);

DBResultSet hQuery = SQL_Query(db, query);
if (hQuery == null)
{
return false;
}

PrintResults(hQuery);

delete hQuery;

return true;
}

DBStatement hAgeStmt = null;
bool GetByAge_Statement(Database db, int age)
{
if (hAgeSmt == null)
{
char error[255];
if ((hAgeStmt = SQL_PrepareQuery(db,
"SELECT name FROM users WHERE age = ?",
error,
sizeof(error)))
== null)
{
return false;
}
}

SQL_BindParamInt(hAgeStmt, 0, age);
if (!SQL_Execute(hAgeStmt))
{
return false;
}

PrintResults(hAgeStmt);

return true;
}</pawn>

Note that these examples did not close the statement Handles. These examples assume a global database instance that is only closed when the plugin is unloaded. For plugins which maintain temporary database connections, prepared statement Handles must be freed or else the database connection will never be closed.

=Threading=
SourceMod supports threaded SQL querying. That is, SQL operations can be completed in a separate thread from main gameplay. If your database server is remote or requires a network connection, queries can cause noticeable gameplay lag, and supporting threading is often a good idea if your queries occur in the middle of gameplay.

Threaded queries are ''asynchronous''. That is, they are dispatched and you can only find the results through a callback. Although the callback is guaranteed to fire eventually, it may not fire in any specific given timeframe. Certain drivers may not support threading; if this is the case, an RTE will be thrown. If the threader cannot start or the threader is currently disabled, SourceMod will transparently execute the query in the main thread as a fallback.

==Operations==
All threaded operations (except connecting) use the same callback for result notification: <tt>SQLQueryCallback</tt>. The parameters are:
*<tt>db</tt> - The cloned database handle. If the db handle was not found or was invalidated, <tt>null</tt> is passed.
*<tt>results</tt> - Result object, or null on failure.
*<tt>error</tt> - An error string.
*<tt>data</tt> - Custom data that can be passed via some SQL operations.

The following operations can be done via threads:
*Connection, via <tt>SQL_TConnect</tt>.
*Querying, via <tt>SQL_TQuery()</tt>.
*''Note: prepared statements are not yet available for the threader.''

It is always safe to chain one operation from another.

===Connecting===
It is not necessary to make a threaded connection in order to make threaded queries. However, creating a threaded connection will not pause the game server if a connection cannot be immediately established.
Connecting however uses a different callback: <tt>SQLConnectCallback</tt>.

The following parameters are used for the threaded connection callback:
*<tt>db</tt>: Handle to the database connection, or <tt>null</tt> if it could not be found.
*<tt>error</tt>: The error string, if any.
*<tt>data</tt>: Unused (0)

Example:
<pawn>Database hDatabase = null;

void StartSQL()
{
Database.Connect(GotDatabase);
}

public void GotDatabase(Database db, const char[] error, any data)
{
if (db == null)
{
LogError("Database failure: %s", error);
}
else
{
hDatabase = hndl;
}
}</pawn>

===Querying===
Threaded queries can be performed on any database Handle as long as the driver supports threading. All query results for the first result set are retrieved while in the thread. If your query returns more than one set of results (for example, <tt>CALL</tt> on MySQL with certain functions), the behaviour of the threader is undefined at this time. Note that if you want to perform both threaded and non-threaded queries on the same connection, you MUST read the "Locking" section below.

Query operations use the following callback parameters:
*<tt>owner</tt>: A Handle to the database used to query. The Handle is not the same as the Handle originally passed; however, it will test positively with <tt>SQL_IsSameConnection</tt>. The Handle can be cloned but it cannot be closed (it is closed automatically). It may be <tt>null</tt> in the case of a serious error (for example, the driver being unloaded).
*<tt>hndl</tt>: A Handle to the query. It can be cloned, but not closed (it is closed automatically). It may be <tt>null</tt> if there was an error.
*<tt>error</tt>: Error string, if any.
*<tt>data</tt>: Optional user-defined data passed in through <tt>SQL_TQuery()</tt>.

Example, continuing from above:
<pawn>void CheckSteamID(int userid, const char[] auth)
{
char query[255];
FormatEx(query, sizeof(query), "SELECT userid FROM users WHERE steamid = '%s'", auth);
hdatabase.Query(T_CheckSteamID, query, userid);
}

public void T_CheckSteamID(Database db, DBResultSet results, const char[] error, any data)
{
int client = 0;

/* Make sure the client didn't disconnect while the thread was running */
if ((client = GetClientOfUserId(data)) == 0)
{
return;
}

if (results == null)
{
LogError("Query failed! %s", error);
KickClient(client, "Authorization failed");
} else if (results.RowCount == 0) {
KickClient(client, "You are not a member");
}
}
</pawn>

==Locking==
It is possible to run both threaded and non-threaded queries on the same connection. However, without the proper precautions, you could corrupt the network stream (even if it's local), corrupt memory, or otherwise cause a crash in the SQL driver. To solve this, SourceMod has ''database locking''. Locking is done via <tt>SQL_LockDatabase()</tt> and <tt>SQL_UnlockDatabase</tt>.

Whenever performing any of the following non-threaded operations on a database, it is absolutely necessary to enclose the entire operation with a lock:
*<tt>SQL_Query()</tt> (and <tt>SQL_FetchMoreResults</tt> pairings)
*<tt>SQL_FastQuery</tt>
*<tt>SQL_PrepareQuery</tt>
*<tt>SQL_Bind*</tt> and <tt>SQL_Execute</tt> pairings

The rule of thumb is: if your operation is going to use the database connection, it must be locked until the operation is fully completed.

Example:
<pawn>bool GetByAge_Query(Database db, int age)
{
char query[100];
FormatEx(query, sizeof(query), "SELECT name FROM users WHERE age = %d", age);

SQL_LockDatabase(db);
DBResultSet hQuery = SQL_Query(db, query);
if (hQuery == null)
{
SQL_UnlockDatabase(db);
return false;
}
SQL_UnlockDatabase(db);

PrintResults(hQuery);

delete hQuery;

return true;
}</pawn>

Note that it was only necessary to lock the query; SourceMod pre-fetches the result set, and thus the network queue is clean.

===Warnings===
*Never call <tt>SQL_LockDatabase</tt> right before a threaded operation. You will deadlock the server and have to terminate/kill it.
*Always pair every Lock with an Unlock. Otherwise you risk a deadlock.
*If your query returns multiple result sets, for example, a procedure call on MySQL that returns results, you must lock both the query and the entire fetch operation. SourceMod is only able to fetch one result set at a time, and all result sets must be cleared before a new query is started.

==Priority==
Threaded SQL operations are placed in a simple priority queue. The priority levels are <tt>High</tt>, <tt>Medium</tt>, and <tt>Low</tt>. Connections always have the highest priority.

Changing the priority can be useful if you have many queries with different purposes. For example, a statistics plugin might execute 10 queries on death, and one query on join. Because the statistics might rely on the join info, the join query might need to be high priority, while the death queries can be low priority.

You should never simply assign a high priority to all of your queries simply because you want them to get done fast. Not only does it not work that way, but you may be inserting subtle problems into other plugins by being greedy.

=SQLite=
==Introduction==
[http://www.sqlite.org/ SQLite] is a fast local-file SQL database engine and SourceMod provides a DBI driver for it. SQLite differs from MySQL, and thus MySQL queries may not work in SQLite. The driver type for connections is <tt>sqlite</tt>.

==Usage==
Since SQLite is local only, most of the connection parameters can be ignored. The only connection parameter required is <tt>database</tt>, which specifies the file name of the database. Databases are created on demand if they do not already exist, and are stored in <tt>addons/sourcemod/data/sqlite</tt>. An extension of ".sq3" is automatically appended to the file name.

Additionally, you can specify sub-folders in the database name. For example, "cssdm/players" will become <tt>addons/sourcemod/data/sqlite/cssdm/players.sq3</tt>.

SQLite supports the threading layer, and requires all of the same rules as the MySQL driver (including locks on shared connections).

==External Links==
*[http://www.sqlite.org SQLite Homepage]
*[http://sqlitebrowser.sourceforge.net/ SQLite Browser]

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Optional Requirements (SourceMod Scripting)

2016-07-26T02:43:20Z

Shavit: Update example code to transitional syntax

Normally, if you use natives from an extension or another plugin, your plugin will not load unless those natives exist. However, it is possible to make your dependencies "optional." This article details how.

=Disabling Requirements=
==Extensions==
To disable an extension being marked as "required," remove the <tt>REQUIRE_EXTENSIONS</tt> define. For example:

<pawn>#include <sourcemod>
#undef REQUIRE_EXTENSIONS
#include <sdktools></pawn>

Note that any extensions included after the <tt>#undef</tt> will also be marked as not required. Thus, you may need to move the include down, or do something like:

<pawn>#include <sourcemod>
#undef REQUIRE_EXTENSIONS
#include <sdktools>
#define REQUIRE_EXTENSIONS</pawn>

==Plugins==
To disable an plugin being marked as "required," remove the <tt>REQUIRE_PLUGIN</tt> define. For example:

<pawn>#include <sourcemod>
#undef REQUIRE_PLUGIN
#include <ircrelay></pawn>

Note that any plugins included after the <tt>#undef</tt> will also be marked as not required. Thus, you may need to move the include down, or do something like:

<pawn>#include <sourcemod>
#undef REQUIRE_PLUGIN
#include <ircrelay>
#define REQUIRE_PLUGIN</pawn>

==Optional Natives==
To mark a native as optional, use <tt>MarkNativeAsOptional</tt>. It should be called in <tt>AskPluginLoad2</tt>. For example:

<pawn>public APLRes AskPluginLoad2(Handle myself, bool late, char[] error, int err_max)
{
MarkNativeAsOptional("SDKCall");
return APLRes_Success;
}</pawn>

=Checking Optional Dependencies=
If you use a plugin or extension as an optional dependency, you may need to check whether it exists. For example, let's say we're relying on a plugin with the library name of "ircrelay." The way to always know whether ircrelay is loaded (and working) is:

<pawn>bool ircrelay = false;

public void OnAllPluginsLoaded()
{
ircrelay = LibraryExists("ircrelay");
}

public void OnLibraryRemoved(const char[] name)
{
if (StrEqual(name, "ircrelay"))
{
ircrelay = false;
}
}

public void OnLibraryAdded(const char[] name)
{
if (StrEqual(name, "ircrelay"))
{
ircrelay = true;
}
}</pawn>

=Creating a Dependency=
Allowing other plugins to use your plugin as a library requires making an include file with two structures (the second of which is optional). The first structure must look like this:

<pawn>public SharedPlugin __pl_myfile =
{
name = "myfile",
file = "myfile.smx",
#if defined REQUIRE_PLUGIN
required = 1,
#else
required = 0,
#endif
};</pawn>

The basic format is:
*The variable name MUST start with <tt>__pl_</tt> and must end with a unique string.
*The "name" portion is treated as the library name and must be unique.
*The filename must match the filename of the plugin implementing the library.
*The requirement portion should remain unchanged in order to maintain standards.

Additionally, you should expose a function which marks all of your natives as optional. You can do this by:
<pawn>#if !defined REQUIRE_PLUGIN
public void __pl_myfile_SetNTVOptional()
{
MarkNativeAsOptional("native1");
MarkNativeAsOptional("native2");
MarkNativeAsOptional("native3");
}
#endif</pawn>

This function will be secretly called before the plugin loads (if and only if the requirement is optional), thus allowing seamless optional usage by third party developers. Note that the <tt>__pl_</tt> and <tt>_SetNTVOptional</tt> portions must be present, and that everything in between must match the ending of <tt>__pl_</tt> for the <tt>SharedPlugin</tt> structure.

You also must register the library name with SourceMod -- again this should be the unique string. This should be done inside the <code>AskPluginLoad2</code> function.

<pawn>
public APLRes AskPluginLoad2(Handle myself, bool late, char[] error, int err_max)
{
//... code here ...
RegPluginLibrary("myfile");

return APLRes_Success;
}
</pawn>

= Full Example =
;''Bounty: bounty.sp''
<pawn>
#include <sourcemod>
#undef REQUIRE_PLUGIN
#include <ircrelay>
</pawn>
;''Bounty: bounty.config.sp''
<pawn>
bool plugin_IrcRelay = LibraryExists("ircrelay");
if ((BountyIRC) && (plugin_IrcRelay))
{
RegisterIrcCommand("!bounty", "x", Irc_ViewBounty);
IrcMessage(CHAN_MASTER, "IRC Bounty Running!");
} else {
if ((BountyIRC) && (!plugin_IrcRelay))
{
BountyConsole_Debug("%t", "Bounty IRC Relay failed");
}
}
</pawn>
;''IRC Relay: ircrelay.sp''
<pawn>
public APLRes AskPluginLoad2(Handle myself, bool late, char[] error, int err_max)
{
//... code here ...
RegPluginLibrary("ircrelay");

return APLRes_Success;
}
</pawn>
;''IRC Relay: ircrelay.inc''
<pawn>
public SharedPlugin __pl_ircrelay =
{
name = "ircrelay",
file = "ircrelay.smx",
#if defined REQUIRE_PLUGIN
required = 1,
#else
required = 0,
#endif
};

#if !defined REQUIRE_PLUGIN
public void __pl_ircrelay_SetNTVOptional()
{
MarkNativeAsOptional("IrcMessage");
MarkNativeAsOptional("RegisterIrcCommand");
MarkNativeAsOptional("IrcGetCmdArgc");
MarkNativeAsOptional("IrcGetCmdArgv");
}
#endif
</pawn>
The <code>name</code> value is what will be checked when you run <code>LibraryExists</code>. This allows the bounty script to fully work, even if the IRC relay plugin is not installed and/or running correctly on your server.

[[Category:SourceMod Scripting]]

Adding Admins (SourceMod)

2016-07-09T19:32:45Z

Shavit: fix annoying typo

__FORCETOC__
SourceMod has as very detailed and flexible administration system, and it can be quite daunting to users. To simplify things, there are a number of "flags" which specify generic permissions administrators can have.

There are currently two provided ways of storing admins. One is via the admin-flatfile.smx plugin that is enabled by default. This plugin provides two files: a simplified flat file, and another more complex tree-based file. The other way to store admins is using [[SQL Admins (SourceMod)|SQL]].

SourceMod provides three methods of authentication:
*''Steam ID'' (unique to a Steam account)
*''IP Address'' (semi-unique to a given computer, better for LANs)
*''Name'' (requires a password)

=Quick Start=
On the server, open <code>/addons/sourcemod/configs/admins_simple.ini</code>

In a new line, add the following, replacing yoursteamid (use your client's console '''status''' command to retrieve your Steam ID - formatted as STEAM_n:o:p)

'''"yoursteamid" "99:z"'''

Save the file, then type <code>sm_reloadadmins</code> in the server console. Connect to the server with the game client. Enter sm_admin in the client console, and then return to the game. You should see the admin menu.

=Levels=
First, let's quickly run down the provided levels:
:{| cellpadding="5"
|- class="t2th"
| Name
| Flag
| Purpose
|- class="t2td"
| reservation
| a
| Reserved slot access.
|- class="t2td"
| generic
| b
| Generic admin; required for admins.
|- class="t2td"
| kick
| c
| Kick other players.
|- class="t2td"
| ban
| d
| Ban other players.
|- class="t2td"
| unban
| e
| Remove bans.
|- class="t2td"
| slay
| f
| Slay/harm other players.
|- class="t2td"
| changemap
| g
| Change the map or major gameplay features.
|- class="t2td"
| cvar
| h
| Change most cvars.
|- class="t2td"
| config
| i
| Execute config files.
|- class="t2td"
| chat
| j
| Special chat privileges.
|- class="t2td"
| vote
| k
| Start or create votes.
|- class="t2td"
| password
| l
| Set a password on the server.
|- class="t2td"
| rcon
| m
| Use RCON commands.
|- class="t2td"
| cheats
| n
| Change sv_cheats or use cheating commands.
|- class="t2td"
| root
| z
| Magically enables all flags and ignores immunity values.

|- class="t2td"
| custom1
| o
| Custom Group 1.
|- class="t2td"
| custom2
| p
| Custom Group 2.
|- class="t2td"
| custom3
| q
| Custom Group 3.
|- class="t2td"
| custom4
| r
| Custom Group 4.
|- class="t2td"
| custom5
| s
| Custom Group 5.
|- class="t2td"
| custom6
| t
| Custom Group 6.
|}

=Immunity=
In SourceMod, immunity is a flexible system based on ''immunity levels''. Every admin can have an arbitrary immunity value assigned to them. Whether an admin can target another admin depends on who has a higher immunity value.

For example, say Admin #1 has an immunity level of "3" and Admin #2 has an immunity level of "10." Admin #2 can target Admin #1, but Admin #1 cannot target Admin #2. The numbers are completely arbitrary, and they can be any number equal to or higher than 0. Note that 0 always implies no immunity.

By default, admins with the same immunity value can target each other. This can be changed via <tt>sm_immunity_mode</tt> in <tt>cfg/sourcemod.cfg</tt>.

'''Admins with the z flag are not subject to immunity checks.''' This means they can always target anyone.

=Passwords=
Using the passwords method is '''optional'''.

For passwords to work, the server administrator must change the <code>PassInfoVar</code> line in <tt>addons/sourcemod/configs/core.cfg</tt>. For example:
<pre>"PassInfoVar" "_sm1337"</pre>

Next, if an admin has a password, the person must set the password via the ''setinfo'' command in the client console. For example, using the examples above, the player <tt>BAILOPAN</tt> would need to type:
<pre>setinfo "_sm1337" "Gab3n"</pre>

To automate this upon connecting to a server, you can create an "autoexec.cfg" file in your client game folder. This will be located under <tt>SteamApps\common\[game]\[gameabbr]\cfg</tt>. For example:
*<tt>C:\Program Files\Steam\steamapps\common\Counter-Strike Source\cstrike\cfg</tt>

You can also set the password upon connecting. For Steam and IP authentication, your admin privileges will be automatically assigned if the password is correct. For name based authentication, your password must be correct before you change your name, or else you will be kicked from the server.

=Simple Admins=
The easiest way to add administrators is through <tt>configs/admins_simple.ini</tt>. This is a flat file which requires two parameters per line: authentication info, and flags.

The string's syntax:

< > - Required

[ ] - Optional

/ - Or
<pre>
"<Steam ID/!IP/Steam name>" "[immunity level:]<flag/@group>" ["password"]
</pre>

Examples:
<pre>
"STEAM_0:1:16" "bce" //generic, kick, unban for this steam ID. no immunity
"!127.0.0.1" "5:z" //all permissions for this IP, immunity level = 5
"BAILOPAN" "abc" "Gab3n" //name BAILOPAN, password "Gab3n": gets reservation, generic, kick
"Gaben" "@Admins" //name Gaben, group Admins
</pre>

=Detailed Admins=
Alternatively, you can add admins via <tt>configs/admins.cfg</tt>, a more advanced file stored in a KeyValues format. Each admin is its own block inside a main "Admin" block. You can create and / or modify <tt>admins.cfg</tt> files with [http://forums.alliedmods.net/showthread.php?t=81160 KVManager]. The format is as follows:

<pre>Admins
{
"Admin Name"
{
"auth" "[steam|name|ip]"
"identity" "[unique id]"
"[option1]" "[value1]"
"[option2]" "[value2]"
/* .... */
}
}</pre>

Available options:

* - Required
*<tt>auth</tt> *: Must be one of <tt>steam</tt>, <tt>name</tt>, or <tt>ip</tt> (unless there is a custom auth method), and instructs SourceMod how to interpret the <tt>identity</tt> value.
*<tt>identity</tt> *: Unique value that allows SourceMod to find this admin given an authentication method and the given value.
*<tt>password</tt>: Specifies the password the user must enter (see [[#Passwords|passwords]]).
*<tt>group</tt>: Specifies a group name the user should inherit if available. More than one "group" line can be specified. There should be no '@' symbol as there is no ambiguity.
*<tt>flags</tt>: Default access flags the user should receive.
*<tt>immunity</tt>: Default immunity level the user should receive.

The admin name is optional (it can be blank). It is not used internally and is intended for convenience usage by 3rd party tools.

Example:
<pre>Admins
{
"BAILOPAN"
{
"auth" "steam"
"identity" "STEAM_0:1:2345"
"flags" "abcdef"
"immunity" "5"
"group" "Awesome Admins"
}

"Blue Crab"
{
"auth" "steam"
"identity" "STEAM_0:1:666666"
"flags" "z"
"immunity" "99"
}
}</pre>

=See Also=
*[[Adding Groups (SourceMod)]]
*[[Overriding Command Access (SourceMod)]]

[[Category:SourceMod Documentation]]

{{LanguageSwitch}}

Menu API (SourceMod)

2016-06-24T11:12:34Z

Shavit: Fix error that could cause an error in compilation

SourceMod has an extensive API for building and displaying menus to clients. Unlike AMX Mod X, this API is highly state driven. Menus are based on callbacks which are guaranteed to be fired.

For C++, the Menu API can be found in <tt>public/IMenuManager.h</tt>. For SourcePawn, it is in <tt>scripting/include/menus.inc</tt>.

=Objects=
The SourceMod Menu System is based on an object oriented hierarchy. Understanding this hierarchy, even for scripting, is critical to using menus effectively.

==Styles==
The top level object is a ''MenuStyle'' (<tt>IMenuStyle</tt> in C++). Styles describe a unique menu system. There are two such styles built into SourceMod:
*Valve Style, also called "ESC" menus; 8 items per page, no raw/disabled text can be rendered
*Radio Style, also called "AMX" menus; 10 items per page, raw/disabled text can be rendered

Each MenuStyle has its own rules and properties. You can think of them as existing on separate "channels." For example, two different menus can exist on a player's screen as both a Valve menu and a Radio menu at the same time, and SourceMod will be able to manage both without any problems. This is because each style keeps track of its own menus separately.

==Panels==
Menu displays are drawn with a lower level interface called ''Panels'' (<tt>IMenuPanel</tt> in C++). Panels describe exactly one chunk of display text. Both selectable items and raw text can be added to a panel as long as its parent style supports the contents you're trying to draw. For example, the Valve style does not support drawing raw text or disabled items. But with a Radio-style Panel, you can display a large amount of on-screen data in your own format.

Panels are considered temporary objects. They are created, rendered, displayed, and destroyed. Although they can be saved indefinitely, it is not necessary to do so.

Valve Style drawing rules/limitations:
*Max items per page is 8.
*Disabled items cannot be drawn.
*Raw text cannot be drawn.
*Spacers do not add a space/newline, giving a "cramped" feel.
*Users must press "ESC" or be at their console to view the menu.

Radio Style drawing rules/limitations:
*Max items per page is 10.
*Titles appear white; items appear yellow, unless disabled, in which case they are white.
*The 0th item is always white. For consistency, this means navigational controls explained in the next section are always white, and simply not drawn if disabled.

==Menus==
Lastly, there are plain ''Menus'' (<tt>IBaseMenu</tt> in C++). These are helper objects designed for storing a menu based on selectable items. Unlike low-level panels, menus are containers for '''items''', and can only contain items which are selectable (i.e., do not contain raw text). They fall into two categories:
*Non-paginated: The menu can only have a certain number of items on it, and no control/navigation options will be added, except for an "Exit" button which will always be in the last position supported by the style.
**Valve Style maximum items: 8
**Radio Style maximum items: 10
*Paginated: The menu can have any number of items. When displayed, only a certain number of items will be drawn at a time. Automatic navigation controls are added so players can easily move back and forth to different "pages" of items in the menu.
**"Previous" is always drawn as the first navigation item, third from the last supported position. This will not be drawn if the menu only contains one page. If there are no previous pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 6
***Radio Style position: 8
**"Next" is always drawn as the second navigation item, second from the last supported position. This will not be drawn if the menu only contains one page. If there are no further pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 7
***Radio Style position: 9
**"Exit" is drawn if the menu has the exit button property set. It is always the last supported item position.
***Valve Style position: 8
***Radio Style position: 10

The purpose of Menus is to simplify the procedure of storing, drawing, and calculating the selection of items. Thus, menus do not allow for adding raw text, as that would considerably complicate the drawing algorithm. ''Note: The C++ API supports hooking <tt>IBaseMenu</tt> drawing procedures and adding raw text; this will be added to the scripting API soon.''

Internally, Menus are drawn via a ''RenderMenu'' algorithm. This algorithm creates a temporary panel and fills it with items from menus. This panel is then displayed to a client. The algorithm attempts to create a consistent feel across all menus, and across all styles. Thus any menu displayed via the <tt>IBaseMenu</tt> class, or <tt>Menu</tt> Handles, will look and act the same, and the Menu API is based off the Panel API.

=Callbacks=
==Overview==
Menus are a callback based system. Each callback represents an action that occurs during a ''menu display cycle''. A cycle consists of a number of notifications:
*Start notification.
**Display notification if the menu can be displayed to the client.
**Either an item select or menu cancel notification.
*End notification.

Since ''End'' signifies the end of a full display cycle, it is usually used to destroy temporary menus.

==Specification==
A detailed explanation of these events is below. For C++, an <tt>IBaseMenu</tt> pointer is always available. For SourcePawn, a <tt>Menu</tt> Handle and a <tt>MenuAction</tt> are always set in the <tt>MenuHandler</tt> callback. Unlike C++, the SourcePawn API allows certain actions to only be called if they are requested at menu creation time. This is an optimization. However, certain actions cannot be prevented from being called.

*'''Start'''. The menu has been acknowledged. This does not mean it will be displayed; however, it guarantees that "OnMenuEnd" will be called.
**<tt>OnMenuStart()</tt> in C++.
**<tt>MenuAction_Start</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: Ignored (always 0).
***<tt>param2</tt>: Ignored (always 0).
*'''Display'''. The menu is being displayed to a client.
**<tt>OnMenuDisplay()</tt> in C++. An <tt>IMenuPanel</tt> pointer and client index are available.
**<tt>MenuAction_Display</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A Handle to a menu panel.
*'''Select'''. An item on the menu has been selected. The item position given will be the position in the menu, rather than the key pressed (unless the menu is a raw panel).
**<tt>OnMenuSelect()</tt> in C++. A client index and item position are passed.
**<tt>MenuAction_Select</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: An item position.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.
*'''End'''. The menu's display cycle has finished; this means that the "Start" action has occurred, and either "Select" or "Cancel" has occurred thereafter. This is typically where menu resources are removed/deleted.
**<tt>OnMenuEnd()</tt> in C++.
**<tt>MenuAction_End</tt> in SourcePawn. This action is always triggered, whether requested or not.
***<tt>param1</tt>: A menu end reason code.
***<tt>param2</tt>: If param1 was MenuEnd_Cancelled, this contains a menu cancellation reason code.

==Panels==
For panels, the callback rules change. Panels only receive two of the above callbacks, and it is guaranteed that only one of them will be called for a given display cycle. For C++, the <tt>IBaseMenu</tt> pointer will always be <tt>NULL</tt>. For SourcePawn, the menu Handle will always be <tt>INVALID_HANDLE</tt>.

*'''Select'''. A key has been pressed. This can be any number and should not be considered as reliably in bounds. For example, even if you only had 2 items in your panel, a client could trigger a key press of "43."
**<tt>OnMenuSelect()</tt> in C++. A client index and key number pressed are passed.
**<tt>MenuAction_Select</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: Number of the key pressed.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.

=Examples=
First, let's start off with a very basic menu. We want the menu to look like this:

<pre>Do you like apples?
1. Yes
2. No</pre>

We'll draw this menu with both a basic Menu and a Panel to show the API differences.

==Basic Menu==
First, let's write our example using the Menu building API. For a more in-depth guide, see [[Menus Step By Step (SourceMod Scripting)]].

<pawn>public void OnPluginStart()
{
RegConsoleCmd("menu_test1", Menu_Test1);
}

public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)
{
/* If an option was selected, tell the client about the item. */
if (action == MenuAction_Select)
{
char info[32];
bool found = menu.GetItem(param2, info, sizeof(info));
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info);
}
/* If the menu was cancelled, print a message to the server about it. */
else if (action == MenuAction_Cancel)
{
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2);
}
/* If the menu has ended, destroy it */
else if (action == MenuAction_End)
{
delete menu;
}
}

public Action Menu_Test1(int client, int args)
{
Menu menu = new Menu(MenuHandler1);
menu.SetTitle("Do you like apples?");
menu.AddItem("yes", "Yes");
menu.AddItem("no", "No");
menu.ExitButton = false;
menu.Display(client, 20);

return Plugin_Handled;
}</pawn>

Note a few very important points from this example:
*One of either <tt>Select</tt> or <tt>Cancel</tt> will always be sent to the action handler.
*<tt>End</tt> will always be sent to the action handler.
*We destroy our Menu in the <tt>End</tt> action, because our Handle is no longer needed. If we had destroyed the Menu after <tt>DisplayMenu</tt>, it would have canceled the menu's display to the client.
*Menus, by default, have an exit button. We disabled this in our example.
*Our menu is set to display for 20 seconds. That means that if the client does not select an item within 20 seconds, the menu will be canceled. This is usually desired for menus that are for voting. Note that unlike AMX Mod X, you do not need to set a timer to make sure the menu will be ended.
*Although we created and destroyed a new Menu Handle, we didn't need to. It is perfectly acceptable to create the Handle once for the lifetime of the plugin.

Our finished menu and attached console output looks like this (I selected "Yes"):

[[Image:Basic_menu_1.PNG]]

==Basic Panel==
Now, let's rewrite our example to use Panels instead.

<pawn>public void OnPluginStart()
{
RegConsoleCmd("panel_test1", Panel_Test1);
}

public int PanelHandler1(Menu menu, MenuAction action, int param1, int param2)
{
if (action == MenuAction_Select)
{
PrintToConsole(param1, "You selected item: %d", param2);
} else if (action == MenuAction_Cancel) {
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2);
}
}

public Action Panel_Test1(int client, intargs)
{
Panel panel = new Panel();
panel.SetTitle("Do you like apples?");
panel.DrawItem("Yes");
panel.DrawItem("No");

panel.Send(client, PanelHandler1, 20);

delete panel;

return Plugin_Handled;
}</pawn>

As you can see, Panels are significantly different.
*We can destroy the Panel as soon as we're done displaying it. We can create the Panel once and keep re-using it, but we can destroy it at any time without interrupting client menus.
*The Handler function gets much less data. Since panels are designed as a raw display, no "item" information is saved internally. Thus, the handler function only knows whether the display was canceled or whether (and what) numerical key was pressed.
*There is no automation. You cannot add more than a certain amount of selectable items to a Panel and get pagination. Automated control functionality requires using the heftier Menu object API.

Our finished display and console output looks like this (I selected "Yes"):

[[Image:Basic_panel_1.PNG]]

==Basic Paginated Menu==
Now, let's take a more advanced example -- pagination. Let's say we want to build a menu for changing the map. An easy way to do this is to read the <tt>maplist.txt</tt> file at the start of a plugin and build a menu out of it.

Since reading and parsing a file is an expensive operation, we only want to do this once per map. Thus we'll build the menu in <tt>OnMapStart</tt>, and we won't call <tt>CloseHandle</tt> until <tt>OnMapEnd</tt>.

Source code:
<pawn>Menu g_MapMenu = null;

public void OnPluginStart()
{
RegConsoleCmd("menu_changemap", Command_ChangeMap);
}

public void OnMapStart()
{
g_MapMenu = BuildMapMenu();
}

public void OnMapEnd()
{
if (g_MapMenu != INVALID_HANDLE)
{
delete(g_MapMenu);
g_MapMenu = null;
}
}

Menu BuildMapMenu()
{
/* Open the file */
File file = OpenFile("maplist.txt", "rt");
if (file == null)
{
return null;
}

/* Create the menu Handle */
Menu menu = new Menu(Menu_ChangeMap);
char mapname[255];
while (!file.EndOfFile() && file.ReadLine(mapname, sizeof(mapname)))
{
if (mapname[0] == ';' || !IsCharAlpha(mapname[0]))
{
continue;
}
/* Cut off the name at any whitespace */
int len = strlen(mapname);
for (int i=0; i<len; i++)
{
if (IsCharSpace(mapname[i]))
{
mapname[i] = '\0';
break;
}
}
/* Check if the map is valid */
if (!IsMapValid(mapname))
{
continue;
}
/* Add it to the menu */
menu.AddItem(mapname, mapname);
}
/* Make sure we close the file! */
file.Close();

/* Finally, set the title */
menu.SetTitle("Please select a map:");

return menu;
}

public int Menu_ChangeMap(Menu menu, MenuAction action, int param1, int param2)
{
if (action == MenuAction_Select)
{
char info[32];

/* Get item info */
bool found = menu.GetItem(param2, info, sizeof(info));

/* Tell the client */
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info);

/* Change the map */
ServerCommand("changelevel %s", info);
}
}

public Action Command_ChangeMap(int client, int args)
{
if (g_MapMenu == null)
{
PrintToConsole(client, "The maplist.txt file was not found!");
return Plugin_Handled;
}

g_MapMenu.Display(client, MENU_TIME_FOREVER);

return Plugin_Handled;
}</pawn>

This menu results in many selections (my <tt>maplist.txt</tt> file had around 18 maps). So, our final menu has 3 pages, which side by side, look like:

[[Image:Basic_menu_2_page1.PNG]]
[[Image:Basic_menu_2_page2.PNG]]
[[Image:Basic_menu_2_page3.PNG]]

Finally, the console output printed this before the map changed to my selection, <tt>cs_office</tt>:
<pre>You selected item: 8 (found? 1 info: cs_office)</pre>

Displaying and designing this Menu with a raw <tt>ShowMenu</tt> message or <tt>Panel</tt> API would be very time consuming and difficult. We would have to keep track of all the items in an array of hardcoded size, pages which the user is viewing, and write a function which calculated item selection based on current page and key press. The Menu system, thankfully, handles all of this for you.

'''Notes:'''
*Control options which are not available are not drawn. For example, in the first page, you cannot go "back," and in the last page, you cannot go "next." Despite this, the menu API tries to keep each the interface as consistent as possible. Thus, visually, each navigational control is always in the same position.
*Although we specified no time out for our menu, if we had placed a timeout, flipping through pages does not affect the overall time. For example, if we had a timeout of 20, each successive page flip would continue to detract from the overall display time, rather than restart the allowed hold time back to 20.
*If we had disabled the Exit button, options 8 and 9 would still be "Back" and "Next," respectively.
*Again, we did not free the Menu Handle in <tt>MenuAction_End</tt>. This is because our menu is global/static, and we don't want to rebuild it every time.
*These images show "Back." In SourceMod revisions 1011 and higher, "Back" is changed to "Previous," and "Back" is reserved for the special "ExitBack" functionality.

=Voting=
SourceMod also has API for displaying menus as votable choices to more than one client. SourceMod automatically handles selecting an item and randomly picking a tie-breaker. The voting API adds two new <tt>MenuAction</tt> values, which for vote displays, are '''always''' passed:

*<tt>MenuAction_VoteStart</tt>: Fired after <tt>MenuAction_Start</tt> when the voting has officially started.
*<tt>MenuAction_VoteEnd</tt>: Fired when all clients have either voted or cancelled their vote menu. The chosen item is passed through <tt>param1</tt>. This is fired '''before''' <tt>MenuAction_End</tt>. It is important to note that it does not supercede <tt>MenuAction_End</tt>, nor is it the same thing. Menus should never be destroyed in <tt>MenuAction_VoteEnd</tt>. '''Note:''' This is not called if <tt>SetVoteResultCallback</tt>() is used.
*<tt>MenuAction_VoteCancel</tt>: Fired if the menu is cancelled while the vote is in progress. If this is called, <tt>MenuAction_VoteEnd</tt> or the result callback will not be called, but <tt>MenuAction_End</tt> will be afterwards. A vote cancellation reason is passed in <tt>param1</tt>.

The voting system extends overall menus with two additional properties:
*Only one vote can be active at a time. You must call <tt>IsVoteInProgress</tt>() or else <tt>VoteMenu</tt>() will fail.
*If a client votes and then disconnects while the vote is still active, the client's vote will be invalidated.

The example below shows has to create a function called <tt>DoVoteMenu()</tt> which will ask all clients whether or not they would like to change to the given map.

==Simple Vote==
<pawn>public int Handle_VoteMenu(Menu menu, MenuAction action, int param1,int param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
delete menu;
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
char map[64];
menu.GetItem(param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
}
}

void DoVoteMenu(const char[] map)
{
if (IsVoteInProgress())
{
return;
}

Menu menu = new Menu(Handle_VoteMenu);
menu.SetTitle("Change map to: %s?", map);
menu.AddItem(map, "Yes");
menu.AddItem("no", "No");
menu.ExitButton = false;
menu.DisplayVoteToAll(20);
}</pawn>

==Advanced Voting==
If you need more information about voting results than <tt>MenuAction_VoteEnd</tt> gives you, you can choose to have a different callback invoked. The new callback will provide much more information, but at a price: <tt>MenuAction_VoteEnd</tt> will not be called, and you will have to decide how to interpret the results. This is done via <tt>SetVoteResultCallback</tt>().

Example:
<pawn>public int Handle_VoteMenu(Menu menu, MenuAction action, int param1, int param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
delete menu;
}
}

public void Handle_VoteResults(Menu menu,
int num_votes,
int num_clients,
const int[][] client_info,
int num_items,
const int[][] item_info)
{
/* See if there were multiple winners */
int winner = 0;
if (num_items > 1
&& (item_info[0][VOTEINFO_ITEM_VOTES] == item_info[1][VOTEINFO_ITEM_VOTES]))
{
winner = GetRandomInt(0, 1);
}

char map[64];
menu.GetItem(item_info[winner][VOTEINFO_ITEM_INDEX], map, sizeof(map));
ServerCommand("changelevel %s", map);
}

void DoVoteMenu(const char[] map)
{
if (IsVoteInProgress())
{
return;
}

Menu menu = new Menu(Handle_VoteMenu);
menu.VoteResultCallback = Handle_VoteResults;
menu.SetTitle("Change map to: %s?", map);
menu.AddItem(map, "Yes");
menu.AddItem("no", "No");
menu.ExitButton = false;
menu.DisplayVoteToAll(20);
}</pawn>

=ExitBack=
ExitBack is a special term to refer to the "ExitBack Button." This button is disabled by default. Normally, paginated menus have no "Previous" item for the first page. If the "ExitBack" button is enabled, the "Previous" item will show up as "Back."

Selecting the "ExitBack" option will exit the menu with <tt>MenuCancel_ExitBack</tt> and <tt>MenuEnd_ExitBack</tt>. The functionality of this is the same as a normal menu exit internally; extra functionality must be defined through the callbacks.

=Closing Menu Handles=
It is only necessary to close a menu handle on <tt>MenuAction_End</tt>. The <tt>MenuAction_End</tt> is done every time a menu is closed and no longer needed.

=Translations=
It is possible to dynamically translate menus to each player through the <tt>MenuAction_DisplayItem</tt> callback. A special native, <tt>RedrawMenuItem</tt>, is used to transform the text while inside the callback. Let's redo the vote example from earlier to be translated:

<pawn>public int Handle_VoteMenu(Menu menu, MenuAction action, int param1, int param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
delete menu;
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
char map[64];
menu.GetItem(param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
} else if (action == MenuAction_DisplayItem) {
/* Get the display string, we'll use it as a translation phrase */
char display[64];
menu.GetItem(param2, "", 0, _, display, sizeof(display));

/* Translate the string to the client's language */
char buffer[255];
Format(buffer, sizeof(buffer), "%T", display, param1);

/* Override the text */
return RedrawMenuItem(buffer);
} else if (action == MenuAction_Display) {
/* Panel Handle is the second parameter */
Panel panel = view_as<Panel>(param2);

/* Get the map name we're changing to from the first item */
char map[64];
menu.GetItem(0, map, sizeof(map));

/* Translate to our phrase */
char buffer[255];
Format(buffer, sizeof(buffer), "%T", "Change map to?", client, map);

panel.SetTitle(buffer);
}
}

void DoVoteMenu(const char[] map)
{
if (IsVoteInProgress())
{
return;
}

Menu menu = new Menu(Handle_VoteMenu,MenuAction_DisplayItem|MenuAction_Display);
menu.SetTitle("Change map to: %s?", map);
menu.AddItem(map, "Yes");
menu.AddItem("no", "No");
menu.ExitButton = false;
menu.DisplayVoteToAll(20);
}</pawn>

[[Category:SourceMod Development]]
[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

AutoConfigs (SourceMod Scripting)

2016-06-06T11:09:22Z

Shavit: Explain about FCVAR_DONTRECORD

__FORCETOC__
{{Languages|AutoConfigs_(SourceMod_Scripting)}}
SourceMod provides a system for simple plugins to automatically generate config files which get executed on load. This is done via the <tt>AutoExecConfig</tt> native in <tt>scripting/include/sourcemod.inc</tt>.

Once all configuration files are executed, <tt>OnConfigsExecuted</tt> is called. This forward will always be called, even if your plugin had no configs or if it was loaded late.

=Usage=
There are three parameters to this call:
*''autoCreate'' - If true, SourceMod will dump all ConVars created by the plugin into a config file if the specified config file does not exist.
*''name'' - Name of the config file (excluding the .cfg extension). If empty, the plugin's name will be used instead, with <tt>plugin.</tt> prepended. For example, <tt>hat.smx</tt> becomes <tt>plugin.hat.cfg</tt>.
*''folder'' - Optionally change the folder under the main <tt>cfg</tt> folder. By default this is <tt>sourcemod</tt>, and configs go in <tt>cfg/sourcemod/</tt>. If empty, the config will be in <tt>cfg/</tt>.

''Note'': It is possible to write nested folders; SourceMod will attempt to create each one.

''Note'': If you have multiple <tt>AutoExecConfig</tt> calls marked with '''autoCreate''' being true, the first file to be auto created will prevent any others from being created. Thus, there is no way to automatically split cvars between multiple files.

''Note'': If a cvar has the flag <tt>FCVAR_DONTRECORD</tt>, it will not show up in the autoconfig. A good example of a use for this flag in a cvar, would be for the '''version''' cvar plugins need for the sake of tracking.

=Example Dump=
The autoCreate feature exports a config file that looks like this:

<pre>
// This file was auto-generated by SourceMod (v1.0.0.986)
// ConVars for plugin "hat.smx"

// MySQL database
// -
// Default: ""
mysqlk_database ""

// MySQL host, use this to configure various
// things for your server.
// -
// Default: "localhost"
mysqlk_host "localhost"
</pre>

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourceMod Plugins

2015-07-06T07:53:51Z

Shavit: Updated to the new 1.7 syntax

This guide will give you a basic introduction to writing a [[SourceMod]] plugin. If you are not familiar with the SourcePawn language, it is recommended that you at least briefly read the [[Introduction to SourcePawn]] article.

For information on compiling plugins, see [[Compiling SourceMod Plugins]]. You can use [http://www.crimsoneditor.com/ Crimson Editor], [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++], [http://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ Pawn Studio] or any other text editor you're comfortable with to write plugins.

=Starting from scratch=
Open your favorite text editor and create a new empty file. When you have an empty file you can just start writing code using the core language, however, you will not be able to use any of SourceMod features because the compiler does not now about them. This is done deliberately so it is possible to use SourcePawn outside of SourceMod. But since we are writing a SourceMod plugin, it is a good idea to enable access to SourceMod features first. This it done using <tt>#include</tt> directive. It tells compiler to "paste" the code from another file into yours.
<pawn>#include <sourcemod></pawn>
How does this work? First of all, note that we enclosed file name into angle brackets. Angle brackets tell the compiler to look in the default include directory. By default, it is '''scripting/include'''. You can open it right now and see a lot of inc files there. Those are SourceMod include files that describe various functions, tags and other features available for SourceMod plugins. The files are plain-text and you are encouraged to read them. You will notice however, that there's not much code in there, certainly not enough to implement all the great features of SourceMod, so where are they? They are implemented inside a SourceMod core which is written in C++ and is compiled into binary files which end up in '''bin''' directory. So how does your SourcePawn code and SM core link together if compiler doesn't know about existence of the latter? SourceMod include files are written specially, so they say that the implementation of functions is ''somewhere else''. Compiler understands that and generate a special code that says that this function call is going outside. When SourceMod loads your plugin, it inspects these bits of code and substitutes it's own internal functions instead. This is called [http://en.wikipedia.org/wiki/Dynamic_linking dynamic linking].

=Setting up plugin info=
Now that we got access to SourceMod features, it is time to setup the information that will be displayed via <tt>sm plugins list</tt> command. No one likes unnamed plugins. To do that we are going to look inside '''sourcemod.inc''' file and see the format that information should be declared. It's always helpful to look inside SM include files to find out information you don't know. There is also an [http://docs.sourcemod.net/api/ API documentation] but it can be outdated and it only has SM core files so if your plugin are going to use any third party extension or another plugin, you will have to study inc files. So, open '''sourcemod.inc''' and scroll down a bit until you see this:
<pawn>/**
* Plugin public information.
*/
struct Plugin
{
public const char[] name; /**< Plugin Name */
public const char[] description; /**< Plugin Description */
public const char[] author; /**< Plugin Author */
public const char[] version; /**< Plugin Version */
public const char[] url; /**< Plugin URL */
};</pawn>
and this:
<pawn>/**
* Declare this as a struct in your plugin to expose its information.
* Example:
*
* public Plugin myinfo =
* {
* name = "My Plugin",
* //etc
* };
*/
public Plugin myinfo;</pawn>

It tells us that we need to create a global public variable <tt>myinfo</tt> which must be of type <tt>Plugin</tt> which is a struct with 5 fields which themselves are strings. It may sound complicated for a beginner but it's easy. Let's go ahead and create one:
<pawn>public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};</pawn>

The <tt>public</tt> keyword means that SourceMod will be able to directly access our variable. <tt>Plugin:</tt> defines a type of our variable. <tt>myinfo</tt> is, obviously, a name of our variable as required by SourceMod. You see that we initialize it right away. This is preferred way to do when filling out plugin info.

After that the full code of your plugin should look like this:
<pawn>#include <sourcemod>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};</pawn>

=Getting code to run=
We already include SourceMod features and filled up or plugin info. We now have a perfectly well formed plugin which can be compiled and loaded by SourceMod. However, there is one problem - it does nothing. You might be tempted to just start writing a code after <tt>myinfo</tt> declaration just to see that it will not compile. SourcePawn, unlike other scripting languages like Lua, does not allow a code to be outside of functions. After reading that, you may probably want to just define some function, name it <tt>main</tt> probably, compile and load a plugin and see that your code never gets called. So how do we make SourceMod call our code? For this exact reason we have forwards. Forwards are function prototypes declared by one party that can be implemented by another party as a [http://en.wikipedia.org/wiki/Callback_%28computer_programming%29 callback]. When a first party starts a forward call, all parties that have matching callbacks receive the call. SourceMod declares a plenty of interesting forwards that we can implement. As you can see, forwards are the only way to get our code executed, keep that in mind. So let's implement <tt>OnPluginStart</tt> forward. As you may have guessed, it is called when our plugin starts. To do that, we'll have to look up the declaration of <tt>OnPluginStart</tt>. It is declared inside '''sourcemod.inc''', a file we are already familiar with, let's find it:
<pawn>/**
* Called when the plugin is fully initialized and all known external references
* are resolved. This is only called once in the lifetime of the plugin, and is
* paired with OnPluginEnd().
*
* If any run-time error is thrown during this callback, the plugin will be marked
* as failed.
*
* It is not necessary to close any handles or remove hooks in this function.
* SourceMod guarantees that plugin shutdown automatically and correctly releases
* all resources.
*
* @noreturn
*/
forward void OnPluginStart();</pawn>
Empty parentheses tells us that no arguments are passed inside this forward, <tt>@noreturn</tt> inside documentation tells us that we don't have to return anything, pretty simple forward. So how to write a correct callback for it? Firstly, our callback must have the same name, so it's <tt>OnPluginStart</tt>, secondly, our callback should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our callback so it needs to be <tt>public</tt>. So the implementation looks like this:
<pawn>public void OnPluginStart()
{
}</pawn>

Now we can write code inside curly braces and it will be executed when our plugin starts. Let's output <tt>"Hello world!"</tt> to server console. To do that we are going to use <tt>PrintToServer</tt> function. It is declared inside '''console.inc''', however, we don't need to manually include '''console.inc''' because it is included automatically as part of '''sourcemod.inc'''.
<pawn>/**
* Sends a message to the server console.
*
* @param format Formatting rules.
* @param ... Variable number of format parameters.
* @noreturn
*/
native int PrintToServer(const char[] format, any ...);</pawn>
As you can see, this is a native function. It is implemented inside SM core. Judging by it's arguments, we can see that it is a [[Format_Class_Functions_%28SourceMod_Scripting%29|format class function]]. However, we don't need any formatting right now, so let's just pass <tt>"Hello world!"</tt> string as an only argument:
<pawn>public void OnPluginStart()
{
PrintToServer("Hello world!");
}</pawn>
That's it! The full code of your plugin should look like this:
<pawn>#include <sourcemod>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};

public void OnPluginStart()
{
PrintToServer("Hello world!");
}</pawn>
Compile and load your plugin on your server and see for yourself that the message is displayed in server console.

=Includes=
Pawn requires '''include files''', much like C requires header files. Include files list all of the structures, functions, callbacks, and tags that are available. There are three types of include files:
*'''Core''' - <tt>sourcemod.inc</tt> and anything it includes. These are all provided by SourceMod's Core.
*'''Extension''' - adds a dependency against a certain extension.
*'''Plugin''' - adds a dependency against a certain plugin.

Include files are loaded using the <tt>#include</tt> compiler directive.

=Commands=
Our first example will be writing a simple admin command to slap a player. We'll continue to extend this example with more features until we have a final, complete result.

==Declaration==
First, let's look at what an admin command requires. Admin commands are registered using the [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''.

The callback function is what's invoked every time the command is used. [http://docs.sourcemod.net/api/index.php?fastload=show&id=771& Click here] to see its prototype. Example:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
}

public Action:Command_MySlap(client, args)
{
}</pawn>

Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! The reason is because of the <tt>Action</tt> tag. Any command that you type in the console, even if it's registered by SourceMod, will be sent to the engine to be processed. Because we have not had SourceMod block this functionality yet, the engine replies with "Unknown command" because it is not a valid engine command.

<pawn>public Action Command_MySlap(int client, int args)
{
return Plugin_Handled;
}</pawn>

Now the command will report no error, but it still won't do anything. This is because returning "Plugin_Handled" in a command callback will prevent the engine from processing the command. The engine will never even see that the command was run. This is what you will want to do if you are registering a completely new command through SourceMod.

==Implementation==
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:
<pre>sm_myslap <name|#userid> [damage]</pre>

To implement this, we'll need a few steps:
*Get the input from the console. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Find a matching player. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Slap them. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

Full example:

<pawn>
#include <sourcemod>
#include <sdktools>

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0.0.0",
url = "http://www.sourcemod.net/"
}

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], char arg2[32];
int damage;

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1));

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2);
}

/* Try and find a matching player */
int target = FindTarget(client, arg1);
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason.
*/
return Plugin_Handled;
}

SlapPlayer(target, damage);

char name[MAX_NAME_LENGTH];

GetClientName(target, name, sizeof(name));
ReplyToCommand(client, "[SM] You slapped %s for %d damage!", name, damage);

return Plugin_Handled;
}</pawn>

For more information on what %s and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<pawn>ConVar sm_myslap_damage = null

public void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");
AutoExecConfig(true, "plugin_myslap");
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], char arg2[32];
int damage = GetConVarInt(sm_myslap_damage);

/* The rest remains unchanged! */
</pawn>

=Showing Activity, Logging=
Almost all admin commands should log their activity, and some admin commands should show their activity to in-game clients. This can be done via the [http://docs.sourcemod.net/api/index.php?fastload=show&id=599& LogAction()] and [http://docs.sourcemod.net/api/index.php?fastload=show&id=466& ShowActivity2()] functions. The exact functionality of ShowActivity2() is determined by the <tt>sm_show_activity</tt> cvar.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage);

char name[MAX_NAME_LENGTH];

GetClientName(target, name, sizeof(name));

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage);
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage);

return Plugin_Handled;
}
</pawn>

=Multiple Targets=
To fully complete our slap demonstration, let's make it support multiple targets. SourceMod's [[Admin_Commands_%28SourceMod%29#How_to_Target|targeting system]] is quite advanced, so using it may seem complicated at first.

The function we use is [http://docs.sourcemod.net/api/index.php?fastload=show&id=703& ProcessTargetString()]. It takes in input from the console, and returns a list of matching clients. It also returns a noun that will identify either a single client or describe a list of clients. The idea is that each client is then processed, but the activity shown to all players is only processed once. This reduces screen spam.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

ConVar sm_myslap_damage = INVALID_HANDLE

public Plugin myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0.0.0",
url = "http://www.sourcemod.net/"
}

public void OnPluginStart()
{
LoadTranslations("common.phrases");
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage");
AutoExecConfig(true, "plugin_myslap");
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], char arg2[32];
int damage = GetConVarInt(sm_myslap_damage);

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1));

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2);
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
char target_name[MAX_TARGET_LENGTH];
int target_list[MAXPLAYERS], target_count;
bool tn_is_ml;

if ((target_count = ProcessTargetString(
arg1,
client,
target_list,
MAXPLAYERS,
COMMAND_FILTER_ALIVE, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
ReplyToTargetError(client, target_count);
return Plugin_Handled;
}

for (int i = 0; i < target_count; i++)
{
SlapPlayer(target_list[i], damage);
LogAction(client, target_list[i], "\"%L\" slapped \"%L\" (damage %d)", client, target_list[i], damage);
}

if (tn_is_ml)
{
ShowActivity2(client, "[SM] ", "Slapped %t for %d damage!", target_name, damage);
}
else
{
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", target_name, damage);
}

return Plugin_Handled;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

The first answer is that clients are entities. Thus, a client index and an entity index are the same thing. When a SourceMod function asks for an entity index, a client index can be specified. When a SourceMod function asks for a client index, usually it means only a client index can be specified.

A fast way to check if an entity index is a client is checking whether it's between 1 and [http://docs.sourcemod.net/api/index.php?fastload=show&id=397& GetMaxClients()] (inclusive). If a server has N client slots maximum, then entities 1 through N are always reserved for clients. Note that 0 is a valid entity index; it is the world entity (worldspawn).

A userid, on the other hand, is completely different. The server maintains a global "connection count" number, and it starts at 1. Each time a client connects, the connection count is incremented, and the client receives that new number as their userid.

For example, the first client to connect has a userid of 2. If he exits and rejoins, his userid will be 3 (unless another client joins in-between). Although SourceMod fires the OnClientConnected and OnClientDisconnected callbacks every map change, the server tracks players across map changes and does not change their userids or client indexes. To see if a client really connected or disconnected, hook the [[Generic Source Server Events#player_connect|player_connect]] and [[Generic Source Server Events#player_disconnect|player_disconnect]] events instead.

SourceMod provides two functions for userids: [http://docs.sourcemod.net/api/index.php?fastload=show&id=442& GetClientOfUserId()] and [http://docs.sourcemod.net/api/index.php?fastload=show&id=402& GetClientUserId()].

=Events=
Events are informational notification messages passed between objects in the server. Many are also passed from the server to the client. They are defined in .res files under the <tt>hl2/resource</tt> folder and <tt>resource</tt> folders of specific mods. For a basic listing, see [[Game Events (Source)|Source Game Events]].

It is important to note a few concepts about events:
*They are almost always informational. That is, blocking <tt>player_death</tt> will not stop a player from dying. It may block a HUD or console message or something else minor.
*They almost always use userids instead of client indexes.
*Just because it is in a resource file does not mean it is ever called, or works the way you expect it to. Mods are notorious at not properly documenting their event functionality.

An example of finding when a player dies:
<pawn>
public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath);
}

public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
int victim_id = GetEventInt(event, "userid");
int attacker_id = GetEventInt(event, "attacker");

int victim = GetClientOfUserId(victim_id);
int attacker = GetClientOfUserId(attacker_id);

/* CODE */
}</pawn>

=Callback Orders and Pairing=
SourceMod has a number of builtin callbacks about the state of the server and plugin. Some of these are paired in special ways which is confusing to users.

==Pairing==
'''Pairing''' is SourceMod terminology. Examples of it are:
*OnMapEnd() cannot be called without an OnMapStart(), and if OnMapStart() is called, it cannot be called again without an OnMapEnd().
*OnClientConnected(N) for a given client N will only be called once, until an OnClientDisconnected(N) for the same client N is called (which is guaranteed to happen).

There is a formal definition of SourceMod's pairing. For two functions X and Y, both with input A, the following conditions hold:
*If X is invoked with input A, it cannot be invoked again with the same input unless Y is called with input A.
*If X is invoked with input A, it is guaranteed that Y will, at some point, be called with input A.
*Y cannot be invoked with any input A unless X was called first with input A.
*The relationship is described as, "X is paired with Y," and "Y is paired to X."

==General Callbacks==
These callbacks are listed in the order they are called, in the lifetime of a plugin and the server.

*[https://sm.alliedmods.net/new-api/sourcemod/AskPluginLoad2 AskPluginLoad2()] - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here.
*[https://sm.alliedmods.net/new-api/sourcemod/OnPluginStart OnPluginStart()] - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. '''This is paired with OnPluginEnd()'''.
*[https://sm.alliedmods.net/new-api/sourcemod/OnAllPluginsLoaded OnAllPluginsLoaded()] - Called once, after all non-late loaded plugins have called OnPluginStart.
*[https://sm.alliedmods.net/new-api/sourcemod/OnMapStart OnMapStart()] - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*[https://sm.alliedmods.net/new-api/sourcemod/OnConfigsExecuted OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).
*[https://sm.alliedmods.net/new-api/sourcemod/OnMapEnd OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[https://sm.alliedmods.net/new-api/sourcemod/OnPluginEnd OnPluginEnd()] - Called once, immediately before the plugin is unloaded. '''This function is paired to OnPluginStart().'''

==Client Callbacks==
These callbacks are listed in no specific order, however, their documentation holds for both fake and real clients.

*[https://sm.alliedmods.net/new-api/clients/OnClientConnect OnClientConnect()] - Called when a player initiates a connection. You can block a player from connecting by returning Plugin_Stop and setting rejectmsg to an error message.
*[https://sm.alliedmods.net/new-api/clients/OnClientConnected OnClientConnected()] - Called after a player connects. Signifies that the player is in-game and IsClientConnected() will return true. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[https://sm.alliedmods.net/new-api/clients/OnClientAuthorized OnClientAuthorized()] - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between OnClientConnected and OnClientPreAdminCheck/OnClientDisconnect. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use OnClientPostAdminCheck().
*[https://sm.alliedmods.net/new-api/clients/OnClientPutInServer OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[https://sm.alliedmods.net/new-api/clients/OnClientPostAdminCheck OnClientPostAdminCheck()] - Called after the player is '''both authorized and in-game'''. This is the best callback for checking administrative access after connect.
*[https://sm.alliedmods.net/new-api/clients/OnClientDisconnect OnClientDisconnect()] - Called when a player's disconnection starts. '''This is paired to OnClientConnected().'''
*[https://sm.alliedmods.net/new-api/clients/OnClientDisconnect_Post OnClientDisconnect_Post()] - Called when a player's disconnection ends. '''This is paired to OnClientConnected().'''

=Frequently Asked Questions=
==Are plugins reloaded every mapchange?==
Plugins, by default, are not reloaded on mapchange unless their timestamp changes. This is a feature so plugin authors have more flexibility with the state of their plugins.

==Do I need to call CloseHandle in OnPluginEnd?==
No. SourceMod automatically closes your Handles when your plugin is unloaded, in order to prevent memory errors.

==Do I need to #include every individual .inc?==
No. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> includes everything starting with <sdktools>.

==Why don't some events fire?==
There is no guarantee that events will fire. The event listing is not a specification, it is a list of the events that a game is capable of firing. Whether the game actually fires them is up to Valve or the developer.

==Do I need to CloseHandle timers?==
No. In fact, doing so may cause errors. Timers naturally die on their own unless they are infinite timers, in which case you can use KillTimer() or die gracefully by returning <tt>Plugin_Stop</tt> in the callback.

==Are clients disconnected on mapchange?==
All clients are fully disconnected before the map changes. They are all reconnected after the next map starts.

If you only want to detect when a client initially connects or leaves your server, hook the [[Generic Source Server Events#player_connect|player_connect]] or [[Generic Source Server Events#player_disconnect|player_disconnect]] events respectively.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

He:Adding Admins (SourceMod)

2013-08-23T07:41:40Z

Shavit: Blanked the page

He:Adding Admins (SourceMod)

2013-08-23T07:41:00Z

Shavit: Created page with "__FORCETOC__ SourceMod has as very detailed and flexible administration system, and it can be quite daunting to users. To simplify things, there are a number of "flags" which..."

__FORCETOC__
SourceMod has as very detailed and flexible administration system, and it can be quite daunting to users. To simplify things, there are a number of "flags" which specify generic permissions administrators can have.

There are currently two provided ways of storing admins. One is via the admin-flatfile.smx plugin that is enabled by default. This plugin provides two files: a simplified flat file, and another more complex tree-based file. The other way to store admins is using [[SQL Admins (SourceMod)|SQL]].

SourceMod provides three methods of authentication:
*''Steam ID'' (unique to a Steam account)
*''IP Address'' (semi-unique to a given computer, better for LANs)
*''Name'' (requires a password)

=Quick Start=
On the server, open [modfolder]/addons/sourcemod/configs/admins_simple.ini

In a new line, add the following, replacing yoursteamid (use your client's console '''status''' command to retrieve your Steam ID - formatted as STEAM_n:o:p)

'''"yoursteamid" "99:z"'''

Save the file, then type sm_reloadadmins in the server console. Connect to the server with the game client. Enter sm_admin in the client console, and then return to the game. You should see the admin menu.

=Levels=
First, let's quickly run down the provided levels:
:{| cellpadding="5"
|- class="t2th"
| Name
| Flag
| Purpose
|- class="t2td"
| reservation
| a
| Reserved slot access.
|- class="t2td"
| generic
| b
| Generic admin; required for admins.
|- class="t2td"
| kick
| c
| Kick other players.
|- class="t2td"
| ban
| d
| Ban other players.
|- class="t2td"
| unban
| e
| Remove bans.
|- class="t2td"
| slay
| f
| Slay/harm other players.
|- class="t2td"
| changemap
| g
| Change the map or major gameplay features.
|- class="t2td"
| cvar
| h
| Change most cvars.
|- class="t2td"
| config
| i
| Execute config files.
|- class="t2td"
| chat
| j
| Special chat privileges.
|- class="t2td"
| vote
| k
| Start or create votes.
|- class="t2td"
| password
| l
| Set a password on the server.
|- class="t2td"
| rcon
| m
| Use RCON commands.
|- class="t2td"
| cheats
| n
| Change sv_cheats or use cheating commands.
|- class="t2td"
| root
| z
| Magically enables all flags.

|- class="t2td"
| custom1
| o
| Custom Group 1.
|- class="t2td"
| custom2
| p
| Custom Group 2.
|- class="t2td"
| custom3
| q
| Custom Group 3.
|- class="t2td"
| custom4
| r
| Custom Group 4.
|- class="t2td"
| custom5
| s
| Custom Group 5.
|- class="t2td"
| custom6
| t
| Custom Group 6.
|}

=Immunity=
In SourceMod, immunity is a flexible system based on ''immunity levels''. Every admin can have an arbitrary immunity value assigned to them. Whether an admin can target another admin depends on who has a higher immunity value.

For example, say Admin #1 has an immunity level of "3" and Admin #2 has an immunity level of "10." Admin #2 can target Admin #1, but Admin #1 cannot target Admin #2. The numbers are completely arbitrary, and they can be any number equal to or higher than 0. Note that 0 always implies no immunity.

By default, admins with the same immunity value can target each other. This can be changed via <tt>sm_immunity_mode</tt> in <tt>cfg/sourcemod.cfg</tt>.

=Passwords=
For passwords to work, the server administrator must change the "PassInfoVar" line in <tt>addons/sourcemod/configs/core.cfg</tt>. For example:
<pre>"PassInfoVar" "_sm1337"</pre>

Next, if an admin has a password, he or she must set the password via the ''setinfo'' command in the client console. For example, using the examples above, <tt>BAILOPAN</tt> would need to type:
<pre>setinfo "_sm1337" "Gab3n"</pre>

To automate this upon connecting to a server, you can create an "autoexec.cfg" file in your client game folder. This will be located under <tt>SteamApps\ACCOUNT\[game]\[gameabbr]\cfg</tt>. For example:
*<tt>C:\Program Files\Steam\steamapps\bailopan\Counter-Strike Source\cstrike\cfg</tt>

You can also set the password upon connecting. For Steam and IP authentication, your admin privileges will be automatically assigned if the password is correct. For name based authentication, your password must be correct before you change your name, or else you will be kicked from the server.

=Simple Admins=
The easiest way to add administrators is through <tt>configs/admins_simple.ini</tt>. This is a flat file which requires two parameters per line: authentication info, and flags. The flag string is somewhat flexible and can have the following information:
*An optional immunity level value, followed by a colon (':');
*A flag string, '''or''';
*A group name, preceded by an '@' symbol

Three examples are provided:
<pre>
"STEAM_0:1:16" "bce" //generic, kick, unban for this steam ID. no immunity
"!127.0.0.1" "5:z" //all permissions for this ip, immunity level = 5
"BAILOPAN" "abc" "Gab3n" //name BAILOPAN, password "Gab3n": gets reservation, generic, kick
</pre>

=Detailed Admins=
Alternatively, you can add admins via <tt>configs/admins.cfg</tt>, a more advanced file stored in a KeyValues format. Each admin is its own block inside a main "Admin" block. You can create and / or modify <tt>admins.cfg</tt> files with [http://forums.alliedmods.net/showthread.php?t=81160 KVManager]. The format is as follows:

<pre>Admins
{
"Admin Name"
{
"auth" "[steam|name|ip]"
"identity" "[unique id]"
"[option1]" "[value1]"
"[option2]" "[value2]"
/* .... */
}
}</pre>

Available options are:
*<tt>auth</tt>: Required. Must be one of <tt>steam</tt>, <tt>name</tt>, or <tt>ip</tt> (unless there is a custom auth method), and instructs SourceMod how to interpret the <tt>identity</tt> value.
*<tt>identity</tt>: Required. Unique value that allows SourceMod to find this admin given an authentication method and the given value.
*<tt>password</tt>: Optional. Specifies the password the user must enter (see above section on passwords).
*<tt>group</tt>: Optional. Specifies a group name the user should inherit if available. More than one "group" line can be specified. There should be no '@' symbol as there is no ambiguity.
*<tt>flags</tt>: Optional. Default access flags the user should receive.
*<tt>immunity</tt>: Optional: Default immunity level the user should receive.

The admin name is optional (it can be blank). It is not used internally and is intended for convenience usage by 3rd party tools.

Example:
<pre>Admins
{
"BAILOPAN"
{
"auth" "steam"
"identity" "STEAM_0:1:2345"
"flags" "abcdef"
"immunity" "5"
"group" "Awesome Admins"
}

"Blue Crab"
{
"auth" "steam"
"identity" "STEAM_0:1:666666"
"flags" "z"
"immunity" "99"
}
}</pre>

=See Also=
*[[Adding Groups (SourceMod)]]
*[[Overriding Command Access (SourceMod)]]

[[Category:SourceMod Documentation]]