AlliedModders Wiki - User contributions [en]

Pawn Tutorial

2007-08-10T22:09:03Z

Greenberet: /* Two Dimensional Arrays */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3
new z = 1_000_000 // Pawn supports numbers like this. So big values are easier to read.</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]

//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5

//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]

//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15

//This is also totally invalid
Players[-1] = 6

new a = 3
//This is also totally invalid.
//a must be a constant number.
new BadArray[a]

//So this is valid:
const b = 3
new GoodArray[b]

//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
b = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || false) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it 6 (binary 0110).
//This is the "bitwise complement" operator, which performs a !(not) on each bit.
(~(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5)
{
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Multiple conditions are also possible in pawn:
<pawn>//Example of an multiple switch statement
switch (a)
{
case 1, 2, 3:
{
//This code will run if a is equal to 1 or 2 or 3
}

case 4, 5, 6:
{
//This code will run if a is equal to 4 or 5 or6
}

case 7, 8, 9:
{
//This code will run if a is equal to 7 or 8 or 9
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
You could use the switch statement also for ranges:
<pawn>//Example of an range switch statement
switch (a)
{
case 0 .. 50:
{
//This code will run if 0 <= a <= 50
}

case 51 .. 100:
{
//This code will run if 51 <= a <= 100
}

case 101 .. 200:
{
//This code will run if 101 <= a <= 200
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [2][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = HELLO</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

You can also change the control character( amxx std: '^' )
<pawn>#pragma ctrlchar '\'
//this sets the control character to backslash( c/c++/c#/java/... std )
// now you have to use the \ instead of ^
// e.g. "this is ^":D^" " must be now " this is \":D\" "</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

AMX Mod X 1.8.0 Changes

2007-08-09T08:21:14Z

Greenberet: /* Scripting Changes */

AMX Mod X 1.8 is a large feature release with many changes, both to the development API and user-mode features.

=Changelog=
==Overall Changes==
*Added a new module, Ham Sandwich, for hooking virtual CBaseEntity functions in mods.
*Command flags are now initially dumped to disk and can be edited via <tt>configs/cmdaccess.ini</tt>.
*Added {{AMBug|48738}}: Romanian translation from X-5173.
*Added {{AMBug|50741}} and {{AMBug|43830}}: per-map plugins files can now be prefixed based.
*Added {{amb|17}}: New menu rendering is now more consistent; non-consistent controls are deprecated.
*Added {{amb|32}}: The server console commands "amxx cvars" and "amxx cmds" can now filter by plugin.
*Added {{amb|122}}: Log file names now include a four-digit year.
*Fixed {{amb|18}}: New menus are now properly destroyed if overridden.
*Fixed {{amb|46}}: <tt>is_user_bot</tt> had some false positives.
*Fixed {{amb|69}}: Fixed Metamod trying to reload AMX Mod X against a poorly configured clock.
*Fixed {{amb|207}}: New menus now display "0" instead of "10."
*Fixed {{amb|208}}: New menus did not reset callback results after each call.
*Fixed {{amb|200}}: Dynamic/fake natives were not re-entrant.
*Fixed {{amb|244}}: Run-time errors blocked forwards.
*Fixed {{amb|305}}: Core crashed on mods that removed the standard <tt>mp_timelimit</tt> cvar.
*Fixed many various internal new menu rendering and item selection bugs.
==Scripting Changes==
*Added natives for dynamic global arrays.
*Added a new, magic <tt>any</tt> tag from [[SourceMod]].
*Added a <tt>charsmax</tt> makro for safe sizeof(string)-1 usage.
*Added <tt>set_pcvar_string</tt>().
*Added <tt>LookupLangKey</tt>().
*Added <tt>SQL_QuoteString</tt>().
*Added <tt>[g|s]et_pdata_cbase[_safe]</tt>() to the Ham Sandwich module.
*Added <tt>geoip_code[2|3]_ex</tt>(), which address a serious issue in the now deprecated <tt>geoip_code[2|3]</tt>().
*Added <tt>lookup_sequence</tt>(), <tt>set_controller</tt>(), <tt>set_pev_string</tt>(), and <tt>pev_serial</tt>() to Fakemeta.
*Added <tt>ns_get_user_team</tt>.
*Added a menu property to change the numbering color.
*Added {{amb|27}}: <tt>SQL_Rewind</tt>().
*Added {{amb|37}}: <tt>cs_[g|s]et_user_submodel</tt>().
*Added {{amb|38}}: <tt>cs_[g|s]et_user_lastactivity</tt>().
*Added {{amb|39}}: <tt>cs_[g|s]et_hostage_lastuse</tt>() and <tt>cs_[g|s]et_hostage_nextuser</tt>().
*Added {{amb|63}}: <tt>floatmin</tt>(), <tt>floatmax</tt>(), and <tt>floatclamp()</tt>.
*Added {{amb|76}}: Formatting functions can now use %x or %X for hexadecimal numbers.
*Added {{amb|92}}: <tt>create_tr2</tt>() and <tt>free_tr2</tt>().
*Added {{amb|205}}: <tt>cs_[g|s]et_c4_explode_time</tt>().
*Added {{amb|216}}: <tt>SQL_MakeStdTuple</tt>() now has a timeout parameter.
*Added {{amb|237}}: Fakemeta can now call "ServerPrint."
*Added {{amb|242}}: <tt>cs_[g|s]et_user_hostagekills</tt>().
*Added {{amb|245}}: <tt>precache_sound</tt> now returns a precache index.
*Added {{amb|261}}: <tt>has_flag</tt>() and <tt>has_all_flags</tt>().
*Added {{amb|291}}: <tt>cs_[g|s]et_c4_defusing</tt>().
*Added {{amb|673}}: <tt>regex_compile</tt>() and <tt>regex_match_c</tt> for pre-compiling expressions.
*Added {{AMBug|46213}}: <tt>player_menu_info</tt>() now returns a page number.
*Added {{AMBug|51064}}: Some parameters to <tt>get_plugin</tt> are now optional.
*Added {{AMBug|50610}}: Some parameters to <tt>get_user_weapon</tt> are now optional.
*Added {{AMBug|48841}}: <tt>tfc_is_user_feigning</tt>().
*Added {{AMBug|45664}}: <tt>tfc_is_team_ally</tt>().
*Fixed {{AMBug|49337}}: <tt>get_pcvar_float</tt>() malfunctioned on high numbers.
*Fixed {{amb|78}}: <tt>get_concmdsnum</tt> could return an incorrect result.
*Fixed {{amb|85}}: Tag mismatches on <tt>ShowSyncHudMsg</tt>().
*Fixed {{amb|90}}: <tt>set_native_filter</tt>() did not work in rare cases.
*Fixed {{amb|107}}: <tt>socket_open</tt>() didn't return an error by reference.
*Fixed {{amb|110}}: <tt>socket_change</tt>() could return 1 on certain failures.
*Fixed {{amb|116}}: <tt>DispatchKeyValue</tt>() did not work on worldspawn (entity 0).
*Fixed {{amb|149}}: <tt>register_event</tt> with the "e" flag could catch incorrect players.
*Fixed {{amb|230}}: <tt>radius_damage</tt>() didn't kill players on all mods.
*Fixed {{amb|257}}: <tt>get_user_origin</tt>() mode 4 had false positives.
*Fixed {{amb|343}}: <tt>TFC_ClearModel</tt>() did not function as documented.
*Fixed {{amb|421}}: <tt>get_user_weapons</tt>() could omit a weapon on Day of Defeat.
*Fixed {{amb|437}}: <tt>dod_set_user_kills</tt>() and <tt>dod_set_user_score</tt>() could mess up the scoreboard.
*Fixed {{amb|519}}: <tt>geoip_code[2|3]</tt>() buffer overflowed on error.
*Fixed {{amb|736}}: <tt>find_entity</tt>() was defined twice.
*Fixed a memory leak in <tt>SortCustom1D</tt>().
*Fixed a crash bug in <tt>fwrite_blocks</tt>().

==Plugin Changes==
*There is no longer a hardcoded limit to the number of admins.
*There is no longer a hardcoded limit to the map list.
*There is no longer a hardcoded limit to the number of "imessages."
*Added {{amb|34}}: There are now plugin command/cvar menus.
*Added {{AMBug|45044}}: amx_banmenu now prints the ban time length.
*Added {{AMBug|43757}}: amx_addadmin now writes a comment with the player's name.
*Added {{AMBug|29353}}: amx_plugins now prints paginated output.
*Added {{AMBug|50742}}: admin.sma now supports prefix based per-map configs.
*Added {{amb|28}}: statscfg.sma can now use translations.
*Added {{amb|30}}: <tt>csstats_rankbots</tt> prevents bots from showing on <tt>/top15</tt>.
*Added {{amb|31}}: plmenu.sma ban and slap options are now configurable.
*Added {{amb|42}}: Added new values for <tt>amx_show_activity</tt>.
*Added {{amb|51}}: amx_vote can now take more than two options.
*Added {{amb|64}}: amx_voteban autodetects whether it should IP ban.
*Added {{amb|307}}: amx_addban now caches the last ten connections.
*Added {{amb|311}}: mapcycle file now ignores .bsp extensions.
*Added {{amb|340}}: amx_ban/amx_banip now display a reason in the activity.
*Added {{amb|427}}: Additional weapons to <tt>dod_[g|s]et_user_ammo</tt>().
*Fixed {{amb|29}}: pausecfg.sma did not translate two phrases.
*Fixed {{amb|91}}: miscstats.sma truncated some language translations.
*Fixed {{amb|94}}: amx_psay sometimes sent truncated messages.
*Fixed {{amb|109}}: mapsmenu.sma now checks <tt>mapcyclefile</tt> before reverting to <tt>mapcycle.txt</tt>.
*Fixed {{amb|118}}: amx_help would not list <tt>ADMIN_ADMIN</tt> commands.
*Fixed {{amb|130}}: Various menus did not take <tt>ADMIN_ALL</tt> or <tt>ADMIN_ADMIN</tt> into account.
*Fixed {{amb|183}}: plmenu.sma did not work on Natural Selection.
*Fixed {{amb|196}}: amx_modules did not handle invalid modules properly.
*Fixed {{amb|222}}: cl_rebuy could exploit CS weapon restrictions. This also makes CZ bots obey restrictions.
*Fixed {{amb|228}}: amxmod_compat could cause <tt>set_user_hitzones</tt>() to break.
*Fixed {{amb|350}}: <tt>traceline_set_float</tt> from the AMX Mod Compat layer was broken.
*Fixed {{amb|467}}: <tt>conmotd.txt</tt> is now removed.
*Fixed {{amb|633}}: Immune admins can now target themselves.
*Fixed a potential exploit in adminslots.sma.
*SQL cvars are now protected.
*Added {{amb|743}}: plmenu for cstrike has an option to move to spectator.

==Module Changes==
*Fixed {{amb|108}}: IP-based stats no longer include a port when saving.
*Fixed {{amb|503}}: CSX did not set a META_RESULT when paused.

AMX Mod X 1.75 Scripting Changes

2006-06-10T19:14:02Z

Greenberet: /* New Engine/GameDLL Functions */

The AMX Mod X 1.75 release made important changes. While backwards compatibility was kept, intended functionality shifted in esoteric areas that will affect some plugins. Reading this article is highly recommended.

=Module Requirement System=
As part of the new Automatic Module Loading, the old <tt>#pragma library</tt> has been deprecated. You must now use:
<pawn>#pragma reqlib <library>
</pawn>
This means "require library". Plugins still compiled with <tt>#pragma library</tt> will still fail on load if the given module is not found. However, core will try to load each module given the rules below under "Automatic Module Loading".

=Auto Plugin Files=
With the introduction of callfunc and register_native, many people now distribute plugins in large sets. To make this easier on users, you can now distribute an "extended plugin file." For example, say you have five plugins in a set. Normally, you would have to ask the user to write each name into plugins.ini, like so:
<pre>
file1.amxx ;file1
file2.amxx ;file2
file3.amxx ;file3
file4.amxx ;file4
file5.amxx ;file5
</pre>

With AMX Mod X 1.75, any file in the configs folder which follows a certain name pattern will be auto-loaded as an additional plugins.ini file. The pattern is: plugins-*.ini.

For example, you could distribute <tt>plugins-carmod.ini</tt> as:
<pre>
;put a semi-colon to disable a plugin
cars_honda.amxx
cars_toyota.amxx
cars_ford.amxx
cars_bmw.amxx
cars_gaben.amxx
</pre>

This way, you can easily distribute an extractable install, rather than giving the user overcomplicated instructions. Furthermore, the file is easily disabled by simply modifying the name (for example, "disabled-carmod.ini").

=Automatic Module Loading=
==Overview==
As of AMX Mod X 1.75, there is a new, powerful automatic module loading system. That means that <tt>modules.ini</tt> is largely deprecated for general use. Instead, modules are loaded as plugins need them. This is done dynamically by core before plugins are even loaded, without the need to patch <tt>modules.ini</tt> and then change the map.

Modules can now define "Libraries" and "Library Classes". A library is a specific identifier that should match the filename of the module. For example, Engine's defined library is "engine". FakeMeta's library is "fakemeta", and so on.

A "library class" defines membership to a set of modules. For example, CSX has the library name "csx", but it is part of the library class "xstats". Library classes are also used for DBI and SQLX. This is very useful for being able to require one module type of any implementation.

==New API==
===Compiler Pragmas===
This is expanded with a number of new <tt>#pragma</tt> directives:
*<tt>#pragma reqlib <library></tt> - Requires that a given library must be loaded.
*<tt>#pragma reqclass <libclass></tt> - Requires that a given library class must be loaded.
*<tt>#pragma loadlib <library></tt> - Automatically attempts to load a given library (see more info below).
*<tt>#pragma expectlib <library1> <library2></tt> - If the first library is not loaded, the second one will be attempted to load (not very useful).
*<tt>#pragma expectclass <class> <library></tt> - If the expected class is not found, the given library will be attempted to load. This is useful for defining a default module to be loaded with a given class of modules.
*<tt>#pragma defclasslib <class> <library></tt> - Same as <tt>expectclass</tt>, however, <tt>defclasslib</tt> waits until all expectations are resolved. This lets plugins override defaults by adding their own expectations.

===Module Filtering===
The module_filter prototype now includes a second parameter, which tells you whether the requirement is a class or library.

Furthermore, module_exists has been deprecated for LibraryExists().

==How it Works==
The precise order of events is as follows:
*When the first entity is spawned, AMX Mod X loads all unloaded modules in <tt>modules.ini</tt>.
*After <tt>modules.ini</tt> is parsed, <tt>plugins.ini</tt> is read. Each file is mapped into a cache.
*The cache is previewed.
**First, the "library" table is read. This table is read for backwards compatibility with AMX Mod X 1.71 and prior. Each entry is read as a module file shortname, and the module is loaded if it exists.
**Next, the "pubtags" table is read. Each entry is decoded to one of the special #pragma commands.
***All loadlib commands are executed, and the modules loaded.
***All expect commands are executed.
***All defclasslib commands are executed.
*AMX Mod X then waits until ServerActivate is called.
*All plugins are loaded. If the plugin is in the cache, the cache is read instead. For each plugin...
**The library table is read. For each library that is both nonexistant and unhandled by a module filter, the plugin fails to load.
**The pubtags table is read. For each reqlib and reqclass entry that are both nonexistant and unhandled by a module filter, the plugin fails to load.
*The plugin cache is invalidated and the server is considered "loaded".

=SQLX=
==Introduction==
SQLX is a new Database API that supercedes DBI. Its main feature is that you can load two SQLX modules at once, whereas you cannot with DBI. It also supports threaded queries, which let you process data without interrupting gameplay from a bad network connection.

These additions come at a hefty price. The SQLX API is significantly more complex than DBI. Although some might find it easier to use due to its simpler error checking and iteration, it requires more manual memory management and has less simple abstraction. Furthermore, taking advantage of the new <tt>SQL_ThreadQuery</tt> native will require nothing short of a rewrite for most plugins, as it is ''asynchronous'' instead of ''synchronous''. Because of this, the new SQLX modules also implement the old DBI functionality, for both backwards compatibility and for plugin developers familiar with the old API. All three APIs - SQL-threaded, SQL-non-threaded, and DBI, are still fully supported.

==Usage==
Since SQLX is an expansive API, showing a single plugin of its usage would be difficult. It is highly recommended that users interested in the new API look at the [http://cvs.tcwonline.org/viewvc.cgi/amxmodx/plugins/testsuite/sqlxtest.sma?view=log SQLxTest] plugin, which compares two different DBI methods and both SQL methods of querying a database. It is highly useful for both regression testing and for getting an idea of how the API works.

The most important concept of SQLX is "Handles," which are a precursor to a system planned for SourceMod. Handles are datatypes that store internal information that you should not modify. Whenever you create a handle, you must also free it, with <tt>SQL_FreeHandle</tt>().

==Native Overview==
The basic natives of SQLX are:
*<tt>SQL_MakeDbTuple</tt> (or simple stock version, <tt>SQL_MakeStdTuple</tt>) - This creates a variable that holds information about a database. It does not connect to the database. This is so you don't have to keep retrieving cvar info on every connection. You do not have to free these handles, although it is a good idea if you create them dynamically.
*<tt>SQL_Connect</tt> - Connects to a database and returns a new Handle, or <tt>Empty_Handle</tt> on failure.
*<tt>SQL_PrepareQuery</tt> - Prepares a query for execution, and returns a new Handle to the query.
*<tt>SQL_Execute</tt> - Executes a prepared query, and returns 0 on failure (1 on success).
*<tt>SQL_MoreResults</tt> - Returns 1 if there are more results in the query result queue, 0 if none.</tt>
*<tt>SQL_ReadResult</tt> - Reads the current row result by the column's numerical index, similar to dbi_field/dbi_result.
*<tt>SQL_NextRow</tt> - Advances to the next result row. '''Compatibility Warning''': This does not need to be called first! Unlike <tt>dbi_nextrow</tt>, the query is automatically at the first row. If you call <tt>SQL_NextRow</tt> before <tt>SQL_ReadResult</tt>, your are actually skipping a row.
*<tt>SQL_FreeHandle</tt> - Frees a Handle. You must do this or else memory will leak.
*<tt>SQL_ThreadQuery</tt> - Places a query and connection info into a threaded queue. In another thread, the connection is established, the query is executed, and the connection is dropped. The query results are then posted back into the main thread and given to the plugin on the next server-frame.
**Note that while powerful, the mechanism is very simplistic. Similar to <tt>set_task</tt>, you must differentiate multiple queries having the same callback by packing binary data into an array. Furthermore, you can only make one query at a time, since the queue is "push one, resolve one, pop one." If you plan on making five queries in a row in order to get aggregate information about a player, you must make each of these five queries in separate stages, and you must also take into account asynchronous factors such as the player dropping during the middle of a query. (One way to do this is to pack the player's authid and client index into the callback data and verify it when the query finishes.)

=New Natives / Native Changes=
==Register Message==
The <tt>register_message</tt> set of natives, including <tt>get/set_msg_block</tt>, has been moved to Core. This is to facilitate users who prefer to use FakeMeta, and like the simplicity and speed of using Engine's message interception functions.
 
This change is backwards compatible.

==Argument Formatting==
The <tt>format_args</tt> function is now replaced with a much faster, more compatible <tt>vformat</tt> function. Its usage is slightly different (read the include file, <tt>string.inc</tt>), but it accepts %L, whereas format_args does not. A quick example:
<pawn>debugprint(const fmt[], ...)
{
static temp[2048]
vformat(temp, sizeof(temp)-1, fmt, 2)
log_message("[DEBUG] %s", temp)
}</pawn>

==Other Core Natives==
*<tt>register_plugin</tt> - Now returns a plugin id.
*<tt>get_amxx_verstring</tt> - Returns the AMX Mod X version string.
*<tt>get_weaponid</tt> - Gets a weapon id from a weapon name.

==FakeMeta==
===New Natives===
*<tt>get_orig_retval</tt> - Gets the original return value of an engine or game DLL function.
*<tt>copy_infokey_buffer</tt> - Copies the given infobuffer pointer into output buffer.
*<tt>get/set_cd</tt> - Gets or sets members of a clientdata data structure (used with UpdateClientData).
*<tt>get/set_es</tt> - Gets or sets members of an entity_state data structure (used with AddToFullPack).
*<tt>get/set_uc</tt> - Gets or sets members of a usecmd data structure (used with CmdStart).

===New Engine/GameDLL Functions===
The <tt>register_forward</tt> native now allows for hooking a number of new functions from the engine or game DLL including:
*<tt>UpdateClientData</tt>
*<tt>AddToFullPack</tt>
*<tt>CmdStart</tt>
*<tt>CmdEnd</tt>
*<tt>CreateInstBaselines</tt> - Game DLL function
*<tt>CreateInstBaseline</tt> - Engine function
*<tt>CreateBaseline</tt>
*<tt>GetInfoKeyBuffer</tt>
*<tt>AlertMessage</tt> - This now can be called via <tt>engfunc</tt>
*<tt>ClientPrintf</tt>

These functions can also be called via <tt>engfunc</tt> or <tt>dllfunc</tt>.

===Breaking Changes===
Using <tt>engfunc</tt> in order to call <tt>EngFunc_InfoKeyValue</tt>, <tt>EngFunc_SetKeyValue</tt>, or <tt>EngFunc_SetClientKeyValue</tt> now requires passing an infobuffer pointer. An infobuffer pointer can be obtained by calling <tt>EngFunc_GetInfoKeyBuffer</tt>. For example:
<pawn>some_function(id, name[])
{
new infokey = engfunc(EngFunc_GetInfoKeyBuffer, id)
engfunc(EngFunc_SetClientKeyValue, id, infokey, "model", name)
}</pawn>

If you hook ClientUserInfoChanged via Fakemeta, an infobuffer pointer is now also forwarded to your function in addition to the client id.

==Cstrike==
*<tt>cs_get_user_mapzones</tt> - Returns bitwise flags of where on the map a player is located such as buy zone, bomb site, hostage rescue zone, VIP safety zone, and escape zone.
*<tt>cs_set_user_vip</tt> - Now takes two additional (but optional) parameters for determining whether or not the player model and scoreboard get updated.

==New Stocks==
===Engine===
*<tt>IsInWorld</tt> - Checks if an entity is within the bounds of the world (from HLSDK).

===FakeMeta===
*<tt>DF_UpdateClientData</tt> - Calls UpdateClientData game DLL function.
*<tt>DF_AddToFullPack</tt> - Calls AddToFullPack game DLL function.
*<tt>DF_CmdStart</tt> - Calls CmdStart game DLL function.
*<tt>DF_CmdEnd</tt> - Calls CmdEnd game DLL function.
*<tt>DF_CreateBaseline</tt> - Calls CreateBaseline game DLL function.
*<tt>DF_CreateInstBaselines</tt> - Calls CreateInstancedBaselines game DLL function.
*<tt>EF_CreateInstBaseline</tt> - Calls CreateInstancedBaseline engine function.
*<tt>EF_GetInfoKeyBuffer</tt> - Calls GetInfoKeyBuffer engine function.
*<tt>EF_ClientPrintf</tt> - Calls ClientPrintf engine function.

==New Constants==
Various sound constants (<tt>SND_SPAWNING</tt>, <tt>SND_STOP</tt>, <tt>SND_CHANGE_VOL</tt>, and <tt>SND_CHANGE_PITCH</tt>) from the HL SDK as well as a constant for pi were added to <tt>amxconst.inc</tt>. <tt>TE_*</tt> (temp entity) message constants have also been added which will automatically be included with <tt>#include <amxmodx></tt>. And finally, a new <tt>hlsdk_const.inc</tt> file has been added that contains many more constants from the SDK. This is automatically included with <tt>#include <engine></tt> or <tt>#include <fakemeta></tt>.

=Module API=
The AMX Mod X module API received a small overhaul for 1.75.

==Versioning/Interface Additions==
The internal module interface version is 4. However, modules from M/SDK 3 will still load.

M/SDK Version 4 modules have two new members of public information: the library string, and the library class string. These contain comma delimited names of whatever libraries or library classes the module would like to be registered.

For backwards compatibility, M/SDK Version 4 modules have an automatically empty library class string, and a library string equal to the logtag string.

==New Callbacks==
Modules can now be informed of when plugins are about to be unloaded, and when plugins have been fully unloaded. This means that modules don't have to hook ServerActivate and ServerActivate_Post (implementation dependent), don't need to be loaded by Metamod, and don't need to detach simply to release resources.

==New Functions==
*<tt>MF_GetLocalInfo</tt> - Intended for modules using LOCALINFO, which required a Metamod attachment. This is equal to AMX Mod X's core function <tt>get_localinfo</tt>.
*<tt>MF_OverrideNatives</tt> - Given a native list, this specifies that any other module already providing these natives will no longer provide them. This was added to force backwards compatibility between SQLITE and MySQLX. Usage is not recommended.
*<tt>MF_FindLibrary</tt> - Essentially the same function as LibraryExists() for plugins.
*<tt>MF_AddLibraries</tt> - Adds a comma delimited list of libraries or library classes. You must specify a "parent" pointer that identifies the module. This is easily accomplished by taking the address of any static variable.
*<tt>MF_RemoveLibraries</tt> - Removes all library entries with the given parent pointer. This is useful if your module adds custom entries not in its defined list.

==MSVC8 Compatibility==
M/SDK Version 4 now contains preprocessor definitions for compatibility with Microsoft's Visual Studio 2005/8.0 (provided by [[User:Damaged Soul|Damaged Soul]]). These macros can be turned off in the <tt>moduleconfig.h</tt> file by uncommenting the definition of <tt>NO_MSVC8_AUTO_COMPAT</tt>.

=Minor Changes=
==Compiler Defines==
Since <tt>__DATE__</tt> was fixed in 1.75, the macro <tt>__TIME__</tt> was also added.

=Full Changelog=
This changelog is tentative. Developers will be editing it as things are changed.

* Core Changes
** Modules are now automatically loaded by detecting plugin usage.
*** modules.ini is now primarily deprecated, except for SQL and unsupported libraries.
** Rewrote SQLX modules (again). You can now load multiple SQL modules and toggle them per-plugin.
*** Added new SQL API called SQLX. DBI was kept backwards-compatible.
*** Added new function to thread SQL queries (which prevents lag from a bad connection).
** Fixed some very small memory leaks.
** Fixed binary logging building wrong on Linux.
** Fixed some debugging crashes.
** Fixed serious bug when creating plugin_pause/plugin_unpause forwards.
** Fixed serious crash bug involving set_hudmessage and plugins using high hudchannels.
** Added natives:
*** fputs()
*** get_weaponid()
*** rename_file()
*** vformat()
** Any file starting with "plugins-" and ending in ".ini" will now be treated as an extended plugins file. This is useful for distributing sets of plugins separately, and easily disabling them with a name change.

* Fakemeta Changes
** Added new hookable/callable functions:
*** AddToFullPack
*** AlertMessage
*** ClientPrintf
*** ClientUserInfoChanged
*** CmdEnd
*** CmdStart
*** CreateBaseline
*** CreateInstancedBaseline
*** GetInfoKeyBuffer
*** InfoKeyValue
*** UpdateClientData
*** SetClientKeyValue
*** SetKeyValue
** Added new natives:
*** copy_infokey_buffer
*** get_orig_retval
** Fixed various trace bugs in FakeMeta with certain natives.
** Fixed some unhooking on server-deactivate problems in FakeMeta.

* Scripting Changes:
** Added __DATE__ and __TIME__ auto-macros to the compiler.
** Added many HLSDK constants and improved include organization.
** Added new compiler #pragma directives for using the module autoloading system.
** Added cs_get_user_mapzones (thanks VEN!).
** Added IsInWorld() stock (thanks Twilight Suzuka!).
** Added nvault_remove().
** Moved various natives from Engine and into Core:
*** register_message
*** get_msg_args
*** get/set_msg_arg_type
*** get/set_msg_arg_int
*** get/set_msg_arg_float
*** get/set_msg_arg_string
*** get_msg_origin
*** get/set_msg_block
*** velocity_by_aim
*** vector_to_angle
*** angle_vector
*** vector_length
*** vector_distance
*** precache_generic
** Dynamic natives that are paused now also pause parent plugins (with an error).
** register_plugin() now returns the plugin ID.
** Fixed a corruption bug in strip_user_weapons().
** Fixed a bug in set_view() (thanks jtp10181!).
** Fixed is_in_viewcone() always returning 0.
** Fixed is_visible causing a crash, improved accuracy.
** Fixed a crash bug in get_tr2() (thanks Orangutanz!).
** Fixed cs_get_user_buyzone() returning existence in other areas.
** Fixed a rare floatround() bug where values ending strictly in .5 were IEEE rounded.
** Fixed a bug where removing the current parent task could damage the task queue.
** Fixed a bug in get_entity_visibility (thanks VEN!).
** Removed non-existant take_damage() entry.
** Expanded XS Stock Library with addition of xs_vec_make2d.
** Expanded usage of cs_set_user_vip().
** Improved get_brush_entity_origin() and ViewContents (thanks Orangutanz!).

* Plugin Changes:
** Added amx_showrcon command to show rcon results in admincmd.sma.
** Added weapon restriction compatibility for bots in CS (KWo).
** Added admin identifier (asterisk which is red if colors are available) to all menus with a user list.
** Upgraded admin.sma to the new SQLX API.
** Fixed a bug in amx_reloadadmins not giving admins new access.
** Fixed a weapon restriction exploit in restmenu.sma.
** Fixed an HTML exploit in /top15 displaying player names.
** Fixed various and plentiful amx_addadmin bugs.
** Fixed telemenu.sma not letting you teleport yourself (thanks jtp10181!).
** Fixed a bug with adminslots.sma lowering the slots by 1.
** Fixed overlapping hud messages with miscstats.

* Module API Changes:
** Added and fixed module API for inter-module communication.
** Added native overriding and replacing to module API.
** Added plugin unloading/unloaded callbacks to module API.
** Added MSVC8 project files to most CVS projects.

* Configuration Changes:
** Added amx_sql_type cvar to sql.cfg.
** Re-organized and simplified modules.ini.
** Error logging can now be redirected to separate logs.
** Fixed modules.ini parsing bugs and simplified parsing.
** Fixed a double entry in cvars.ini.

* Other Changes:
** Added a Bulgarian translation (thanks lubb!).
** Added a leetspeak translation (thanks, I think, Twilight Suzuka!).
** Improved FTP option of the graphical installer.
** Updated the GeoIP library to June.
** Updated PCRE from v6.1 to v6.4.
** Updated sqLite from 3.3.4 to 3.3.5.
** Fixed a steam account path bug in the installer.

[[Category:AMX Mod X]]

Pawn Tutorial

2006-03-26T08:22:45Z

Greenberet: /* Compiler Pre-processor Directives */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3
new z = 1_000_000 // Pawn supports numbers like this. So big values are easier to read.</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || false) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it 6 (binary 0110).
//This is the "bitwise complement" operator, which performs a !(not) on each bit.
(~(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5)
{
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Multiple conditions are also possible in pawn:
<pawn>//Example of an multiple switch statement
switch (a)
{
case 1, 2, 3:
{
//This code will run if a is equal to 1 or 2 or 3
}

case 4, 5, 6:
{
//This code will run if a is equal to 4 or 5 or6
}

case 7, 8, 9:
{
//This code will run if a is equal to 7 or 8 or 9
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
You could use the switch statement also for ranges:
<pawn>//Example of an range switch statement
switch (a)
{
case 0 .. 50:
{
//This code will run if 0 <= a <= 50
}

case 51 .. 100:
{
//This code will run if 51 <= a <= 100
}

case 101 .. 200:
{
//This code will run if 101 <= a <= 200
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = HELLO</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

You can also change the control character( amxx std: '^' )
<pawn>#pragma ctrlchar '\'
//this sets the control character to backslash( c/c++/c#/java/... std )
// now you have to use the \ instead of ^
// e.g. "this is ^":D^" " must be now " this is \":D\" "</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

Pawn Tutorial

2006-03-26T08:20:36Z

Greenberet: /* Switch Statements */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3
new z = 1_000_000 // Pawn supports numbers like this. So big values are easier to read.</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || false) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it 6 (binary 0110).
//This is the "bitwise complement" operator, which performs a !(not) on each bit.
(~(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5)
{
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Multiple conditions are also possible in pawn:
<pawn>//Example of an multiple switch statement
switch (a)
{
case 1, 2, 3:
{
//This code will run if a is equal to 1 or 2 or 3
}

case 4, 5, 6:
{
//This code will run if a is equal to 4 or 5 or6
}

case 7, 8, 9:
{
//This code will run if a is equal to 7 or 8 or 9
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
You could use the switch statement also for ranges:
<pawn>//Example of an range switch statement
switch (a)
{
case 0 .. 50:
{
//This code will run if 0 <= a <= 50
}

case 51 .. 100:
{
//This code will run if 51 <= a <= 100
}

case 101 .. 200:
{
//This code will run if 101 <= a <= 200
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = {HELLO}</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

You can also change the control character( amxx std: '^' )
<pawn>#pragma ctrlchar '\'
//this sets the control character to backslash( c/c++/c#/java/... std )
// now you have to use the \ instead of ^
// e.g. "this is ^":D^" " must be now " this is \":D\" "</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

Intro to AMX Mod X Scripting

2006-02-26T22:10:20Z

Greenberet: /* Building Admin Commands */

This guide will give you a basic overview to scripting [[AMX Mod X]] plugins.

=Overview=

So you want to create a plugin? You should have a good understand of how Pawn works, so make sure Sections 0 and 1 of this manual make perfect sense to you. You should be reading this portion of the document, sitting at a computer, with a text editor and small compiler at hand. Doing this interactively helps learning. You won't be writing plugins like WC3, Matrix Mod, and CSDM right away, but this is meant to give you a kick start to the modding world of AMX Mod X. For a good text editor that is AMX Pawn enabled, try Crimson Editor (it's free as in beer): http://www.crimsoneditor.com/

You should get familiar with compiling plugins. Refer to the "[[Compiling Plugins (AMX Mod X)|Compiling Plugins]]" section of the AMX Mod X Documentation, as it will not be provided here. You should also be familiar with adding new plugins, so you can test your plugins out.

=Beginning=

An AMX Mod X plugin can have four main types of functions. The first is a "public" function. This means it is publically viewable to the AMX Mod X engine. The second is a "native" function, which is declared in a module or the AMX Mod X Core. The third is a regular user function, which is declared without any special attributes. The fourth is a "forward" function, which is called whenever a special event occurs (a forward is also public). An AMX Mod X plugin must begin with a function initializing the plugin:

<pawn>//This makes it so you can use the core AMX Mod X functions
//It "includes" the native definitions from includes\amxmodx.inc
#include <amxmodx>

//Declare three string variables
new PLUGIN[]="AMXX Demo"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

//This is a public function.
//It is necessary to initialize your script under AMX Mod X.
//It takes no parameters, and is called right after map load.
public plugin_init()
{
//This is a function that takes three strings.
//It registers your function in AMX Mod X, and assigns some basic information.
register_plugin(PLUGIN, VERSION, AUTHOR)
}
</pawn>

Try compiling the script above. It will be very small - as it does nothing so far. However, if you load this script, and type "amxx plugins", you should see the new entry on the list.

=Building Admin Commands=

AMX Mod X provides a way to easily add console admin commands. Each command is "registered" as a console command. When you register a command, you must define four properties: The console command that is typed in, the function you are making that interprets the command, the access level required to use it, and a short description of the command.

For this demonstration, let's build a plugin that lets you change the health of players on the server with the command "amx_hp".

We'll need to do two things to start off - first, we need to register the command in the console. As we are binding a command to a public function, we must then make sure that function exists.

<pawn>#include <amxmodx>
#include <amxmisc> //This contains some useful functions
#include <fun> //This contains the function to change health

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> ")
}

public cmd_hp(id, level, cid)
{
return PLUGIN_HANDLED
}</pawn>

The first new function is "register_concmd", which takes four parameters. The first is the command that a player must type into their console. The second is the public function that will handle the command. The third is the access level your command needs. Lastly, you can pass a string that describes how to use your command (for amx_help).

Next, we have created a public function to handle the amx_hp command. Note that we are giving it three parameters. These parameters will hold special data when the command is used - id will hold the player's id who started the command, level will hold the access level of the command (you must do access checking yourself), and cid will hold the command's internal id.

Also, note PLUGIN_HANDLED. There are two main return values you should concern yourself with. PLUGIN_CONTINUE generally means "continue with normal operation", and PLUGIN_HANDLED means "block further operation". The differences are subtle but important. For example, when binding a command, you should never return PLUGIN_CONTINUE. But if you return PLUGIN_HANDLED while binding to the "say" command, it will block the player's text from ever appearing. You must be careful with which you choose in certain situations. However, most things are unaffected (such as tasks, events, and other things you will run into later on).

So, first things first. How do we make sure this user is an admin who has ADMIN_SLAY access?

<pawn>public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED
return PLUGIN_HANDLED
}</pawn>

The cmd_access() function will check a command's information (user, access level, and id) and makes sure of two things: that the user has access to it, and that it was given a minimum number of parameters. Here we passed three, because the command will look like this: amx_hp <target> <amount>, and the actual command itself counts as a parameter. If cmd_access fails, we have the command immediately end.

The next portion to solve is: we need to take the two parameters and decode them. The "amount" parameter is easy, as we just convert it from a string to a number. The second parameter will be trickier, as we want to be able to target three different types of people:

* @CT or @T - CTs or Ts
* @ALL - Everyone
* <target> - Partial name of a player

<pawn>public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Get the command arguments from the console
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Convert the health from a string to a number
new Health = str_to_num(Arg2)

//Is the first character the @ symbol?
if (Arg1[0] == '@')
{
new Team = 0
//Check which team was specified.
//Note that we start from [1], this is okay
// it just means the @ isn't included
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
//This function will fill the players[32] variable
// with valid player ids. num will contain the number
// of players that are valid.
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
//Set this player's health
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
//finds a player id that matches the partial name given
//the 1 means that it will not target the player if he
// has immunity access
new player = cmd_target(id, Arg1, 1)
if (!player)
{
//this will print a message to the user who tried the command
//The format for this command is called "format()" style,
// where the first string formats the message according
// to any number of following parameters.
// %s means a string
// %d or %i means an integer
// %f means a float
// so "Hello %s, I am %d years old" will
// require a string and integer to follow
console_print(id, "Sorry, player %s could not be found or targetted!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}</pawn>

So, our final stripped amx_hp plugin will look like:

<pawn>#include <amxmodx>
#include <fun>

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> <hp>")
}

public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Get the command arguments from the console
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Convert the health from a string to a number
new Health = str_to_num(Arg2)

//Is the first character the @ symbol?
if (Arg1[0] == '@')
{
new Team = 0
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
new player = cmd_target(id, Arg1, 1)
if (!player)
{
console_print(id, "Sorry, player %s could not be found or targetted!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}</pawn>

=CVARs=

CVARs are server-side storage keys. For example, "mp_startmoney" is the Counter-Strike CVAR to hold how much money people get when they join the game. You can make your own CVARs by registering them in plugin_init(). Let's replicate mp_startmoney.

<pre>
#include <amxmodx>

public plugin_init()
{
register_plugin("CVAR Test", "1.0", "BAILOPAN")
//set default value to 500
register_cvar("amx_startmoney", "500")
}

//this occurs when a client is put in game
public client_putinserver(id)
{
if (get_cvar_num("amx_startmoney") > 0)
{
cs_set_user_money(id, get_cvar_num("amx_startmoney"))
} else {
cs_set_user_money(id, get_cvar_num("mp_startmoney"))
}
}
</pre>

(this plugin probably won't work, it's just a demonstration). You can set CVARs as floats, numbers, or strings, and you can modify just about any valid CVAR from the HL engine or mod.

=Finding More=

To learn more about scripting for AMX Mod X, you should look through the natives in the function reference or the include files. Include files generally follow two formats. They are named after a module or specific purpose. _const is appended if they contain pre-defined numbers or lists. _stocks is appended if they contain helper or useful wrapping functions. Remember, stocks are only compiled if you use them, so it is safe to include an include file with many stocks.

You can also visit the [http://www.amxmodx.org/forums/ Forums] and ask questions, or read how other people achieved certain goals to learn and innovate.

[[Category:Scripting (AMX Mod X)]]

Intro to AMX Mod X Scripting

2006-02-26T22:08:36Z

Greenberet: /* Beginning */

This guide will give you a basic overview to scripting [[AMX Mod X]] plugins.

=Overview=

So you want to create a plugin? You should have a good understand of how Pawn works, so make sure Sections 0 and 1 of this manual make perfect sense to you. You should be reading this portion of the document, sitting at a computer, with a text editor and small compiler at hand. Doing this interactively helps learning. You won't be writing plugins like WC3, Matrix Mod, and CSDM right away, but this is meant to give you a kick start to the modding world of AMX Mod X. For a good text editor that is AMX Pawn enabled, try Crimson Editor (it's free as in beer): http://www.crimsoneditor.com/

You should get familiar with compiling plugins. Refer to the "[[Compiling Plugins (AMX Mod X)|Compiling Plugins]]" section of the AMX Mod X Documentation, as it will not be provided here. You should also be familiar with adding new plugins, so you can test your plugins out.

=Beginning=

An AMX Mod X plugin can have four main types of functions. The first is a "public" function. This means it is publically viewable to the AMX Mod X engine. The second is a "native" function, which is declared in a module or the AMX Mod X Core. The third is a regular user function, which is declared without any special attributes. The fourth is a "forward" function, which is called whenever a special event occurs (a forward is also public). An AMX Mod X plugin must begin with a function initializing the plugin:

<pawn>//This makes it so you can use the core AMX Mod X functions
//It "includes" the native definitions from includes\amxmodx.inc
#include <amxmodx>

//Declare three string variables
new PLUGIN[]="AMXX Demo"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

//This is a public function.
//It is necessary to initialize your script under AMX Mod X.
//It takes no parameters, and is called right after map load.
public plugin_init()
{
//This is a function that takes three strings.
//It registers your function in AMX Mod X, and assigns some basic information.
register_plugin(PLUGIN, VERSION, AUTHOR)
}
</pawn>

Try compiling the script above. It will be very small - as it does nothing so far. However, if you load this script, and type "amxx plugins", you should see the new entry on the list.

=Building Admin Commands=

AMX Mod X provides a way to easily add console admin commands. Each command is "registered" as a console command. When you register a command, you must define four properties: The console command that is typed in, the function you are making that interprets the command, the access level required to use it, and a short description of the command.

For this demonstration, let's build a plugin that lets you change the health of players on the server with the command "amx_hp".

We'll need to do two things to start off - first, we need to register the command in the console. As we are binding a command to a public function, we must then make sure that function exists.

<pre>
#include <amxmodx>
#include <amxmisc> //This contains some useful functions
#include <fun> //This contains the function to change health

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> ")
}

public cmd_hp(id, level, cid)
{
return PLUGIN_HANDLED
}
</pre>

The first new function is "register_concmd", which takes four parameters. The first is the command that a player must type into their console. The second is the public function that will handle the command. The third is the access level your command needs. Lastly, you can pass a string that describes how to use your command (for amx_help).

Next, we have created a public function to handle the amx_hp command. Note that we are giving it three parameters. These parameters will hold special data when the command is used - id will hold the player's id who started the command, level will hold the access level of the command (you must do access checking yourself), and cid will hold the command's internal id.

Also, note PLUGIN_HANDLED. There are two main return values you should concern yourself with. PLUGIN_CONTINUE generally means "continue with normal operation", and PLUGIN_HANDLED means "block further operation". The differences are subtle but important. For example, when binding a command, you should never return PLUGIN_CONTINUE. But if you return PLUGIN_HANDLED while binding to the "say" command, it will block the player's text from ever appearing. You must be careful with which you choose in certain situations. However, most things are unaffected (such as tasks, events, and other things you will run into later on).

So, first things first. How do we make sure this user is an admin who has ADMIN_SLAY access?

<pre>
public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED
return PLUGIN_HANDLED
}
</pre>

The cmd_access() function will check a command's information (user, access level, and id) and makes sure of two things: that the user has access to it, and that it was given a minimum number of parameters. Here we passed three, because the command will look like this: amx_hp <target> <amount>, and the actual command itself counts as a parameter. If cmd_access fails, we have the command immediately end.

The next portion to solve is: we need to take the two parameters and decode them. The "amount" parameter is easy, as we just convert it from a string to a number. The second parameter will be trickier, as we want to be able to target three different types of people:

* @CT or @T - CTs or Ts
* @ALL - Everyone
* <target> - Partial name of a player

<pre>
public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Get the command arguments from the console
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Convert the health from a string to a number
new Health = str_to_num(Arg2)

//Is the first character the @ symbol?
if (Arg1[0] == '@')
{
new Team = 0
//Check which team was specified.
//Note that we start from [1], this is okay
// it just means the @ isn't included
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
//This function will fill the players[32] variable
// with valid player ids. num will contain the number
// of players that are valid.
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
//Set this player's health
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
//finds a player id that matches the partial name given
//the 1 means that it will not target the player if he
// has immunity access
new player = cmd_target(id, Arg1, 1)
if (!player)
{
//this will print a message to the user who tried the command
//The format for this command is called "format()" style,
// where the first string formats the message according
// to any number of following parameters.
// %s means a string
// %d or %i means an integer
// %f means a float
// so "Hello %s, I am %d years old" will
// require a string and integer to follow
console_print(id, "Sorry, player %s could not be found or targetted!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}
</pre>

So, our final stripped amx_hp plugin will look like:

<pre>
#include <amxmodx>
#include <fun>

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> <hp>")
}

public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Get the command arguments from the console
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Convert the health from a string to a number
new Health = str_to_num(Arg2)

//Is the first character the @ symbol?
if (Arg1[0] == '@')
{
new Team = 0
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
new player = cmd_target(id, Arg1, 1)
if (!player)
{
console_print(id, "Sorry, player %s could not be found or targetted!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}
</pre>

=CVARs=

CVARs are server-side storage keys. For example, "mp_startmoney" is the Counter-Strike CVAR to hold how much money people get when they join the game. You can make your own CVARs by registering them in plugin_init(). Let's replicate mp_startmoney.

<pre>
#include <amxmodx>

public plugin_init()
{
register_plugin("CVAR Test", "1.0", "BAILOPAN")
//set default value to 500
register_cvar("amx_startmoney", "500")
}

//this occurs when a client is put in game
public client_putinserver(id)
{
if (get_cvar_num("amx_startmoney") > 0)
{
cs_set_user_money(id, get_cvar_num("amx_startmoney"))
} else {
cs_set_user_money(id, get_cvar_num("mp_startmoney"))
}
}
</pre>

(this plugin probably won't work, it's just a demonstration). You can set CVARs as floats, numbers, or strings, and you can modify just about any valid CVAR from the HL engine or mod.

=Finding More=

To learn more about scripting for AMX Mod X, you should look through the natives in the function reference or the include files. Include files generally follow two formats. They are named after a module or specific purpose. _const is appended if they contain pre-defined numbers or lists. _stocks is appended if they contain helper or useful wrapping functions. Remember, stocks are only compiled if you use them, so it is safe to include an include file with many stocks.

You can also visit the [http://www.amxmodx.org/forums/ Forums] and ask questions, or read how other people achieved certain goals to learn and innovate.

[[Category:Scripting (AMX Mod X)]]

Intro to AMX Mod X Scripting

2006-02-26T22:08:09Z

Greenberet: /* Beginning */

This guide will give you a basic overview to scripting [[AMX Mod X]] plugins.

=Overview=

So you want to create a plugin? You should have a good understand of how Pawn works, so make sure Sections 0 and 1 of this manual make perfect sense to you. You should be reading this portion of the document, sitting at a computer, with a text editor and small compiler at hand. Doing this interactively helps learning. You won't be writing plugins like WC3, Matrix Mod, and CSDM right away, but this is meant to give you a kick start to the modding world of AMX Mod X. For a good text editor that is AMX Pawn enabled, try Crimson Editor (it's free as in beer): http://www.crimsoneditor.com/

You should get familiar with compiling plugins. Refer to the "[[Compiling Plugins (AMX Mod X)|Compiling Plugins]]" section of the AMX Mod X Documentation, as it will not be provided here. You should also be familiar with adding new plugins, so you can test your plugins out.

=Beginning=

An AMX Mod X plugin can have four main types of functions. The first is a "public" function. This means it is publically viewable to the AMX Mod X engine. The second is a "native" function, which is declared in a module or the AMX Mod X Core. The third is a regular user function, which is declared without any special attributes. The fourth is a "forward" function, which is called whenever a special event occurs (a forward is also public). An AMX Mod X plugin must begin with a function initializing the plugin:

<pawn>
//This makes it so you can use the core AMX Mod X functions
//It "includes" the native definitions from includes\amxmodx.inc
#include <amxmodx>

//Declare three string variables
new PLUGIN[]="AMXX Demo"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

//This is a public function.
//It is necessary to initialize your script under AMX Mod X.
//It takes no parameters, and is called right after map load.
public plugin_init()
{
//This is a function that takes three strings.
//It registers your function in AMX Mod X, and assigns some basic information.
register_plugin(PLUGIN, VERSION, AUTHOR)
}
</pawn>

Try compiling the script above. It will be very small - as it does nothing so far. However, if you load this script, and type "amxx plugins", you should see the new entry on the list.

=Building Admin Commands=

AMX Mod X provides a way to easily add console admin commands. Each command is "registered" as a console command. When you register a command, you must define four properties: The console command that is typed in, the function you are making that interprets the command, the access level required to use it, and a short description of the command.

For this demonstration, let's build a plugin that lets you change the health of players on the server with the command "amx_hp".

We'll need to do two things to start off - first, we need to register the command in the console. As we are binding a command to a public function, we must then make sure that function exists.

<pre>
#include <amxmodx>
#include <amxmisc> //This contains some useful functions
#include <fun> //This contains the function to change health

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> ")
}

public cmd_hp(id, level, cid)
{
return PLUGIN_HANDLED
}
</pre>

The first new function is "register_concmd", which takes four parameters. The first is the command that a player must type into their console. The second is the public function that will handle the command. The third is the access level your command needs. Lastly, you can pass a string that describes how to use your command (for amx_help).

Next, we have created a public function to handle the amx_hp command. Note that we are giving it three parameters. These parameters will hold special data when the command is used - id will hold the player's id who started the command, level will hold the access level of the command (you must do access checking yourself), and cid will hold the command's internal id.

Also, note PLUGIN_HANDLED. There are two main return values you should concern yourself with. PLUGIN_CONTINUE generally means "continue with normal operation", and PLUGIN_HANDLED means "block further operation". The differences are subtle but important. For example, when binding a command, you should never return PLUGIN_CONTINUE. But if you return PLUGIN_HANDLED while binding to the "say" command, it will block the player's text from ever appearing. You must be careful with which you choose in certain situations. However, most things are unaffected (such as tasks, events, and other things you will run into later on).

So, first things first. How do we make sure this user is an admin who has ADMIN_SLAY access?

<pre>
public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED
return PLUGIN_HANDLED
}
</pre>

The cmd_access() function will check a command's information (user, access level, and id) and makes sure of two things: that the user has access to it, and that it was given a minimum number of parameters. Here we passed three, because the command will look like this: amx_hp <target> <amount>, and the actual command itself counts as a parameter. If cmd_access fails, we have the command immediately end.

The next portion to solve is: we need to take the two parameters and decode them. The "amount" parameter is easy, as we just convert it from a string to a number. The second parameter will be trickier, as we want to be able to target three different types of people:

* @CT or @T - CTs or Ts
* @ALL - Everyone
* <target> - Partial name of a player

<pre>
public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Get the command arguments from the console
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Convert the health from a string to a number
new Health = str_to_num(Arg2)

//Is the first character the @ symbol?
if (Arg1[0] == '@')
{
new Team = 0
//Check which team was specified.
//Note that we start from [1], this is okay
// it just means the @ isn't included
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
//This function will fill the players[32] variable
// with valid player ids. num will contain the number
// of players that are valid.
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
//Set this player's health
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
//finds a player id that matches the partial name given
//the 1 means that it will not target the player if he
// has immunity access
new player = cmd_target(id, Arg1, 1)
if (!player)
{
//this will print a message to the user who tried the command
//The format for this command is called "format()" style,
// where the first string formats the message according
// to any number of following parameters.
// %s means a string
// %d or %i means an integer
// %f means a float
// so "Hello %s, I am %d years old" will
// require a string and integer to follow
console_print(id, "Sorry, player %s could not be found or targetted!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}
</pre>

So, our final stripped amx_hp plugin will look like:

<pre>
#include <amxmodx>
#include <fun>

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> <hp>")
}

public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Get the command arguments from the console
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Convert the health from a string to a number
new Health = str_to_num(Arg2)

//Is the first character the @ symbol?
if (Arg1[0] == '@')
{
new Team = 0
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
new player = cmd_target(id, Arg1, 1)
if (!player)
{
console_print(id, "Sorry, player %s could not be found or targetted!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}
</pre>

=CVARs=

CVARs are server-side storage keys. For example, "mp_startmoney" is the Counter-Strike CVAR to hold how much money people get when they join the game. You can make your own CVARs by registering them in plugin_init(). Let's replicate mp_startmoney.

<pre>
#include <amxmodx>

public plugin_init()
{
register_plugin("CVAR Test", "1.0", "BAILOPAN")
//set default value to 500
register_cvar("amx_startmoney", "500")
}

//this occurs when a client is put in game
public client_putinserver(id)
{
if (get_cvar_num("amx_startmoney") > 0)
{
cs_set_user_money(id, get_cvar_num("amx_startmoney"))
} else {
cs_set_user_money(id, get_cvar_num("mp_startmoney"))
}
}
</pre>

(this plugin probably won't work, it's just a demonstration). You can set CVARs as floats, numbers, or strings, and you can modify just about any valid CVAR from the HL engine or mod.

=Finding More=

To learn more about scripting for AMX Mod X, you should look through the natives in the function reference or the include files. Include files generally follow two formats. They are named after a module or specific purpose. _const is appended if they contain pre-defined numbers or lists. _stocks is appended if they contain helper or useful wrapping functions. Remember, stocks are only compiled if you use them, so it is safe to include an include file with many stocks.

You can also visit the [http://www.amxmodx.org/forums/ Forums] and ask questions, or read how other people achieved certain goals to learn and innovate.

[[Category:Scripting (AMX Mod X)]]

Optimizing Plugins (AMX Mod X Scripting)

2006-02-25T08:34:39Z

Greenberet: /* Lookup Tables */

==Introduction==
[[Admin-Mod]] and [[AMX Mod X]] became very popular because of their easy to use scripting language. However, the words "scripting language" come with a lot of loaded preconceptions. Most people assume that because it's scripted:
*You can't possibly make it any faster
*It's pre-compiled, so it's already quite fast
*Details don't matter, as it's only "scripting" anyway

Especially, with [[Pawn]] (formerly Small), none of these are true. The compiler, in fact, is very poor at optimizing, and you can '''greatly''' increase the speed and efficiency of your plugins by keeping a few rules in mind. Remember - it's more important to minimize instructions than it is to minimize lines of code.

===Terms===
To read this document, you will need to understand a few concepts beforehand:
*<tt>BRANCHING</tt> - When the processor takes a different path of code. For example, to call a function or to use an if statement, the processor will "branch". Modern processors attempt to predict pathways with "branch prediction", but it's best to avoid branching a lot if possible.
*<tt>STACK ALLOCATION</tt> - In Pawn, all local data is stored on the stack, a big chunk of continuous memory. Whenever you create a variable on the stack, it is automatically written with zeroes.
*<tt>HEAP ALLOCATION</tt> - In Pawn, temporary data that needs to be referenced by a native is stored on the heap, another area of contiguous, but less restrictive memory.
*<tt>DATA SECTION</tt> - This is an area of memory built into your .amxx file. In fact, it "becomes" the heap at load time. All your strings and arrays are hardcoded into this area.
*<tt>EXPENSIVENESS</tt> - To be "expensive" in computer science means an operation requires a lot of CPU processing. It usually does not refer to memory size, only to processing cycles and time. Addition is inexpensive, floating power operations are expensive. However, both are inexpensive in comparison to writing a file. An inexpensive operation can also be called "cheap".
*<tt>BIG-OH NOTATION</tt> - O(*) notation refers to the expensiveness of an algorithm. If something is O(n), it occurs in linear time -- meaning that for N items, it will complete relative to N. O(N^2) means with N items, it will complete relative to N^2. O(1) means "constant time" - no matter what N is, it will run in the same amount of time.

==Compiler Optimizations==
These optimizations have to do with changing how your code is compiled. While the syntax may remain the same, you are not only increasing compile time, but increasing your plugin's efficiency and speed at run time.

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

===Switch instead of If===
If you can, you should use <tt>switch</tt> cases instead of <tt>if</tt>. This is because for an if statement, the compiler must branch to each consecutive <tt>if</tt> case. Using the example from above, observe the switch version:
<pawn>new team = get_user_team(player)
switch (team)
{
case TEAM_T:
//code...
case TEAM_CT:
//code...
case TEAM_SPECTATOR:
//code...
}</pawn>
This will generate what's called a "case table". Rather than worm through displaced <tt>if</tt> tests, the compiler generates a table of possible values, which the virtual machine knows to browse through:
<pre>
CALL get_user_team
COMPARE
COMPARE
COMPARE
</pre>

===Don't Re-index Arrays===
A common practive in Small is to "save space" by re-indexing arrays. There are a few myths behind this, such as saving memory, assuming the compiler does it for you, or readability. Fact: none of these are true. Observe the code below:
<pawn>new players[32], num, team
get_players(players, num)
for (new i=0; i<num; i++)
{
if (!is_user_connected(players[i]))
continue;
team = get_user_team(players[i])
set_user_frags(players[i], 0)
}</pawn>
For this, the compiler generates code similar to:
<pre>
:LOOP_BEGIN
LOAD i
LOAD players
CALC
LOAD players[i]
CALL is_user_connected
LOAD i
LOAD players
CALC
LOAD players[i]
CALL get_user_team
LOAD i
LOAD players
CALC
LOAD players[i]
CALL set_user_frags
</pre>
See what happened? The compiler does not cache array indexing. Because we've used <tt>players[i]</tt> each time, every instance generates 4-6 (or more) instructions which load <tt>i</tt>, the address of <tt>players</tt>, computes the final location, and then grabs the data out of memory. It is much faster to do:
<pawn>new player
for (new i=0; i<num; i++)
{
player = players[i]
if (!is_user_connected(player))
continue;
team = get_user_team(player)
}</pawn>
Not only is this more readable, but look at how much cruft we've shaved off the compiler's generated code:
<pre>
:LOOP_BEGIN
LOAD i
LOAD players
CALC
LOAD players[i]
STORE player
CALL is_user_connected
LOAD player
CALL get_user_team
LOAD player
CALL set_user_frags
</pre>
In a large loop you can drastically reduce codesize in this manner.

===Global vs Local and Variables in Loops===
It is important to realize that every variable in [[Pawn]] is automatically zeroed. For global variables, they are static and permanent, thus they are zeroed when your plugin is loaded. Variables in functions, however, must be zeroed dynamically. This is a slow and tedious operation, and you should not only avoid relying on it when necessary, but you should keep that fact in mind when using arrays.

[[Arrays]] in [[Pawn]] are "cells" of data. Each cell is four or eight bytes, depending on whether your processor is 32bit or 64bit. To create an array of 4096 cells, for example:
<pawn>new array[4096]</pawn>
The compiler generates code to manually zero every single one of the 16,384 bytes in that location. Normally, this isn't too bad -- but it can be absolutely deadly in a function which is called quite often. For example, <tt>server_frame</tt> is called on every [[server tick]] in [[AMX Mod X]]. To declare an array of that size in <tt>server_frame</tt> is highly unnecessary. Instead, you can take advantage of the fact that not only are globals free of charge, but <tt>server_frame</tt> does not need to be re-entrant. That is, you will never call <tt>server_frame</tt> inside of <tt>server_frame</tt>, so making the variable global will not bring up the problem of one instance of the function overwriting data from another instance of the same function. Observe:
<pawn>new g_serverframe_array[4096]
public server_frame()
{
//...code that uses g_serverframe_array
}</pawn>
This will execute conseridably faster. You can do this with smaller arrays too.

Likewise, it is equally important to avoid declaring arrays inside of loops. Consider the following block of code:
<pawn>for (new i=0; i<num; i++)
{
new message[255], name[32], player
player = players[i]
get_user_name(player, name, 31)
format(message, 254, "Hello, %s", name)
}</pawn>
If there are 32 players, this loop will actually resize and zero out over 1K of memory thirty two times in a row. Not good! However, on the other hand, it's nice that the message is zeroed out for us each time. <tt>Tip:</tt> you often only need to zero out the first character of a string. This will make the entire string empty. The code below is much more efficient:
<pawn>new message[255], name[32], player
for (new i=0; i<num; i++)
{
player = players[i]
name[0] = '\0'
message[0] = '\0'
get_user_name(player, name, 31)
format(message, 254, "Hello, %s", name)
}</pawn>
This has the effect of safely making the string empty beforehand, as well as largely reducing a lot of run-time overhead.

===Static vs Global===
An alternative to global variables is static variables, which are internally the same but easier to work with for programming.

A variable declared with the keyword "static" instead of "new" operates in the same way a global does (it is created only once) but the variable is local to the function; this means the code is much easier to read, while drastically improving speed just like a global variable. Example:
<pawn>stock SomeBigFunction()
{
static gaben[255];
format(gaben, "%L", LANG_SERVER, "STUFF");
}</pawn>

This has the same effect as declaring <tt>gaben</tt> as global, except only <tt>SomeBigFunction</tt> can use it.

{{qnotice|Be careful of re-entrancy!}}
When a variable is static, it has the same re-entrancy problems of a global variable. That means, if your function might be called recursively, or twice in the same stack frame, you should not use static variables. This is most often the case for API provided to other plugins or helper functions. Triggered events are usually never called twice on the same execution chain.

===Constant variables===
You can declare a variable "constant" by adding the "const" keyword before the variable name:

<pawn>new const AMX_GABEN[] = "amx_gaben"</pawn>

What this does is prevents the variable from being changed; essentially, you've locked the variable to a certain value. In this way, a constant can offer a type safe method of simplifying code, unlike a define, which is not type safe.

In addition, constant variables are often optimized out, resulting in quicker and smaller code.

===For Loop Comparisons===
A common mistake is to write code like this:
<pawn>new string[256] = "something long"
for (new i=0; i<strlen(string); i++)
//...code</pawn>
This plays off a similar principle from before: cache results. The compiler will actually recompute your string length on each iteration of the loop. This will have even worse effects if your string changes mid-loop. A more sensible method is:
<pawn>new string[256] = "something long"
new len = strlen(string)
for (new i=0; i<len; i++)
//...code</pawn>

==Tips and Tricks==
===Lookup Tables===
Precompute what can be precomputed. For example, say you have a mapping of weapon indices to names:
<pawn>if (weapon == CSW_AK47)
copy(name, len, "weapon_ak47")</pawn>
Ignoring the fact that we have <tt>get_weapon_name</tt> in [[AMX Mod X]], this is inefficient. We could precompute this result in a table:
<pawn>new g_WeaponNamesTable[TOTAL_WEAPONS][] = {
//..0 to CSW_AK47-1
"weapon_ak47",
//..CSW_AK47+1 to TOTAL_WEAPONS-1
};</pawn>

===Perfect Hashing===
:TODO: explain this

===Local Strings===
The [[Pawn]] compiler does not optimize the DATA section, which stores all hardcoded strings and global arrays. If you reference the same hardcoded string 500 times in your plugin, it will appear 500 different times. If this seems bad enough, it actually does this with all strings. For example, the empty string ("") appears everywhere in the include files, usually used as a default parameter to many natives. This too is copied into the data section for each unique reference.

For example:
<pawn>set_cvar_string("amx_gaben", get_cvar_string("amx_gaben") + 1)</pawn>
This will create two copies of "amx_gaben" in the DATA section. While this doesn't really hurt, it does increase the size of your plugin.

Similarly, this has the same problem:
<pawn>#define AMX_GABEN "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>
The only way to avoid this mess is to use global variables. As stated earlier, they're basically free storage.
<pawn>new AMX_GABEN[] = "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>

Again, while not necessary, this will reduce your plugin's size in memory and on disk. If you're already using defines, you can make this switch easily.

In order to prevent this from changing, you may want to declare it constant:

<pawn>new const AMX_GABEN[] = "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>

Now it is a perfectly safe method of storage.

==Faster Natives==
AMX Mod X replaces many of the old AMX Mod natives with faster versions. Read below to discover them.

===Cvar Pointers===
As of AMX Mod X 1.65, you can cache "cvar pointers". These are direct accesses to cvars, rather than named access. This is a critical optimization which is dozens of times faster. For example:
<pawn>new g_enabled = register_cvar("csdm_enabled", "1")
//OR
new g_enabled = get_cvar_pointer("csdm_enabled")

stock SetCSDM(num)
set_pcvar_num(g_enabled, num)

stock GetCSDM()
return get_pcvar_num(g_enabled)
</pawn>
All of the cvar* functions (except for set_cvar_string) are mapped to [get|set]_pcvar_*. You can get a cached cvar pointer with get_cvar_pointer() or register_cvar().

===FormatEX===
As of AMX Mod X 1.65, there is an ultra high-speed version of format() called formatex(). It skips copy-back checking, unlike format(). formatex() cannot be used if a source input is the same as the output buffer. For example, these are invalid:
<pawn>new buffer[255]
formatex(buffer, 254, "%s", buffer);
formatex(buffer, 254, buffer);
formatex(buffer, 254, "%d %s", buffer[2]);</pawn>

It should be noted that format() will behave the same as formatex() if it detects that there will be no copy-back needed. However, formatex() does not check this, and thus is slightly faster for situations where the coder is sure of its usage.

===File Writing===
As of AMX Mod X 1.65, there are new natives for file writing. Read_file and write_file are O(n^2) functions for consecutive read/writes. fopen(), fgets(), fputs(), and fclose() are O(n) (or better) depending on how you use them.

[[Category:Scripting (AMX Mod X)]]

Pawn Tutorial

2006-01-28T15:02:35Z

Greenberet: /* Integers */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3
new z = 1_000_000 // Pawn supports numbers like this. So big values are easier to read.</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || false) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it 6 (binary 0110).
//This is the "bitwise complement" operator, which performs a !(not) on each bit.
(~(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5)
{
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = {HELLO}</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

You can also change the control character( amxx std: '^' )
<pawn>#pragma ctrlchar '\'
//this sets the control character to backslash( c/c++/c#/java/... std )
// now you have to use the \ instead of ^
// e.g. "this is ^":D^" " must be now " this is \":D\" "</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

Pawn Tutorial

2006-01-28T15:02:09Z

Greenberet: /* Integers */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3
new z = 1_000_000 // Pawn supports numbers like this. So big values are easier to read.
</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || false) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it 6 (binary 0110).
//This is the "bitwise complement" operator, which performs a !(not) on each bit.
(~(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5)
{
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = {HELLO}</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

You can also change the control character( amxx std: '^' )
<pawn>#pragma ctrlchar '\'
//this sets the control character to backslash( c/c++/c#/java/... std )
// now you have to use the \ instead of ^
// e.g. "this is ^":D^" " must be now " this is \":D\" "</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

Pawn Tutorial

2006-01-21T22:03:48Z

Greenberet: /* Conclusion */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || true) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it to false (binary 0000).
(!(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5) {
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = {HELLO}</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

You can also change the control character( amxx std: '^' )
<pawn>#pragma ctrlchar '\'
//this sets the control character to backslash( c/c++/c#/java/... std )
// now you have to use the \ instead of ^
// e.g. "this is ^":D^" " must be now " this is \":D\" "</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

Pawn Tutorial

2006-01-21T22:01:33Z

Greenberet: /* Compiler Pre-processor Directives */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || true) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it to false (binary 0000).
(!(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5) {
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = {HELLO}</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

You can also change the control character( amxx std: '^' )
<pawn>#pragma ctrlchar '\'
//this sets the control character to backslash( c/c++/c#/java/... std )
// now you have to use the \ instead of ^
// e.g. "this is ^":D^" " must be now " this is \":D\" "</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Small documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

Pawn Tutorial

2006-01-21T22:00:05Z

Greenberet: /* Compiler Pre-processor Directives */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || true) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it to false (binary 0000).
(!(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5) {
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = {HELLO}</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

You can also change the control character( amxx std: '^' )
<pawn>#pragma ctrlchar '\'
//this sets the control character to backslash( c/c++/c#/java/... std )
// now you have to use the \ instead of ^
// e.g. "this is ^":D^" " must be now " this is \":D\" "
</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Small documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

Pawn Tutorial

2006-01-21T21:52:26Z

Greenberet: /* Expressions */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || true) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it to false (binary 0000).
(!(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5) {
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = {HELLO}</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Small documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]

Pawn Tutorial

2006-01-21T21:46:27Z

Greenberet: /* Strings */

{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}

This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].

=Introduction=
Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a "Compiler", which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.

Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera.

==Language Paradigms==
Pawn was originally named "[[Small]]" to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.
*No typing
**Pawn only has one data type -- the "[[Cell_(Pawn)|cell]]". It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.
**[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed "tags", which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning.
**Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.
**Pawn does support arrays of cells, which leads to C-style arrays for strings.
*No garbage collection
**Pawn has no "heap" allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.
*Procedural
**Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's "extern").
*No thread-safety
**Pawn is targetted toward single-thread instances.

==Implementation Features==
*Cross-platform compatible compiler, which outputs bytecode and debug browsing information.
*Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.
*IA32 JIT Compiler for vastly increasing script execution time.

Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.

==License==
Pawn is licensed under the [[ZLib/libpng_License]] license.

=Variables=
Variables are simple structures for holding data throughout a period of time in your script.

==Types==
Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore ("_"). It is important to note that variable names are case sensitive - "myvar", "MyVaR", and "MYVAR" are three separate symbols.

===Integers===
The simplest data type in Pawn is an "integer". Integers are whole numbers. To declare a new integer variable, use the "new" operator like so:

<pawn>new a //Declare empty variable "a"
new b=5 //Declare variable "b" and set it to 5.
new c=5.0 //This is invalid, technically not a whole number!
new d="hello" //"hello" is not a number either, this is invalid.

//You can also declare multiple variables on one line:
new e,f,g,h
new x=7, y=3</pawn>

===Floats===
You can also declare a variable as a "Float", which means it can store numbers with decimal places. These are called "floating point" numbers:

<pawn>new Float:a //Declare empty floating point variable "a"
new Float:b=5.3 //This will declare a new variable "b" and assign 5.3 to it.
new Float:c=5 //This is valid, but the compiler will give you a warning.
new Float:d="hello" //This is invalid, "hello" is not a decimal number.</pawn>

You can also do the following:
<pawn>//float(n) is a function that takes a number n and makes it a
// floating point number.
new Float:var = float(5)
new Float:var2 = 5.0
new Float:var3 = 1.0*5
new var4 = floatround(5.0)
//Note: floatround(n) is a function that takes a number n and rounds it to a whole number.
// this makes the assignment to a regular integer variable valid.</pawn>

Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, "new var = 5" and "new var=5" are the same, but "newvar=5" is totally wrong.

===Booleans===
The last variable type is "boolean". It is very simple - it is either "true", or "false". Both "true" and "false" are predefined data structures.

<pawn>new bool:IsItOn //Declares a new variable "IsItOn" which is automatically false
new bool:xyz=true //Declares a new variable "xyz" set to true</pawn>

=Arrays=

Pawn features basic "arrays". An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:

<pawn>//This will declare a variable called "Players" which holds 32 numbers.
new Players[32]
//You can now store values in any of the 32 "slots" this array has.
// The slots are numbered from 0 to n-1, or in this case, 0 to 31.
//Every slot starts off as 0.

//Set slot 0 to 5
Players[0] = 5
//Set slot 1 to whatever is in slot 0, in this case, the number 5
Players[1] = Players[0]
//This is invalid!
//Although there are 32 slots, they are numbered from 0 to 31.
//Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS
// or, it simply won't compile!
Players[32] = 15
//This is also totally invalid
Players[-1] = 6
new a = 3
//This is also totally invalid.
//a must be a constant number, so this is valid:
new BadArray[a]
const b = 3
new GoodArray[b]
//You can also use Compiler Directives (See last section)

#define ARRAY_SIZE 3
new Array[ARRAY_SIZE]</pawn>

Arrays can also be declared with groups of data default, such as:

<pawn>new Numbers[4] = {0,1,2,3}
//Note: it is important that you make sure the amount of numbers
// you pass and the size of the array match</pawn>

You can also use any data type with arrays:

<pawn>//Array of floating points:
new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}
//Array of booleans. Note this sets every slot to true.
new bool:playerHasGun[32] = true</pawn>

=Strings=

You have probably noticed that an important data type is missing - characters (letters and symbols). These are called "strings", and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:

<pawn>//This will declare a number array "myString" that contains the data "Hello".
//It will have 6 slots, because there are 5 characters.
//The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.
new myString[] = "Hello"</pawn>

Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string "Hello" is stored in a slot in the array.
<pawn>new myString[6]
myString[0] = 'H'
myString[1] = 'e'
myString[2] = 'l'
myString[3] = 'l'
myString[4] = 'o'
myString[5] = 0</pawn>

{{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}

You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:
<pawn>new myString[6]
myString = "Hello" //INVALID!
myString[0] = "Hello" //INVALID!
//To add data to a string, you can do this:
new goodString[7]
copy(goodString, 6, "Hello")</pawn>

Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.

More examples:
<pawn>//Copy is a function that takes three parameters:
copy(destination[], length, source[])
//It copies the string inside the source array and places
// it into the destination array, but only copies up to length characters.

//Lastly, to prove that a string is really an array of numbers, this is completely valid:
new weird[6]
weird[0] = 68
weird[1] = 65
weird[2] = 73
weird[3] = 86
weird[4] = 68
weird[5] = 0
//This will set the variable "weird" to the string "DAVID".
//To see how letters and symbols translate into numbers, visit www.asctiitable.com </pawn>

=Functions=

Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the "return" command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:

<pawn>//This is a function that takes no parameters and returns 1.
//When activated, it uses the (non-existant) print function.
show()
{
print("Hello!")

return 1 //End, return 1
}

//Activate like this:
show()</pawn>

You can also declare functions to take parameters.

<pawn>//This declares a function called "add_two_numbers", which takes two numbers and returns the sum.
add_two_numbers(first, second)
{
new sum = first + second

return sum //Return the sum
}
//Then you can use your new function like this:

new a,b
a = 5
a = 12
new c = add_two_numbers(a,b)
//c will now be equal to 17.</pawn>

You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called "passing". You can pass either data or a variable to a function.

<pawn>//This defines a new function called "add_two_floats"
// which takes two floating points and returns the sum
Float:add_two_floats(Float:first, Float:second)
{
new Float:sum = first + second

return sum
}

new Float:a
new Float:b
a = 5.0
b = 6.3
new Float:c
c = add_two_floats( a+b )
//c is now equal to 11.3</pawn>

You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.
<pawn>add_two_from_array(array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_numbers(first, second) //use our function from earlier

return sum
}</pawn>

Note, that when you pass arrays through a function they are passed through what is called "by reference". When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is "referenced" instead of copied. This means if you change the array, afterwards it will stay changed. For example:

<pawn>//This function will switch slots a and b inside any array passed to this function.
swap_slots(array[], a, b)
{
//Note, you need to temporarily hold one of the slots before swapping them
//Otherwise, you can't swap both values! This is a classic problem.
//If you have a and b, setting b equal to a eliminates the original value in b.
new temp

temp = array[b]
array[b] = array[a]
array[a] = temp
}

new myArray[2]
myArray[0] = 5
myArray[1] = 6
swap_slots(myArray, 0, 1)
//myArray[0] is 6, myArray[1] is 5</pawn>

You can prevent arrays from being modified by declaring them "constant", like so:
<pawn>add_two_from_array(const array[], a, b)
{
new first = array[a]
new second = array[b]
new sum = add_two_from_array(first, second)
return sum
}
//Note, now when you use the function, you are guaranteed that the array will not be modified.</pawn>

This function modifies an array passed as a constant. It will not work.
<pawn>bad_function(const array[])
{
array[0] = 0
}</pawn>

=Expressions=

Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.

<pawn>//This is the simplest expression. It returns the number zero.
0
//However, to make it easier to read, this is also valid:
(0)</pawn>

If an expression is not zero or it is not false, it not only returns a value, it also returns "true". Otherwise, it will return 0, which is also "false".

<pawn>//Here are more mathematical expressions. The mathematical operators are
// + for addition
// - for subtraction
// * for multiplication
// / for division
// % for modulus (finding the remainder of one number divided by another (5%2 is 1)
(5+6) //returns 11
((5*6)+3) //returns 33
((((5+3)/2)*4)-9) //returns 5
((5*6) % 7) //returns 2
//Here are other expressions:
(true) //returns true
(5.0 + 2.3) //returns 7.3 as a floating point</pawn>

There are also extensions of these operators for direct use on variables.
<pawn>new a = 5
new b = 6
//The first are the post/pre increment and decrement operators.
a++ //returns a+1, or 6. This is a post increment.
++a //also returns a+1, or 6. This is a pre increment.</pawn>

The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.

<pawn>a-- //returns 4, post decrement
--a //returns 4, pre decrement</pawn>

Note that a++ essentially trims down this code:
<pawn>a = a + 1</pawn>
However, there is another way to write lines of code of this form:
<pawn>a = a OP y</pawn>
Where OP is a math operator. It can be shortened to:
<pawn>a OP= x</pawn>
Observe:
<pawn>a += 1 //This sets a to a + 1
a -= b //This sets a to a - b
a *= 0 //This multiplies a by 0
a /= 2 //This divides a by 2.</pawn>

However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.

The and operator takes in the left expression and right expression. If both are "true", then it returns true.

<pawn>//This is false, because 1 returns true and 0 returns false.
//Since both are not true, && returns false.
(1 && 0)
(1 && 2) //Both numbers are "true", therefore the expression is true.
(true && false) //false
(false && false) //false
(true && true) //true</pawn>

The other important operator is "or". It returns true if one of two expressions are true.
<pawn>(1 || 0) //true, since one of the values is true.
(1 || 2) //true
(true || true) //true
(false || false) //false
(true || true) //true</pawn>

There are other operators as well, that you may not use as often. The "bitwise and" operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an "and (&&)" operation on each of the bits in both numbers. For example, say you have the number "9", which is "1001" in binary. If you want to know if that sequence contains the number "8" (1000), you can do:

<pawn>//This will return 8, which means 8 is indeed a bit in 9.
(9 & 8)
//4 (00100) is not a bit inside 16 (10000) and this will return 0.
(16 & 4)
//The next operator is "bitwise or"
//which does an "or (||)' operation on each of the bits in both numbers.
//This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.
(9 | 3)</pawn>

These two operators are also important, but not used often. They are the bitwise shift operators, << is a left shift and >> is a right shift. They shift the bits in a number to one direction.

<pawn>//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.
(3 << 3)
//This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.
(24 >> 3)</pawn>

The last operator is "bitwise not". It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).

<pawn>//This returns false
(!true)
//This returns true
(!false)
//This takes 9 (binary 1001) and makes it 6 (binary 0110).
(!(9))</pawn>

=Conditionals=

Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision.

==If Statements==

The most important conditional is called "if ... then". If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:

This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.

<pawn>if (a == 5)
{
a = 6
}</pawn>

However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.

<pawn>if (a == 5) {
a = 6
} else {
a = 7
}</pawn>

There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).

<pawn>//This will return true if a does not equal 5
if (a != 5) {}
//Returns true if a is greater than 5
if (a > 5) {}
//Returns true if a is less than 5
if (a < 5) {}
//Returns true if a is greater than or equal to 5
if (a >= 5) {}
//Returns true if a is less than or equal to 5
if (a <= 5) {}
//Returns true because 11 is true
if (5+6) {}
//Returns true of both a and b are true
if (a && b) {}
//Returns true if 7.5 is greater than c
if ( ((5*3)/2) > c) {}
//Always returns true no matter what
if (true) {}
//Never returns true
if (false) {}</pawn>
Note that array comparisons have restrictions. This is invalid:

<pawn>my arrayOne[3]
my arrayTwo[3]
if (arrayOne == arrayTwo) {</pawn>

You must do:
<pawn>if ((arrayOne[0] == arrayTwo[0]) &&
(arrayOne[1] == arrayTwo[1]) &&
(arrayOne[2] == arrayTwo[2])) {</pawn>

Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.

The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.

<pawn>//Example of "if...else if"
if (a == 5) {
//This code will be run if a is 5.
} else if (a < 6) {
//This code will be run if a is less than 6
} else if (a == 7) {
//This code will be run if a is 7.
} else {
//If none of the above conditions are met, this code will be run.
}</pawn>

It is important to note that in the above example, each code block is not "fall through". That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.

==Switch Statements==

Lastly, there is one last type of conditional statement. It is called a "switch" statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, "if...else if".

<pawn>//Example of a switch statement
switch (a)
{
case 5:
{
//This code will run if a is equal to 5
}

case 6:
{
//This code will run if a is equal to 6
}

case 7:
{
//This code will run if a is equal to 7
}

default:
{
//This code will run if all other cases fail
}
}</pawn>
Note that a switch is not "fall-through". If a case is true, no other cases are evaluated.

=Looping=

Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.

==For Loops==

The first and most widely used loop is called a "for loop". It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:

<pawn>/*A for loop has three parameters:
for (initial; condition; increment)
{
//your code here
}

Before the first loop executes, it runs your initial condition.
Then it begins looping your code with these steps:
1. Check if the condition is true. If so, continue. If not, stop.
2. Run the code.
3. Run the "increment" parameter.
4. Go to step 1.
*/

//Example of a for loop
new i
new sum
for (i=1; i<=10; i++)
{
sum += i
}</pawn>

Explanation:

#The first parameter, i=1, sets the i variable to one. This happens before the looping starts.
#Next, the "increment" parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.
#Then the condition is checked. Is i<=10? It is currently 1, so it is indeed less than or equal to 10.
#Since the condition is true, sum+=i is executed. This means i is added into sum.
#The code block has finished, and i++ increments i to 2.
#Now it repeats.
#Is i<=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.
#The code block has finished, and i now increments to 3.
#This happens until...
#The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.
#The sum variable now holds the number 55, which is the sum of 1 through 10.

This provides a nice way of managing arrays!

<pawn>//Note: this provides a nice way to loop through arrays! Observe this function below.
sum_of_array(myArray[], size)
{
//Note: Make sure the user passes the size of the array, so we don't overflow it.
new i, sum

//This loop will start at 0 and stop right before size is reached.
//If the user passes the correct size of the array,
// the loop will be going from 0 to size-1
// This correctly matches the numbers of slots in the array.
for (i=0; i<size; i++)
{
//For every time this loop executes,
// i will be a number from 0 to size-1
//Add the value of the slot (i) in the array to sum.
//Once this is finished, sum will contain
// the sum of all slots in the array.
sum += myArray[i]
}

return sum
}

new NumberArray[4]
NumberArray[0] = 3
NumberArray[1] = 1
NumberArray[2] = 4
NumberArray[3] = 1

new answer = sum_of_array(NumberArray, 4)
//answer will be 3+1+4+1, or 9

//Here is a function to compare if one array is equal to another (i.e. a string)
bool:compare_arrays(array1[], array2[], size)
{
new i
for (i=0; i<size, i++)
{
//If a slot does not match, halt the function and return false.
if (array1[i] != array2[i])
{
return false
}
}

//If the function got to this point without returning false, return true.
return true
}</pawn>

==While Loops==

The next kind of loop is also very important, and is simpler than a for loop. Called a "while" loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.

<pawn>//Basic loop
new i=0
new sum

while (++i <= 10)
{
sum+=i
}

sum_of_array(array[], size)
{
new i=0, sum

//Do this loop while i is less than the size.
//i is incremented at the end of every loop.
while (i++ < size)
{
sum += array[i]
}

return sum
}

bool:compare_arrays(array1[], array2[], size)
{
new i
while (i++ < size)
{
if (array1[i] != array2[i])
{
return false
}
}

return true
}</pawn>

==Two Dimensional Arrays==

In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:

<pawn>//This declares an array with 50 rows and 50 columns.
new BigArray[50][50]
//this declares a floating point array with 25 rows and 10 columns.
new Float:BigArray[25][10]</pawn>

Each slot in the first subset of the array becomes its own array.

<pawn>new BigArray[3][3]
BigArray[0][0] = 10
BigArray[0][1] = 20
BigArray[0][2] = 30
BigArray[1][0] = 40
BigArray[1][1] = 50
BigArray[1][2] = 60
BigArray[2][0] = 70
BigArray[2][1] = 80
BigArray[2][2] = 90</pawn>

Will result in BigArray looking like this:
:{|
|-
| BigArray
| 0
| 1
| 2
|-
| 0
| 10
| 20
| 30
|-
| 1
| 40
| 50
| 60
|-
| 2
| 70
| 80
| 90
|}

Note that our old sum_of_array() function can still work! We can do:

<pawn>new sum = sum_of_array(BigArray[2], 3)</pawn>

Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.

<pawn>//This function will tally up a two dimensional array.
sum_of_table(array[][], rows, cols)
{
new i, j, sum

//Note, there is a loop inside the loop.
//This lets you go through each array inside the
// bigger array.
for (i=0; i<rows; i++)
{
for (j=0; j<cols; j++)
{
sum += array[i][j]
}
}

return sum
}</pawn>

Note, it is also possible to store an array of strings using two dimensional arrays.

<pawn>new StringList[3][] = {"Hello", "my", "friend"}
/*
StringList[0][0] through [0][5] contains "Hello"
StringList[1][0] through [1][2] contains "my"
StringList[2][0] through [1][6] contains "friend"
*/</pawn>

The table for StringList will look like:
StringList 0 1 2 3 4 5 6
0 H e l l o \0
1 m y \0
2 f r i e n d \0

Comparing strings in multidimensional arrays is also similar:

<pawn>if (StringList[0] == "Hello") //INVALID
if (StringList[0][0] == "Hello") //INVALID
if (equali(StringList[0], "Hello")) //Valid</pawn>

=Compiler Pre-processor Directives=

Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.

<pawn>//To bind a symbol to a value, you can do this:
#define SYMBOL VALUE
//for example:

#define MAX_STRING 250
new String[MAX_STRING]

#define HELLO "Hello. This is a generic greeting."
new Hello[MAX_STRING] = {HELLO}</pawn>

You can also use #defines to change the flow of code the compiler makes.
<pawn>#if defined LINUX
//This portion will be compiled if #define LINUX exists
execute_command("ls -l")
#else
//This portion will be compiled if #define LINUX does not exist
execute_command("dir")
#endif</pawn>

You can also change how much memory your script uses.
<pawn>#pragma dynamic 4096
//This creates a 16K stack of memory (default).
//It is measured in blocks of 4 byte cells.</pawn>

You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required).
<pawn>#pragma semicolon 1</pawn>

=Conclusion=

This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Small documentation and language guide, go this website: http://www.compuphase.com/pawn/pawn-lang.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!

=External Links=
*[http://www.compuphase.com/pawn/pawn-lang.pdf Pawn Language Reference]
*[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]
*[http://www.compuphase.com/ ITB CompuPhase]

[[Category:Scripting (AMX Mod X)]]