Mex at 14:02, 10 May 2020

2020-05-10T14:02:36Z

New page

{{DISPLAYTITLE:Scripting Interface}}

= Summary =

The GTAC scripting interface aims to be enjoyable to use.<br>
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.<br>
Multiple scripting languages can be used in the same server/client instance, and even in the same resource.

'''Example'''<br>
<code>meta.xml:</code>
{{InformationBox|1=<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:

{| class="wikitable"
! style="text-align: left;" | Scripting Language
! style="text-align: left;" | Data Type
|-
|JavaScript
|Object
|-
|Lua
|Userdata
|-
|Squirrel
|Object
|}

'''Example''' (Lua)
{{LuaCode|1=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.<br>

'''Example'''
{{LuaCode|1=gta.createVehicle(..)
getVehicles(..)}}

=== Item Destroying ===

Global functions are used to destroy an item.

'''Example''' (Lua)
{{LuaCode|1=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.<br>
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)
{{LuaCode|1=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)
{{LuaCode|1=local vehicle = gta.createVehicle(..)
vehicle:respawn()}}

= Signatures =
=== Naming Convention ===

[https://en.wikipedia.org/wiki/Camel_case Lower camel case] is used as the naming convention for all functionality provided, except event names which are case-insensitive.<br>
This means that variable, function, property & method names start with a lowercase letter, and event names can be any case.<br>

'''Example''' (Lua)
{{LuaCode|1=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.<br>
Implicit modulo division occurs for angle input to functionality.

'''Example''' (Lua)
{{LuaCode|1=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.<br>
Arrays of size 3 can be used in place of vec3 for input to functionality.

'''Example''' (Lua)
{{LuaCode|1=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.<br>
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.<br>
For scripting callback errors, the resource continues as normal, and the callback invocation instance is aborted natively.

'''Example''' (Lua)
{{LuaCode|1=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'''
{{LuaCode|1=gta.createVehicle(void) -- fails
getVehicles('unusedArgument') -- fails
gta.createVehicle(false) -- fails}}

= Other =
=== Wrappable ===

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

'''Wrapping Example''' (Lua)
{{LuaCode|1=gta.createVehicle = function(...)
someFunc(...)
gta.createVehicle(...)
end}}

=== Backward Compatibility ===

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

ScriptingInterface - Revision history

Mex at 14:02, 10 May 2020