The Absolute Beginner's Guide to Pawn (w/ examples)

[stormeus]

NOTE
This topic is locked to prevent people from ruining the succession of posts while the guide is being written. PM any errors or suggestions to stormeus.

The Absolute Beginner's
Guide to Pawn

Part I: Concepts

Part II: Control Structures

Part III: Arrays and Strings

Part IV: Basic Functions/Constructs

[stormeus]

Part I
Concepts of Pawn

Welcome to the absolute beginner's guide to Pawn! Before you can get into the nooks and crannies of Pawn, first we have to learn about the concepts of Pawn and programming in General.

Introduction
Pawn is an embeddable programming language and has a C-like syntax. Pawn was designed as an embeddable programming language, and is now used by projects like AMX Mod X, SA:MP, and, of course, VC:MP. Pawn scripts need to be compiled, or translate source code into computer-readable instructions. Pawn scripts have a structured flow, which means instructions are run one after another, but control statements can change what instructions come next.

The Compiler
The compiler translates source code into computer-readable code which will get run by the server. To use the compiler, you can download Pawno from the SA:MP server package, then go to Build > Compile. I recommend you use Pawno for this tutorial series so you can compile your test scripts and get compiler feedback if anything's wrong with the code.

Basic Program Structure
A very basic "Hello World" Pawn script would look like this:

Code Select Expand


main()
{
    print("Hello World!");
}


The main() function is the entry-point for the script, or where the program starts. The print() function writes a line of text in the console. The main() function doesn't concern us much in VC:MP scripting, but is good for printing script copyrights.

Note how the end of the Hello World line ends with a semicolon (;), but the rest of the code does not. That is because semicolons define where commands end, whereas control flow contains commands.

Variables
Variables are placeholders for information that a script can use, and can be changed at any time by the script. Variables are given names so we can not only get the variable's value, but so that we can also change it later if we need to. Variables can be assigned types so that their values can only be of a given type. Some common types are:

• Integer: Sometimes represented as int, this is any integer or "whole" number.
• Float: Stores decimals and any real number
• Character: Or char, stores a letter, number, or punctuation. Arrays of characters create strings.

The only type that needs to be explicitly declared is a float. Otherwise, Pawn will assume that a variable is an integer, and that arrays are either strings or arrays of integers. However, variables still need to be declared at some point in the script. A variable declaration consists of the word new, followed by the name of the variable, and a semicolon. For example:

• new myInt; defines a new integral variable named "myInt"
• new Float:myFloat; defines a new floating point number named "myFloat" -- note the Type: prefix.

Boolean
Boolean algebra is when a mathematical expression is evaluated as either true or false. Therefore, a boolean value can only have one of two values: true or false. However, it evaluates entire expressions. Let's take a few expressions into consideration.

If I were to say 3 < (is less than) 6, obviously the statement is true.
If I were to say I am 5' 9" tall, this statement is also true.

However, if I were to say I am 5' 9" tall AND I am President of the United States, boolean logic states that the ENTIRE expression is false. While it may be true that I am 5' 9", I am not the President. Therefore, the entire expression is false.

A similar sentence: I am 5' 9" tall OR I am President of the United States.
Since only one part of the sentence has to be true, the entire sentence is considered true.

Note
0 is considered false, and 1 is considered true.

Boolean Operators
There are three boolean operators: AND, OR, and NOT. In Pawn:

• AND is written as &&
• OR is written as ||
• NOT is written as !

Boolean operators are evaluated like so. For AND, the combination of two "True" values results in "True" while two "False" values results in "True." Any other combinations returns False. For example:

True AND True is true.
True AND False is false.
False AND True is false.
False AND False is true.

For OR, as long as one value is true, the entire statement is true.

True OR True is true.
True OR False is true.
False OR False is false.
False OR True is true.

The AND operator negates the value of an expression.
NOT True is false.
NOT False is true.

Comparison Operators
Boolean expressions most often involve comparison operators to see if they are true or false. These operators are equal to, greater than (or equal to), less than (or equal to), and not equal. In Pawn:

• Equal to is written as ==
• Less than is written as <
• Greater than is written as >
• Less than or equal to is written as <=
• Greater than or equal to is written as >=
• Inequality is written as !=

Comparison operators form expressions that can be evaluated as true or false. For example, Number_of_Students > 30. IF there are more than 30 students in the class, the entire expression is true. Otherwise, it is false.

Combining Boolean and Comparison Operators
We've looked at how boolean and comparison operators work to form expressions. Now, we'll look at how we can combine them to form more complex expressions.

If we wanted to know if there were more than 30 students in a class and if there were more than 30 seats, we could express this as:
Number_of_Students > 30 && Number_of_Seats > 30

Pawn has to determine the boolean (true/false) value of each expression, then use those values to evaluate the expression as a whole. Let's say we declare two new variables:

Code Select Expand


new Number_of_Students = 35;
new Number_of_Seats = 38;


Pawn will break this down into 35 > 30 && 38 > 30, which then evaluates to TRUE && TRUE. Therefore, the entire expression is true. The following example uses the following assumptions:

• All employees work in a department.
• All employees in department 5 have salaries greater than $25,000
• Alice is an employee in department 5

Consider the truth of these few expressions:

Alice_salary < 25000 && Alice_department == 5
Alice_salary < 25000 is False. Alice_department == 5 is true. False && True is false.

!Alice_salary < 25000
Alice_salary < 25000 is false. NOT FALSE is true.

Appendix I: Mathematical Operators
Pawn offers mathematical operators as well if you wish to do math with scripts, which will come in handy a lot.
Note that "var" is shorthand for variable.

var + var - Addition
var - var - Subtraction
var * var - Multiplication
var / var - Division
var ^ power - Exponentiation
dividend % divisor - Modulus

variable += number - Adds number to variable and saves in variable
variable *= number - Multiplies number to variable and saves in variable
variable -= number - Subtracts number from variable and saves in variable
variable /= number - Divides number into variable and saves in variable

Appendix II: Comments
Comments allow you to make notes in your code to explain to people who might view it, including yourself, what a piece of code does. Comments can be one line long: one-line comments start with // and continue until the line ends. Multi-line comments begin with /* and end with */ and last between the two markers. Anything that is commented is NOT run or compiled.

Examples:
// One-line long comment
/* Multi
* line
* comment
*/

[stormeus]

Part II
Control Structures

Introduction
Control flow is the order that Pawn (and any programming language) runs instructions and functions in. The use of loops and switch blocks can change the flow of a program, and repeat a piece of code or execute code specific to an expression.

If, Else If, Else
Toward the end of Part I, we learned about boolean algebra and comparison operators. Here's how such expressions would be used in Pawn. If, Else If, and Else are control statements, which "control" which pieces of code are run. For example, we might want a piece of code to run only if certain conditions are met.

Going back to our previous example with Alice, let's say we want to see how much a department should be paid based on the department ID. If we say new department is equal to 5, employees should be paid at least $25,000. If they're in department 3, they get paid more than $50,000. Otherwise, they should be paid exactly $40,000. In our main function, we have this so far:

Code Select Expand


main()
{
new department = 5;
}


This still doesn't tell us how much an employee should be paid in department 5, so we'll come back to this example.

The standard syntax for an if/else statement is:

Code Select Expand


if(expression)
{
// Expression is true.
// <code to run>
}
else if(expression)
{
// Other expression is true.
// <code to run>
}
else
{
// Neither are true.
// <code to run>
}


Keep in mind that you can have multiple else if statements in one conditional block and that else if statements are optional. Using this and our comparison operators, we can now make a conditional block to see how much a department gets paid, like so:

Code Select Expand


main()
{
new department = 5;
if(department == 5)
{
print("Employees get paid at least $25,000.");
}
else if(department == 3)
{
print("Employees get paid more than $50,000.");
}
else
{
print("Employees get paid exactly $40,000.");
}
}


For/While Loops and Switch
As well as conditional blocks of code, we can also run a piece of code as long as a given condition is true. For example, let's say we have a list of departments and we want to see how much each department is paid:

• Department 1 - $10,000
• Department 2 - $20,000
• Department 3 - $30,000
• Department 4 - $40,000
• Department 5 - $50,000

If we wanted to go through each department, we could use a for or while loop. Let's start with the for loop.

The for loop looks a little something like this:

Code Select Expand


for(variable = counter; condition; counter++)
{
// <code>
}


Let's break this down.
variable is the variable we want to use as our counter. You can also declare a new variable inline like this:

Code Select Expand


for(new i = [...]


counter is the number we want to start counting from. Usually this is 0. In our case, it's 1.
condition is a condition we want to fulfill. As long as it's true, the for loop will run.
counter++ increments the counter by one. This can also be counter-- to reduce the counter by one.

In the end we get something like this:

Code Select Expand


for(new i = 1; i < 5; i++)
{
// <code>
}


With 1 being the first department and 5 being the last. Here's where we're also going to introduce switch blocks. Switch blocks consist of a variable and multiple "cases," which are one line long each. Each case is a possible value for the variable, and a default case can be used if none match.

Syntax for switch blocks

Code Select Expand


switch(variable)
{
case <case>:
// <one line of code>
case <case>:
// <one line of code>
default:
// <one line of code>
}


With each case being a possible value for variable. Now, let's say we want to get the payroll of a department, between 1 and 5. Here's how our switch block would look:

Code Select Expand


switch(i)
{
case 1:
print("Department 1 gets paid $10,000");
case 2:
print("Department 2 gets paid $20,000");
case 3:
print("Department 3 gets paid $30,000");
case 4:
print("Department 4 gets paid $40,000");
case 5:
print("Department 5 gets paid $50,000");
default:
print("Unknown department.");
}


After placing this in our for block, we get this:

Code Select Expand


for(new i = 1; i < 5; i++)
{
switch(i)
{
case 1:
print("Department 1 gets paid $10,000");
case 2:
print("Department 2 gets paid $20,000");
case 3:
print("Department 3 gets paid $30,000");
case 4:
print("Department 4 gets paid $40,000");
case 5:
print("Department 5 gets paid $50,000");
default:
print("Unknown department.");
}
}


Which will go through each department and print their payroll in the console, or "Unknown department." if the department does not exist. This same result can be achieved with a while loop, which executes a piece of code while a certain expression is true.

Syntax of a while loop

Code Select Expand


while(condition)
{
// <code here>
}


If we declare a variable named i and set it to 1, a while loop could be used like so:

Code Select Expand


new i = 1;
while(i < 5)
{
switch(i)
{
case 1:
print("Department 1 gets paid $10,000");
case 2:
print("Department 2 gets paid $20,000");
case 3:
print("Department 3 gets paid $30,000");
case 4:
print("Department 4 gets paid $40,000");
case 5:
print("Department 5 gets paid $50,000");
default:
print("Unknown department.");
}
i++;
}


With the i++; placed at the end to add 1 to the variable i so we don't have an endless loop, which can lead to memory leaks or crashes.

[stormeus]

Part III
Arrays and Strings

Introduction
Arrays are like variables, except that they allow you to store more than one value in a given variable while only using one reference. Imagine a variable as a box that can hold a certain type. An array would be the equivalent of that same box divided into multiple pieces, each piece containing a piece of data. Of course, since the array box stores more information than the single variable box, it is bigger, so it uses more memory.

Array Indexes
We can use the same name to get the value of a part in the array, but we need a way to differentiate between each cell, or part, of the array. To do this, we use a zero-index in the array. Let's say we have an array that's 100 cells large. The zero-index, as you might assume, starts at zero, so our first value is myArray[0], and the 100^th value is myArray[99]. The fifth value is myArray[4], so think of it as myArray[item number - 1].

Creating Arrays
Arrays are declared similarly to regular variables, except we specify how many array cells we want to use. Unlike the zero-index, when you create the array, you specify exactly how many cells you want to use, i.e. new myArray[10] for an array named myArray 10 cells long.

Using Array Cells
Once you have declared an array, you can use an array index to both store and get information stored in that cell. Right now, we can only store integers and floats in our arrays. Strings and characters will come later. Let's say we want to, like our last example, set the payrolls of each department into an array, with payrollArray[0] reserved for department 1, payrollArray[1] for department 2, etc. First, instantiate (create) a new array with new payrollArray[5];

Given that we know each department's payroll is $10,000 times the department ID, we can use our mathematical operators, a for loop, and our array. We've declared our array, so now let's create our for loop to iterate through each department, starting at 1 and ending at 5.

Code Select Expand


// Declare our new array
new payrollArray[5];

// Iterate through each department.
for(new i = 1; i < 5; i++)
{
// <code here>
}


However, this still doesn't store each department's payroll in the array. Trying to compile this will result in an array something like payrollArray is unused. Since our array starts at index 0 while our department IDs start at 1, we can subtract 1 from the department ID to get the array index that goes with it. Array indexes, as long as they're integral, are valid, so mathematical expressions can also be array indexes, like so: payrollArray[i - 1]; with i - 1 being the array index (DepartmentID - 1). If i was 1, the index would be 0, which is valid, so let's use this to our advantage.

We also know that our payroll is $10,000 times the department ID, so whatever the cell is, it will be equal to the department ID * 10000 (note that there are NO commas in numbers).

Code Select Expand


// Declare our new array.
new payrollArray[5];

// Iterate through each department.
for(new i = 1; i < 5; i++)
{
// i - 1 = DepartmentID - 1, for our zero-indexed array
payrollArray[i - 1] = i * 10000; // Department ID * 10000
}


We can now get the payroll from this array by using payrollArray[ID - 1]

Strings
A string is simply an array of characters (letters and punctuation) which, when put together, form a sentence, phrase, word, etc. Since they are arrays, they work similar to integral arrays, except each cell is one letter or punctuation mark. In addition, the last character in the string has to be a null character (\0), which tells the computer when the string ends. Strings can be as long or longer than the sentence that they hold. For example, the following sentence is 12 characters long:

I like pie.

It consists of 11 letters and punctuation marks, plus the null character at the end. myString[12] would work for it. myString[25] would work too. However, myString[11] is invalid. Each cell is going to be one letter, thus:

myString[0] = "I"
myString[1] = " "
myString[4] = "k"

Strings can also be formatted using the format() function, which will be described in further detail later. Entire strings can be created at once as well. If we want to use our "I like pie." sentence for our string, we first have to declare our new array.

new myString[12];

Instead of saving to individual cells, we can instead reference just the variable, then place the sentence inside a string, enclosed by double quotes (""). For example:

myString = "I like pie."

This will automatically include the null character at the end.