[Deskoft]

Lawedan Basic Tutorial

This is a basic tutorial created by the Lawedan Team. During this tutorial you will be able to learn the basics of scripting. Sadly, the 'Scripter's Guide' is a separate tutorial, which was not created by the Lawedan Crew. The original owner has left SA-MP and told me to post it and update it when I was able to.

That tutorial was disorganized, and our aim is to add a complete introduction to PAWN. This tutorial was developed by the whole San Andreas Multiplayer Script Development team at Lawedan.

Definitions

Pawn differs from Pawno, Pawn is the programming language, Pawno is a compiler.
Programming language means: a language designed for programming computers (princeton.edu)
Programming means: The action or process of writing computer programs.

Programming?

Why do we call it programming? Why do we use programming? All the questions you have on your mind have been answered since 1896 when the core of IBM was developed by Herman Hollerith.
Programming is related to the word Program, which means A planned series of future events, items, or performances(Dictionary.com). We are developing a planned series of future events inside a programmable machine.

Chapter 1: Previous knowledge

Before we even start coding, we will need some previous knowledge. One of the first topics to touch is Cartesian Coordinates.

Cartesian Coordinates



The coordinates system (usually refered as Cartesian Coordinates System) was developed by Rene Descartes (that's the reason of the name), It originally used only a horizontal line (refered as x) and a vertical line (refered as y), later it was developed for three-dimensions, adding a Z value for 'height'.

The Cartesian Coordinates System is widely used in graphics and specially in three-dimensional programming, like in this case, three-dimensional scripting.

During this course, you will understand that mathematics is a very important point in programming and scripting.

Angles



I think angles is not really used a lot in basic PAWN, but it's always good to have this knowledge when programming.

Our friend Wikipedia says: In geometry, an angle is the figure formed by two rays sharing a common endpoint, called the vertex of the angle.

The image shows a 90° angle.

---

That's the knowledge you will require as of now for the first chapters.

Chapter 2: Pawno

I will suppose you have installed the server pack already, and you have it all set.
So let's open pawno (again, differs from pawn).

We will first of all introduce you to Pawno.



If you click the file tab, you will see that features or items.

The 'New' Item creates a new document or script, you can use the Ctrl + N shortcut.
The 'Open' Item opens an existing document or script, you can use the Ctrl + O shortcut.
The 'Close' Item closes the active document.
The 'Save' Item saves the active document or script, you can use the Ctrl + S shortcut.
The 'Save As...' Item saves the active document under a new name or root (location).
The 'Exit' Item closes Pawno.



The 'Undo' Item allows the user to reverse the last action, you can use the Ctrl + Z shortcut.
The 'Copy' Item allows the user to copy a piece of text from the script, you can use the Ctrl + C shortcut.
The 'Paste' Item allows the user to paste a copied piece of text, you can use the Ctrl + V shortcut.
The 'Delete' Item deletes a selected piece of text (pretty useless in my opinion).
The 'Find...' Item tries to find a piece of text or word (Will use it alot), you can use the Ctrl + F shortcut.
The 'Replace' Item allows to replace a selected piece of text for another one (similar to find).
The 'Go to...' Item redirects the user a specified line.



The 'Compile' Item 'builds' the script, a type of 'release' feature.
The 'Compile/Run' Item 'builds' and 'runs' the script, very similar to the Compile Item.
The 'Run Options' Item allows the user to specify the options for the Compile/Run Item.



The 'Font' Item allows the user to specify the types of fonts he will use in the script.
The 'Show Function List' allows the user to show / hide the following bar:



The 'Associate with * .pwn files' Item allows you to link Pawno to .pwn files.

This concludes the Pawno Interface.

Chapter 3: Understanding the initial script

So if we start a new document, we will see the following script:

pawn Код:

// This is a comment
// uncomment the line below if you want to write a filterscript
//#define FILTERSCRIPT

#include <a_samp>

#if defined FILTERSCRIPT

public OnFilterScriptInit()
{
    print("\n--------------------------------------");
    print(" Blank Filterscript by your name here");
    print("--------------------------------------\n");
    return 1;
}

public OnFilterScriptExit()
{
    return 1;
}

#else

main()
{
    print("\n----------------------------------");
    print(" Blank Gamemode by your name here");
    print("----------------------------------\n");
}

#endif

public OnGameModeInit()
{
    // Don't use these lines if it's a filterscript
    SetGameModeText("Blank Script");
    AddPlayerClass(0, 1958.3783, 1343.1572, 15.3746, 269.1425, 0, 0, 0, 0, 0, 0);
    return 1;
}

public OnGameModeExit()
{
    return 1;
}

public OnPlayerRequestClass(playerid, classid)
{
    SetPlayerPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraLookAt(playerid, 1958.3783, 1343.1572, 15.3746);
    return 1;
}

public OnPlayerConnect(playerid)
{
    return 1;
}

public OnPlayerDisconnect(playerid, reason)
{
    return 1;
}

public OnPlayerSpawn(playerid)
{
    return 1;
}

public OnPlayerDeath(playerid, killerid, reason)
{
    return 1;
}

public OnVehicleSpawn(vehicleid)
{
    return 1;
}

public OnVehicleDeath(vehicleid, killerid)
{
    return 1;
}

public OnPlayerText(playerid, text[])
{
    return 1;
}

public OnPlayerCommandText(playerid, cmdtext[])
{
    if (strcmp("/mycommand", cmdtext, true, 10) == 0)
    {
        // Do something here
        return 1;
    }
    return 0;
}

public OnPlayerEnterVehicle(playerid, vehicleid, ispassenger)
{
    return 1;
}

public OnPlayerExitVehicle(playerid, vehicleid)
{
    return 1;
}

public OnPlayerStateChange(playerid, newstate, oldstate)
{
    return 1;
}

public OnPlayerEnterCheckpoint(playerid)
{
    return 1;
}

public OnPlayerLeaveCheckpoint(playerid)
{
    return 1;
}

public OnPlayerEnterRaceCheckpoint(playerid)
{
    return 1;
}

public OnPlayerLeaveRaceCheckpoint(playerid)
{
    return 1;
}

public OnRconCommand(cmd[])
{
    return 1;
}

public OnPlayerRequestSpawn(playerid)
{
    return 1;
}

public OnObjectMoved(objectid)
{
    return 1;
}

public OnPlayerObjectMoved(playerid, objectid)
{
    return 1;
}

public OnPlayerPickUpPickup(playerid, pickupid)
{
    return 1;
}

public OnVehicleMod(playerid, vehicleid, componentid)
{
    return 1;
}

public OnVehiclePaintjob(playerid, vehicleid, paintjobid)
{
    return 1;
}

public OnVehicleRespray(playerid, vehicleid, color1, color2)
{
    return 1;
}

public OnPlayerSelectedMenuRow(playerid, row)
{
    return 1;
}

public OnPlayerExitedMenu(playerid)
{
    return 1;
}

public OnPlayerInteriorChange(playerid, newinteriorid, oldinteriorid)
{
    return 1;
}

public OnPlayerKeyStateChange(playerid, newkeys, oldkeys)
{
    return 1;
}

public OnRconLoginAttempt(ip[], password[], success)
{
    return 1;
}

public OnPlayerUpdate(playerid)
{
    return 1;
}

public OnPlayerStreamIn(playerid, forplayerid)
{
    return 1;
}

public OnPlayerStreamOut(playerid, forplayerid)
{
    return 1;
}

public OnVehicleStreamIn(vehicleid, forplayerid)
{
    return 1;
}

public OnVehicleStreamOut(vehicleid, forplayerid)
{
    return 1;
}

public OnDialogResponse(playerid, dialogid, response, listitem, inputtext[])
{
    return 1;
}

public OnPlayerClickPlayer(playerid, clickedplayerid, source)
{
    return 1;
}

You won't understand most of the code until we get into actual theory, so don't worry if you can't understand anything or if this seems very complex!

Comments

The first thing we notice is the following text:

pawn Код:

// This is a comment
// uncomment the line below if you want to write a filterscript
//#define FILTERSCRIPT

That piece of code is called a comment, this is a way to 'comment' your code, adding explanations.
yes, you can add anything YOU want!
The example above shows a 1-lined comment, comments are not recognized by the compiler (yes, that's okay, that's the idea).

pawn Код:

// Hai I'm Deskoft And I Love To Type Like This

is the correct way to type a 1-lined comment.
While...

pawn Код:

// Hai I'm Deskoft And I Love To Type Like This
But This Is Not Cool Anymore

will show:

Код:

error 010: invalid function or declaration

if we compile it, why? because it's a 1 lined comment.

Hey but it's not that bad, as we have multi-lined comments!

pawn Код:

/*
Tutorial Script by Deskoft
Yay, multi-lined
*/

pawn Код:

/* - Initial Bracket
End bracket - */

Includes

Now we notice a blue line saying:

pawn Код:

#include <a_samp>

It looks complex, you can only understand 8 characters in that random and fancy piece of text ('include').
But it's actually simple, the #include <includename> is the way in Pawn to use a set of tools.
Like the doctors, that use a bag with tools which has alcohol, gauze. etc.
Here, we use 'functions' as our tools, and includes are our sword against the dark world of scripting.
Now, what is <a_samp>? That's the basic include, which gives us the possibility to script into San Andreas Multiplayer. Without that include, we won't be able to use our script in SA-MP.

Main

It was all good, we were having fun with includes, until we checked this code:

pawn Код:

#if defined FILTERSCRIPT

public OnFilterScriptInit()
{
    print("\n--------------------------------------");
    print(" Blank Filterscript by your name here");
    print("--------------------------------------\n");
    return 1;
}

public OnFilterScriptExit()
{
    return 1;
}

#else

main()
{
    print("\n----------------------------------");
    print(" Blank Gamemode by your name here");
    print("----------------------------------\n");
}

#endif

The first line looks impossible, but it's actually very easy...

pawn Код:

#if defined FILTERSCRIPT

We will check #if and OnFilterscriptInit later.
As for now, that's not needed.
Delete everything from #if to OnFilterscriptExit.
And then also remove #endif.

So our code is like this:

pawn Код:

/*
Tutorial Script by Deskoft
*/

#include <a_samp>

main()
{
    print("\n----------------------------------");
    print(" Blank Gamemode by your name here");
    print("----------------------------------\n");
}

public OnGameModeInit()
{
    // Don't use these lines if it's a filterscript
    SetGameModeText("Blank Script");
    AddPlayerClass(0, 1958.3783, 1343.1572, 15.3746, 269.1425, 0, 0, 0, 0, 0, 0);
    return 1;
}

public OnGameModeExit()
{
    return 1;
}

public OnPlayerRequestClass(playerid, classid)
{
    SetPlayerPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraLookAt(playerid, 1958.3783, 1343.1572, 15.3746);
    return 1;
}

public OnPlayerConnect(playerid)
{
    return 1;
}

public OnPlayerDisconnect(playerid, reason)
{
    return 1;
}

public OnPlayerSpawn(playerid)
{
    return 1;
}

public OnPlayerDeath(playerid, killerid, reason)
{
    return 1;
}

public OnVehicleSpawn(vehicleid)
{
    return 1;
}

public OnVehicleDeath(vehicleid, killerid)
{
    return 1;
}

public OnPlayerText(playerid, text[])
{
    return 1;
}

public OnPlayerCommandText(playerid, cmdtext[])
{
    if (strcmp("/mycommand", cmdtext, true, 10) == 0)
    {
        // Do something here
        return 1;
    }
    return 0;
}

public OnPlayerEnterVehicle(playerid, vehicleid, ispassenger)
{
    return 1;
}

public OnPlayerExitVehicle(playerid, vehicleid)
{
    return 1;
}

public OnPlayerStateChange(playerid, newstate, oldstate)
{
    return 1;
}

public OnPlayerEnterCheckpoint(playerid)
{
    return 1;
}

public OnPlayerLeaveCheckpoint(playerid)
{
    return 1;
}

public OnPlayerEnterRaceCheckpoint(playerid)
{
    return 1;
}

public OnPlayerLeaveRaceCheckpoint(playerid)
{
    return 1;
}

public OnRconCommand(cmd[])
{
    return 1;
}

public OnPlayerRequestSpawn(playerid)
{
    return 1;
}

public OnObjectMoved(objectid)
{
    return 1;
}

public OnPlayerObjectMoved(playerid, objectid)
{
    return 1;
}

public OnPlayerPickUpPickup(playerid, pickupid)
{
    return 1;
}

public OnVehicleMod(playerid, vehicleid, componentid)
{
    return 1;
}

public OnVehiclePaintjob(playerid, vehicleid, paintjobid)
{
    return 1;
}

public OnVehicleRespray(playerid, vehicleid, color1, color2)
{
    return 1;
}

public OnPlayerSelectedMenuRow(playerid, row)
{
    return 1;
}

public OnPlayerExitedMenu(playerid)
{
    return 1;
}

public OnPlayerInteriorChange(playerid, newinteriorid, oldinteriorid)
{
    return 1;
}

public OnPlayerKeyStateChange(playerid, newkeys, oldkeys)
{
    return 1;
}

public OnRconLoginAttempt(ip[], password[], success)
{
    return 1;
}

public OnPlayerUpdate(playerid)
{
    return 1;
}

public OnPlayerStreamIn(playerid, forplayerid)
{
    return 1;
}

public OnPlayerStreamOut(playerid, forplayerid)
{
    return 1;
}

public OnVehicleStreamIn(vehicleid, forplayerid)
{
    return 1;
}

public OnVehicleStreamOut(vehicleid, forplayerid)
{
    return 1;
}

public OnDialogResponse(playerid, dialogid, response, listitem, inputtext[])
{
    return 1;
}

public OnPlayerClickPlayer(playerid, clickedplayerid, source)
{
    return 1;
}

Let's analize:

pawn Код:

main()
{
    print("\n----------------------------------");
    print(" Blank Gamemode by your name here");
    print("----------------------------------\n");
}

Remove the text inside the brackets... ( We will learn about print soon)

pawn Код:

main()
{
}

main is called when the server starts and/or the gamemode is loaded.

OnGameModeInit

pawn Код:

public OnGameModeInit()
{
    // Don't use these lines if it's a filterscript
    SetGameModeText("Blank Script");
    AddPlayerClass(0, 1958.3783, 1343.1572, 15.3746, 269.1425, 0, 0, 0, 0, 0, 0);
    return 1;
}

This one is called after main, after the gamemode is loaded.
This is used alot to define EVERYTHING.
We see a comment, and then we see 'SetGameModeText'.
Inside we see some text inside " and "'s.

The 'Mode' (Scratch Roleplay(RP) in the image) is what that sets.

Let's remove AddPlayerClass for now.
So we have this:

pawn Код:

/*
Tutorial Script by Deskoft
*/

#include <a_samp>

main()
{
}

public OnGameModeInit()
{
    // Don't use these lines if it's a filterscript
    SetGameModeText("Blank Script");
    return 1;
}

public OnGameModeExit()
{
    return 1;
}

public OnPlayerRequestClass(playerid, classid)
{
    SetPlayerPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraLookAt(playerid, 1958.3783, 1343.1572, 15.3746);
    return 1;
}

public OnPlayerConnect(playerid)
{
    return 1;
}

public OnPlayerDisconnect(playerid, reason)
{
    return 1;
}

public OnPlayerSpawn(playerid)
{
    return 1;
}

public OnPlayerDeath(playerid, killerid, reason)
{
    return 1;
}

public OnVehicleSpawn(vehicleid)
{
    return 1;
}

public OnVehicleDeath(vehicleid, killerid)
{
    return 1;
}

public OnPlayerText(playerid, text[])
{
    return 1;
}

public OnPlayerCommandText(playerid, cmdtext[])
{
    if (strcmp("/mycommand", cmdtext, true, 10) == 0)
    {
        // Do something here
        return 1;
    }
    return 0;
}

public OnPlayerEnterVehicle(playerid, vehicleid, ispassenger)
{
    return 1;
}

public OnPlayerExitVehicle(playerid, vehicleid)
{
    return 1;
}

public OnPlayerStateChange(playerid, newstate, oldstate)
{
    return 1;
}

public OnPlayerEnterCheckpoint(playerid)
{
    return 1;
}

public OnPlayerLeaveCheckpoint(playerid)
{
    return 1;
}

public OnPlayerEnterRaceCheckpoint(playerid)
{
    return 1;
}

public OnPlayerLeaveRaceCheckpoint(playerid)
{
    return 1;
}

public OnRconCommand(cmd[])
{
    return 1;
}

public OnPlayerRequestSpawn(playerid)
{
    return 1;
}

public OnObjectMoved(objectid)
{
    return 1;
}

public OnPlayerObjectMoved(playerid, objectid)
{
    return 1;
}

public OnPlayerPickUpPickup(playerid, pickupid)
{
    return 1;
}

public OnVehicleMod(playerid, vehicleid, componentid)
{
    return 1;
}

public OnVehiclePaintjob(playerid, vehicleid, paintjobid)
{
    return 1;
}

public OnVehicleRespray(playerid, vehicleid, color1, color2)
{
    return 1;
}

public OnPlayerSelectedMenuRow(playerid, row)
{
    return 1;
}

public OnPlayerExitedMenu(playerid)
{
    return 1;
}

public OnPlayerInteriorChange(playerid, newinteriorid, oldinteriorid)
{
    return 1;
}

public OnPlayerKeyStateChange(playerid, newkeys, oldkeys)
{
    return 1;
}

public OnRconLoginAttempt(ip[], password[], success)
{
    return 1;
}

public OnPlayerUpdate(playerid)
{
    return 1;
}

public OnPlayerStreamIn(playerid, forplayerid)
{
    return 1;
}

public OnPlayerStreamOut(playerid, forplayerid)
{
    return 1;
}

public OnVehicleStreamIn(vehicleid, forplayerid)
{
    return 1;
}

public OnVehicleStreamOut(vehicleid, forplayerid)
{
    return 1;
}

public OnDialogResponse(playerid, dialogid, response, listitem, inputtext[])
{
    return 1;
}

public OnPlayerClickPlayer(playerid, clickedplayerid, source)
{
    return 1;
}

OnGameModeExit, OnPlayerRequestClass

So we checked OnGameModeInit, now we have:

pawn Код:

public OnGameModeExit()
{
    return 1;
}

This one is basically called when the gamemode is unloaded, either the server is closed, restarted or changing of gamemode.

pawn Код:

public OnPlayerRequestClass(playerid, classid)
{
    SetPlayerPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraLookAt(playerid, 1958.3783, 1343.1572, 15.3746);
    return 1;
}

Now we have that too.
Let's remove the text inside

pawn Код:

public OnPlayerRequestClass(playerid, classid)
{
    return 1;
}

That basically is called when the player requests a class (pressed the arrow keys before spawning, you will see more on this later).

pawn Код:

public OnPlayerConnect(playerid)
{
    return 1;
}

public OnPlayerDisconnect(playerid, reason)
{
    return 1;
}

OnPlayerConnect is called when a player joins the server.
When the player is leaving the server, OnPlayerDisconnect is called.

pawn Код:

public OnPlayerSpawn(playerid)
{
    return 1;
}

public OnPlayerDeath(playerid, killerid, reason)
{
    return 1;
}

OnPlayerSpawn is called when the player spawns (either when he joins or when he is respawned or when he dies).
OnPlayerDeath is called when the player dies.

pawn Код:

public OnVehicleSpawn(vehicleid)
{
    return 1;
}

public OnVehicleDeath(vehicleid, killerid)
{
    return 1;
}

OnVehicleSpawn is called when a vehicle is spawned (or re-spawns).
OnVehicleDeath is called when the vehicle is destroyed.

pawn Код:

public OnPlayerText(playerid, text[])
{
    return 1;
}

OnPlayerText is called when the players writes something in the chat.

Now we have...

pawn Код:

public OnPlayerCommandText(playerid, cmdtext[])
{
    if (strcmp("/mycommand", cmdtext, true, 10) == 0)
    {
        // Do something here
        return 1;
    }
    return 0;
}

Let's do it simple, and remove the text inside (but return 0).

pawn Код:

public OnPlayerCommandText(playerid, cmdtext[])
{
    return 0;
}

This will be called when they type a command (/help, /hi, /imnew).

pawn Код:

public OnPlayerEnterVehicle(playerid, vehicleid, ispassenger)
{
    return 1;
}

public OnPlayerExitVehicle(playerid, vehicleid)
{
    return 1;
}

OnPlayerEnterVehicle is called when they enter the vehicle, OnPlayerExitVehicle is called when they exit the vehicle, logically.

Those are the basic callbacks, the other callbacks will be explain in the following chapters.

Chapter 3: Variables

So maybe we have doubts, maybe we don't, but if you have reached to this point, then congratulations, because you have made the first step in being a good scripter!
It's really important that you read all the things I have typed above.
But now we are going to learn real stuff.


This tutorial is under construction

[AndreT]

You should first cover everything basic - statements, functions, variables, arrays, strings - how they work and so on. Also link to some useful documentation:
www.compuphase.com/pawn/Pawn_Language_Guide.pdf
www.compuphase.com/pawn/String_Manipulation.pdf

[Deskoft]

Quote:

Originally Posted by AndreT You should first cover everything basic - statements, functions, variables, arrays, strings - how they work and so on. Also link to some useful documentation: www.compuphase.com/pawn/Pawn_Language_Guide.pdf www.compuphase.com/pawn/String_Manipulation.pdf

Yes, that's a must (logically). We are first explaining the callbacks though.

[Darnell]

This is awesome, good job.

[juraska]

Very useful tutorial for beginers
Great tutorial !

[Deskoft]

The tutorial is still under construction, but thanks!

[linuxthefish]

Hotlinking images..

[Deskoft]

Quote:

Originally Posted by linuxthefish Hotlinking images..

I'm the owner of lawedan.org maybe?

[AndreT]

Quote:

Originally Posted by Deskoft We are first explaining the callbacks though.

You're first explaining Cartesian coordinates and angles. That is very wide yet somewhat specific knowledge which on the first look has nothing to do with PAWN coding.

[Deskoft]

Quote:

Originally Posted by AndreT You're first explaining Cartesian coordinates and angles. That is very wide yet somewhat specific knowledge which on the first look has nothing to do with PAWN coding.

That's previous knowledge, clearly explained in the chapter title.

Later, I clearly point out:

Код:

During this course, you will understand that mathematics is a very important point in programming and scripting.

After explaining all the callbacks, now we are going to 'start learning real stuff'.
includes variables. Thanks for your suggestion though, we really appreciate it (and thank you for the links, even though I already read the PDFs when I was learning PAWN, they will always help the new members).