James
16th January 2014, 10:32 AM
ULTA-Detailed Scripting Guide
by Laurens "James Williamson" Vijnck
Welcome, it's a pleasure to have you here. In this guide - I'll teach you all you need to know to get started into the PAWN language. In the list below, you can see all of the subjects we'll be talking about - ofcourse all of them will be given with clear examples. At the end of the guide, we'll be scripting a in-game gate editor. This quide wont make you a pro, nor an experienced scripter - but this will guide you throughout the basics of scripting.
Installing PAWN
A first look at the program (IDE)
Building up our 'basic gamemode' file.
What are 'Variables'?
Logical operators
The difference between 'public' and 'private'
Working with loops
Plugins
SAMP's functions.
Working with external documents
Advanced structures 'Enums'
1 - Installing PAWN
Let's get started. First off all - download the SAMP 0.3x Windows Server, which can be found on SAMP's download page (http://www.sa-mp.com/download.php) and extract those files anywhere you like. In my case, I created a new folder named 'Sampscript' which I placed on my desktop. I extracted the files from the .ZIP file in there. I suggest you to do the same thing, because i'll be constantly making references to this folder and the files in there.
So - at this moment, we freshly installed SAMP's Windows server. The first question you might have is.. 'Why?' Well - I do have a simply answer to that question. PAWN is included in SAMP's windows server. Get inside the 'sampscript/pawno' folder, and open the PAWN.exe file.
AAAAAAAAAND, there we go:
http://img89.imageshack.us/img89/4526/h1sd.png
Our first error pops up, atleast it always does for me when running PAWN for the first time. This error isn't anything major, it just refuses to open any files when loading the program. I could explain why this is, but that seems pretty damn useless to me. What I want you to do, is close down PAWNO for a second, and get back into 'sampscript/pawno' and open the settings.ini with notepad, replace the code in there, by the following:
[General]
FileAssoc=0
[Display]
WindowMax=1
WindowX=50
WindowY=389
WindowW=1163
WindowH=187
Splitter=30
Font_Name=Courier New
Font_Size=10
ShowFuncList=1
[RunOpts]
CopyDir=\
ExeFile=pawncc.exe
Params=-r -w 203
Re-open the execute file and you no longer will recieve this error.
2 - A first look at the program (IDE)
Pawno is a IDE for the PAWN language, we have many different programming languages, such as C, C++, C#, F#, Objective C, etc. Though, this guide is for the PAWN language only - if you do want to learn any other language, you are not at the right place here - if you have any question regarding to another scripting language, feel free to send me a private message. Anyway, back to the IDE part. IDE is an abbreviation for Integrated Development Environment, which basically means, a program to program in.
As you open pawn, hit 'file' and click 'new'. This will open a brand-new game-mode file:
http://img844.imageshack.us/img844/2098/ot2v.png
Riteeeee.... That's a lot of code to digest already, isn't it? We'll be building this all up from nowhere - if you do not understand what you are writing, there is no point in writing anything at all, and therefore hold down CNTRL+A and after that hit delete. Lets get rid of everything!
We'll be looking away from the main window for the moment being, on the right side of PAWN you'll see a list:
http://img41.imageshack.us/img41/15/tr74.png
(My list might differ from yours, due to me having shitloads of includes installed.)
This is a list of all your includes, and the functions they have. Look at it from this side - an include, is basically a script by someone else, for a certain purpose. For PAWN, we have numerous includes written by dozen of different developers. You can also write a include yourself if you like to, we'll get deeper into this later on. Anyway, the most important include for us, is the a_samp.inc - because this gives us access, to all of the features SAMP has already made for us, more about this, is to come.
Special terms learned in this chapter:
IDE: Integrated Development Environment, A program to program in, it makes it easier for developers to write code.
An Include: Includes are scripts with own functions written by others to make it easier for us, an example is the a_samp.inc written by the samp team.
3 - Building up our 'basic gamemode' file
In every and each gamemode script, you will find the following accessories.
Comments
Includes
Defines
Main()
Call-Backs
3.1 Comments
First off all, we have comments. Comments are not related to scripting at all, they are just notes to make things easier for you, lets say - you write a whole gamemode, and you took a year to write all of the code for it, of-course you do not remember what every and each line does. That's why comments are necessarily, they help you to organise your script(s). I would heavily recommend you using them, especially when you are writing a extra-complicated piece of code.
These line(s) will always be coloured in green, the IDE (PAWN) will automatically do this for you. There are two different ways to write comments:
http://img17.imageshack.us/img17/3661/gjpz.png
Look twice, it's all about how they start. Let's speak about the one-lined comment first. If you want to write a comment over just one line, or a piece of a line, you just type '//' and after that, you can type whatever you want. It'll be ignored by the actual 'script'. The second type is multi-lined comments, they start with '/*' and after that, you can write as many comment lines as you like, don't forget to close it down by using '*/' at the end of the comments, otherwise you'll run into trouble later on.
3.2 Includes
To easily keep track of what you include, and to not run into trouble when using includes we always do that ON TOP of the scripting document. Always, no matter what - always put them at the first lines of your script. As we are only working with the a_samp include, this is fairly simple:
http://img547.imageshack.us/img547/5463/7k8d.png
As you can see, this is always coloured in blue - PAWNO automtically assigns colours to certain pieces of code, just to make it easier for the developers who are working with it. Some IDE's even offer the ability to change to colours which it assigns, but pawno on his place doesn't - which is too bad. So as I stated before - we now included the a_samp include, which gives us acces to all of the functions which the samp team has already written for us.
3.3 Defines
I'm not going too deep into this right now, as we didn't get to the variables part yet. But I found it rather important to show you that you can define a constant as a word:
http://img7.imageshack.us/img7/1892/8eer.png
As you can see, I defined MAX_PING with 1200 as value - so if I wanna use the value 1200 with the meaning of MAX_PING, I could just write MAX_PING instead of the 1200, which is waaaay clearer. It's probably hard to understand this right now, but it'll be pointed out later on.
3.4 main()
A gamemode file will always have a main() 'function' this will be called when you open up the gamemode to run it on a server. A server will always have a command window, and what you type in the main() will be displayed there when you launch it up.
http://img202.imageshack.us/img202/7471/7e8m.png
So, when I use the piece of code above, in the main() function, this'll be displayed in the command when you open the gamemode:
http://img547.imageshack.us/img547/9366/ayrf.png
I'll explain you later about how to open the command, but for now it's pretty useless - as we didn't even script anything so far.
3.5 Functions
We have 3 type of functions:
Naked
Stock
Callbacks/public
3.5.1 Naked Functions
These are just functions, calculations and other stuff. Warnings will be displayed within these functions by pawn.
3.5.1 Stock Functions
PAWN will 'ignore' this piece of code when it's not used, and it will not show any errors within that function.
3.5.1 Callback/public
Callbacks, are certain functions which are called when something happens within the game. There is a callback for almost everything! (Thanks to the a_samp.inc) Such as, when a player dies, when a player connects, and when a player spawns. These functions get called when this happens in-game - so we can apply logic to it.
Expanded: The UMX calls stocks and normal functions by ID's However, public functions are called by name, thus allowing us to use CallLocalFunction, and stuff like this. (You probably won't understand this right now, so ignore it.)
Below you can see a screenshot on how a callback is written, I just wrote down four of them, as example:
http://img5.imageshack.us/img5/4982/3zwl.png
When you read this, I think it's pretty logic - right? The first one is called/executed when someone connects to the server, the second one when someone leaves, the third one when someone spawns, and the least but not least when someone dies. Callbacks are important when we a coding for a SAMP server, more explanation follows.
Special terms learned in this chapter:
Comments: Certain line(s) with notes, to help organizing the code - it also explains with a piece of code does in complicated pieces of code.
Defines: Attaching a word, to a value - in other words, creating a constant.
Call-backs: Pieces of code, which are called/executed when something happens in-game (i.e. a player dies).
4 - What are variables?
Variables are one of the most important aspects of scripting, without them - there isn't much logic we could complete. PAWN's way creating, and accessing variables is really easy, it's childplay - in all honestly in comparison to other scripting languages. We have 3 different types of variables we use, normal variables, float variables, string variables, and arrays. When you declare them, you can chose any name you like, however using a name as : ffffff is not really organised at all, named the variable after it's purpose. 'Declaring a variable' does simply mean, creating a new variable.
Normal
Float
String
Array
4.1 Integer variables
Normal variables do only work with whole numbers, and not with decimal numbers.
The following picture will show a static way of working with variables, you can asign value's to variables to do logic with those, and even create new variables based on other variables.
http://img59.imageshack.us/img59/4305/l3np.png
As you see, at the very top - you can declare variables together, or you can declare them seperatly.
4.2 Float Variables
Whilst normal variables to only work with whole numbers, float variables do work with decimal numbers, there is only a slight difference in declaring float variables. They work exacly the same.
http://img547.imageshack.us/img547/1232/htt2.png
4.3 String Variables
Strings are (pieces of) text. When you work with a string, you ALWAYS put it between quotation marks, always otherwise the program doesn't know you are working with strings, and you'll run into trouble. Declaring them works this way;
http://img843.imageshack.us/img843/3247/am5n.png
4.4 Arrays
And here is, where it gets alittle tricky. And thats why picking names is so important. Arrays look, and are declared the same way as a string, however you can compare an Array with a list. The following picture shows how to access, declare and use a array, you can also make an array of floats. As stated above, to avoid confusion between arrays and strings, pick correct names.
http://img706.imageshack.us/img706/9017/7gd0.png
Don't be worried if you do not fully understand the meaning of a variable, examples on how we use them are to come. Just make sure to keep in mind how they are declared.
5 - Logical operators
http://www.enough.pro/wp-content/uploads/2013/05/enough-pro-php-operator-3.jpg
Still being worked at. More coming soon!
by Laurens "James Williamson" Vijnck
Welcome, it's a pleasure to have you here. In this guide - I'll teach you all you need to know to get started into the PAWN language. In the list below, you can see all of the subjects we'll be talking about - ofcourse all of them will be given with clear examples. At the end of the guide, we'll be scripting a in-game gate editor. This quide wont make you a pro, nor an experienced scripter - but this will guide you throughout the basics of scripting.
Installing PAWN
A first look at the program (IDE)
Building up our 'basic gamemode' file.
What are 'Variables'?
Logical operators
The difference between 'public' and 'private'
Working with loops
Plugins
SAMP's functions.
Working with external documents
Advanced structures 'Enums'
1 - Installing PAWN
Let's get started. First off all - download the SAMP 0.3x Windows Server, which can be found on SAMP's download page (http://www.sa-mp.com/download.php) and extract those files anywhere you like. In my case, I created a new folder named 'Sampscript' which I placed on my desktop. I extracted the files from the .ZIP file in there. I suggest you to do the same thing, because i'll be constantly making references to this folder and the files in there.
So - at this moment, we freshly installed SAMP's Windows server. The first question you might have is.. 'Why?' Well - I do have a simply answer to that question. PAWN is included in SAMP's windows server. Get inside the 'sampscript/pawno' folder, and open the PAWN.exe file.
AAAAAAAAAND, there we go:
http://img89.imageshack.us/img89/4526/h1sd.png
Our first error pops up, atleast it always does for me when running PAWN for the first time. This error isn't anything major, it just refuses to open any files when loading the program. I could explain why this is, but that seems pretty damn useless to me. What I want you to do, is close down PAWNO for a second, and get back into 'sampscript/pawno' and open the settings.ini with notepad, replace the code in there, by the following:
[General]
FileAssoc=0
[Display]
WindowMax=1
WindowX=50
WindowY=389
WindowW=1163
WindowH=187
Splitter=30
Font_Name=Courier New
Font_Size=10
ShowFuncList=1
[RunOpts]
CopyDir=\
ExeFile=pawncc.exe
Params=-r -w 203
Re-open the execute file and you no longer will recieve this error.
2 - A first look at the program (IDE)
Pawno is a IDE for the PAWN language, we have many different programming languages, such as C, C++, C#, F#, Objective C, etc. Though, this guide is for the PAWN language only - if you do want to learn any other language, you are not at the right place here - if you have any question regarding to another scripting language, feel free to send me a private message. Anyway, back to the IDE part. IDE is an abbreviation for Integrated Development Environment, which basically means, a program to program in.
As you open pawn, hit 'file' and click 'new'. This will open a brand-new game-mode file:
http://img844.imageshack.us/img844/2098/ot2v.png
Riteeeee.... That's a lot of code to digest already, isn't it? We'll be building this all up from nowhere - if you do not understand what you are writing, there is no point in writing anything at all, and therefore hold down CNTRL+A and after that hit delete. Lets get rid of everything!
We'll be looking away from the main window for the moment being, on the right side of PAWN you'll see a list:
http://img41.imageshack.us/img41/15/tr74.png
(My list might differ from yours, due to me having shitloads of includes installed.)
This is a list of all your includes, and the functions they have. Look at it from this side - an include, is basically a script by someone else, for a certain purpose. For PAWN, we have numerous includes written by dozen of different developers. You can also write a include yourself if you like to, we'll get deeper into this later on. Anyway, the most important include for us, is the a_samp.inc - because this gives us access, to all of the features SAMP has already made for us, more about this, is to come.
Special terms learned in this chapter:
IDE: Integrated Development Environment, A program to program in, it makes it easier for developers to write code.
An Include: Includes are scripts with own functions written by others to make it easier for us, an example is the a_samp.inc written by the samp team.
3 - Building up our 'basic gamemode' file
In every and each gamemode script, you will find the following accessories.
Comments
Includes
Defines
Main()
Call-Backs
3.1 Comments
First off all, we have comments. Comments are not related to scripting at all, they are just notes to make things easier for you, lets say - you write a whole gamemode, and you took a year to write all of the code for it, of-course you do not remember what every and each line does. That's why comments are necessarily, they help you to organise your script(s). I would heavily recommend you using them, especially when you are writing a extra-complicated piece of code.
These line(s) will always be coloured in green, the IDE (PAWN) will automatically do this for you. There are two different ways to write comments:
http://img17.imageshack.us/img17/3661/gjpz.png
Look twice, it's all about how they start. Let's speak about the one-lined comment first. If you want to write a comment over just one line, or a piece of a line, you just type '//' and after that, you can type whatever you want. It'll be ignored by the actual 'script'. The second type is multi-lined comments, they start with '/*' and after that, you can write as many comment lines as you like, don't forget to close it down by using '*/' at the end of the comments, otherwise you'll run into trouble later on.
3.2 Includes
To easily keep track of what you include, and to not run into trouble when using includes we always do that ON TOP of the scripting document. Always, no matter what - always put them at the first lines of your script. As we are only working with the a_samp include, this is fairly simple:
http://img547.imageshack.us/img547/5463/7k8d.png
As you can see, this is always coloured in blue - PAWNO automtically assigns colours to certain pieces of code, just to make it easier for the developers who are working with it. Some IDE's even offer the ability to change to colours which it assigns, but pawno on his place doesn't - which is too bad. So as I stated before - we now included the a_samp include, which gives us acces to all of the functions which the samp team has already written for us.
3.3 Defines
I'm not going too deep into this right now, as we didn't get to the variables part yet. But I found it rather important to show you that you can define a constant as a word:
http://img7.imageshack.us/img7/1892/8eer.png
As you can see, I defined MAX_PING with 1200 as value - so if I wanna use the value 1200 with the meaning of MAX_PING, I could just write MAX_PING instead of the 1200, which is waaaay clearer. It's probably hard to understand this right now, but it'll be pointed out later on.
3.4 main()
A gamemode file will always have a main() 'function' this will be called when you open up the gamemode to run it on a server. A server will always have a command window, and what you type in the main() will be displayed there when you launch it up.
http://img202.imageshack.us/img202/7471/7e8m.png
So, when I use the piece of code above, in the main() function, this'll be displayed in the command when you open the gamemode:
http://img547.imageshack.us/img547/9366/ayrf.png
I'll explain you later about how to open the command, but for now it's pretty useless - as we didn't even script anything so far.
3.5 Functions
We have 3 type of functions:
Naked
Stock
Callbacks/public
3.5.1 Naked Functions
These are just functions, calculations and other stuff. Warnings will be displayed within these functions by pawn.
3.5.1 Stock Functions
PAWN will 'ignore' this piece of code when it's not used, and it will not show any errors within that function.
3.5.1 Callback/public
Callbacks, are certain functions which are called when something happens within the game. There is a callback for almost everything! (Thanks to the a_samp.inc) Such as, when a player dies, when a player connects, and when a player spawns. These functions get called when this happens in-game - so we can apply logic to it.
Expanded: The UMX calls stocks and normal functions by ID's However, public functions are called by name, thus allowing us to use CallLocalFunction, and stuff like this. (You probably won't understand this right now, so ignore it.)
Below you can see a screenshot on how a callback is written, I just wrote down four of them, as example:
http://img5.imageshack.us/img5/4982/3zwl.png
When you read this, I think it's pretty logic - right? The first one is called/executed when someone connects to the server, the second one when someone leaves, the third one when someone spawns, and the least but not least when someone dies. Callbacks are important when we a coding for a SAMP server, more explanation follows.
Special terms learned in this chapter:
Comments: Certain line(s) with notes, to help organizing the code - it also explains with a piece of code does in complicated pieces of code.
Defines: Attaching a word, to a value - in other words, creating a constant.
Call-backs: Pieces of code, which are called/executed when something happens in-game (i.e. a player dies).
4 - What are variables?
Variables are one of the most important aspects of scripting, without them - there isn't much logic we could complete. PAWN's way creating, and accessing variables is really easy, it's childplay - in all honestly in comparison to other scripting languages. We have 3 different types of variables we use, normal variables, float variables, string variables, and arrays. When you declare them, you can chose any name you like, however using a name as : ffffff is not really organised at all, named the variable after it's purpose. 'Declaring a variable' does simply mean, creating a new variable.
Normal
Float
String
Array
4.1 Integer variables
Normal variables do only work with whole numbers, and not with decimal numbers.
The following picture will show a static way of working with variables, you can asign value's to variables to do logic with those, and even create new variables based on other variables.
http://img59.imageshack.us/img59/4305/l3np.png
As you see, at the very top - you can declare variables together, or you can declare them seperatly.
4.2 Float Variables
Whilst normal variables to only work with whole numbers, float variables do work with decimal numbers, there is only a slight difference in declaring float variables. They work exacly the same.
http://img547.imageshack.us/img547/1232/htt2.png
4.3 String Variables
Strings are (pieces of) text. When you work with a string, you ALWAYS put it between quotation marks, always otherwise the program doesn't know you are working with strings, and you'll run into trouble. Declaring them works this way;
http://img843.imageshack.us/img843/3247/am5n.png
4.4 Arrays
And here is, where it gets alittle tricky. And thats why picking names is so important. Arrays look, and are declared the same way as a string, however you can compare an Array with a list. The following picture shows how to access, declare and use a array, you can also make an array of floats. As stated above, to avoid confusion between arrays and strings, pick correct names.
http://img706.imageshack.us/img706/9017/7gd0.png
Don't be worried if you do not fully understand the meaning of a variable, examples on how we use them are to come. Just make sure to keep in mind how they are declared.
5 - Logical operators
http://www.enough.pro/wp-content/uploads/2013/05/enough-pro-php-operator-3.jpg
Still being worked at. More coming soon!