Scripting Introduction

Resources are a key part of MTA. A resource is essentially a folder or zip file that contains a collection of files, plus a meta file that describes to the server how the resource should be loaded and what files it does contain. A resource can be seen as being partly equivalent to a program running in an operating system - it can be started and stopped, and multiple resources can run at once.

Everything that has to do with scripting happens in resources, what a resource does defines if it is a gamemode, a map or anything else.

Creating a simple script

Firstly, we want to write something that adds a 'createvehicle' command players can use to spawn a vehicle beside their position.

Preparations

As decribed above, a resource is a folder or zip file, so first you should create a folder. The folder name is the name of the resource, that is used to start or stop it or reference in scripts. In our example, we shall call it commands.

What every resource has and needs is the meta.xml file. In our case, we want to create a script that provides some simple commands to the user, thus we need to tell the server to load a script file, we name script.lua in our case.

<meta>
  <info author="YourName" description="A few simple commands" />
  <script src="script.lua" />
 </meta>

Now we have to create the script.lua file we defined above in the same directory as the meta.xml. Now we have the both files:

/commands/meta.xml
/commands/script.lua

Writing the script

Let's start with the contents of the script.lua file. As mentioned above, we want to provide a command to create a vehicle beside your current position in the game. Firstly we need to create a function we want to call and a command handler that creates the command the player will be able to enter in the console.

-- create the function the command handler calls, with the arguments: thePlayer, command, vehicle
function createVehicleForPlayer(thePlayer, command, vehicle)
   -- create a vehicle and stuff
end

-- create a command handler
addCommandHandler("createvehicle", createVehicleForPlayer)

Please note that function names are clickable in code examples on the wiki, which will lead you to the functions' documentation.

About command handlers

The first argument of addCommandHandler is the name of the command the player will be able to enter, the second argument is the function this will call, in this case createVehicleForPlayer.

If you have already experience in scripting, you will know that you call a function like this:

functionName(argument1, argument2, argument3, ..)

We called the addCommandHandler function this way already and since createVehicleForPlayer is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.

For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as if we would have this line of code in the script:

createVehiceForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command

As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. Those parameters are the same with all command handlers, which you can read on the AddEventHandler page.

Writing the function

In order to fill the function we created, we need to think about what we have to do:

• Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)
• Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)
• Spawn the vehicle
• Check if it has been spawned successfully, or output a message

In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the Server Functions List. First we need a function to get the players position. Since players are Elements, we first jump to the Element functions where we find the getElementPosition function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.

For getElementPosition, the syntax is:

float, float, float getElementPosition ( element theElement )

The three float in front of the function name are the return type. In this case it means the function returns three floating point numbers. Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.

function createVehicleForPlayer(thePlayer, command, vehicle)
	-- get the position and put it in the x,y,z variables
	-- (local means, the variables only exist in the current scope, in this case, the function)
	local x,y,z = getElementPosition(thePlayer)
end

Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the x variable, which will make it spawn east from the player.

function createVehicleForPlayer(thePlayer, command, vehicle)
	local x,y,z = getElementPosition(thePlayer) -- get the position of the player
	x = x + 5 -- add 5 units to the x position
end

Now we need another function, one to spawn a vehicle. We once again search for it on the Server Functions List, this time - since we are talking about vehicles - in the Vehicle functions section, where we will choose createVehicle. In this functions' syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.

We already have all arguments we need in our functions, the position (x,y,z) and the model that we provided in the command ("createvehicle 468") and can access in the function as vehicle variable.

function createVehicleForPlayer(thePlayer, command, vehicle)
	local x,y,z = getElementPosition(thePlayer) -- get the position of the player
	x = x + 5 -- add 5 units to the x position
	-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable
	local createdVehicle = createVehicle(tonumber(vehicle),x,y,z)
end

Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the createVehicle page under Returns, the function returns false when it was unable to create the vehicle. Thus, we check the value of the createVehicle variable.

function createVehicleForPlayer(thePlayer, command, vehicle)
	local x,y,z = getElementPosition(thePlayer) -- get the position of the player
	x = x + 5 -- add 5 units to the x position
	local createdVehicle = createVehicle(tonumber(vehicle),x,y,z)
	-- check if the return value was ''false''
	if (createdVehicle == false) then
		-- if so, output a message to the chatbox, but only to this player.
		outputChatBox("Failed to create vehicle.",thePlayer)
	end
end

As you can see, we introduced another function with outputChatBox. By now, you should be able to explore the function's documentation page yourself.