Conventions

Rules shared by the whole API: script sides, elements, root and source, coordinates and error handling.

Server, client, both sides

Every function and event shows where it works:

Mark	Side	Where you use it
S	Server	`type="server"` scripts
C	Client	`type="client"` scripts
B	Both	any script, including `type="shared"`

Some shared functions have a shorter syntax on the client, because they always apply to the local player. For example outputChatBox on the server takes a player, while on the client it writes straight to that player's chat. Such differences are described on the function's page.

Elements

Players, vehicles, objects, markers, GUI windows and sounds are elements. Functions take them as arguments and events pass them as source. isElement(x) checks whether an element still exists.

Elements form a tree. At the top is root, and under it every resource has its own resourceRoot. A handler attached to root catches the event of every element, one attached to resourceRoot only those of that resource's elements.

Built-in variables

Variable	Side	Meaning
`root`	both	root of the element tree
`resourceRoot`	both	root of the current resource's elements
`source`	both	the element the event is about
`localPlayer`	client	the player the script runs for
`client`	server	the player who sent the event with `triggerServerEvent`

Coordinates

You give a position as three numbers x, y, z in game world metres. The map centre is 0, 0, Los Santos is in the south-east (positive x, negative y), and z is height. Rotations are in degrees.

Errors and bad arguments

A bad argument does not stop the script. The function returns false and the console shows a warning with the function name and the argument number:

Bad argument @ 'setPlayerMoney' [expected player at argument 1, got string 'Adam']

An out-of-range value is also rejected rather than clamped, unless the function's description says otherwise. That is why it is worth checking the result of functions that create something:

local car = createVehicle(411, 0, 0, 3)
if not car then
    outputDebugString("Could not create the car")
    return
end

Custom events

You register an event with addEvent("name"). If the client is going to trigger it, the server must register it with true as the second argument: addEvent("name", true). Without it the server rejects the event from the player. Details in triggerServerEvent and triggerClientEvent.

Lua 5.4 and scripts from MTA

Scripts run on Lua 5.4. For compatibility with scripts written for Lua 5.1 (MTA) there are math.atan2(y, x) (in 5.4 that is math.atan(y, x)), math.pow(x, y) (same as x ^ y) and math.log10(x). Division / always gives a float (7 / 2 = 3.5); integer division is //.

Limitations and workarounds

Collision between just two elements (setElementCollidableWith) does not exist yet. Ghost-mode workaround: setElementCollisionsEnabled(otherCar, false) on the client plus transparency (setElementAlpha); such a car collides with nothing for that player, so only enable it for the start of a round.
The game map on the server: the server has no collision for buildings or terrain, so processLineOfSight, isLineOfSightClear and getGroundPosition on the server only see script elements. Do an exact test against the map in a client script and send the result with triggerServerEvent.
NPC damage on the client: there is onClientPlayerDamage (your own ped); NPC damage is reported by the server in onPedDamage.