AlliedModders Wiki - User contributions [en]

Introduction to SourceMod Plugins

2012-10-12T23:13:12Z

FaTony:

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-12T22:32:15Z

FaTony: /* Naive implementation */

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. So we need to use floating point number. For that, we just need to tag our variable as <tt>Float</tt>:
<pawn>new Float:ratio = kills / 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 = kills / 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}}

Commands (SourceMod Scripting)

2012-10-12T22:29:11Z

FaTony:

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

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

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

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

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

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

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

GetCmdArgString(full, sizeof(full));

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

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

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

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

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

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

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

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

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

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

GetCmdArgString(full, sizeof(full));

if (client)
{
PrintToServer("Command from client: %N", name);
} else {
PrintToServer("Command from server.");
}

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

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

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

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

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

<pawn>new Handle:ff = INVALID_HANDLE;

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

ff = FindConVar("mp_friendlyfire");
}

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

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

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

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

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

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

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

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

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

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

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

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

return Plugin_Handled;
}</pawn>

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

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

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

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

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

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

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

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

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

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

return Plugin_Handled;
}</pawn>

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

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

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

return Plugin_Continue;
}</pawn>

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

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

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

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

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourceMod Plugins

2012-10-12T20:38:50Z

FaTony: WIP Rewrite

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. So we need to use floating point number. For that, we just need to tag our variable as <tt>Float</tt>:
<pawn>new Float:ratio = kills / deaths;</pawn>
And now we only need to display the ratio, 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 = kills / 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-08T14:28:46Z

FaTony: WIP Rewrite

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!

=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-08T13:09:55Z

FaTony: /* Getting code to run */

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 OnPluginStart 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 OnPluginStart. 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 OnPluginStart, 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 "Hello world!" to server console. To do that we are going to use PrintToServer 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 "Hello world!" 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.

=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-08T11:25:01Z

FaTony: /* Getting code to run */

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 OnPluginStart 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 OnPluginStart. 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 implementation must have the same name, so it's OnPluginStart, secondly, our implementation should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our implementation 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 "Hello world!" to server console. To do that we are going to use PrintToServer 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 "Hello world!" 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.

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

User:FaTony

2012-10-08T09:52:01Z

FaTony:

https://forums.alliedmods.net/member.php?u=41205

Category:SourceMod Scripting

2012-10-06T09:52:37Z

FaTony: /* Introductions */

This category contains articles about scripting for SourceMod with SourcePawn.

===Introductions===
*[[Introduction to SourcePawn]] - Learning language syntax.
*[[Introduction to SourceMod Plugins]] - Writing your "first plugin."
*[http://docs.sourcemod.net/api API Reference] - Searchable scripting API reference.

===Basic API===
*[[AutoConfigs (SourceMod Scripting)|AutoConfigs]] - Automatic .cfg creation for cvars.
*[[Commands (SourceMod Scripting)|Commands]] - Console commands/input.
*[[ConVars (SourceMod Scripting)|ConVars]] - Console variables (cvars).
*[[Events (SourceMod Scripting)|Events]] - Half-Life 2 Game Events.
*[[KeyValues (SourceMod Scripting)|KeyValues]] - KeyValues file parsing/writing.
*[[Menu API (SourceMod)|Menus]] - Building and drawing menus.
*[[SQL (SourceMod Scripting)|SQL]] - Using databases (MySQL, SQLite).
*[[Timers (SourceMod Scripting)|Timers]] - Timed callbacks.
*[[DataPacks|DataPacks]] - A good way to store asynchronous data.
*[[Translations (SourceMod Scripting)|Translations]] - Internationalization.
*[[Entity References (SourceMod)|Entity References]] - A safe way of storing entities.

===Advanced API===
*[[Admin API (SourceMod)|Administration API]] - Using the Admin Cache.
*[[Admin Menu (SourceMod Scripting)|Admin Menu API]] - Attaching to the Admin Menu.
*[[Creating Natives (SourceMod Scripting)|Creating Natives]] - Exposing API to other plugins.
*[[Function Calling API (SourceMod Scripting)|Function Calling API]] - Calling external functions.
*[[Optional Requirements (SourceMod Scripting)|Optional Requirements]] - Managing dependencies.
*[[SDKTools (SourceMod Scripting)|SDKTools]] - Using the powerful SDK abstraction layer.
*[[TempEnts (SourceMod SDKTools)|Temporary Entities]] - Using temporary entities.

===Information===
*[[Format Class Functions (SourceMod Scripting)|Format Class Functions]] - All about text formatting.
*[[Handles (SourceMod Scripting)|Handles]] - Overview of Handles and some common types.
*[[Optimizing Plugins (SourceMod Scripting)|Optimizing Plugins]] - Optimization hints.
*[[Tags (Scripting)|Tags]] - All about tags.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Explanation of Vector types.

===Resources===
*[http://docs.sourcemod.net/api API Reference] - Searchable scripting API reference.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Game events listings for popular mods.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Temporary entities for popular mods.
*[[SourceMod Profiler]] - Performance tracking and optimizing.
*[[Vice_keys]] - Decryption keys for ctx files
*[[Weapon Names(Source)]] - Weapon Names / weapon entity names
[[Category:SourceMod]]
[[Category:SourceMod Development]]

Introduction to SourceMod Plugins

2012-10-06T06:32:52Z

FaTony: WIP Rewrite

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. When a first party starts a forward call, all parties that implemented that forward 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 OnPluginStart 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 OnPluginStart. 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 implement it? Firstly, our implementation must have the same name, so it's OnPluginStart, secondly, our implementation should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our implementation 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 "Hello world!" to server console. To do that we are going to use PrintToServer 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 "Hello world!" 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.

=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-05T11:11:18Z

FaTony: WIP Rewrite

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. When a first party starts a forward call, all parties that implemented that forward 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 OnPluginStart 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 OnPluginStart. 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 implement it? Firstly, our implementation must have the same name, so it's OnPluginStart, secondly, our implementation should have the same number of arguments, none in this case, and lastly, SourceMod needs to be able to call our implementation 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 "Hello world!" to server console.

=Plugin Structure=
Almost all plugins have the same three elements:
*'''Includes''' - Allows you to access the SourceMod API, and if you desire, APIs from external SourceMod extensions and plugins.
*'''Info''' - Public information about your plugin.
*'''Startup''' - A function which performs start-up routines in your plugin.

A skeletal plugin structure looks like this:
<pawn>
#include <sourcemod>

public OnPluginStart()
{
// Perform one-time startup tasks ...
}</pawn>

The information portion is a special syntax construct. You cannot change any of the keywords, or the <tt>public Plugin:myinfo</tt> declaration. The best idea is to copy and paste this skeletal structure and modify the strings to get started.

=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-05T10:05:55Z

FaTony: WIP Rewrite

Introduction to SourceMod Plugins

2012-10-05T09:28:49Z

FaTony: WIP Rewrite

Introduction to SourceMod Plugins

2012-10-05T08:10:10Z

FaTony:

Introduction to SourceMod Plugins

2012-10-05T08:05:28Z

FaTony:

Talk:Admin API (SourceMod)

2012-09-29T15:40:04Z

FaTony: Created page with "No example code, wtf?"

No example code, wtf?

User:FaTony

2012-09-16T20:39:41Z

FaTony: Created page with "."

Introduction to SourceMod Plugins

2012-09-16T20:38:15Z

FaTony:

Creating Natives (SourceMod Scripting)

2012-09-16T15:32:10Z

FaTony: /* Throwing Errors */

SourceMod allows plugins to create their own natives that other plugins can use. This is very similar to AMX Mod X's {{amxx_func|register_native}} function. It is a powerful inter-plugin communication resource that can greatly enhance the functionality you provide.

''Prerequisites:'' You should have a good grasp of Pawn or SourcePawn scripting, as well as how [[Tags (Scripting)|Tags]] work. 
''Note:'' Most functions herein can be found in the [[SourceMod SDK]], under <tt>plugins/include/functions.inc</tt>.

=Introduction=
Before creating natives, you should always document and specify exactly how they will work. This means writing your "include file" beforehand. Not only does this guide you in writing your natives, but it has the added benefit of completing a large portion of documentation at the same time.

==Include File==
For our first example, let's start off with a simple native that adds two numbers, a float and a non-float. It might look like this:
<pawn>/** Double-include prevention */
#if defined _mynatives_included_
#endinput
#endif
#define _mynatives_included_

/**
* Adds two numbers together.
*
* @param num1 An integer.
* @param num2 A float.
* @return The float value of the integer and float added together.
*/
native Float:My_AddNumbers(num1, num2);</pawn>

The documentation and commenting style above is a SourceMod Development Team convention. While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

==Creating the Native==
To actually create the native, first let's define the native handler itself. From <tt>functions.inc</tt> we can see that this follows the prototype:
<pawn>functag NativeCall public(Handle:plugin, numParams);</pawn>

Thus, we have a function like:
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
}</pawn>

Note that we don't use the same function name as we did in our include file. This is to prevent a possible ''name clash''. Otherwise, two different symbols (one a native, another a function) could have the same name, and that's not allowed. We'll see later how we bind the native to its actual name.

Next, we need to implement our native.
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
/* Retrieve the first parameter we receive */
new num1 = GetNativeCell(1);
/* Retrieve the second parameter we receive */
new Float:num2 = Float:GetNativeCell(2);
/* Add them together */
new Float:value = num1 + num2;
/* Return the value */
return _:value;
}</pawn>

You should note four important details. The first is that we have to manually grab the parameters -- they're not easily sent via arguments. This is for technical reasons that go beyond the scope of this document. That means you have to know exactly ''how'' to grab each parameter. For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.

However, the second detail is that there is no <tt>GetNativeCellFloat</tt>. This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently. Thus, we ''change'' the tag to <tt>Float</tt> manual. '''This is different from calling float(GetNativeCell(2)).''' In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).

Similarly, the third detail is that we cannot simply put <tt>return value</tt> or <tt>return FloatRound(value)</tt>. The reason is that our native is supposed to be returning a float. If we return <tt>value</tt>, we'll get a tag mismatch. If we return <tt>FloatRound(value)</tt>, we'll be returning an integer when a float is expected. The solution is to change the tag to the default tag, which will retain the value but remove the tag warning.

Lastly, we did not need to verify <tt>numParams</tt>. The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way. Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

==Registering the Native==
Natives must be registered in <tt>AskPluginLoad2</tt>. Although they can be registered elsewhere, only this function guarantees that all other plugins will see your native. The definition for this forward is in <tt>sourcemod.inc</tt>.

<pawn>public APLRes:AskPluginLoad2(Handle:myself, bool:late, String:error[], err_max)
{
CreateNative("My_AddNumbers", Native_My_AddNumbers);
return APLRes_Success;
}</pawn>

Now, any plugin will be able to use our native as if it were from a Core or a C++ extension.

=Usage=
==By-Reference==
Sometimes, it may be desirable to return data through by-reference parameters. For example, observe the following native prototype:
<pawn>/**
* Closes a Handle, and sets the variable to INVALID_HANDLE by reference.
*
* @param hndl Handle to close and clear.
* @return Anything that CloseHandle() returns.
*/
native bool:AltCloseHandle(&Handle:hndl);</pawn>

An implementation of this would look like:
<pawn>public Native_AltCloseHandle(Handle:plugin, numParams)
{
new Handle:hndl = Handle:GetNativeCellRef(1);
SetNativeCellRef(1, 0); /* Zero out the variable by reference */
return CloseHandle(hndl);
}</pawn>

Now, we have a native that is "safer" than a normal <tt>CloseHandle</tt>, as it ensures we don't hold onto invalid Handles.

==Strings==
Strings can be retrieved and altered via dynamic natives. Observe the following native prototype:
<pawn>/**
* Converts a string to upper case.
*
* @param str String to convert.
* @noreturn
*/
native StringToUpper(String:str[]);</pawn>

An implementation of this is very easy, because of dynamic arrays:
<pawn>public Native_StringToUpper(Handle:plugin, numParams)
{
new len;
GetNativeStringLength(1, len);

if (len <= 0)
{
return;
}

new String:str[len + 1];
GetNativeString(1, str, len + 1);

for (new i = 0; i < len; i++)
{
/* 5th bit specifies case in ASCII --
* this is not UTF-8 compatible.
*/
if ((str[i] & (1 << 5)) == (1 << 5))
{
str[i] &= ~(1 << 5)
}
}

SetNativeString(1, str, len+1, false);
}</pawn>

==Arrays==
Working with arrays is very similar to strings. For example, observe the following native prototype:
<pawn>/**
* Sums an array of numbers and returns the sum.
*
* @param array Array of numbers to sum.
* @param size Size of array.
* @return Sum of the array elements.
*/
native SumArray(const array[], size);</pawn>

An implementation of this could look like:
<pawn>public Native_SumArray(Handle:plugin, numParams)
{
new size = GetNativeCell(2);
if (size < 1)
{
return 0;
}

new array[size], total;
GetNativeArray(1, array, size);

for (new i = 0; i < size; i++)
{
total += array[i];
}
return total;
}</pawn>

Similarly, there is a <tt>SetNativeArray</tt>, which is used to alter array contents.

==Variable Arguments==
Variable arguments are usually used when dealing with [[Format Class Functions (SourceMod Scripting)|format class functions]], however it is also possible to use them for general functionality. The only trick is that unlike normal parameters, every variable argument parameter is passed by-reference. This adds no change for arrays and strings, but for floats, handles, numbers, or anything else that fits in a cell, <tt>GetNativeCellRef</tt> must be used instead.

As an example, let's convert our function from above to use variable arguments:
<pawn>/**
* Sums a list of numbers.
*
* @param num First number to use as a base.
* @param ... Any number of additional numbers to add.
* @return Sum of all numbers passed.
*/
native SumParams(num, ...);</pawn>

An implementation of this would look like:
<pawn>public Native_SumParams(Handle:plugin, numParams)
{
new base = GetNativeCell(1);
for (new i = 2; i <= numParams; i++)
{
base += GetNativeCellRef(i);
}
return base;
}</pawn>

==Format Functions==
It is also possible to create your own [[Format Class Functions (SourceMod Scripting)|format class functions]]. This topic is much more complicated than the previous ones, as the native string formatter allows for many different configurations. This is mainly for optimization. Note that a formatting routine deals with two buffers: the input format string, and the output buffer. <tt>FormatNativeString</tt>, by default, uses parameter indexes directly so you don't have to copy or locally store any of these buffers.

The most common usage of this is to accept a user-formatted string and to not
<pawn>/**
* Prints a message with a [DEBUG] prefix to the server.
*
* @param fmt Format string.
* @param ... Format arguments.
*/
native DebugPrint(const String:fmt[], any:...);</pawn>

This could be easily implemented as:
<pawn>native DebugPrint(Handle:plugin, numParams)
{
decl String:buffer[1024], written

FormatNativeString(0, /* Use an output buffer */
1, /* Format param */
2, /* Format argument #1 */
sizeof(buffer), /* Size of output buffer */
written, /* Store # of written bytes */
buffer /* Use our buffer */
);

PrintToServer("[DEBUG] %s", buffer);
}</pawn>

==Throwing Errors==
Often, your native will encounter an unrecoverable error, and you wish to trigger a fatal exception. This is equivalent to <tt>IPluginContext::ThrowNativeError</tt>, and will halt the current function execution in the plugin. The debugger will be invoked and a backtrace will be printed out (if the plugin is in debug mode). Although the current function is cancelled, the plugin will continue to operate normally afterward.

For example, let's say we have a native that operates on clients. We want to throw an error if we get a client index that is invalid or disconnected. We could do this like so:
<pawn>public MyFunction(Handle:plugin, numParams)
{
new client = GetNativeCell(1);
if (client < 1 || client > MaxClients);
{
return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client);
}
if (!IsClientConnected(client))
{
return ThrowNativeError(SP_ERROR_NATIVE, "Client %d is not connected", client);
}
/* Code */
}</pawn>

[[Category:SourceMod Scripting]]

Creating Natives (SourceMod Scripting)

2012-09-16T15:31:33Z

FaTony: /* Throwing Errors */

SourceMod allows plugins to create their own natives that other plugins can use. This is very similar to AMX Mod X's {{amxx_func|register_native}} function. It is a powerful inter-plugin communication resource that can greatly enhance the functionality you provide.

''Prerequisites:'' You should have a good grasp of Pawn or SourcePawn scripting, as well as how [[Tags (Scripting)|Tags]] work. 
''Note:'' Most functions herein can be found in the [[SourceMod SDK]], under <tt>plugins/include/functions.inc</tt>.

=Introduction=
Before creating natives, you should always document and specify exactly how they will work. This means writing your "include file" beforehand. Not only does this guide you in writing your natives, but it has the added benefit of completing a large portion of documentation at the same time.

==Include File==
For our first example, let's start off with a simple native that adds two numbers, a float and a non-float. It might look like this:
<pawn>/** Double-include prevention */
#if defined _mynatives_included_
#endinput
#endif
#define _mynatives_included_

/**
* Adds two numbers together.
*
* @param num1 An integer.
* @param num2 A float.
* @return The float value of the integer and float added together.
*/
native Float:My_AddNumbers(num1, num2);</pawn>

The documentation and commenting style above is a SourceMod Development Team convention. While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

==Creating the Native==
To actually create the native, first let's define the native handler itself. From <tt>functions.inc</tt> we can see that this follows the prototype:
<pawn>functag NativeCall public(Handle:plugin, numParams);</pawn>

Thus, we have a function like:
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
}</pawn>

Note that we don't use the same function name as we did in our include file. This is to prevent a possible ''name clash''. Otherwise, two different symbols (one a native, another a function) could have the same name, and that's not allowed. We'll see later how we bind the native to its actual name.

Next, we need to implement our native.
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
/* Retrieve the first parameter we receive */
new num1 = GetNativeCell(1);
/* Retrieve the second parameter we receive */
new Float:num2 = Float:GetNativeCell(2);
/* Add them together */
new Float:value = num1 + num2;
/* Return the value */
return _:value;
}</pawn>

You should note four important details. The first is that we have to manually grab the parameters -- they're not easily sent via arguments. This is for technical reasons that go beyond the scope of this document. That means you have to know exactly ''how'' to grab each parameter. For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.

However, the second detail is that there is no <tt>GetNativeCellFloat</tt>. This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently. Thus, we ''change'' the tag to <tt>Float</tt> manual. '''This is different from calling float(GetNativeCell(2)).''' In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).

Similarly, the third detail is that we cannot simply put <tt>return value</tt> or <tt>return FloatRound(value)</tt>. The reason is that our native is supposed to be returning a float. If we return <tt>value</tt>, we'll get a tag mismatch. If we return <tt>FloatRound(value)</tt>, we'll be returning an integer when a float is expected. The solution is to change the tag to the default tag, which will retain the value but remove the tag warning.

Lastly, we did not need to verify <tt>numParams</tt>. The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way. Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

==Registering the Native==
Natives must be registered in <tt>AskPluginLoad2</tt>. Although they can be registered elsewhere, only this function guarantees that all other plugins will see your native. The definition for this forward is in <tt>sourcemod.inc</tt>.

<pawn>public APLRes:AskPluginLoad2(Handle:myself, bool:late, String:error[], err_max)
{
CreateNative("My_AddNumbers", Native_My_AddNumbers);
return APLRes_Success;
}</pawn>

Now, any plugin will be able to use our native as if it were from a Core or a C++ extension.

=Usage=
==By-Reference==
Sometimes, it may be desirable to return data through by-reference parameters. For example, observe the following native prototype:
<pawn>/**
* Closes a Handle, and sets the variable to INVALID_HANDLE by reference.
*
* @param hndl Handle to close and clear.
* @return Anything that CloseHandle() returns.
*/
native bool:AltCloseHandle(&Handle:hndl);</pawn>

An implementation of this would look like:
<pawn>public Native_AltCloseHandle(Handle:plugin, numParams)
{
new Handle:hndl = Handle:GetNativeCellRef(1);
SetNativeCellRef(1, 0); /* Zero out the variable by reference */
return CloseHandle(hndl);
}</pawn>

Now, we have a native that is "safer" than a normal <tt>CloseHandle</tt>, as it ensures we don't hold onto invalid Handles.

==Strings==
Strings can be retrieved and altered via dynamic natives. Observe the following native prototype:
<pawn>/**
* Converts a string to upper case.
*
* @param str String to convert.
* @noreturn
*/
native StringToUpper(String:str[]);</pawn>

An implementation of this is very easy, because of dynamic arrays:
<pawn>public Native_StringToUpper(Handle:plugin, numParams)
{
new len;
GetNativeStringLength(1, len);

if (len <= 0)
{
return;
}

new String:str[len + 1];
GetNativeString(1, str, len + 1);

for (new i = 0; i < len; i++)
{
/* 5th bit specifies case in ASCII --
* this is not UTF-8 compatible.
*/
if ((str[i] & (1 << 5)) == (1 << 5))
{
str[i] &= ~(1 << 5)
}
}

SetNativeString(1, str, len+1, false);
}</pawn>

==Arrays==
Working with arrays is very similar to strings. For example, observe the following native prototype:
<pawn>/**
* Sums an array of numbers and returns the sum.
*
* @param array Array of numbers to sum.
* @param size Size of array.
* @return Sum of the array elements.
*/
native SumArray(const array[], size);</pawn>

An implementation of this could look like:
<pawn>public Native_SumArray(Handle:plugin, numParams)
{
new size = GetNativeCell(2);
if (size < 1)
{
return 0;
}

new array[size], total;
GetNativeArray(1, array, size);

for (new i = 0; i < size; i++)
{
total += array[i];
}
return total;
}</pawn>

Similarly, there is a <tt>SetNativeArray</tt>, which is used to alter array contents.

==Variable Arguments==
Variable arguments are usually used when dealing with [[Format Class Functions (SourceMod Scripting)|format class functions]], however it is also possible to use them for general functionality. The only trick is that unlike normal parameters, every variable argument parameter is passed by-reference. This adds no change for arrays and strings, but for floats, handles, numbers, or anything else that fits in a cell, <tt>GetNativeCellRef</tt> must be used instead.

As an example, let's convert our function from above to use variable arguments:
<pawn>/**
* Sums a list of numbers.
*
* @param num First number to use as a base.
* @param ... Any number of additional numbers to add.
* @return Sum of all numbers passed.
*/
native SumParams(num, ...);</pawn>

An implementation of this would look like:
<pawn>public Native_SumParams(Handle:plugin, numParams)
{
new base = GetNativeCell(1);
for (new i = 2; i <= numParams; i++)
{
base += GetNativeCellRef(i);
}
return base;
}</pawn>

==Format Functions==
It is also possible to create your own [[Format Class Functions (SourceMod Scripting)|format class functions]]. This topic is much more complicated than the previous ones, as the native string formatter allows for many different configurations. This is mainly for optimization. Note that a formatting routine deals with two buffers: the input format string, and the output buffer. <tt>FormatNativeString</tt>, by default, uses parameter indexes directly so you don't have to copy or locally store any of these buffers.

The most common usage of this is to accept a user-formatted string and to not
<pawn>/**
* Prints a message with a [DEBUG] prefix to the server.
*
* @param fmt Format string.
* @param ... Format arguments.
*/
native DebugPrint(const String:fmt[], any:...);</pawn>

This could be easily implemented as:
<pawn>native DebugPrint(Handle:plugin, numParams)
{
decl String:buffer[1024], written

FormatNativeString(0, /* Use an output buffer */
1, /* Format param */
2, /* Format argument #1 */
sizeof(buffer), /* Size of output buffer */
written, /* Store # of written bytes */
buffer /* Use our buffer */
);

PrintToServer("[DEBUG] %s", buffer);
}</pawn>

==Throwing Errors==
Often, your native will encounter an unrecoverable error, and you wish to trigger a fatal exception. This is equivalent to <tt>IPluginContext::ThrowNativeError</tt>, and will halt the current function execution in the plugin. The debugger will be invoked and a backtrace will be printed out (if the plugin is in debug mode). Although the current function is cancelled, the plugin will continue to operate normally afterward.

For example, let's say we have a native that operates on clients. We want to throw an error if we get a client index that is invalid or disconnected. We could do this like so:
<pawn>public MyFunction(Handle:plugin, numParams)
{
new client = GetNativeCell(1);
if (client < 1 || client > GetMaxClients());
{
return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client);
}
if (!IsClientConnected(client))
{
return ThrowNativeError(SP_ERROR_NATIVE, "Client %d is not connected", client);
}
/* Code */
}</pawn>

[[Category:SourceMod Scripting]]

Creating Natives (SourceMod Scripting)

2012-09-16T15:31:04Z

FaTony: /* Format Functions */

SourceMod allows plugins to create their own natives that other plugins can use. This is very similar to AMX Mod X's {{amxx_func|register_native}} function. It is a powerful inter-plugin communication resource that can greatly enhance the functionality you provide.

''Prerequisites:'' You should have a good grasp of Pawn or SourcePawn scripting, as well as how [[Tags (Scripting)|Tags]] work. 
''Note:'' Most functions herein can be found in the [[SourceMod SDK]], under <tt>plugins/include/functions.inc</tt>.

=Introduction=
Before creating natives, you should always document and specify exactly how they will work. This means writing your "include file" beforehand. Not only does this guide you in writing your natives, but it has the added benefit of completing a large portion of documentation at the same time.

==Include File==
For our first example, let's start off with a simple native that adds two numbers, a float and a non-float. It might look like this:
<pawn>/** Double-include prevention */
#if defined _mynatives_included_
#endinput
#endif
#define _mynatives_included_

/**
* Adds two numbers together.
*
* @param num1 An integer.
* @param num2 A float.
* @return The float value of the integer and float added together.
*/
native Float:My_AddNumbers(num1, num2);</pawn>

The documentation and commenting style above is a SourceMod Development Team convention. While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

==Creating the Native==
To actually create the native, first let's define the native handler itself. From <tt>functions.inc</tt> we can see that this follows the prototype:
<pawn>functag NativeCall public(Handle:plugin, numParams);</pawn>

Thus, we have a function like:
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
}</pawn>

Note that we don't use the same function name as we did in our include file. This is to prevent a possible ''name clash''. Otherwise, two different symbols (one a native, another a function) could have the same name, and that's not allowed. We'll see later how we bind the native to its actual name.

Next, we need to implement our native.
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
/* Retrieve the first parameter we receive */
new num1 = GetNativeCell(1);
/* Retrieve the second parameter we receive */
new Float:num2 = Float:GetNativeCell(2);
/* Add them together */
new Float:value = num1 + num2;
/* Return the value */
return _:value;
}</pawn>

You should note four important details. The first is that we have to manually grab the parameters -- they're not easily sent via arguments. This is for technical reasons that go beyond the scope of this document. That means you have to know exactly ''how'' to grab each parameter. For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.

However, the second detail is that there is no <tt>GetNativeCellFloat</tt>. This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently. Thus, we ''change'' the tag to <tt>Float</tt> manual. '''This is different from calling float(GetNativeCell(2)).''' In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).

Similarly, the third detail is that we cannot simply put <tt>return value</tt> or <tt>return FloatRound(value)</tt>. The reason is that our native is supposed to be returning a float. If we return <tt>value</tt>, we'll get a tag mismatch. If we return <tt>FloatRound(value)</tt>, we'll be returning an integer when a float is expected. The solution is to change the tag to the default tag, which will retain the value but remove the tag warning.

Lastly, we did not need to verify <tt>numParams</tt>. The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way. Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

==Registering the Native==
Natives must be registered in <tt>AskPluginLoad2</tt>. Although they can be registered elsewhere, only this function guarantees that all other plugins will see your native. The definition for this forward is in <tt>sourcemod.inc</tt>.

<pawn>public APLRes:AskPluginLoad2(Handle:myself, bool:late, String:error[], err_max)
{
CreateNative("My_AddNumbers", Native_My_AddNumbers);
return APLRes_Success;
}</pawn>

Now, any plugin will be able to use our native as if it were from a Core or a C++ extension.

=Usage=
==By-Reference==
Sometimes, it may be desirable to return data through by-reference parameters. For example, observe the following native prototype:
<pawn>/**
* Closes a Handle, and sets the variable to INVALID_HANDLE by reference.
*
* @param hndl Handle to close and clear.
* @return Anything that CloseHandle() returns.
*/
native bool:AltCloseHandle(&Handle:hndl);</pawn>

An implementation of this would look like:
<pawn>public Native_AltCloseHandle(Handle:plugin, numParams)
{
new Handle:hndl = Handle:GetNativeCellRef(1);
SetNativeCellRef(1, 0); /* Zero out the variable by reference */
return CloseHandle(hndl);
}</pawn>

Now, we have a native that is "safer" than a normal <tt>CloseHandle</tt>, as it ensures we don't hold onto invalid Handles.

==Strings==
Strings can be retrieved and altered via dynamic natives. Observe the following native prototype:
<pawn>/**
* Converts a string to upper case.
*
* @param str String to convert.
* @noreturn
*/
native StringToUpper(String:str[]);</pawn>

An implementation of this is very easy, because of dynamic arrays:
<pawn>public Native_StringToUpper(Handle:plugin, numParams)
{
new len;
GetNativeStringLength(1, len);

if (len <= 0)
{
return;
}

new String:str[len + 1];
GetNativeString(1, str, len + 1);

for (new i = 0; i < len; i++)
{
/* 5th bit specifies case in ASCII --
* this is not UTF-8 compatible.
*/
if ((str[i] & (1 << 5)) == (1 << 5))
{
str[i] &= ~(1 << 5)
}
}

SetNativeString(1, str, len+1, false);
}</pawn>

==Arrays==
Working with arrays is very similar to strings. For example, observe the following native prototype:
<pawn>/**
* Sums an array of numbers and returns the sum.
*
* @param array Array of numbers to sum.
* @param size Size of array.
* @return Sum of the array elements.
*/
native SumArray(const array[], size);</pawn>

An implementation of this could look like:
<pawn>public Native_SumArray(Handle:plugin, numParams)
{
new size = GetNativeCell(2);
if (size < 1)
{
return 0;
}

new array[size], total;
GetNativeArray(1, array, size);

for (new i = 0; i < size; i++)
{
total += array[i];
}
return total;
}</pawn>

Similarly, there is a <tt>SetNativeArray</tt>, which is used to alter array contents.

==Variable Arguments==
Variable arguments are usually used when dealing with [[Format Class Functions (SourceMod Scripting)|format class functions]], however it is also possible to use them for general functionality. The only trick is that unlike normal parameters, every variable argument parameter is passed by-reference. This adds no change for arrays and strings, but for floats, handles, numbers, or anything else that fits in a cell, <tt>GetNativeCellRef</tt> must be used instead.

As an example, let's convert our function from above to use variable arguments:
<pawn>/**
* Sums a list of numbers.
*
* @param num First number to use as a base.
* @param ... Any number of additional numbers to add.
* @return Sum of all numbers passed.
*/
native SumParams(num, ...);</pawn>

An implementation of this would look like:
<pawn>public Native_SumParams(Handle:plugin, numParams)
{
new base = GetNativeCell(1);
for (new i = 2; i <= numParams; i++)
{
base += GetNativeCellRef(i);
}
return base;
}</pawn>

==Format Functions==
It is also possible to create your own [[Format Class Functions (SourceMod Scripting)|format class functions]]. This topic is much more complicated than the previous ones, as the native string formatter allows for many different configurations. This is mainly for optimization. Note that a formatting routine deals with two buffers: the input format string, and the output buffer. <tt>FormatNativeString</tt>, by default, uses parameter indexes directly so you don't have to copy or locally store any of these buffers.

The most common usage of this is to accept a user-formatted string and to not
<pawn>/**
* Prints a message with a [DEBUG] prefix to the server.
*
* @param fmt Format string.
* @param ... Format arguments.
*/
native DebugPrint(const String:fmt[], any:...);</pawn>

This could be easily implemented as:
<pawn>native DebugPrint(Handle:plugin, numParams)
{
decl String:buffer[1024], written

FormatNativeString(0, /* Use an output buffer */
1, /* Format param */
2, /* Format argument #1 */
sizeof(buffer), /* Size of output buffer */
written, /* Store # of written bytes */
buffer /* Use our buffer */
);

PrintToServer("[DEBUG] %s", buffer);
}</pawn>

==Throwing Errors==
Often, your native will encounter an unrecoverable error, and you wish to trigger a fatal exception. This is equivalent to <tt>IPluginContext::ThrowNativeError</tt>, and will halt the current function execution in the plugin. The debugger will be invoked and a backtrace will be printed out (if the plugin is in debug mode). Although the current function is cancelled, the plugin will continue to operate normally afterward.

For example, let's say we have a native that operates on clients. We want to throw an error if we get a client index that is invalid or disconnected. We could do this like so:
<pawn>public MyFunction(Handle:plugin, numParams)
{
new client = GetNativeCell(1)
if (client < 1 || client > GetMaxClients())
{
return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client)
}
if (!IsClientConnected(client))
{
return ThrowNativeError(SP_ERROR_NATIVE, "Client %d is not connected", client)
}
/* Code */
}</pawn>

[[Category:SourceMod Scripting]]

Creating Natives (SourceMod Scripting)

2012-09-16T15:30:20Z

FaTony: /* Variable Arguments */

SourceMod allows plugins to create their own natives that other plugins can use. This is very similar to AMX Mod X's {{amxx_func|register_native}} function. It is a powerful inter-plugin communication resource that can greatly enhance the functionality you provide.

''Prerequisites:'' You should have a good grasp of Pawn or SourcePawn scripting, as well as how [[Tags (Scripting)|Tags]] work. 
''Note:'' Most functions herein can be found in the [[SourceMod SDK]], under <tt>plugins/include/functions.inc</tt>.

=Introduction=
Before creating natives, you should always document and specify exactly how they will work. This means writing your "include file" beforehand. Not only does this guide you in writing your natives, but it has the added benefit of completing a large portion of documentation at the same time.

==Include File==
For our first example, let's start off with a simple native that adds two numbers, a float and a non-float. It might look like this:
<pawn>/** Double-include prevention */
#if defined _mynatives_included_
#endinput
#endif
#define _mynatives_included_

/**
* Adds two numbers together.
*
* @param num1 An integer.
* @param num2 A float.
* @return The float value of the integer and float added together.
*/
native Float:My_AddNumbers(num1, num2);</pawn>

The documentation and commenting style above is a SourceMod Development Team convention. While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

==Creating the Native==
To actually create the native, first let's define the native handler itself. From <tt>functions.inc</tt> we can see that this follows the prototype:
<pawn>functag NativeCall public(Handle:plugin, numParams);</pawn>

Thus, we have a function like:
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
}</pawn>

Note that we don't use the same function name as we did in our include file. This is to prevent a possible ''name clash''. Otherwise, two different symbols (one a native, another a function) could have the same name, and that's not allowed. We'll see later how we bind the native to its actual name.

Next, we need to implement our native.
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
/* Retrieve the first parameter we receive */
new num1 = GetNativeCell(1);
/* Retrieve the second parameter we receive */
new Float:num2 = Float:GetNativeCell(2);
/* Add them together */
new Float:value = num1 + num2;
/* Return the value */
return _:value;
}</pawn>

You should note four important details. The first is that we have to manually grab the parameters -- they're not easily sent via arguments. This is for technical reasons that go beyond the scope of this document. That means you have to know exactly ''how'' to grab each parameter. For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.

However, the second detail is that there is no <tt>GetNativeCellFloat</tt>. This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently. Thus, we ''change'' the tag to <tt>Float</tt> manual. '''This is different from calling float(GetNativeCell(2)).''' In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).

Similarly, the third detail is that we cannot simply put <tt>return value</tt> or <tt>return FloatRound(value)</tt>. The reason is that our native is supposed to be returning a float. If we return <tt>value</tt>, we'll get a tag mismatch. If we return <tt>FloatRound(value)</tt>, we'll be returning an integer when a float is expected. The solution is to change the tag to the default tag, which will retain the value but remove the tag warning.

Lastly, we did not need to verify <tt>numParams</tt>. The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way. Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

==Registering the Native==
Natives must be registered in <tt>AskPluginLoad2</tt>. Although they can be registered elsewhere, only this function guarantees that all other plugins will see your native. The definition for this forward is in <tt>sourcemod.inc</tt>.

<pawn>public APLRes:AskPluginLoad2(Handle:myself, bool:late, String:error[], err_max)
{
CreateNative("My_AddNumbers", Native_My_AddNumbers);
return APLRes_Success;
}</pawn>

Now, any plugin will be able to use our native as if it were from a Core or a C++ extension.

=Usage=
==By-Reference==
Sometimes, it may be desirable to return data through by-reference parameters. For example, observe the following native prototype:
<pawn>/**
* Closes a Handle, and sets the variable to INVALID_HANDLE by reference.
*
* @param hndl Handle to close and clear.
* @return Anything that CloseHandle() returns.
*/
native bool:AltCloseHandle(&Handle:hndl);</pawn>

An implementation of this would look like:
<pawn>public Native_AltCloseHandle(Handle:plugin, numParams)
{
new Handle:hndl = Handle:GetNativeCellRef(1);
SetNativeCellRef(1, 0); /* Zero out the variable by reference */
return CloseHandle(hndl);
}</pawn>

Now, we have a native that is "safer" than a normal <tt>CloseHandle</tt>, as it ensures we don't hold onto invalid Handles.

==Strings==
Strings can be retrieved and altered via dynamic natives. Observe the following native prototype:
<pawn>/**
* Converts a string to upper case.
*
* @param str String to convert.
* @noreturn
*/
native StringToUpper(String:str[]);</pawn>

An implementation of this is very easy, because of dynamic arrays:
<pawn>public Native_StringToUpper(Handle:plugin, numParams)
{
new len;
GetNativeStringLength(1, len);

if (len <= 0)
{
return;
}

new String:str[len + 1];
GetNativeString(1, str, len + 1);

for (new i = 0; i < len; i++)
{
/* 5th bit specifies case in ASCII --
* this is not UTF-8 compatible.
*/
if ((str[i] & (1 << 5)) == (1 << 5))
{
str[i] &= ~(1 << 5)
}
}

SetNativeString(1, str, len+1, false);
}</pawn>

==Arrays==
Working with arrays is very similar to strings. For example, observe the following native prototype:
<pawn>/**
* Sums an array of numbers and returns the sum.
*
* @param array Array of numbers to sum.
* @param size Size of array.
* @return Sum of the array elements.
*/
native SumArray(const array[], size);</pawn>

An implementation of this could look like:
<pawn>public Native_SumArray(Handle:plugin, numParams)
{
new size = GetNativeCell(2);
if (size < 1)
{
return 0;
}

new array[size], total;
GetNativeArray(1, array, size);

for (new i = 0; i < size; i++)
{
total += array[i];
}
return total;
}</pawn>

Similarly, there is a <tt>SetNativeArray</tt>, which is used to alter array contents.

==Variable Arguments==
Variable arguments are usually used when dealing with [[Format Class Functions (SourceMod Scripting)|format class functions]], however it is also possible to use them for general functionality. The only trick is that unlike normal parameters, every variable argument parameter is passed by-reference. This adds no change for arrays and strings, but for floats, handles, numbers, or anything else that fits in a cell, <tt>GetNativeCellRef</tt> must be used instead.

As an example, let's convert our function from above to use variable arguments:
<pawn>/**
* Sums a list of numbers.
*
* @param num First number to use as a base.
* @param ... Any number of additional numbers to add.
* @return Sum of all numbers passed.
*/
native SumParams(num, ...);</pawn>

An implementation of this would look like:
<pawn>public Native_SumParams(Handle:plugin, numParams)
{
new base = GetNativeCell(1);
for (new i = 2; i <= numParams; i++)
{
base += GetNativeCellRef(i);
}
return base;
}</pawn>

==Format Functions==
It is also possible to create your own [[Format Class Functions (SourceMod Scripting)|format class functions]]. This topic is much more complicated than the previous ones, as the native string formatter allows for many different configurations. This is mainly for optimization. Note that a formatting routine deals with two buffers: the input format string, and the output buffer. <tt>FormatNativeString</tt>, by default, uses parameter indexes directly so you don't have to copy or locally store any of these buffers.

The most common usage of this is to accept a user-formatted string and to not
<pawn>/**
* Prints a message with a [DEBUG] prefix to the server.
*
* @param fmt Format string.
* @param ... Format arguments.
*/
native DebugPrint(const String:fmt[], any:...);</pawn>

This could be easily implemented as:
<pawn>native DebugPrint(Handle:plugin, numParams)
{
decl String:buffer[1024], written

FormatNativeString(0, /* Use an output buffer */
1, /* Format param */
2, /* Format argument #1 */
sizeof(buffer), /* Size of output buffer */
written, /* Store # of written bytes */
buffer /* Use our buffer */
)

PrintToServer("[DEBUG] %s", buffer)
}</pawn>

==Throwing Errors==
Often, your native will encounter an unrecoverable error, and you wish to trigger a fatal exception. This is equivalent to <tt>IPluginContext::ThrowNativeError</tt>, and will halt the current function execution in the plugin. The debugger will be invoked and a backtrace will be printed out (if the plugin is in debug mode). Although the current function is cancelled, the plugin will continue to operate normally afterward.

For example, let's say we have a native that operates on clients. We want to throw an error if we get a client index that is invalid or disconnected. We could do this like so:
<pawn>public MyFunction(Handle:plugin, numParams)
{
new client = GetNativeCell(1)
if (client < 1 || client > GetMaxClients())
{
return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client)
}
if (!IsClientConnected(client))
{
return ThrowNativeError(SP_ERROR_NATIVE, "Client %d is not connected", client)
}
/* Code */
}</pawn>

[[Category:SourceMod Scripting]]

Creating Natives (SourceMod Scripting)

2012-09-16T15:29:33Z

FaTony: /* Arrays */

SourceMod allows plugins to create their own natives that other plugins can use. This is very similar to AMX Mod X's {{amxx_func|register_native}} function. It is a powerful inter-plugin communication resource that can greatly enhance the functionality you provide.

''Prerequisites:'' You should have a good grasp of Pawn or SourcePawn scripting, as well as how [[Tags (Scripting)|Tags]] work. 
''Note:'' Most functions herein can be found in the [[SourceMod SDK]], under <tt>plugins/include/functions.inc</tt>.

=Introduction=
Before creating natives, you should always document and specify exactly how they will work. This means writing your "include file" beforehand. Not only does this guide you in writing your natives, but it has the added benefit of completing a large portion of documentation at the same time.

==Include File==
For our first example, let's start off with a simple native that adds two numbers, a float and a non-float. It might look like this:
<pawn>/** Double-include prevention */
#if defined _mynatives_included_
#endinput
#endif
#define _mynatives_included_

/**
* Adds two numbers together.
*
* @param num1 An integer.
* @param num2 A float.
* @return The float value of the integer and float added together.
*/
native Float:My_AddNumbers(num1, num2);</pawn>

The documentation and commenting style above is a SourceMod Development Team convention. While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

==Creating the Native==
To actually create the native, first let's define the native handler itself. From <tt>functions.inc</tt> we can see that this follows the prototype:
<pawn>functag NativeCall public(Handle:plugin, numParams);</pawn>

Thus, we have a function like:
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
}</pawn>

Note that we don't use the same function name as we did in our include file. This is to prevent a possible ''name clash''. Otherwise, two different symbols (one a native, another a function) could have the same name, and that's not allowed. We'll see later how we bind the native to its actual name.

Next, we need to implement our native.
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
/* Retrieve the first parameter we receive */
new num1 = GetNativeCell(1);
/* Retrieve the second parameter we receive */
new Float:num2 = Float:GetNativeCell(2);
/* Add them together */
new Float:value = num1 + num2;
/* Return the value */
return _:value;
}</pawn>

You should note four important details. The first is that we have to manually grab the parameters -- they're not easily sent via arguments. This is for technical reasons that go beyond the scope of this document. That means you have to know exactly ''how'' to grab each parameter. For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.

However, the second detail is that there is no <tt>GetNativeCellFloat</tt>. This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently. Thus, we ''change'' the tag to <tt>Float</tt> manual. '''This is different from calling float(GetNativeCell(2)).''' In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).

Similarly, the third detail is that we cannot simply put <tt>return value</tt> or <tt>return FloatRound(value)</tt>. The reason is that our native is supposed to be returning a float. If we return <tt>value</tt>, we'll get a tag mismatch. If we return <tt>FloatRound(value)</tt>, we'll be returning an integer when a float is expected. The solution is to change the tag to the default tag, which will retain the value but remove the tag warning.

Lastly, we did not need to verify <tt>numParams</tt>. The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way. Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

==Registering the Native==
Natives must be registered in <tt>AskPluginLoad2</tt>. Although they can be registered elsewhere, only this function guarantees that all other plugins will see your native. The definition for this forward is in <tt>sourcemod.inc</tt>.

<pawn>public APLRes:AskPluginLoad2(Handle:myself, bool:late, String:error[], err_max)
{
CreateNative("My_AddNumbers", Native_My_AddNumbers);
return APLRes_Success;
}</pawn>

Now, any plugin will be able to use our native as if it were from a Core or a C++ extension.

=Usage=
==By-Reference==
Sometimes, it may be desirable to return data through by-reference parameters. For example, observe the following native prototype:
<pawn>/**
* Closes a Handle, and sets the variable to INVALID_HANDLE by reference.
*
* @param hndl Handle to close and clear.
* @return Anything that CloseHandle() returns.
*/
native bool:AltCloseHandle(&Handle:hndl);</pawn>

An implementation of this would look like:
<pawn>public Native_AltCloseHandle(Handle:plugin, numParams)
{
new Handle:hndl = Handle:GetNativeCellRef(1);
SetNativeCellRef(1, 0); /* Zero out the variable by reference */
return CloseHandle(hndl);
}</pawn>

Now, we have a native that is "safer" than a normal <tt>CloseHandle</tt>, as it ensures we don't hold onto invalid Handles.

==Strings==
Strings can be retrieved and altered via dynamic natives. Observe the following native prototype:
<pawn>/**
* Converts a string to upper case.
*
* @param str String to convert.
* @noreturn
*/
native StringToUpper(String:str[]);</pawn>

An implementation of this is very easy, because of dynamic arrays:
<pawn>public Native_StringToUpper(Handle:plugin, numParams)
{
new len;
GetNativeStringLength(1, len);

if (len <= 0)
{
return;
}

new String:str[len + 1];
GetNativeString(1, str, len + 1);

for (new i = 0; i < len; i++)
{
/* 5th bit specifies case in ASCII --
* this is not UTF-8 compatible.
*/
if ((str[i] & (1 << 5)) == (1 << 5))
{
str[i] &= ~(1 << 5)
}
}

SetNativeString(1, str, len+1, false);
}</pawn>

==Arrays==
Working with arrays is very similar to strings. For example, observe the following native prototype:
<pawn>/**
* Sums an array of numbers and returns the sum.
*
* @param array Array of numbers to sum.
* @param size Size of array.
* @return Sum of the array elements.
*/
native SumArray(const array[], size);</pawn>

An implementation of this could look like:
<pawn>public Native_SumArray(Handle:plugin, numParams)
{
new size = GetNativeCell(2);
if (size < 1)
{
return 0;
}

new array[size], total;
GetNativeArray(1, array, size);

for (new i = 0; i < size; i++)
{
total += array[i];
}
return total;
}</pawn>

Similarly, there is a <tt>SetNativeArray</tt>, which is used to alter array contents.

==Variable Arguments==
Variable arguments are usually used when dealing with [[Format Class Functions (SourceMod Scripting)|format class functions]], however it is also possible to use them for general functionality. The only trick is that unlike normal parameters, every variable argument parameter is passed by-reference. This adds no change for arrays and strings, but for floats, handles, numbers, or anything else that fits in a cell, <tt>GetNativeCellRef</tt> must be used instead.

As an example, let's convert our function from above to use variable arguments:
<pawn>/**
* Sums a list of numbers.
*
* @param num First number to use as a base.
* @param ... Any number of additional numbers to add.
* @return Sum of all numbers passed.
*/
native SumParams(num, ...);</pawn>

An implementation of this would look like:
<pawn>public Native_SumParams(Handle:plugin, numParams)
{
new base = GetNativeCell(1)
for (new i=2; i<=numParams; i++)
{
base += GetNativeCellRef(i)
}
return base
}</pawn>

==Format Functions==
It is also possible to create your own [[Format Class Functions (SourceMod Scripting)|format class functions]]. This topic is much more complicated than the previous ones, as the native string formatter allows for many different configurations. This is mainly for optimization. Note that a formatting routine deals with two buffers: the input format string, and the output buffer. <tt>FormatNativeString</tt>, by default, uses parameter indexes directly so you don't have to copy or locally store any of these buffers.

The most common usage of this is to accept a user-formatted string and to not
<pawn>/**
* Prints a message with a [DEBUG] prefix to the server.
*
* @param fmt Format string.
* @param ... Format arguments.
*/
native DebugPrint(const String:fmt[], any:...);</pawn>

This could be easily implemented as:
<pawn>native DebugPrint(Handle:plugin, numParams)
{
decl String:buffer[1024], written

FormatNativeString(0, /* Use an output buffer */
1, /* Format param */
2, /* Format argument #1 */
sizeof(buffer), /* Size of output buffer */
written, /* Store # of written bytes */
buffer /* Use our buffer */
)

PrintToServer("[DEBUG] %s", buffer)
}</pawn>

==Throwing Errors==
Often, your native will encounter an unrecoverable error, and you wish to trigger a fatal exception. This is equivalent to <tt>IPluginContext::ThrowNativeError</tt>, and will halt the current function execution in the plugin. The debugger will be invoked and a backtrace will be printed out (if the plugin is in debug mode). Although the current function is cancelled, the plugin will continue to operate normally afterward.

For example, let's say we have a native that operates on clients. We want to throw an error if we get a client index that is invalid or disconnected. We could do this like so:
<pawn>public MyFunction(Handle:plugin, numParams)
{
new client = GetNativeCell(1)
if (client < 1 || client > GetMaxClients())
{
return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client)
}
if (!IsClientConnected(client))
{
return ThrowNativeError(SP_ERROR_NATIVE, "Client %d is not connected", client)
}
/* Code */
}</pawn>

[[Category:SourceMod Scripting]]

Creating Natives (SourceMod Scripting)

2012-09-16T15:28:47Z

FaTony: /* Strings */

SourceMod allows plugins to create their own natives that other plugins can use. This is very similar to AMX Mod X's {{amxx_func|register_native}} function. It is a powerful inter-plugin communication resource that can greatly enhance the functionality you provide.

''Prerequisites:'' You should have a good grasp of Pawn or SourcePawn scripting, as well as how [[Tags (Scripting)|Tags]] work. 
''Note:'' Most functions herein can be found in the [[SourceMod SDK]], under <tt>plugins/include/functions.inc</tt>.

=Introduction=
Before creating natives, you should always document and specify exactly how they will work. This means writing your "include file" beforehand. Not only does this guide you in writing your natives, but it has the added benefit of completing a large portion of documentation at the same time.

==Include File==
For our first example, let's start off with a simple native that adds two numbers, a float and a non-float. It might look like this:
<pawn>/** Double-include prevention */
#if defined _mynatives_included_
#endinput
#endif
#define _mynatives_included_

/**
* Adds two numbers together.
*
* @param num1 An integer.
* @param num2 A float.
* @return The float value of the integer and float added together.
*/
native Float:My_AddNumbers(num1, num2);</pawn>

The documentation and commenting style above is a SourceMod Development Team convention. While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

==Creating the Native==
To actually create the native, first let's define the native handler itself. From <tt>functions.inc</tt> we can see that this follows the prototype:
<pawn>functag NativeCall public(Handle:plugin, numParams);</pawn>

Thus, we have a function like:
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
}</pawn>

Note that we don't use the same function name as we did in our include file. This is to prevent a possible ''name clash''. Otherwise, two different symbols (one a native, another a function) could have the same name, and that's not allowed. We'll see later how we bind the native to its actual name.

Next, we need to implement our native.
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
/* Retrieve the first parameter we receive */
new num1 = GetNativeCell(1);
/* Retrieve the second parameter we receive */
new Float:num2 = Float:GetNativeCell(2);
/* Add them together */
new Float:value = num1 + num2;
/* Return the value */
return _:value;
}</pawn>

You should note four important details. The first is that we have to manually grab the parameters -- they're not easily sent via arguments. This is for technical reasons that go beyond the scope of this document. That means you have to know exactly ''how'' to grab each parameter. For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.

However, the second detail is that there is no <tt>GetNativeCellFloat</tt>. This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently. Thus, we ''change'' the tag to <tt>Float</tt> manual. '''This is different from calling float(GetNativeCell(2)).''' In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).

Similarly, the third detail is that we cannot simply put <tt>return value</tt> or <tt>return FloatRound(value)</tt>. The reason is that our native is supposed to be returning a float. If we return <tt>value</tt>, we'll get a tag mismatch. If we return <tt>FloatRound(value)</tt>, we'll be returning an integer when a float is expected. The solution is to change the tag to the default tag, which will retain the value but remove the tag warning.

Lastly, we did not need to verify <tt>numParams</tt>. The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way. Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

==Registering the Native==
Natives must be registered in <tt>AskPluginLoad2</tt>. Although they can be registered elsewhere, only this function guarantees that all other plugins will see your native. The definition for this forward is in <tt>sourcemod.inc</tt>.

<pawn>public APLRes:AskPluginLoad2(Handle:myself, bool:late, String:error[], err_max)
{
CreateNative("My_AddNumbers", Native_My_AddNumbers);
return APLRes_Success;
}</pawn>

Now, any plugin will be able to use our native as if it were from a Core or a C++ extension.

=Usage=
==By-Reference==
Sometimes, it may be desirable to return data through by-reference parameters. For example, observe the following native prototype:
<pawn>/**
* Closes a Handle, and sets the variable to INVALID_HANDLE by reference.
*
* @param hndl Handle to close and clear.
* @return Anything that CloseHandle() returns.
*/
native bool:AltCloseHandle(&Handle:hndl);</pawn>

An implementation of this would look like:
<pawn>public Native_AltCloseHandle(Handle:plugin, numParams)
{
new Handle:hndl = Handle:GetNativeCellRef(1);
SetNativeCellRef(1, 0); /* Zero out the variable by reference */
return CloseHandle(hndl);
}</pawn>

Now, we have a native that is "safer" than a normal <tt>CloseHandle</tt>, as it ensures we don't hold onto invalid Handles.

==Strings==
Strings can be retrieved and altered via dynamic natives. Observe the following native prototype:
<pawn>/**
* Converts a string to upper case.
*
* @param str String to convert.
* @noreturn
*/
native StringToUpper(String:str[]);</pawn>

An implementation of this is very easy, because of dynamic arrays:
<pawn>public Native_StringToUpper(Handle:plugin, numParams)
{
new len;
GetNativeStringLength(1, len);

if (len <= 0)
{
return;
}

new String:str[len + 1];
GetNativeString(1, str, len + 1);

for (new i = 0; i < len; i++)
{
/* 5th bit specifies case in ASCII --
* this is not UTF-8 compatible.
*/
if ((str[i] & (1 << 5)) == (1 << 5))
{
str[i] &= ~(1 << 5)
}
}

SetNativeString(1, str, len+1, false);
}</pawn>

==Arrays==
Working with arrays is very similar to strings. For example, observe the following native prototype:
<pawn>/**
* Sums an array of numbers and returns the sum.
*
* @param array Array of numbers to sum.
* @param size Size of array.
* @return Sum of the array elements.
*/
native SumArray(const array[], size);</pawn>

An implementation of this could look like:
<pawn>public Native_SumArray(Handle:plugin, numParams)
{
new size = GetNativeCell(2)
if (size < 1)
{
return 0
}

new array[size], total
GetNativeArray(1, array, size)

for (new i=0; i<size; i++)
{
total += array[i]
}
return total
}</pawn>

Similarly, there is a <tt>SetNativeArray</tt>, which is used to alter array contents.

==Variable Arguments==
Variable arguments are usually used when dealing with [[Format Class Functions (SourceMod Scripting)|format class functions]], however it is also possible to use them for general functionality. The only trick is that unlike normal parameters, every variable argument parameter is passed by-reference. This adds no change for arrays and strings, but for floats, handles, numbers, or anything else that fits in a cell, <tt>GetNativeCellRef</tt> must be used instead.

As an example, let's convert our function from above to use variable arguments:
<pawn>/**
* Sums a list of numbers.
*
* @param num First number to use as a base.
* @param ... Any number of additional numbers to add.
* @return Sum of all numbers passed.
*/
native SumParams(num, ...);</pawn>

An implementation of this would look like:
<pawn>public Native_SumParams(Handle:plugin, numParams)
{
new base = GetNativeCell(1)
for (new i=2; i<=numParams; i++)
{
base += GetNativeCellRef(i)
}
return base
}</pawn>

==Format Functions==
It is also possible to create your own [[Format Class Functions (SourceMod Scripting)|format class functions]]. This topic is much more complicated than the previous ones, as the native string formatter allows for many different configurations. This is mainly for optimization. Note that a formatting routine deals with two buffers: the input format string, and the output buffer. <tt>FormatNativeString</tt>, by default, uses parameter indexes directly so you don't have to copy or locally store any of these buffers.

The most common usage of this is to accept a user-formatted string and to not
<pawn>/**
* Prints a message with a [DEBUG] prefix to the server.
*
* @param fmt Format string.
* @param ... Format arguments.
*/
native DebugPrint(const String:fmt[], any:...);</pawn>

This could be easily implemented as:
<pawn>native DebugPrint(Handle:plugin, numParams)
{
decl String:buffer[1024], written

FormatNativeString(0, /* Use an output buffer */
1, /* Format param */
2, /* Format argument #1 */
sizeof(buffer), /* Size of output buffer */
written, /* Store # of written bytes */
buffer /* Use our buffer */
)

PrintToServer("[DEBUG] %s", buffer)
}</pawn>

==Throwing Errors==
Often, your native will encounter an unrecoverable error, and you wish to trigger a fatal exception. This is equivalent to <tt>IPluginContext::ThrowNativeError</tt>, and will halt the current function execution in the plugin. The debugger will be invoked and a backtrace will be printed out (if the plugin is in debug mode). Although the current function is cancelled, the plugin will continue to operate normally afterward.

For example, let's say we have a native that operates on clients. We want to throw an error if we get a client index that is invalid or disconnected. We could do this like so:
<pawn>public MyFunction(Handle:plugin, numParams)
{
new client = GetNativeCell(1)
if (client < 1 || client > GetMaxClients())
{
return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client)
}
if (!IsClientConnected(client))
{
return ThrowNativeError(SP_ERROR_NATIVE, "Client %d is not connected", client)
}
/* Code */
}</pawn>

[[Category:SourceMod Scripting]]

Creating Natives (SourceMod Scripting)

2012-09-16T15:27:29Z

FaTony: /* Creating the Native */

SourceMod allows plugins to create their own natives that other plugins can use. This is very similar to AMX Mod X's {{amxx_func|register_native}} function. It is a powerful inter-plugin communication resource that can greatly enhance the functionality you provide.

''Prerequisites:'' You should have a good grasp of Pawn or SourcePawn scripting, as well as how [[Tags (Scripting)|Tags]] work. 
''Note:'' Most functions herein can be found in the [[SourceMod SDK]], under <tt>plugins/include/functions.inc</tt>.

=Introduction=
Before creating natives, you should always document and specify exactly how they will work. This means writing your "include file" beforehand. Not only does this guide you in writing your natives, but it has the added benefit of completing a large portion of documentation at the same time.

==Include File==
For our first example, let's start off with a simple native that adds two numbers, a float and a non-float. It might look like this:
<pawn>/** Double-include prevention */
#if defined _mynatives_included_
#endinput
#endif
#define _mynatives_included_

/**
* Adds two numbers together.
*
* @param num1 An integer.
* @param num2 A float.
* @return The float value of the integer and float added together.
*/
native Float:My_AddNumbers(num1, num2);</pawn>

The documentation and commenting style above is a SourceMod Development Team convention. While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

==Creating the Native==
To actually create the native, first let's define the native handler itself. From <tt>functions.inc</tt> we can see that this follows the prototype:
<pawn>functag NativeCall public(Handle:plugin, numParams);</pawn>

Thus, we have a function like:
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
}</pawn>

Note that we don't use the same function name as we did in our include file. This is to prevent a possible ''name clash''. Otherwise, two different symbols (one a native, another a function) could have the same name, and that's not allowed. We'll see later how we bind the native to its actual name.

Next, we need to implement our native.
<pawn>public Native_My_AddNumbers(Handle:plugin, numParams)
{
/* Retrieve the first parameter we receive */
new num1 = GetNativeCell(1);
/* Retrieve the second parameter we receive */
new Float:num2 = Float:GetNativeCell(2);
/* Add them together */
new Float:value = num1 + num2;
/* Return the value */
return _:value;
}</pawn>

You should note four important details. The first is that we have to manually grab the parameters -- they're not easily sent via arguments. This is for technical reasons that go beyond the scope of this document. That means you have to know exactly ''how'' to grab each parameter. For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.

However, the second detail is that there is no <tt>GetNativeCellFloat</tt>. This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently. Thus, we ''change'' the tag to <tt>Float</tt> manual. '''This is different from calling float(GetNativeCell(2)).''' In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).

Similarly, the third detail is that we cannot simply put <tt>return value</tt> or <tt>return FloatRound(value)</tt>. The reason is that our native is supposed to be returning a float. If we return <tt>value</tt>, we'll get a tag mismatch. If we return <tt>FloatRound(value)</tt>, we'll be returning an integer when a float is expected. The solution is to change the tag to the default tag, which will retain the value but remove the tag warning.

Lastly, we did not need to verify <tt>numParams</tt>. The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way. Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

==Registering the Native==
Natives must be registered in <tt>AskPluginLoad2</tt>. Although they can be registered elsewhere, only this function guarantees that all other plugins will see your native. The definition for this forward is in <tt>sourcemod.inc</tt>.

<pawn>public APLRes:AskPluginLoad2(Handle:myself, bool:late, String:error[], err_max)
{
CreateNative("My_AddNumbers", Native_My_AddNumbers);
return APLRes_Success;
}</pawn>

Now, any plugin will be able to use our native as if it were from a Core or a C++ extension.

=Usage=
==By-Reference==
Sometimes, it may be desirable to return data through by-reference parameters. For example, observe the following native prototype:
<pawn>/**
* Closes a Handle, and sets the variable to INVALID_HANDLE by reference.
*
* @param hndl Handle to close and clear.
* @return Anything that CloseHandle() returns.
*/
native bool:AltCloseHandle(&Handle:hndl);</pawn>

An implementation of this would look like:
<pawn>public Native_AltCloseHandle(Handle:plugin, numParams)
{
new Handle:hndl = Handle:GetNativeCellRef(1);
SetNativeCellRef(1, 0); /* Zero out the variable by reference */
return CloseHandle(hndl);
}</pawn>

Now, we have a native that is "safer" than a normal <tt>CloseHandle</tt>, as it ensures we don't hold onto invalid Handles.

==Strings==
Strings can be retrieved and altered via dynamic natives. Observe the following native prototype:
<pawn>/**
* Converts a string to upper case.
*
* @param str String to convert.
* @noreturn
*/
native StringToUpper(String:str[]);</pawn>

An implementation of this is very easy, because of dynamic arrays:
<pawn>public Native_StringToUpper(Handle:plugin, numParams)
{
new len
GetNativeStringLength(1, len)

if (len <= 0)
{
return
}

new String:str[len+1]
GetNativeString(1, str, len+1)

for (new i=0; i<len; i++)
{
/* 5th bit specifies case in ASCII --
* this is not UTF-8 compatible.
*/
if ((str[i] & (1<<5)) == (1<<5))
{
str[i] &= ~(1<<5)
}
}

SetNativeString(1, str, len+1, false)
}</pawn>

==Arrays==
Working with arrays is very similar to strings. For example, observe the following native prototype:
<pawn>/**
* Sums an array of numbers and returns the sum.
*
* @param array Array of numbers to sum.
* @param size Size of array.
* @return Sum of the array elements.
*/
native SumArray(const array[], size);</pawn>

An implementation of this could look like:
<pawn>public Native_SumArray(Handle:plugin, numParams)
{
new size = GetNativeCell(2)
if (size < 1)
{
return 0
}

new array[size], total
GetNativeArray(1, array, size)

for (new i=0; i<size; i++)
{
total += array[i]
}
return total
}</pawn>

Similarly, there is a <tt>SetNativeArray</tt>, which is used to alter array contents.

==Variable Arguments==
Variable arguments are usually used when dealing with [[Format Class Functions (SourceMod Scripting)|format class functions]], however it is also possible to use them for general functionality. The only trick is that unlike normal parameters, every variable argument parameter is passed by-reference. This adds no change for arrays and strings, but for floats, handles, numbers, or anything else that fits in a cell, <tt>GetNativeCellRef</tt> must be used instead.

As an example, let's convert our function from above to use variable arguments:
<pawn>/**
* Sums a list of numbers.
*
* @param num First number to use as a base.
* @param ... Any number of additional numbers to add.
* @return Sum of all numbers passed.
*/
native SumParams(num, ...);</pawn>

An implementation of this would look like:
<pawn>public Native_SumParams(Handle:plugin, numParams)
{
new base = GetNativeCell(1)
for (new i=2; i<=numParams; i++)
{
base += GetNativeCellRef(i)
}
return base
}</pawn>

==Format Functions==
It is also possible to create your own [[Format Class Functions (SourceMod Scripting)|format class functions]]. This topic is much more complicated than the previous ones, as the native string formatter allows for many different configurations. This is mainly for optimization. Note that a formatting routine deals with two buffers: the input format string, and the output buffer. <tt>FormatNativeString</tt>, by default, uses parameter indexes directly so you don't have to copy or locally store any of these buffers.

The most common usage of this is to accept a user-formatted string and to not
<pawn>/**
* Prints a message with a [DEBUG] prefix to the server.
*
* @param fmt Format string.
* @param ... Format arguments.
*/
native DebugPrint(const String:fmt[], any:...);</pawn>

This could be easily implemented as:
<pawn>native DebugPrint(Handle:plugin, numParams)
{
decl String:buffer[1024], written

FormatNativeString(0, /* Use an output buffer */
1, /* Format param */
2, /* Format argument #1 */
sizeof(buffer), /* Size of output buffer */
written, /* Store # of written bytes */
buffer /* Use our buffer */
)

PrintToServer("[DEBUG] %s", buffer)
}</pawn>

==Throwing Errors==
Often, your native will encounter an unrecoverable error, and you wish to trigger a fatal exception. This is equivalent to <tt>IPluginContext::ThrowNativeError</tt>, and will halt the current function execution in the plugin. The debugger will be invoked and a backtrace will be printed out (if the plugin is in debug mode). Although the current function is cancelled, the plugin will continue to operate normally afterward.

For example, let's say we have a native that operates on clients. We want to throw an error if we get a client index that is invalid or disconnected. We could do this like so:
<pawn>public MyFunction(Handle:plugin, numParams)
{
new client = GetNativeCell(1)
if (client < 1 || client > GetMaxClients())
{
return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client)
}
if (!IsClientConnected(client))
{
return ThrowNativeError(SP_ERROR_NATIVE, "Client %d is not connected", client)
}
/* Code */
}</pawn>

[[Category:SourceMod Scripting]]