AlliedModders Wiki - User contributions [en]

Scripting FAQ (SourceMod)

2015-03-09T08:34:22Z

TnTSCS: /* How do I add color to my messages? */

[[Image:Yak.gif]]
yak wuz heer

=How do I learn SourcePawn?=
A good start is on the [[Introduction to SourcePawn]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.

=Where can I find all the SourcePawn functions and other information?=
All SourceMod plug-ins have this line:

<pawn>#include <sourcemod></pawn>

This line instructs the compiler to retrieve the file <tt>sourcemod.inc</tt> from the <tt>sourcemod/scripting/include</tt> folder. Every function, variable, and definition can be found in the <tt>.inc</tt> files inside the <tt>sourcemod/scripting/include</tt> folder.

But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [http://docs.sourcemod.net/api/ http://docs.sourcemod.net/api/]

Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the <tt>!api</tt> command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:
<pre><theY4Kman> !api Netclass
<yakbot> theY4Kman: GetEntityNetClass(edict, String:clsname[], maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (http://docs.sourcemod.net/api/index.php?fastload=show&id=66)</pre>

=How do I find the classname of an entity? (e.g., "<tt>weapon_knife</tt>" or "<tt>prop_physics</tt>")=
The classname of an entity (not to be confused with a netclass such as <tt>CCSPlayer</tt>) is a unique identifier. It's the most well known of entity names. To find it, use the function [http://docs.sourcemod.net/api/index.php?fastload=show&id=65 GetEdictClassname()]:

<pawn>decl String:classname[128];
GetEdictClassname(myentity, classname, sizeof(classname));

PrintToServer("myentity classname: %s", classname);
// myentity classname: weapon_knife</pawn>

=How do I block regular commands, such as <tt>kill</tt> and <tt>say</tt>?=
As of version 1.3, the recommended way to hook and block commands is with [http://docs.sourcemod.net/api/index.php?fastload=show&id=949 AddCommandListener()]. Previously, using [http://docs.sourcemod.net/api/index.php?fastload=show&id=470 RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [http://docs.sourcemod.net/api/index.php?fastload=show&id=949 AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.

Here's how to use it to block the <tt>say</tt> command:

<pawn>public OnPluginStart()
{
AddCommandListener(SayCallback, "say");
}

public Action:SayCallback(client, const String:command[], argc)
{
Return Plugin_Handled;
}</pawn>

=How do I hook +commands, such as <tt>+zoom</tt> and <tt>+attack</tt>?=
Unlike regular commands, <tt>+commands</tt> are handled on the client's computer, then sent to the server in a more compressed fashion. This means [http://docs.sourcemod.net/api/index.php?fastload=show&id=949 AddCommandListener()] cannot be used to hook <tt>+commands</tt>. As of version 1.3, the recommended solution is to use the global forward [http://docs.sourcemod.net/api/index.php?fastload=show&id=937 OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a <tt>+command</tt>, you'll first have to find out its proper <tt>IN_</tt> constant (see <tt>[http://docs.sourcemod.net/api/index.php?fastload=file&id=47&file=& entity_prop_stocks.inc]</tt>).

Here's how to use it to block crouching when attacking:

<pawn>public Action:OnPlayerRunCmd(client, &buttons, &impulse, Float:vel[3], Float:angles[3], &weapon)
{
// Check if the player is attacking (+attack)
if ((buttons & IN_ATTACK) == IN_ATTACK)
{
// If so, block their crouching (+duck)
buttons &= ~IN_DUCK;
}

// We must return Plugin_Continue to let the changes be processed.
// Otherwise, we can return Plugin_Handled to block the commands
return Plugin_Continue;
}</pawn>

=How do I get rid of loose indentation warnings?=
<pre>myplugin.sp(#) : warning 217: loose indentation</pre>

Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.

Good:

<pawn>public OnPluginStart()
{
new myvar = 5;
if (myvar == (2 + 3))
PrintToServer("myvar is %d", myvar);
}</pawn>

Bad:

<pawn>public OnPluginStart()
{
new myvar = 5;
if (myvar == (2 + 3))
PrintToServer("myvar is %d", myvar);
}</pawn>

=How do I get rid of tag mismatch warnings?=
Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are <tt>_</tt> (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), <tt>Float</tt>, <tt>bool</tt>, and <tt>String</tt>. See [[Introduction to SourcePawn#Variables_2]] for more information.

Functions wear these tags on their parameters so you can tell what needs to be passed to the function:
<pawn>native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);</pawn>

This function calls for '''<tt>entity</tt>''', a cell with the implied tag '''''<tt>_</tt>'''''; '''<tt>type</tt>''', with the developer-defined tag '''''<tt>PropType</tt>'''''; '''<tt>prop</tt>''', with the built-in tag '''''<tt>String</tt>'''''; and '''<tt>value</tt>''', with the built-in tag '''''<tt>Float</tt>'''''.
To call this function, then, you must pass values with the specified tags. For example:
<pawn>SetEntPropFloat(1234, Prop_Send, "m_fNumber", 1.0);</pawn>

This calls the function correctly: <tt>1234</tt> is a regular cell ('''''<tt>_</tt>'''''), <tt>Prop_Send</tt> is a variable defined in the enum '''''<tt>PropType</tt>''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&id=4&file=& entity.inc], <tt>"m_fNumber"</tt> is a '''''<tt>String</tt>''''', and <tt>1.0</tt> is a '''''<tt>Float</tt>'''''. For a nonexample:
<pawn>SetEntPropFloat(1234.0, 1, "m_fNumber", 1337);</pawn>

This is incorrect! <tt>1234.0</tt> is a '''''<tt>Float</tt>''''' that should be a regular cell ('''''<tt>_</tt>'''''); <tt>1</tt> is a regular cell ('''''<tt>_</tt>''''') that should be a '''''<tt>PropType</tt>'''''; and <tt>1337</tt> is a regular cell ('''''<tt>_</tt>''''') that should be a '''''<tt>Float</tt>'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''<tt>PropType</tt>''''') can be found in the same file where a function uses them (you can find '''''<tt>PropType</tt>''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&id=4&file=& entity.inc]).

=How do I add color to my messages?=
Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters <tt>0x01</tt> to <tt>0x08</tt>. For example:
<pawn>PrintToChatAll ("\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8");</pawn>

Example output from Left 4 Dead:

[[Image:Left_4_Dead_Colors.png]]

With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:

* <tt style="color: blue;">0x01</tt> = Normal color
* <tt style="color: blue;">0x02</tt> = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.
* <tt style="color: blue;">0x03</tt> = Team color
* <tt style="color: blue;">0x04</tt> = Location color

This data comes from Counter-Strike: Source.

For CS:GO, here are some colors:
<pawn>PrintToChat("\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF");</pawn>

Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:

<pawn>new Handle:hBf;
hBf = StartMessageOne("SayText2", player_to); // To send the message to all players, use StartMessageAll("SayText2");
if (hBf != INVALID_HANDLE)
{
BfWriteByte(hBf, player_from);
BfWriteByte(hBf, 0);
BfWriteString(hBf, "<\x03player_from team color\x01> My message");
EndMessage();
}</pawn>

<tt>player_to</tt> is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&id=132& StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&id=133& StartMessageOne()] to send the message to all players). <tt>player_from</tt> is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming <tt>player_from</tt> is on the RED team):

<player_from team color> My message

There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.

==Color Libraries==
There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:

===exvel's Colors===
This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as <tt>{default}</tt>, <tt>{green}</tt>, or <tt>{blue}</tt>.

Here's some example usage. Note that this code assumes client 1 is in game and on the BLU team:

<pawn>#include <colors>

public OnPluginStart()
{
CPrintToChatAll("{green}Hello {red}World! {default}Test 1 concluded.");

new client_on_blu_team = 1;
CPrintToChatAllEx(client_on_blu_team, "{teamcolor}BLU team {default}says {green}hi!");
}</pawn>

Hello World! Test 1 concluded.
BLU team says hi!

Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to <tt>{green}</tt>.

===SMLib===
[http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as <tt>{N}</tt> and <tt>{G}</tt>, and all colors are supported in its <tt>Client_PrintToChat()</tt> function.

Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the BLU team:

<pawn>#include <smlib>

public OnPluginStart()
{
Client_PrintToChatAll("{G}Hello {R}World! {N}Test 1 concluded.");

new client_on_blu_team = 1;
Client_PrintToChatAll(client_on_blu_team, "{T}BLU team {N}says {G}hi!");
}</pawn>

Hello World! Test 1 concluded.
BLU team says hi!

=Why do I get an "unknown symbol" error when using an SDKTools native?=
None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include <sourcemod> to use SourceMod's functions, you need to:
<pawn>#include <sdktools></pawn>
to use an SDKTools native.

=Why is Source telling me my command is an "Unknown command"?=
This is because you're not returning <tt>Plugin_Handled</tt> in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.

<pawn>public Action:MyCommand(client, args)
{
// Do something...

return Plugin_Handled;
}</pawn>

Timers (SourceMod Scripting)

2013-09-13T16:34:16Z

TnTSCS: /* Simple Values */

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 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>
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 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>
new Handle:WelcomeTimers[MAXPLAYERS+1]

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

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

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

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

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

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

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

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_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>
new Handle:WelcomeTimers[MAXPLAYERS+1]

public OnClientPutInServer(client)
{
new Handle:pack
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack)
WritePackCell(pack, client)
WritePackString(pack, "Welcome to the server!")
}

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

public Action:WelcomePlayer(Handle:timer, Handle:pack)
{
decl String:str[128]
new client

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

PrintToConsole(client, "%s", str)
WelcomeTimers[client] = INVALID_HANDLE
}</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_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}}

Timers (SourceMod Scripting)

2013-09-13T16:20:36Z

TnTSCS: /* Accuracy */

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 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>
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 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>
new Handle:WelcomeTimers[MAXPLAYERS+1]

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

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

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

==Handles==
If you want to pass a Handle as a value, you have the option of using <tt>TIMER_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>
new Handle:WelcomeTimers[MAXPLAYERS+1]

public OnClientPutInServer(client)
{
new Handle:pack
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack)
WritePackCell(pack, client)
WritePackString(pack, "Welcome to the server!")
}

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

public Action:WelcomePlayer(Handle:timer, Handle:pack)
{
decl String:str[128]
new client

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

PrintToConsole(client, "%s", str)
WelcomeTimers[client] = INVALID_HANDLE
}</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_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}}

Upgrading SourceMod

2012-08-11T16:48:30Z

TnTSCS: Added note to shut down game server before updating

When upgrading SourceMod, backwards compatibility is guaranteed except in rare cases. To completely upgrade, you should:

*Ensure your game server is completely stopped and not running as you cannot update some files while they are still in use.
*If you are upgrading to a stable release (not a nightly build), check its release notes for any specific instructions.
*Upgrade all <tt>.so</tt>/<tt>.dll</tt> binaries in the following folders:
**<tt>sourcemod/bin</tt>
**<tt>sourcemod/extensions</tt>
*Upgrade all of the <tt>.txt</tt> files in the <tt>sourcemod/gamedata</tt> folder.
*Upgrade all of the <tt>.txt</tt> files in the <tt>sourcemod/translations</tt> folder.
*Upgrade all of the default <tt>.smx</tt> binaries in the <tt>sourcemod/plugins</tt> folder.
*Read the release notes to see if there were any configuration files that got new features. If so, you should look and see if you want to tweak those new settings. You may want to use a program such as [http://www.scootersoftware.com/ Beyond Compare] or [http://winmerge.org/ WinMerge].

'''Note:''' If a plugin stops working due to a SourceMod upgrade, file a bug report and the development team will assess the situation.

'''Note:''' It is extremely important to update all <tt>gamedata</tt> files, as those specify how SourceMod interacts with mod-specific properties.

'''Note:''' As of SourceMod 1.2.2, the "auto" folders for SourceMod extensions are no longer used by default. Third party extensions, however, may still use them.

'''Note:''' If you update your base SourceMod plugins, you must update your translation files (and vice versa). If you absolutely don't want to update your SourceMod base plugins, you should at least update the <tt>core.phrases.txt</tt> translation file.

'''Note:''' You only need to update the .inc files if you are a plugin developer. If you do update .inc files, you must update the compiler (spcomp.exe for Windows, spcomp for Linux) as well.

[[Category:SourceMod Documentation]]

Commands (SourceMod Scripting)

2012-08-03T01:30:52Z

TnTSCS:

[[SourceMod]] allows you to create console commands similar to [[AMX Mod X]]. There are two main types of console commands:
*'''Server Commands''' - Fired from one of the following input methods:
**the server console itself
**the remote console (RCON)
**the ServerCommand() function, either from SourceMod or the [[Half-Life 2]] engine
*'''Console Commands''' - Fired from one of the following input methods:
**a client's console
**any of the server command input methods

For server commands, there is no client index. For console/client commands, there is a client index, but it may be 0 to indicate that the command is from the server.

Note that button-bound "commands," such as +attack and +duck, are not actually console commands. They are a separate command stream sent over the network, as they need to be tied to a specific frame.

=Server Commands=
As noted above, server commands are fired through the server console, whether remote, local, or through the Source engine. There is no client index associated with a server command.

Server commands are registered through the <tt>RegServerCmd()</tt> function defined in <tt>console.inc</tt>. When registering a server command, you may be hooking an already existing command, and thus the return value is important.
*<tt>Plugin_Continue</tt> - The original server command will be processed, if there was one. If the server command was created by a plugin, this has no effect.
*<tt>Plugin_Handled</tt> - The original server command will not be processed, if there was one. If the server command was created by a plugin, this has no effect.
*<tt>Plugin_Stop</tt> - The original server command will not be processed, if there was one. Additionally, no further hooks will be called for this command until it is fired again.

==Adding Server Commands==
Let's say we want to add a test command to show how Half-Life 2 breaks down command arguments. A possible implementation might be
<pawn>
public OnPluginStart()
{
RegServerCmd("test_command", Command_Test)
}

public Action:Command_Test(args)
{
new String:arg[128]
new String:full[256]

GetCmdArgString(full, sizeof(full))

PrintToServer("Argument string: %s", full)
PrintToServer("Argument count: %d", args)
for (new i=1; i<=args; i++)
{
GetCmdArg(i, arg, sizeof(arg))
PrintToServer("Argument %d: %s", i, arg)
}
}
</pawn>

==Blocking Server Commands==
Let's say we wanted to disable the "kickid" command on the server. There's no real good reason to do this, but for example's sake:
<pawn>
public OnPluginStart()
{
RegServerCmd("kickid", Command_KickId)
}

public Action:Command_Kickid(args)
{
return Plugin_Handled
}
</pawn>

=Console Commands=
Unlike server commands, console commands can be triggered by either the server or the client, so the callback function receives a client index as well as the argument count. If the server fired the command, the client index will be 0.

When returning the <tt>Action</tt> from the callback, the following effects will happen:
*<tt>Plugin_Continue</tt>: The original functionality of the command (if any) will still be processed. If there was no original functionality, the client will receive "Unknown command" in their console.
*<tt>Plugin_Handled</tt>: The original functionality of the command (if any) will be blocked. If there was no functionality originally, this prevents clients from seeing "Unknown command" in their console.
*<tt>Plugin_Stop</tt>: Same as <tt>Plugin_Handled</tt>, except that this will be the last hook called.

Note that, unlike AMX Mod X, SourceMod does not allow you to register command filters. I.e., there is no equivalent to this notation:
<pawn>register_clcmd("say /ff", "Command_SayFF");</pawn>

This notation was removed to make our internal code simpler and faster. Writing the same functionality is easy, and demonstrated below.

==Adding Commands==
Adding client commands is very simple. Let's port our earlier testing command to display information about the client as well.

<pawn>public OnPluginStart()
{
RegConsoleCmd("test_command", Command_Test)
}

public Action:Command_Test(client, args)
{
new String:arg[128]
new String:full[256]

GetCmdArgString(full, sizeof(full))

if (client)
{
new String:name[32]
GetClientName(client, name, sizeof(name))
PrintToServer("Command from client: %s", name);
} else {
PrintToServer("Command from server.");
}

PrintToServer("Argument string: %s", full)
PrintToServer("Argument count: %d", args)
for (new i=1; i<=args; i++)
{
GetCmdArg(i, arg, sizeof(arg))
PrintToServer("Argument %d: %s", i, arg)
}
}</pawn>

==Hooking Commands==
A common example is hooking the say command. Let's say we want to tell players whether FF is enabled when they say '/ff' in game.

Before we implement this, a common point of confusion with the 'say' command is that Half-Life 2 (and Half-Life 1), by default, send it with the text in one big quoted string. This means if you say "I like hot dogs," your command will be broken down as such:
*Argument string: "I like hot dogs"
*Argument count: 1
*Argument #1: I like hot dogs

However, if a player types this in their console: <tt>say I like yams</tt>, it will be broken up as:
*Argument string: I like yams
*Argument count: 3
*Argument #1: I
*Argument #2: like
*Argument #3: yams

Thus, to take into account both of these situations, we are going to use <tt>GetCmdArgString</tt> and manually parse the input.

<pawn>new Handle:ff = INVALID_HANDLE

public OnPluginStart()
{
AddCommandListener(Command_Say, "say")
AddCommandListener(Command_Say, "say2")
AddCommandListener(Command_Say, "say_team")

ff = FindConVar("mp_friendlyfire")
}

public Action:Command_Say(client, const String:command[], argc)
{
decl String:text[192]
new startidx = 0
if (GetCmdArgString(text, sizeof(text)) < 1)
{
return Plugin_Continue
}

if (text[strlen(text)-1] == '"')
{
text[strlen(text)-1] = '\0'
startidx = 1
}

if (strcmp(command, "say2", false) == 0)
startidx += 4

if (strcmp(text[startidx], "ff", false) == 0)
{
if (ff != INVALID_HANDLE)
{
if (GetConVarBool(ff))
{
PrintToChat(client, "Friendly fire is enabled.")
} else {
PrintToChat(client, "Friendly fire is disabled.")
}
/* Block the client's messsage from broadcasting */
return Plugin_Handled
}
}

/* Let say continue normally */
return Plugin_Continue
}</pawn>

==Creating Admin Commands==
Let's create a simple admin command which kicks another player by their full name.

<pawn>public OnPluginStart()
{
RegAdminCmd("admin_kick",
Command_Kick,
ADMFLAG_KICK,
"Kicks a player by name")
}

public Action:Command_Kick(client, args)
{
if (args < 1)
{
PrintToConsole(client, "Usage: admin_kick <name>")
return Plugin_Handled
}

new String:name[32], target = -1
GetCmdArg(1, name, sizeof(name))

for (new i=1; i<=MaxClients; i++)
{
if (!IsClientConnected(i))
{
continue
}
decl String:other[32]
GetClientName(i, other, sizeof(other))
if (StrEqual(name, other))
{
target = i
}
}

if (target == -1)
{
PrintToConsole(client, "Could not find any player with the name: \"%s\"", name)
return Plugin_Handled
}

ServerCommand("kickid %d", GetClientUserId(target));

return Plugin_Handled
}</pawn>

==Immunity==
In our previous example, we did not take immunity into account. Immunity is a much more complex system in SourceMod than it was in AMX Mod X, and there is no simple flag to denote its permissions. Instead, two functions are provided:
*<tt>CanAdminTarget</tt>: Tests raw AdminId values for immunity.
*<tt>CanUserTarget</tt>: Tests in-game clients for immunity.

While immunity is generally tested ''player versus player'', it is possible you might want to check for immunity and not have a targetting client. While there is no convenience function for this yet, a good idea might be to check for either ''default'' or ''global'' immunity on the player's groups (these can be user-defined for non-player targeted scenarios).

When checking for immunity, the following heuristics are performed in this exact order:
<ol><li>If the targeting AdminId is <tt>INVALID_ADMIN_ID</tt>, targeting fails.</li>
<li>If the targetted AdminId is <tt>INVALID_ADMIN_ID</tt>, targeting succeeds.</li>
<li>If the targeting admin has <tt>Admin_Root</tt> (<tt>ADMFLAG_ROOT</tt>), targeting succeeds.</li>
<li>If the targetted admin has global immunity, targeting fails.</li>
<li>If the targetted admin has default immunity, and the targeting admin belongs to no groups, targeting fails.</li>
<li>If the targetted admin has specific immunity from the targeting admin via group immunities, targeting fails.</li>
<li>If no conclusion is reached via the previous steps, targeting succeeds.</li>
</ol>

So, how can we adapt our function about to use immunity?

<pawn>public Action:Command_Kick(client, args)
{
if (args < 1)
{
PrintToConsole(client, "Usage: admin_kick <name>")
return Plugin_Handled
}

new String:name[32], target = -1
GetCmdArg(1, name, sizeof(name))

for (new i=1; i<=MaxClients; i++)
{
if (!IsClientConnected(i))
{
continue
}
decl String:other[32]
GetClientName(i, other, sizeof(other))
if (StrEqual(name, other))
{
target = i
}
}

if (target == -1)
{
PrintToConsole(client, "Could not find any player with the name: \"%s\"", name)
return Plugin_Handled
}

if (!CanUserTarget(client, target))
{
PrintToConsole(client, "You cannot target this client.")
return Plugin_Handled
}

ServerCommand("kickid %d", GetClientUserId(target))

return Plugin_Handled
}</pawn>

=Client-Only Commands=
SourceMod exposes a forward that is called whenever a client executes any command string in their console, called <tt>OnClientCommand</tt>. An example of this looks like:

<pawn>public Action:OnClientCommand(client, args)
{
new String:cmd[16]
GetCmdArg(0, cmd, sizeof(cmd)); /* Get command name */

if (StrEqual(cmd, "test_command"))
{
/* Got the client command! Block it... */
return Plugin_Handled
}

return Plugin_Continue
}</pawn>

It is worth noting that not everything a client sends will be available through this command. Command registered via external sources in C++ may not be available, especially if they are created via <tt>CON_COMMAND</tt> in the game mod itself. For example, "say" is usually implemented this way, because it can be used by both clients and the server, and thus it does not channel through this forward.

=Chat Triggers=
SourceMod will automatically create chat triggers for every command you make (as of revision 900). For example, if you create a console command called "sm_megaslap," administrators will be able to type any of the following commands in <tt>say</tt>/<tt>say_team</tt> message modes:
<pre>!sm_megaslap
!megaslap
/sm_megaslap
/megaslap</pre>

SourceMod then executes this command and its arguments as if it came from the client console.
*"<tt>!</tt>" is the default ''public'' trigger (<tt>PublicChatTrigger</tt> in <tt>configs/core.cfg</tt>) and your entry will be displayed to all clients as normal.
*"<tt>/</tt>" is the default ''silent'' trigger (<tt>SilentChatTrigger</tt> in <tt>configs/core.cfg</tt>) and your entry will be blocked from being displayed.

SourceMod will only execute commands registered with <tt>RegConsoleCmd</tt> or <tt>RegAdminCmd</tt>, and only if those commands are not already provided by Half-Life 2 or the game mod. If the command is prefixed with "sm_" then the "sm_" can be omitted from the chat trigger.

Console commands which wish to support usage as a chat trigger should not use <tt>PrintTo*</tt> natives. Instead, they should use <tt>ReplyToCommand()</tt>, which will automatically print your message either as a chat message or to the client's console, depending on the source of the command.

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}