AlliedModders Wiki - User contributions [en]

KeyValues (SourceMod Scripting)

2018-03-10T10:32:56Z

TheXeon: methodmapped

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>new KeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
delete kv;
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>void BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>void DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
delete kv;
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}

delete kv;
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

Timers (SourceMod Scripting)

2018-03-04T11:26:22Z

TheXeon: Change Invalid_Handle to null

Timers in [[SourceMod]] are timed events that occur once or repeatedly at a given interval.

=Introduction=
Timers allow you to set an interval, a function to use as the event callback, and an optional Handle to pass through the callback. This is useful for saving data asynchronously.

All timer functions are in <tt>plugins/include/timers.inc</tt>.

=Basic Usage=
==One-Time Timers==
One-time timers are timers that only execute once. An example of a one-time timer might look like:

<pawn>public void OnPluginStart()
{
CreateTimer(5.0, LoadStuff);
}

public Action LoadStuff(Handle timer)
{
PrintToServer("Loading stuff!");
}</pawn>

This code will print "Loading stuff!" to the server console five seconds after the map loads. The return value has no meaning for one-time timers.

==Repeatable Timers==
Repeatable timers execute infinitely many times, once every interval. Based on the return value, they either continue or cancel.

For example, say you want to display a message five times, once every three seconds:
<pawn>
void someFunction()
{
CreateTimer(3.0, Timer_PrintMessageFiveTimes, _, TIMER_REPEAT);
}

public Action Timer_PrintMessageFiveTimes(Handle timer)
{
// Create a global variable visible only in the local scope (this function).
static int numPrinted = 0;

if (numPrinted >= 5)
{
numPrinted = 0;
return Plugin_Stop;
}

PrintToServer("Warning! This is a message.");
numPrinted++;

return Plugin_Continue;
}</pawn>

Note that <tt>Plugin_Stop</tt> stops the timer, and <tt>Plugin_Continue</tt> allows it to continue repeating.

=Passing Data=
==Simple Values==
As mentioned earlier, timers let you pass values on to the callback function. This value can be any type. For example, let's say we want to print a message to a player fifteen seconds after they connect. However, we want to cancel the timer if the player disconnects. Implementing this is very easy:

<pawn>
Handle WelcomeTimers[MAXPLAYERS+1];

public void OnClientPutInServer(int client)
{
WelcomeTimers[client] = CreateTimer(15.0, WelcomePlayer, client);
}

public void OnClientDisconnect(int client)
{
if (WelcomeTimers[client] != null)
{
KillTimer(WelcomeTimers[client]);
WelcomeTimers[client] = null;
}
}

public Action WelcomePlayer(Handle timer, any client)
{
PrintToConsole(client, "Welcome to the server!");
WelcomeTimers[client] = null;
}</pawn>

Another example without using handles is to use either UserID or ClientSerial (which is unique to each player):

<pawn>
public void OnClientPutInServer(int client)
{
CreateTimer(15.0, WelcomePlayer, GetClientSerial(client)); // You could also use GetClientUserId(client)
}

public Action WelcomePlayer(Handle timer, any serial)
{
int client = GetClientFromSerial(serial); // Validate the client serial

if (client == 0) // The serial is no longer valid, the player must have disconnected
{
return Plugin_Stop;
}

PrintToConsole(client, "Welcome to the server!");
}</pawn>
If you want to close or cancel a timer when a client disconnects, then use the first example with handles.

==Handles==
If you want to pass a Handle as a value, you have the option of using <tt>TIMER_DATA_HNDL_CLOSE</tt>, which will automatically call <tt>CloseHandle()</tt> for you once the timer dies.

==Data Packs==
Data packs are packable structures that can be used to hold asynchronous data (data that must be saved and unpacked for later). They are especially useful for timers, and thus there exists a helper function, called <tt>CreateDataTimer()</tt>, which creates a timer using a data pack handle. The handle is created and closed automatically for you.

The above example could be rewritten as:
<pawn>
Handle WelcomeTimers[MAXPLAYERS+1];

public void OnClientPutInServer(int client)
{
DataPack pack;
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack);
pack.WriteCell(client);
pack.WriteString("Welcome to the server!");
}

public void OnClientDisconnect(int client)
{
if (WelcomeTimers[client] != null)
{
KillTimer(WelcomeTimers[client]);
WelcomeTimers[client] = null;
}
}

public Action WelcomePlayer(Handle timer, Handle pack)
{
char str[128];
int client;

/* Set to the beginning and unpack it */
ResetPack(pack);
client = ReadPackCell(pack);
ReadPackString(pack, str, sizeof(str));

PrintToConsole(client, "%s", str);
WelcomeTimers[client] = null;
}</pawn>

=Notes=
==Accuracy==
The smallest possible interval is 0.1 seconds. Timers have high precision (floating point) but low accuracy, as the current time is based on the in-game tick count, not the system clock. This has two implications:
*If the server is paused (not ticking or hibernating), timers will not run.
*The server will not always tick at an exact interval.

For example, a 1.234 second interval timer starting from time <tt>t</tt> might not tick until <tt>t+1.242</tt> at a tickrate of 66 ticks per second.

==Timer Death==
All timers are guaranteed to die either by:
*<tt>CloseHandle()</tt> being called (or on plugin unload);
*<tt>KillTimer()</tt> being called;
*<tt>Plugin_Stop</tt> being returned from a repeatable timer;
*<tt>TriggerTimer()</tt> being called on a one-time timer;
*Execution of a one-time timer finishes.

When a timer dies, if <tt>TIMER_DATA_HNDL_CLOSE</tt> is set, the Handle will always be closed with the permissions that <tt>CloseHandle()</tt> uses by default. Since timers cannot be cloned, there should be no ownership issues.

==Changing Intervals==
The interval of a timer cannot be changed as of this writing. The timer must be killed and a new one created.

==AMX Mod X==
Unlike [[AMX Mod X]]'s <tt>set_task</tt> function, you cannot pass arrays using <tt>CreateTimer</tt>. To accomplish this, you should use the data pack functionality explained above.

Similarly, there are no flags for counted repeats (non-infinite loops) or timers based on the map start or end. These must be done manually.

=External Links=
*[http://www.sourcemod.net/devlog/?p=130 On Timer Design, Part 3] (SourceMod DevLog)
*[http://www.sourcemod.net/devlog/?p=119 On Timer Design, Part 2] (SourceMod DevLog)
*[http://www.sourcemod.net/devlog/?p=118 On Timer Design, Part 1] (SourceMod DevLog)

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T21:13:29Z

TheXeon: /* Full Deletion */

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
delete kv;
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>void BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>void DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
delete kv;
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}

delete kv;
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T21:13:05Z

TheXeon: /* Full Deletion */

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
delete kv;
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>void BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>void DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
delete kv;
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
delete kv;
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T21:11:42Z

TheXeon: /* Full Traversal */

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
delete kv;
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>void BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T21:11:22Z

TheXeon: /* Iterative Deletion */

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
delete kv;
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T21:10:18Z

TheXeon: /* Simple Deletion */

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
delete kv;
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
void RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T21:09:05Z

TheXeon: /* Iterative Lookup */

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
delete kv;
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T21:08:28Z

TheXeon: delete on return false;

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name,int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
delete kv;
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T20:21:12Z

TheXeon: Delete structure after use

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
delete kv;
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name,int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T20:20:12Z

TheXeon:

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>kv.ImportFromFile</tt> To save KeyValues to a file, use <tt>kv.ExportToFile</tt>, where <tt>kv</tt> is a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name,int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

KeyValues (SourceMod Scripting)

2018-02-22T20:18:54Z

TheXeon: Change to newdecls

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the [http://developer.valvesoftware.com/wiki/KeyValues_class Valve Developer Wiki].

All KeyValues specific functions in this document are from <tt>public/include/keyvalues.inc</tt>.

''Note: While the following examples are correct code-wise, over the years they have occasionally led people to use KeyValues in cases where they really should be using a [https://wiki.alliedmods.net/SQL_%28SourceMod_Scripting%29 database] instead.''

=Introduction=
KeyValues consist of a ''nodes'', or ''sections'', which contain pairs of keys and values. A section looks like this:
<pre>"section"
{
"key" "value"
}</pre>

The <tt>"section"</tt> string denotes the section's name. The <tt>"key"</tt> string is the key name, and the <tt>"value"</tt>" string is the value.

KeyValues structures are created with <tt>CreateKeyValues()</tt>. The Handle must be freed when finished in order to avoid a memory leak.

=Files=
KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:
<pre>"MyFile"
{
"STEAM_0:0:7"
{
"name" "crab"
}
}</pre>

In this example, <tt>STEAM_0:0:7</tt> is a section under <tt>MyFile</tt>, the root node.

To load KeyValues from a file, use <tt>KeyValues.ImportFromFile</tt> To save KeyValues to a file, use <tt>KeyValues.ExportToFile</tt>. For both cases, you must already have a Handle to a KeyValues structure.

=Traversal=
SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:
*The root node
*A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the ''traversal stack'' is used to save a history of each ''traversal'' made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The ''top'' of this stack is where all operations take place.

For example, <tt>kv.JumpToKey</tt> will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as <tt>kv.GetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>kv.GotoNextKey</tt> will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:
*<tt>kv.GotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>kv.GoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>kv.Rewind</tt> - Clears the traversal stack so the current position is the root node.

==Basic Lookup==
Let's take our <tt>MyFile</tt> example from above. How could we retrieve the name "crab" given the Steam ID?

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return false;
}
kv.GetString("name", name, maxlength);
delete kv;
return true;
}</pawn>

'''Note:''' <tt>kv.JumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>delete</tt> will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

==Iterative Lookup==
Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

<pawn>bool GetNameFromSteamID(const char[] steamid, char[] name,int maxlength)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");

// Jump into the first subsection
if (!kv.GotoFirstSubKey())
{
return false;
}

// Iterate over subsections at the same nesting level
char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
kv.GetString("name", name, maxlength);
delete kv;
return true;
}
} while (kv.GotoNextKey());

delete kv;
return false;
}</pawn>

'''Note:''' In this example, note that <tt>kv.GotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>kv.GoBack</tt> to return and continue iterating.

==Full Traversal==
Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:
<pawn>BrowseKeyValues(KeyValues kv)
{
do
{
// You can read the section/key name by using kv.GetSectionName here.

if (kv.GotoFirstSubKey(false))
{
// Current key is a section. Browse it recursively.
BrowseKeyValues(kv);
kv.GoBack(kv);
}
else
{
// Current key is a regular key, or an empty section.
if (kv.GetDataType(NULL_STRING) != KvData_None)
{
// Read value of key here (use NULL_STRING as key name). You can
// also get the key name by using kv.GetSectionName here.
}
else
{
// Found an empty sub section. It can be handled here if necessary.
}
}
} while (kv.GotoNextKey(false));
}</pawn>

This function will browse an entire KeyValues structure. Note that every successful call to <tt>kv.GotoFirstSubKey</tt> is paired with a call to <tt>kv.GoBack</tt>. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that <tt>keyOnly</tt> is set to false in both <tt>kv.GotoFirstSubKey</tt> and <tt>kv.GotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>kv.GotoFirstSubKey</tt> succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If <tt>kv.GotoFirstSubKey</tt> failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

=Deletion=
There are two ways to delete sections from a KeyValues structure:
*<tt>kv.DeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>kv.DeleteThis</tt> - Safely removes the current position if possible.

==Simple Deletion==
First, let's use our "basic lookup" example to delete a Steam ID section:
<pawn>
RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}
kv.DeleteThis();
kv.Rewind();
kv.ExportToFile("myfile.txt");
delete kv;
}
</pawn>

'''Note:''' We called <tt>kv.Rewind</tt> so the file would be dumped from the root position, instead of the current one.

==Iterative Deletion==
Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use <tt>kv.DeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>RemoveSteamID(const char[] steamid)
{
KeyValues kv = new KeyValues("MyFile");
kv.ImportFromFile("myfile.txt");
if (!kv.JumpToKey(steamid))
{
return;
}

char buffer[255];
do
{
kv.GetSectionName(buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
kv.DeleteThis();
delete kv;
return;
}
} while (kv.GotoNextKey());

delete kv;
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>kv.DeleteThis</tt> has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as <tt>kv.GotoNextKey</tt> would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:
<pawn>DeleteAll(KeyValues kv)
{
if (!kv.GotoFirstSubKey())
{
return;
}

for (;;)
{
char name[4];
kv.GetString("name", name, sizeof(name));
if (name[0] == '\0')
{
if (kv.DeleteThis() < 1)
{
break;
}
} else if (!kv.GotoNextKey()) {
break;
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>kv.DeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>kv.GotoNextKey</tt> fails, the loop will end.

==KeyValue Creation==
This is how you would create the <tt>MyFile</tt> example from above with the KeyValue API
<pawn>KeyValues kv = new KeyValues("MyFile");
kv.JumpToKey("STEAM_0:0:7", true);
kv.SetString("name", "crab");
kv.Rewind();
kv.ExportToFile("C:\javalia.txt");
delete kv;</pawn>

[[Category:SourceMod Scripting]]
{{LanguageSwitch}}

Introduction to SourceMod Plugins

2018-01-20T04:12:19Z

TheXeon: Grammar

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 [https://forums.alliedmods.net/showthread.php?t=259917 SPEdit], [https://www.crimsoneditor.com/ Crimson Editor], [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [https://notepad-plus-plus.org/ Notepad++], [https://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ Pawn Studio], [https://forums.alliedmods.net/showthread.php?t=289127 BasicPawn] 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 know 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 is done using <tt>#include</tt> directive. It tells the 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 the compiler doesn't know about the existence of the latter? SourceMod include files are written specially, so they say that the implementation of functions is ''somewhere else''. The compiler understands that and generates 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 set up 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 is 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 the preferable way to fill 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 tell 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 the 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 [https://sm.alliedmods.net/new-api/console/RegAdminCmd 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. [https://sm.alliedmods.net/new-api/console/ConCmd Click here] to see its prototype. Example:

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

public Action Command_MySlap(int client, int 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! This is because you're not returning Plugin_Handled in your callback. Since you haven't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so. The reason SourceMod expects your function to return Plugin_Handled is because of the Action tag you put in your function's prototype. The Action tag specifies that Command_MySlap must return one of four things. See the [https://sm.alliedmods.net/new-api/core/Action Action] enumeration in the sourcemod API to learn more about these return types and when to use them.

<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 [https://sm.alliedmods.net/new-api/console/GetCmdArg GetCmdArg()].
*Find a matching player. For this we use [https://sm.alliedmods.net/new-api/helpers/FindTarget FindTarget()].
*Slap them. For this we use [https://sm.alliedmods.net/new-api/sdktools_functions/SlapPlayer SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [https://sm.alliedmods.net/new-api/console/ReplyToCommand 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], arg2[32];

/* By default, we set damage = 0 */
int damage = 0;

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

/* If there are 2 or more arguments, we set damage to
* what the user specified. If a damage isn't specified
* then it will stay zero. */
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 and returns -1 so we know not
* to continue
*/
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 [https://sm.alliedmods.net/new-api/sourcemod/AutoExecConfig AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommended 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], 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 [https://sm.alliedmods.net/new-api/logging/LogAction LogAction()] and [https://sm.alliedmods.net/new-api/console/ShowActivity2 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 [https://sm.alliedmods.net/new-api/commandfilters/ProcessTargetString 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 = null;

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], 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>

=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 for 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 = event.GetInt("userid");
int attacker_id = event.GetInt("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 can confuse 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}}

Introduction to SourceMod Plugins

2018-01-20T04:01:29Z

TheXeon: Add BasicPawn

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 [https://forums.alliedmods.net/showthread.php?t=259917 SPEdit], [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], [https://forums.alliedmods.net/showthread.php?t=289127 BasicPawn] 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 [https://sm.alliedmods.net/new-api/console/RegAdminCmd 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. [https://sm.alliedmods.net/new-api/console/ConCmd Click here] to see its prototype. Example:

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

public Action Command_MySlap(int client, int 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! This is because you're not returning Plugin_Handled in your callback. Since you haven't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so. The reason SourceMod expects your function to return Plugin_Handled is because of the Action tag you put in your function's prototype. The Action tag specifies that Command_MySlap must return one of four things. See the [https://sm.alliedmods.net/new-api/core/Action Action] enumeration in the sourcemod API to learn more about these return types and when to use them.

<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 [https://sm.alliedmods.net/new-api/console/GetCmdArg GetCmdArg()].
*Find a matching player. For this we use [https://sm.alliedmods.net/new-api/helpers/FindTarget FindTarget()].
*Slap them. For this we use [https://sm.alliedmods.net/new-api/sdktools_functions/SlapPlayer SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [https://sm.alliedmods.net/new-api/console/ReplyToCommand 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], arg2[32];

/* By default, we set damage = 0 */
int damage = 0;

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

/* If there are 2 or more arguments, we set damage to
* what the user specified. If a damage isn't specified
* then it will stay zero. */
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 and returns -1 so we know not
* to continue
*/
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 [https://sm.alliedmods.net/new-api/sourcemod/AutoExecConfig 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], 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 [https://sm.alliedmods.net/new-api/logging/LogAction LogAction()] and [https://sm.alliedmods.net/new-api/console/ShowActivity2 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 [https://sm.alliedmods.net/new-api/commandfilters/ProcessTargetString 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 = null;

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], 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>

=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 = event.GetInt("userid");
int attacker_id = event.GetInt("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}}