AlliedModders Wiki - User contributions [en]

Function Calling API (SourceMod Scripting)

2022-01-06T11:45:11Z

Asherkin: Correct void forward event type

SourceMod provides plugins with an API for calling functions. This API can be used to call public functions in any plugin, including public functions in the same plugin.

This article is split into two sections. The first is on generic function calling, which is used for single function calls. The second is on Forwards, which is used for calling multiple functions in one operation.

For more information on forwards, readers should see [[Writing_Extensions#Creating_Events.2FForwards|forwards in extensions]].

=Generic Calling=
There are four steps to calling a function in a plugin:
<ol>
<li>Obtaining a "call Handle." This is either in the form of a function ID, tagged with <tt>Function</tt>, or a Forward Handle, tagged with <tt>Handle</tt>.</li>
<li>Starting the call.
<li>Pushing parameters in increasing order in a way that matches the function prototype.</li>
<li>Ending the the call, which performs the call operation and returns the result.</li>
</ol>

For simplicity, let's consider calling a function in our own plugin. We have the following function:
<sourcepawn>public void OnClientDied(int attacker, int victim, const char[] weapon, bool headshot)
{
char name[MAX_NAME_LENGTH];
GetClientName(victim, name, sizeof(name));

if (attacker != victim)
{
char other[MAX_NAME_LENGTH];
GetClientName(attacker, other, sizeof(other));
PrintToServer("<\"%s\"> killed by <\"%s\"> with \"%s\" (headshot: %d)", name, other, weapon, headshot);
}
else if (!attacker)
{
PrintToServer("<\"%s\"> killed by \"world\" with \"%s\" (headshot: %d)", name, weapon, headshot);
}
else
{
PrintToServer("<\"%s\"> killed by \"self\" with \"%s\" (headshot: %d)", name, weapon, headshot);
}
}</sourcepawn>

An indirect way to call this function would be:
<sourcepawn>
public void EventHandler(Event event, const char[] name, bool dontBroadcast)
{
if (StrEqual(name, "player_death"))
{
char weapon[64];
int result;

event.GetString("weapon", weapon, sizeof(weapon));

/* Start function call */
Call_StartFunction(null, OnClientDied);

/* Push parameters one at a time */
Call_PushCell(GetClientOfUserId(event.GetInt("attacker")));
Call_PushCell(GetClientOfUserId(event.GetInt("userid")));
Call_PushString(weapon);
Call_PushCell(event.GetInt("headshot"));

/* Finish the call, get the result */
Call_Finish(result);
}
}</sourcepawn>

This basic example shows starting and completing a function call. However, the real use of function calling is with forwards, which is covered in the next section.

=Forwards=
Forwards are much more advantageous over single function calls. They are expandable containers, so you can store and complete many calls with very little action. Furthermore, they also adjust themselves when contained plugins are unloaded. Lastly, they are type-checked; each forward's parameter types must be known in advance, and if you push a mismatching type, the call will not complete.

Forwards must be created using the following types:
*<tt>Param_Any</tt> - Any parameter type can be pushed
*<tt>Param_Cell</tt> - A non-Float cell can be pushed
*<tt>Param_Float</tt> - A Float cell can be pushed
*<tt>Param_String</tt> - A string can be pushed
*<tt>Param_Array</tt> - An array can be pushed
*<tt>Param_VarArgs</tt> - This and all further parameters can be any type, but will be by reference. This cannot be the first parameter type, and if it is used, it must be the last parameter type.
*<tt>Param_CellByRef</tt> - A non-Float cell by reference
*<tt>Param_FloatByRef</tt> - A Float cell by reference

Strings and arrays are implicitly by-reference. When pushing variable argument parameters, if anything is pushed by-value, it will be internally automatically converted to by-reference.

Since Forwards will call multiple functions in a row, it needs to know how to interpret the return values of functions. There are four predefined methods:
*<tt>ET_Ignore</tt> - All return values will be ignored; 0 will be returned at the end.
*<tt>ET_Single</tt> - Only the last return value will be returned.
*<tt>ET_Event</tt> - Function should return an <tt>Action</tt> value (<tt>core.inc</tt>). <tt>Plugin_Stop</tt> acts as <tt>Plugin_Handled</tt>. The highest value is returned.
*<tt>ET_Hook</tt> - Function should return an <tt>Action</tt> value. <tt>Plugin_Stop</tt> ends the forward call immediately.

Let's write a simple example. Our plugin, Plugin A, wants to tell other plugins when a player dies. It has two ways of doing this, either via a ''global'' forward or a ''private'' forward. A global forward acts upon all functions in all plugins that match a single name. A private forward lets you explicitly manage which functions are in the container.

==Global Forwards==
Global forwards are very simple to use. After creation, they do not need to be maintained. An example plugin below creates a global forward with the following prototype:
<sourcepawn>forward void OnClientDied(int attacker, int victim, const char[] weapon, bool headshot);</sourcepawn>

Implementation:
<sourcepawn>GlobalForward g_DeathForward;

public void OnPluginStart()
{
g_DeathForward = new GlobalForward("OnClientDied", ET_Ignore, Param_Cell, Param_Cell, Param_String, Param_Cell);
HookEvent("player_death", EventHandler);
}

public APLRes AskPluginLoad2(Handle plugin, bool late, char[] error, int err_max)
{
RegPluginLibrary("my_plugin");
}

public Action EventHandler(Event event, const char[] name, bool dontBroadcast)
{
char weapon[64];
event.GetString("weapon", weapon, sizeof(weapon));

/* Start function call */
Call_StartForward(g_DeathForward);

/* Push parameters one at a time */
Call_PushCell(GetClientOfUserId(event.GetInt("attacker")));
Call_PushCell(GetClientOfUserId(event.GetInt("userid")));
Call_PushString(weapon);
Call_PushCell(GetEventInt(event, "headshot"));

/* Finish the call */
Call_Finish();

return result;
}</sourcepawn>

==Private Forwards==
Private forwards require you to manually add functions to its container. This can leave you with much more flexibility. Like global forwards, they automatically remove functions from unloaded plugins.

Usually, this is done using dynamic natives; a plugin will expose a function to add to its own forwards. For example:
<sourcepawn>typedef OnClientDiedFunc = function Action (int attacker, int victim, const char[] weapon, bool headshot);

/**
* Calls the target function when a client dies.
*
* @param func OnClientDiedFunc function.
* @noreturn
*/
native void HookClientDeath(OnClientDiedFunc func);</sourcepawn>

An implementation of this might look like:
<sourcepawn>PrivateForward g_DeathForward;

public void OnPluginStart()
{
g_DeathForward = new PrivateForward(ET_Ignore, Param_Cell, Param_Cell, Param_String, Param_Cell);

CreateNative("HookClientDeath", Native_HookClientDeath);

HookEvent("player_death", EventHandler);
}

public int Native_HookClientDeath(Handle plugin, int numParams)
{
g_DeathForward.AddFunction(plugin, GetNativeFunction(1));
}</sourcepawn>

Note that the code to call the forward does not need to change at all.

A complete implementation of a private forward may look like this:
<sourcepawn>typedef MyFunction = function void (int client);
native void My_NativeEx(MyFunction func);</sourcepawn>

<sourcepawn>PrivateForward g_hDeathFwd;

// typedef MyFunction = function void (int client);
// native void My_NativeEx(MyFunction func);
public APLRes AskPluginLoad2(Handle plugin, bool late, char[] error, int err_max)
{
RegPluginLibrary("MyPlugin");

CreateNative("My_NativeEx", My_Native);

return APLRes_Success;
}

public void OnPluginStart()
{
HookEvent("player_death", Event_Death);
g_hDeathFwd = new PrivateForward(ET_Ignore, Param_Cell);
}

public int My_Native(Handle plugin, int numParams)
{
g_hDeathFwd.AddFunction(plugin, GetNativeFunction(1));
}

public Action Event_Death(Event event, const char[] name, bool dontBroadcast)
{
int client = GetClientOfUserId(event.GetInt("userid"));

Call_StartForward(g_hDeathFwd);
Call_PushCell(client);
Call_Finish();
}</sourcepawn>

[[Category:SourceMod Scripting]]

Introduction to SourcePawn 1.7

2021-10-07T23:22:17Z

Asherkin: No such thing as an unsigned left shift

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

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

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

==Symbols/Keywords==
A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.

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

==Variables==
There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable "a" could hold the number "2", "16", "0", et cetera. Since a variable holds data, it also allocates the memory needed to store that data.

In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has four types of data that are most commonly used:
* Integers, using the <tt>int</tt> type. Integer types may store a whole number from -2147483648 to 2147483647.
* Floats, using the <tt>float</tt> type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.
* Characters, using the <tt>char</tt> type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.
* Booleans, using the <tt>bool</tt> type. Booleans store either true or false.

Example of creating variables and assigning values:

<sourcepawn>int money = 5400;
float percent = 67.3;
char key = 'A';
bool enabled = false;
</sourcepawn>

==Functions==
The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:

<sourcepawn>
show(56); // Calls the "show" function, and gives it the number 56.
enable(); // Calls the "enable" function with no values.
bool visible = show(a); //Calls the "show" function, stores its result in a variable.
</sourcepawn>

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

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

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

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

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

=Language Paradigms=
Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.
*'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the <tt>new</tt> keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].
*'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.
*'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.
*'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe.
*'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a ".smx" file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.

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

=Variables=
Pawn currently supports the following basic variable types:
*<tt>bool</tt> - true or false.
*<tt>char</tt> - an 8-bit ASCII character.
*<tt>int</tt> - a 32-bit signed integer.
*<tt>float</tt> - a 32-bit IEEE-754 floating point number.
*<tt>Handle</tt> - the base type of a SourceMod object

Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from <tt>Handle</tt>.

Strings, currently, are 0-terminated arrays of <tt>char</tt>s. They're described a little further ahead.

==Declaration==
Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.

<sourcepawn>
int a = 5;
float b = 5.0;
bool c = true;
bool d = false;
</sourcepawn>

Invalid variable usage:
<sourcepawn>
int a = 5.0; // Type mismatch. 5.0 is a float.
float b = 5; // Type mismatch. 5 is an integer.
</sourcepawn>

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

==Assignment==
Variables can be re-assigned data after they are created. For example:
<sourcepawn>int a;
float b;
bool c;

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

=Arrays=
An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.

==Declaration==
An array is declared using brackets. Some examples of arrays:
<sourcepawn>
int players[32]; // Stores 32 integers.
float origin[3]; // Stores 3 floating point numbers
</sourcepawn>

By default, arrays are initialized to 0. You can assign them different default values, however:
<sourcepawn>
int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.
float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.
int autoNum[3] = {1, ...}; // Stores 1, 1, 1
</sourcepawn>

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

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

When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,

<sourcepawn>
int[] numbers = new int[MaxClients]
</sourcepawn>

This creates an array of size <tt>MaxClients</tt>, which could be anything, so the size of the array is not known until the array is allocated.

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

For example, here is an example of the above code using indexes:
<sourcepawn>
int numbers[5];
float origin[3];

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

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

Using an incorrect index will cause an error. For example:
<sourcepawn>
int numbers[5];

numbers[5] = 20;</sourcepawn>

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

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

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

Expressions will be discussed in depth later in the article.

=Enums=
Enums are retyped integers. A new enum can be declared as follows:

<sourcepawn>enum MyEnum // the name is optional
{
MyFirstValue, // == 0, if not explicitly assigned, the first value is zero
MySecondValue, // == 1, implicitly set to the previous value plus one
MyThirdValue = 1, // == 1, explicitly assign to one -- multiple names can share the same value
MyFourthValue, // == 2
}
</sourcepawn>

To allow implicit conversions of enums back to integers (that is, so functions expecting a value of type 'int' accepts it as one instead of generating a warning), the enum must either be anonymous (unnamed) or must start with a lowercase character.

=Strings=
Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.

In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.

==Usage==
Strings are usually declared as arrays. For example:
<sourcepawn>
char message[] = "Hello!";
char clams[6] = "Clams";
</sourcepawn>

These are equivalent to doing:
<sourcepawn>
char message[7];
char clams[6];

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

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

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

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

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

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

==Concatenation==
In programming, concatenation is the operation of joining character strings end-to-end. The benefit of this is to improve the readability of the source code for humans, since the compiler will continue to treat the strings as a single string. String literals can be concatenated with the <tt>...</tt> or <tt>\</tt> operator:

<sourcepawn>
char text[] = "This is a really long string of text that should be split over multiple lines for the sake of readability."

char text[] = "This is a really long string of text that should be "
... "split over multiple lines for the sake of readability."; // Valid.

char text[] = "This is a really long string of text that should be \
split over multiple lines for the sake of readability."; // Valid.

char prefix[] = "What you can't do, however, ";
char moreText[] = prefix ... "is concatenate using a non-literal string."; // Invalid, not a constant expression.
</sourcepawn>

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

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

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

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

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

Example of a function:
<sourcepawn>
int AddTwoNumbers(int first, int second)
{
int sum = first + second;
return sum;
}</sourcepawn>

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

Broken down, it means:
*<tt>int</tt> - Return value type (integer).
*<tt>AddTwoNumbers</tt> - Name of the function.
*<tt>int first</tt> - First parameter, an integer.
*<tt>int second</tt> - Second parameter, an integer.

The body is a block of code. It creates a new variable, called <tt>sum</tt>, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the <tt>return</tt> statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called <tt>void</tt>.

A function can accept any type of input, and it can return any non-array type.

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

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

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

ChangeValue(a);

void ChangeValue(int b)
{
b = 5;
}</sourcepawn>

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

More examples of functions will be provided throughout the article.

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

<sourcepawn>forward void OnPluginStart();
forward void OnClientDisconnected(int client);</sourcepawn>

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

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

public void OnClientDisconnected(int client)
{
/* Code here */
}</sourcepawn>

The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.

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

<sourcepawn>native float FloatRound(float num);</sourcepawn>

It can be called like so:
<sourcepawn>int rounded = FloatRound(5.2); // rounded will be 5</sourcepawn>

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

<sourcepawn>
int example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

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

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

Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.

To prevent an array from being modified in a function, you can mark it as <tt>const</tt>. This will raise an error on code that attempts to modify it. For example:

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

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

When a function takes an array as a parameter, you can also pass any indexed array element which will be interpreted as a sub-array (slice) that begins from that index. For example,
if you want to get the length of a string, you can use the strlen function like so:

<sourcepawn>
char myString[] = "myString";
int length = strlen(myString); // Set length = 8
</sourcepawn>

And if you pass an indexed array element, it will be interpreted as a slice that begins from that index like so:

<sourcepawn>
char myString[] = "myString";
int length = strlen(myString[2]); // Set length = 6
</sourcepawn>

==Named Parameters==
With functions that have many parameters with default values, you can call the function with named parameters to assign a value based on its name instead of which position it is in the argument list. For example:

<sourcepawn>
void SomeFunctionWithDefaultParams(int a, int b = 1, int c = 2, int d = 3, int e = 4);

// If you want to call it with a different value for `d` -- note the dotted argument assignment
SomeFunctionWithDefaultParams(0, .d = 14);

// This is effectively the same, but less readable:
SomeFunctionWithDefaultParams(0, _, _, 14, _);
</sourcepawn>

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

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

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

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

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

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

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

a = a + 5;</sourcepawn>

Can be rewritten as:
<sourcepawn>int a = 5;
a += 5;</sourcepawn>

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

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

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

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

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

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

For example:

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

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

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

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

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

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

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

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

For example:
<sourcepawn>
int a = 5;</sourcepawn>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return total;
}</sourcepawn>

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

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

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

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

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

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

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

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

return total;
}</sourcepawn>

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

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

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

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

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

return index;
}</sourcepawn>

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

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

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

return sum;
}</sourcepawn>

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

<sourcepawn>
int A, B, C;

void Function1()
{
int B;

Function2();
}

void Function2()
{
int C;
}</sourcepawn>

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

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

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

Function1();
}</sourcepawn>

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

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

<sourcepawn>void Function1()
{
int A;

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

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

if (A)
{
int B = 5;
}

B = 5;
}</sourcepawn>

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

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

<sourcepawn>void Function1(int size)
{
int[] array = new int[size];

/* Code */
}</sourcepawn>

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

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

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>int float or char</tt>.

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

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

<sourcepawn>//file1.inc
static float g_value1 = 0.15f;

//file2.inc
static float g_value2 = 0.15f;</sourcepawn>

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

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

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

counter += inc;

return counter;
}</sourcepawn>

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

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

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

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

Note that statics can exist in any local scope:

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourcePawn 1.7

2021-07-19T21:19:03Z

Asherkin: "sub-arrays" are formally known as slices

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

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

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

==Symbols/Keywords==
A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.

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

==Variables==
There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable "a" could hold the number "2", "16", "0", et cetera. Since a variable holds data, it also allocates the memory needed to store that data.

In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:
* Integers, using the <tt>int</tt> type. Integer types may store a whole number from -2147483648 to 2147483647.
* Floats, using the <tt>float</tt> type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.
* Characters, using the <tt>char</tt> type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.
* Booleans, using the <tt>bool</tt> type. Booleans store either true or false.

Example of creating variables and assigning values:

<sourcepawn>int money = 5400;
float percent = 67.3;
char key = 'A';
bool enabled = false;
</sourcepawn>

==Functions==
The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:

<sourcepawn>
show(56); // Calls the "show" function, and gives it the number 56.
enable(); // Calls the "enable" function with no values.
bool visible = show(a); //Calls the "show" function, stores its result in a variable.
</sourcepawn>

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

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

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

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

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

=Language Paradigms=
Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.
*'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the <tt>new</tt> keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].
*'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.
*'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.
*'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe.
*'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a ".smx" file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.

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

=Variables=
Pawn currently supports the following basic variable types:
*<tt>bool</tt> - true or false.
*<tt>char</tt> - an 8-bit ASCII character.
*<tt>int</tt> - a 32-bit signed integer.
*<tt>float</tt> - a 32-bit IEEE-754 floating point number.
*<tt>Handle</tt> - the base type of a SourceMod object

Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from <tt>Handle</tt>.

Strings, currently, are 0-terminated arrays of <tt>char</tt>s. They're described a little further ahead.

==Declaration==
Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.

<sourcepawn>
int a = 5;
float b = 5.0;
bool c = true;
bool d = false;
</sourcepawn>

Invalid variable usage:
<sourcepawn>
int a = 5.0; // Type mismatch. 5.0 is a float.
float b = 5; // Type mismatch. 5 is an integer.
</sourcepawn>

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

==Assignment==
Variables can be re-assigned data after they are created. For example:
<sourcepawn>int a;
float b;
bool c;

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

=Arrays=
An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.

==Declaration==
An array is declared using brackets. Some examples of arrays:
<sourcepawn>
int players[32]; // Stores 32 integers.
float origin[3]; // Stores 3 floating point numbers
</sourcepawn>

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

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

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

When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,

<sourcepawn>
int[] numbers = new int[MaxClients]
</sourcepawn>

This creates an array of size <tt>MaxClients</tt>, which could be anything, so the size of the array is not known until the array is allocated.

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

For example, here is an example of the above code using indexes:
<sourcepawn>
int numbers[5];
float origin[3];

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

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

Using an incorrect index will cause an error. For example:
<sourcepawn>
int numbers[5];

numbers[5] = 20;</sourcepawn>

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

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

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

Expressions will be discussed in depth later in the article.

=Enums=
Enums are retyped integers. A new enum can be declared as follows:

<sourcepawn>enum MyEnum // the name is optional
{
MyFirstValue, // == 0, if not explicitly assigned, the first value is zero
MySecondValue, // == 1, implicitly set to the previous value plus one
MyThirdValue = 1, // == 1, explicitly assign to one -- multiple names can share the same value
MyFourthValue, // == 2
}
</sourcepawn>

To allow implicit conversions of enums back to integers (that is, so functions expecting a value of type 'int' accepts it as one instead of generating a warning), the enum must either be anonymous (unnamed) or must start with a lowercase character.

=Strings=
Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.

In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.

==Usage==
Strings are usually declared as arrays. For example:
<sourcepawn>
char message[] = "Hello!";
char clams[6] = "Clams";
</sourcepawn>

These are equivalent to doing:
<sourcepawn>
char message[7];
char clams[6];

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

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

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

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

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

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

==Concatenation==
In programming, concatenation is the operation of joining character strings end-to-end. The benefit of this is to improve the readability of the source code for humans, since the compiler will continue to treat the strings as a single string. String literals can be concatenated with the <tt>...</tt> or <tt>\</tt> operator:

<sourcepawn>
char text[] = "This is a really long string of text that should be split over multiple lines for the sake of readability."

char text[] = "This is a really long string of text that should be "
... "split over multiple lines for the sake of readability."; // Valid.

char text[] = "This is a really long string of text that should be \
split over multiple lines for the sake of readability."; // Valid.

char prefix[] = "What you can't do, however, ";
char moreText[] = prefix ... "is concatenate using a non-literal string."; // Invalid, not a constant expression.
</sourcepawn>

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

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

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

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

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

Example of a function:
<sourcepawn>
int AddTwoNumbers(int first, int second)
{
int sum = first + second;
return sum;
}</sourcepawn>

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

Broken down, it means:
*<tt>int</tt> - Return value type (integer).
*<tt>AddTwoNumbers</tt> - Name of the function.
*<tt>int first</tt> - First parameter, an integer.
*<tt>int second</tt> - Second parameter, an integer.

The body is a block of code. It creates a new variable, called <tt>sum</tt>, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the <tt>return</tt> statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called <tt>void</tt>.

A function can accept any type of input, and it can return any non-array type.

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

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

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

ChangeValue(a);

void ChangeValue(int b)
{
b = 5;
}</sourcepawn>

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

More examples of functions will be provided throughout the article.

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

<sourcepawn>forward void OnPluginStart();
forward void OnClientDisconnected(int client);</sourcepawn>

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

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

public void OnClientDisconnected(int client)
{
/* Code here */
}</sourcepawn>

The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.

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

<sourcepawn>native float FloatRound(float num);</sourcepawn>

It can be called like so:
<sourcepawn>int rounded = FloatRound(5.2); // rounded will be 5</sourcepawn>

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

<sourcepawn>
int example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

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

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

Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.

To prevent an array from being modified in a function, you can mark it as <tt>const</tt>. This will raise an error on code that attempts to modify it. For example:

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

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

When a function takes an array as a parameter, you can also pass any indexed array element which will be interpreted as a sub-array (slice) that begins from that index. For example,
if you want to get the length of a string, you can use the strlen function like so:

<sourcepawn>
char myString[] = "myString";
int length = strlen(myString); // Set length = 8
</sourcepawn>

And if you pass an indexed array element, it will be interpreted as a slice that begins from that index like so:

<sourcepawn>
char myString[] = "myString";
int length = strlen(myString[2]); // Set length = 6
</sourcepawn>

==Named Parameters==
With functions that have many parameters with default values, you can call the function with named parameters to assign a value based on its name instead of which position it is in the argument list. For example:

<sourcepawn>
void SomeFunctionWithDefaultParams(int a, int b = 1, int c = 2, int d = 3, int e = 4);

// If you want to call it with a different value for `d` -- note the dotted argument assignment
SomeFunctionWithDefaultParams(0, .d = 14);

// This is effectively the same, but less readable:
SomeFunctionWithDefaultParams(0, _, _, 14, _);
</sourcepawn>

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

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

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

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

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

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

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

a = a + 5;</sourcepawn>

Can be rewritten as:
<sourcepawn>int a = 5;
a += 5;</sourcepawn>

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

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

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

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

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

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

For example:

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

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

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

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

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

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

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

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

For example:
<sourcepawn>
int a = 5;</sourcepawn>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return total;
}</sourcepawn>

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

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

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

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

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

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

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

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

return total;
}</sourcepawn>

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

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

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

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

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

return index;
}</sourcepawn>

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

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

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

return sum;
}</sourcepawn>

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

<sourcepawn>
int A, B, C;

void Function1()
{
int B;

Function2();
}

void Function2()
{
int C;
}</sourcepawn>

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

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

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

Function1();
}</sourcepawn>

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

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

<sourcepawn>void Function1()
{
int A;

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

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

if (A)
{
int B = 5;
}

B = 5;
}</sourcepawn>

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

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

<sourcepawn>void Function1(int size)
{
int[] array = new int[size];

/* Code */
}</sourcepawn>

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

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

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>int float or char</tt>.

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

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

<sourcepawn>//file1.inc
static float g_value1 = 0.15f;

//file2.inc
static float g_value2 = 0.15f;</sourcepawn>

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

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

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

counter += inc;

return counter;
}</sourcepawn>

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

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

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

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

Note that statics can exist in any local scope:

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Writing Extensions

2021-05-22T17:00:33Z

Asherkin:

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

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

=SDK Structure=
First, download the [[SourceMod SDK]] from the [https://github.com/alliedmodders/sourcemod SourceMod github], and one of the SDKs from the [https://github.com/alliedmodders/hl2sdk hl2sdk github].

There are some scripts in the SourceMod repo to easily download all the dependencies, see the info at [[Building_SourceMod#Downloading_Source_and_Dependencies]].

The directory structure should contain these folders:
<code>
* hl2sdk-something - One of the HL2 SDKs
* sourcemod-version - The sourcemod package
** extensions - Sourcemod Extensions code
*** curl - Source code to the cURL extension
*** geoip - Source code to the GeoIP extension
*** mysql - Source code to the MySQL extension
** plugins - Source code to all of SourceMod's plugins
*** include - The include files which document plugin API
** public - Interface files for SourceMod's Core Interfaces
*** extensions - Interfaces that are provided by extensions
*** '''sample_ext''' - The Sample Extension SDK
**** extension.cpp - Sample C++ plugin
**** extension.h - Sample C++ header file
**** Makefile - Sample C++ plugin compiler
**** smsdk_config.h - Sample C++ plugin settings
** sourcepawn - The include/interface files for SourcePawn
</code>

=Starting an Extension=
For simplicity, this article will assume you are using the SDK base files. Navigate to <code>extensions/public/sample_ext</code>, and ensure that you can compile your code. If using the command line, <code>make</code> should do this, if using Visual Studio, see [[#Setting up Visual Studio|Setting up Visual Studio]].

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

Next, you should change the name of your extension. By convention, your extension's class name should start with a capital letter.
* First, open <code>extension.h</code> and change "Sample" in this line:
<cpp>class Sample : public SDKExtension</cpp>
* Next, open <code>extension.cpp</code> change these two lines:
<cpp>Sample g_Sample;
SMEXT_LINK(&g_Sample);</cpp>

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

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

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

You should now be able to compile a blank extension!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return true;
}</cpp>

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

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

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

Example prototype:
<sourcepawn>typedef SayChatHook = function Action (int client, const char[] text);

native void AddSayChatHook(SayChatHook hook);
native void RemoveSayChatHook(SayChatHook hook);</sourcepawn>

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

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

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

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

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

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

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

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

Example:
<cpp>#ifndef _INCLUDE_MYINTERFACE_FILE_H_
#define _INCLUDE_MYINTERFACE_FILE_H_

#include <IShareSys.h>

#define SMINTERFACE_MYINTERFACE_NAME "IMyInterface"
#define SMINTERFACE_MYINTERFACE_VERSION 1

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

#endif //_INCLUDE_MYINTERFACE_FILE_H_</cpp>

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

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

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

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

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

IPluginManager *g_pPlugins = NULL;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A few notes:
*This only works for extensions using the .ext.<platform> convention. SourceMod cuts off the ".autoload" portion of the file, then adds the appropriate extension just as if 'sm exts load' was used.
*The file does not need to contain anything, it simply needs to exist.

=Conventions=

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

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

=Setting up Visual Studio=

{{qnotice|It is recommended that you make a copy of the sample_ext project and modify that rather than create your own project, as it will set up most of this for you}} 

== Sample Project ==

Instead of manually creating a project, you can make a copy of the sample_ext project and modify it.

The sample_ext project assumes that it is located in a subdirectory inside the SourceMod public directory. To change this, modify all references to ..\.. to $(SOURCEMOD15)\public and specify the SOURCEMOD15 variable as mentioned in the Optional Environment variables.

The sample_ext projectuses the following environment variables to locate the various source code parts. To set environment variables:

'''Windows XP''': Start -> Settings -> Control Panel -> System -> Advanced -> Environment Variables

'''Windows Vista/7''': Start -> Control Panel -> System -> Advanced system properties -> Advanced -> Environment Variables

=== Environment Variables ===

The environment variables used are:

* '''MMSOURCE17''': Path to MetaMod: Source source code for version 1.7 or newer. Used to compile SourceMod itself.
* '''MMSOURCE18''': Path to MetaMod: Source source code for version 1.8 or newer. Used in SourceMod 1.4 projects.
* '''MMSOURCE19''': Path to MetaMod: Source source code for version 1.9 or newer. Used in SourceMod 1.5 projects.
* '''HL2SDK''': Path to the Episode 1 SDK
* '''HL2SDK-SWARM''': Path to the Alien Swarm SDK
* '''HL2SDK-DARKM''': Path to the Dark Messiah SDK
* '''HL2SDKCSGO''': Path to the Counter-Strike: Global Offensive SDK
* '''HL2SDKCSS''': Path to the Counter-Strike: Source SDK
* '''HL2SDKL4D''': Path to the Left 4 Dead SDK
* '''HL2SDKL4D2''': Path to the Left 4 Dead 2 SDK
* '''HL2SDKOB''': Path to the Orange Box SDK (not Source 2009)
* '''HL2SDKOBVALVE''': Path to the Orange Box Valve / Source 2009 SDK (Half-Life 2: Deathmatch, Day of Defeat: Source, Team Fortress 2)

Optional environment variables:

* '''SOURCEMOD15'': Optional path to SourceMod 1.5 or newer source code

==Manually configuring a project==

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

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

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

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

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

For VS 2005, goto Project->Properties.

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

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

Multiple or Forked Servers (SourceMod)

2020-08-05T23:12:18Z

Asherkin: Reverted edits by Almil36 (talk) to last revision by Asherkin

SourceMod does not support running more than one server from the same SourceMod installation. This means you cannot:
*Point multiple forked servers (a feature in Left 4 Dead's srcds) at one SourceMod install.
*Start multiple copies of the same srcds to the same SourceMod install.

The reason for this is that SourceMod needs to "own" certain folders.
*SourceMod's auto-updating feature overwrites gamedata files, and could one day overwrite other files as well.
*The "data" folder is considered writeable for any purpose, and can be used to store locks that live beyond process IDs.

You can have multiple copies of SourceMod in your "addons" folder, however. For example, you can have <tt>addons/sourcemod1</tt> and <tt>addons/sourcemod2</tt>. There are two ways to make this work.

Specify <tt>+sm_basepath</tt> on the server command line. For example:
<pre>srcds -game tf +maxplayers 12 +sm_basepath addons/sourcemod2</pre>

If you are looking to save space or unify certain files that you know will not change, use symlinks. On Linux/FreeBSD this is the <tt>ln -s</tt> command (<tt>man ln</tt>). On Windows Vista or 2008 Server, this is <tt>mklink</tt> from the command prompt.

[[Category:SourceMod Documentation]]

Entity References (SourceMod)

2020-05-04T13:24:11Z

Asherkin: Reverted edits by Joinedsenses (talk) to last revision by Xerox8521

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

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

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

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

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

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

<pawn>
int index = EntRefToEntIndex(ref);

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

==Using References to handle a logic entity==

<pawn>
int ent = -1;

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

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

}
</pawn>

[[Category:SourceMod Scripting]]

SourceMod Profiler

2019-12-07T22:51:08Z

Asherkin: Replace the entire page with a stub as it documents the old profiler

SourceMod has built-in profiling support for plugins with integration into the game's "vprof" system.

See the "sm prof" command for more details.

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

SSH Keys

2019-04-05T08:33:45Z

Asherkin: Add note about PuTTY website.

=Introduction=
A private-public key pair allows one to a access remote server via SSH with a preset encryption key, rather than just a password. Key pairs can be generated with <tt>ssh-keygen</tt> on Linux and <tt>PuTTYGen</tt> on Windows. When a key pair is generated, a passphrase may be created. If there is a passphrase set, then <tt>ssh-agent</tt> on Linux or <tt>Pageant</tt> on Windows can be used for logging in without needing to type the passphrase. This article explains how to use these tools in order to log in to a remote server using SSH and not typing a password.

=Windows=
First, you should make sure you have the <tt>Pageant</tt> and <tt>PuTTYGen</tt> programs downloaded. If you already have <tt>PuTTY</tt> and you installed it via an automated installer program, then it is likely you already have these. You should be able to find them in the directory in which <tt>PuTTY</tt> was installed. If you do not have them, you can grab both from the <tt>PuTTY</tt> downloads page: https://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. There are lots of websites, many more legitimate looking than the official site, distributing malicious copies of the <tt>PuTTY</tt> tools due to its popularity, make sure to always download from the official website linked previously. 

Open <tt>PuTTYGen</tt> first and click the button labeled "Generate." It will then ask you to move the mouse cursor over the blank area on the program's window (in order to generate some randomness for the keys). Then it will ask you to enter a comment (which is already filled, but may be changed) and the key's passphrase twice. You may leave this passphrase blank if you never wish to enter any kind of password for accessing the server via SSH. However it might be a good idea to enter something there for extra security. When using <tt>Pageant</tt>, you will only have to enter this passphrase once per Windows login. Your <tt>PuTTYGen</tt> window may look like this:

[[Image:PuTTYGen.png]]

Click the button labeled "Save private key" and save this key somewhere on your computer, such as your <tt>My Documents</tt> directory. Right click in the area that shows your public key and select "Select All" from the menu. Then right click again and select "Copy."

Next, open a terminal window (with <tt>PuTTY</tt> or some other program) to the server that you wish to access using this key pair. Navigate to your home directory if you are not already there, and look for a directory named <tt>.ssh</tt>. If you do not have this directory, then create it like so:
<pre>cd ~
mkdir --mode=700 .ssh
cd .ssh</pre>
Now you can go into this directory and type <tt>echo</tt>. Then right click on your terminal window. This should then paste your public key into the window. Then type a space after your public key followed by <tt>>> authorized_keys</tt> and press the enter key. Here is an example:
<pre>echo mypastedkey >> authorized_keys</pre>

Lastly, make sure your <tt>authorized_keys</tt> file has the correct permissions, or else it will not load. You can do this with:
<pre>chmod 600 authorized_keys</pre>

Now you should open <tt>Pageant</tt>. An icon for the program should appear in your system tray. Right click on this icon and select "Add Key" from the context menu.

[[Image:Pageant_TrayMenu.png]]

A file dialog box will appear. Find and select the private key file that you saved earlier. If you chose to use a passphrase, it will ask you to enter it once. If you did not have a passphrase, then the key will be added automatically.

Now you may access the server via SSH in any way (such as using [[Subversion Tutorial#TortoiseSVN|TortoiseSVN]]) without having to enter a password again. If you reboot your computer, or log out of your Windows session and log back in, you only have to open <tt>Pageant</tt> and add your key file again.

=Linux=

First, a private-public key pair must be created. You can do this by using <tt>ssh-keygen</tt>, which comes with openssh (which should already be installed). Type "<tt>ssh-keygen -t rsa</tt>". You will be asked to type a path to the file that will be created. You can press enter here because the default is usually fine. You will then be asked for the passphrase twice. As mentioned in the Windows section above, this is optional. You may leave this passphrase blank (by pressing enter when it asks) if you wish to use the keys without having to type a password. However, it might be a good idea to use one for extra security. When using <tt>ssh-agent</tt>, you will only have to enter this passphrase once per login.

Here's an example of what may occur with <tt>ssh-keygen</tt>:
<pre>damagedsoul@sente ~ $ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/users/damagedsoul/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/users/damagedsoul/.ssh/id_rsa.
Your public key has been saved in /home/users/damagedsoul/.ssh/id_rsa.pub.
The key fingerprint is:
69:11:bb:1f:9b:e4:52:53:e1:75:30:75:b5:d2:c1:ba damagedsoul@sente.tcwonline.org</pre>

There should now be a file named <tt>id_rsa.pub</tt> in the <tt>.ssh</tt> directory of your home directory. Upload this file to the home directory of the server you wish to access using <tt>scp</tt> or some other means. Start an SSH session with the remote server and then navigate to your home directory if you are not already there. Then you can add the contents of <tt>id_rsa.pub</tt> to your <tt>authorized_keys</tt> file in the <tt>.ssh</tt> directory. If you do not have an <tt>.ssh</tt> directory, then you will have to create it.

Here is an example of the above information:
<pre>scp ~/.ssh/id_rsa.pub damagedsoul@takkun.tcwonline.org:~/
ssh damagedsoul@takkun.tcwonline.org</pre>
These next commands are then executed on the remote server:
<pre>cd ~
mkdir --mode=700 .ssh
cat id_rsa.pub >> .ssh/authorized_keys</pre>

Now exit from the remote server's SSH session. You now need to run <tt>ssh-agent</tt>. However, if you have a blank passphrase, the following steps are not necessary and you may begin logging in to the remote server without a password.

If you did enter a passphrase, then execute the following commands:
<pre>eval `ssh-agent -s`
ssh-add</pre>

It would also probably be a good idea to add a command to kill all <tt>ssh-agent</tt> processes to your shell's logout script (for example <tt>~/.bash_logout</tt>) or else you may leave behind some stray processes.
<pre>echo killall ssh-agent >> ~/.bash_logout</pre>

You may now access the remote server via SSH in any way (such as using [[Subversion Tutorial|svn]]) without having to enter a password again. If you reboot or log out and log back in, you only have to run <tt>ssh-agent</tt> and <tt>ssh-add</tt> again.

Menus Step By Step (SourceMod Scripting)

2018-12-21T18:16:40Z

Asherkin: Remove SetMenuTitle note, it causes confusion.

The SourceMod [[Menu API (SourceMod)|Menu API]] is fairly useful for displaying an information panel, a menu, or a vote to users. This document talks specifically about menus and how to create one.

== The working menu example ==

This is the working code example that we'll be talking about in the upcoming sections. If you need to, you can come back and look at it as you read the rest of this page.

We will be using PrintToServer to print text to the server console as we run through the events.

Usage of the [[Translations (SourceMod Scripting)|Translations]] system is highly recommended and will be used in this example.

<pawn>#define CHOICE1 "#choice1"
#define CHOICE2 "#choice2"
#define CHOICE3 "#choice3"

public void OnPluginStart()
{
LoadTranslations("menu_test.phrases");
RegConsoleCmd("menu_test1", Menu_Test1);
}

public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)
{
switch(action)
{
case MenuAction_Start:
{
PrintToServer("Displaying menu");
}

case MenuAction_Display:
{
char buffer[255];
Format(buffer, sizeof(buffer), "%T", "Vote Nextmap", param1);

Panel panel = view_as<Panel>(param2);
panel.SetTitle(buffer);
PrintToServer("Client %d was sent menu with panel %x", param1, param2);
}

case MenuAction_Select:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));
if (StrEqual(info, CHOICE3))
{
PrintToServer("Client %d somehow selected %s despite it being disabled", param1, info);
}
else
{
PrintToServer("Client %d selected %s", param1, info);
}
}

case MenuAction_Cancel:
{
PrintToServer("Client %d's menu was cancelled for reason %d", param1, param2);
}

case MenuAction_End:
{
delete menu;
}

case MenuAction_DrawItem:
{
int style;
char info[32];
menu.GetItem(param2, info, sizeof(info), style);

if (StrEqual(info, CHOICE3))
{
return ITEMDRAW_DISABLED;
}
else
{
return style;
}
}

case MenuAction_DisplayItem:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));

char display[64];

if (StrEqual(info, CHOICE3))
{
Format(display, sizeof(display), "%T", "Choice 3", param1);
return RedrawMenuItem(display);
}
}
}

return 0;
}

public Action Menu_Test1(int client, int args)
{
Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);
menu.SetTitle("%T", "Menu Title", LANG_SERVER);
menu.AddItem(CHOICE1, "Choice 1");
menu.AddItem(CHOICE2, "Choice 2");
menu.AddItem(CHOICE3, "Choice 3");
menu.ExitButton = false;
menu.Display(client, 20);

return Plugin_Handled;
}</pawn>

The translation file that goes with it... addons/sourcemod/translations/menu_test.phrases.txt

<pre>"Phrases"
{
"Choice 3"
{
"en" "Choice Translated"
}

"Menu Title"
{
"en" "Menu Title Translated"
}
}</pre>

== Step by Step ==

=== OnPluginStart ===

<pawn>public void OnPluginStart()
{
LoadTranslations("menu_test.phrases");
RegConsoleCmd("menu_test1", Menu_Test1);
}</pawn>

This block is here to register the command /menu_test1 so that this menu can be tested.

This block is beyond the scope of this page. See: [[Introduction to SourceMod Plugins#Plugin Structure|Plugin Structure]] for OnPluginStart, [[Translations (SourceMod Scripting)|Translations]] for LoadTranslations, and [[Commands_(SourceMod_Scripting)|Commands]] for RegConsoleCmd.

=== Menu_Test1 ===

Menu_Test1 is a ConCmd, which is beyond the scope of this page. See: [[Commands (SourceMod Scripting)|Commands]] for more details on that. We're going to be talking about what's in it.

==== Menu ====

<pawn> Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);</pawn>

Menu takes two arguments.

The first is a function that matches the [https://sm.alliedmods.net/new-api/menus/MenuHandler MenuHandler] callback signature.

The second is a bitmask of which MenuAction events we are going to handle in our MenuHandler. There are 7 that apply to standard menus:
* MenuAction_Start - Called once when a menu is displayed
* MenuAction_Display - Called once for each client a menu is displayed to
* MenuAction_Select - Called when a client makes a selection from the menu that isn't Previous, Next, Back, or Exit.
* MenuAction_Cancel - Called when a client closes a menu or it is closed on them
* MenuAction_End - Called once when all clients have closed the menu
* MenuAction_DrawItem - Called once for each item for each user a menu is displayed to. Can change the menu item style.
* MenuAction_DisplayIitem. - Called once for each item for each user a menu is displayed to. Can change the menu item text.

These will be discussed in more detail in the MenuHandler1 section.

Of those 7, 3 are called whether you specify them or not: MenuAction_Select, MenuAction_Cancel, and MenuAction_End.

MENU_ACTIONS_DEFAULT sets just the 3 required fields, while MENU_ACTIONS_ALL specifies all 10 actions (including the 3 vote actions).

To specify just a few of them, you can do this:

<pawn> Menu menu = new Menu(MenuHandler1, MenuAction_Start|MenuAction_Select|MenuAction_Cancel|MenuAction_End);</pawn>

==== menu.SetTitle ====
<pawn> menu.SetTitle("%T", "Menu Title", LANG_SERVER);</pawn>

Sets the menu's title. This example uses the translation system and the server's default language. This isn't strictly necessary as we will set the menu title again later.

==== menu.AddItem ====

<pawn> menu.AddItem(CHOICE1, "Choice 1");
menu.AddItem(CHOICE2, "Choice 2");
menu.AddItem(CHOICE3, "Choice 3");</pawn>

A menu isn't useful without something in it!
menu.AddItem has 2 required arguments and one optional argument.

The 2 required arguments are:

The Info string, and the Display string.

The Info String is a string that is used to uniquely identify this menu item. It is never displayed to the user, but is used in various callbacks.

The Display String is the default text to be used for this item on the menu. It can be changed via the menu's MenuAction_DisplayItem callback.

The optional argument is the menu's item draw style. It can be one of these values:
* ITEMDRAW_DEFAULT - Displays text as normal.
* ITEMDRAW_DISABLED - Item is displayed and has a number, but can't be selected.
* ITEMDRAW_RAWLINE - Item is displayed, but doesn't have a number assigned to it and thus can't be selected
* ITEMDRAW_NOTEXT - Draws an item with no text. Not very useful.
* ITEMDRAW_SPACER - Item is blank, but has a number. Can't be selected.
* ITEMDRAW_IGNORE - Item is blank with no number. Can't be selected.
* ITEMDRAW_CONTROL - Don't use this one. It's used for the items SourceMod automatically adds.

Be aware that if your CreateMenu second argument includes MenuAction_DrawItem or MENU_ACTIONS_ALL and you don't actually implement the MenuAction_DrawItem callback (or implement it and don't return the current item's style if you don't change it), your style here will be completely ignored.

==== menu.ExitButton ====
<pawn> menu.ExitButton = false;</pawn>

Defaults to true.

It set to false, the menu won't have an exit button.

==== menu.ExitBackButton ====
<pawn> menu.ExitBackButton = false;</pawn>

(This isn't in the code above, but it should be mentioned)

Defaults to false.

Should only be used if the menu is a submenu, with the menu set up to check the cancel reason to see if the ExitBack action was used.

If set to true, replaces the Exit item with the Back item. The Back item still cancels the menu, but has a separate cancel reason.

This can be used to dynamically set if a menu is being called as its own menu or as a submenu.

==== menu.Display ====
<pawn> menu.Display(client, 20);</pawn>

DisplayMenu takes 2 arguments:

A Menu handle, a client index, and the amount of time in seconds to show the menu.

If you want the menu to show forever, pass MENU_TIME_FOREVER as the third argument.

=== MenuHandler1 ===
<pawn>public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)</pawn>

MenuHandler1 is a function whose signature matches the MenuHandler callback. It can be named something other than MenuHandler1. It must always be public and it will always have these arguments: Handle, MenuAction, cell, and cell in that order.

The Handle argument is always the menu that called the handler.

The MenuAction argument is always one of 7 actions for a standard menu. They are: MenuAction_Start, MenuAction_Display, MenuAction_Select, MenuAction_Cancel, MenuAction_End, MenuAction_DrawItem, and MenuAction_DisplayIitem. We will discuss each of these as we reach their code.

The two cell arguments meaning depend on the MenuAction argument. '''A common mistake is to assume param1 is the client.''' This is incorrect for MenuAction_Start, MenuAction_End, MenuAction_VoteEnd, MenuAction_VoteStart, and MenuAction_VoteCancel.

==== MenuAction_Start ====

<pawn> case MenuAction_Start:
{
PrintToServer("Displaying menu");
}</pawn>

* param1: not set
* param2: not set
* return: 0 (or don't return)

MenuAction_Start doesn't set param1 and param2. It is fired when the menu is displayed to one or more users using DisplayMenu, DisplayMenuAtItem, VoteMenu, or VoteMenuToAll.

==== MenuAction_Display ====

<pawn> case MenuAction_Display:
{
char buffer[255];
Format(buffer, sizeof(buffer), "%T", "Vote Nextmap", param1);

Panel panel = view_as<Panel>(param2);
panel.SetTitle(buffer);
PrintToServer("Client %d was sent menu with panel %x", param1, param2);
}</pawn>

* param1: client index
* param2: MenuPanel Handle
* return: 0 (or don't return)

MenuAction_Display is called once for each user a menu is displayed to. param1 is the client, param2 is the MenuPanel handle.

SetPanelTitle is used to change the menu's title based on the language of the user viewing it using the Translations system.

==== MenuAction_Select ====
<pawn> case MenuAction_Select:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));
if (StrEqual(info, CHOICE3))
{
PrintToServer("Client %d somehow selected %s despite it being disabled", param1, info);
}
else
{
PrintToServer("Client %d selected %s", param1, info);
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: 0 (or don't return)

MenuAction_Select is called when a user selects a non-control item on the menu (something added using AddMenuItem). param1 is the client, param2 is the menu position of the item the client selected.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string.

==== MenuAction_Cancel ====

case MenuAction_Cancel:
{
PrintToServer("Client %d's menu was cancelled for reason %d", param1, param2);
}

* param1: client index
* param2: MenuCancel reason
* return: 0 (or don't return)

MenuAction_Cancel is called whenever a user closes a menu or it is closed for them for another reason. param1 is the client, param2 is the close reason.

The close reasons you can receive are:

* MenuCancel_Disconnected - The client got disconnected from the server.
* MenuCancel_Interrupted - Another menu opened, automatically closing our menu.
* MenuCancel_Exit - The client selected Exit. Not called if SetMenuExitBack was set to true. Not called if SetMenuExit was set to false.
* MenuCancel_NoDisplay - Our menu never displayed to the client for whatever reason.
* MenuCancel_Timeout - The menu timed out. Not called if the menu time was MENU_TIME_FOREVER.
* MenuCancel_ExitBack - The client selected Back. Only called if SetMenuExitBack has been called and set to true before the menu was sent. Not called if SetMenuExit was set to false.

==== MenuAction_End ====
<pawn> case MenuAction_End:
{
delete menu;
}</pawn>

* param1: MenuEnd reason
* param2: If param1 is MenuEnd_Cancelled, the MenuCancel reason
* return: 0 (or don't return)

MenuAction_End is called when ''all'' clients have closed a menu or vote. For menus that are not going to be redisplayed, it is required that you call CloseHandle on the menu here.

The parameters are rarely used in MenuAction_End. param1 is the menu end reason. param2 depends on param1.

The end reasons you can receive for normal menus are:

* MenuEnd_Selected - The menu closed because an item was selected (MenuAction_Select was fired)
* MenuEnd_Cancelled - The menu was cancelled (MenuAction_Cancel was fired), cancel reason is in param2; cancel reason can be any of the ones listed in MenuAction_Cancel except MenuCancel_Exit or MenuCancel_ExitBack
* MenuEnd_Exit - The menu was exited via the Exit item (MenuAction_Cancel was fired with param2 set to MenuCancel_Exit)
* MenuEnd_ExitBack - The menu was exited via the ExitBack item (MenuAction_Cancel was fired with param 2 set to MenuCancel_ExitBack)

Note: You do '''not''' have the client index during this callback, so it's far too late to do anything useful with this information.

==== MenuAction_DrawItem ====
<pawn> case MenuAction_DrawItem:
{
int style;
char info[32];
menu.GetItem(param2, info, sizeof(info), style);

if (StrEqual(info, CHOICE3))
{
return ITEMDRAW_DISABLED;
}
else
{
return style;
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: new ITEMDRAW properties or style from GetMenuItem. Since 0 is ITEMDRAW_DEFAULT, returning 0 clears all styles for this item.

MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its draw style here. param1 is the client, param2 is the menu position.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string and menu style.

You should return the style you want the menu item to have. In our example, if client 1 is viewing the menu, we want CHOICE3 to be disabled.

the return value is a bitfield, so to apply multiple styles, you do something like this:

return ITEMDRAW_NOTEXT | ITEMDRAW_SPACER;

'''Failing to return the current item's style if you don't change the style is a programmer error.'''

==== MenuAction_DisplayItem ====

<pawn> case MenuAction_DisplayItem:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));

char display[64];

if (StrEqual(info, CHOICE3))
{
Format(display, sizeof(display), "%T", "Choice 3", param1);
return RedrawMenuItem(display);
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: return value from RedrawMenuItem or 0 for no change

MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its text here. param1 is the client, param2 is the menu position.

This callback is intended for use with the Translation system.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string.

Once we have the info string, we compare our item to it and apply the appropriate translation string.

If we change an item, we have to call RedrawMenuItem and return the value it returns. If we do not change an item, we must return 0.

==== return ====
<pawn> return 0;</pawn>

If you handle MenuAction_DrawItem or MenuAction_DisplayItem, you will get the following warning if you fail to return 0 after the switch block:

<code>warning 209: function "MenuHandler1" should return a value</code>

This is because MenuAction_DrawItem and MenuAction_DisplayItem have return values, while the other actions only return 0.

== The End ==
Hopefully this walk through a simple menu helped you understand why each call is being made where. Menus have some options that we didn't explore here, such as disabling pagination (which is enabled by default). You may want to refer to the main Menu documentation for more details.

User talk:Asherkin

2016-11-30T16:45:32Z

Asherkin: Reverted edits by TheY4Kman (talk) to last revision by Asherkin

Introduction to SourcePawn 1.7

2016-06-27T21:22:18Z

Asherkin:

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

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

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

==Symbols/Keywords==
A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.

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

==Variables==
There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable "a" could hold the number "2", "16", "0", et cetera. Since a variable holds data, it also allocates the memory needed to store that data.

In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:
* Integers, using the <tt>int</tt> type. Integer types may store a whole number from -2147483648 to 2147483647.
* Floats, using the <tt>float</tt> type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.
* Characters, using the <tt>char</tt> type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.
* Booleans, using the <tt>bool</tt> type. Booleans store either true or false.

Example of creating variables and assigning values:

<pawn>int money = 5400;
float percent = 67.3;
bool enabled = false;
</pawn>

==Functions==
The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:

<pawn>
show(56); // Calls the "show" function, and gives it the number 56.
enable(); // Calls the "enable" function with no values.
bool visible = show(a); //Calls the "show" function, stores its result in a variable.
</pawn>

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

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

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

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

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

=Language Paradigms=
Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.
*'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the <tt>new</tt> keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].
*'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.
*'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.
*'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe.
*'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a ".smx" file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.

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

=Variables=
Pawn currently supports the following basic variable types:
*<tt>bool</tt> - true or false.
*<tt>char</tt> - an 8-bit ASCII character.
*<tt>int</tt> - a 32-bit signed integer.
*<tt>float</tt> - a 32-bit IEEE-754 floating point number.
*<tt>Handle</tt> - the base type of a SourceMod object

Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from <tt>Handle</tt>.

Strings, currently, are 0-terminated arrays of <tt>char</tt>s. They're described a little further ahead.

==Declaration==
Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.

<pawn>
int a = 5;
float b = 5.0;
bool c = true;
bool d = false;
</pawn>

Invalid variable usage:
<pawn>
int a = 5.0; // Type mismatch. 5.0 is a float.
float b = 5; // Type mismatch. 5 is an integer.
</pawn>

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

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

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

=Arrays=
An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.

==Declaration==
An array is declared using brackets. Some examples of arrays:
<pawn>
int players[32]; // Stores 32 integers.
float origin[3]; // Stores 3 floating point numbers
</pawn>

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

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

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

When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,

<pawn>
int[] numbers = new int[MaxClients]
</pawn>

This creates an array of size <tt>MaxClients</tt>, which could be anything, so the size of the array is not known until the array is allocated.

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

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

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

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

Using an incorrect index will cause an error. For example:
<pawn>
int numbers[5];

numbers[5] = 20;</pawn>

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

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

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

Expressions will be discussed in depth later in the article.

=Strings=
Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.

In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.

==Usage==
Strings are usually declared as arrays. For example:
<pawn>
char message[] = "Hello!";
char clams[6] = "Clams";
</pawn>

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

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

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

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

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

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

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

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

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

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

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

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

Example of a function:
<pawn>
int AddTwoNumbers(int first, int second)
{
int sum = first + second;
return sum;
}</pawn>

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

Broken down, it means:
*<tt>int</tt> - Return value type (integer).
*<tt>AddTwoNumbers</tt> - Name of the function.
*<tt>int first</tt> - First parameter, an integer.
*<tt>int second</tt> - Second parameter, an integer.

The body is a block of code. It creates a new variable, called <tt>sum</tt>, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the <tt>return</tt> statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called <tt>void</tt>.

A function can accept any type of input, and it can return any non-array type.

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

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

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

ChangeValue(a);

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

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

More examples of functions will be provided throughout the article.

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

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

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

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

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

The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.

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

<pawn>native float FloatRound(float num);</pawn>

It can be called like so:
<pawn>int rounded = FloatRound(5.2); // rounded will be 5</pawn>

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

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

ChangeArray(example, 2, 29);

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

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

Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.

To prevent an array from being modified in a function, you can mark it as <tt>const</tt>. This will raise an error on code that attempts to modify it. For example:

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

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

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

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

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

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

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

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

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

a = a + 5;</pawn>

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

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

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

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

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

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

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

For example:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return total;
}</pawn>

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

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

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

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

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

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

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

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

return total;
}</pawn>

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

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

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

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

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

return index;
}</pawn>

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

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

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

return sum;
}</pawn>

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

<pawn>
int A, B, C;

void Function1()
{
int B;

Function2();
}

void Function2()
{
int C;
}</pawn>

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

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

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

Function1();
}</pawn>

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

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

<pawn>void Function1()
{
int A;

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

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

if (A)
{
int B = 5;
}

B = 5;
}</pawn>

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

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

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

/* Code */
}</pawn>

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

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

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>int float or char</tt>.

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

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

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

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

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

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

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

counter += inc;

return counter;
}</pawn>

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

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

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

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

Note that statics can exist in any local scope:

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourceMod Plugins

2015-12-28T01:10:04Z

Asherkin: Removed /* Client and Entity Indexes */ section due to being mostly wrong.

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
{
public const char[] name; /**< Plugin Name */
public const char[] description; /**< Plugin Description */
public const char[] author; /**< Plugin Author */
public const char[] version; /**< Plugin Version */
public const char[] 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 void 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 void 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 int PrintToServer(const char[] 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 void 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 void 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 [https://sm.alliedmods.net/new-api/console/RegAdminCmd 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. [https://sm.alliedmods.net/new-api/console/ConCmd Click here] to see its prototype. Example:

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

public Action Command_MySlap(int client, int 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! This is because you're not returning Plugin_Handled in your callback. Since you haven't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so. The reason SourceMod expects your function to return Plugin_Handled is because of the Action tag you put in your function's prototype. The Action tag specifies that Command_MySlap must return one of four things. See the [https://sm.alliedmods.net/new-api/core/Action Action] enumeration in the sourcemod API to learn more about these return types and when to use them.

<pawn>public Action Command_MySlap(int client, int 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 [https://sm.alliedmods.net/new-api/console/GetCmdArg GetCmdArg()].
*Find a matching player. For this we use [https://sm.alliedmods.net/new-api/helpers/FindTarget FindTarget()].
*Slap them. For this we use [https://sm.alliedmods.net/new-api/sdktools_functions/SlapPlayer SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [https://sm.alliedmods.net/new-api/console/ReplyToCommand 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 void OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY);
}

public Action Command_MySlap(int client, int args)
{
char arg1[32], arg2[32];
int 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 */
int target = FindTarget(client, arg1);
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason.
*/
return Plugin_Handled;
}

SlapPlayer(target, damage);

char 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 [https://sm.alliedmods.net/new-api/sourcemod/AutoExecConfig 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>ConVar sm_myslap_damage = null;

public void 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(int client, int args)
{
char arg1[32], arg2[32];
int 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 [https://sm.alliedmods.net/new-api/logging/LogAction LogAction()] and [https://sm.alliedmods.net/new-api/console/ShowActivity2 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);

char 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 [https://sm.alliedmods.net/new-api/commandfilters/ProcessTargetString 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>

ConVar sm_myslap_damage = null;

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 void 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(int client, int args)
{
char arg1[32], arg2[32];
int 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
*/
char target_name[MAX_TARGET_LENGTH];
int target_list[MAXPLAYERS], target_count;
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 (int 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>

=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 void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath);
}

public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
int victim_id = event.GetInt("userid");
int attacker_id = event.GetInt("attacker");

int victim = GetClientOfUserId(victim_id);
int 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.

*[https://sm.alliedmods.net/new-api/sourcemod/AskPluginLoad2 AskPluginLoad2()] - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here.
*[https://sm.alliedmods.net/new-api/sourcemod/OnPluginStart 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()'''.
*[https://sm.alliedmods.net/new-api/sourcemod/OnAllPluginsLoaded OnAllPluginsLoaded()] - Called once, after all non-late loaded plugins have called OnPluginStart.
*[https://sm.alliedmods.net/new-api/sourcemod/OnMapStart 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().'''
*[https://sm.alliedmods.net/new-api/sourcemod/OnConfigsExecuted 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).
*[https://sm.alliedmods.net/new-api/sourcemod/OnMapEnd 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().'''
*[https://sm.alliedmods.net/new-api/sourcemod/OnPluginEnd 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.

*[https://sm.alliedmods.net/new-api/clients/OnClientConnect OnClientConnect()] - Called when a player initiates a connection. You can block a player from connecting by returning Plugin_Stop and setting rejectmsg to an error message.
*[https://sm.alliedmods.net/new-api/clients/OnClientConnected OnClientConnected()] - Called after a player connects. Signifies that the player is in-game and IsClientConnected() will return true. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[https://sm.alliedmods.net/new-api/clients/OnClientAuthorized 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 OnClientConnected and OnClientPreAdminCheck/OnClientDisconnect. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use OnClientPostAdminCheck().
*[https://sm.alliedmods.net/new-api/clients/OnClientPutInServer OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[https://sm.alliedmods.net/new-api/clients/OnClientPostAdminCheck OnClientPostAdminCheck()] - Called after the player is '''both authorized and in-game'''. This is the best callback for checking administrative access after connect.
*[https://sm.alliedmods.net/new-api/clients/OnClientDisconnect OnClientDisconnect()] - Called when a player's disconnection starts. '''This is paired to OnClientConnected().'''
*[https://sm.alliedmods.net/new-api/clients/OnClientDisconnect_Post OnClientDisconnect_Post()] - Called when a player's disconnection ends. '''This is paired to OnClientConnected().'''

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

If you only want to detect when a client initially connects or leaves your server, hook the [[Generic Source Server Events#player_connect|player_connect]] or [[Generic Source Server Events#player_disconnect|player_disconnect]] events respectively.

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Category:SourceMod Scripting

2015-08-13T18:52:56Z

Asherkin:

This category contains articles about scripting for SourceMod with SourcePawn.

===Introductions===
*[[Introduction to SourcePawn 1.7]] - 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===
*[https://sm.alliedmods.net/new-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]]

Required Versions (SourceMod

2014-11-01T12:24:35Z

Asherkin: Redirected page to Required Versions (SourceMod)

#REDIRECT [[Required Versions (SourceMod)]]

Required Versions (SourceMod

2014-11-01T12:24:15Z

Asherkin: Redirected page to Creating Required Versions (SourceMod)

#REDIRECT [[Creating Required Versions (SourceMod)]]

Template:Pr

2014-08-18T08:26:16Z

Asherkin: Removed trailing slash from links.

[https://github.com/alliedmodders/sourcemod/pull/{{{1}}} PR {{{1}}}]

Introduction to SourceMod Plugins

2014-06-15T13:26:59Z

Asherkin: Reverted edits by Castile (talk) to last revision by Powerlord

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.

=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=771& 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). Although SourceMod fires the OnClientConnected and OnClientDisconnected callbacks every map change, the server tracks players across map changes and does not change their userids or client indexes. To see if a client really connected or disconnected, hook the [[Generic Source Server Events#player_connect|player_connect]] and [[Generic Source Server Events#player_disconnect|player_disconnect]] events instead.

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=940& AskPluginLoad2()] - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here.
*[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=583& OnAllPluginsLoaded()] - Called once, after all non-late loaded plugins have called OnPluginStart.
*[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. You can block a player from connecting by returning Plugin_Stop and setting rejectmsg to an error message.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=916& OnClientConnected()] - Called after a player connects. Signifies that the player is in-game and IsClientConnected() will return true. '''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 OnClientConnected and OnClientPreAdminCheck/OnClientDisconnect. 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'''. 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 starts. '''This is paired to OnClientConnected().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=391& OnClientDisconnect_Post()] - Called when a player's disconnection ends. '''This is paired to OnClientConnected().'''

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

If you only want to detect when a client initially connects or leaves your server, hook the [[Generic Source Server Events#player_connect|player_connect]] or [[Generic Source Server Events#player_disconnect|player_disconnect]] events respectively.

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Scripting FAQ (SourceMod)

2014-06-15T13:25:43Z

Asherkin: Undo revision 8701 by Impact123 (talk)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Good:

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

Bad:

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

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

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

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

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

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

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

Example output from Left 4 Dead:

[[Image:Left_4_Dead_Colors.png]]

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

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

This data comes from Counter-Strike: Source.

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

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

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

<player_from team color> My message

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

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

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

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

<pawn>#include <colors>

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

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

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

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

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

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

<pawn>#include <smlib>

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

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

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

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

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

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

return Plugin_Handled;
}</pawn>

Installing Metamod:Source

2014-05-21T02:36:16Z

Asherkin: /* Custom VDF File */

This article will guide you through a [[Metamod:Source]] installation.

=Normal Installation=
<ol>
<li>[http://www.metamodsource.net/ Download] Metamod:Source.</li>
<li>Extract the package to your game folder. For example, for Counter-Strike:Source, you would have <tt>cstrike/addons/metamod</tt> after extracting. If you are uploading to FTP, extract the files locally before transferring to your server's game folder.</li>
<li>Restart your server.</li>
<li>Type "meta version" in your server console (or RCON). You should see a line like: "Loaded As: Valve Server Plugin." If the command is not recognized, see the sections below.</li>
</ol>

==Custom VDF File==
Metamod:Source 1.10.0 and later include a <tt>metamod.vdf</tt> file for easier installation on most games. If you have trouble getting it to load, [http://www.metamodsource.net/?go=vdf go here] to generate a VDF file specific to your game. This file should be placed into your server's <tt>addons</tt> directory.

Known setups that require this step:
<ol>
<li>Left 4 Dead 1</li>
<li>3rd party mods using the Source SDK Base.</li>
<li>Listen servers (created with the in-game "Create Server" option) for non-english game clients.</li>
</ol>

=GameInfo=
'''Note: This is normally not needed - if you do not understand what this, do NOT do this unless instructed to. The above instructions are sufficient to install Metamod:Source for 99% of servers.'''

Metamod:Source 1.4.2 and lower used an older method for loading itself. The advantage of this method was that Metamod:Source could be loaded before the actual game mod, which gave it a small amount of extra functionality. This functionality was never used by plugin developers, and Steam updates kept overwriting <tt>gameinfo.txt</tt> files, so we switched to a different loading mechanism.

However this loading mechanism may still be desirable if you run into backwards compatibility issues, or you have a plugin which takes advantage of the early-loading mechanism. If this is your case, here are the <tt>gameinfo.txt</tt> directions below:

<ul>
<li>Open the file in the mod folder called "gameinfo.txt". You will see a few lines at the bottom like this:
<pre>
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}
</pre></li>
<li>Add a line after the "{" sign but before all of the "Game" entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>If you're using Windows, you may need to use a backwards slash (\) instead.
<li>You're done! To test whether it worked, restart your game server and type "meta version" in the server console. You should see a line that says "Loaded as: GameDLL (gameinfo.txt)." If it doesn't recognize the command, the installation probably failed. If the "Loaded as:" line says something else, <tt>gameinfo.txt</tt> was probably not modified correctly.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

The <tt>gameinfo.txt</tt> loading method is supported as a legacy feature only. The patcher tool is no longer provided. You can mark <tt>gameinfo.txt</tt> if you absolutely want to protect it from being overwritten.

We will continue to make sure Metamod:Source can load via this method for as long as the Source Engine allows it. However, we will concentrate more on supporting the new loading mechanism for general use.

[[Category:Metamod:Source Documentation]]

Installing Metamod:Source

2013-08-30T17:53:38Z

Asherkin: /* Normal Installation */

This article will guide you through a [[Metamod:Source]] installation.

=Normal Installation=
<ol>
<li>[http://www.metamodsource.net/ Download] Metamod:Source.</li>
<li>Extract the package to your game folder. For example, for Counter-Strike:Source, you would have <tt>cstrike/addons/metamod</tt> after extracting. If you are uploading to FTP, extract the files locally before transferring to your server's game folder.</li>
<li>Restart your server.</li>
<li>Type "meta version" in your server console (or RCON). You should see a line like: "Loaded As: Valve Server Plugin." If the command is not recognized, see the sections below.</li>
</ol>

==Custom VDF File==
Metamod:Source 1.10.0 and later include a <tt>metamod.vdf</tt> file for easier installation on most games. If you have trouble getting it to load, [http://www.metamodsource.net/?go=vdf go here] to generate a VDF file specific to your game. This file should be placed into your server's <tt>addons</tt> directory.

Known setups that require this step:
<ol>
<li>3rd party mods using the Source SDK Base.</li>
<li>Listen servers (created with the in-game "Create Server" option) for non-english game clients.</li>
</ol>

=GameInfo=
'''Note: This is normally not needed - if you do not understand what this, do NOT do this unless instructed to. The above instructions are sufficient to install Metamod:Source for 99% of servers.'''

Metamod:Source 1.4.2 and lower used an older method for loading itself. The advantage of this method was that Metamod:Source could be loaded before the actual game mod, which gave it a small amount of extra functionality. This functionality was never used by plugin developers, and Steam updates kept overwriting <tt>gameinfo.txt</tt> files, so we switched to a different loading mechanism.

However this loading mechanism may still be desirable if you run into backwards compatibility issues, or you have a plugin which takes advantage of the early-loading mechanism. If this is your case, here are the <tt>gameinfo.txt</tt> directions below:

<ul>
<li>Open the file in the mod folder called "gameinfo.txt". You will see a few lines at the bottom like this:
<pre>
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}
</pre></li>
<li>Add a line after the "{" sign but before all of the "Game" entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>If you're using Windows, you may need to use a backwards slash (\) instead.
<li>You're done! To test whether it worked, restart your game server and type "meta version" in the server console. You should see a line that says "Loaded as: GameDLL (gameinfo.txt)." If it doesn't recognize the command, the installation probably failed. If the "Loaded as:" line says something else, <tt>gameinfo.txt</tt> was probably not modified correctly.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

The <tt>gameinfo.txt</tt> loading method is supported as a legacy feature only. The patcher tool is no longer provided. You can mark <tt>gameinfo.txt</tt> if you absolutely want to protect it from being overwritten.

We will continue to make sure Metamod:Source can load via this method for as long as the Source Engine allows it. However, we will concentrate more on supporting the new loading mechanism for general use.

[[Category:Metamod:Source Documentation]]

Installing Metamod:Source

2013-08-30T17:52:25Z

Asherkin: /* Custom VDF File */

This article will guide you through a [[Metamod:Source]] installation.

=Normal Installation=
<ol>
<li>[http://www.metamodsource.net/ Download] Metamod:Source.</li>
<li>Extract the package to your game folder. For example, for Counter-Strike:Source, you would have <tt>cstrike/addons/metamod</tt> after extracting. If you are uploading to FTP, extract the files locally before transferring to your server's game folder.</li>
<li>Restart your server.</li>
<li>Type "meta version" in your server console (or RCON). You should see a line like: "Loaded As: Valve Server Plugin." If the command is not recognized, see the [[Installing Metamod:Source#Troubleshooting|Troubleshooting]] section below.</li>
</ol>

==Custom VDF File==
Metamod:Source 1.10.0 and later include a <tt>metamod.vdf</tt> file for easier installation on most games. If you have trouble getting it to load, [http://www.metamodsource.net/?go=vdf go here] to generate a VDF file specific to your game. This file should be placed into your server's <tt>addons</tt> directory.

Known setups that require this step:
<ol>
<li>3rd party mods using the Source SDK Base.</li>
<li>Listen servers (created with the in-game "Create Server" option) for non-english game clients.</li>
</ol>

=GameInfo=
'''Note: This is normally not needed - if you do not understand what this, do NOT do this unless instructed to. The above instructions are sufficient to install Metamod:Source for 99% of servers.'''

Metamod:Source 1.4.2 and lower used an older method for loading itself. The advantage of this method was that Metamod:Source could be loaded before the actual game mod, which gave it a small amount of extra functionality. This functionality was never used by plugin developers, and Steam updates kept overwriting <tt>gameinfo.txt</tt> files, so we switched to a different loading mechanism.

However this loading mechanism may still be desirable if you run into backwards compatibility issues, or you have a plugin which takes advantage of the early-loading mechanism. If this is your case, here are the <tt>gameinfo.txt</tt> directions below:

<ul>
<li>Open the file in the mod folder called "gameinfo.txt". You will see a few lines at the bottom like this:
<pre>
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}
</pre></li>
<li>Add a line after the "{" sign but before all of the "Game" entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>If you're using Windows, you may need to use a backwards slash (\) instead.
<li>You're done! To test whether it worked, restart your game server and type "meta version" in the server console. You should see a line that says "Loaded as: GameDLL (gameinfo.txt)." If it doesn't recognize the command, the installation probably failed. If the "Loaded as:" line says something else, <tt>gameinfo.txt</tt> was probably not modified correctly.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

The <tt>gameinfo.txt</tt> loading method is supported as a legacy feature only. The patcher tool is no longer provided. You can mark <tt>gameinfo.txt</tt> if you absolutely want to protect it from being overwritten.

We will continue to make sure Metamod:Source can load via this method for as long as the Source Engine allows it. However, we will concentrate more on supporting the new loading mechanism for general use.

[[Category:Metamod:Source Documentation]]

SourceMod 1.5.0 Release Notes

2013-08-26T14:41:27Z

Asherkin:

__FORCETOC__
SourceMod 1.5.0 is a major update with many new features and bug fixes.

=Overview for Admins=

*'''New Game Support''' - SourceMod, including base plugins and the CStrike extension now fully support Counter-Strike: Global Offensive.
*Updated gamedata for many games and mods.
*The popular SDKHooks extension is now shipped with SourceMod.
*Lots of stability fixes.
*Better localization support.

=Overview for Developers=

A full list of API additions and changes is available.
*Many new functions added.
*Some existing functions made more useful.
*Large scale documentation cleanup and fixing of functionality to match documenation or vice versa in cases.

*Too much to name here. For overview of all sourcepawn and SM extension API changes and additions, please see [[SourceMod_1.5.0_API_Changes]]

=Compatibility Issues=

In almost all cases, SourceMod 1.5.0 is fully backward compatible with the 1.4.x releases. The following are the few places where this is not the case.

'''BfRead* and BfWrite natives not available on CS:GO''':

CS:GO has a completely new usermessage system for which there is no direct way to force compatibility through the existing bitbuf read/write natives. To read or write usermessage parameters in CS:GO, you need to use the new Pb natives.

There is also a new <tt>GetUserMessageType</tt> native to check which one of the two usermessage types that the running game uses.

For more information, see [[SourceMod_1.5.0_API_Changes#Protobuf]] and [[SourceMod_1.5.0_API_Changes#UserMessages]]

'''GuessSDKVersion deprecated, GetEngineVersion added'''

<tt>GuessSDKVersion</tt> will continue to function as-is for now, but will be removed in a later version. Additionally, a compile-time warning will be thrown. It has been superseded by the new <tt>GetEngineVersion</tt> native which will give clearer results and is more extendable for the future.

For more information, see [[SourceMod_1.5.0_API_Changes#HalfLife]]

'''TF2_GetResourceEntity, TF2_GetPlayerResourceData, and TF2_SetPlayerResourceData deprecated'''

These natives will continue to function as-is for now, but will generate a compile-time warning and be removed in a later version.

Calls to them should be replaced with calls to the new <tt>GetPlayerResourceEntity</tt> and the GetEntProp* and SetEntProp* natives.

For more information, see [[SourceMod_1.5.0_API_Changes#TF2]]

=Translations=
SourceMod 1.5 comes with the following languages translated, thanks to [http://www.sourcemod.net/translator/?go=translate&op=status community translators]:
*Arabic
*Brazilian Portuguese
*Bulgarian
*Chinese (Simplified)
*Chinese (Traditional)
*Czech
*Danish
*Dutch
*English
*Finnish
*French
*German
*Greek
*Hebrew
*Hungarian
*Italian
*Japanese
*Korean
*Latvian
*Lithuanian
*Norwegian
*Polish
*Portuguese
*Romanian
*Russian
*Slovak
*Spanish
*Swedish
*Thai
*Turkish

=Changelog=

===User Changes===

*Added support for Counter-Strike: Global Offensive ({{bz|5299}}, {{bz|5579}}).
*Split CS:S, TF2, DoD:S, HL2:DM, and ND to separate binaries ({{bz|5370}}, {{bz|5813}}).
*Added support for runoff voting in mapchooser ({{bz|4218}}).
*Added option to require Steam validation before granting admin access ({{bz|4837}}) ({{user|49537|VoiDeD}}).
*Added localization support for many more core and base plugin messages ({{bz|5120}}, {{bz|5146}}).
*Added the ability to override RegConsoleCommand-created commands ({{bz|5199}}).
*Added support for "fuzzy" (partial) map names in map-related natives and cmds for L4D and later ({{bz|5599}}).
*Updated Reserved Slots to use max humans as max count ({{bz|5444}}).
*Added support for custom maxitems on radio menus ({{bz|5371}}).
*Improved console config editing ({{bz|5470}}).
*Increased map name buffer sizes in mapchooser to better account for nested maps ({{bz|5609}}) ({{user|41418|Peace-Maker}}).
*Fixed JIT conflicts with SELinux ({{bz|5581}}).
*Added logged error when PlayerRunCommand offset lookup fails ({{bz|5535}}) ({{user|6136|GoD-Tony}}).
*Fixed double print when sending psay to self ({{bz|5649}}) ({{user|41418|Peace-Maker}}).
*Fixed check against uninitialized string in extension loader ({{bz|5546}}) ({{user|57030|KyleS}}).
*Fixed possible runtime errors in basetriggers for not-ingame clients ({{bz|5191}}) ({{user|41418|Peace-Maker}}).
*Check all possible mapcycle paths on newer orangebox games ({{bz|5719}}).
*Fixed ReadMapList not seeing maps in all valve search paths ({{bz|5715}}) ({{user|49537|VoiDeD}}).
*Fixed typo in too-many-params native error message ({{user|41418|Peace-Maker}}).
*Fixed various issues in clientprefs ({{bz|5538}}) ({{user|57030|KyleS}}).
*Removed debug printout from PerformGravity ({{bz|5679}}) ({{user|57030|KyleS}}).
*Fixed broken translating in some plugins and natives ({{bz|5612}}) ({{user|57030|KyleS}}).
*Fixed issues with COMMAND_FILTER_NO_BOTS and @bots multi-target.
*Fixed crash in SDKHooks when throwing bad ent type error on logical ent ({{user|57030|KyleS}}).

===Developer Changes===

*Added support for CS:GO to the CStrike extension ({{bz|5299}}) ({{user|26021|Drifter}}).
*Added support for new protobuf usermessages used in newer games ({{bz|5579}}, {{bz|5588}}, {{bz|5590}}, {{bz|5633}}).
*Added latest SDKHooks version as first-party extension.
*Updated SQLite to version 3.7.15.1 ({{bz|5235}}).
*Added natives for changing team score and mvp stars on CSS/CSGO ({{bz|5295}}) ({{user|26021|Drifter}}).
*Added global pre and post forwards for client chat ({{bz|5394}}) ({{user|57030|KyleS}}).
*Added TF2_CanPlayerTeleport forward to the TF2 game extension ({{bz|5283}}) ({{user|49537|VoiDeD}}).
*Added GetEntityAddress native ({{bz|5269}}) ({{user|71533|ProdigySim}}).
*Added more parameters to PlayerRunCommand forward ({{bz|5346}}) ({{user|6136|GoD-Tony}}).
*Added forwards to basecomm plugin ({{bz|5466}}) ({{user|26021|Drifter}}).
*Added symbol lookup support to gamedata on Windows ({{bz|5511}}) ({{user|6136|GoD-Tony}}).
*Exposed GetLanguageInfo in ITranslator interface ({{bz|5249}}) ({{user|49537|VoiDeD}}).
*Increase maximum .sp line length to 4095 characters. ({{bz|5347}}) ({{user|28227|theY4Kman}}).
*Improved netprop dump output ({{bz|5471}}).
*Added int64 typename to netprop dumps ({{bz|5655}}).
*Added GetMaxHumanPlayers native exposing IServerGameClients func ({{bz|5551}}).
*Added WeaponIDToAlias native to CStrike extension ({{bz|5460}}) ({{user|57030|KyleS}}).
*Fixed OnLibraryAdded/Removed not being called in all plugins ({{bz|5431}}).
*Made thread worker processing limits configurable at runtime ({{bz|5326}}).
*Added support in TF2 ext for detection of player conds >= 64 ({{bz|5565}}).
*Updated button defines in entity_prop_stocks ({{bz|5564}}).
*Added GetPlayerResourceEntity to SDKTools to replace old, semi-broken TF2-only version ({{bz|5491}}).
*Exposed third parameter of TF2's AddCond in TF2_AddCondition ({{bz|5641}}) ({{user|84304|FlaminSarge}}).
*Added GetSteamAccountID function to IPlayerHelpers and native for sp ({{bz|5548}}) ({{user|57030|KyleS}}).
*Added ISDKHooks interface with entity listeners ({{bz|5602}}) ({{user|6136|GoD-Tony}}).
*Added file upload support to webternet extension.
*Added more alternative names for TFClass_Heavy ({{bz|5338}}) ({{user|59521|Afronanny}}).
*Throw error instead of crash when calling SetTeamScore between maps ({{bz|5718}}) ({{user|57030|KyleS}}).
*Fixed clients not being marked as in kick queue in some cases ({{bz|5746}}) ({{user|193987|SystematicMania}}).
*Made compile.sh set working dir to own dir ({{bz|5710}}) ({{user|57030|KyleS}}).
*Added CS_IsValidWeaponID native and validity checks to other natives ({{bz|5566}}) ({{user|26021|Drifter}}).
*Numerous code documentation fixups ({{bz|5720}}) ({{user|34668|Tsunami}}).
*Fixed cmd listener callback return behavior to match func doc ({{bz|5882}}).

===Internal Changes===

*Fixed handle misuse in clientprefs plugin ({{bz|5805}}) ({{user|57030|KyleS}}).
*Removed call to getchar() in debug build of compiler ({{bz|5626}}) ({{user|57030|KyleS}}).
*Fixed instability issues with cloned handles ({{bz|5245}}, {{bz|5240}}) ({{user|57030|KyleS}}).
*Changed extension unload order to avoid exposing finalization window ({{bz|5556}}) ({{user|57030|KyleS}}).
*Fixed typo in TF2 ext asm.c causing accidental assignment instead of compare.
*Call OnPluginEnd before finalizer hooks have run ({{bz|4519}}).
*Fixed potential for reading out of library bounds in MemoryUtils::FindPattern.
*Overhauled versioning information ({{bz|5453}}).
*Changed from RemoveEdict to using the Kill input for TF2_RemoveWeapon.
*Fixed accidental assignment in each of SDKTools and sp compiler ({{bz|5745}}) ({{user|57030|KyleS}}).
*Fixed potential deadlock in HandleSystem::TryAndFreeSomeHandles ({{bz|5665}}) ({{user|57030|KyleS}}).

Installing SourceMod

2013-08-26T02:17:07Z

Asherkin: /* Prerequisites */

{{Languages|Installing_SourceMod}}

Installing SourceMod is very simple, and it can be added with almost no configuration changes.

=Prerequisites=
A GUI Web Browser to retrieve Metamod and SourceMod compressed archives.
A tool to copy archive to your dedicated server host.

SourceMod requires [[Metamod:Source]] 1.9.0 or higher (it is recommended that the latest version is used). [http://www.metamodsource.net/ Click here] to visit the Metamod:Source homepage. Instructions to install SourceMM manually can be found [[Installing Metamod:Source|here]].

SourceMod will run on almost any mod built using the Source SDK.

=Uploading/Installing=
==Local Server==
To install SourceMod locally, simply extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike, <tt>dod</tt> for Day of Defeat, et cetera).
[http://www.sourcemod.net/downloads.php Download Here]

==Remote Server==
To install SourceMod remotely, first extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your local computer (for example, your Desktop). You will see an <tt>addons</tt> folder.

Using a tool such as [http://www.google.com/search?q=FTP FTP], locate your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike:Source, <tt>dod</tt> for Day of Defeat:Source, et cetera). Underneath this folder, you should have an <tt>addons</tt> folder (if not, Metamod:Source is probably not installed). From your local <tt>addons</tt> folder, upload the entire contents to your remote <tt>addons</tt> folder. When done, your remote <tt>addons</tt> folder should have a <tt>sourcemod</tt> folder.

If you have trouble with these steps, you need to get acquainted with FTP and server management. However, you can also ask your server provider for help. Some providers also have web interfaces for managing your server.

Alternatively, if you copied the tar.gz to your srcds directory, execute the following from the cstrike sub directory:
tar -xzf ../sourcemod-1.1.0.tar.gz

=Checking the Install=
Your folder layout should look like:
*<tt>[mod]</tt> - Your mod's folder
**<tt>addons</tt>
***<tt>metamod</tt> - Metamod:Source
***<tt>sourcemod</tt> - SourceMod

Once SourceMod is uploaded/copied and configured with Metamod:Source, restart your server completely. If it is local, shut it down and restart it. If it is remote, you may need to ask your server provider for help. However, it is often safe to issue a "quit" command via [[rcon]], since most providers will automatically restart your server.

First, in your [[server console]] (not client console), type:
<pre>meta list</pre>

If the install worked, you will see something like:
<pre>] meta list
Listing 1 plugin:
[01] SourceMod (1.1.0.2489) by AlliedModders LLC</pre>

You should then be able to use the SourceMod root console command, which can be invoked with simply:
<pre>sm</pre>

For example:
<pre>] sm version
SourceMod Version Information:
SourceMod Version: 1.1.0.2489
SourcePawn Engine: SourcePawn 1.1, jit-x86 (build 1.1.0-svn)
SourcePawn API: v1 = 4, v2 = 2
Compiled on: Sep 5 2008 02:02:12
http://www.sourcemod.net/
</pre>

Lastly, assuming you have already setup your administration user, you can test the in game menu by joining the server, and in the client console type the following:
<pre>sm_admin</pre>
You should see a menu popup with all you options.

=Troubleshooting=
If the install failed, you will generally see one of four symptoms.

==Metamod reports NOFILE or FAILED==
If "meta list" replies with something like this:
<pre>] meta list
Listing 1 plugin:
[01] <NOFILE></pre>

Most likely, either the files are not located in the correct place, or the file could not be loaded. For more information, use the following command (except use the correct list number):
<pre>meta info 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
Listing 0 plugins:</pre>

There are several causes of this error.

# The most common cause is that sourcemod.vdf can't be located in the addons/metamod folder. Verify that sourcemod.vdf is present in this folder.
# If sourcemod.vdf is present, make sure you are using the correct build of Sourcemod (zip = windows, tar.gz = linux).

==Metamod says nothing==
If "meta list" has no reply at all, Metamod:Source is not properly installed. [[Installing Metamod:Source|This wiki page]] may provide you with clues on how to solve this problem.

[[Category:SourceMod Documentation]]

Category:Metamod:Source Documentation

2013-08-26T02:07:27Z

Asherkin:

*Installation and Setup
**[[Installing Metamod:Source]]
**[[Configuring Metamod:Source]]
*Usage
**[[Console Commands (Metamod:Source)|Console Commands]]
**[[:Category:Metamod:Source Development|Development]]
*Information
**[[Gameinfo Deprecation]]
**[[Metamod:Source VDF Files]]
**[[Supported Games (Metamod:Source)|Supported Games]]
**[[Frequently Asked Questions (Metamod:Source)|FAQ]]
**[[Open Source Plugins for Metamod:Source|Open Source Plugins]]
*Development
**[[:Category:Metamod:Source Development|Metamod:Source Development]]

Installing SourceMod

2013-08-26T02:05:01Z

Asherkin:

{{Languages|Installing_SourceMod}}

Installing SourceMod is very simple, and it can be added with almost no configuration changes.

=Prerequisites=
A GUI Web Browser to retrieve Metamod and SourceMod compressed archives.
A tool to copy archive to your dedicated server host.

SourceMod requires [[Metamod:Source]] 1.8.0 or higher (it is recommended that the latest version is used). [http://www.metamodsource.net/ Click here] to visit the Metamod:Source homepage. Instructions to install SourceMM manually can be found [[Installing Metamod:Source|here]].

SourceMod will run on almost any mod built using the Source SDK.

=Uploading/Installing=
==Local Server==
To install SourceMod locally, simply extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike, <tt>dod</tt> for Day of Defeat, et cetera).
[http://www.sourcemod.net/downloads.php Download Here]

==Remote Server==
To install SourceMod remotely, first extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your local computer (for example, your Desktop). You will see an <tt>addons</tt> folder.

Using a tool such as [http://www.google.com/search?q=FTP FTP], locate your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike:Source, <tt>dod</tt> for Day of Defeat:Source, et cetera). Underneath this folder, you should have an <tt>addons</tt> folder (if not, Metamod:Source is probably not installed). From your local <tt>addons</tt> folder, upload the entire contents to your remote <tt>addons</tt> folder. When done, your remote <tt>addons</tt> folder should have a <tt>sourcemod</tt> folder.

If you have trouble with these steps, you need to get acquainted with FTP and server management. However, you can also ask your server provider for help. Some providers also have web interfaces for managing your server.

Alternatively, if you copied the tar.gz to your srcds directory, execute the following from the cstrike sub directory:
tar -xzf ../sourcemod-1.1.0.tar.gz

=Checking the Install=
Your folder layout should look like:
*<tt>[mod]</tt> - Your mod's folder
**<tt>addons</tt>
***<tt>metamod</tt> - Metamod:Source
***<tt>sourcemod</tt> - SourceMod

Once SourceMod is uploaded/copied and configured with Metamod:Source, restart your server completely. If it is local, shut it down and restart it. If it is remote, you may need to ask your server provider for help. However, it is often safe to issue a "quit" command via [[rcon]], since most providers will automatically restart your server.

First, in your [[server console]] (not client console), type:
<pre>meta list</pre>

If the install worked, you will see something like:
<pre>] meta list
Listing 1 plugin:
[01] SourceMod (1.1.0.2489) by AlliedModders LLC</pre>

You should then be able to use the SourceMod root console command, which can be invoked with simply:
<pre>sm</pre>

For example:
<pre>] sm version
SourceMod Version Information:
SourceMod Version: 1.1.0.2489
SourcePawn Engine: SourcePawn 1.1, jit-x86 (build 1.1.0-svn)
SourcePawn API: v1 = 4, v2 = 2
Compiled on: Sep 5 2008 02:02:12
http://www.sourcemod.net/
</pre>

Lastly, assuming you have already setup your administration user, you can test the in game menu by joining the server, and in the client console type the following:
<pre>sm_admin</pre>
You should see a menu popup with all you options.

=Troubleshooting=
If the install failed, you will generally see one of four symptoms.

==Metamod reports NOFILE or FAILED==
If "meta list" replies with something like this:
<pre>] meta list
Listing 1 plugin:
[01] <NOFILE></pre>

Most likely, either the files are not located in the correct place, or the file could not be loaded. For more information, use the following command (except use the correct list number):
<pre>meta info 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
Listing 0 plugins:</pre>

There are several causes of this error.

# The most common cause is that sourcemod.vdf can't be located in the addons/metamod folder. Verify that sourcemod.vdf is present in this folder.
# If sourcemod.vdf is present, make sure you are using the correct build of Sourcemod (zip = windows, tar.gz = linux).

==Metamod says nothing==
If "meta list" has no reply at all, Metamod:Source is not properly installed. [[Installing Metamod:Source|This wiki page]] may provide you with clues on how to solve this problem.

[[Category:SourceMod Documentation]]

Installing SourceMod (simple)

2013-08-26T02:03:51Z

Asherkin:

{{outdated|directions=Please refer to the detailed guides for [[Installing Metamod:Source]] and [[Installing SourceMod]] respectively.}}

The below is a simplified install guide and does not provide full issue and install feedback in order to remain simple. In most cases this guide should be sufficient, however in case you experience unusual behaviour, a detailed install guide is available [[Installing_SourceMod|here]].

==Your Server==
SourceMod is a server addon. If you want to install SourceMod, it needs to be installed on the server. 
There are two kinds of servers: listen and dedicated.
[[File:Sourcededicatedserver.jpg|thumb|right|The Source dedicated server is located in the ''Tools'' category on Steam.]]
* A listen server is the server you host when using the in-game "create server" feature. '''NOTE:''' as of recent, SourceMod cannot run on a listen server by default. It is '''not''' recommended to use a listen server.
* A dedicated server is run using the ''Source Multiplayer Dedicated Server'', located in the ''Tools'' category on Steam.
Note: If you are installing SourceMod on a server not located near you, you should use the [[Installing_SourceMod|detailed install guide]].

==Finding the root folder==
SourceMod is installed on the server for a specific game. The game could be Counter Strike:Source, Team Fortress 2 or many other. 
Each game has its own folder on your server if installed. Each folder has a unique name with the game's initials. 
A list of initials is included below. 

{| class="wikitable" style="text-align:left"
! Game !! Initials
|-
| Counter Strike:Source || cstrike
|-
| Day of Defeat:Source || dod
|-
| Team Fortress 2 || tf
|} 

The root folder of your game is located in: 
Steam/steamapps/'''<accountname>'''/source 2007 dedicated server/'''<initials>'''/ 
''Note: Replace <accountname> with your Steam account name and <initials> with the proper initials listed above. 
'''Example:''' Steam/steamapps/'''gaben'''/source 2007 dedicated server/'''tf'''/ 
Now that you have found your game's root folder, we can begin installing.

==Installing Metamod:Source==
SourceMod runs using Metamod:Source. You will need to install Metamod in order for SourceMod to work.
* [http://www.metamodsource.net Download Metamod]. The download link is located on the left side of the webpage. Make sure to pick the proper operation system (Windows on a Windows server, Linux on a Linux server, and so on).
* Put the content of the zip into your game's root folder. You should now have an "addons" folder in your game's root folder.
* In order for the game to recognise Metamod, you need a vdf file. [http://www.metamodsource.net/?go=vdf Click here] and select the game you wish to install Metamod for, then click the generate button.
* Once the metamod.vdf file has downloaded, copy it into your "addons" folder.

You have now successfully installed Metamod!

==Installing SourceMod==
Once you have installed Metamod:Source, there will be an "addons" folder in your server's game root. 
* [http://www.sourcemod.net/downloads.php Download SourceMod] (make sure to pick the proper operation system).
* Place the content of the zip into your server's game root.

You have now successfully installed SourceMod!

==Confirmation==
Before we end the guide, let's make sure everything is working.
* Start your server (or restart it if it was already running).
* Type 'meta version' into the server's console. If it does not recognise the command, then you have made a mistake in installing Metamod and we recommend that you follow the [[Installing_Metamod:Source|detailed guide]].
* Type 'sm version' into the server's console. If it does not recognise the command, then you have made a mistake in installing Sourcemod and we recommend that you follow the [[Installing_SourceMod|detailed guide]].

If everything was successful then you're done!

Installing SourceMod

2013-08-26T02:02:04Z

Asherkin:

{{Languages|Installing_SourceMod}}

Installing SourceMod is very simple, and it can be added with almost no configuration changes.

=Prerequisites=
A GUI Web Browser to retrieve Metamod and SourceMod compressed archives.
A tool to copy archive to your dedicated server host.

SourceMod requires [[Metamod:Source]] 1.8.0 or higher (it is recommended that the latest version is used). [http://www.metamodsource.net/ Click here] to visit the Metamod:Source homepage. Instructions to install SourceMM manually can be found [[Installing Metamod:Source|here]].

SourceMod will run on almost any mod built using the Source SDK.

=Uploading/Installing=
==Local Server==
To install SourceMod locally, simply extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike, <tt>dod</tt> for Day of Defeat, et cetera).
[http://www.sourcemod.net/downloads.php Download Here]

==Remote Server==
To install SourceMod remotely, first extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your local computer (for example, your Desktop). You will see an <tt>addons</tt> folder.

Using a tool such as [http://www.google.com/search?q=FTP FTP], locate your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike:Source, <tt>dod</tt> for Day of Defeat:Source, et cetera). Underneath this folder, you should have an <tt>addons</tt> folder (if not, Metamod:Source is probably not installed). From your local <tt>addons</tt> folder, upload the entire contents to your remote <tt>addons</tt> folder. When done, your remote <tt>addons</tt> folder should have a <tt>sourcemod</tt> folder.

If you have trouble with these steps, you need to get acquainted with FTP and server management. However, you can also ask your server provider for help. Some providers also have web interfaces for managing your server.

Alternatively, if you copied the tar.gz to your srcds directory, execute the following from the cstrike sub directory:
tar -xzf ../sourcemod-1.1.0.tar.gz

=Checking the Install=
Your folder layout should look like:
*<tt>[mod]</tt> - Your mod's folder
**<tt>addons</tt>
***<tt>metamod</tt> - Metamod:Source
***<tt>sourcemod</tt> - SourceMod

Once SourceMod is uploaded/copied and configured with Metamod:Source, restart your server completely. If it is local, shut it down and restart it. If it is remote, you may need to ask your server provider for help. However, it is often safe to issue a "quit" command via [[rcon]], since most providers will automatically restart your server.

First, in your [[server console]] (not client console), type:
<pre>meta list</pre>

If the install worked, you will see something like:
<pre>] meta list
Listing 1 plugin:
[01] SourceMod (1.1.0.2489) by AlliedModders LLC</pre>

You should then be able to use the SourceMod root console command, which can be invoked with simply:
<pre>sm</pre>

For example:
<pre>] sm version
SourceMod Version Information:
SourceMod Version: 1.1.0.2489
SourcePawn Engine: SourcePawn 1.1, jit-x86 (build 1.1.0-svn)
SourcePawn API: v1 = 4, v2 = 2
Compiled on: Sep 5 2008 02:02:12
http://www.sourcemod.net/
</pre>

Lastly, assuming you have already setup your administration user, you can test the in game menu by joining the server, and in the client console type the following:
<pre>sm_admin</pre>
You should see a menu popup with all you options.

=Troubleshooting=
If the install failed, you will generally see one of four symptoms.

==Metamod reports NOFILE or FAILED==
If "meta list" replies with something like this:
<pre>] meta list
Listing 1 plugin:
[01] <NOFILE></pre>

Most likely, either the files are not located in the correct place, or the file could not be loaded. For more information, use the following command (except use the correct list number):
<pre>meta info 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
Listing 0 plugins:</pre>

There are several causes of this error.

# The most common cause is that sourcemod.vdf can't be located in the addons/metamod folder. Verify that sourcemod.vdf is present in this folder.
# If sourcemod.vdf is present, make sure you are using the correct build of Sourcemod (zip = windows, tar.gz = linux).

==Metamod says nothing==
If "meta list" has no reply at all, Metamod:Source is not properly installed. [http://wiki.alliedmods.net/index.php/Installing_SourceMM This wiki page] may provide you with clues on how to solve this problem.

[[Category:SourceMod Documentation]]

Template:Outdated

2013-08-26T02:01:03Z

Asherkin:

<center>{{nmbox
| image = [[Image:Gnome globe current event.png|42px]]
| text = '''This article's factual accuracy may be compromised due to out-of-date information.''' It is strongly suggested that you do not follow any instructions that may appear on this page.{{#if:{{{directions|}}}| '''{{{directions|}}}'''|}}
}}<includeonly>[[Category:Outdated]]</includeonly></center>

Template:Outdated

2013-08-26T02:00:38Z

Asherkin:

<center>{{nmbox
| image = [[Image:Gnome globe current event.png|42px]]
| text = '''This article's factual accuracy may be compromised due to out-of-date information''' It is strongly suggested that you do not follow any instructions that may appear on this page.{{#if:{{{directions|}}}| '''{{{directions|}}}'''|}}
}}<includeonly>[[Category:Outdated]]</includeonly></center>

Template:Outdated

2013-08-26T01:59:53Z

Asherkin:

<center>{{nmbox
| image = [[Image:Gnome globe current event.png|42px]]
| text = '''This article's factual accuracy may be compromised due to out-of-date information''' It is strongly suggested that you do not follow any instructions that may appear on this page.{{#if:{{{directions|}}}| {{{directions|}}}|}}
}}<includeonly>[[Category:Outdated]]</includeonly></center>

Installing SourceMod

2013-08-26T01:57:28Z

Asherkin:

{{Languages|Installing_SourceMod}}

Installing SourceMod is very simple, and it can be added with almost no configuration changes.

=Prerequisites=
A GUI Web Browser to retrieve Metamod and SourceMod compressed archives.
A tool to copy archive to your dedicated server host.

SourceMod requires [[Metamod:Source]] 1.8.0 or higher (it is recommended that the latest version is used). [http://www.metamodsource.net/ Click here] to visit the Metamod:Source homepage. Instructions to install SourceMM manually can be found [http://wiki.alliedmods.net/index.php/Installing_Metamod:Source here].

SourceMod will run on almost any mod built using the Source SDK.

=Uploading/Installing=
==Local Server==
To install SourceMod locally, simply extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike, <tt>dod</tt> for Day of Defeat, et cetera).
[http://www.sourcemod.net/downloads.php Download Here]

==Remote Server==
To install SourceMod remotely, first extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your local computer (for example, your Desktop). You will see an <tt>addons</tt> folder.

Using a tool such as [http://www.google.com/search?q=FTP FTP], locate your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike:Source, <tt>dod</tt> for Day of Defeat:Source, et cetera). Underneath this folder, you should have an <tt>addons</tt> folder (if not, Metamod:Source is probably not installed). From your local <tt>addons</tt> folder, upload the entire contents to your remote <tt>addons</tt> folder. When done, your remote <tt>addons</tt> folder should have a <tt>sourcemod</tt> folder.

If you have trouble with these steps, you need to get acquainted with FTP and server management. However, you can also ask your server provider for help. Some providers also have web interfaces for managing your server.

Alternatively, if you copied the tar.gz to your srcds directory, execute the following from the cstrike sub directory:
tar -xzf ../sourcemod-1.1.0.tar.gz

=Checking the Install=
Your folder layout should look like:
*<tt>[mod]</tt> - Your mod's folder
**<tt>addons</tt>
***<tt>metamod</tt> - Metamod:Source
***<tt>sourcemod</tt> - SourceMod

Once SourceMod is uploaded/copied and configured with Metamod:Source, restart your server completely. If it is local, shut it down and restart it. If it is remote, you may need to ask your server provider for help. However, it is often safe to issue a "quit" command via [[rcon]], since most providers will automatically restart your server.

First, in your [[server console]] (not client console), type:
<pre>meta list</pre>

If the install worked, you will see something like:
<pre>] meta list
Listing 1 plugin:
[01] SourceMod (1.1.0.2489) by AlliedModders LLC</pre>

You should then be able to use the SourceMod root console command, which can be invoked with simply:
<pre>sm</pre>

For example:
<pre>] sm version
SourceMod Version Information:
SourceMod Version: 1.1.0.2489
SourcePawn Engine: SourcePawn 1.1, jit-x86 (build 1.1.0-svn)
SourcePawn API: v1 = 4, v2 = 2
Compiled on: Sep 5 2008 02:02:12
http://www.sourcemod.net/
</pre>

Lastly, assuming you have already setup your administration user, you can test the in game menu by joining the server, and in the client console type the following:
<pre>sm_admin</pre>
You should see a menu popup with all you options.

=Troubleshooting=
If the install failed, you will generally see one of four symptoms.

==Metamod reports NOFILE or FAILED==
If "meta list" replies with something like this:
<pre>] meta list
Listing 1 plugin:
[01] <NOFILE></pre>

Most likely, either the files are not located in the correct place, or the file could not be loaded. For more information, use the following command (except use the correct list number):
<pre>meta info 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
Listing 0 plugins:</pre>

There are several causes of this error.

# The most common cause is that sourcemod.vdf can't be located in the addons/metamod folder. Verify that sourcemod.vdf is present in this folder.
# If sourcemod.vdf is present, make sure you are using the correct build of Sourcemod (zip = windows, tar.gz = linux).

==Metamod says nothing==
If "meta list" has no reply at all, Metamod:Source is not properly installed. [http://wiki.alliedmods.net/index.php/Installing_SourceMM This wiki page] may provide you with clues on how to solve this problem.

[[Category:SourceMod Documentation]]

Installing SourceMod/ko

2013-08-26T01:55:44Z

Asherkin:

{{outdated|directions=Please refer to the english language version.}}

{{Languages|Installing_SourceMod}}

소스모드를 설치하는 것은 아주 간단합니다. 그리고 설정을 바꿀 필요도 거의 없습니다.
 '''아래는 자세한 설치 안내이고, 중요한 정보와 설치 피드팩을 제공합니다. 그러나, 이 페이지의 설명을 이해하는 데 어려움을 겪고있다면, 간단한 설치 안내서가 [[Installing_SourceMod_(simple)|여기]]에 있습니다.'''

=필요한 것들=
메타모드와 소스모드의 파일을 받기 위해서 GUI 웹브라우저가 필요합니다
당신의 데디케이트 서버 호스트에 파일들을 복사할 도구가 필요합니다

소스모드는 [[Metamod:Source|메타모드:소스]] 1.8.0 이나 더 높은 버전이 필요합니다
메타모드:소스의 홈페이지에 방문하려면 [http://www.metamodsource.net/ 이곳]을 클릭하세요
메타모드:소스를 설치를 위한 설명은 [[Installing_Metamod:Source|여기]]에 있습니다.

소스모드는 Source SDK를 사용해서 만들어진 어떤 모드에서도 작동합니다. 또한, Source Engine을 사용해 만들어진 "더 쉽(The Ship)"도 지원합니다.

=업그레이드/설치=
==로컬 서버==
소스모드를 로컬 서버에 설치하려면, 단순히 <tt>.zip</tt>(윈도우즈) 또는 <tt>.tar.gz</tt>(리눅스) 패키지를 당신의 모드 폴더 (예를 들어 카운터스트라이크:소스라면 <tt>cstrike</tt>, 데이 오브 디피트:소스 라면 <tt>dod</tt> 등...)에 압축 해제하세요. [http://www.sourcemod.net/downloads.php 여기]에서 다운로드하세요. <tt>addons</tt> 폴더가 보일 것입니다.

[http://www.google.com/search?q=FTP FTP] 같은 도구를 써서, 당신의 모드 폴더(예를 들어 카운터스트라이크:소스라면 <tt>cstrike</tt>, 데이 오브 디피트:소스 라면 <tt>dod</tt> 등...)를 찾으세요. 그리고 그 폴더 아래에, <tt>addons</tt> 폴더가 있어야 합니다.(없다면, 메타모드:소스가 설치되지 않은 것입니다.) 당신의 로컬 <tt>addons</tt> 폴더에서 목표로 하는 원격 <tt>addons</tt> 폴더로 모든 내용물을 업로드하세요. 다 끝나면, 원격 <tt>addons</tt> 폴더는 <tt>sourcemod</tt> 폴더를 가지고 있을 것입니다.

이러한 단계를 수행하는 데 어려움을 겪는다면, FTP나 서버 관리에 보다 익숙해져야 합니다. 그러나 당신의 서버 제공자에게 도움을 요청할 수 있을 것입니다. 몇몇 서버 제공자들은 당신의 서버를 관리하기 위한 웹 인터페이스를 제공해 줄 것입니다.

만약 당신이 tar.gz 파일을 srcds 디렉토리에 복사했다면, 하위의 cstrike 디렉토리에서 다음을 실행하세요 :
tar -xzf ../sourcemod-1.1.0.tar.gz

=설치 확인=
이제 폴더 구조가 다음과 같을 것입니다:
*<tt>[모드]</tt> - 모드의 폴더
**<tt>addons</tt>
***<tt>metamod</tt> - 메타모드:소스
***<tt>sourcemod</tt> - 소스모드

일단 소스모드가 업로드/복사 되고, 메타모드:소스와 설정이 끝나면, 당신의 서버를 완전히 재시작하세요. 로컬 서버라면, 종료한 뒤 재시작하고, 원격 서버라면 서버 제공자에게 문의해야 합니다. 경우에 따라 [[rcon]] 명령으로 "quit" 명령을 실행하는 것도 안전한데, 대개의 서버 제공자들이 당신의 서버를 다시 실행시켜 줄 것이기 때문입니다.

먼저, [[server console|서버 콘솔]](클라이언트 콘솔이 아님) 에 다음을 입력하세요:
<pre>meta list</pre>

설치가 제대로 됬다면, 다음과 같은 것을 볼 것입니다:
<pre>] meta list
Listing 1 plugin:
[01] SourceMod (1.1.0.2489) by AlliedModders LLC</pre>

이제 소스모드의 주 콘솔 명령을 사용할 수 있습니다. 단순히 아래와 같이 실행합니다:
<pre>sm</pre>

예제:
<pre>] sm version
SourceMod Version Information:
SourceMod Version: 1.1.0.2489
SourcePawn Engine: SourcePawn 1.1, jit-x86 (build 1.1.0-svn)
SourcePawn API: v1 = 4, v2 = 2
Compiled on: Sep 5 2008 02:02:12
http://www.sourcemod.net/
</pre>

마지막으로, 당신이 이미 관리자 설정을 끝마쳤다고 가정한다면, 이제 서버에 접속해서 클라이언트 콘솔에 다음을 입력해서 인게임 메뉴를 시험해 볼 수 있습니다:
<pre>sm_admin</pre>
이것으로 옵션이 있는 메뉴를 볼 수 있어야 합니다.

=문제 해결=
설치에 실패했다면, 일반적으로 네가지 증상을 살펴보아야 합니다.

==메타모드가 NOFILE 혹은 FAILED 를 보고한다==
"meta list" 를 입력했을 때 다음과 같은 응답을 한다면:
<pre>] meta list
-Id- Name Version Author Status
[01] - - - NOFILE </pre>

대개의 경우 파일들이 올바른 위치에 없거나, 파일이 로드될 수 없는 것입니다. 자세한 정보를 위해서는 다음의 명령어를 사용하세요 (단, 올바를 줄번호를 사용해야 합니다):
<pre>meta list 1</pre>

==메타모드가 아무 플러그인도 보여주지 않는다==
만약 "meta list" 다음과 같은 응답을 한다면:
<pre>] meta list
-Id- Name Version Author Status </pre>

소스모드를 <tt>addons/metamod/metaplugins.ini</tt> 파일에 더하는 것을 잊었거나, 혹은 그것이 당신의 문제를 해결해주지 못한다면, 올바른 소스모드의 빌드를 사용하는지 확인하십시오(zip = 윈도우즈, tar = 리눅스)

==메타모드가 아무 응답도 하지 않는다==
만약 "meta list" 가 전혀 응답하지 않는다면, 메타모드:소스가 설치되지 않은 것입니다.
[[Installing_SourceMM|이 위키 페이지]] 가 아마도 이 문제를 해결할 단서를 제공해 줄 것입니다.

[[Category:SourceMod Documentation]]

Installing Metamod:Source

2013-08-26T01:54:22Z

Asherkin:

This article will guide you through a [[Metamod:Source]] installation.

=Normal Installation=
<ol>
<li>[http://www.metamodsource.net/ Download] Metamod:Source.</li>
<li>Extract the package to your game folder. For example, for Counter-Strike:Source, you would have <tt>cstrike/addons/metamod</tt> after extracting. If you are uploading to FTP, extract the files locally before transferring to your server's game folder.</li>
<li>Restart your server.</li>
<li>Type "meta version" in your server console (or RCON). You should see a line like: "Loaded As: Valve Server Plugin." If the command is not recognized, see the [[Installing Metamod:Source#Troubleshooting|Troubleshooting]] section below.</li>
</ol>

==Custom VDF File==
Metamod:Source 1.10.0 and later include a <tt>metamod.vdf</tt> file for easier installation on most games. If you have trouble getting it to load, [http://www.metamodsource.net/?go=vdf go here] to generate a VDF file specific to your game. This file should be placed into your server's <tt>addons</tt> directory.

Known setups that require this step:
<ol>
<li>Games on the Episode 1 or older engines.</li>
<li>Listen servers (created with the in-game "Create Server" option) for non-english game clients.</li>
</ol>

=GameInfo=
'''Note: This is normally not needed - if you do not understand what this, do NOT do this unless instructed to. The above instructions are sufficient to install Metamod:Source for 99% of servers.'''

Metamod:Source 1.4.2 and lower used an older method for loading itself. The advantage of this method was that Metamod:Source could be loaded before the actual game mod, which gave it a small amount of extra functionality. This functionality was never used by plugin developers, and Steam updates kept overwriting <tt>gameinfo.txt</tt> files, so we switched to a different loading mechanism.

However this loading mechanism may still be desirable if you run into backwards compatibility issues, or you have a plugin which takes advantage of the early-loading mechanism. If this is your case, here are the <tt>gameinfo.txt</tt> directions below:

<ul>
<li>Open the file in the mod folder called "gameinfo.txt". You will see a few lines at the bottom like this:
<pre>
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}
</pre></li>
<li>Add a line after the "{" sign but before all of the "Game" entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>If you're using Windows, you may need to use a backwards slash (\) instead.
<li>You're done! To test whether it worked, restart your game server and type "meta version" in the server console. You should see a line that says "Loaded as: GameDLL (gameinfo.txt)." If it doesn't recognize the command, the installation probably failed. If the "Loaded as:" line says something else, <tt>gameinfo.txt</tt> was probably not modified correctly.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

The <tt>gameinfo.txt</tt> loading method is supported as a legacy feature only. The patcher tool is no longer provided. You can mark <tt>gameinfo.txt</tt> if you absolutely want to protect it from being overwritten.

We will continue to make sure Metamod:Source can load via this method for as long as the Source Engine allows it. However, we will concentrate more on supporting the new loading mechanism for general use.

[[Category:Metamod:Source Documentation]]

Category:Outdated

2013-08-26T01:53:24Z

Asherkin: Created page with "Pages in this category have been marked as containing outdated information, they should be updated, or references to them should be removed if the information is no longer rel..."

Pages in this category have been marked as containing outdated information, they should be updated, or references to them should be removed if the information is no longer relevant in any way.

Installing SourceMod (simple)

2013-08-26T01:52:18Z

Asherkin:

{{outdated}}

The below is a simplified install guide and does not provide full issue and install feedback in order to remain simple. In most cases this guide should be sufficient, however in case you experience unusual behaviour, a detailed install guide is available [[Installing_SourceMod|here]].

==Your Server==
SourceMod is a server addon. If you want to install SourceMod, it needs to be installed on the server. 
There are two kinds of servers: listen and dedicated.
[[File:Sourcededicatedserver.jpg|thumb|right|The Source dedicated server is located in the ''Tools'' category on Steam.]]
* A listen server is the server you host when using the in-game "create server" feature. '''NOTE:''' as of recent, SourceMod cannot run on a listen server by default. It is '''not''' recommended to use a listen server.
* A dedicated server is run using the ''Source Multiplayer Dedicated Server'', located in the ''Tools'' category on Steam.
Note: If you are installing SourceMod on a server not located near you, you should use the [[Installing_SourceMod|detailed install guide]].

==Finding the root folder==
SourceMod is installed on the server for a specific game. The game could be Counter Strike:Source, Team Fortress 2 or many other. 
Each game has its own folder on your server if installed. Each folder has a unique name with the game's initials. 
A list of initials is included below. 

{| class="wikitable" style="text-align:left"
! Game !! Initials
|-
| Counter Strike:Source || cstrike
|-
| Day of Defeat:Source || dod
|-
| Team Fortress 2 || tf
|} 

The root folder of your game is located in: 
Steam/steamapps/'''<accountname>'''/source 2007 dedicated server/'''<initials>'''/ 
''Note: Replace <accountname> with your Steam account name and <initials> with the proper initials listed above. 
'''Example:''' Steam/steamapps/'''gaben'''/source 2007 dedicated server/'''tf'''/ 
Now that you have found your game's root folder, we can begin installing.

==Installing Metamod:Source==
SourceMod runs using Metamod:Source. You will need to install Metamod in order for SourceMod to work.
* [http://www.metamodsource.net Download Metamod]. The download link is located on the left side of the webpage. Make sure to pick the proper operation system (Windows on a Windows server, Linux on a Linux server, and so on).
* Put the content of the zip into your game's root folder. You should now have an "addons" folder in your game's root folder.
* In order for the game to recognise Metamod, you need a vdf file. [http://www.metamodsource.net/?go=vdf Click here] and select the game you wish to install Metamod for, then click the generate button.
* Once the metamod.vdf file has downloaded, copy it into your "addons" folder.

You have now successfully installed Metamod!

==Installing SourceMod==
Once you have installed Metamod:Source, there will be an "addons" folder in your server's game root. 
* [http://www.sourcemod.net/downloads.php Download SourceMod] (make sure to pick the proper operation system).
* Place the content of the zip into your server's game root.

You have now successfully installed SourceMod!

==Confirmation==
Before we end the guide, let's make sure everything is working.
* Start your server (or restart it if it was already running).
* Type 'meta version' into the server's console. If it does not recognise the command, then you have made a mistake in installing Metamod and we recommend that you follow the [[Installing_Metamod:Source|detailed guide]].
* Type 'sm version' into the server's console. If it does not recognise the command, then you have made a mistake in installing Sourcemod and we recommend that you follow the [[Installing_SourceMod|detailed guide]].

If everything was successful then you're done!

Template:Outdated

2013-08-26T01:51:53Z

Asherkin:

<center>{{nmbox
| image = [[Image:Gnome globe current event.png|42px]]
| text = '''This article's factual accuracy may be compromised due to out-of-date information''' It is strongly suggested that you do not follow any instructions that may appear on this page.
}}<includeonly>[[Category:Outdated]]</includeonly></center>

Template:Outdated

2013-08-26T01:48:26Z

Asherkin:

Template:Nmbox

2013-08-26T01:47:41Z

Asherkin:

<table class="nmbox" style="border:1px solid #AAAAAA; border-collapse:collapse; clear:both; font-size:85%; margin: 0.25em 0;">
<tr style="background: #EEF3E2">
{{#if:{{{image|}}}{{{header|}}}
| <th class="mbox-image" style="white-space: nowrap; padding: 4px 1em; border-right: 1px solid #aaaaaa;">{{{image|}}} {{{header|}}}</th>
| <td class="mbox-empty-cell"></td> 
}}
<td class="mbox-text" style="background: #F6F9ED; padding: 4px 1em">{{{text|}}}</td>
</tr></table>

Template:Outdated

2013-08-26T01:46:32Z

Asherkin: Created page with "{{nmbox | image = 42px | text = '''This article's factual accuracy may be compromised due to out-of-date information''' It is str..."

{{nmbox
| image = [[Image:Gnome globe current event.png|42px]]
| text = '''This article's factual accuracy may be compromised due to out-of-date information''' It is strongly suggested that you do not follow any instructions that may appear on this page.
}}

File:Gnome globe current event.png

2013-08-26T01:42:52Z

Asherkin:

Installing Metamod:Source

2013-08-26T01:27:55Z

Asherkin: Updated install instructions for 1.10.0

This article will guide you through a [[Metamod:Source]] installation. Use this guide if you wish to install Metamod:Source manually, or for some reason you cannot (or will not) use the automated installer.
 '''The below is a detailed install guide and provides excellent issue and install feedback. However, if you're having troubles understanding the page and its instructions, [[Installing_SourceMod_(simple)|a simplified install guide is available here]].'''

=Normal Installation=
<ol>
<li>[http://www.metamodsource.net/ Download] Metamod:Source.</li>
<li>Extract the package to your game folder. For example, for Counter-Strike:Source, you would have <tt>cstrike/addons/metamod</tt> after extracting. If you are uploading to FTP, extract the files locally before transferring to your server's game folder.</li>
<li>Restart your server.</li>
<li>Type "meta version" in your server console (or RCON). You should see a line like: "Loaded As: Valve Server Plugin." If the command is not recognized, see the [[Installing Metamod:Source#Troubleshooting|Troubleshooting]] section below.</li>
</ol>

==Custom VDF File==
Metamod:Source 1.10.0 and later include a <tt>metamod.vdf</tt> file for easier installation on most games. If you have trouble getting it to load, [http://www.metamodsource.net/?go=vdf go here] to generate a VDF file specific to your game. This file should be placed into your server's <tt>addons</tt> directory.

Known setups that require this step:
<ol>
<li>Games on the Episode 1 or older engines.</li>
<li>Listen servers (created with the in-game "Create Server" option) for non-english game clients.</li>
</ol>

=GameInfo=
'''Note: This is normally not needed - if you do not understand what this, do NOT do this unless instructed to. The above instructions are sufficient to install Metamod:Source for 99% of servers.'''

Metamod:Source 1.4.2 and lower used an older method for loading itself. The advantage of this method was that Metamod:Source could be loaded before the actual game mod, which gave it a small amount of extra functionality. This functionality was never used by plugin developers, and Steam updates kept overwriting <tt>gameinfo.txt</tt> files, so we switched to a different loading mechanism.

However this loading mechanism may still be desirable if you run into backwards compatibility issues, or you have a plugin which takes advantage of the early-loading mechanism. If this is your case, here are the <tt>gameinfo.txt</tt> directions below:

<ul>
<li>Open the file in the mod folder called "gameinfo.txt". You will see a few lines at the bottom like this:
<pre>
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}
</pre></li>
<li>Add a line after the "{" sign but before all of the "Game" entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>If you're using Windows, you may need to use a backwards slash (\) instead.
<li>You're done! To test whether it worked, restart your game server and type "meta version" in the server console. You should see a line that says "Loaded as: GameDLL (gameinfo.txt)." If it doesn't recognize the command, the installation probably failed. If the "Loaded as:" line says something else, <tt>gameinfo.txt</tt> was probably not modified correctly.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

The <tt>gameinfo.txt</tt> loading method is supported as a legacy feature only. The patcher tool is no longer provided. You can mark <tt>gameinfo.txt</tt> if you absolutely want to protect it from being overwritten.

We will continue to make sure Metamod:Source can load via this method for as long as the Source Engine allows it. However, we will concentrate more on supporting the new loading mechanism for general use.

[[Category:Metamod:Source Documentation]]

Installing SourceMod

2013-07-07T12:45:58Z

Asherkin: /* Metamod lists no plugins */

{{Languages|Installing_SourceMod}}

Installing SourceMod is very simple, and it can be added with almost no configuration changes.
 '''The below is a detailed install guide and provides excellent issue and install feedback. However, if you're having troubles understanding the page and its instructions, [[Installing_SourceMod_(simple)|a simplified install guide is available here]].'''

=Prerequisites=
A GUI Web Browser to retrieve Metamod and SourceMod compressed archives.
A tool to copy archive to your dedicated server host.

SourceMod requires [[Metamod:Source]] 1.8.0 or higher. [http://www.metamodsource.net/ Click here] to visit the Metamod:Source homepage. Instructions to install SourceMM manually can be found [http://wiki.alliedmods.net/index.php/Installing_Metamod:Source here].

SourceMod will run on any mod built using the Source SDK. It also supports "The Ship," which uses the Source engine.

=Uploading/Installing=
==Local Server==
To install SourceMod locally, simply extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike, <tt>dod</tt> for Day of Defeat, et cetera).
[http://www.sourcemod.net/downloads.php Download Here]

==Remote Server==
To install SourceMod remotely, first extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your local computer (for example, your Desktop). You will see an <tt>addons</tt> folder.

Using a tool such as [http://www.google.com/search?q=FTP FTP], locate your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike:Source, <tt>dod</tt> for Day of Defeat:Source, et cetera). Underneath this folder, you should have an <tt>addons</tt> folder (if not, Metamod:Source is probably not installed). From your local <tt>addons</tt> folder, upload the entire contents to your remote <tt>addons</tt> folder. When done, your remote <tt>addons</tt> folder should have a <tt>sourcemod</tt> folder.

If you have trouble with these steps, you need to get acquainted with FTP and server management. However, you can also ask your server provider for help. Some providers also have web interfaces for managing your server.

Alternatively, if you copied the tar.gz to your srcds directory, execute the following from the cstrike sub directory:
tar -xzf ../sourcemod-1.1.0.tar.gz

=Checking the Install=
Your folder layout should look like:
*<tt>[mod]</tt> - Your mod's folder
**<tt>addons</tt>
***<tt>metamod</tt> - Metamod:Source
***<tt>sourcemod</tt> - SourceMod

Once SourceMod is uploaded/copied and configured with Metamod:Source, restart your server completely. If it is local, shut it down and restart it. If it is remote, you may need to ask your server provider for help. However, it is often safe to issue a "quit" command via [[rcon]], since most providers will automatically restart your server.

First, in your [[server console]] (not client console), type:
<pre>meta list</pre>

If the install worked, you will see something like:
<pre>] meta list
Listing 1 plugin:
[01] SourceMod (1.1.0.2489) by AlliedModders LLC</pre>

You should then be able to use the SourceMod root console command, which can be invoked with simply:
<pre>sm</pre>

For example:
<pre>] sm version
SourceMod Version Information:
SourceMod Version: 1.1.0.2489
SourcePawn Engine: SourcePawn 1.1, jit-x86 (build 1.1.0-svn)
SourcePawn API: v1 = 4, v2 = 2
Compiled on: Sep 5 2008 02:02:12
http://www.sourcemod.net/
</pre>

Lastly, assuming you have already setup your administration user, you can test the in game menu by joining the server, and in the client console type the following:
<pre>sm_admin</pre>
You should see a menu popup with all you options.

=Troubleshooting=
If the install failed, you will generally see one of four symptoms.

==Metamod reports NOFILE or FAILED==
If "meta list" replies with something like this:
<pre>] meta list
Listing 1 plugin:
[01] <NOFILE></pre>

Most likely, either the files are not located in the correct place, or the file could not be loaded. For more information, use the following command (except use the correct list number):
<pre>meta info 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
Listing 0 plugins:</pre>

There are several causes of this error.

# The most common cause is that sourcemod.vdf can't be located in the addons/metamod folder. Verify that sourcemod.vdf is present in this folder.
# If sourcemod.vdf is present, make sure you are using the correct build of Sourcemod (zip = windows, tar.gz = linux).

==Metamod says nothing==
If "meta list" has no reply at all, Metamod:Source is not properly installed. [http://wiki.alliedmods.net/index.php/Installing_SourceMM This wiki page] may provide you with clues on how to solve this problem.

[[Category:SourceMod Documentation]]

Installing SourceMod

2013-07-07T12:44:12Z

Asherkin: /* Metamod reports NOFILE or FAILED */

{{Languages|Installing_SourceMod}}

Installing SourceMod is very simple, and it can be added with almost no configuration changes.
 '''The below is a detailed install guide and provides excellent issue and install feedback. However, if you're having troubles understanding the page and its instructions, [[Installing_SourceMod_(simple)|a simplified install guide is available here]].'''

=Prerequisites=
A GUI Web Browser to retrieve Metamod and SourceMod compressed archives.
A tool to copy archive to your dedicated server host.

SourceMod requires [[Metamod:Source]] 1.8.0 or higher. [http://www.metamodsource.net/ Click here] to visit the Metamod:Source homepage. Instructions to install SourceMM manually can be found [http://wiki.alliedmods.net/index.php/Installing_Metamod:Source here].

SourceMod will run on any mod built using the Source SDK. It also supports "The Ship," which uses the Source engine.

=Uploading/Installing=
==Local Server==
To install SourceMod locally, simply extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike, <tt>dod</tt> for Day of Defeat, et cetera).
[http://www.sourcemod.net/downloads.php Download Here]

==Remote Server==
To install SourceMod remotely, first extract the <tt>.zip</tt> (Windows) or <tt>.tar.gz</tt> (Linux) package to your local computer (for example, your Desktop). You will see an <tt>addons</tt> folder.

Using a tool such as [http://www.google.com/search?q=FTP FTP], locate your mod folder (i.e. <tt>cstrike</tt> for Counter-Strike:Source, <tt>dod</tt> for Day of Defeat:Source, et cetera). Underneath this folder, you should have an <tt>addons</tt> folder (if not, Metamod:Source is probably not installed). From your local <tt>addons</tt> folder, upload the entire contents to your remote <tt>addons</tt> folder. When done, your remote <tt>addons</tt> folder should have a <tt>sourcemod</tt> folder.

If you have trouble with these steps, you need to get acquainted with FTP and server management. However, you can also ask your server provider for help. Some providers also have web interfaces for managing your server.

Alternatively, if you copied the tar.gz to your srcds directory, execute the following from the cstrike sub directory:
tar -xzf ../sourcemod-1.1.0.tar.gz

=Checking the Install=
Your folder layout should look like:
*<tt>[mod]</tt> - Your mod's folder
**<tt>addons</tt>
***<tt>metamod</tt> - Metamod:Source
***<tt>sourcemod</tt> - SourceMod

Once SourceMod is uploaded/copied and configured with Metamod:Source, restart your server completely. If it is local, shut it down and restart it. If it is remote, you may need to ask your server provider for help. However, it is often safe to issue a "quit" command via [[rcon]], since most providers will automatically restart your server.

First, in your [[server console]] (not client console), type:
<pre>meta list</pre>

If the install worked, you will see something like:
<pre>] meta list
Listing 1 plugin:
[01] SourceMod (1.1.0.2489) by AlliedModders LLC</pre>

You should then be able to use the SourceMod root console command, which can be invoked with simply:
<pre>sm</pre>

For example:
<pre>] sm version
SourceMod Version Information:
SourceMod Version: 1.1.0.2489
SourcePawn Engine: SourcePawn 1.1, jit-x86 (build 1.1.0-svn)
SourcePawn API: v1 = 4, v2 = 2
Compiled on: Sep 5 2008 02:02:12
http://www.sourcemod.net/
</pre>

Lastly, assuming you have already setup your administration user, you can test the in game menu by joining the server, and in the client console type the following:
<pre>sm_admin</pre>
You should see a menu popup with all you options.

=Troubleshooting=
If the install failed, you will generally see one of four symptoms.

==Metamod reports NOFILE or FAILED==
If "meta list" replies with something like this:
<pre>] meta list
Listing 1 plugin:
[01] <NOFILE></pre>

Most likely, either the files are not located in the correct place, or the file could not be loaded. For more information, use the following command (except use the correct list number):
<pre>meta info 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
Listing 0 plugins:</pre>

There are several causes of this error.

# The most common cause is that sourcemod.vdf can't be located in the addons/metamod folder. Verify that sourcemod.vdf is present in this folder.
# If sourcemod.vdf is present, make sure you are using the correct build of Sourcemod (zip = windows, tar.gz = linux).
# If the game was recently updated, it may be using a newer filesystem interface causing MetaMod to disable VDF loading. Try switching to a [http://www.sourcemm.net/snapshots snapshot build] or manually add sourcemod to MetaMod's addons/metamod/metaplugins.ini

==Metamod says nothing==
If "meta list" has no reply at all, Metamod:Source is not properly installed. [http://wiki.alliedmods.net/index.php/Installing_SourceMM This wiki page] may provide you with clues on how to solve this problem.

[[Category:SourceMod Documentation]]

Spcomp (Emscripten)

2013-05-02T20:38:02Z

Asherkin:

{{Lowercase_title}}

In <tt>sourcepawn/compiler</tt>, clone Emscripten to <tt>./emscripten</tt> and copy <tt>../../plugins/include</tt> to <tt>./include</tt>.

Make sure you run the tests from https://github.com/kripken/emscripten/wiki/Tutorial.

You need to compile the LZMA encoder for compression to work:
cd ./emscripten/third_party/lzma.js
./doit.sh
cd ../../../

emscripten/emcc -O0 --closure 0 -DNDEBUG -fno-strict-aliasing -I . -I ../../public/ -I ../../public/sourcepawn/ \
-D_GNU_SOURCE -Wall -DLINUX -DHAVE_STDINT_H -DAMX_ANSIONLY -Dstricmp=strcasecmp -m32 -fno-exceptions -fno-rtti \
binreloc.c libpawnc.c lstring.c memfile.c pawncc.c sc1.c sc2.c sc3.c sc4.c sc5.c sc6.c sc7.c scexpand.c sci18n.c sclist.c \
scmemfil.c scstate.c sctracker.c scvars.c sp_file.c sp_symhash.c zlib/adler32.c zlib/compress.c zlib/crc32.c zlib/deflate.c \
zlib/gzio.c zlib/infback.c zlib/inffast.c zlib/inflate.c zlib/inftrees.c zlib/trees.c zlib/uncompr.c zlib/zutil.c \
--compression emscripten/third_party/lzma.js/lzma-native,emscripten/third_party/lzma.js/lzma-decoder.js,LZMA.decompress \
-o spcomp.html --preload-file include -Wno-format -Wno-parentheses -Wno-unused -Wno-sometimes-uninitialized -funroll-loops \
-ldl -lm -lgcc -s UNALIGNED_MEMORY=1

Enabling optimisations currently breaks emcc, leave them disabled.

UPDATE: Due to a small patch to spcomp, optimisation is now possible. You can also enable the closure compiler if you're writing your own frontend.

emscripten/emcc -O3 --closure 0 -DNDEBUG -fno-strict-aliasing -I . -I ../../public/ -I ../../public/sourcepawn/ \
-D_GNU_SOURCE -Wall -DLINUX -DHAVE_STDINT_H -DAMX_ANSIONLY -Dstricmp=strcasecmp -m32 -fno-exceptions -fno-rtti \
binreloc.c libpawnc.c lstring.c memfile.c pawncc.c sc1.c sc2.c sc3.c sc4.c sc5.c sc6.c sc7.c scexpand.c sci18n.c sclist.c \
scmemfil.c scstate.c sctracker.c scvars.c sp_file.c sp_symhash.c zlib/adler32.c zlib/compress.c zlib/crc32.c zlib/deflate.c \
zlib/gzio.c zlib/infback.c zlib/inffast.c zlib/inflate.c zlib/inftrees.c zlib/trees.c zlib/uncompr.c zlib/zutil.c \
--compression emscripten/third_party/lzma.js/lzma-native,emscripten/third_party/lzma.js/lzma-decoder.js,LZMA.decompress \
-o spcomp.html --preload-file include -Wno-format -Wno-parentheses -Wno-unused -Wno-sometimes-uninitialized -funroll-loops \
-ldl -lm -lgcc

spcomp won't be able to find the include folder automatically, make sure you invoke it with <tt>-iinclude</tt>.

Spcomp (Emscripten)

2013-04-05T06:19:12Z

Asherkin: Created page with "{{Lowercase_title}} In <tt>sourcepawn/compiler</tt>, clone Emscripten to <tt>./emscripten</tt> and copy <tt>../../plugins/include</tt> to <tt>./include</tt>. Make sure you r..."

Introduction to SourceMod Plugins

2013-03-17T16:13:02Z

Asherkin: Moved incomplete new tutorial to talk page.

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.

=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=771& 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=940& AskPluginLoad2()] - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here.
*[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=583& OnAllPluginsLoaded()] - Called once, after all non-late loaded plugins have called OnPluginStart.
*[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. You can block a player from connecting by returning Plugin_Stop and setting rejectmsg to an error message.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=916& OnClientConnected()] - Called after a player connects. Signifies that the player is in-game and IsClientConnected() will return true. '''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 OnClientConnected and OnClientPreAdminCheck/OnClientDisconnect. 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'''. 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 starts. '''This is paired to OnClientConnected().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=391& OnClientDisconnect_Post()] - Called when a player's disconnection ends. '''This is paired to OnClientConnected().'''

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

Talk:Introduction to SourceMod Plugins

2013-03-17T16:12:18Z

Asherkin: Created page with " ---- <div class="info">Below is FaTony's WIP rewrite of the command tutorial, it's been remove from the main page as it's incomplete and more confusing for new users --~~..."

----

<div class="info">Below is FaTony's WIP rewrite of the command tutorial, it's been remove from the main page as it's incomplete and more confusing for new users --[[User:Asherkin|Asherkin]] ([[User talk:Asherkin|talk]]) 11:12, 17 March 2013 (CDT)</div>
=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.

----

MediaWiki:Common.css

2013-03-17T16:11:08Z

Asherkin:

/* CSS placed here will be applied to all skins */
div.info {
background-color:#FFFFFF;
padding-left:6px;
padding-bottom:2px;
padding-top:2px;
background-position: 8px center;
font-family: Arial, Helvetica, sans-serif;
font-size: 12px;
color: #003399;
border-top-width: 1px;
border-right-width: 1px;
border-bottom-width: 1px;
border-left-width: 10px;
border-top-style: solid;
border-right-style: solid;
border-bottom-style: solid;
border-left-style: solid;
border-top-color: #aaa;
border-right-color: #aaa;
border-bottom-color: #aaa;
border-left-color: #1e90ff;
letter-spacing: 0.1em;
word-spacing:0.1em;
min-height:50px;
margin-left:10px;
margin-right:10px;
vertical-align:middle;
}

MediaWiki:Common.css

2013-03-17T16:07:50Z

Asherkin: Created page with "/* CSS placed here will be applied to all skins */ div.info { background-color:#FFFFFF; padding-left:70px; padding-bottom:2px; padding-top:2px; background-position: 8px c..."

/* CSS placed here will be applied to all skins */
div.info {
background-color:#FFFFFF;
padding-left:70px;
padding-bottom:2px;
padding-top:2px;
background-position: 8px center;
font-family: Arial, Helvetica, sans-serif;
font-size: 12px;
color: #003399;
border-top-width: 1px;
border-right-width: 1px;
border-bottom-width: 1px;
border-left-width: 10px;
border-top-style: solid;
border-right-style: solid;
border-bottom-style: solid;
border-left-style: solid;
border-top-color: #aaa;
border-right-color: #aaa;
border-bottom-color: #aaa;
border-left-color: #1e90ff;
letter-spacing: 0.1em;
word-spacing:0.1em;
min-height:50px;
background-repeat: no-repeat;
background-image:url(../Info.png);
margin-left:10px;
margin-right:10px;
vertical-align:middle;
}

Introduction to SourceMod Plugins

2013-03-17T15:56:32Z

Asherkin: /* Declaration */ Fixed link to ConCmd

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=771& 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=940& AskPluginLoad2()] - Called once, immediately after the plugin is loaded from the disk. This function can be used to stop a plugin from loading and return a custom error message; return APLRes_Failure and use strcopy on to replace the error string. All CreateNative and RegPluginLibrary calls should be done here.
*[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=583& OnAllPluginsLoaded()] - Called once, after all non-late loaded plugins have called OnPluginStart.
*[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. You can block a player from connecting by returning Plugin_Stop and setting rejectmsg to an error message.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=916& OnClientConnected()] - Called after a player connects. Signifies that the player is in-game and IsClientConnected() will return true. '''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 OnClientConnected and OnClientPreAdminCheck/OnClientDisconnect. 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'''. 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 starts. '''This is paired to OnClientConnected().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=391& OnClientDisconnect_Post()] - Called when a player's disconnection ends. '''This is paired to OnClientConnected().'''

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