AlliedModders Wiki - User contributions [en]

User talk:Asherkin

2016-07-01T18:24:18Z

TheY4Kman:

{{Lowercase_title}}

asherkin smells like old babies.

Scripting FAQ (SourceMod)

2013-01-24T14:52:01Z

TheY4Kman:

[[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)
{
// 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.

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>

Scripting FAQ (SourceMod)

2012-08-13T02:43:33Z

TheY4Kman: yak yak yak yak yak yak yak yak yak yak yak

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

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>

File:Yak.gif

2012-08-13T02:42:52Z

TheY4Kman: yak wuz heer

yak wuz heer

Scripting FAQ (SourceMod)

2012-08-13T02:15:11Z

TheY4Kman: /* How do I find the classname of an entity? (e.g., "weapon_knife" or "prop_physics") */ Added netclass example

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

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>

Scripting FAQ (SourceMod)

2012-08-13T02:13:25Z

TheY4Kman: Added color question

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

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>

File:Left 4 Dead Colors.png

2012-08-13T01:12:13Z

TheY4Kman: Output of `PrintToChatAll ("\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8");` in Left 4 Dead. Image courtesy of antihacker (http://forums.alliedmods.net/member.php?u=47979).

Output of `PrintToChatAll ("\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8");` in Left 4 Dead.

Image courtesy of antihacker (http://forums.alliedmods.net/member.php?u=47979).

Scripting FAQ (SourceMod)

2012-08-13T00:37:49Z

TheY4Kman: Added SDKTools "unknown symbol" and "Unknown command" questions

Scripting FAQ (SourceMod)

2012-08-13T00:34:12Z

TheY4Kman: Added tag mismatch warning question

Scripting FAQ (SourceMod)

2012-08-13T00:21:44Z

TheY4Kman: Started porting Yak's FAQ's

SourceMod Profiler

2012-04-10T13:59:32Z

TheY4Kman: /* Interpreting Results */ LINKIFYING MOFO

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>[http://www.sourcemod.net/profviewer.exe profviewer.exe]</tt> tool available on [http://www.sourcemod.net/downloads.php 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]]

Writing Extensions

2011-06-18T10:38:55Z

TheY4Kman: /* Implementing */ Being more explicit

SourceMod's Extension System is a powerful way to greatly enhance the flexibility of your SourceMod plugins. You can take full advantage of SourceMod's Core, using the interfaces it provides, to create C++ plugins, plugin events, plugin native functions, and shared interfaces. Extensions can also hook into Metamod:Source.

This article goes into the details of creating a SourceMod Extension. Knowledge of C++ is required.

=SDK Structure=
First, download the [[SourceMod SDK]] from the [[SourceMod]] website. The directory structure looks like this:
*<tt>extensions</tt>
**<tt>geoip/</tt> - Source code to the GeoIP extension
**<tt>mysql/</tt> - Source code to the MySQL extension
**<tt>threader/</tt> - Source code to the Threader extension
*<tt>plugins/</tt> - Source code to all of SourceMod's plugins
**<tt>include/</tt> - The include files which document plugin API
*<tt>public/</tt> - Interface files for SourceMod's Core Interfaces
**<tt>extensions/</tt> - Interfaces that are provided by extensions
**<tt>sample_ext/</tt> - The Sample Extension SDK
**<tt>sourcepawn</tt> - The include/interface files for SourcePawn
*<tt>sourcepawn/</tt>
**<tt>compiler/</tt> - The SourcePawn Compiler

=Starting an Extension=
For simplicity, this article will assume you are using the SDK base files. These are:
*<tt>sdk/smsdk_config.h</tt> - Configuration settings (we will be editing this)
*<tt>sdk/smsdk_ext.h</tt> - Header for SDK wrappers (usually never needs to be edited)
**''Note: Sometimes, this may be updated by the SourceMod Dev Team. Using a newest version is recommended.'
*<tt>sdk/smsdk_ext.cpp</tt> - Source for SDK wrappers (usually never needs to be edited)
**''Note: Sometimes, this may be updated by the SourceMod Dev Team. Using a newest version is recommended.'
*<tt>extension.h</tt> - User file for main extension header
*<tt>extension.cpp</tt> - User file for main extension code

''The <tt>extension.*</tt> files are not technically part of the SDK. However, they are provided to give users a starting point and some documentation.''

'''Note:''' For help setting up Visual Studio, please see [[#Setting up Visual Studio|Setting up Visual Studio]].

The first step of creating your extension is to configure it. Open the <tt>smsdk_config.h</tt> file and edit each of the following defines. Use the information below to guide you.
*<tt>SMEXT_CONF_NAME</tt> - The general name for your Extension (should be short).
*<tt>SMEXT_CONF_DESCRIPTION</tt> - A short description of what your extension does.
*<tt>SMEXT_CONF_VERSION</tt> - A version number string. By convention, SourceMod uses the four set build number notation. I.e. for 1.2.3.4:
**<tt>1</tt> is the "Major" release version.
**<tt>2</tt> is the "Minor" release version.
**<tt>3</tt> is the "Maintenance" or "Revision" version.
**<tt>4</tt> is the "Build," usually an internal source control number.
*<tt>SMEXT_CONF_AUTHOR</tt> - Your name (or whoever/whatever authored the plugin).
*<tt>SMEXT_CONF_URL</tt> - The URL/homepage of this extension.
*<tt>SMEXT_CONF_LOGTAG</tt> - The logtag your extension will use for SourceMod logging. By convention, try to keep this under ten characters or so, and to make it all caps.
*<tt>SMEXT_CONF_LICENSE</tt> - Right now, the SourceMod Dev Team mandates that 3rd party extensions must be under an Open Source license. Putting a license abbreviation or very short message here is appropriate. For more information, see [[SourceMod License]].
*<tt>SMEXT_CONF_DATESTRING</tt> - You do not need to modify this.
*<tt>SMEXT_CONF_METAMOD</tt> - If your plugin requires using SourceHook or Metamod:Source, uncomment this line.

Next, you may want to change the name of the default class that <tt>extension.h</tt> declares. To do this...
<ul><li>Open <tt>extension.h</tt> and change "Sample" in this line:
<cpp>class Sample : public SDKExtension</cpp></li>
<li>Open <tt>extension.cpp</tt> and change the two lines to correspond to your new class name. You can also change the global singleton that's declared, although you cannot remove the <tt>SMEXT_LINK</tt> line (this lets SourceMod load your extension).</li>
</ul>

==Visual Studio Users==
Make sure you change the name of your <tt>.dll</tt> file. The naming convention for SourceMod extensions is <tt>name.ext.dll</tt>, where <tt>name</tt> is a short name for your extension. You are free to change this, but it is highly recommended that you keep the <tt>.ext.dll</tt> intact.

You can do this by going to <tt>Project</tt> -> <tt>Properties</tt> -> <tt>Configuration Properties</tt> -> <tt>Linker</tt> -> <tt>General</tt>. Set the <tt>Output File</tt> option appropriately.

==Linux Users==
Simply edit the <tt>Makefile</tt> and change the <tt>BINARY</tt> line near the top. Make sure you do not add any trailing spaces at the end of the name, or the build won't come out right.

You should now be able to compile a blank extension!

=Creating Native Functions=
''Main article: [[Natives (SourceMod Development)]]''

Most of the time, an extension exists to add "native functions" to the plugin system. Native functions are simply the functions that plugins can use in SourceMod. They are coded in C++ and have a short prototype declaration in an include file.

==Prototyping==
The first step to creating a native is to <tt>spec it</tt>, or <tt>prototype</tt> it. This is a simple but often time consuming process, but if you get in the habit of it, your documentation will be much better. Let's first create a very simply native. Here is a prototype for it, which we will place in <tt>sample.inc</tt>:
<pawn>/**
* Returns the square of a number.
*
* @param num Number to square.
* @return The square of num.
*/
native SquareNumber(num);</pawn>

The <tt>native</tt> keyword tells the compiler that this function exists in an outside source. The comment style is similar to [http://www.stack.nl/~dimitri/doxygen/ doxygen] or [http://java.sun.com/j2se/javadoc/ Javadoc], and is preferred by the SourceMod Development Team.

==Implementing==
Now that our function is documented, it's time to create it! Each native function is bound to a C++ function. The prototype for this function looks like:
<cpp>cell_t Function(IPluginContext *pContext, const cell_t *params);</cpp>

A quick explanation of these types:
*<tt>cell_t</tt> - This is a 32bit signed integer, the generic data type for Pawn.
*<tt>IPluginContext</tt> - This interface provides Virtual Machine functions for retrieving or modifying memory in the plugin.
*<tt>params</tt> - This is the "stack" of parameters that the plugin passed. It is an array from [0..N] where 0 contains N. This means <tt>params[0]</tt> contains the number of arguments passed to the native.
**For example, if one parameter was passed, and the parameter is 25:
***<tt>params[0]</tt> == 1
***<tt>params[1]</tt> == 25
**Even though it tells you how many parameters are passed, you do not need to verify this number. The compiler will always pass the correct number of parameters in. The only time you need to verify it is for backwards compatibility or variable parameter lists, which will be discussed later.

Now, let's write our native function:
<cpp>cell_t SquareNumber(IPluginContext *pContext, const cell_t *params)
{
cell_t number = params[1];
return number * number;
}</cpp>

==Binding==
Now, the final step is to bind our native. Natives are bound in ''native lists''. Each list must be terminated by a <tt>NULL</tt> bind. Example:
<cpp>const sp_nativeinfo_t MyNatives[] =
{
{"SquareNumber", SquareNumber},
{NULL, NULL},
};</cpp>

The first column/member is a string containing the name you've assigned to the native. The second column/member is the C++ function you're binding to. Here, both contain the same name, but it is certainly possible to bind a function to any valid Pawn function name, and likewise, you can bind one function to more than one name.

Lastly, you must tell Core about your native list. There are two places that are good to do this. Whichever you choose, you must uncomment the function in <tt>extension.h</tt> and implement it in <tt>extension.cpp</tt>.
*<tt>SDK_OnLoad</tt> - This is called when your extension is first loaded. If you do not require any outside interfaces, it is safe to add natives here.
*<tt>SDK_OnAllLoaded</tt> - This is called when all extensions have been loaded. This is generally a better place to add natives.

Let's say we choose <tt>SDK_OnAllLoaded</tt>, we'd then have code like this:
<cpp>void Sample::SDK_OnAllLoaded()
{
sharesys->AddNatives(myself, MyNatives);
}</cpp>
''Note: <tt>myself</tt> is a global variable declared in the SDK. It is a pointer that identifies your extension.''

For more information on writing natives, see [[Natives (SourceMod Development)]].

=Creating Events/Forwards=
Events are an integral part to SourceMod. An Event is formally called a ''Forward''. Forwards are functions inside a plugin which are not called by the plugin itself, but are triggered from an external source. For example, <tt>OnClientConnect</tt> is a forward which is triggered when a player connects to a server.

There are two major types of forwards:
*'''Managed''': This forward is global and has a name. To use this forward, the function must be declared as <tt>public</tt> inside the user's script. Any plugin having this public function will receive the event.
*'''Unmanaged''': This forward is private in nature. For example, the <tt>HookUserMessage</tt> native lets users specify a function to be called when a specific user message is sent. This is done with an unmanaged forward, and adding functions to this forward is not automatic. In general, function calls for unmanaged forwards are not public, although they can be.

''Note: To enable the Forward interface, you must uncomment the definition <tt>SMEXT_ENABLE_FORWARDSYS</tt> in smsdk_config.h.''
==Managed Forwards==
Let's say we want to create a forward that will be called when a player uses say chat. For simplicity, let's assume you already have a function that tells you when a player says say chat. We will just be creating the forward for it.

As we did before, first let's prototype our global forward. In our include file, we add this:
<pawn>/**
* @brief Called whenever a client says something in chat.
*
* @param client Index of the client.
* @param text String containing the say text.
* @return Pl_Handled to block text from printing, Pl_Continue otherwise.
*/
forward ResultType:OnPlayerSayChat(client, const String:text[]);</pawn>

The <tt>forward</tt> keyword tells the compiler that any function having this name must be declared exactly the same. In a plugin, this would

The next step is to declare your forward somewhere at the top of your <tt>extension.cpp</tt> file. This will look like:
<cpp>IForward *g_pSayChat = NULL</cpp>

Next, re-using our code from above, let's create this forward in <tt>SDK_OnAllLoaded</tt>:
<cpp>void Sample::SDK_OnAllLoaded()
{
sharesys->AddNatives(myself, MyNatives);
g_pSayChat = forwards->CreateForward("OnPlayerSayChat", ET_Event, 2, NULL, Param_Cell, Param_String);
}</cpp>

Explanation of parameters:
*<tt>"OnPlayerSayChat"</tt> - The name of our forward.
*<tt>ET_Event</tt> - Since forwards can execute multiple functions in multiple scripts, this is one of the ways of specifying what to do with the return value of each function. <tt>ET_Event</tt> means "return the highest value, do not allow stops." A stop refers to <tt>Pl_Stop</tt>, which lets a plugin block the rest of the event chain.
*<tt>2</tt> - This is the number of parameters our forward will have.
*<tt>NULL</tt> - Not used in our example. This lets you pass parameters by array rather than variable arguments.
*<tt>Param_Cell</tt> - The first parameter is a cell (integer).
*<tt>Param_String</tt> - The second parameter is a string.

Now, we write a quick function in our module to call this forward:
<cpp>/** Fires the say chat event in plugins. Returns true to allow the text, false to block. */
bool FireChatEvent(int client, const char *text)
{
if (!g_pSayChat)
{
return true;
}

cell_t result = 0;
g_pSayChat->PushCell(client);
g_pSayChat->PushString(text);
g_pSayChat->Execute(&result);

if (result == Pl_Handled)
{
return false;
}

return true;
}</cpp>

As you can see, this was pretty simple. Each parameter is "pushed" one at a time, in ascending order. First we push the client index as a cell, then the text as a string. Once done, we execute, and the value will be returned by reference.

Lastly, there is a caveat. Unlike natives, SourceMod does not automatically clean up forwards for us when are done. We have to make sure we destroy them. Uncomment <tt>SDK_OnUnload</tt> from <tt>extension.h</tt> and implement it like so:
<cpp>void Sample::SDK_OnUnload()
{
forwards->ReleaseForward(g_pSayChat);
}</cpp>

==Unmanaged Forwards==
Now things get a bit more complicated. However, unmanaged forwards are essentially the same -- they just give you more flexibility. Let's consider the managed example with a new twist. We want to let users add and remove hooks from their plugins, rather than having one global forward. The standard way to do this is with ''function IDs''.

Example prototype:
<pawn>funcenum SayChatHook
{
forward(client, const String:text[]);
}

native AddSayChatHook(SayChatHook:hook);
native RemoveSayChatHook(SayChatHook:hook);</pawn>

The <tt>funcenum</tt> syntax lets you define all the valid prototypes for your hook. In this example, the only valid method is a function declared like this (only MyHook can be changed):
<pawn>MyHook(client, const String:text[])</pawn>

How do we make such a beast? The first step is setting up our forward.
<cpp>IChangeableForward *g_pSayChat = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
g_pSayChat = forwards->CreateForwardEx(NULL, ET_Hook, 2, NULL, Param_Cell, Param_String);
}</cpp>

Notice two big differences. We now use <tt>IChangeableForward</tt> instead of <tt>IForward</tt>, and we use <tt>CreateForwardEx</tt> instead. The initial first parameter specifies a name for our forward - we're going to ignore this.

Now, we need to create our natives. These will be fairly simple:
<cpp>cell_t AddSayChatHook(IPluginContext *pContext, const cell_t *params)
{
g_pSayChat->AddFunction(pContext, static_cast<funcid_t>(params[1]));
return 1;
}

cell_t RemoveSayChatHook(IPluginContext *pContext, const cell_t *params)
{
IPluginFunction *pFunction = pContext->GetFunctionById(static_cast<funcid_t>(params[1]));
g_pSayChat->RemoveFunction(pFunction);
return 1;
}</cpp>
''Note: These natives must be added -- that step is removed here and explained earlier.''

You do not need to worry about a plugin unloading - Core will automatically remove the functions for you. Since an <tt>IChangeableForward</tt> is also an <tt>IForward</tt>, the <tt>FireChatEvent</tt> function from earlier does not need to change. We're done!

==Creating Interfaces==
Do you want your extension to share an interface? If so, first you should create an ''interface file''. This file should contain everything your interface needs - this way other authors can easily reference it. Your interface must inherit the <tt>SMInterface</tt> class. It must also declare two global macros that uniquely identify your interface. It must also implement two functions: <tt>GetInterfaceName</tt> and <tt>GetInterfaceVersion</tt>.

The two defines must start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt> respectively. The first must be a string and the second must be an unsigned integer. This integer represents your interface's version number. While you are free to use it however you please, by default it should be linearly increased. If you make breaking changes or change the versioning scheme, you must overload the <tt>IsVersionCompat</tt> function in <tt>SMInterface</tt>.

Example:
<cpp>#ifndef _INCLUDE_MYINTERFACE_FILE_H_
#define _INCLUDE_MYINTERFACE_FILE_H_

#include <IShareSys.h>

#define SMINTERFACE_MYINTERFACE_NAME "IMyInterface"
#define SMINTERFACE_MYINTERFACE_VERSION 1

class IMyInterface : public SourceMod::SMInterface
{
public:
virtual const char *GetInterfaceName()
{
return SMINTERFACE_MYINTERFACE_NAME;
}
virtual unsigned int GetInterfaceVersion()
{
return SMINTERFACE_MYINTERFACE_VERSION;
}
public:
/**
* @brief This function does nothing.
*/
virtual void DoNothingAtAll() =0;
};

#endif //_INCLUDE_MYINTERFACE_FILE_H_</cpp>

Notice, of course, that our interface is ''pure virtual''. This means it must be implemented in the extension. Assuming you know C++, this should be fairly straight forward, so let's skip right to how to add this interface to the SourceMod shared system:
<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
sharesys->AddInterface(myself, &g_MyInterface);
return true;
}</cpp>
''Note: We do this in <tt>SDK_OnLoad()</tT> instead of <tt>SDK_OnAllLoaded()</tt>. Otherwise, an extension might try to search for your interface during <tt>SDK_OnAllLoaded()</tt>, and it might fail depending on the load order.''

That simple? Yup! Now other extensions can use your interface.

=Using Interfaces/Other Extensions=
There are a variety of interfaces that are available, but not loaded by default in the Extension SDK. These interfaces can be retrieved and used in your extension.

==Core Interfaces==
If they are provided by Core, getting them is very simple. Many interfaces can simply be uncommented in <tt>smsdk_config.h</tt> and they will become usable. See the "Available Interfaces" list below for the exposure list.

Otherwise, most of the <tt>.h</tt> interface files in the root of the <tt>public</tt> folder in the SDK are Core interfaces. For example, code to use the IPluginManager interface might look like this:
<cpp>#include <IPluginSys.h>

IPluginManager *g_pPlugins = NULL;

bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
SM_GET_IFACE(PLUGINSYSTEM, g_pPlugins);
return true;
}</cpp>

Where did we get <tt>PLUGINSYSTEM</tt> from? Observe the two lines in <tt>IPluginSys.h</tt>:
<cpp>#define SMINTERFACE_PLUGINSYSTEM_NAME "IPluginManager"
#define SMINTERFACE_PLUGINSYSTEM_VERSION 1</cpp>

The <tt>SM_GET_IFACE</tt> macro uses the text in between the <tt>SMINTERFACE_</tt> and the <tt>_NAME</tt> characters. It also uses the version for compatibility checking. If it can't find the interface, it automatically prints to the error buffer and returns false.

===Default Interfaces===
There are interfaces which are grabbed by the Extension SDK by default. You do not need to query for them on load, or even check if they are valid or not. They are:
*<tt>IShareSys</tt> - Exposed as <tt>sharesys</tt>, found in <tt>IShareSys.h</tt>
*<tt>HANDLESYSTEM</tt> - Exposed as <tt>handlesys</tt>, found in <tt>IHandleSys.h</tt>
*<tt>SOURCEMOD</tt> - Exposed as <tt>g_pSM</tt>, found in <tt>ISourceMod.h</tt>
*<tt>FORWARDMANAGER</tt> - Exposed as <tt>forwards</tt>, found in <tt>IForwardSys.h</tt>

===Available Interfaces===
*<tt>SMEXT_ENABLE_FORWARDSYS</tt>: <tt>forwards</tt>
*<tt>SMEXT_ENABLE_HANDLESYS</tt>: <tt>handlesys</tt>
*<tt>SMEXT_ENABLE_PLAYERHELPERS</tt>: <tt>playerhelpers</tt>
*<tt>SMEXT_ENABLE_DBMANAGER</tt>: <tt>dbi</tt>
*<tt>SMEXT_ENABLE_GAMECONF</tt>: <tt>gameconfs</tt>
*<tt>SMEXT_ENABLE_MEMUTILS</tt>: <tt>memutils</tt>
*<tt>SMEXT_ENABLE_GAMEHELPERS</tt>: <tt>gamehelpers</tt>
*<tt>SMEXT_ENABLE_TIMERSYS</tt>: <tt>timersys</tt>
*<tt>SMEXT_ENABLE_THREADER</tt>: <tt>threader</tt>

==External Interfaces==
The situation changes if your extension requires ''another extension'', since extensions may load in a completely random order. The first step is to mark the other extension as a dependency. Let's say you want to use the <tt>IThreader.h</tt> interfaces from <tt>threader.ext.dll</tt>. First, we declare it as such:

<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
sharesys->AddDependency(myself, "thread.ext", true, true);
return true;
}</cpp>

The two boolean parameters to <tt>AddDependency</tt> mean, respectively: "try to automatically load this extension" and "this extension cannot work without the dependency."

Second, we query for the interface in <tt>SDK_OnAllLoaded</tt>. Since we don't know when <tt>thread.ext</tt> will actually be loaded, we have to wait until everything is definitely loaded.
<cpp>IThreader *g_pThreader = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
SM_GET_LATE_IFACE(THREADER, g_pThreader);
}</cpp>

Third, we need to find a way to fail if this interface was never found. The way to do this is by uncommenting <tt>QueryRunning</tt> from <tt>extension.h</tt> and implementing it:
<cpp>bool Sample::QueryRunning(char *error, size_t err_max)
{
SM_CHECK_IFACE(THREADER, g_pThreader);
return true;
}</cpp>

When SourceMod queries your extension, the macro above will either validate the pointer or return false. If it returns false, SourceMod marks your extension as failed.

==Caveats==
===NULL Interfaces===
There are a few ways that external interfaces can make your code complicated. The first is simple but a common oversight. Don't assume interfaces will be okay. For example, say we want to create a thread once we get the <tt>IThreader</tt> interface. Our code should something like this:

<cpp>void Sample::SDK_OnAllLoaded()
{
SM_GET_IFACE(THREADER, g_pThreader);

if (QueryRunning(NULL, 0))
{
g_pThreader->MakeThread(/* stuff */);
}
}</cpp>

Note that we ''query ourself'' in order to find if it's safe to continue executing code. We could also have simply checked if <tt>g_pThreader</tt> is <tt>NULL</tt>, but self-querying has a bonus: if your extension continues to do things like hook events or add listeners, you will be preventing your extension from entirely initializing itself while one interface is bad. Always make sure you have sanity checks like this where needed.

===Dynamic Unloading===
The second major caveat is that extensions can be dynamically unloaded. If you specified yourself as having a dependency and that each dependency is required, you will have no problem. Your extension will be unloaded before the interface is removed, and you can clean up memory/hooks in your <tt>SDK_OnUnload()</tt> code. There are two situations where this is a different story.

====Optional Interfaces====
The first situation is if you are not requiring an extension that contains an interface. Now, when the extension unloads, your extension will not be unloaded first. This creates a small problem, as you must clean up without being unloaded. There are two functions you can implement in your extension class to resolve this, both documented in <tt>IExtensionSys.h</tt>:
*<tt>QueryInterfaceDrop</tt> - Allows you to request unloading when a specific interface is unloaded. This is the default behavior for all interfaces. If you want to block this functionality, continue reading.
*<tt>NotifyInterfaceDrop</tt> - This is called when an interface is dropped. If your plugin will not be unloaded, you can use this to clean up any resources on a specific interface being removed.

====Circular Dependencies====
The second situation is a bit more complicated. It is possible for two extensions to have circular dependencies. For example:
*Extension "A" requires extension "B."
*Extension "B" requires extension "A."

If either extension is unloaded, the opposite extension is unloaded normally. The first extension then receives the interface drop callbacks. In this situation, it is essential that the <tt>NotifyInterfaceDrop</tt> function be implemented and used with the circular interface. Otherwise, you risk crashing when your extension unloads (or at the very least, leaking memory). Since the actual drop order is undefined, it means both extensions must implement this function to be safe.

=Automatic Loading=
There are two types of automatic loading: Dynamic and Global. Dynamic loading means your extension is only loaded when a plugin requires it. Global loading means your extension loads no matter what.

==Dynamic Autoloading==
Dynamic loading requires that you create an include file for plugins. Plugins that include your file will automatically load your extension. This requires implementing the <tt>Extension</tt> structure found in <tt>core.inc</tt>. You must expose the structure as <tt>public</tt>, and the name must start with "<tt>__ext_</tt>".

<pawn>/**
* Do not edit below this line!
*/
public Extension:__ext_geoip =
{
name = "GeoIP",
file = "geoip.ext",
#if defined AUTOLOAD_EXTENSIONS
autoload = 1,
#else
autoload = 0,
#endif
#if defined REQUIRE_EXTENSIONS
required = 1,
#else
required = 0,
#endif
};
</pawn>

Explanations:
*name: The name of your module as written in <tt>SMEXT_CONF_NAME</tt>.
*file: The platform-inspecific portion of your extension's file name.
*autoload: Specifies that your module should always dynamically autoload by default. You can tweak this to either never autoload or always autoload (without letting the user toggle).
*required: Specifies whether or not this extension is '''required''' by your plugin. If for some reason your extension fails to load (or is not found), the plugin will also fail to load. This is changeable if you wish to override the default behavior.

You can copy and paste this example, but remember to modify the following portions:
*__ext_geoip: Change the "geoip" portion to your own unique variable name.
*"GeoIP: Change the GeoIP portion to your extension's name. This should match the name you chose as <tt>SMEXT_CONF_NAME</tt>.
*"geoip.ext": Change this to your extension's file name, without the .dll/.so portion.

==Global Autoloading==
To have your extension always autoload, you must create a ''.autoload'' file in the <tt>extensions</tt> folder. For example, to have the <tt>threader.ext.dll</tt> or <tt>threader.ext.so</tt> extensions autoload, you'd create the following file in <tt>extensions</tt>: <tt>threader.autoload</tt>.

A few notes:
*This only works for extensions using the .ext.<platform> convention. SourceMod cuts off the ".autoload" portion of the file, then adds on ".ext.dll" or ".ext.so" which will not work on custom files.
*The file does not need to contain anything, it simply needs to exist.

=Conventions=

==Designing API/Natives==
*Start interface names with the capital letter 'I'.
*Use a consistent naming convention. SourceMod uses [http://msdn2.microsoft.com/en-us/library/ms229002.aspx Microsoft/Pascal] naming. Avoid Java/Camel casing for both API and natives.
*When exposing interfaces, make sure your exposure defines start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt>

==External Naming==
*Logtags (<tt>SMEXT_CONF_LOGTAG</tt>) should be short names (under 10 characters or so) in all capital letters.
*Your extension file name should never have <tt>_i486</tt> or other unnecessary platform-specific notations in its name.
*Your extension file name should always end in <tt>.ext.so</tt> or <tt>.ext.dll</tt> depending on the platform. The <tt>.ext.</tt> is SourceMod convention.

=Setting up Visual Studio=
==Paths==
'''Visual Studio 2003''': Tools -> Options -> Projects, VC++ Directories

'''Visual Studio 2005''': Tools -> Options -> Projects and Solutions -> VC++ Directories

===Include Paths===
*SourceMod only:
**sdk\public\extensions
**sdk\public\sourcepawn
**sdk\public
*SourceMM (Note that sourcemm might be 'trunk' for you):
**sourcemm\core
**sourcemm\core\sourcehook
*HL2SDK:
**game\shared
**public\vstdlib
**public\tier1
**public\tier0
**public\engine
**public
**dlls

===Link Paths===
*HL2SDK:
**lib\public for version 2005
**lib-vc7\public for version 2003

==Compiler Options==
Note: These options are set by default in the sample Extension SDK. 
Note: These options should be set for every build (Release/Debug/others).

For VS 2005, goto Project->Properties.

*General
**<tt>Character Set</tt>: '''Use Multi-Byte Character Set'''
*C/C++
**General
***<tt>Detect 64-bit Portability Issues</tt>: '''No'''
**Preprocessor
***<tt>Preprocessor Defines</tt>: Add <tt>_CRT_SECURE_NO_DEPRECATE</tt>, <tt>_CRT_NONSTDC_NO_DEPRECATE</tt>, <tt>SOURCEMOD_BUILD</tt> and <tt>WIN32</tt>
**Code Generation
***<tt>Runtime Library</tt>: Multi-threaded or /MT (for Release), Multi-threaded Debug or /MTd (for Debug)
*Linker
**General
***<tt>Output File</tt>: Change <tt>$(ProjectName)</tt> to <tt>$(ProjectName).ext</tt>, or use your own custom string.
**Input
***<tt>Additional Dependencies</tt>: <tt>tier0.lib tier1.lib vstdlib.lib</tt> (for SourceMM attached extensions only)

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

Introduction to SourcePawn (legacy syntax)

2009-09-28T20:38:54Z

TheY4Kman: /* Notes */ decl can initialize strings

This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a "scripting" language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].

This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics.

=Non-Programmer Intro=
This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.

==Symbols/Keywords==
A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive (unlike PHP, where sometimes they are not). Symbols do not start with any special character, though they must start with a letter.

There are a few reserved symbols that have special meaning. For example, <tt>if</tt>, <tt>for</tt>, and <tt>return</tt> are special constructs in the language that will explained later. They cannot be used as symbol names.

==Variables==
There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable "a" could hold the number "2", "16", "0", et cetera. Variables are created for storage space throughout a program. Variables must be declared before being used, using the "new" keyword. Data is assigned to variables using the equal sign (=). Example:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

In SourcePawn, variables have two types, which will be explained in more detail further on.
*Cells (arbitrary numerical data), as shown above.
*Strings (a series of text characters)

==Functions==
The next important concept is '''functions'''. Functions are symbols or names that perform an action. That means when you activate them, they carry out a specific sequence of code. There are a few types of functions, but every function is activated the same way. "Calling a function" is the term for invoking a function's action. Function calls are constructed like this:
<pawn>function(<parameters>)</pawn>

Examples:

<pawn>show(56); //Activates "show" function, and gives the number 56 to it
show(); //Activates "show" function with no data, blank
show(a); //Activates "show" function, gives a variable's contents as data
</pawn>

Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a "reasonable" limit of 32 in SourceMod). Parameters will be explained further in the article.

==Comments==
Note any text that appears after a "//" is considered a "comment" and is not actual code. There are two comment styles:
*<tt>//</tt> - Double slash, everything following on that line is ignored.
*<tt>/* */</tt> - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.

==Block Coding==
The next concept is block coding. You can group code into "blocks" separated by { and }. This effectively makes one large block of code act as one statement. For example:

<pawn>{
here;
is;
some;
code;
}</pawn>

Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.

=Language Paradigms=
Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.
*'''Pawn is not typed.''' Pawn only has one data type, the '''cell'''. This will be explained in detail later. [Below it says that there are two types: cell and string.]
*'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.
*'''Pawn is not object oriented.''' Pawn is procedural, and relies on subroutines. It also does not have C structs.
*'''Pawn is not functional.''' Pawn is procedural, and does not support lambda functions or late binding or anything else you might find in a very high-level language, like Python or Ruby.
*'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe.
*'''Pawn is not interpreted.''' Well, it "sort of" is. It gets interpreted at a very low level. You must run your code through a compiler, which produces a binary. This binary will work on any platform that the host application uses. This speeds up loading time and lets you check errors easier.

These language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.

=Variables=
In Pawn there are two variable types: the '''cell''' and the '''String'''. A cell can store 32 bits of numerical data. A String is a sequential/flat list of UTF-8 text characters.

A '''cell''' has no inherent type, however, cells can be '''tagged'''. A tag lets you enforce where certain cells can be used. The default tags are:
*(nothing), or '''_''' - No tag. Usually used for whole numbers ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - Used for floating point (fractional) numbers.
*'''bool''' - Used for storing either '''true''' or '''false'''.

Strings are different and will be explained in the next sections.

==Declaration==
Examples of different valid variable declarations:
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Works because 0 is false
</pawn>

Invalid variable usage:
<pawn>
new a = 5.0; //Tag mismatch. 5.0 is tagged as Float
new Float:b = 5; //Tag mismatch. 5 is not tagged.
</pawn>

If a variable is not assigned upon declaration, it will be set to 0. For example:
<pawn>
new a; //Set to 0
new Float:b; //Set to 0.0
new bool:c; //Set to false
</pawn>

==Assignment==
Variables can be re-assigned data after they are created. For example:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

=Arrays=
An array is a sequence of data in a sequential list. Arrays are useful for storing multiple pieces of data in one variable, and often greatly simplify many tasks.

==Declaration==
An array is declared using brackets. Some examples of arrays:
<pawn>
new players[32]; //Stores 32 cells (numbers)
new Float:origin[3]; //Stores 3 floating point numbers
</pawn>

By default, arrays are initialized to 0. You can assign them different default values, however:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Stores 1, 2, 3, 4, 5 in the cells.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Stores 1.0, 2.0, 3.0 in the cells.
</pawn>

You can leave out the array size if you're going to pre-assign data to it. For example:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

The compiler will automatically deduce that you intended an array of size 5.

==Usage==
Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.

For example, here is an example of the above code using indexes:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.

To use an incorrect index will cause an error. For example:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

This may look correct, but 5 is not a valid index. The highest valid index is 4.

You can use any expression as an index. For example:
<pawn>new a, numbers[5];

a = 1; //Set a = 1
numbers[a] = 4; //Set numbers[1] = 4
numbers[numbers[a]] = 2; //Set numbers[4] = 2
</pawn>

Expressions will be discussed in depth later in the article.

=Strings=
Strings are a convenient method of storing text. The characters are stored in an array. The string is terminated by a '''null terminator''', or a 0. Without a null terminator, Pawn would not know where to stop reading the string. All strings are UTF-8 in SourcePawn.

Notice that Strings are a combination of arrays and cells. Unlike other languages, this means you must know how much space a string will use in advance. That is, strings are not dynamic. They can only grow to the space you allocate for them.

''Note for experts: They're not actually cells. SourcePawn uses 8-bit storage for String arrays as an optimization. This is what makes String a type and not a tag.''

==Usage==
Strings are declared almost equivalently to arrays. For example:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

These are equivalent to doing:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.

Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.

==Characters==
A character of text can be used in either a String or a cell. For example:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Set clam to 'D'
text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'
clam = text[0]; //Set clam to 'A'
text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'
</pawn>

What you can't do is mix character arrays with strings. The internal storage is different. For example:
<pawn>
new clams[] = "Clams"; //Invalid, needs String: type
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Valid, but NOT A STRING.
</pawn>

=Functions=
Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.

There are two types of ways functions are called:
*'''direct call''' - You specifically call a function in your code.
*'''callback''' - The application calls a function in your code, as if it were an event trigger.

There are five types of functions:
*'''native''': A direct, internal function provided by the application.
*'''public''': A callback function that is visible to the application and other scripts.
*'''normal''': A normal function that only you can call.
*'''stock''': A normal function provided by an include file. If unused, it won't be compiled.
*'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.

All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.

==Declaration==
Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''prototype''' and the '''body'''. The prototype contains the name of your function and the parameters it will accept. The body is the contents of its code.

Example of a function:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

This is a simple function. The prototype is this line:
<pawn>AddTwoNumbers(first, second)</pawn>

Broken down, it means:
*<tt>AddTwoNumbers</tt> - Name of the function.
*<tt>first</tt> - Name of the first parameter, which is a simple cell.
*<tt>second</tt> - Name of the second parameter, which is a simple cell.

The body is a simple block of code. It creates a new variable, called <tt>sum</tt>, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the <tt>return</tt> statement, which tells the function to end and return a value to the caller of the function. All functions ''return a cell'' upon completion. That means, for example:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

The above code will assign the number 9 to sum. The function adds the two inputs, and the sum is given as the '''return value'''. If a function has no return statement or does not place a value in the return statement, it returns 0 by default.

A function can accept any type of input. It can return any cell, but not arrays or strings. Example:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Note that if in the above function, you returned a non-Float, you would get a tag mismatch.''

You can, of course, pass variables to functions:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

This code would not change the value of <tt>a</tt>. That is because a copy of the value in <tt>a</tt> is passed instead of <tt>a</tt> itself.

More examples of functions will be provided throughout the article.

==Publics==
Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

To implement and receive these two events, you would write functions as such:

<pawn>public OnPluginStart()
{
/* Code here */
}

public OnClientDisconnected(client)
{
/* Code here */
}</pawn>

The '''public''' keyword exposes the function publicly, and allows the parent application to directly call the function.

==Natives==
Natives are builtin functions provided by the application. You can call them as if they were a normal function. For example, SourceMod has the following function:

<pawn>native FloatRound(Float:num);</pawn>

It can be called like so:
<pawn>new num = FloatRound(5.2); //Results in num = 5</pawn>

==Array Parameters==
You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:
<pawn>example[2] = 29;</pawn>

This is only possible because the array can be directly modified. To prevent an array from being modified, you can mark it as <tt>const</tt>. This will raise an error on code that attempts to modify it. For example:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Won't compile
}</pawn>

It is a good idea to use <tt>const</tt> in array parameters if you know the array won't be modified; this can prevent coding mistakes.

=Expressions=
Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict "order of operations." They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.

The simplest expression is a single number. For example:
<pawn>
0; //Returns the number 0
(0); //Returns the number 0 as well
</pawn>

Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.

The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:
<pawn>
5 + 6; //Evaluates to 11
5 * 6 + 3; //Evaluates to 33
5 * (6 + 3); //Evaluates to 45
5.0 + 2.3; //Evaluates to 7.3
(5 * 6) % 7; //Modulo operator, evaluates to 2
(5 + 3) / 2 * 4 - 9; //Evaluates to 7
</pawn>

As noted, expressions can contain variables, or even functions:
<pawn>
new a = 5 * 6;
new b = a * 3; //Evaluates to 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.

==Operators==
There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:
<pawn>new a = 5;

a = a + 5;</pawn>

Can be rewritten as:
<pawn>new a = 5;
a += 5;</pawn>

This is true of the following operators in Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Additionally, there are increment/decrement operators:
<pawn>a = a + 1;
a = a - 1;</pawn>

Can be simplified as:
<pawn>a++;
a--;</pawn>

As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.

* ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.
* ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.

In other words, <tt>a++</tt> evaluates to the value of <tt>a</tt> while <tt>++a</tt> evaluates to the value of <tt>a + 1</tt>. In both cases <tt>a</tt> is incremented by <tt>1</tt>.

For example:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

In (1) <tt>b</tt> is assigned <tt>a</tt>'s ''old'' value ''before'' it is incremented to <tt>6</tt>, but in (2) <tt>c</tt> is assigned <tt>a</tt>'s ''new'' value ''after'' it is incremented to <tt>7</tt>.

==Comparison Operators==
There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):
*<tt>a == b</tt> - True if a and b have the same value.
*<tt>a != b</tt> - True if a and b have different values.
*<tt>a > b</tt> - True if a is greater than b
*<tt>a >= b</tt> - True if a is greater than or equal to b
*<tt>a < b</tt> - True if a is less than b
*<tt>a <= b</tt> - True if a is less than or equal to b

For example:
<pawn>
(1 != 3); //Evaluates to true because 1 is not equal to 3.
(3 + 3 == 6); //Evaluates to true because 3+3 is 6.
(5 - 2 >= 4); //Evaluates to false because 3 is less than 4.
</pawn>

Note that these operators do not work on arrays or strings. That is, you cannot compare either using <tt>==</tt>.

==Truth Operators==
These truth values can be combined using three boolean operators:
*<tt>a && b</tt> - True if both a and b are true. False if a or b (or both) is false.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - True if a or b (or both) is true. False if both a and b are false.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - True if a is false. False if a is true.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

For example:
<pawn>
(1 || 0); //Evaluates to true because the expression 1 is true
(1 && 0); //Evaluates to false because the expression 0 is false
(!1 || 0); //Evaluates to false because !1 is false.
</pawn>

==Left/Right Values==
Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.

For example:
<pawn>
new a = 5;</pawn>

In this example <tt>a</tt> is an l-value and <tt>5</tt> is an r-value.

The rules:
*'''Expressions are never l-values'''.
*'''Variables are both l-values and r-values'''.

=Conditionals=
Conditional statements let you only run code if a certain condition is matched.

==If Statements==
If statements test one or more conditions. For example:

<pawn>
if (a == 5)
{
/* Code that will run if the expression was true */
}</pawn>

They can be extended to handle more cases as well:
<pawn>
if (a == 5)
{
/* Code */
}
else if (a == 6)
{
/* Code */
}
else if (a == 7)
{
/* Code */
}</pawn>

You can also handle the case of no expression being matched. For example:
<pawn>
if (a == 5)
{
/* Code */
}
else
{
/* Code that will run if no expressions were true */
}</pawn>

==Switch Statements==
Switch statements are restricted if statements. They test one expression for a series of possible values. For example:

<pawn>
switch (a)
{
case 5:
{
/* code */
}
case 6:
{
/* code */
}
case 7:
{
/* code */
}
case 8, 9, 10:
{
/* Code */
}
default:
{
/* will run if no case matched */
}
}</pawn>

Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.

=Loops=
Loops allow you to conveniently repeat a block of code while a given condition remains true.

==For Loops==
For loops are loops which have four parts:
*The '''initialization''' statement - run once before the first loop.
*The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.
*The '''iteration''' statement - run after each loop.
*The '''body''' block - run each time the '''condition''' statement evaluates to true.

<pawn>
for ( /* initialization */ ; /* condition */ ; /* iteration */ )
{
/* body */
}
</pawn>

A simple example is a function to sum an array:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

Broken down:
*<tt>new i = 0</tt> - Creates a new variable for the loop, sets it to 0.
*<tt>i < count</tt> - Only runs the loop if <tt>i</tt> is less than <tt>count</tt>. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.
*<tt>i++</tt> - Increments <tt>i</tt> by one after each loop. This ensures that the loop doesn't run forever; eventually <tt>i</tt> will become too big and the loop will end.

Thus, the <tt>SumArray</tt> function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.

==While Loops==
While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:
*The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.
*The '''body''' block - run each time through the loop.

<pawn>
while ( /* condition */ )
{
/* body */
}
</pawn>

As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:

<pawn>
/* initialization */
while ( /* condition */ )
{
/* body */
/* iteration */
}
</pawn>

Here is the previous for loop rewritten as a while loop:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:

<pawn>
do
{
/* body */
}
while ( /* condition */ );
</pawn>

==Loop Control==
There are two cases in which you want to selectively control a loop:
*'''skipping''' one iteration of the loop but continuing as normal, or;
*'''breaking''' the loop entirely before it's finished.

Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:
<pawn>
/**
* Returns the array index where the value is, or -1 if not found.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Certainly, this function could simply <tt>return i</tt> instead, but the example shows how <tt>break</tt> will terminate the loop.

Similarly, the <tt>continue</tt> keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:
<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Skip the rest of this loop iteration */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Scope=
Scope refers to the '''visibility''' of code. That is, code at one level may not be "visible" to code at another level. For example:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

In this example, <tt>A</tt>, <tt>B</tt>, and <tt>C</tt> exist at '''global scope'''. They can be seen by any function. However, the <tt>B</tt> in <tt>Function1</tt> is not the same variable as the <tt>B</tt> at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.

Similarly, <tt>Function1</tt> and <tt>Function2</tt> know nothing about each other's variables.

Not only is the variable private to <tt>Function1</tt>, but it is re-created each time the function is invoked. Imagine this:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

In the above example, <tt>Function1</tt> calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of <tt>B</tt>. When the function ends, <tt>B</tt> is destroyed, and the value is lost.

This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks "beneath" its nesting level. For example:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Notice that <tt>B</tt> is declared in a new code block. That means <tt>B</tt> is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, <tt>B</tt> is no longer valid.

=Dynamic Arrays=
Dynamic arrays are arrays which don't have a hardcoded size. For example:

<pawn>Function1(size)
{
new array[size];

/* Code */
}</pawn>

Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.

Dynamic arrays are only valid at the local scope level, since code cannot exist globally.

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is valid to explicitly initialize a <tt>decl</tt> '''ONLY''' with strings:
<pawn>decl String:blah[512] = "a";</pawn>

However, any other tag will fail to compile, because the purpose of <tt>decl</tt> is to avoid any initialization:
<pawn>decl Float:blah[512] = {1.0};</pawn>

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

User:TheY4Kman/Plug-in Search API

2009-03-15T07:41:08Z

TheY4Kman: /* How To Search */

'''WORK IN PROGRESS!'''

The plug-in search API exposes the plug-ins database through the JSON format.

==How To Search==
Criteria for searching is specified in GET variables in the URL. For example, http://users.alliedmods.net/~they4kman/plugin_search.php?approved=yes&author=theY4Kman will retrieve all the approved plug-ins by theY4Kman. Here's the rest of the search criteria available:

*'''title''': the title of the plug-in, e.g. "Triggers"
*'''author''': the username of the author, e.g. "theY4Kman"
*'''description''': the description provided by the author
*'''category''': the type of plug-in, e.g. "General Purpose", "All", "Administration", etc.
*'''pluginid''': the ID of a plug-in ('''note''': this is NOT the thread ID)
*'''postid''': the ID of the plug-in's thread ('''note''': this IS the thread ID)
*'''authorid''': the forum user ID of the author
*'''mod''': the short name of a mod. For example, "cstrike" to search for Counter-Strike: Source games.
*'''approved''': whether the plug-in has been approved or not. '1', 'yes', and 'true' will filter out all non-approved plug-ins, whereas '0', 'no', and 'false' will filter out all approved plug-ins. Don't use this variable at all to see both approved and unapproved plug-ins.

All of the criteria (save for ''approved'') support MySQL wildcards. '''%''' (percent sign) will accept any range of text, and '''_''' (underscore) will accept one character. For example:
<pre>http://users.alliedmods.net/~they4kman/plugin_search.php?approved=yes&title=sawce%rukia</pre>
Will accept plug-in titles with any of these values:
*sawce loves rukia
*sawce is rukia
*sawce LOOOVES rukia
*sawcerukia
*sawce and rukia

<pre>http://users.alliedmods.net/~they4kman/plugin_search.php?approved=yes&title=sawce_</pre>
Will accept any of these:
*sawces
*sawce!
*sawce.

==Results==
The query http://users.alliedmods.net/~they4kman/plugin_search.php?author=theY4Kman&title=Triggers will find theY4Kman's Triggers plug-in, which will result in the following output (whitespace added for human readability):
<pre>[
{
"pluginid":"285",
"author":"theY4Kman",
"postid":"585758",
"title":"Triggers",
"category":"General Purpose",
"mod_url":"",
"description":"Adds commandlist.txt functionality (From Mani) to SourceMod",
"authorid":"28227",
"mod_short":"any",
"mod_full":"Any",
"approved":"1",
"dependencies":[]
}
]</pre>

*'''pluginid''': the ID of the plug-in
*'''author''': the username of the author
*'''postid''': the thread ID of the plug-in. Use ''forums.alliedmods.net/showthread.php?t='''postid''''' to get the full URL to the thread.
*'''title''': the title of the plug-in
*'''category''': the type of plug-in
*'''mod_url''': a link to the webpage for the mod this plug-in was built for. For example, if the plug-in was meant for Counter-Strike: Source, the ''mod_url'' will be "http://www.steamgames.com/v/index.php?area=game&AppId=240"
*'''description''': self-explanitory
*'''authorid''': the forum user ID of the author. Use ''forums.alliedmods.net/member.php?u='''authorid''''' to get the full URL of the author.
*'''mod_short''': the short name of the mod this plug-in was built for. For example, if the plug-in was meant for Counter-Strike: Source, ''mod_short'' will be "cstrike"
*'''mod_full''': the full name of the mod. For example, if the plug-in was meant for Counter-Strike: Source, ''mod_full'' will be "Counter-Strike: Source"
*'''approved''': whether the plug-in was approved. '1' if it was, '0' if it wasn't.
*'''dependencies''': this is a list of plug-in IDs that the plug-in depends on. At the time of writing, extension dependencies have not been implemented, and plug-in dependencies are rare, so this list is not very useful.

User:TheY4Kman/Plug-in Search API

2009-03-14T23:55:37Z

TheY4Kman:

'''WORK IN PROGRESS!'''

The plug-in search API exposes the plug-ins database through the JSON format.

==How To Search==
Criteria for searching is specified in GET variables in the URL. For example, http://users.alliedmods.net/~they4kman/plugin_search.php?approved=yes&author=theY4Kman will retrieve all the plug-ins by theY4Kman. Here's the rest of the search criteria available:

*'''title''': the title of the plug-in, e.g. "Triggers"
*'''author''': the username of the author, e.g. "theY4Kman"
*'''description''': the description provided by the author
*'''category''': the type of plug-in, e.g. "General Purpose", "All", "Administration", etc.
*'''pluginid''': the ID of a plug-in ('''note''': this is NOT the thread ID)
*'''postid''': the ID of the plug-in's thread ('''note''': this IS the thread ID)
*'''authorid''': the forum user ID of the author
*'''mod''': the short name of a mod. For example, "cstrike" to search for Counter-Strike: Source games.
*'''approved''': whether the plug-in has been approved or not. '1', 'yes', and 'true' will filter out all non-approved plug-ins, whereas '0', 'no', and 'false' will filter out all approved plug-ins. Don't use this variable at all to see both approved and unapproved plug-ins.

All of the criteria (save for ''approved'') support MySQL wildcards. '''%''' (percent sign) will accept any range of text, and '''_''' (underscore) will accept one character. For example:
<pre>http://users.alliedmods.net/~they4kman/plugin_search.php?approved=yes&title=sawce%rukia</pre>
Will accept plug-in titles with any of these values:
*sawce loves rukia
*sawce is rukia
*sawce LOOOVES rukia
*sawcerukia
*sawce and rukia

<pre>http://users.alliedmods.net/~they4kman/plugin_search.php?approved=yes&title=sawce_</pre>
Will accept any of these:
*sawces
*sawce!
*sawce.

==Results==
The query http://users.alliedmods.net/~they4kman/plugin_search.php?author=theY4Kman&title=Triggers will find theY4Kman's Triggers plug-in, which will result in the following output (whitespace added for human readability):
<pre>[
{
"pluginid":"285",
"author":"theY4Kman",
"postid":"585758",
"title":"Triggers",
"category":"General Purpose",
"mod_url":"",
"description":"Adds commandlist.txt functionality (From Mani) to SourceMod",
"authorid":"28227",
"mod_short":"any",
"mod_full":"Any",
"approved":"1",
"dependencies":[]
}
]</pre>

*'''pluginid''': the ID of the plug-in
*'''author''': the username of the author
*'''postid''': the thread ID of the plug-in. Use ''forums.alliedmods.net/showthread.php?t='''postid''''' to get the full URL to the thread.
*'''title''': the title of the plug-in
*'''category''': the type of plug-in
*'''mod_url''': a link to the webpage for the mod this plug-in was built for. For example, if the plug-in was meant for Counter-Strike: Source, the ''mod_url'' will be "http://www.steamgames.com/v/index.php?area=game&AppId=240"
*'''description''': self-explanitory
*'''authorid''': the forum user ID of the author. Use ''forums.alliedmods.net/member.php?u='''authorid''''' to get the full URL of the author.
*'''mod_short''': the short name of the mod this plug-in was built for. For example, if the plug-in was meant for Counter-Strike: Source, ''mod_short'' will be "cstrike"
*'''mod_full''': the full name of the mod. For example, if the plug-in was meant for Counter-Strike: Source, ''mod_full'' will be "Counter-Strike: Source"
*'''approved''': whether the plug-in was approved. '1' if it was, '0' if it wasn't.
*'''dependencies''': this is a list of plug-in IDs that the plug-in depends on. At the time of writing, extension dependencies have not been implemented, and plug-in dependencies are rare, so this list is not very useful.

User:TheY4Kman/Plug-in Search API

2009-03-14T22:56:31Z

TheY4Kman: /* How To Use It */

'''WORK IN PROGRESS!'''
The plug-in search API exposes the plug-ins database through the JSON format.

==How To Use It==
Criteria for searching is specified in GET variables in the URL. For example, http://users.alliedmods.net/~they4kman/plugin_search.php?approved=yes&author=theY4Kman will retrieve all the plug-ins by theY4Kman.

User:TheY4Kman/Plug-in Search API

2009-03-02T05:31:24Z

TheY4Kman: New page: '''WORK IN PROGRESS!''' The plug-in search API exposes the plug-ins database through the JSON format. ==How To Use It== Criteria for searching is specified in GET variables in the URL. Fo...

'''WORK IN PROGRESS!'''
The plug-in search API exposes the plug-ins database through the JSON format.

==How To Use It==
Criteria for searching is specified in GET variables in the URL. For example: http://users.alliedmods.net/~they4kman/plugin_search.php?approved=yes&author=theY4Kman will retrieve all the plug-ins by the

Gabe Newell

2009-01-26T23:19:59Z

TheY4Kman:

[[Category:VALVe_Software]]
[[Category:People]]
[[Image:Gabe Newell.jpg|thumb|300px|Gabe Newell, laying down the law.]]
{{Gaben|C’mon, people, you can’t show the player a really big bomb and not let them blow it up.|[[Half-Life 1]]}}

{{Gaben|Yes.|[[turning into cows when eating grass]]}}

{{Gaben|this extents the original player_death by a new fields|Counter-Strike:Source modevents.res}}

{{Gaben|Uh, no. And whoever is winding people up with this rumor, please stop giving out my home phone number. |rights on a half-life movie}}

{{Gaben| We at Valve have always thought of ourselves as being part of a community, and I can't imagine a better group of people to <s>help us take care of these problems than this community</s> screw over with obnoxious advertising.|[http://www.shacknews.com/onearticle.x/28619 HL2 Source Leak]}}

[[Image:Gaben_Portal_Cake.jpg|thumb|300px|Gabe Newell, reaching for the <strike>stars</strike> cake]]

File:Gaben Portal Cake.jpg

2009-01-26T23:13:38Z

TheY4Kman: Gaben tries and tries, but alas, he may never reach the cake.

Gaben tries and tries, but alas, he may never reach the cake.

Entity Properties

2008-05-14T20:22:24Z

TheY4Kman: s/encapsulates/encapsulate

This article is a brief introduction into Half-Life 2 entity properties.

=Introduction=
'''In layman's terms:'''
Entity properties are named variables attached to entities. Each variable is located at a specific offset from the entity. For example, CS:S player entities have a variable called "m_iAccount" which is offset 3,608 bytes from every player in memory. These variables, as well as their offsets, are enumerable at run-time. They are not the same as KeyValues inputs, which are designed to accept information from maps. Entity properties are the raw, internal data that comprises an entity.

'''In C++ terms:'''
Entity properties are named, retrievable properties that represent a certain data structure specific to an entity instance. They are usually tied to variables of CBaseEntity and its derivatives. Each named property is tied to, among other pieces of information, an offset from the <tt>this</tt> pointer of the entity. This means that server-side developers can easily decompose entity information, because the variable names and offsets are enumerable.

The information here is intended for server-side plugin developers who are learning, programming, or reverse engineering a mod that does not nicely expose API for modifying entities. Mod developers should use the [http://developer.valvesoftware.com/ Valve Wiki].

There are two main property types for Source entities:
*SendProps: These are properties designed for networking. Changes are mirrored to clients via the Source engine and RecvProps.
*DataMaps: These are properties designed for saving and restoring an entity. Unlike SendProps, they are not necessarily networkable, and they are more mod specific.

=Network Properties=
Network properties deal with properties that must be transmitted over the network. There are four pieces to this:
*Network variables, which handle marking offsets in memory as changed.
*Send properties, which describe how the memory/data at the offset should be networked.
*Send tables, also called data tables, which contain lists of send properties.
*Server classes, which contain all of the send tables an entity needs for networking.

Since correct networking is crucial to client/server communication, the send table hierarchy must be the same between the server and the client. Otherwise, the client will not be able to connect to the server.

==Network Variables==
The purpose of network variables is to notify the engine of which entities, and which offsets in those entities, need to be re-transmitted over the network because they have changed.

'''Important Headers''': <tt>public/networkvar.h</tt>, <tt>public/edict.h</tt>

Network variables are simple, operator-overloading macros, which box the original value type. This is to detect state changes. When m_fOnTarget is changed via normal means (for example, using C++ operators and not something like <tt>memcpy</tt>), it will trigger a function called <tt>NetworkStateChanged()</tt> in the entity. This state change can be global (resends the entire entity) or offset specific (only transmits as many bits as needed).

The order of operations is usually similar to:
<ol>
<li>Code, like the following, is executed:
<cpp>m_fOnTarget = false;</cpp>
</li>
<li>This assignment triggers <tt>::NetworkStateChanged(address)</tt> in <tt>CBaseEntity</tt> or its derived class.</li>
<li>This calls <tt>CServerNetworkProperty::NetworkStateChanged(offset_from_this)</tt></li>
<li>This calls <tt>edict_t::StateChanged(offset_from_baseent)</tt> (entities are tied to edicts)</li>
<li>If the entity has had more than 19 offsets changed, or more than 100 entities have changed, the entire entity is marked for retransmission. </li>
<li>Otherwise, its changed offset is added to the global change offset table.</li>
</ol>

An example of a network variable being declared looks like below, from <tt>dlls/player.cpp</tt>:
<cpp> CNetworkVar( bool, m_fOnTarget ); //Is the crosshair on a target?</cpp>

==Send Properties==
While network properties are for notifying the engine of changes, send properties tell the engine exactly how to deal with those changes.

'''Important Headers''': <tt>public/dt_send.h</tt>, <tt>public/dt_shared.h</tt>, <tt>public/dt_common.h</tt>

Send properties enumerate the following pieces of information about each network offset:
*A <tt>SendPropType</tt> value (Int, Float, Vector, String, Array, or Data Table).
*The number of bits to transmit.
*The name of the property (usually, the same as the variable name).
*Transmission flags (such as, whether it is signed or unsigned).
*The offset from the CBaseEntity pointer at which this variable lives.

An example of a SendProp being declared looks like below, from <tt>dlls/player.cpp</tt>:
<cpp>SendPropInt ( SENDINFO( m_fOnTarget ), 2, SPROP_UNSIGNED ),</cpp>

This declares an unsigned send property that only transmits two bits.

==Send Tables==
Send tables, also called ''data tables'', encapsulate a set of related send properties. Send tables can be nested; if there is a send property that includes a send table, the tables will effectively be merged.

'''Important Headers''': <tt>public/dt_send.h</tt>

Send tables have explicit names. For example the following line from <tt>dlls/player.cpp</tt> begins a send table named <tt>DT_PlayerState</tt>:
<cpp>BEGIN_SEND_TABLE_NOBASE(CPlayerState, DT_PlayerState)</cpp>

This particular send table is then linked into <tt>DT_BasePlayer</tt> via:
<cpp>SendPropDataTable(SENDINFO_DT(pl), &REFERENCE_SEND_TABLE(DT_PlayerState), SendProxy_DataTableToDataTable),</cpp>

==Server Classes==
Server classes are at the highest level of the networking chain. Each server class has:
*A unique name (a <tt>ClassName</tt> as opposed to an entity's <tt>Classname</tt>).
*A root send table.
*A pointer to the next server class in the chain.

'''Important Headers''': <tt>public/server_class.h</tt>

While server classes are not related, they are globally linked via a constructor - this is simply to make development easier. The engine retrieves the first server class pointer via <tt>IServerGameDLL::GetAllServerClasses()</tt>. Using this pointer, the engine can find every single server class, and thus all send tables in the tree, and likewise, all send properties in each table.

Usually, each major CBaseEntity derivation contains a server class. For example, for Counter-Strike:Source, there is a <tt>CCSPlayer</tt> server class. Its major hierarchy looks roughly like:
*CCSPlayer
**DT_CSPlayer
***DT_BasePlayer
****DT_BaseCombatCharacter
*****DT_BaseFlex
******DT_BaseAnimatingOverlay
*******DT_BaseAnimating
********DT_BaseEntity

Although this is a recursive tree, the properties themselves are all linear. This means, that all send properties under CCSPlayer are all offsets to anything matching a CCSPlayer.

Because server classes can be enumerated without the instantiation of a given object/entity, send property lookup can be resolved at load time. Even if it needs to be done at run-time, it can be easily optimized given this linear structure.

=Data Maps=
Data maps are properties which are enumerated for save/restore mechanisms. They are less complicated than send properties, but more mod-specific.

'''Important Headers''': <tt>public/datamap.h</tt>

Data maps are encapsulated in a structure called <tt>datamap_t</tt>. This structure contains the following information:
*An array of <tt>typedescription_t</tt> structures.
*A string name.
*A link to a parent data map, if any.

The <tt>typedescription_t</tt> structure declares one property. It contains:
*A <tt>fieldtype_t</tt> data type, which has types such as <tt>FIELD_INTEGER</tt> and <tt>FIELD_STRING</tt>
*A field name, which will usually be the same as the variable name.
*An offset from the entity pointer to where this data lives.

Data maps can be recursive trees like send tables, since a field can contain another data map. However, there is no known or documented method of easily extracting all data maps. This means that lookup can only be done once an instance to a given entity is known, relying on <tt>CBaseEntity::GetDataDescMap</tt>.

However, CBaseEntity is ultimately mod specific. Even if it's rare that its position in the virtual table will change, care should be taken to ensure cross-mod compatibility. It is incorrect to assume that calling this function will result in the same behaviour on every mod.

An example of a data map being declared can be found in <tt>dlls/player.cpp</tt>:
<cpp>BEGIN_SIMPLE_DATADESC( CPlayerState )
// DEFINE_FIELD( netname, FIELD_STRING ), // Don't stomp player name with what's in save/restore
DEFINE_FIELD( v_angle, FIELD_VECTOR ),</cpp>

=Enumeration=
==Server Classes==
Server classes are easily enumerable. Here is an example function:

<cpp>/**
* Searches for a named Server Class.
*
* @param name Name of the top-level server class.
* @return Server class matching the name, or NULL if none found.
*/
ServerClass *UTIL_FindServerClass(const char *name)
{
ServerClass *pClass = server->GetAllServerClasses();
while (pClass)
{
if (strcmp(pClass->m_pNetworkName, name) == 0)
{
return pClass;
}
pClass = pClass->m_pNext;
}
return NULL;
}</cpp>

==Send Properties==
Full send table enumeration requires recursion. An example function below recurses through all properties and sub-table properties of a table.

<cpp>/**
* Recursively looks through a send table for a given named property.
*
* @param pTable Send table to browse.
* @param name Property to search for.
* @return SendProp pointer on success, NULL on failure.
*/
SendProp *UTIL_FindSendProp(SendTable *pTable, const char *name)
{
int count = pTable->GetNumProps();
SendTable *pTable;
SendProp *pProp;
for (int i=0; i<count; i++)
{
pProp = pTable->GetProp(i);
if (strcmp(pProp->GetName(), name) == 0)
{
return pProp;
}
if (pProp->GetDataTable())
{
if ((pProp=UTIL_FindSendProp(pProp->GetDataTable(), name)) != NULL)
{
return pProp;
}
}
}

return NULL;
}</cpp>

An example usage of both of these functions might look like:
<cpp>/**
* Sets a player's health.
*
* @param edict Player's edict.
* @param health Health to set.
*/
void SetPlayerHealth(edict_t *edict, int health)
{
static unsigned int offset = 0;

if (!offset)
{
ServerClass *sc = UTIL_FindServerClass("CBasePlayer");
SendProp *pProp = UTIL_FindSendProp(sc->m_pTable, "m_iHealth");
offset = pProp->GetOffset();
}

IServerUnknown *pUnknown = (IServerUnknown *)edict->GetUnknown();
if (!pUnknown)
{
return;
}

CBaseEntity *pEntity = pUnknown->GetBaseEntity();
*(int *)((char *)pEntity + offset) = health;
}</cpp>

==Datamap Properties==
Here is an example of a function for searching datamaps for a given property.

<cpp>/**
* Finds a named offset in a datamap.
*
* @param pMap Datamap to search.
* @param name Name of the property to find.
* @return Offset of a data map property, or 0 if not found.
*/
unsigned int UTIL_FindInDataMap(datamap_t *pMap, const char *name)
{
while (pMap)
{
for (int i=0; i<pMap->dataNumFields; i++)
{
if (pMap->dataDesc[i].fieldName == NULL)
{
continue;
}
if (strcmp(name, pMap->dataDesc[i].fieldName) == 0)
{
return pMap->dataDesc[i].fieldOffset[TD_OFFSET_NORMAL];
}
if (pMap->dataDesc[i].td)
{
unsigned int offset;
if ((offset=UTIL_FindInDataMap(pMap->dataDesc[i].td, name)) != 0)
{
return offset;
}
}
}
pMap = pMap->baseMap;
}

return 0;
}</cpp>

Now we can rewrite the <tt>SetPlayerHealth</tt> function using data maps:

<cpp>/**
* Sets a player's health.
*
* @param edict Player's edict.
* @param health Health to set.
*/
void SetPlayerHealth(edict_t *edict, int health)
{
static unsigned int offset = 0;

IServerUnknown *pUnknown = (IServerUnknown *)edict->GetUnknown();
if (!pUnknown)
{
return;
}

CBaseEntity *pEntity = pUnknown->GetBaseEntity();

if (!offset)
{
offset = UTIL_FindInDataMap(pEntity->GetDataDescMap(), "m_iHealth");
}

*(int *)((char *)pEntity + offset) = health;
}</cpp>

=SourceMod Commands=
SDKTools provides two commands for dumping netprops:
*<tt>sm_dump_netprops <file></tt> - Dumps network properties to a named text file (in the mod folder).
*<tt>sm_dump_netprops_xml <file></tt> - Dumps network properties to a named text file in XML format (in the mod folder).

=External Links=
*[http://www.bailopan.net/table_dump.txt Sample CS:S Network Property Dump]
*[http://www.bailopan.net/tf_netprops.txt Sample TF Network Property Dump]

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

Introduction to SourcePawn (legacy syntax)

2008-05-10T21:17:00Z

TheY4Kman: More semi-colons!

This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a "scripting" language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].

This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics.

=Non-Programmer Intro=
This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.

==Symbols/Keywords==
A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive (unlike PHP, where sometimes they are not). Symbols do not start with any special character, though they must start with a letter.

There are a few reserved symbols that have special meaning. For example, <tt>if</tt>, <tt>for</tt>, and <tt>return</tt> are special constructs in the language that will explained later. They cannot be used as symbol names.

==Variables==
There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable "a" could hold the number "2", "16", "0", et cetera. Variables are created for storage space throughout a program. Variables must be declared before being used, using the "new" keyword. Data is assigned to variables using the equal sign (=). Example:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

In SourcePawn, variables have two types, which will be explained in more detail further on.
*Cells (arbitrary numerical data), as shown above.
*Strings (a series of text characters)

==Functions==
The next important concept is '''functions'''. Functions are symbols or names that perform an action. That means when you activate them, they carry out a specific sequence of code. There are a few types of functions, but every function is activated the same way. "Calling a function" is the term for invoking a function's action. Function calls are constructed like this:
<pawn>function(<parameters>)</pawn>

Examples:

<pawn>show(56); //Activates "show" function, and gives the number 56 to it
show(); //Activates "show" function with no data, blank
show(a); //Activates "show" function, gives a variable's contents as data
</pawn>

Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a "reasonable" limit of 32 in SourceMod). Parameters will be explained further in the article.

==Comments==
Note any text that appears after a "//" is considered a "comment" and is not actual code. There are two comment styles:
*<tt>//</tt> - Double slash, everything following on that line is ignored.
*<tt>/* */</tt> - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.

==Block Coding==
The next concept is block coding. You can group code into "blocks" separated by { and }. This effectively makes one large block of code act as one statement. For example:

<pawn>{
here;
is;
some;
code;
}</pawn>

Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.

=Language Paradigms=
Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.
*'''Pawn is not typed.''' Pawn only has one data type, the '''cell'''. This will be explained in detail later.
*'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.
*'''Pawn is not object oriented.''' Pawn is procedural, and relies on subroutines. It also does not have C structs.
*'''Pawn is not functional.''' Pawn is procedural, and does not support lambda functions or late binding or anything else you might find in a very high-level language, like Python or Ruby.
*'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe.
*'''Pawn is not interpreted.''' Well, it "sort of" is. It gets interpreted at a very low level. You must run your code through a compiler, which produces a binary. This binary will work on any platform that the host application uses. This speeds up loading time and lets you check errors easier.

These languages design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.

=Variables=
In Pawn there are two variable types: the '''cell''' and the '''String'''. A cell can store 32 bits of numerical data. A String is a sequential/flat list of UTF-8 text characters.

A '''cell''' has no inherent type, however, cells can be '''tagged'''. A tag lets you enforce where certain cells can be used. The default tags are:
*(nothing), or '''_''' - No tag. Usually used for whole numbers ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - Used for floating point (fractional) numbers.
*'''bool''' - Used for storing either '''true''' or '''false'''.

Strings are different and will be explained in the next sections.

==Declaration==
Examples of different valid variable declarations:
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Works because 0 is false
</pawn>

Invalid variable usage:
<pawn>
new a = 5.0; //Tag mismatch. 5.0 is tagged as Float
new Float:b = 5; //Tag mismatch. 5 is not tagged.
</pawn>

If a variable is not assigned upon declaration, it will be set to 0. For example:
<pawn>
new a; //Set to 0
new Float:b; //Set to 0.0
new bool:c; //Set to false
</pawn>

==Assignment==
Variables can be re-assigned data after they are created. For example:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

=Arrays=
An array is a sequence of data in a sequential list. Arrays are useful for storing multiple pieces of data in one variable, and often greatly simplify many tasks.

==Declaration==
An array is declared using brackets. Some examples of arrays:
<pawn>
new players[32]; //Stores 32 cells (numbers)
new Float:origin[3]; //Stores 3 floating point numbers
</pawn>

By default, arrays are initialized to 0. You can assign them different default values, however:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Stores 1, 2, 3, 4, 5 in the cells.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Stores 1.0, 2.0, 3.0 in the cells.
</pawn>

You can leave out the array size if you're going to pre-assign data to it. For example:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

The compiler will automatically deduce that you intended an array of size 5.

==Usage==
Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.

For example, here is an example of the above code using indexes:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.

To use an incorrect index will cause an error. For example:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

This may look correct, but 5 is not a valid index. The highest valid index is 4.

You can use any expression as an index. For example:
<pawn>new a, numbers[5];

a = 1; //Set a = 1
numbers[a] = 4; //Set numbers[1] = 3
numbers[numbers[a]] = 2; //Set numbers[4] = 2
</pawn>

Expressions will be discussed in depth later in the article.

=Strings=
Strings are a convenient method of storing text. The characters are stored in an array. The string is terminated by a '''null terminator''', or a 0. Without a null terminator, Pawn would not know where to stop reading the string. All strings are UTF-8 in SourcePawn.

Notice that Strings are a combination of arrays and cells. Unlike other languages, this means you must know how much space a string will use in advance. That is, strings are not dynamic. They can only grow to the space you allocate for them.

''Note for experts: They're not actually cells. SourcePawn uses 8-bit storage for String arrays as an optimization. This is what makes String a type and not a tag.''

==Usage==
Strings are declared almost equivalently to arrays. For example:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

These are equivalent to doing:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.

Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.

==Characters==
A character of text can be used in either a String or a cell. For example:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Set clam to 'D'
text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'
clam = text[0]; //Set clam to 'A'
text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'
</pawn>

What you can't do is mix character arrays with strings. The internal storage is different. For example:
<pawn>
new clams[] = "Clams"; //Invalid, needs String: type
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Valid, but NOT A STRING.
</pawn>

=Functions=
Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.

There are two types of ways functions are called:
*'''direct call''' - You specifically call a function in your code.
*'''callback''' - The application calls a function in your code, as if it were an event trigger.

There are five types of functions:
*'''native''': A direct, internal function provided by the application.
*'''public''': A callback function that is visible to the application and other scripts.
*'''normal''': A normal function that only you can call.
*'''stock''': A normal function provided by an include file. If unused, it won't be compiled.
*'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.

All code in Pawn must exist in functions. This is contrast to languages like PHP, Perl, or Python, which let you write global code. That is because Pawn is a callback-based language; it responds to actions from a parent application, and functions must be built to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.

==Declaration==
Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''prototype''' and the '''body'''. The prototype contains the name of your function and the parameters it will accept. The body is the contents of its code.

Example of a function:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

This is a simple function. The prototype is this line:
<pawn>AddTwoNumbers(first, second);</pawn>

Broken down, it means:
*<tt>AddTwoNumbers</tt> - Name of the function.
*<tt>first</tt> - Name of the first parameter, which is a simple cell.
*<tt>second</tt> - Name of the second parameter, which is a simple cell.

The body is a simple block of code. It creates a new variable, called <tt>sum</tt>, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the <tt>return</tt> statement, which tells the function to end. All functions ''return a cell'' upon completion. That means, for example:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

The above code will assign the number 9 to sum. The function adds the two inputs, and the sum is given as the '''return value'''. If a function has no return statement, or does not place a value in the return statement, it returns 0 by default.

A function can accept any type of input. It can return any cell, but not arrays or strings. Example:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Note that if in the above function, you returned a non-Float, you would get a tag mismatch.''

You can, of course, pass variables to functions:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

This code would not change the value of <tt>a</tt>. That is because a copy of the value in <tt>a</tt> is passed instead of <tt>a</tt> itself.

More examples of functions will be provided throughout the article.

==Publics==
Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

To implement and receive these two events, you would write functions as such:

<pawn>public OnPluginStart()
{
/* Code here */
}

public OnClientDisconnected(client)
{
/* Code here */
}</pawn>

The '''public''' keyword exposes the function publicly, and allows the parent application to directly call the function.

==Natives==
Natives are builtin functions provided by the application. You can call them as if they were a normal function. For example, SourceMod has the following function:

<pawn>native FloatRound(Float:num);</pawn>

It can be called like so:
<pawn>new num = FloatRound(5.0); //Results in num = 5</pawn>

==Array Parameters==
You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:
<pawn>example[2] = 29;</pawn>

This is only possible because the array can be directly modified. To prevent an array from being modified, you can mark it as <tt>const</tt>. This will raise an error on code that attempts to modify it. For example:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Won't compile
}</pawn>

It is a good idea to use <tt>const</tt> in array parameters if you know the array won't be modified; this can prevent coding mistakes.

=Expressions=
Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict "order of operations." They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.

The simplest expression is a single number. For example:
<pawn>
0; //Returns the number 0
(0); //Returns the number 0 as well
</pawn>

Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.

The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:
<pawn>
5 + 6; //Evaluates to 11
5 * 6 + 3; //Evaluates to 33
5 * (6 + 3); //Evaluates to 45
5.0 + 2.3; //Evaluates to 7.3
(5 * 6) % 7; //Modulo operator, evaluates to 2
(5 + 3) / 2 * 4 - 9; //Evaluates to 7
</pawn>

As noted, expressions can contain variables, or even functions:
<pawn>
new a = 5 * 6;
new b = a * 3; //Evaluates to 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Operators==
There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:
<pawn>new a = 5;

a = a + 5;</pawn>

Can be rewritten as:
<pawn>new a = 5;
a += 5;</pawn>

This is true of the following operators in Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Additionally, there are increment/decrement operators:
<pawn>a = a + 1;
a = a - 1;</pawn>

Can be simplified as:
<pawn>a++;
a--;</pawn>

As an advanced note, the ++ or -- can be before the variable (preincrement, predecrement) or after the variable (postincrement, postdecrement). The difference is in the order of execution. For example:

<pawn>new a = 5;
new b = a++;
new c = ++a;
</pawn>

In this example, <tt>b</tt> will be equal to 5, after which <tt>a</tt> will be incremented to 6. But then <tt>a</tt> will be incremented to 7, and <tt>c</tt> will receive the value of 7.

==Truth Operators==
As noted earlier, expressions can either be true or false depending on if they're non-zero or zero. This is especially useful with truth operators. There are five important truth operators:
*<tt>&&</tt> - Tests whether two expressions are both true.
*<tt>||</tt> - Tests whether one of two expressions is true.
*<tt>!</tt> - Flips the truth value of an expression.
*<tt>==</tt> - Tests whether two expressions are numerically equivalent.
*<tt>!=</tt> - Tests whether two expressions are numerically inequivalent.

There are also some mathematical truth operators (L is left hand, R is right hand):
*<tt>></tt> - True if L is greater than R
*<tt>>=</tt> - True if L is greater than or equal to R
*<tt><</tt> - True if L is less than R
*<tt><=</tt> - True if L is less than or equal to R

For example:
<pawn>
(1 || 0); //Evaluates to true because the expression 1 is true
(1 && 0); //Evaluates to false because the expression 0 is false
(!1 || 0); //Evaluates to false because !1 is false.
(1 != 3); //Evaluates to true because 1 is not equal to 3
(3 + 3 == 6); //Evaluates to true because 3+3 is 6.
</pawn>

Note that these operators do not work on arrays. That is, you cannot compare strings or arrays using <tt>==</tt>.

==Left/Right Values==
Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.

For example:
<pawn>
new a = 5;</pawn>

In this example <tt>a</tt> is an l-value and <tt>5</tt> is an r-value.

The rules:
*'''Expressions are never l-values'''.
*'''Variables are both l-values and r-values'''.

=Conditionals=
Conditional statements let you only run code if a certain condition is matched.

==If Statements==
If statements test one or more conditions. For example:

<pawn>
if (a == 5)
{
/* Code that will run if the expression was true */
}</pawn>

They can be extended to handle more cases as well:
<pawn>
if (a == 5)
{
/* Code */
}
else if (a == 6)
{
/* Code */
}
else if (a == 7)
{
/* Code */
}</pawn>

You can also handle the case of no expression being matched. For example:
<pawn>
if (a == 5)
{
/* Code */
}
else
{
/* Code that will run if no expressions were true */
}</pawn>

==Switch Statements==
Switch statements are restricted if statements. They test one expression for a series of possible values. For example:

<pawn>
switch (a)
{
case 5:
{
/* code */
}
case 6:
{
/* code */
}
case 7:
{
/* code */
}
case 8, 9, 10:
{
/* Code */
}
default:
{
/* will run if no case matched */
}
}</pawn>

Unlike some other languages, switches are not fall-through. That is, multiple cases will never be ran. If a single case matches, its code is ran, and the switch is then immediately terminated.

=Loops=
Loops allow you to conveniently repeat a block of code while a given condition remains true.

==For Loops==
For loops are loops which have four properties:
*The '''begin''' statement, which is ran before the first loop occurs.
*The '''condition''' statement, which checks whether the next loop should run.
*The '''iterator''' statement, which is ran after each loop runs.
*The code block itself, which is what's run every loop.

A simple example is a function to sum an array:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

Broken down:
*<tt>new i = 0</tt> - Creates a new variable for the loop, sets it to 0.
*<tt>i < count</tt> - Only runs the loop if <tt>i</tt> is less than <tt>count</tt>. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.
*<tt>i++</tt> - Increments <tt>i</tt> by one after each loop. This ensures that the loop doesn't run forever; eventually <tt>i</tt> will become too big and the loop will end.

Thus, the <tt>SumArray</tt> function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.

==While Loops==
While loops are less common than for loops, but are actually the simplest possible loop. It only has two properties:
*The '''condition''', which is checked before each loop.
*The '''code''', which is what's run each loop.

As long as the condition expression remains true, the loop will continue. Here is an example of the previous for loop as a while loop:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:

<pawn>
do
{
/* Code */
} while(CONDITION);
</pawn>

==Loop Control==
There are two cases in which you want to selectively control a loop:
*'''skipping''' one iteration of the loop but continuing as normal, or;
*'''breaking''' the loop entirely before it's finished.

Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:
<pawn>
/**
* Returns the array index where the value is, or -1 if not found.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Certainly, this function could simply <tt>return i</tt> instead, but the example shows how <tt>break</tt> will terminate the loop.

Similarly, the <tt>continue</tt> keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:
<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Skip the rest of this loop iteration */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Scope=
Scope refers to the '''visibility''' of code. That is, code at one level may not be "visible" to code at another level. For example:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

In this example, <tt>A</tt>, <tt>B</tt>, and <tt>C</tt> exist at '''global scope'''. They can be seen by any function. However, the <tt>B</tt> in <tt>Function1</tt> is not the same variable as the <tt>B</tt> at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.

Similarly, <tt>Function1</tt> and <tt>Function2</tt> know nothing about each other's variables.

Not only is the variable private to <tt>Function1</tt>, but it is re-created each time the function is invoked. Imagine this:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

In the above example, <tt>Function1</tt> calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of <tt>B</tt>. When the function ends, <tt>B</tt> is destroyed, and the value is lost.

This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks "beneath" its nesting level. For example:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Notice that <tt>B</tt> is declared in a new code block. That means <tt>B</tt> is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, <tt>B</tt> is no longer valid.

=Dynamic Arrays=
Dynamic arrays are arrays which don't have a hardcoded size. For example:

<pawn>Function1(size)
{
new array[size];

/* Code */
}</pawn>

Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.

Dynamic arrays are only valid at the local scope level, since code cannot exist globally.

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:SourceMod Scripting]]

Introduction to SourcePawn (legacy syntax)

2008-05-10T21:15:38Z

TheY4Kman: Fixed some spelling errors, and added semi-colons

This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a "scripting" language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].

This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics.

=Non-Programmer Intro=
This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.

==Symbols/Keywords==
A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive (unlike PHP, where sometimes they are not). Symbols do not start with any special character, though they must start with a letter.

There are a few reserved symbols that have special meaning. For example, <tt>if</tt>, <tt>for</tt>, and <tt>return</tt> are special constructs in the language that will explained later. They cannot be used as symbol names.

==Variables==
There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable "a" could hold the number "2", "16", "0", et cetera. Variables are created for storage space throughout a program. Variables must be declared before being used, using the "new" keyword. Data is assigned to variables using the equal sign (=). Example:

<pawn>new a,b,c,d

a=5
b=16
c=0
d=500</pawn>

In SourcePawn, variables have two types, which will be explained in more detail further on.
*Cells (arbitrary numerical data), as shown above.
*Strings (a series of text characters)

==Functions==
The next important concept is '''functions'''. Functions are symbols or names that perform an action. That means when you activate them, they carry out a specific sequence of code. There are a few types of functions, but every function is activated the same way. "Calling a function" is the term for invoking a function's action. Function calls are constructed like this:
<pawn>function(<parameters>)</pawn>

Examples:

<pawn>show(56) //Activates "show" function, and gives the number 56 to it
show() //Activates "show" function with no data, blank
show(a) //Activates "show" function, gives a variable's contents as data
</pawn>

Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a "reasonable" limit of 32 in SourceMod). Parameters will be explained further in the article.

==Comments==
Note any text that appears after a "//" is considered a "comment" and is not actual code. There are two comment styles:
*<tt>//</tt> - Double slash, everything following on that line is ignored.
*<tt>/* */</tt> - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.

==Block Coding==
The next concept is block coding. You can group code into "blocks" separated by { and }. This effectively makes one large block of code act as one statement. For example:

<pawn>{
here
is
some
code
}</pawn>

Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.

=Language Paradigms=
Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.
*'''Pawn is not typed.''' Pawn only has one data type, the '''cell'''. This will be explained in detail later.
*'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.
*'''Pawn is not object oriented.''' Pawn is procedural, and relies on subroutines. It also does not have C structs.
*'''Pawn is not functional.''' Pawn is procedural, and does not support lambda functions or late binding or anything else you might find in a very high-level language, like Python or Ruby.
*'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe.
*'''Pawn is not interpreted.''' Well, it "sort of" is. It gets interpreted at a very low level. You must run your code through a compiler, which produces a binary. This binary will work on any platform that the host application uses. This speeds up loading time and lets you check errors easier.

These languages design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.

=Variables=
In Pawn there are two variable types: the '''cell''' and the '''String'''. A cell can store 32 bits of numerical data. A String is a sequential/flat list of UTF-8 text characters.

A '''cell''' has no inherent type, however, cells can be '''tagged'''. A tag lets you enforce where certain cells can be used. The default tags are:
*(nothing), or '''_''' - No tag. Usually used for whole numbers ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - Used for floating point (fractional) numbers.
*'''bool''' - Used for storing either '''true''' or '''false'''.

Strings are different and will be explained in the next sections.

==Declaration==
Examples of different valid variable declarations:
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Works because 0 is false
</pawn>

Invalid variable usage:
<pawn>
new a = 5.0; //Tag mismatch. 5.0 is tagged as Float
new Float:b = 5; //Tag mismatch. 5 is not tagged.
</pawn>

If a variable is not assigned upon declaration, it will be set to 0. For example:
<pawn>
new a; //Set to 0
new Float:b; //Set to 0.0
new bool:c; //Set to false
</pawn>

==Assignment==
Variables can be re-assigned data after they are created. For example:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

=Arrays=
An array is a sequence of data in a sequential list. Arrays are useful for storing multiple pieces of data in one variable, and often greatly simplify many tasks.

==Declaration==
An array is declared using brackets. Some examples of arrays:
<pawn>
new players[32]; //Stores 32 cells (numbers)
new Float:origin[3]; //Stores 3 floating point numbers
</pawn>

By default, arrays are initialized to 0. You can assign them different default values, however:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Stores 1, 2, 3, 4, 5 in the cells.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Stores 1.0, 2.0, 3.0 in the cells.
</pawn>

You can leave out the array size if you're going to pre-assign data to it. For example:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

The compiler will automatically deduce that you intended an array of size 5.

==Usage==
Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.

For example, here is an example of the above code using indexes:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.

To use an incorrect index will cause an error. For example:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

This may look correct, but 5 is not a valid index. The highest valid index is 4.

You can use any expression as an index. For example:
<pawn>new a, numbers[5];

a = 1; //Set a = 1
numbers[a] = 4; //Set numbers[1] = 3
numbers[numbers[a]] = 2; //Set numbers[4] = 2
</pawn>

Expressions will be discussed in depth later in the article.

=Strings=
Strings are a convenient method of storing text. The characters are stored in an array. The string is terminated by a '''null terminator''', or a 0. Without a null terminator, Pawn would not know where to stop reading the string. All strings are UTF-8 in SourcePawn.

Notice that Strings are a combination of arrays and cells. Unlike other languages, this means you must know how much space a string will use in advance. That is, strings are not dynamic. They can only grow to the space you allocate for them.

''Note for experts: They're not actually cells. SourcePawn uses 8-bit storage for String arrays as an optimization. This is what makes String a type and not a tag.''

==Usage==
Strings are declared almost equivalently to arrays. For example:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

These are equivalent to doing:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.

Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.

==Characters==
A character of text can be used in either a String or a cell. For example:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Set clam to 'D'
text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'
clam = text[0]; //Set clam to 'A'
text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'
</pawn>

What you can't do is mix character arrays with strings. The internal storage is different. For example:
<pawn>
new clams[] = "Clams"; //Invalid, needs String: type
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Valid, but NOT A STRING.
</pawn>

=Functions=
Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.

There are two types of ways functions are called:
*'''direct call''' - You specifically call a function in your code.
*'''callback''' - The application calls a function in your code, as if it were an event trigger.

There are five types of functions:
*'''native''': A direct, internal function provided by the application.
*'''public''': A callback function that is visible to the application and other scripts.
*'''normal''': A normal function that only you can call.
*'''stock''': A normal function provided by an include file. If unused, it won't be compiled.
*'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.

All code in Pawn must exist in functions. This is contrast to languages like PHP, Perl, or Python, which let you write global code. That is because Pawn is a callback-based language; it responds to actions from a parent application, and functions must be built to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.

==Declaration==
Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''prototype''' and the '''body'''. The prototype contains the name of your function and the parameters it will accept. The body is the contents of its code.

Example of a function:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

This is a simple function. The prototype is this line:
<pawn>AddTwoNumbers(first, second);</pawn>

Broken down, it means:
*<tt>AddTwoNumbers</tt> - Name of the function.
*<tt>first</tt> - Name of the first parameter, which is a simple cell.
*<tt>second</tt> - Name of the second parameter, which is a simple cell.

The body is a simple block of code. It creates a new variable, called <tt>sum</tt>, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the <tt>return</tt> statement, which tells the function to end. All functions ''return a cell'' upon completion. That means, for example:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

The above code will assign the number 9 to sum. The function adds the two inputs, and the sum is given as the '''return value'''. If a function has no return statement, or does not place a value in the return statement, it returns 0 by default.

A function can accept any type of input. It can return any cell, but not arrays or strings. Example:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Note that if in the above function, you returned a non-Float, you would get a tag mismatch.''

You can, of course, pass variables to functions:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

This code would not change the value of <tt>a</tt>. That is because a copy of the value in <tt>a</tt> is passed instead of <tt>a</tt> itself.

More examples of functions will be provided throughout the article.

==Publics==
Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

To implement and receive these two events, you would write functions as such:

<pawn>public OnPluginStart()
{
/* Code here */
}

public OnClientDisconnected(client)
{
/* Code here */
}</pawn>

The '''public''' keyword exposes the function publicly, and allows the parent application to directly call the function.

==Natives==
Natives are builtin functions provided by the application. You can call them as if they were a normal function. For example, SourceMod has the following function:

<pawn>native FloatRound(Float:num);</pawn>

It can be called like so:
<pawn>new num = FloatRound(5.0); //Results in num = 5</pawn>

==Array Parameters==
You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:
<pawn>example[2] = 29;</pawn>

This is only possible because the array can be directly modified. To prevent an array from being modified, you can mark it as <tt>const</tt>. This will raise an error on code that attempts to modify it. For example:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Won't compile
}</pawn>

It is a good idea to use <tt>const</tt> in array parameters if you know the array won't be modified; this can prevent coding mistakes.

=Expressions=
Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict "order of operations." They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.

The simplest expression is a single number. For example:
<pawn>
0; //Returns the number 0
(0); //Returns the number 0 as well
</pawn>

Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.

The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:
<pawn>
5 + 6; //Evaluates to 11
5 * 6 + 3; //Evaluates to 33
5 * (6 + 3); //Evaluates to 45
5.0 + 2.3; //Evaluates to 7.3
(5 * 6) % 7; //Modulo operator, evaluates to 2
(5 + 3) / 2 * 4 - 9; //Evaluates to 7
</pawn>

As noted, expressions can contain variables, or even functions:
<pawn>
new a = 5 * 6;
new b = a * 3; //Evaluates to 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Operators==
There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:
<pawn>new a = 5;

a = a + 5;</pawn>

Can be rewritten as:
<pawn>new a = 5;
a += 5;</pawn>

This is true of the following operators in Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Additionally, there are increment/decrement operators:
<pawn>a = a + 1;
a = a - 1;</pawn>

Can be simplified as:
<pawn>a++;
a--;</pawn>

As an advanced note, the ++ or -- can be before the variable (preincrement, predecrement) or after the variable (postincrement, postdecrement). The difference is in the order of execution. For example:

<pawn>new a = 5;
new b = a++;
new c = ++a;
</pawn>

In this example, <tt>b</tt> will be equal to 5, after which <tt>a</tt> will be incremented to 6. But then <tt>a</tt> will be incremented to 7, and <tt>c</tt> will receive the value of 7.

==Truth Operators==
As noted earlier, expressions can either be true or false depending on if they're non-zero or zero. This is especially useful with truth operators. There are five important truth operators:
*<tt>&&</tt> - Tests whether two expressions are both true.
*<tt>||</tt> - Tests whether one of two expressions is true.
*<tt>!</tt> - Flips the truth value of an expression.
*<tt>==</tt> - Tests whether two expressions are numerically equivalent.
*<tt>!=</tt> - Tests whether two expressions are numerically inequivalent.

There are also some mathematical truth operators (L is left hand, R is right hand):
*<tt>></tt> - True if L is greater than R
*<tt>>=</tt> - True if L is greater than or equal to R
*<tt><</tt> - True if L is less than R
*<tt><=</tt> - True if L is less than or equal to R

For example:
<pawn>
(1 || 0); //Evaluates to true because the expression 1 is true
(1 && 0); //Evaluates to false because the expression 0 is false
(!1 || 0); //Evaluates to false because !1 is false.
(1 != 3); //Evaluates to true because 1 is not equal to 3
(3 + 3 == 6); //Evaluates to true because 3+3 is 6.
</pawn>

Note that these operators do not work on arrays. That is, you cannot compare strings or arrays using <tt>==</tt>.

==Left/Right Values==
Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.

For example:
<pawn>
new a = 5;</pawn>

In this example <tt>a</tt> is an l-value and <tt>5</tt> is an r-value.

The rules:
*'''Expressions are never l-values'''.
*'''Variables are both l-values and r-values'''.

=Conditionals=
Conditional statements let you only run code if a certain condition is matched.

==If Statements==
If statements test one or more conditions. For example:

<pawn>
if (a == 5)
{
/* Code that will run if the expression was true */
}</pawn>

They can be extended to handle more cases as well:
<pawn>
if (a == 5)
{
/* Code */
}
else if (a == 6)
{
/* Code */
}
else if (a == 7)
{
/* Code */
}</pawn>

You can also handle the case of no expression being matched. For example:
<pawn>
if (a == 5)
{
/* Code */
}
else
{
/* Code that will run if no expressions were true */
}</pawn>

==Switch Statements==
Switch statements are restricted if statements. They test one expression for a series of possible values. For example:

<pawn>
switch (a)
{
case 5:
{
/* code */
}
case 6:
{
/* code */
}
case 7:
{
/* code */
}
case 8, 9, 10:
{
/* Code */
}
default:
{
/* will run if no case matched */
}
}</pawn>

Unlike some other languages, switches are not fall-through. That is, multiple cases will never be ran. If a single case matches, its code is ran, and the switch is then immediately terminated.

=Loops=
Loops allow you to conveniently repeat a block of code while a given condition remains true.

==For Loops==
For loops are loops which have four properties:
*The '''begin''' statement, which is ran before the first loop occurs.
*The '''condition''' statement, which checks whether the next loop should run.
*The '''iterator''' statement, which is ran after each loop runs.
*The code block itself, which is what's run every loop.

A simple example is a function to sum an array:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

Broken down:
*<tt>new i = 0</tt> - Creates a new variable for the loop, sets it to 0.
*<tt>i < count</tt> - Only runs the loop if <tt>i</tt> is less than <tt>count</tt>. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.
*<tt>i++</tt> - Increments <tt>i</tt> by one after each loop. This ensures that the loop doesn't run forever; eventually <tt>i</tt> will become too big and the loop will end.

Thus, the <tt>SumArray</tt> function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.

==While Loops==
While loops are less common than for loops, but are actually the simplest possible loop. It only has two properties:
*The '''condition''', which is checked before each loop.
*The '''code''', which is what's run each loop.

As long as the condition expression remains true, the loop will continue. Here is an example of the previous for loop as a while loop:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:

<pawn>
do
{
/* Code */
} while(CONDITION);
</pawn>

==Loop Control==
There are two cases in which you want to selectively control a loop:
*'''skipping''' one iteration of the loop but continuing as normal, or;
*'''breaking''' the loop entirely before it's finished.

Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:
<pawn>
/**
* Returns the array index where the value is, or -1 if not found.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Certainly, this function could simply <tt>return i</tt> instead, but the example shows how <tt>break</tt> will terminate the loop.

Similarly, the <tt>continue</tt> keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:
<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Skip the rest of this loop iteration */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Scope=
Scope refers to the '''visibility''' of code. That is, code at one level may not be "visible" to code at another level. For example:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

In this example, <tt>A</tt>, <tt>B</tt>, and <tt>C</tt> exist at '''global scope'''. They can be seen by any function. However, the <tt>B</tt> in <tt>Function1</tt> is not the same variable as the <tt>B</tt> at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.

Similarly, <tt>Function1</tt> and <tt>Function2</tt> know nothing about each other's variables.

Not only is the variable private to <tt>Function1</tt>, but it is re-created each time the function is invoked. Imagine this:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

In the above example, <tt>Function1</tt> calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of <tt>B</tt>. When the function ends, <tt>B</tt> is destroyed, and the value is lost.

This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks "beneath" its nesting level. For example:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Notice that <tt>B</tt> is declared in a new code block. That means <tt>B</tt> is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, <tt>B</tt> is no longer valid.

=Dynamic Arrays=
Dynamic arrays are arrays which don't have a hardcoded size. For example:

<pawn>Function1(size)
{
new array[size];

/* Code */
}</pawn>

Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.

Dynamic arrays are only valid at the local scope level, since code cannot exist globally.

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:SourceMod Scripting]]

User:TheY4Kman

2008-03-02T05:10:33Z

TheY4Kman: Redid SourceMod links

This information is from [http://en.wikipedia.org/wiki/User:TheY4Kman Wikipedia].

Zach "theY4Kman" Kanzler is the owner of [http://y4kstudios.com Y4K Studios]. He is a programmer most notable for his work in [http://cheatsync.net CheatSync] and [[SOURCEMOD|SourceMod]].

==Projects==
theY4Kman has worked on several major projects, and some smaller ones.

===CheatSync===
With the advent of [http://cheatdevice.com CheatDevice] by edisoncarter, the cheats created for it were spread across the web. On [http://gtaforums.com the GTA Forums], ADePSP and theY4Kman discussed creating a database for all the new cheats. theY4Kman wrote the website front-end for it, and hosted it on his site. It was a very basic form, consisting of an author field, a name field, a description field, and a cheat field. ADePSP wrote the desktop application for it, in [[Delphi]]. As the new database was about to be released, theY4Kman thought up the name "[http://cheatsync.net CheatSync]."

[http://cheatsync.net CheatSync] was a huge hit. Hundreds of users contributed thousands of cheats. The crummy front-end and buggy program couldn't deal with the load. edisoncarter purchased [http://cheatsync.net cheatsync.net] for ADePSP. ADe programmed an online version of [http://cheatsync.net CheatSync], in the [[PHP]] language. At this point, theY4Kman was no longer necessary.

Zach offered to create a version of CheatSync which used AJAX, but the project quickly ended, due to lack of time.

===EventScripts===
Zach became addicted to [[Source engine|Source]] games (e.g., [[Counter-Strike: Source|CS:S]] and [[Half-Life 2|HL2]]). With his programming background, plug-ins like [[EventScripts ]] and [[SOURCEMOD|SourceMod]]. At first, he experimented with [[EventScripts]]. However, he did not appreciate the lack of performance it held and its heavily scripted language. This led to his delving into [[SOURCEMOD|SourceMod]].

===SourceMod===
Upon learning '''SourcePawn''' (The language of [[SOURCEMOD|SourceMod]], based off [[Pawn (programming language)|Pawn]]), theY4Kman wrote the plug-in "[http://forums.alliedmods.net/showthread.php?t=56376 Maplister]." It was a very simple program, that printed out all the maps available on a [[Source engine|Source]] game server. After his first plug-in, he developed a few more plug-ins, such as [http://forums.alliedmods.net/showthread.php?t=56264 Weapon Rewards Advanced], [http://forums.alliedmods.net/showthread.php?t=60146 CommandReact], [http://forums.alliedmods.net/showthread.php?t=56778 UserRestrict], and [http://forums.alliedmods.net/showthread.php?t=56960 EventInfo]. His latest plug-in is [http://forums.alliedmods.net/showthread.php?t=67098 Triggers], which provides [http://www.mani-admin-plugin.com/mani_admin_plugin/documentation/mani_install_config_commandlist.htm commandlist.txt] functionality to [[SOURCEMOD|SourceMod]] users.

====Viper====
One of his latest projects is an extension of [[SOURCEMOD|SourceMod]]. Viper is a program written in C++, which allows [[SOURCEMOD|SourceMod]] developers to code plug-ins with Python, instead of [[SOURCEMOD|SM]]'s native language, SourcePawn.

The project took off the in IRC channel [irc://irc.gamesurge.net/sourcemod #sourcemod]. One of the members bet theY4Kman that he couldn't do it. However, Viper is being actively developed now.

Originally, Viper was named "SMPython," for "SourceMod Python." To Zach, though, it seemed very generic. A week or so after the title "SMPython" was given, the project was renamed to "Viper." The new name came from the [[Viperidae|snake family]] and the user "Viper," who is an active member of [irc://irc.gamesurge.net/sourcemod #sourcemod].

==Pronunciation==
'''theY4Kman''' means "the year 4000 man." The simplification of "Year 4000" to '''Y4K''' was derived from "Y2K", meaning "Year 2000". Thus, '''Y4K''' is actually pronounced "Why Four Kay," not "Yak." This common mistake originates from the notion that frequent internet users speak [[Leet|Leetspeak]]. However, using "Yak" is accepted.

User:TheY4Kman

2008-03-02T05:08:55Z

TheY4Kman: Added it all!

This information is from [http://en.wikipedia.org/wiki/User:TheY4Kman Wikipedia].

Zach "theY4Kman" Kanzler is the owner of [http://y4kstudios.com Y4K Studios]. He is a programmer most notable for his work in [http://cheatsync.net CheatSync] and [[Sourcemod|SourceMod]].

==Projects==
theY4Kman has worked on several major projects, and some smaller ones.

===CheatSync===
With the advent of [http://cheatdevice.com CheatDevice] by edisoncarter, the cheats created for it were spread across the web. On [http://gtaforums.com the GTA Forums], ADePSP and theY4Kman discussed creating a database for all the new cheats. theY4Kman wrote the website front-end for it, and hosted it on his site. It was a very basic form, consisting of an author field, a name field, a description field, and a cheat field. ADePSP wrote the desktop application for it, in [[Delphi]]. As the new database was about to be released, theY4Kman thought up the name "[http://cheatsync.net CheatSync]."

[http://cheatsync.net CheatSync] was a huge hit. Hundreds of users contributed thousands of cheats. The crummy front-end and buggy program couldn't deal with the load. edisoncarter purchased [http://cheatsync.net cheatsync.net] for ADePSP. ADe programmed an online version of [http://cheatsync.net CheatSync], in the [[PHP]] language. At this point, theY4Kman was no longer necessary.

Zach offered to create a version of CheatSync which used AJAX, but the project quickly ended, due to lack of time.

===EventScripts===
Zach became addicted to [[Source engine|Source]] games (e.g., [[Counter-Strike: Source|CS:S]] and [[Half-Life 2|HL2]]). With his programming background, plug-ins like [[EventScripts ]] and [[Sourcemod|SourceMod]]. At first, he experimented with [[EventScripts]]. However, he did not appreciate the lack of performance it held and its heavily scripted language. This led to his delving into [[Sourcemod|SourceMod]].

===SourceMod===
Upon learning '''SourcePawn''' (The language of [[Sourcemod|SourceMod]], based off [[Pawn (programming language)|Pawn]]), theY4Kman wrote the plug-in "[http://forums.alliedmods.net/showthread.php?t=56376 Maplister]." It was a very simple program, that printed out all the maps available on a [[Source engine|Source]] game server. After his first plug-in, he developed a few more plug-ins, such as [http://forums.alliedmods.net/showthread.php?t=56264 Weapon Rewards Advanced], [http://forums.alliedmods.net/showthread.php?t=60146 CommandReact], [http://forums.alliedmods.net/showthread.php?t=56778 UserRestrict], and [http://forums.alliedmods.net/showthread.php?t=56960 EventInfo]. His latest plug-in is [http://forums.alliedmods.net/showthread.php?t=67098 Triggers], which provides [http://www.mani-admin-plugin.com/mani_admin_plugin/documentation/mani_install_config_commandlist.htm commandlist.txt] functionality to [[Sourcemod|SourceMod]] users.

====Viper====
One of his latest projects is an extension of [[Sourcemod|SourceMod]]. Viper is a program written in C++, which allows [[Sourcemod|SourceMod]] developers to code plug-ins with Python, instead of [[Sourcemod|SM]]'s native language, SourcePawn.

The project took off the in IRC channel [irc://irc.gamesurge.net/sourcemod #sourcemod]. One of the members bet theY4Kman that he couldn't do it. However, Viper is being actively developed now.

Originally, Viper was named "SMPython," for "SourceMod Python." To Zach, though, it seemed very generic. A week or so after the title "SMPython" was given, the project was renamed to "Viper." The new name came from the [[Viperidae|snake family]] and the user "Viper," who is an active member of [irc://irc.gamesurge.net/sourcemod #sourcemod].

==Pronunciation==
'''theY4Kman''' means "the year 4000 man." The simplification of "Year 4000" to '''Y4K''' was derived from "Y2K", meaning "Year 2000". Thus, '''Y4K''' is actually pronounced "Why Four Kay," not "Yak." This common mistake originates from the notion that frequent internet users speak [[Leet|Leetspeak]]. However, using "Yak" is accepted.

Optimizing Plugins (SourceMod Scripting)

2008-03-02T04:47:06Z

TheY4Kman: /* Stock */ Clarified "include"

==Introduction==
SourceMod is pretty fast, but there are some common assumptions about scripts:
*You can't possibly make it any faster.
*It's pre-compiled, so it's already quite fast.
*Details don't matter, as it's only "scripting" anyway.

None of these are true. The compiler, in fact, is very poor at optimizing, and the JIT is left to do most of the work. You can '''greatly''' increase the speed and efficiency of your plugins by keeping a few rules in mind. Remember - it's more important to minimize instructions than it is to minimize lines of code.

Note that many of these optimizations should be taken in context. An admin command probably doesn't need fine-tuned optimizations. But a timer that executes every 0.1 seconds, or a GameFrame hook, should definitely be as fast as possible.

=Always Save Results=
Observe the example code snippet below:
<pawn>if (GetClientTeam(player) == 3)
{
//...code
}
else if (GetClientTeam(player) == 2)
{
//...code
}
else if (GetClientTeam(player) == 1)
{
//...code
}</pawn>
This is a mild example of "cache your results". When the compiler generates assembly for this code, it will (in pseudo code) generate:
<pre>
CALL GetClientTeam
COMPARE+JUMP
CALL GetClientTeam
COMPARE+JUMP
CALL GetClientTeam
COMPARE+JUMP
</pre>
Notice the problem? We have called <tt>GetClientTeam</tt> an extra two times than necessary. The result doesn't change, so we can save it. Observe:
<pawn>new team = GetClientTeam(player)
if (team == 3)
{
//...code
}
else if (team == 2)
{
//...code
}
else if (team == 1)
{
//...code
}</pawn>
Now, the compiler will only generate this:
<pre>
CALL get_user_team
COMPARE+JUMP
COMPARE+JUMP
COMPARE+JUMP
</pre>
If <tt>GetClientTeam</tt> were a more expensive operation (it's relatively cheap), we would have recalculated the entire result each branch of the <tt>if</tt> case, wasting CPU cycles.

Similarly, this type of code is usually not a good idea:
<pre>for (new i = 0; i < strlen(string); i++) ....
</pre>

Better code is:
<pre>new len = strlen(string);
for (new i = 0; i < len; i++)</pre>

Similarly, you may not want to put <tt>GetMaxClients()</tt> in a loop about players. While it is a very cheap function call, it incurs the cost of a native call, which might be significant in highly performance-sensitive code.

=Switch instead of If=
If you can, you should use <tt>switch</tt> cases instead of <tt>if</tt>. This is because for an <tt>if</tt> statement, the compiler must branch to each consecutive <tt>if</tt> case. Using the example from above, observe the switch version:
<pawn>new team = GetClientTeam(player)
switch (team)
{
case 3:
//code...
case 2:
//code...
case 1:
//code...
}</pawn>
This will generate what's called a "case table". Rather than worm through displaced <tt>if</tt> tests, the compiler generates a table of possible values. The JIT is smart enough to optimize this even further, and the best case is:
<pre>
JUMP Table[CALL GetUserTeam]
</pre>

If your switch cases are listed in perfectly sequential order (that is, skipping no numbers, either ascending or descending), the JIT can make the best optimizations. For example, "7,8,9" and "2,1,0" are examples of perfect switch cases. "1,3,4" is not.

=Don't Re-index Arrays=
A common practice in Pawn is to "save space" by re-indexing arrays. There are a few myths behind this, such as saving memory, assuming the compiler does it for you, or readability. Fact: none of these are true. Observe the code below.
<pawn>SomeFunction(const clients[], num_clients)
{
for (new i = 0; i < num_clients; i++)
{
if (!IsClientInGame(clients[i]))
{
continue;
}
SetSomething(clients[i], GetSomething(clients[i]) + 1);
}
}
</pawn>

For this, the compiler generates code similar to:

<pre>
:LOOP_BEGIN
LOAD i
LOAD clients
CALC
LOAD clients[i]
CALL IsClientInGame
LOAD i
LOAD clients
CALC
LOAD clients[i]
CALL GetSomething
LOAD i
LOAD players
CALC
LOAD players[i]
CALL SetSomething
</pre>

See what happened? The compiler does not cache array indexing. Because we've used <tt>clients[i]</tt> each time, every instance generates 4-6 (or more) instructions which load <tt>i</tt>, the address of <tt>clients</tt>, computes the final location, and then grabs the data out of memory. It is much faster to do:

<pawn>SomeFunction(const clients[], num_clients)
{
new client;
for (new i = 0; i < num_clients; i++)
{
client = clients[i];
if (!IsClientInGame(client))
{
continue;
}
SetSomething(client, GetSomething(client) + 1);
}
}
</pawn>

Not only is this more readable, but look at how much cruft we've shaved off the compiler's generated code:
<pre>
:LOOP_BEGIN
LOAD i
LOAD clients
CALC
LOAD clients[i]
STORE client
CALL IsClientInGame
LOAD client
CALL GetSomething
LOAD client
CALL SetSomething
</pre>
In a large loop you can drastically reduce codesize in this manner.

=Decl on Local Arrays=
There is a small caveat to the 'new' statement in Pawn; it automatically writes a zero for every byte in the data structure. For example:

<pawn>new String:elephant[512];</pawn>

If placed inside local scope, all 512 bytes of the variable will be cleared every time the variable is created. In a performance-sensitive callback, this could be disastrous. Even something as innocuous as:

<pawn>new temp_players[MAX_PLAYERS];</pawn>

Could be a significant slow-down if called too often. To solve this, SourceMod has a special replacement for <tt>new</tt> called <tt>decl</tt>. Unlike <tt>new</tt>, <tt>decl</tt> does not bother setting the entire array or structure to zero. Thus, the data will be filled with random garbage.

While this is much faster, you must be careful to initialize the data before you use it. Observe the following code:

<pawn>decl String:my_string[256];

if (Something())
{
Format(my_string, sizeof(my_string), "clam");
}

PrintToChat(client, "%s", my_string);</pawn>

Notice the bug? If <tt>Something()</tt> returned false, <tt>my_string</tt> would still have garbage in it. Thus, you must always take care and make sure that you might not accidentally be reading from uninitialized data. Once that happens, you will get undefined behavior and possibly even crashes.

A common practice is to short-initialize strings. For example:
<pawn>decl String:my_string[256];
my_string[0] = '\0';</pawn>

This sets the first byte of the string to zero, which makes sure the string will be read as a valid, but empty, string.

Note that <tt>decl</tt> will work on any local variable type (array, string, float, integer, et cetera). The one thing it cannot be used for is initialization. This is invalid:

<pawn>decl var = 5;</pawn>

Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. You must use <tt>new</tt> in order to do initialize:

<pawn>new var = 5;</pawn>

=Avoid Large KeyValues=
KeyValues is an n-ary structure using linked lists. This type of structure is extremely expensive to allocate and traverse. While it might be suitable for tiny pieces of information (that is, under 10KB of data or so), its complexity growth is very poor.

If you load KeyValues data, you should make an effort to, at the very least, cache its Handle so you don't need to reparse the file every time. Caching its contents on a needed basis would be a bonus as well.

If you're trying to use a KeyValues file with thousands of entries and updating/loading it on events such as player connections or disconnections, you will find that the structure will grow to an unmanageably slow size. If that's the case, you should consider moving to something like SQLite or MySQL.

=Use Stock/Public Correctly=
Using <tt>stock</tt> and <tt>public</tt> correctly won't necessarily optimize your plugin, but they will help your code be more maintainable and will eliminate extra exports/data being written to your plugin file.

==Stock==
A <tt>stock</tt> function is compiled, but only written to the plugin's binary if it's used. Generally, you should use the <tt>stock</tt> keyword if:
*You may use the function in the future, and don't want the compiler telling you it's never used;
*You are writing an include file and don't want the function put in the binary if it's never used.

==Public==
A <tt>public</tt> function is exported externally. Every plugin binary has a list of all its <tt>public</tt> functions, and Core uses this table whenever it needs to find a matching <tt>forward</tt>.

Generally, there are only two reasons you should ever use <tt>public</tt>:
*You are implementing a <tt>forward</tt>.
*You are implementing a callback to another function, and it requires you to use <tt>public</tt>.

It seems common for users to randomly add <tt>public</tt> to completely private functions -- not only is that unnecessary, but it only adds to the amount of work Core has to do to find functions in your plugin.

=Conclusion=
Although optimization is important, you should always keep context in mind. Don't replace every single <tt>new</tt> in your plugin with <tt>decl</tt> just because it might be faster. Identify the areas of your plugin where optimization is significant, and tweak from there.

[[Category:SourceMod Scripting]]

Optimizing Plugins (SourceMod Scripting)

2008-03-02T04:39:55Z

TheY4Kman: /* Decl on Local Arrays */ Uh, fuck. Forgot to close the <tt> tag

==Introduction==
SourceMod is pretty fast, but there are some common assumptions about scripts:
*You can't possibly make it any faster.
*It's pre-compiled, so it's already quite fast.
*Details don't matter, as it's only "scripting" anyway.

None of these are true. The compiler, in fact, is very poor at optimizing, and the JIT is left to do most of the work. You can '''greatly''' increase the speed and efficiency of your plugins by keeping a few rules in mind. Remember - it's more important to minimize instructions than it is to minimize lines of code.

Note that many of these optimizations should be taken in context. An admin command probably doesn't need fine-tuned optimizations. But a timer that executes every 0.1 seconds, or a GameFrame hook, should definitely be as fast as possible.

=Always Save Results=
Observe the example code snippet below:
<pawn>if (GetClientTeam(player) == 3)
{
//...code
}
else if (GetClientTeam(player) == 2)
{
//...code
}
else if (GetClientTeam(player) == 1)
{
//...code
}</pawn>
This is a mild example of "cache your results". When the compiler generates assembly for this code, it will (in pseudo code) generate:
<pre>
CALL GetClientTeam
COMPARE+JUMP
CALL GetClientTeam
COMPARE+JUMP
CALL GetClientTeam
COMPARE+JUMP
</pre>
Notice the problem? We have called <tt>GetClientTeam</tt> an extra two times than necessary. The result doesn't change, so we can save it. Observe:
<pawn>new team = GetClientTeam(player)
if (team == 3)
{
//...code
}
else if (team == 2)
{
//...code
}
else if (team == 1)
{
//...code
}</pawn>
Now, the compiler will only generate this:
<pre>
CALL get_user_team
COMPARE+JUMP
COMPARE+JUMP
COMPARE+JUMP
</pre>
If <tt>GetClientTeam</tt> were a more expensive operation (it's relatively cheap), we would have recalculated the entire result each branch of the <tt>if</tt> case, wasting CPU cycles.

Similarly, this type of code is usually not a good idea:
<pre>for (new i = 0; i < strlen(string); i++) ....
</pre>

Better code is:
<pre>new len = strlen(string);
for (new i = 0; i < len; i++)</pre>

Similarly, you may not want to put <tt>GetMaxClients()</tt> in a loop about players. While it is a very cheap function call, it incurs the cost of a native call, which might be significant in highly performance-sensitive code.

=Switch instead of If=
If you can, you should use <tt>switch</tt> cases instead of <tt>if</tt>. This is because for an <tt>if</tt> statement, the compiler must branch to each consecutive <tt>if</tt> case. Using the example from above, observe the switch version:
<pawn>new team = GetClientTeam(player)
switch (team)
{
case 3:
//code...
case 2:
//code...
case 1:
//code...
}</pawn>
This will generate what's called a "case table". Rather than worm through displaced <tt>if</tt> tests, the compiler generates a table of possible values. The JIT is smart enough to optimize this even further, and the best case is:
<pre>
JUMP Table[CALL GetUserTeam]
</pre>

If your switch cases are listed in perfectly sequential order (that is, skipping no numbers, either ascending or descending), the JIT can make the best optimizations. For example, "7,8,9" and "2,1,0" are examples of perfect switch cases. "1,3,4" is not.

=Don't Re-index Arrays=
A common practice in Pawn is to "save space" by re-indexing arrays. There are a few myths behind this, such as saving memory, assuming the compiler does it for you, or readability. Fact: none of these are true. Observe the code below.
<pawn>SomeFunction(const clients[], num_clients)
{
for (new i = 0; i < num_clients; i++)
{
if (!IsClientInGame(clients[i]))
{
continue;
}
SetSomething(clients[i], GetSomething(clients[i]) + 1);
}
}
</pawn>

For this, the compiler generates code similar to:

<pre>
:LOOP_BEGIN
LOAD i
LOAD clients
CALC
LOAD clients[i]
CALL IsClientInGame
LOAD i
LOAD clients
CALC
LOAD clients[i]
CALL GetSomething
LOAD i
LOAD players
CALC
LOAD players[i]
CALL SetSomething
</pre>

See what happened? The compiler does not cache array indexing. Because we've used <tt>clients[i]</tt> each time, every instance generates 4-6 (or more) instructions which load <tt>i</tt>, the address of <tt>clients</tt>, computes the final location, and then grabs the data out of memory. It is much faster to do:

<pawn>SomeFunction(const clients[], num_clients)
{
new client;
for (new i = 0; i < num_clients; i++)
{
client = clients[i];
if (!IsClientInGame(client))
{
continue;
}
SetSomething(client, GetSomething(client) + 1);
}
}
</pawn>

Not only is this more readable, but look at how much cruft we've shaved off the compiler's generated code:
<pre>
:LOOP_BEGIN
LOAD i
LOAD clients
CALC
LOAD clients[i]
STORE client
CALL IsClientInGame
LOAD client
CALL GetSomething
LOAD client
CALL SetSomething
</pre>
In a large loop you can drastically reduce codesize in this manner.

=Decl on Local Arrays=
There is a small caveat to the 'new' statement in Pawn; it automatically writes a zero for every byte in the data structure. For example:

<pawn>new String:elephant[512];</pawn>

If placed inside local scope, all 512 bytes of the variable will be cleared every time the variable is created. In a performance-sensitive callback, this could be disastrous. Even something as innocuous as:

<pawn>new temp_players[MAX_PLAYERS];</pawn>

Could be a significant slow-down if called too often. To solve this, SourceMod has a special replacement for <tt>new</tt> called <tt>decl</tt>. Unlike <tt>new</tt>, <tt>decl</tt> does not bother setting the entire array or structure to zero. Thus, the data will be filled with random garbage.

While this is much faster, you must be careful to initialize the data before you use it. Observe the following code:

<pawn>decl String:my_string[256];

if (Something())
{
Format(my_string, sizeof(my_string), "clam");
}

PrintToChat(client, "%s", my_string);</pawn>

Notice the bug? If <tt>Something()</tt> returned false, <tt>my_string</tt> would still have garbage in it. Thus, you must always take care and make sure that you might not accidentally be reading from uninitialized data. Once that happens, you will get undefined behavior and possibly even crashes.

A common practice is to short-initialize strings. For example:
<pawn>decl String:my_string[256];
my_string[0] = '\0';</pawn>

This sets the first byte of the string to zero, which makes sure the string will be read as a valid, but empty, string.

Note that <tt>decl</tt> will work on any local variable type (array, string, float, integer, et cetera). The one thing it cannot be used for is initialization. This is invalid:

<pawn>decl var = 5;</pawn>

Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. You must use <tt>new</tt> in order to do initialize:

<pawn>new var = 5;</pawn>

=Avoid Large KeyValues=
KeyValues is an n-ary structure using linked lists. This type of structure is extremely expensive to allocate and traverse. While it might be suitable for tiny pieces of information (that is, under 10KB of data or so), its complexity growth is very poor.

If you load KeyValues data, you should make an effort to, at the very least, cache its Handle so you don't need to reparse the file every time. Caching its contents on a needed basis would be a bonus as well.

If you're trying to use a KeyValues file with thousands of entries and updating/loading it on events such as player connections or disconnections, you will find that the structure will grow to an unmanageably slow size. If that's the case, you should consider moving to something like SQLite or MySQL.

=Use Stock/Public Correctly=
Using <tt>stock</tt> and <tt>public</tt> correctly won't necessarily optimize your plugin, but they will help your code be more maintainable and will eliminate extra exports/data being written to your plugin file.

==Stock==
A <tt>stock</tt> function is compiled, but only written to the plugin's binary if it's used. Generally, you should use the <tt>stock</tt> keyword if:
*You may use the function in the future, and don't want the compiler telling you it's never used;
*You are writing an include file and don't want the function compiled if it's never used.

==Public==
A <tt>public</tt> function is exported externally. Every plugin binary has a list of all its <tt>public</tt> functions, and Core uses this table whenever it needs to find a matching <tt>forward</tt>.

Generally, there are only two reasons you should ever use <tt>public</tt>:
*You are implementing a <tt>forward</tt>.
*You are implementing a callback to another function, and it requires you to use <tt>public</tt>.

It seems common for users to randomly add <tt>public</tt> to completely private functions -- not only is that unnecessary, but it only adds to the amount of work Core has to do to find functions in your plugin.

=Conclusion=
Although optimization is important, you should always keep context in mind. Don't replace every single <tt>new</tt> in your plugin with <tt>decl</tt> just because it might be faster. Identify the areas of your plugin where optimization is significant, and tweak from there.

[[Category:SourceMod Scripting]]

Optimizing Plugins (SourceMod Scripting)

2008-03-02T04:39:01Z

TheY4Kman: /* Decl on Local Arrays */ Edited for consistency of semicolons and clarification on intialization.

==Introduction==
SourceMod is pretty fast, but there are some common assumptions about scripts:
*You can't possibly make it any faster.
*It's pre-compiled, so it's already quite fast.
*Details don't matter, as it's only "scripting" anyway.

None of these are true. The compiler, in fact, is very poor at optimizing, and the JIT is left to do most of the work. You can '''greatly''' increase the speed and efficiency of your plugins by keeping a few rules in mind. Remember - it's more important to minimize instructions than it is to minimize lines of code.

Note that many of these optimizations should be taken in context. An admin command probably doesn't need fine-tuned optimizations. But a timer that executes every 0.1 seconds, or a GameFrame hook, should definitely be as fast as possible.

=Always Save Results=
Observe the example code snippet below:
<pawn>if (GetClientTeam(player) == 3)
{
//...code
}
else if (GetClientTeam(player) == 2)
{
//...code
}
else if (GetClientTeam(player) == 1)
{
//...code
}</pawn>
This is a mild example of "cache your results". When the compiler generates assembly for this code, it will (in pseudo code) generate:
<pre>
CALL GetClientTeam
COMPARE+JUMP
CALL GetClientTeam
COMPARE+JUMP
CALL GetClientTeam
COMPARE+JUMP
</pre>
Notice the problem? We have called <tt>GetClientTeam</tt> an extra two times than necessary. The result doesn't change, so we can save it. Observe:
<pawn>new team = GetClientTeam(player)
if (team == 3)
{
//...code
}
else if (team == 2)
{
//...code
}
else if (team == 1)
{
//...code
}</pawn>
Now, the compiler will only generate this:
<pre>
CALL get_user_team
COMPARE+JUMP
COMPARE+JUMP
COMPARE+JUMP
</pre>
If <tt>GetClientTeam</tt> were a more expensive operation (it's relatively cheap), we would have recalculated the entire result each branch of the <tt>if</tt> case, wasting CPU cycles.

Similarly, this type of code is usually not a good idea:
<pre>for (new i = 0; i < strlen(string); i++) ....
</pre>

Better code is:
<pre>new len = strlen(string);
for (new i = 0; i < len; i++)</pre>

Similarly, you may not want to put <tt>GetMaxClients()</tt> in a loop about players. While it is a very cheap function call, it incurs the cost of a native call, which might be significant in highly performance-sensitive code.

=Switch instead of If=
If you can, you should use <tt>switch</tt> cases instead of <tt>if</tt>. This is because for an <tt>if</tt> statement, the compiler must branch to each consecutive <tt>if</tt> case. Using the example from above, observe the switch version:
<pawn>new team = GetClientTeam(player)
switch (team)
{
case 3:
//code...
case 2:
//code...
case 1:
//code...
}</pawn>
This will generate what's called a "case table". Rather than worm through displaced <tt>if</tt> tests, the compiler generates a table of possible values. The JIT is smart enough to optimize this even further, and the best case is:
<pre>
JUMP Table[CALL GetUserTeam]
</pre>

If your switch cases are listed in perfectly sequential order (that is, skipping no numbers, either ascending or descending), the JIT can make the best optimizations. For example, "7,8,9" and "2,1,0" are examples of perfect switch cases. "1,3,4" is not.

=Don't Re-index Arrays=
A common practice in Pawn is to "save space" by re-indexing arrays. There are a few myths behind this, such as saving memory, assuming the compiler does it for you, or readability. Fact: none of these are true. Observe the code below.
<pawn>SomeFunction(const clients[], num_clients)
{
for (new i = 0; i < num_clients; i++)
{
if (!IsClientInGame(clients[i]))
{
continue;
}
SetSomething(clients[i], GetSomething(clients[i]) + 1);
}
}
</pawn>

For this, the compiler generates code similar to:

<pre>
:LOOP_BEGIN
LOAD i
LOAD clients
CALC
LOAD clients[i]
CALL IsClientInGame
LOAD i
LOAD clients
CALC
LOAD clients[i]
CALL GetSomething
LOAD i
LOAD players
CALC
LOAD players[i]
CALL SetSomething
</pre>

See what happened? The compiler does not cache array indexing. Because we've used <tt>clients[i]</tt> each time, every instance generates 4-6 (or more) instructions which load <tt>i</tt>, the address of <tt>clients</tt>, computes the final location, and then grabs the data out of memory. It is much faster to do:

<pawn>SomeFunction(const clients[], num_clients)
{
new client;
for (new i = 0; i < num_clients; i++)
{
client = clients[i];
if (!IsClientInGame(client))
{
continue;
}
SetSomething(client, GetSomething(client) + 1);
}
}
</pawn>

Not only is this more readable, but look at how much cruft we've shaved off the compiler's generated code:
<pre>
:LOOP_BEGIN
LOAD i
LOAD clients
CALC
LOAD clients[i]
STORE client
CALL IsClientInGame
LOAD client
CALL GetSomething
LOAD client
CALL SetSomething
</pre>
In a large loop you can drastically reduce codesize in this manner.

=Decl on Local Arrays=
There is a small caveat to the 'new' statement in Pawn; it automatically writes a zero for every byte in the data structure. For example:

<pawn>new String:elephant[512];</pawn>

If placed inside local scope, all 512 bytes of the variable will be cleared every time the variable is created. In a performance-sensitive callback, this could be disastrous. Even something as innocuous as:

<pawn>new temp_players[MAX_PLAYERS];</pawn>

Could be a significant slow-down if called too often. To solve this, SourceMod has a special replacement for <tt>new</tt> called <tt>decl</tt>. Unlike <tt>new</tt>, <tt>decl</tt> does not bother setting the entire array or structure to zero. Thus, the data will be filled with random garbage.

While this is much faster, you must be careful to initialize the data before you use it. Observe the following code:

<pawn>decl String:my_string[256];

if (Something())
{
Format(my_string, sizeof(my_string), "clam");
}

PrintToChat(client, "%s", my_string);</pawn>

Notice the bug? If <tt>Something()</tt> returned false, <tt>my_string</tt> would still have garbage in it. Thus, you must always take care and make sure that you might not accidentally be reading from uninitialized data. Once that happens, you will get undefined behavior and possibly even crashes.

A common practice is to short-initialize strings. For example:
<pawn>decl String:my_string[256];
my_string[0] = '\0';</pawn>

This sets the first byte of the string to zero, which makes sure the string will be read as a valid, but empty, string.

Note that <tt>decl</tt> will work on any local variable type (array, string, float, integer, et cetera). The one thing it cannot be used for is initialization. This is invalid:

<pawn>decl var = 5;</pawn>

Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. You must use <tt>new<tt> in order to do initialize:

<pawn>new var = 5;</pawn>

=Avoid Large KeyValues=
KeyValues is an n-ary structure using linked lists. This type of structure is extremely expensive to allocate and traverse. While it might be suitable for tiny pieces of information (that is, under 10KB of data or so), its complexity growth is very poor.

If you load KeyValues data, you should make an effort to, at the very least, cache its Handle so you don't need to reparse the file every time. Caching its contents on a needed basis would be a bonus as well.

If you're trying to use a KeyValues file with thousands of entries and updating/loading it on events such as player connections or disconnections, you will find that the structure will grow to an unmanageably slow size. If that's the case, you should consider moving to something like SQLite or MySQL.

=Use Stock/Public Correctly=
Using <tt>stock</tt> and <tt>public</tt> correctly won't necessarily optimize your plugin, but they will help your code be more maintainable and will eliminate extra exports/data being written to your plugin file.

==Stock==
A <tt>stock</tt> function is compiled, but only written to the plugin's binary if it's used. Generally, you should use the <tt>stock</tt> keyword if:
*You may use the function in the future, and don't want the compiler telling you it's never used;
*You are writing an include file and don't want the function compiled if it's never used.

==Public==
A <tt>public</tt> function is exported externally. Every plugin binary has a list of all its <tt>public</tt> functions, and Core uses this table whenever it needs to find a matching <tt>forward</tt>.

Generally, there are only two reasons you should ever use <tt>public</tt>:
*You are implementing a <tt>forward</tt>.
*You are implementing a callback to another function, and it requires you to use <tt>public</tt>.

It seems common for users to randomly add <tt>public</tt> to completely private functions -- not only is that unnecessary, but it only adds to the amount of work Core has to do to find functions in your plugin.

=Conclusion=
Although optimization is important, you should always keep context in mind. Don't replace every single <tt>new</tt> in your plugin with <tt>decl</tt> just because it might be faster. Identify the areas of your plugin where optimization is significant, and tweak from there.

[[Category:SourceMod Scripting]]

Handle API (SourceMod)

2008-02-18T08:16:05Z

TheY4Kman: /* Reading/Checking Handles */ Changed "herr" to "err". "herr" does not exist!

The SourceMod [[Handles (SourceMod Scripting)|Handle System]] marshals pointers into typed, unique, 32-bit integers. This makes coding in SourceMod more cross-platform compatible, type safe, and mistake safe than its predecessor, [[AMX Mod X]]. It also allows for safe object sharing and reference count based object destruction.

The fundamental aspect of Handles is that they encapsulate a single pointer. This pointer is private data, and can only be read by the Handle's creator. When the Handle is freed, the pointer is automatically freed (via a special interface), thus ensuring that memory is not leaked.

Handles also provide a simple "security" system for restricting which areas of SourceMod are allowed to directly call certain functions on Handles under a given type.

=Basic Types=
==Handle_t==
The <tt>Handle_t</tt> type is a 32bit integer. Currently, it is composed of two 16-bit integers, a serial number and a handle index. The serial number is private and used for integrity checking. The index is the internal ID of the Handle, which is tied to the encapsulated pointer and security information.

Each <tt>Handle_t</tt> is a unique Handle, however, there are ''cloned'' Handles which are copies of another Handle. They have their own unique signatures, but they refer to another Handle internally. Each Handle is also associated with a ''type'', explained below.

==HandleType_t==
The <tt>HandleType_t</tt> describes a type under which Handles can be created. Types can have up to 15 sub-types; sub-types cannot have their own sub-types, called child types. When Handles are being read, they are "type checked," to make sure they are being read under a given type. When a type is destroyed, all Handles under the type are destroyed. If the type has child types, each child type is also destroyed.

Handle types also allow overloading of various Handle operations. Currently, the only overloaded action is for overloading when a Handle is destroyed. This allows the encapsulated pointer to be safely destroyed by the type interface. The interface which overloads type operations is called <tt>IHandleTypeDispatch</tt>.

Lastly, types provide a "default security" system which lets programmers restrict which functions can be accessed by other areas in SourceMod. This is explained later.

=Security=
'''Note:''' Type defaults can be set via <tt>IHandleSys::InitAccessDefaults()</tt>.

==Type Security==
Often, extensions may want to share HandleType_t values with each other, so they can create Handles of external types. However, the owner of the handle type may not want other extensions to perform certain actions. Thus, types can be ''secured'' by an <tt>IdentityToken_t</tt> when created. Unless the same <tt>IdentityToken</tt> is provided, a function may fail if restricted.

Type permissions are declared in a <tt>TypeAccess</tt> struct, which has the following user-set members:
*<tt>ident</tt>: The <tt>IdentityToken_t</tt> owner of this type.
*<tt>access</tt>: An array where each index is a <tt>HTypeAccessRight</tt> enumeration member. If an index is set to false, functions requiring that right will fail unless the correct <tt>IdentityToken_t</tt> is passed in.

The <tt>HTypeAccessRight</tt> enumeration has the following values:
*<tt>HTypeAccess_Create</tt>: Handle creation using this type; default is false.
*<tt>HTypeAccess_Inherit</tt>: Inheriting this type for child types; default is false.

Below is a list of each Handle System function that requires type permissions, and which permissions may be required:
*<tt>CreateType</tt>: <tt>HTypeAccess_Inherit</tt> if a parent is specified
*<tt>RemoveType</tt>: (none, always secured)
*<tt>CreateHandle</tt>: <tt>HTypeAccess_Create</tt>

==Handle Security==
Handle security permissions inherit from their parent type unless given an alternate set of permissions. Handles are "secured" by two properties, unlike Handles, which just have one. When verifying your identity with a secured Handle function, you must use the <tt>HandleSecurity</tt> struct, which has two properties:
*<tt>pOwner</tt>: The owner of the Handle, which is usually a plugin <tt>IdentityToken_t</tt>.
*<tt>pIdentity</tt>: The owner of the Handle's type, or the <tt>IdentityToken_t</tt> securing its type.

Handle permissions are specified via the <tt>HandleAccess</tt> struct. It is passed either through <tt>CreateType</tt> for default settings in a given type, or through <tt>CreateHandleEx</tt> for explicit per-Handle permissions. This struct has the following members:
*<tt>access</tt>: An array where each index is a <tt>HandleAccessRight</tt> enumeration member. If set to 0, an access right is allowed without a <tt>HandleSecurity</tt> instance. Otherwise, the following bitwise flags are checked:
**<tt>HANDLE_RESTRICT_IDENTITY</tt>: If flagged, this access right is only granted if the <tt>pIdentity</tt> member of the <tt>HandleSecurity</tt> struct matches the Handle's '''type's''' owner.
**<tt>HANDLE_RESTRICT_OWNER</tt>: If flagged, this access right is onyl granted if the <tt>pOwner</tt> member of the <tt>Handlesecurity</tt> struct matches the Handle's owner.

The following access rights exist for Handles:
*<tt>HandleAccess_Read</tt>: This Handle's encapsulated pointer can be retrieved. Defaults to <tt>HANDLE_RESTRICT_IDENTITY</tt>.
*<tt>HandleAccess_Delete</tt>: This Handle can be removed or freed. Defaults to <tt>HANDLE_RESTRICT_OWNER</tt>.
*<tt>HandleAccess_Clone</tt>: This Handle can be cloned. Defaults to 0.

Below is a list of each Handle system function that requires permissions, and which permissions may be required:
*<tt>FreeHandle</tt>: <tt>HandleAccess_Delete</tt>
*<tt>CloneHandle/CloneHandleEx</tt>: <tt>HandleAccess_Clone</tt>
*<tt>ReadHandle</tt>: <tt>HandleAccess_Read</tt>

SourceMod's generic native wrappers assume follow these rules, however, they assume certain access rights, and will return <tt>INVALID_HANDLE</tt> or 0 if these rights are denied. Thus, you should make sure your permissions are compatible, unless you explicitly want to deny usage of these functions.
*<tt>CloneHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity</tt>, meaning <tt>HandleAccess_Clone</tt> must be 0.
*<tt>CloseHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity::pIdentity</tt>, and the plugin's <tt>IdentityToken_t</tt> for <tt>HandleSecurity::pOwner</tt/>. This means that at most, the only restriction can be <tt>HANDLE_RESTRICT_OWNER</tt> for <tt>HandleAccess_Delete</tt>.

=Usage Examples=
Here are some examples of Handle usages.

==Basic Handles==
The most basic use of Handles is to encapsulate a data structure and allow <tt>CloseHandle</tt> to universally destroy it. Let's say we want to implement two natives - <tt>CreateFile</tt> for creating an empty file, and <tt>WriteLine</tt> for writing a line to this file. How could we implement this using the Handle system?

After reading this, it is tempting to think, "Why can't we just return the <tt>FILE</tt> pointer as a <tt>cell_t</tt>?" The reason is that a <tt>cell_t</tt> is guaranteed to be a 32bit integer. There is no guarantee that a pointer will always be this size, however, and thus casting on future platforms could break. This problem happened in [[AMX Mod X]] and greatly restricted flexibility.

===Creating the type===
First, we have to create the type and its Dispatch interface.
<cpp>HandleType_t g_FileType = 0; /* Holds the HandleType ID */

class FileTypeHandler : public IHandleTypeDispatch
{
public:
void OnHandleDestroy(HandleType_t type, void *object)
{
/* :TODO: implement this */
}
};

/* Create an instance of the handler */
FileTypeHandler g_FileTypeHandler;

Initialize()
{
/* Register the type with default security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
NULL,
myself->GetIdentity(),
NULL);
}

Shutdown()
{
/* Remove the type on shutdown */
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());
}</cpp>

===Creating Handles===
Creating the Handles is fairly easy once we have a valid pointer to stuff in it.
<cpp>/* native CreateFile(const String:file[]) */
static cell_t sm_CreateFile(IPluginContext *pContext, const cell_t *params)
{
char path[PLATFORM_MAX_PATH];
char *filename;

/* Get the filename */
pContext->LocalToString(params[1], &filename);
/* Build a full path */
g_pSM->BuildPath(Path_SM, path, sizeof(path), "%s", filename);

/* Open for writing */
FILE *fp = fopen(path, "wt");
if (!fp)
{
return BAD_HANDLE;
}

/* Create the Handle with our type, the FILE pointer, the plugin's identity, and our identity */
return g_pHandleSys->CreateHandle(g_FileType,
fp,
pContext->GetIdentity(),
myself->GetIdentity(),
NULL);
}</cpp>

===Reading/Checking Handles===
Handles aren't very useful unless you have natives to use them. Let's say we want to write lines of text to our File type.
<cpp>/* native WriteLine(Handle:hndl, const String:line[]); */
static cell_t sm_WriteLine(IPluginContext *pContext, const cell_t *params)
{
Handle_t hndl = static_cast<Handle_t>(params[1]);
HandleError err;
HandleSecurity sec;

/* Build our security descriptor */
sec.pOwner = NULL; /* Not needed, owner access is not checked */
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */

/* Attempt to read the given handle as our type, using our security info.
* Note that we read the pointer directly in with a little cast.
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.
*/
FILE *fp;
if ((err = g_pHandleSys->ReadHandle(hndl, g_FileType, &sec, (void **)&fp))
!= HandleError_None)
{
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);
}

/* Get the text */
char *text;
pContext->LocalToString(params[2], &text);

/* Write it */
fputs(text, fp);

return 1;
}</cpp>

===CloseHandle Support===
Lastly, we need to make it so <tt>CloseHandle()</tt> or <tt>FreeHandle()</tt> will close our file pointer when removing the Handle, which we skipped before.
<cpp>class FileTypeHandler : public IHandleTypeDispatch
{
public:
void OnHandleDestroy(HandleType_t type, void *object)
{
fclose( (FILE *)object );
}
};</cpp>

==Restricting CloseHandle==
Let's say that, for various reasons, you don't want users to be able to call CloseHandle(). An example of this might be a data type that is non-temporary, or is being called from a forward, and thus should not be touched. Or, you might have a special deconstructor that takes extra parameters, and thus you need a separate destroy function.

For example, let's create a separate function called <tt>CloseFile</tt>. It doesn't do anything particularly special, but we are going to force its usage over CloseHandle().

===New Security Rules===
<cpp>Initialize()
{
/* Create default access rights */
HandleAccess rules;
g_pHandleSys->InitAccessDefaults(NULL, &rules);

/* Restrict delete to only our identity */
rules.access[HandleAccess_Delete] = HANDLE_RESTRICT_IDENTITY;

/* Register the type with our security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
&rules,
myself->GetIdentity(),
NULL);
}</cpp>

===Implementing the Native===
<cpp>/* native Closefile(Handle:hndl); */
static cell_t sm_CloseFile(IPluginContext *pContext, const cell_t *params)
{
Handle_t hndl = static_cast<Handle_t>(params[1]);
HandleError err;
HandleSecurity sec;

/* Build our security descriptor */
sec.pOwner = pContext->GetIdentity(); /* Needed, HANDLE_RESTRICT_OWNER is default */
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */

/* Attempt to read the given handle as our type, using our security info.
* Note that we read the pointer directly in with a little cast.
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.
*/
FILE *fp;
if ((herr = g_pHandleSys->FreeHandle(hndl, &src))
!= HandleError_None)
{
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);
}

return 1;
}</cpp>

==Restricting CloseHandle Per-Handle==
Taking our above example, it is possible that we might want some Handles to be closed via CloseHandle(), but others not. Again, this is useful if you wish to pass a Handle as read-only to a plugin, commonly done when using non-temporary structures or Handles used in Forwards.

In this example, we'll create a global instance of our file type, and this instance will be denied access to CloseHandle(), whereas files returned by OpenFile() will not.

===Implementation===
<cpp>Handle_t g_GlobalFile;

Initialize()
{
/* Register the type with default security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
NULL,
myself->GetIdentity(),
NULL);

/* Create our 'global' file */
FILE *fp = tmpfile();

/* Set up the security descriptor */
HandleSecurity sec;
sec.pOwner = NULL; /* No owner for this Handle */
sec.pIdentity = myself->GetIdentity(); /* Only this identity will be allowed */

/* Set up the access permissions */
HandleAccess rules;
g_pHandleSys->InitAccessDefaults(NULL, &rules);
rules.access[HandleAccess_Delete] |= HANDLE_RESTRICT_IDENTITY;

/* Finally, create the Handle with our rules */
g_GlobalFile = g_pHandleSys->CreateHandleEx(g_FileType, fp, &sec, &rules, NULL);
}

Shutdown()
{
/* Remove our global Handle (not needed, but we do it for clarity */
HandleSecurity sec;
sec.pOwner = NULL;
sec.pIdentity = myself->GetIdentity();

g_pHandleSys->FreeHandle(g_GlobalFile, &sec);

/* Remove the type on shutdown */
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());
}</cpp>

[[Category:SourceMod Development]]

Commands (SourceMod Scripting)

2007-12-16T19:17:54Z

TheY4Kman:

[[SourceMod]] allows you to create console commands similar to [[AMX Mod X]]. There are two main types of console commands:
*'''Server Commands''', which are 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''', which are 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 "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, listed in <tt>console.inc</tt>. When registering a server command, you may be hooking an already existing command, and thus whether you return <tt>Plugin_Handled</tt> or <tt>Plugin_Continue</tt> 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>: This 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>public OnPluginStart()
{
RegConsoleCmd("say", Command_Say)
}

public Action:Command_Say(client, args)
{
new String:text[192]
GetCmdArgString(text, sizeof(text))

new startidx = 0
if (text[0] == '"')
{
startidx = 1
/* Strip the ending quote, if there is one */
new len = strlen(text);
if (text[len-1] == '"')
{
text[len-1] = '\0'
}
}

if (StrEqual(text[startidx], "/ff"))
{
new Handle:ff = FindConVar("mp_friendlyfire")
if (GetConVarInt(ff))
{
PrintToConsole(client, "Friendly fire is enabled.")
} else {
PrintToConsole(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], maxplayers, target = -1
GetCmdArg(1, name, sizeof(name))

maxplayers = GetMaxClients()
for (new i=1; i<=maxplayers; 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], maxplayers, target = -1
GetCmdArg(1, name, sizeof(name))

maxplayers = GetMaxClients()
for (new i=1; i<=maxplayers; 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]]

Menu API (SourceMod)

2007-06-12T18:04:54Z

TheY4Kman: Fixed a few typos

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Basic Menu==
First, let's write our example using the Menu building API.

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

public MenuHandler1(Handle:menu, MenuAction:action, param1, param2)
{
/* Either Select or Cancel will ALWAYS be sent! */
if (action == MenuAction_Select)
{
new String:info[32]
new bool:found = GetMenuItem(menu, param2, info, sizeof(info))
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info)
} else if (action == MenuAction_Cancel) {
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2)
}

/* If the menu has ended, destroy it */
if (action == MenuAction_End)
{
CloseHandle(menu)
}
}

public Action:Menu_Test1(client, args)
{
new Handle:menu = CreateMenu(MenuHandler1)
SetMenuTitle(menu, "Do you like apples?")
AddMenuItem(menu, "yes", "Yes")
AddMenuItem(menu, "no", "No")
SetMenuExitButton(menu, false)
DisplayMenu(menu, client, 20)

return Plugin_Handled
}</pawn>

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

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

[[Image:Basic_menu_1.PNG]]

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

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

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

public Action:Panel_Test1(client, args)
{
new Handle:panel = CreatePanel();
SetPanelTitle(panel, "Do you like apples?")
DrawPanelItem(panel, "Yes")
DrawPanelItem(panel, "No")

SendPanelToClient(panel, client, PanelHandler1, 20)

CloseHandle(panel)

return Plugin_Handled
}</pawn>

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

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

[[Image:Basic_panel_1.PNG]]

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

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

Source code:
<pawn>new Handle:g_MapMenu = INVALID_HANDLE

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

public OnMapStart()
{
g_MapMenu = BuildMapMenu()
}

public OnMapEnd()
{
if (g_MapMenu != INVALID_HANDLE)
{
CloseHandle(g_MapMenu)
g_MapMenu = INVALID_HANDLE
}
}

Handle:BuildMapMenu()
{
/* Open the file */
new Handle:file = OpenFile("maplist.txt", "rt")
if (file == INVALID_HANDLE)
{
return INVALID_HANDLE
}

/* Create the menu Handle */
new Handle:menu = CreateMenu(Menu_ChangeMap);
new String:mapname[255]
while (!IsEndOfFile(file) && ReadFileLine(file, mapname, sizeof(mapname)))
{
if (mapname[0] == ';' || !IsCharAlpha(mapname[0]))
{
continue
}
/* Cut off the name at any whitespace */
new len = strlen(mapname)
for (new i=0; i<len; i++)
{
if (IsCharSpace(mapname[i]))
{
mapname[i] = '\0'
break
}
}
/* Check if the map is valid */
if (!IsMapValid(mapname))
{
continue
}
/* Add it to the menu */
AddMenuItem(menu, mapname, mapname)
}
/* Make sure we close the file! */
CloseHandle(file)

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

return menu
}

public Menu_ChangeMap(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
new String:info[32]

/* Get item info */
new bool:found = GetMenuItem(menu, param2, info, sizeof(info))

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

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

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

DisplayMenu(g_MapMenu, client, MENU_TIME_FOREVER)

return Plugin_Handled
}</pawn>

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

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

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

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

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

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

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

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

<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
new String:map[64]
GetMenuItem(menu, param1, map, sizeof(map))
ServerCommand("changelevel %s", map);
}
}
}

DoVoteMenu(const String:map[])
{
new Handle:menu = CreateMenu(Handle_VoteMenu)
SetMenuTitle(menu, "Change map to: %s?", map)
AddMenuItem(menu, map, "Yes")
AddMenuItem(menu, "no", "No")
SetMenuExitButton(menu, false)
VoteMenuToAll(menu, 20);
}</pawn>

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