Coding Convention

From GTA Connected
Jump to navigation Jump to search


Summary[edit]

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[edit]

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[edit]

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 = createVehicle(..) -- vehicle is an item handle

Item Existence & Item Properties[edit]

Item Creation & Item General Functionality[edit]

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

Example

Item Destroying[edit]

Global functions are used to destroy an item.

Example (Lua)

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

Item Setters and Getters[edit]

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 = 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 = createVehicle(..)
vehicle:respawn()

Signatures[edit]

Naming Convention[edit]

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 = createVehicle(..) -- global function name "createVehicle"
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[edit]

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

Item Type Values[edit]

Angles[edit]

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[edit]

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[edit]

Input Validation[edit]

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[edit]

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

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

Other[edit]

Wrappable[edit]

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)

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

Backward Compatibility[edit]

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