AlliedModders Wiki - User contributions [en]

KeyValues (SourceMod Scripting)

2013-07-24T15:21:33Z

11530: Changed incorrect native name from KeyValuesFromFile to KeyValuesToFile

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>.

=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>FileToKeyValues</tt> To save KeyValues to a file, use <tt>KeyValuesToFile</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>KvJumpToKey</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>KvGetString</tt> will use this new position.

There are natives which change the position but do not change the traversal stack. For example, <tt>KvGotoNextKey</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>KvGotoFirstSubKey</tt> - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
*<tt>KvGoBack</tt> - Pops the traversal stack (moves up one level).
*<tt>KvRewind</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 String:steamid[], String:name[], maxlength)
{
new Handle:kv = CreateKeyValues("MyFile");
FileToKeyValues(kv, "myfile.txt");
if (!KvJumpToKey(kv, steamid))
{
return false;
}
KvGetString(kv, "name", name, maxlength);
CloseHandle(kv);
return true;
}</pawn>

'''Note:''' <tt>KvJumpToKey</tt> is a traversal native that changes the nesting level of the traversal stack. However, <tt>CloseHandle</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 String:steamid[], String:name[], maxlength)
{
new Handle:kv = CreateKeyValues("MyFile");
FileToKeyValues(kv, "myfile.txt");

if (!KvGotoFirstSubKey(kv))
{
return false;
}

decl String:buffer[255];
do
{
KvGetSectionName(kv, buffer, sizeof(buffer));
if (StrEqual(buffer, steamid))
{
KvGetString(kv, "name", name, maxlength);
CloseHandle(kv);
return true;
}
} while (KvGotoNextKey(kv));

CloseHandle(kv)
return false
}</pawn>

'''Note:''' In this example, note that <tt>KvGotoNextKey</tt> is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call <tt>KvGoBack</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(Handle:kv)
{
do
{
// You can read the section/key name by using KvGetSectionName here.

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

This function will browse an entire KeyValues structure. Note that every successful call to <tt>KvGotoFirstSubKey</tt> is paired with a call to <tt>KvGoBack</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>KvGotoFirstSubKey</tt> and <tt>KvGotoNextKey</tt> so that it will jump to regular keys and not just between sections. Because of this we also need to check if <tt>KvGotoFirstSubKey</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>KvGotoFirstSubKey</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>KvDeleteKey</tt> - Safely removes a named sub-section and any of its child sections/keys.
*<tt>KvDeleteThis</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 String:steamid[])
{
new Handle:kv = CreateKeyValues("MyFile")
FileToKeyValues(kv, "myfile.txt")
if (!KvGotoFirstSubKey(kv))
{
return
}
KvDeleteKey(kv, steamid)
KvRewind(kv)
KeyValuesToFile(kv, "myfile.txt")
CloseHandle(kv)
}</pawn>

'''Note:''' We called <tt>KvRewind</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>KvDeleteThis</tt>, which deletes the current position from the previous position in the traversal stack.

<pawn>RemoveSteamID(const String:steamid[])
{
new Handle:kv = CreateKeyValues("MyFile")
FileToKeyValues(kv, "myfile.txt")

if (!KvGotoFirstSubKey(kv))
{
return
}

decl String:buffer[255]
do
{
KvGetSectionName(kv, buffer, sizeof(buffer))
if (StrEqual(buffer, steamid))
{
KvDeleteThis(kv)
CloseHandle(kv)
return
}
} while (KvGotoNextKey(kv))

CloseHandle(kv)
}</pawn>

==Full Deletion==
Now, let's take a look at how we would delete all (or some) keys. <tt>KvDeleteThis</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>KvGotoNextKey</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(Handle:kv)
{
if (!KvGotoFirstSubKey(kv))
{
return
}

for (;;)
{
decl String:name[4]
KvGetString(kv, name, sizeof(name))
if (name[0] == '\0')
{
if (KvDeleteThis(kv) < 1)
{
break
}
} else if (!KvGotoNextKey(kv)) {
break
}
}
}</pawn>

While at first this loop looks infinite, it is not. If <tt>KvDeleteThis</tt> fails to find a subsequent key, it will break out of the loop. Similarly, if <tt>KvGotoNextKey</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>new Handle:kv = CreateKeyValues("MyFile");
KvJumpToKey(kv, "STEAM_0:0:7", true);
KvSetString(kv, "name", "crab");
KvRewind(kv);
KeyValuesToFile(kv, "C:\javalia.txt");
CloseHandle(kv);</pawn>

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

Entity References (SourceMod)

2012-08-09T20:47:14Z

11530: /* Using References to handle a logic entity */ Changing code to use references instead of indices

An entity reference is a combination of a standard entity index (used for all entities in SourceMod previously) and a pseudo-unique serial number that identifies the entity. Since entities are constantly being created and destroyed a cached index doesn't guarantee the underlying entity is the same, references provide a way of verifying the same entity still exists. Generally speaking, if you have an entity index you wish to cache you should convert it to a reference first. All natives (provided by SourceMod) should be able to accept references in place of indexes (wherever the parameter asks for an entity - Not clients), and these will check use the serial to check that the entity index contained in the reference is the same as when the reference was created.

SourceMod now also supports handling of logical (non-networked entities) and these use references exclusively. Natives that used to return an entity index will continue to do so in the case of networked entities (for backwards compatability) and will only return a reference for non-networked ones.

==Converting a backwards-compat index/ref to a guaranteed reference for safely caching==

<pawn>
new index = GetEntPropEnt(client, Prop_Send, "m_hActiveWeapon");

/* Convert our backwards-compat index/ref to a guaranteed reference */
new ref = EntIndexToEntRef(index);
</pawn>

==Converting a reference back to an entity index==

<pawn>
new index = EntRefToEntIndex(ref);

if (index == INVALID_ENT_REFERENCE)
{
/* Reference wasn't valid - Entity must have been deleted */
}
</pawn>

==Using References to handle a logic entity==

<pawn>
new ent = -1;

while ((ent = FindEntityByClassname(ent, "logic_auto")) != -1)
{
/**
* Get the entity index from this reference - This works on references and indexes for convenience.
* Should be a number >2048 since logic_auto is a non networked entity
*/
new ref = EntIndexToEntRef(ent);

/* Fire an input on this entity - We use the reference version since this includes a serial check */
AcceptEntityInput(ref, "Kill");

}
</pawn>

[[Category:SourceMod Scripting]]

Overriding Command Access (SourceMod)

2012-06-25T01:04:17Z

11530:

This article explains how, without editing plugin source code, you can change the flags or permissions on any command, either globally, or for a specific group.

=Introduction=
Command access overrides are one of the most powerful aspects of the SourceMod administration system. They effectively let you:
*Change the access to any admin command without modifying plugin source code;
*Change the access to entire groups of commands without modifying source code;
*Create custom access levels;
*Allow or deny commands and groups of commands to an administrator group regardless of the command flags.

When you change the permissions to a SourceMod object, it is called an ''override''. An override is an arbitrary string. If the override string matches a command name, then the command permissions will be inherited from that override.

This concept is important for two reasons:
*An override can change the permissions of a command.
*An override can be used as a custom access flag.

For example, a plugin might require access "g" to use the <tt>sm_map</tt> command. However, an override could explicitly allow/deny usage of this command to a given group, and/or it could change the default flag for <tt>sm_map</tt> to be "k" instead.

More interestingly, a plugin could require <tt>sm_map</tt> access in order to use a specific menu option. In this case, a user would have to be able to access <tt>sm_map</tt>, rather than have a hardcoded flag.

As a final example of the flexibility of this system, a plugin might say that users must be able to access <tt>plugin_crab_usage</tt>, which isn't a command at all. Instead, the plugin assumes a ''default'' access level internally, and users can opt to override it as they wish. This demonstrates that overrides are separate from commands, however, commands themselves inherit their permissions from overrides of the same name.

=Override Types=
Overrides come in two flavors: ''command'' overrides and ''command group'' overrides. Command overrides are overrides that, if they have the same name as a command, that command will automatically inherit that override's permissions.

Similarly, a ''command group'' override is an override that which, if a command has the same group name as a ''command group'' override, that command will inherit the override's permissions.

Example 1: If a command override exists for <tt>sm_map</tt>, any admin command named <tt>sm_map</tt> will inherit those permissions.

Example 2: If a command group override exists for <tt>CSDM</tt>, any admin command labelled as a "CSDM" command will inherit those permissions.

=Global Configuration=
Access levels for overrides can be globally reconfigured via <tt>configs/admin_overrides.cfg</tt>. The file format is very simple:

<pre>
Overrides
{
"[name1]" "[flags]"
"@[group1]" "[flags]"
/* ... */
}</pre>

Command groups are specified with an 'at' sign ('@') preceding the name. Example:

<pre>
Overrides
{
"sm_map" "k" //Change "sm_map" to the "k" flag.
"@CSDM" "m" //Change all CSDM commands to the "m" flag.
"sm_chat" "" //Allow anyone to use "sm_chat"
}</pre>

Note that given an arbitrary number of flags, the client must require access to '''all''' specified flags in the string, as opposed to just any one of them.

=Group Configuration=
Group overrides are given on an allow or deny basis. That is, rather than changing flags per-group, the override is simply whether it is allowed or denied to members of that group.

For more information, visit [[Adding_Groups_%28SourceMod%29#File_Format|Adding Groups]].

[[Category:SourceMod Documentation]]

SourceMod Profiler

2012-03-29T21:26:25Z

11530: Changing example code from "*" to "adminhelp"

The SourceMod profiler is a built-in tool for measuring the performance of SourceMod natives and plugins.

It is currently an "alpha" addition. While it was tested to work, there may be cases where it breaks. Do not use it in a production environment -- it is intended as a tool for developers.

=Introduction=
The SourceMod Profiler tracks "profilable items." These items are:
* Native calls from plugins.
* Callbacks into plugins.
* Internal function calls in plugins.

The following statistics are tracked for each item:
* Number calls.
* Total time spent in all calls.
* Minimum time spent in any call.
* Maximum time spent in any call.

These statistics can be used to gauge how well your plugin is performing. It can also be used to tweak and optimize your code where necessary.

=Usage=
==Configuration==
The profiler can only be enabled in <tt>configs/plugin_settings.cfg</tt>. You can enable it on any number of plugins at a time. However, it is a good idea to only profile what you need.

The profiler can be configured with the "profile" option key in an "Options" section. The value should be a bits added up:
* 1 - Profile natives.
* 2 - Profile callbacks.
* 4 - Profile functions (implies 2).

Example for profiling "adminhelp":
<pre>
"adminhelp"
{
"pause" "no"
"lifetime" "mapsync"

"Options"
{
"debug" "no"
"profile" "7"
}
}
</pre>

Note that one can also use the "*" wildcard (as seen in the default config) in place of a plugin name in order to change the settings of all loaded plugins.

==Getting Results==
You can use "sm profiler flush" in your console to dump and reset the profiler statistics. The output will be written to an XML file in your <tt>sourcemod/logs</tt> folder. For example: <tt>addons/sourcemod/logs/profile_1204422886.xml</tt> (note that a timestamp is included).

There is no way to stop the profiler entirely save from editing <tt>plugin_settings.cfg</tt>

=Interpreting Results=
[[image:Sm_profiler.PNG|thumb|right|300px|Profiler Screenshot]]
The easiest way to interpret the results is to use the <tt>profviewer.exe</tt> tool available on SourceMod's downloads page. It requires the [http://www.microsoft.com/downloads/details.aspx?FamilyID=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5&displaylang=en .NET 2.0 Framework]. You can open profiler .xml files with this tool and sort the various result metrics (descending order only).

*All times are in seconds. The "min" and "max" times are single measurements. The "average" time is the total time spent divided by the number of calls.
*Function names are displayed as raw names for natives, or "a!b" for plugins, where "a" is the plugin filename and "b" is the function name.

It is important to note how the time values are actually computed. You may find the results to be deceiving otherwise. Take the following list of events:
*Core calls <tt>OnClientCommand</tt> in plugin <tt>a.smx</tt>
*<tt>a.smx!OnClientCommand</tt> calls <tt>a.smx!StrEqual</tt>
*<tt>a.smx!StrEqual</tt> calls <tt>strcmp()</tt>

SourceMod computes each item's time by adding in its children's time. For example, the time <tt>t(a.smx!OnClientCommand)</tt> will be equal to:
<pre>t(a.smx!OnClientCommand) + t(a.smx!StrEqual) + t(strcmp)</pre>

Likewise, the time of <tt>StrEqual</tt> will be equal to:
<pre>t(a.smx!StrEqual) + t(strcmp)</pre>

This has two major implications:
*'''You cannot profile recursive functions'''. The data will be nonsensical. Use <tt>profiler.inc</tt> for manually timing recursive calls.
*The time of re-entrant functions may be deceiving. For example, <tt>DisplayMenu()</tt> may appear very slow, but that's because it may fire dozens of callbacks. Similarly, the custom sorting natives' time will include their callbacks' time. That doesn't necessarily mean the natives themselves are slow, but that they are slow because of the callbacks they are invoking.

''Note: The profiler does not include its own internal operations when timing items. There is a small margin of error, however.''

In general, you should not go insane trying to optimize unless there is a good reason. For example, an <tt>OnGameFrame</tt> callback may be called 200 times per minute, and thus if its average time exceeds reasonable values (say, a dozen milliseconds) then you may want to consider optimizing it. However, if you see that a particular call to <tt>LoadTranslations()</tt> is taking 150ms, you shouldn't worry too much - that function only gets called on load.

Use your judgment when interpreting the results, and don't go crazy. If you need advice, post on the forums.

=File Format=
The file format is XML. The contents are fairly self-explanatory, as there are only three elements. Sample parsers are included in the SourceMod source code tree:

*<tt>tools/csharp</tt> - Source code for the profviewer.exe program. <tt>ProfReport.cs</tt> implements the parser.
*<tt>php/ProfFileParser.class.php</tt> - Source code for a PHP parser. Requires PHP5 and libexpat (XML) support.

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