AlliedModders Wiki - User contributions [en]

Introduction to SourceMod Plugins

2012-10-27T15:25:36Z

Bittersweet: /* Native implementation */ I guess you did mean Naive, but that's not really a good word for it - "Simple" is a better word

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

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

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

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

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

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

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

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

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

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

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

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

=Creating client command=
So far we have learned how to set up our plugin and run some code. But our plugin still doesn't do anything useful. Let's add a console command to allow clients to see their kills/deaths ratio. For demonstration purposes, we are going to start with very naive implementation that a beginner could write, then we'll look at the common bugs it contains, fix them and add more advanced features. In the end we'll have a mature feature-rich implementation and experience that will prevent us from making simple mistakes in the future.

==Naive implementation==
First, we need to register our console command. <tt>OnPluginStart</tt> is a good place to do that. In order to register our console command, we need to use <tt>RegConsoleCmd</tt> function, it is declared inside '''console.inc''', here's how it's declared:
<pawn>/**
* Creates a console command, or hooks an already existing one.
*
* Console commands are case sensitive. However, if the command already exists in the game,
* the a client may enter the command in any case. SourceMod corrects for this automatically,
* and you should only hook the "real" version of the command.
*
* @param cmd Name of the command to hook or create.
* @param callback A function to use as a callback for when the command is invoked.
* @param description Optional description to use for command creation.
* @param flags Optional flags to use for command creation.
* @noreturn
* @error Command name is the same as an existing convar.
*/
native RegConsoleCmd(const String:cmd[], ConCmd:callback, const String:description[]="", flags=0);</pawn>
This native looks a bit more complicated than the previous one, so let's go through each argument step by step. First one is the name of our command, we'll use <tt>"sm_kdr"</tt>. Second one is a callback, but it has unknown tag <tt>ConCmd</tt>. In order to correctly call <tt>RegConsoleCmd</tt> we need to find how <tt>ConCmd</tt> is declared. Thankfully, we don't need to look hard, it's declared right above <tt>RegConsoleCmd</tt>:
<pawn>/**
* Called when a generic console command is invoked.
*
* @param client Index of the client, or 0 from the server.
* @param args Number of arguments that were in the argument string.
* @return An Action value. Not handling the command
* means that Source will report it as "not found."
*/
functag public Action:ConCmd(client, args);</pawn>
This is a function tag. What does it mean? It means that we need to define our own function that will have the same prototype (number of arguments, their tags and return tag) as the one of function tag. However, in this case, we don't need to (and can't) use the same name as in tag, that would result in error. We need to use our own name, let's use <tt>Command_KDR</tt>. Function tags doesn't require to use the same argument names as specified in declaration, but it's a good idea to use them, because they usually have the most meaning. So, all in all, it leads us to the following definition:
<pawn>public Action:Command_KDR(client, args)
{
}</pawn>
Now, if you've been following carefully, you should see that we have another unknown tag here - <tt>Action</tt>. Let's look how it's declared ('''core.inc'''):
<pawn>/**
* Specifies what to do after a hook completes.
*/
enum Action
{
Plugin_Continue = 0, /**< Continue with the original action */
Plugin_Changed = 1, /**< Inputs or outputs have been overridden with new values */
Plugin_Handled = 3, /**< Handle the action at the end (don't call it) */
Plugin_Stop = 4, /**< Immediately stop the hook chain and handle the original */
};</pawn>
It's an enumeration tag and in our callback it's up to us to decide which value to return. As you probably understood from reading all the info, SourceMod console commands are implemented as hooks between client and original server code. If we don't return anything and "let it slide" or return <tt>Plugin_Continue</tt>, the original command from client will reach the server and, since it's highly unlikely that there is <tt>sm_kdr</tt> command in the game, the message <tt>Unknown command "sm_kdr"</tt> will be printed to client's console. We don't want that, so let's modify our callback to return <tt>Plugin_Handled</tt>:
<pawn>public Action:Command_KDR(client, args)
{
return Plugin_Handled;
}</pawn>
It's a very common mistake to forget to return <tt>Plugin_Handled</tt> so our naive implementation is going to be not so naive after all! Now, after we finally understood how <tt>ConCmd</tt> tag works, it's time to move to the next argument of <tt>RegConsoleCmd</tt>. It is a string that will act like a description of our command. However, notice the <tt>=</tt> after argument name, it indicates that this argument is optional, we can skip it and empty string (<tt>""</tt>) will be used. And the last argument is flags and it's also optional. Command flags are used to change behavior of command, but for now default behavior is ok. Now we know the meaning of all arguments, let's make a call.
<pawn>RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");</pawn>
Notice that we skipped flags because we want default behavior. Now let's see how the full command-related code looks like:
<pawn>public OnPluginStart()
{
RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");
}

public Action:Command_KDR(client, args)
{
return Plugin_Handled;
}</pawn>
Why did we choose <tt>sm_kdr</tt> as the name of our command? It's handy because it will create convenient [[Commands_%28SourceMod_Scripting%29#Chat_Triggers|chat triggers]]. The skeleton of our command is ready, it is time to write the actual code for calculating KDR and displaying it to client. Notice that the first argument of our <tt>Command_KDR</tt> callback is <tt>client</tt>. When our callback is called, it will hold the index of client who called our command. We'll use this to find necessary information about client and to display that information back. First, let's find the number of kills, we'll use <tt>GetClientFrags</tt> function for that, it's declared in '''clients.inc''':
<pawn>/**
* Returns the client's frag count.
*
* @param client Player's index.
* @return Frag count.
* @error Invalid client index, client not in game, or no mod support.
*/
native GetClientFrags(client);</pawn>
It takes one argument - the client index and returns the number of frags. For the only argument of <tt>GetClientFrags</tt> we'll use <tt>client</tt> argument of our callback and we also need to store the return value so we'll create a local variable for that:
<pawn>new kills = GetClientFrags(client);</pawn>
By this time, it is assumed that you've learned how to read include files and find necessary information, so only links to online SourceMod API will be provided. Next, we need to find the number of client deaths, we'll use <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=431& GetClientDeaths]</tt>:
<pawn>new deaths = GetClientDeaths(client);</pawn>
Now that we have both kills and deaths, let's find the ratio. Remember that by default all variables in SourcePawn act like integers, but we need the fractional part in this case. Another very important thing to remember is that a result of integer division is also an integer. So we need to convert both kills and deaths to floating point values and store the result in a floating point variable. <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=705& float]</tt> function does the conversion.
<pawn>new Float:ratio = float(kills) / float(deaths);</pawn>
And now we only need to display the ratio, since our command can be called either via console or chat, it is good idea to display our info accordingly, so we'll use <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand]</tt>. It's another [[Format_Class_Functions_(SourceMod_Scripting)|format class function]] and now we need to apply some formatting. In a nutshell, we pass the string which acts as a template for text and <tt>%</tt> sign and one-letter type identifier (which is called format specifier) for variable values to put inside that template. After that, we must pass the number of arguments that correspond to the number of format specifiers in our format string. Since we have a floating point number, the format specifier will be <tt>%f</tt>:
<pawn>ReplyToCommand(client, "Your KDR is: %f.", ratio);</pawn>
That's it! Now let's see the full code of our naive implementation:
<pawn>#include <sourcemod>

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

public OnPluginStart()
{
RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");
}

public Action:Command_KDR(client, args)
{
new kills = GetClientFrags(client);
new deaths = GetClientDeaths(client);
new Float:ratio = float(kills) / float(deaths);
ReplyToCommand(client, "Your KDR is: %f.", ratio);
return Plugin_Handled;
}</pawn>
Compile and test this plugin and notice that something is wrong. We'll talk about it in the next section.

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

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

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

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

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

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

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

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

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

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

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

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

Full example:

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

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

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

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32];
new damage;

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

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

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

SlapPlayer(target, damage);

new String:name[MAX_NAME_LENGTH];

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

return Plugin_Handled;
}</pawn>

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

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

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

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

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

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

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

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32];
new damage = GetConVarInt(sm_myslap_damage);

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

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

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

new String:name[MAX_NAME_LENGTH];

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

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

return Plugin_Handled;
}
</pawn>

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

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

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

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

new Handle:sm_myslap_damage = INVALID_HANDLE

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

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

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

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32];
new damage = GetConVarInt(sm_myslap_damage);

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

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

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

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

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

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

return Plugin_Handled;
}</pawn>

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

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

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

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

For example, the first client to connect has a userid of 2. If he exits and rejoins, his userid will be 3 (unless another client joins in-between). Since clients are disconnected on mapchange, their userids change as well. Userids are a handy way to check if a client's connection status has changed.

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

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

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

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

public Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
new victim_id = GetEventInt(event, "userid");
new attacker_id = GetEventInt(event, "attacker");

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

/* CODE */
}</pawn>

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

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

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

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& OnPluginStart()] - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. '''This is paired with OnPluginEnd()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& OnMapStart()] - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& OnPluginEnd()] - Called once, immediately before the plugin is unloaded. '''This function is paired to OnPluginStart().'''

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& OnClientAuthorized()] - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between connect and disconnect. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use OnClientPostAdminCheck().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& OnClientPostAdminCheck()] - Called after the player is '''both authorized and in-game'''. That is, both OnClientAuthorized() '''and''' OnClientPutInServer() have been invoked. This is the best callback for checking administrative access after connect.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& OnClientDisconnect()] - Called when a player's disconnection ends. '''This is paired to OnClientConnect().'''

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

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

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

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

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

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

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourceMod Plugins

2012-10-27T15:06:33Z

Bittersweet: /* Naive implementation */ Native, no Naive

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

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

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

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

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

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

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

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

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

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

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

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

=Creating client command=
So far we have learned how to set up our plugin and run some code. But our plugin still doesn't do anything useful. Let's add a console command to allow clients to see their kills/deaths ratio. For demonstration purposes, we are going to start with very naive implementation that a beginner could write, then we'll look at the common bugs it contains, fix them and add more advanced features. In the end we'll have a mature feature-rich implementation and experience that will prevent us from making simple mistakes in the future.

==Native implementation==
First, we need to register our console command. <tt>OnPluginStart</tt> is a good place to do that. In order to register our console command, we need to use <tt>RegConsoleCmd</tt> function, it is declared inside '''console.inc''', here's how it's declared:
<pawn>/**
* Creates a console command, or hooks an already existing one.
*
* Console commands are case sensitive. However, if the command already exists in the game,
* the a client may enter the command in any case. SourceMod corrects for this automatically,
* and you should only hook the "real" version of the command.
*
* @param cmd Name of the command to hook or create.
* @param callback A function to use as a callback for when the command is invoked.
* @param description Optional description to use for command creation.
* @param flags Optional flags to use for command creation.
* @noreturn
* @error Command name is the same as an existing convar.
*/
native RegConsoleCmd(const String:cmd[], ConCmd:callback, const String:description[]="", flags=0);</pawn>
This native looks a bit more complicated than the previous one, so let's go through each argument step by step. First one is the name of our command, we'll use <tt>"sm_kdr"</tt>. Second one is a callback, but it has unknown tag <tt>ConCmd</tt>. In order to correctly call <tt>RegConsoleCmd</tt> we need to find how <tt>ConCmd</tt> is declared. Thankfully, we don't need to look hard, it's declared right above <tt>RegConsoleCmd</tt>:
<pawn>/**
* Called when a generic console command is invoked.
*
* @param client Index of the client, or 0 from the server.
* @param args Number of arguments that were in the argument string.
* @return An Action value. Not handling the command
* means that Source will report it as "not found."
*/
functag public Action:ConCmd(client, args);</pawn>
This is a function tag. What does it mean? It means that we need to define our own function that will have the same prototype (number of arguments, their tags and return tag) as the one of function tag. However, in this case, we don't need to (and can't) use the same name as in tag, that would result in error. We need to use our own name, let's use <tt>Command_KDR</tt>. Function tags doesn't require to use the same argument names as specified in declaration, but it's a good idea to use them, because they usually have the most meaning. So, all in all, it leads us to the following definition:
<pawn>public Action:Command_KDR(client, args)
{
}</pawn>
Now, if you've been following carefully, you should see that we have another unknown tag here - <tt>Action</tt>. Let's look how it's declared ('''core.inc'''):
<pawn>/**
* Specifies what to do after a hook completes.
*/
enum Action
{
Plugin_Continue = 0, /**< Continue with the original action */
Plugin_Changed = 1, /**< Inputs or outputs have been overridden with new values */
Plugin_Handled = 3, /**< Handle the action at the end (don't call it) */
Plugin_Stop = 4, /**< Immediately stop the hook chain and handle the original */
};</pawn>
It's an enumeration tag and in our callback it's up to us to decide which value to return. As you probably understood from reading all the info, SourceMod console commands are implemented as hooks between client and original server code. If we don't return anything and "let it slide" or return <tt>Plugin_Continue</tt>, the original command from client will reach the server and, since it's highly unlikely that there is <tt>sm_kdr</tt> command in the game, the message <tt>Unknown command "sm_kdr"</tt> will be printed to client's console. We don't want that, so let's modify our callback to return <tt>Plugin_Handled</tt>:
<pawn>public Action:Command_KDR(client, args)
{
return Plugin_Handled;
}</pawn>
It's a very common mistake to forget to return <tt>Plugin_Handled</tt> so our naive implementation is going to be not so naive after all! Now, after we finally understood how <tt>ConCmd</tt> tag works, it's time to move to the next argument of <tt>RegConsoleCmd</tt>. It is a string that will act like a description of our command. However, notice the <tt>=</tt> after argument name, it indicates that this argument is optional, we can skip it and empty string (<tt>""</tt>) will be used. And the last argument is flags and it's also optional. Command flags are used to change behavior of command, but for now default behavior is ok. Now we know the meaning of all arguments, let's make a call.
<pawn>RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");</pawn>
Notice that we skipped flags because we want default behavior. Now let's see how the full command-related code looks like:
<pawn>public OnPluginStart()
{
RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");
}

public Action:Command_KDR(client, args)
{
return Plugin_Handled;
}</pawn>
Why did we choose <tt>sm_kdr</tt> as the name of our command? It's handy because it will create convenient [[Commands_%28SourceMod_Scripting%29#Chat_Triggers|chat triggers]]. The skeleton of our command is ready, it is time to write the actual code for calculating KDR and displaying it to client. Notice that the first argument of our <tt>Command_KDR</tt> callback is <tt>client</tt>. When our callback is called, it will hold the index of client who called our command. We'll use this to find necessary information about client and to display that information back. First, let's find the number of kills, we'll use <tt>GetClientFrags</tt> function for that, it's declared in '''clients.inc''':
<pawn>/**
* Returns the client's frag count.
*
* @param client Player's index.
* @return Frag count.
* @error Invalid client index, client not in game, or no mod support.
*/
native GetClientFrags(client);</pawn>
It takes one argument - the client index and returns the number of frags. For the only argument of <tt>GetClientFrags</tt> we'll use <tt>client</tt> argument of our callback and we also need to store the return value so we'll create a local variable for that:
<pawn>new kills = GetClientFrags(client);</pawn>
By this time, it is assumed that you've learned how to read include files and find necessary information, so only links to online SourceMod API will be provided. Next, we need to find the number of client deaths, we'll use <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=431& GetClientDeaths]</tt>:
<pawn>new deaths = GetClientDeaths(client);</pawn>
Now that we have both kills and deaths, let's find the ratio. Remember that by default all variables in SourcePawn act like integers, but we need the fractional part in this case. Another very important thing to remember is that a result of integer division is also an integer. So we need to convert both kills and deaths to floating point values and store the result in a floating point variable. <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=705& float]</tt> function does the conversion.
<pawn>new Float:ratio = float(kills) / float(deaths);</pawn>
And now we only need to display the ratio, since our command can be called either via console or chat, it is good idea to display our info accordingly, so we'll use <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand]</tt>. It's another [[Format_Class_Functions_(SourceMod_Scripting)|format class function]] and now we need to apply some formatting. In a nutshell, we pass the string which acts as a template for text and <tt>%</tt> sign and one-letter type identifier (which is called format specifier) for variable values to put inside that template. After that, we must pass the number of arguments that correspond to the number of format specifiers in our format string. Since we have a floating point number, the format specifier will be <tt>%f</tt>:
<pawn>ReplyToCommand(client, "Your KDR is: %f.", ratio);</pawn>
That's it! Now let's see the full code of our naive implementation:
<pawn>#include <sourcemod>

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

public OnPluginStart()
{
RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");
}

public Action:Command_KDR(client, args)
{
new kills = GetClientFrags(client);
new deaths = GetClientDeaths(client);
new Float:ratio = float(kills) / float(deaths);
ReplyToCommand(client, "Your KDR is: %f.", ratio);
return Plugin_Handled;
}</pawn>
Compile and test this plugin and notice that something is wrong. We'll talk about it in the next section.

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

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

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

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

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

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

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

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

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

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

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

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

Full example:

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

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

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

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32];
new damage;

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

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

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

SlapPlayer(target, damage);

new String:name[MAX_NAME_LENGTH];

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

return Plugin_Handled;
}</pawn>

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

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

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

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

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

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

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

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32];
new damage = GetConVarInt(sm_myslap_damage);

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

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

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

new String:name[MAX_NAME_LENGTH];

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

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

return Plugin_Handled;
}
</pawn>

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

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

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

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

new Handle:sm_myslap_damage = INVALID_HANDLE

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

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

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

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32];
new damage = GetConVarInt(sm_myslap_damage);

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

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

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

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

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

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

return Plugin_Handled;
}</pawn>

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

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

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

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

For example, the first client to connect has a userid of 2. If he exits and rejoins, his userid will be 3 (unless another client joins in-between). Since clients are disconnected on mapchange, their userids change as well. Userids are a handy way to check if a client's connection status has changed.

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

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

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

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

public Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
new victim_id = GetEventInt(event, "userid");
new attacker_id = GetEventInt(event, "attacker");

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

/* CODE */
}</pawn>

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

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

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

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& OnPluginStart()] - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. '''This is paired with OnPluginEnd()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& OnMapStart()] - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. '''This function is paired with OnMapEnd().'''
*At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& OnPluginEnd()] - Called once, immediately before the plugin is unloaded. '''This function is paired to OnPluginStart().'''

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& OnClientAuthorized()] - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between connect and disconnect. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use OnClientPostAdminCheck().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& OnClientPostAdminCheck()] - Called after the player is '''both authorized and in-game'''. That is, both OnClientAuthorized() '''and''' OnClientPutInServer() have been invoked. This is the best callback for checking administrative access after connect.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& OnClientDisconnect()] - Called when a player's disconnection ends. '''This is paired to OnClientConnect().'''

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

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

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

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

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

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

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourcePawn (legacy syntax)

2012-06-21T05:18:11Z

Bittersweet: /* Expressions */ - This (5 + 3) / 2 * 4 - 9; //Evaluates to 7 - actually evaluates to -8

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 six 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.
*'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.
*'''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 SourceMod. 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 -8
</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}}