PAWN tutorial
From SA-MP Wiki
Contents |
Making a basic deathmatch
Making a basic deatchmatch in PAWN couldn't be simpler. Simply open up Pawno (see Scripting Editors) and click new. There you have it, your first script. To run it first save it (most people save it to "<San Andreas Install Directory>/samp/gamemodes/src/" but it is easier (for local testing) to save it to "<SA>/samp/gamemodes/"), then click the button on the toolbar to the immediate left of the blue arrow button. This will compile your .pwn file to a .amx in the same folder, however for the game to see it it needs to be in "<SA>/samp/gamemodes/" (see why saving there was easier, that makes it already there after compiling). Now to test your map you will need to set up a local server and change to your mode (type "changemode <your mode name>" in the server window).
If all that worked, when you connect to your server through the sa-mp client and the game starts you should appear outside a casino in Las Venturas. Unfortunately you won't be able to see the character you are selecting (there is currently only one) but we can easily change that later. It is also not a very interesting deathmatch as you only have fists to fight with and no opponents, but as this is a local server there is currently not a lot we can do about the second problem.
Now the first thing you are likely to want to add to your mode is weapons, these are controlled on a "per class" basis. Every player you have to select from at the start of a game (or later if you change) is called a player "class". They may all have the same weapons or all different, or a combination. You set each classes weapons separately, so to make them all have the same weapon you would simply copy the weapon data and add it to each class, this will guarantee a balanced match but is not too interesting, however it is up to you. In the editor search for this line:
AddPlayerClass(0, 1958.3783, 1343.1572, 15.3746, 269.1425, 0, 0, 0, 0, 0, 0);
This is a class definition, the parameters are as follows:
AddPlayerClass(Player model, X, Y, Z, A, Weapon 0, Ammo 0, Weapon 1, Ammo 1, Weapon 2, Ammo 2);
Player model can be got from "peds.ide", "X", "Y" and "Z" are the co-ordinates of where the player will spawn when selected and "A" is their facing angle, there is one spawn point per class, however this can be got around with coding which will be covered later. The weapon numbers can be found here and the ammo numbers are simply the amount of ammo you want to give the player per weapon (melee weapon ammo is always 0).
Now copy this line:
AddPlayerClass(102, 1958.3783, 1343.1572, 15.3746, 269.1425, 5, 0, 22, 100, 32, 50);
and place it under the line you found in your script. You will now have a choice ingame between CJ with nothing and a Balla with a baseball bat, pistol and Tec9, if you want to even this up try adding your own weapons to CJ or adding more player classes under these with other weapons.
Note: the weapons listed on the page linked to above which say "(crashes if you try to fire)" or "(Unusable)" do not work with SA-MP either.
Getting co-ordinates, angles and model ids
You will probably want to move some of your spawn points about so everyone doesn't spawn in the same place, which would make a rather boring deathmatch and camping amazingly easy. This is where the debug mode comes in. Run "samp_debug.exe" in your San Andreas root directory and whenever you want to save a co-ordinate type "/save" in the game (press "t" or the key under escape to bring up the text/chat prompt). This will save your current position, angle and playerid to a file called "savedpositions.txt" in your SA root directory.
Introduction to functions and callbacks
Before we can continue you will need to be introduced to callbacks. These are the chunks of code already in your gamemode that look something like this:
public OnPlayerDisconnect(playerid) { printf("OnPlayerDisconnect(%d)", playerid); return 1; }
This is the OnPlayerDisconnect callback, that means this section of code is run by the server whenever a player disconnects, so if you want to show a big message on the screen when a player leaves you would put the code for that here. All the callbacks the game uses (except 2, but they are used by filterscripts, not gamemodes and are not covered here) are in your file, you cannot make up your own. Most of them appear as the one above does, but some (i.e. "OnPlayerCommandText", "OnPlayerRequestClass", "OnGameModeInit" and "main" (which is not strictly a callback and never has more than your game title)) have other bits in already, either to make the game work or to show you what to do there. You may also use other, similar blocks (as we are about to) which look the same but are called functions, these have to be called by you yourself. Here is a function called "IMadeThis" (note the lack of spaces).
IMadeThis() { // This is a comment and is ignored by the game/compiler /* So is this */ print("This will be printed to the server window"); return 0; }
You may have also noticed a very quick introduction to comments there, everything on a line after "//" will be ignored, as will anything anywhere between "/*" and "*/". As a function is not called by the game we need to call it ourselves from a callback, this is dead easy as most of the commands you use to code with are in fact premade functions (commands are in fact different), so if you placed:
IMadeThis();
in your OnPlayerDisconnect callback (it must be between the "{" and "}" and also before the "return 1;" it would run that function and print a message in the server window when you disconnected (remember the other things in there are ignored). We don't generally want to print things to the server window and all the "print" and "printf" functions already in the file are generally removed by the coder. Only things between the braces are in the function/callback (from now on function refers to callbacks as well as they are a special case of function), the line above is the name of the function. "public" means the function can be run by any other bit of code, this basically means your code can be run when you call it, we're not worried about private functions as they are not generally used in SA-MP (if at all). The brackets after the function name enclose the parameters list, we haven't covered these yet but you can see an example of their usage in some of the callbacks in your blank file, note that those parameters are automatically passed when the game calls the function, if we are using a custom functions (i.e. not a callback) and we want to use some parameters we will need to pass them ourselves. One tiny other thing which should be mentioned is that all lines apart from lines with braces on (and even them in certain circumstances, but these will be covered later) and lines directly before an open brace (braces may be on the end of that line or, as shown here, on a new line), end with a semicolon to denote the end of a process.
Making a team deathmatch
OK, now you know how to make classes and place them about we will show you how to set teams, this will be the first bit of real coding but is fairly easy. I will just be using the two classes described on this page so if you have more remove them for now or start a new mode and make sure only those two are in. Classes are numbered in order from 0, so the first class in your file is 0, the second is 1 and so on (computers and programs nearly always start from 0 in counting (you will find that your playerid in a test game is 0)). We want to set the team based on which class they choose (either Grove or Balla), you may look at the callbacks and think that this would go in the OnPlayerRequestClass function, and you would be correct. When the select their class you want to set the team based on that, we can't do it in the OnPlayerSpawn function as at that point we don't know the class they have selected (that is a parameter and only parameters we are passed or which are global in your script (we will cover this later) can be used in any function). First we need to define our teams, under the "#include" line(s) at the top of your file add these lines:
#define TEAM_GROVE 1 #define TEAM_BALLA 2 #define TEAM_GROVE_COLOR 0x00FF00AA // Bright Green (in RGBA format) #define TEAM_BALLA_COLOR 0xFF00FFAA // Bright Purple
If you want to alter the colors, that's fine, just remember that the last two digits are the alpha and the lower that is the less you can see the color. Defines are purely replacements, now if you ever want to use the number 1 in your script you can use TEAM_GROVE instead, this is not a good idea for normal calculations as it makes them harder to read, but for using to denote teams, which are only denoted by a number, it makes it a lot clearer what's going on (and makes it very easy to change the teams around or modify later as you need only change the 1 in the define rather than all the instances of it throughout the code. When the code is compiled, all the "TEAM_GROVE"s will be replaced by 1, it is not like a variable, it is a constant, it doesn't change. Now under those lines add:
new gTeam[MAX_PLAYERS];
This is called a global array. An array is basically lots of variables (places you store data to read and write) clumped together to store lots of data at once. The "MAX_PLAYERS" is a pre-defined constant (done in exactly the same way as we did our defines. MAX_PLAYERS is actually set at 500 in SA-MP 0.3a, so this means that our array can store up to 500 pieces of data. The g on the name means global, but that doesn't make it global (it just makes it easier to tell what variables do what, defining it outside a function means it is global and can be used by all our functions. Any variable defined in a function is local to that function and it can't have the same name as another variable in the same function or a global variable (which is also why the g is useful), it can however have the same name as another variable in another function. All the "playerid" variables in your blank script are in fact all independent variables, each local to a different function, however they are all passed the same data, but just remember that any functions you make won't automatically have that data. Now we have that set up we can set the teams:
SetPlayerTeamFromClass(playerid, classid) { if (classid == 0) { gTeam[playerid] = TEAM_GROVE; } else { gTeam[playerid] = TEAM_BALLA; } }
Place that code OUTSIDE a function in your code (as it is a new function) and put these lines as the first things after the open curly braces in your OnPlayerRequestClass callback (notice the way the variables are not global so we are having to pass them to out function too):
SetPlayerTeamFromClass(playerid, classid);
This will save the players team to an array through our new function. Data in an array is referenced by a number, so array[0] is the first item of data, array[1] is the second and so on, as we are using gTeam[playerid], depending on which playerid we are passed will define where in the array to store the data, so for player 5 their data will be stored at array position 5 (remember, this is the 6th piece of data). Now copy this function:
SetPlayerToTeamColor(playerid) { if (gTeam[playerid] == TEAM_GROVE) { SetPlayerColor(playerid, TEAM_GROVE_COLOR); } else if (gTeam[playerid] == TEAM_BALLA) { SetPlayerColor(playerid, TEAM_BALLA_COLOR); } }
And add the following line to OnPlayerSpawn:
SetPlayerToTeamColor(playerid);
We now have our teams, but what have we actually done?
if (classid == 0) { gTeam[playerid] = TEAM_GROVE; }
In our first function, we check which class they chose (remember we said that the first class defined in your file was class 0?) "==" means "is equal to", a single equals sign simply sets the variable to the number given (as seen on the next line but one). The curly braces separate the functions between them from the rest of the code, bits in there are only executed if the selected class is 0 (cj), if it isn't, the else command comes into play and executes instead (this executes whenever the "if" command is false (i.e. the class isn't 0)), since we only have two classes to choose from this must mean we're Balla:
else { gTeam[playerid] = TEAM_BALLA; }
We don't need a return here as there is no data to return.
The second half set the players' color when they spawn, so you can tell who's on which team. As we saved their team to a global array, we can still access the data even though it is in a separate function.
if (gTeam[playerid] == TEAM_GROVE) { SetPlayerColor(playerid, TEAM_GROVE_COLOR); }
Hopefully you can see what this is doing now, if the player who just spawned (as referenced by playerid) is in TEAM_GROVE, we set their color to TEAM_GROVEs color.
else if (gTeam[playerid] == TEAM_BALLA) { SetPlayerColor(playerid, TEAM_BALLA_COLOR); }
This next section is a little different, it could easilly have been done like this:
else { SetPlayerColor(playerid, TEAM_BALLA_COLOR); }
But the way it is done allows you to set their color to TEAM_BALLAs color only if the first part is false (as sorted by the ELSE) AND if they are in TEAM_BALLA, this allows you to add more options by adding more "else if ()" blocks to the end as one will only be executed if all the blocks before it weren't.
Vehicles
OK, if you have previous chapters you should have a very basic deathmatch or team-deathmatch with spawns placed wherever you want, so lets add some vehicles. Most of the commands in PAWN do pretty much exactly as they're named, we want to add a vehicle so lets look for vehicle commands:
CreateVehicle(); AddStaticVehicle();
If you click on either of these and look in the status bar (the bar at the bottom of the editor) you will see their syntax (what information/parameters you need to give them to work):
[a_samp.inc] native CreateVehicle(vehicletype, Float:x, Float:y, Float:z, Float:rotation, color1, color2, respawn_time); [a_samp.inc] native AddStaticVehicle(modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, color1, color2);
Now they both look equally as good, but this is where prior knowledge comes in, CreateVehicle only places one car ingame, AddStaticVehicle creates a vehicle spawn, so when the car is destroyed or desynched it will reappear back where you placed the spawn. These need to be created at the start of the game so you would place this in your "OnGameModeInit()" callback.
I got these co-ordinates:
2040.2279, 1344.4127, 11.0, 3.5436
Note: These are called floats, 11.0 is a float despite being whole, any whole number being used as a float must have a trailing ".0" to denote it as a float. These numbers are in the english format of using a decimal point ("."), commas are used to separate parameters. Also remember the 4th number is angle, so if we now add the following line to the game mode in OnGameModeInit, recompile and test, we will get a bright pink infernus outside the casino which is the default spawn position for CJ. Note: on a car which uses the secondary color (such as a cop car (id 596)) this would be a pink and blue car as that is the secondary color.
AddStaticVehicle(411, 2040.2279, 1344.4127, 10.6719, 3.5436, 126, 54);
Now you can easily go about saving positions and creating as many cars as you want, up to an engine defined limit of 2000 individual cars of any model. However, since vehicles are dynamically streamed, it is a good idea to keep the number of vehicle models below 150.
