AlliedModders Wiki - User contributions [en]

Supported Games (Metamod:Source)

2010-08-22T10:53:31Z

Matthias Vance:

[[Metamod:Source]] generally tries to support all Source engine based games. However, some API features may only be supported by some games. This does not mean these features will not work on games not listed here, but that games listed here are specifically known and tested to work.

*'''[[Introduction to SourceMM Coding#User_Message_Enumeration|User Message API Functions]]''' - <tt>GetUserMessageCount()</tt>, <tt>FindUserMessage()</tt>, <tt>GetUserMessage()</tt>
**Battle Grounds 2
**Counter-Strike: Source
**Day of Defeat: Source
**Dystopia
**Garry's Mod 10
**Goldeneye: Source
**Half-Life 2: Capture the Flag
**Half-Life 2: Deathmatch
**The Hidden: Source
**Insects Infestation
**Jailbreak!
**Kreedz Climbing
**Pirates, Vikings, and Knights II
**Team Fortress 2
**The Ship
**SourceForts
**Zombie Master
**Dark Messiah
**Left 4 Dead
**Left 4 Dead 2

[[Category:Metamod:Source Documentation]]

Introduction to SourcePawn (legacy syntax)

2010-08-19T09:30:55Z

Matthias Vance: /* Functions */

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

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

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

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

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

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

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

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

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

numbers[5] = 20;</pawn>

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

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

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

Expressions will be discussed in depth later in the article.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return sum;
}</pawn>

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

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

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

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

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

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

return sum;
}</pawn>

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

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

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

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

ChangeValue(a);

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

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

More examples of functions will be provided throughout the article.

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

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

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

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

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

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

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

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

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

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

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

ChangeArray(example, 2, 29);

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

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

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

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

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

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

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

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

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

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

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

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

a = a + 5;</pawn>

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

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

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

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

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

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

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

For example:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return total;
}</pawn>

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

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

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

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

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

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

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

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

return total;
}</pawn>

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

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

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

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

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

return index;
}</pawn>

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

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

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

return sum;
}</pawn>

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

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

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

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

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

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

Function1();
}</pawn>

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

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

<pawn>Function1()
{
new A;

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

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

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

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

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

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

/* Code */
}</pawn>

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

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

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

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

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

===Explanation===
For example:

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

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

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

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

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

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

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

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

PrintToServer("%s", blah);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

counter += inc;

return counter;
}</pawn>

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

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

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

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

Note that statics can exist in any local scope:

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Introduction to SourcePawn (legacy syntax)

2010-06-03T05:36:03Z

Matthias Vance: /* Natives */

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

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

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

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

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

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

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

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

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

numbers[5] = 20;</pawn>

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

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

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

Expressions will be discussed in depth later in the article.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return sum;
}</pawn>

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

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

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

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

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

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

return sum;
}</pawn>

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

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

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

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

ChangeValue(a);

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

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

More examples of functions will be provided throughout the article.

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

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

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

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

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

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

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

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

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

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

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

ChangeArray(example, 2, 29);

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

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

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

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

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

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

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

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

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

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

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

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

a = a + 5;</pawn>

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

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

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

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

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

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

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

For example:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return total;
}</pawn>

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

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

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

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

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

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

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

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

return total;
}</pawn>

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

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

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

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

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

return index;
}</pawn>

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

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

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

return sum;
}</pawn>

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

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

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

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

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

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

Function1();
}</pawn>

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

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

<pawn>Function1()
{
new A;

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

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

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

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

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

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

/* Code */
}</pawn>

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

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

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

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

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

===Explanation===
For example:

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

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

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

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

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

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

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

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

PrintToServer("%s", blah);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

counter += inc;

return counter;
}</pawn>

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

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

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

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

Note that statics can exist in any local scope:

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Porting to Orange Box

2010-05-01T11:03:11Z

Matthias Vance:

__FORCETOC__
Porting Valve Server Plugins or Metamod:Source plugins to Orange Box is not very difficult. This article explores some of the changes and how to simplify them.

Users of Metamod:Source should upgrade to Metamod:Source 1.7 and use the 1.6+ API (see [[MM:S API Differences]]).

This document will assume a single preprocessor macro, <tt>ORANGEBOX_BUILD</tt>, determines that an Orange Box build is being made.

=Command Callbacks=
In the original Half-Life 2 engine, all commands used <tt>IVEngineServer::Cmd_Arg*</tt> in order to receive information about the current command's tokenization. However, these functions have been completely removed, and a new re-entrant version is in place.

Each of the following callbacks:
<cpp>void IServerGameClients::ClientCommand(edict_t *pEdict);
typedef void (*FnCommandCallback)(void);</cpp>

Is now:
<cpp>void IServerGameClients::ClientCommand(edict_t *pEdict, const CCommand &args);
typedef void (*FnCommandCallback)(const CCommand &args);</cpp>

Definitions for <tt>CCommand</tt> can be found in <tt>convar.h</tt>. A simple way to work around this change is to use wrapper functions. For example:

<cpp>
#if defined ORANGEBOX_BUILD
SH_DECL_HOOK2_void(IServerGameClients, ClientCommand, SH_NOATTRIB, 0, edict_t *, const CCommand &);
#else
SH_DECL_HOOK1_void(IServerGameClients, ClientCommand, SH_NOATTRIB, 0, edict_t *);
#endif

#if !defined ORANGEBOX_BUILD
class CCommand
{
public:
const char *ArgS()
{
return engine->Cmd_Args();
}
int ArgC()
{
return engine->Cmd_Argc();
}

const char *Arg(int index)
{
return engine->Cmd_Argv(index);
}
};
#endif

#if defined ORANGEBOX_BUILD
void Hook_ClientCommand(edict_t *pEntity, const CCommand &args)
#else
void Hook_ClientCommand(edict_t *pEntity)
#endif

{
#if !defined ORANGEBOX_BUILD
CCommand args;
#endif

const char *cmd = args.Arg(0);
/* ... stuff ... */
}</cpp>

=ConCommandBaseMgr Removed=
ConCommandBaseMgr has been removed. That means the normal call, <tt>ConCommandBaseMgr::OneTimeInit()</tt>, is no longer applicable. There are two other solutions to registering your ConVars and ConCommands:
*Use <tt>ConVar_Register</tt> instead.
*Use <tt>META_REGCVAR</tt> on each pointer (it will work on any ConCommandBase *) pointer, or <tt>META_REGCMD</tt> on each individual command name.

It is highly recommended that Metamod:Source plugins go through Metamod:Source's ConCommandBase registration process. This will make your plugin more compatible across engines and other plugins. Example:

<cpp>
class BaseAccessor : public IConCommandBaseAccessor
{
public:
bool RegisterConCommandBase(ConCommandBase *pVar)
{
META_REGCVAR(pVar);
}
} s_BaseAccessor;

void SetupEverything()
{
#if defined ORANGEBOX_BUILD
/* NOTE! g_pCvar must be set to a valid ICvar instance first. */
ConVar_Register(0, &s_BaseAccessor);
#else
ConCommandBaseMgr::OneTimeInit(&s_BaseAccessor);
#endif
}</cpp>

Note that Valve Server Plugins can pass <tt>NULL</tt> to use the default accessor. '''Metamod:Source plugins should not do this.''' Otherwise, Metamod:Source will not be able to keep track of the ConCommandBase allocations per-plugin.

=Renamings/Removals=
*<tt>VENGINE_CVAR_INTERFACE_VERSION</tt> was renamed to <tt>CVAR_INTERFACE_VERSION</tt>.
*<tt>FCVAR_PLUGIN</tt> was removed. It is probably no longer needed with the advent of <tt>ConVar_Unregister</tt>.

=Sample Port=
An example of a plugin that fully supports both versions is [http://www.bailopan.net/stripper Stripper:Source] ([http://svn.alliedmods.net/viewvc.cgi/sourcemm/stripper/?root=dvander SVN here]).

Note that this plugin uses the new "extended loading" API available in Metamod:Source 1.6.0. The thin-loader library runs on any Metamod:Source version, and will correctly pick one of 6 child plugins to load. This allows Stripper:Source to be distributed as one package with no configuration hassle.

[[Category:Metamod:Source Development]]

Creating Natives (SourceMod Scripting)

2010-04-26T17:45:43Z

Matthias Vance: Changed AskPluginLoad to AskPluginLoad2.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

if (len <= 0)
{
return
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:SourceMod Scripting]]

Installing SourceMod

2010-01-02T15:58:28Z

Matthias Vance: Spelling

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.4.3 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
-Id- Name Version Author Status
[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 list 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
-Id- Name Version Author Status </pre>

You forgot to add SourceMod to the <tt>addons/metamod/metaplugins.ini</tt> file.
Or if that doesn't fix your problem, make sure you are using the correct build of Sourcemod (zip = windows, tar = 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

2010-01-02T15:57:13Z

Matthias Vance: /* Prerequisites */

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.4.3 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]], and 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
-Id- Name Version Author Status
[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 list 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
-Id- Name Version Author Status </pre>

You forgot to add SourceMod to the <tt>addons/metamod/metaplugins.ini</tt> file.
Or if that doesn't fix your problem, make sure you are using the correct build of Sourcemod (zip = windows, tar = 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

2010-01-02T15:56:21Z

Matthias Vance: /* Prerequisites */

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.4.3 or higher. [http://www.metamodsource.net/ Click here] to visit the Metamod:Source homepage. Instructions to install SourceMM muanually 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]], and 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
-Id- Name Version Author Status
[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 list 1</pre>

==Metamod lists no plugins==
If "meta list" replies with something like this:
<pre>] meta list
-Id- Name Version Author Status </pre>

You forgot to add SourceMod to the <tt>addons/metamod/metaplugins.ini</tt> file.
Or if that doesn't fix your problem, make sure you are using the correct build of Sourcemod (zip = windows, tar = 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]]

Menu API (SourceMod)

2009-08-25T07:42:06Z

Matthias Vance: Fixed a typo in the example code.

SourceMod has an extensive API for building and displaying menus to clients. Unlike AMX Mod X, this API is highly state driven. Menus are based on callbacks which are guaranteed to be fired.

For C++, the Menu API can be found in <tt>public/IMenuManager.h</tt>. For SourcePawn, it is in <tt>plugins/include/menus.inc</tt>.

=Objects=
The SourceMod Menu System is based on an object oriented hierarchy. Understanding this hierarchy, even for scripting, is critical to using menus effectively.

==Styles==
The top level object is a ''MenuStyle'' (<tt>IMenuStyle</tt> in C++). Styles describe a unique menu system. There are two such styles built into SourceMod:
*Valve Style, also called "ESC" menus; 8 items per page, no raw/disabled text can be rendered
*Radio Style, also called "AMX" menus; 10 items per page, raw/disabled text can be rendered

Each MenuStyle has its own rules and properties. You can think of them as existing on separate "channels." For example, two different menus can exist on a player's screen as both a Valve menu and a Radio menu at the same time, and SourceMod will be able to manage both without any problems. This is because each style keeps track of its own menus separately.

==Panels==
Menu displays are drawn with a lower level interface called ''Panels'' (<tt>IMenuPanel</tt> in C++). Panels describe exactly one chunk of display text. Both selectable items and raw text can be added to a panel as long as its parent style supports the contents you're trying to draw. For example, the Valve style does not support drawing raw text or disabled items. But with a Radio-style Panel, you can display a large amount of on-screen data in your own format.

Panels are considered temporary objects. They are created, rendered, displayed, and destroyed. Although they can be saved indefinitely, it is not necessary to do so.

Valve Style drawing rules/limitations:
*Max items per page is 8.
*Disabled items cannot be drawn.
*Raw text cannot be drawn.
*Spacers do not add a space/newline, giving a "cramped" feel.
*Users must press "ESC" or be at their console to view the menu.

Radio Style drawing rules/limitations:
*Max items per page is 10.
*Titles appear white; items appear yellow, unless disabled, in which case they are white.
*The 0th item is always white. For consistency, this means navigational controls explained in the next section are always white, and simply not drawn if disabled.

==Menus==
Lastly, there are plain ''Menus'' (<tt>IBaseMenu</tt> in C++). These are helper objects designed for storing a menu based on selectable items. Unlike low-level panels, menus are containers for '''items''', and can only contain items which are selectable (i.e., do not contain raw text). They fall into two categories:
*Non-paginated: The menu can only have a certain number of items on it, and no control/navigation options will be added, except for an "Exit" button which will always be in the last position supported by the style.
**Valve Style maximum items: 8
**Radio Style maximum items: 10
*Paginated: The menu can have any number of items. When displayed, only a certain number of items will be drawn at a time. Automatic navigation controls are added so players can easily move back and forth to different "pages" of items in the menu.
**"Previous" is always drawn as the first navigation item, third from the last supported position. This will not be drawn if the menu only contains one page. If there are no previous pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 6
***Radio Style position: 8
**"Next" is always drawn as the second navigation item, second from the last supported position. This will not be drawn if the menu only contains one page. If there are no further pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 7
***Radio Style position: 9
**"Exit" is drawn if the menu has the exit button property set. It is always the last supported item position.
***Valve Style position: 8
***Radio Style position: 10

The purpose of Menus is to simplify the procedure of storing, drawing, and calculating the selection of items. Thus, menus do not allow for adding raw text, as that would considerably complicate the drawing algorithm. ''Note: The C++ API supports hooking <tt>IBaseMenu</tt> drawing procedures and adding raw text; this will be added to the scripting API soon.''

Internally, Menus are drawn via a ''RenderMenu'' algorithm. This algorithm creates a temporary panel and fills it with items from menus. This panel is then displayed to a client. The algorithm attempts to create a consistent feel across all menus, and across all styles. Thus any menu displayed via the <tt>IBaseMenu</tt> class, or <tt>Menu</tt> Handles, will look and act the same, and the Menu API is based off the Panel API.

=Callbacks=
==Overview==
Menus are a callback based system. Each callback represents an action that occurs during a ''menu display cycle''. A cycle consists of a number of notifications:
*Start notification.
**Display notification if the menu can be displayed to the client.
**Either an item select or menu cancel notification.
*End notification.

Since ''End'' signifies the end of a full display cycle, it is usually used to destroy temporary menus.

==Specification==
A detailed explanation of these events is below. For C++, an <tt>IBaseMenu</tt> pointer is always available. For SourcePawn, a <tt>Menu</tt> Handle and a <tt>MenuAction</tt> are always set in the <tt>MenuHandler</tt> callback. Unlike C++, the SourcePawn API allows certain actions to only be called if they are requested at menu creation time. This is an optimization. However, certain actions cannot be prevented from being called.

*'''Start'''. The menu has been acknowledged. This does not mean it will be displayed; however, it guarantees that "OnMenuEnd" will be called.
**<tt>OnMenuStart()</tt> in C++.
**<tt>MenuAction_Start</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: Ignored (always 0).
***<tt>param2</tt>: Ignored (always 0).
*'''Display'''. The menu is being displayed to a client.
**<tt>OnMenuDisplay()</tt> in C++. An <tt>IMenuPanel</tt> pointer and client index are available.
**<tt>MenuAction_Display</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A Handle to a menu panel.
*'''Select'''. An item on the menu has been selected. The item position given will be the position in the menu, rather than the key pressed (unless the menu is a raw panel).
**<tt>OnMenuSelect()</tt> in C++. A client index and item position are passed.
**<tt>MenuAction_Select</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: An item position.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.
*'''End'''. The menu's display cycle has finished; this means that the "Start" action has occurred, and either "Select" or "Cancel" has occurred thereafter. This is typically where menu resources are removed/deleted.
**<tt>OnMenuEnd()</tt> in C++.
**<tt>MenuAction_End</tt> in SourcePawn. This action is always triggered, whether requested or not.
***<tt>param1</tt>: A menu end reason code.
***<tt>param2</tt>: If param1 was MenuEnd_Cancelled, this contains a menu cancellation reason code.

==Panels==
For panels, the callback rules change. Panels only receive two of the above callbacks, and it is guaranteed that only one of them will be called for a given display cycle. For C++, the <tt>IBaseMenu</tt> pointer will always be <tt>NULL</tt>. For SourcePawn, the menu Handle will always be <tt>INVALID_HANDLE</tt>.

*'''Select'''. A key has been pressed. This can be any number and should not be considered as reliably in bounds. For example, even if you only had 2 items in your panel, a client could trigger a key press of "43."
**<tt>OnMenuSelect()</tt> in C++. A client index and key number pressed are passed.
**<tt>MenuAction_Select</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: Number of the key pressed.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.

=Examples=
First, let's start off with a very basic menu. We want the menu to look like this:

<pre>Do you like apples?
1. Yes
2. No</pre>

We'll draw this menu with both a basic Menu and a Panel to show the API differences.

==Basic Menu==
First, let's write our example using the Menu building API.

<pawn>public OnPluginStart()
{
RegConsoleCmd("menu_test1", Menu_Test1);
}

public MenuHandler1(Handle:menu, MenuAction:action, param1, param2)
{
/* If an option was selected, tell the client about the item. */
if (action == MenuAction_Select)
{
new String:info[32];
new bool:found = GetMenuItem(menu, param2, info, sizeof(info));
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info);
}
/* If the menu was cancelled, print a message to the server about it. */
else if (action == MenuAction_Cancel)
{
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2);
}
/* If the menu has ended, destroy it */
else if (action == MenuAction_End)
{
CloseHandle(menu);
}
}

public Action:Menu_Test1(client, args)
{
new Handle:menu = CreateMenu(MenuHandler1);
SetMenuTitle(menu, "Do you like apples?");
AddMenuItem(menu, "yes", "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
DisplayMenu(menu, client, 20);

return Plugin_Handled;
}</pawn>

Note a few very important points from this example:
*One of either <tt>Select</tt> or <tt>Cancel</tt> will always be sent to the action handler.
*<tt>End</tt> will always be sent to the action handler.
*We destroy our Menu in the <tt>End</tt> action, because our Handle is no longer needed. If we had destroyed the Menu after <tt>DisplayMenu</tt>, it would have canceled the menu's display to the client.
*Menus, by default, have an exit button. We disabled this in our example.
*Our menu is set to display for 20 seconds. That means that if the client does not select an item within 20 seconds, the menu will be canceled. This is usually desired for menus that are for voting. Note that unlike AMX Mod X, you do not need to set a timer to make sure the menu will be ended.
*Although we created and destroyed a new Menu Handle, we didn't need to. It is perfectly acceptable to create the Handle once for the lifetime of the plugin.

Our finished menu and attached console output looks like this (I selected "Yes"):

[[Image:Basic_menu_1.PNG]]

==Basic Panel==
Now, let's rewrite our example to use Panels instead.

<pawn>public OnPluginStart()
{
RegConsoleCmd("panel_test1", Panel_Test1);
}

public PanelHandler1(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
PrintToConsole(param1, "You selected item: %d", param2);
} else if (action == MenuAction_Cancel) {
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2);
}
}

public Action:Panel_Test1(client, args)
{
new Handle:panel = CreatePanel();
SetPanelTitle(panel, "Do you like apples?");
DrawPanelItem(panel, "Yes");
DrawPanelItem(panel, "No");

SendPanelToClient(panel, client, PanelHandler1, 20);

CloseHandle(panel);

return Plugin_Handled;
}</pawn>

As you can see, Panels are significantly different.
*We can destroy the Panel as soon as we're done displaying it. We can create the Panel once and keep re-using it, but we can destroy it at any time without interrupting client menus.
*The Handler function gets much less data. Since panels are designed as a raw display, no "item" information is saved internally. Thus, the handler function only knows whether the display was canceled or whether (and what) numerical key was pressed.
*There is no automation. You cannot add more than a certain amount of selectable items to a Panel and get pagination. Automated control functionality requires using the heftier Menu object API.

Our finished display and console output looks like this (I selected "Yes"):

[[Image:Basic_panel_1.PNG]]

==Basic Paginated Menu==
Now, let's take a more advanced example -- pagination. Let's say we want to build a menu for changing the map. An easy way to do this is to read the <tt>maplist.txt</tt> file at the start of a plugin and build a menu out of it.

Since reading and parsing a file is an expensive operation, we only want to do this once per map. Thus we'll build the menu in <tt>OnMapStart</tt>, and we won't call <tt>CloseHandle</tt> until <tt>OnMapEnd</tt>.

Source code:
<pawn>new Handle:g_MapMenu = INVALID_HANDLE

public OnPluginStart()
{
RegConsoleCmd("menu_changemap", Command_ChangeMap);
}

public OnMapStart()
{
g_MapMenu = BuildMapMenu();
}

public OnMapEnd()
{
if (g_MapMenu != INVALID_HANDLE)
{
CloseHandle(g_MapMenu);
g_MapMenu = INVALID_HANDLE;
}
}

Handle:BuildMapMenu()
{
/* Open the file */
new Handle:file = OpenFile("maplist.txt", "rt");
if (file == INVALID_HANDLE)
{
return INVALID_HANDLE;
}

/* Create the menu Handle */
new Handle:menu = CreateMenu(Menu_ChangeMap);
new String:mapname[255];
while (!IsEndOfFile(file) && ReadFileLine(file, mapname, sizeof(mapname)))
{
if (mapname[0] == ';' || !IsCharAlpha(mapname[0]))
{
continue;
}
/* Cut off the name at any whitespace */
new len = strlen(mapname);
for (new i=0; i<len; i++)
{
if (IsCharSpace(mapname[i]))
{
mapname[i] = '\0';
break;
}
}
/* Check if the map is valid */
if (!IsMapValid(mapname))
{
continue;
}
/* Add it to the menu */
AddMenuItem(menu, mapname, mapname);
}
/* Make sure we close the file! */
CloseHandle(file);

/* Finally, set the title */
SetMenuTitle(menu, "Please select a map:");

return menu;
}

public Menu_ChangeMap(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
new String:info[32];

/* Get item info */
new bool:found = GetMenuItem(menu, param2, info, sizeof(info));

/* Tell the client */
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info);

/* Change the map */
ServerCommand("changelevel %s", info);
}
}

public Action:Command_ChangeMap(client, args)
{
if (g_MapMenu == INVALID_HANDLE)
{
PrintToConsole(client, "The maplist.txt file was not found!");
return Plugin_Handled;
}

DisplayMenu(g_MapMenu, client, MENU_TIME_FOREVER);

return Plugin_Handled;
}</pawn>

This menu results in many selections (my <tt>maplist.txt</tt> file had around 18 maps). So, our final menu has 3 pages, which side by side, look like:

[[Image:Basic_menu_2_page1.PNG]]
[[Image:Basic_menu_2_page2.PNG]]
[[Image:Basic_menu_2_page3.PNG]]

Finally, the console output printed this before the map changed to my selection, <tt>cs_office</tt>:
<pre>You selected item: 8 (found? 1 info: cs_office)</pre>

Displaying and designing this Menu with a raw <tt>ShowMenu</tt> message or <tt>Panel</tt> API would be very time consuming and difficult. We would have to keep track of all the items in an array of hardcoded size, pages which the user is viewing, and write a function which calculated item selection based on current page and key press. The Menu system, thankfully, handles all of this for you.

'''Notes:'''
*Control options which are not available are not drawn. For example, in the first page, you cannot go "back," and in the last page, you cannot go "next." Despite this, the menu API tries to keep each the interface as consistent as possible. Thus, visually, each navigational control is always in the same position.
*Although we specified no time out for our menu, if we had placed a timeout, flipping through pages does not affect the overall time. For example, if we had a timeout of 20, each successive page flip would continue to detract from the overall display time, rather than restart the allowed hold time back to 20.
*If we had disabled the Exit button, options 8 and 9 would still be "Back" and "Next," respectively.
*Again, we did not free the Menu Handle in <tt>MenuAction_End</tt>. This is because our menu is global/static, and we don't want to rebuild it every time.
*These images show "Back." In SourceMod revisions 1011 and higher, "Back" is changed to "Previous," and "Back" is reserved for the special "ExitBack" functionality.

=Voting=
SourceMod also has API for displaying menus as votable choices to more than one client. SourceMod automatically handles selecting an item and randomly picking a tie-breaker. The voting API adds two new <tt>MenuAction</tt> values, which for vote displays, are '''always''' passed:

*<tt>MenuAction_VoteStart</tt>: Fired after <tt>MenuAction_Start</tt> when the voting has officially started.
*<tt>MenuAction_VoteEnd</tt>: Fired when all clients have either voted or cancelled their vote menu. The chosen item is passed through <tt>param1</tt>. This is fired '''before''' <tt>MenuAction_End</tt>. It is important to note that it does not supercede <tt>MenuAction_End</tt>, nor is it the same thing. Menus should never be destroyed in <tt>MenuAction_VoteEnd</tt>. '''Note:''' This is not called if <tt>SetVoteResultCallback</tt>() is used.
*<tt>MenuAction_VoteCancel</tt>: Fired if the menu is cancelled while the vote is in progress. If this is called, <tt>MenuAction_VoteEnd</tt> or the result callback will not be called, but <tt>MenuAction_End</tt> will be afterwards. A vote cancellation reason is passed in <tt>param1</tt>.

The voting system extends overall menus with two additional properties:
*Only one vote can be active at a time. You must call <tt>IsVoteInProgress</tt>() or else <tt>VoteMenu</tt>() will fail.
*If a client votes and then disconnects while the vote is still active, the client's vote will be invalidated.

The example below shows has to create a function called <tt>DoVoteMenu()</tt> which will ask all clients whether or not they would like to change to the given map.

==Simple Vote==
<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
new String:map[64];
GetMenuItem(menu, param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
}
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu);
SetMenuTitle(menu, "Change map to: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

==Advanced Voting==
If you need more information about voting results than <tt>MenuAction_VoteEnd</tt> gives you, you can choose to have a different callback invoked. The new callback will provide much more information, but at a price: <tt>MenuAction_VoteEnd</tt> will not be called, and you will have to decide how to interpret the results. This is done via <tt>SetVoteResultCallback</tt>().

Example:
<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
}
}

public Handle_VoteResults(Handle:menu,
num_votes,
num_clients,
const client_info[][2],
num_items,
const item_info[][2])
{
/* See if there were multiple winners */
new winner = 0;
if (num_items > 1
&& (item_info[0][VOTEINFO_ITEM_VOTES] == item_info[1][VOTEINFO_ITEM_VOTES]))
{
winner = GetRandomInt(0, 1);
}

new String:map[64];
GetMenuItem(menu, item_info[winner][VOTEINFO_ITEM_INDEX], map, sizeof(map));
ServerCommand("changelevel %s", map);
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu);
SetVoteResultCallback(menu, Handle_VoteResults);
SetMenuTitle(menu, "Change map to: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

=ExitBack=
ExitBack is a special term to refer to the "ExitBack Button." This button is disabled by default. Normally, paginated menus have no "Previous" item for the first page. If the "ExitBack" button is enabled, the "Previous" item will show up as "Back."

Selecting the "ExitBack" option will exit the menu with <tt>MenuCancel_ExitBack</tt> and <tt>MenuEnd_ExitBack</tt>. The functionality of this is the same as a normal menu exit internally; extra functionality must be defined through the callbacks.

=Closing Menu Handles=
It is only necessary to close a menu handle on <tt>MenuAction_End</tt>. The <tt>MenuAction_End</tt> is done every time a menu is closed and no longer needed.

=Translations=
It is possible to dynamically translate menus to each player through the <tt>MenuAction_DisplayItem</tt> callback. A special native, <tt>RedrawMenuItem</tt>, is used to transform the text while inside the callback. Let's redo the vote example from earlier to be translated:

<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
new String:map[64];
GetMenuItem(menu, param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
} else if (action == MenuAction_DisplayItem) {
/* Get the display string, we'll use it as a translation phrase */
decl String:display[64];
GetMenuItem(menu, param2, "", 0, _, display, sizeof(display));

/* Translate the string to the client's language */
decl String:buffer[255];
Format(buffer, sizeof(buffer), "%T", display, param1);

/* Override the text */
return RedrawMenuItem(buffer);
} else if (action == MenuAction_Display) {
/* Panel Handle is the second parameter */
new Handle:panel = Handle:param2;

/* Get the map name we're changing to from the first item */
decl String:map[64];
GetMenuItem(menu, 0, map, sizeof(map));

/* Translate to our phrase */
decl String:buffer[255];
Format(buffer, sizeof(buffer), "%T", "Change map to?", client, map);

SetPanelTitle(panel, buffer);
}
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu, MenuAction_DisplayItem|MenuAction_Display);
SetMenuTitle(menu, "Change map to: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

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

{{LanguageSwitch}}

Writing Extensions

2009-03-27T12:41:25Z

Matthias Vance: /* Compiler Options */

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

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

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

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

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

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

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

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

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

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

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

You should now be able to compile a blank extension!

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

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

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

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

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

A quick explanation of these types:
*<tt>cell_t</tt> - This is a 32bit signed integer, the generic data type for Pawn.
*<tt>IPluginContext</tt> - This interface provides Virtual Machine functions for retrieving or modifying memory in the plugin.
*<tt>params</tt> - This is the "stack" of parameters that the plugin passed. It is an array from [0..N] where 0 contains N.
**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.

==Managed Forwards==
Let's say we want to create a forward that will be called when a player uses say chat. For simplicity, let's assume you already have a function that tells you when a player says say chat. We will just be creating the forward for it.

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

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

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

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

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

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

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

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

return true;
}</cpp>

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

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

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

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

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

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

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

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

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

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

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

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

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

Example:
<cpp>#ifndef _INCLUDE_MYINTERFACE_FILE_H_
#define _INCLUDE_MYINTERFACE_FILE_H_

#include <IShareSys.h>

#define SMINTERFACE_MYINTERFACE_NAME "IMyInterface"
#define SMINTERFACE_MYINTERFACE_VERSION 1

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

#endif //_INCLUDE_MYINTERFACE_FILE_H_</cpp>

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

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

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

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

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

IPluginManager *g_pPlugins = NULL;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=Conventions=

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

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

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

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

===Include Paths===
*SourceMod only:
**sdk\public\extensions
**sdk\public\sourcepawn
**sdk\public
*SourceMM (Note that sourcemm might be 'trunk' for you):
**sourcemm\sourcemm
**sourcemm\sourcehook
**sourcemm
*HL2SDK:
**game_shared
**public\vstdlib
**public\tier1
**public\tier0
**public\engine
**public\dlls
**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]]

Supported Games (Metamod:Source)

2009-03-08T20:48:52Z

Matthias Vance: Changed support for "Dark Messiah"

Supported Games (Metamod:Source)

2009-03-08T20:47:55Z

Matthias Vance:

[[Metamod:Source]] generally tries to support all Source engine based games. However, some API features may only be supported by some games. This does not mean these features will not work on games not listed here, but that games listed here are specifically known and tested to work.

The only Source-based game completely unsupported by [[Metamod:Source]] is Dark Messiah.

*'''[[Introduction to SourceMM Coding#User_Message_Enumeration|User Message API Functions]]''' - <tt>GetUserMessageCount()</tt>, <tt>FindUserMessage()</tt>, <tt>GetUserMessage()</tt>
**Battle Grounds 2
**Counter-Strike: Source
**Day of Defeat: Source
**Dystopia
**Garry's Mod 10
**Goldeneye: Source
**Half-Life 2: Capture the Flag
**Half-Life 2: Deathmatch
**The Hidden: Source
**Insects Infestation
**Jailbreak!
**Kreedz Climbing
**Pirates, Vikings, and Knights II
**Team Fortress 2
**The Ship
**SourceForts
**Zombie Master
**Dark Messiah

[[Category:Metamod:Source Documentation]]