ScriptingInterface

Summary

The GTAC scripting interface aims to be enjoyable to use.
Goals include: clean, easy to use, minimal typing, consistent, no duplicate functionality, and wrappable.

Scripting Languages

There are currently three scripting languages used. JavaScript, Lua, and Squirrel.
Multiple scripting languages can be used in the same server/client instance, and even in the same resource.

Example
meta.xml:

<meta>
	<script language="lua" type="server" src="script1.lua" />
	<script language="lua" type="client" src="script1.lua" />
	<script language="javascript" type="server" src="script1.js" />
	<script language="javascript" type="client" src="script1.js" />
	<script language="squirrel" type="server" src="script1.nut" />
	<script language="squirrel" type="client" src="script1.nut" />
</meta>

Item Handles

Item handles are used to refer to items that are created, whether the item is created by a resource, a module, or by GTAC.

List of data types used for item handles in different scripting languages:

Scripting Language	Data Type
JavaScript	Object
Lua	Userdata
Squirrel	Object

Example (Lua)

local vehicle = gta.createVehicle(..) -- vehicle is an item handle

Item Existence & Item Properties

Item Creation & Item General Functionality

Global functions are used to create an item, and are also used for general functionality.

Example

gta.createVehicle(..)
getVehicles(..)

Item Destroying

Global functions are used to destroy an item.

Example (Lua)

local vehicle = gta.createVehicle(..)
destroyElement(vehicle)

Item Setters and Getters

The majority of item attributes are applied and fetched via OOP properties. OOP methods are used too.
Either an OOP property or an OOP method is used per functionality, not both.

OOP properties are used when a single value can be applied or fetched for an item.

Example (Lua)

local vehicle = gta.createVehicle(..)
vehicle.health = 1000
print(tostring(vehicle.health))

OOP methods are used when it is not appropriate to use an OOP property.

Example (Lua)

local vehicle = gta.createVehicle(..)
vehicle:respawn()

Signatures

Naming Convention

Lower camel case is used as the naming convention for all functionality provided, except event names which are case-insensitive.
This means that variable, function, property & method names start with a lowercase letter, and event names can be any case.

Example (Lua)

local Var = gta.createVehicle(..) -- function name "createVehicle" in global table "gta".
Var:fix() -- method name "fix"
addEventHandler('onElementStreamIn', function() end) -- event name "onElementStreamIn"
addEventHandler('ONelementSTREAMin', function() end) -- event name "onElementStreamIn"

-- In this example, "Var" is a variable name, and naming conventions for variables are managed by the scripting languages, not by GTAC.
-- Most scripting languages will allow you to use any text case for variable naming.
-- "Var" could well have been "var", and probably should be for Lua, because some scripting languages have preferred naming rules for implementation by coders.

Multiple Signatures

A global function or a method may use more than one signature.

Item Type Values

Angles

Radians are used as the angle measurement unit, not degrees.
Implicit modulo division occurs for angle input to functionality.

Example (Lua)

addEventHandler('onPlayerSpawn',function(event,ped)
    ped.heading = math.rad(450.0)
    print(tostring(ped.heading)) -- math.rad(90.0)
end)

Vectors and Arrays

Arrays of size 2 can be used in place of vec2 for input to functionality.
Arrays of size 3 can be used in place of vec3 for input to functionality.

Example (Lua)

addEventHandler('onPlayerSpawn',function(event,ped)
    ped.position = vec3(50,80,110)
    ped.position = {50,80,110}
end)

Validation

Input Validation

Global functions and methods provided have their input parameter count validated.
All functionality provided has input data type(s) validated. Integer and float are considered different in languages that natively differentiate them.

Resource Errors

For scripting launch errors, the resource is not loaded.
For scripting callback errors, the resource continues as normal, and the callback invocation instance is aborted natively.

Example (Lua)

addEventHandler('onPlayerSpawn',function(event,ped)
    ped.heading = 'a string' -- should be a number of course
    -- this lambda function can be invoked more than once
end)

Example

gta.createVehicle(void) -- fails
getVehicles('unusedArgument') -- fails
gta.createVehicle(false) -- fails

Other

Wrappable

Provided functionality has no restrictions on wrapping.
However, events (observer pattern) should always be used instead when the applicable event is provided, to prevent resource conflictions.

Wrapping Example (Lua)

gta.createVehicle = function(...)
    someFunc(...)
    gta.createVehicle(...)
end

Backward Compatibility

Backward compatibility is supported for all functionality, excluding when a confliction would occur.