Types: Difference between revisions

From GTA Connected
Jump to navigation Jump to search
No edit summary
No edit summary
 
(9 intermediate revisions by the same user not shown)
Line 9: Line 9:
* {{Side|client=1}} <code>Effect</code> - effect (FX)
* {{Side|client=1}} <code>Effect</code> - effect (FX)
*  {{Side|shared=1}} <code>Element</code> - element
*  {{Side|shared=1}} <code>Element</code> - element
** {{Side|shared=1}} <code>Transformable</code> - (2D / 3D) positionable element
** {{Side|shared=1}} <code>Blip</code> - blip
*** {{Side|shared=1}} <code>Blip</code> - blip
** {{Side|shared=1}} <code>Entity</code> - entity
*** {{Side|shared=1}} <code>Entity</code> - entity
*** {{Side|shared=1}} <code>Building</code> - building (GTA Building)
**** {{Side|shared=1}} <code>Building</code> - building (GTA Building)
*** {{Side|shared=1}} <code>Physical</code> - object that interacts with physics
**** {{Side|shared=1}} <code>Physical</code> - object that interacts with physics
**** {{Side|shared=1}} <code>Object</code> - placeable object
***** {{Side|shared=1}} <code>Object</code> - placeable object
**** {{Side|shared=1}} <code>Ped</code> - pedestrian
***** {{Side|shared=1}} <code>Ped</code> - pedestrian
***** {{Side|shared=1}} <code>Player</code> - player
****** {{Side|shared=1}} <code>Player</code> - player
**** {{Side|shared=1}} <code>Vehicle</code> - any vehicle
***** {{Side|shared=1}} <code>Vehicle</code> - any vehicle
***** {{Side|shared=1}} <code>Train</code> - train
****** {{Side|shared=1}} <code>Train</code> - train
** {{Side|shared=1}} <code>Marker</code> - marker
*** {{Side|shared=1}} <code>Marker</code> - marker
** {{Side|shared=1}} <code>Pickup</code> - pickup
*** {{Side|shared=1}} <code>Pickup</code> - pickup
* {{Side|shared=1}} <code>Event</code> - event
* {{Side|shared=1}} <code>Event</code> - event
** {{Side|shared=1}} <code>CancellableEvent</code> - cancellable event
** {{Side|shared=1}} <code>CancellableEvent</code> - cancellable event
** {{Side|shared=1}} <code>KeyEvent</code> - key vent
** {{Side|shared=1}} <code>KeyEvent</code> - key event
* {{Side|client=1}} <code>Font</code> - font
* {{Side|client=1}} <code>Font</code> - font
* {{Side|client=1}} <code>GUIElement</code> - gui element
* {{Side|client=1}} <code>GUIElement</code> - gui element
Line 30: Line 29:
* {{Side|client=1}} <code>GUIPage</code> - gui page
* {{Side|client=1}} <code>GUIPage</code> - gui page
* {{Side|client=1}} <code>GUIWindow</code> - gui window
* {{Side|client=1}} <code>GUIWindow</code> - gui window
* {{Side|shared=1}} <code>Matrix4x4</code> - matrix of 4 by 4 numbers
* {{Side|shared=1}} <code>Matrix4x4</code> - matrix of 4 by 4 decimal numbers
* {{Side|shared=1}} <code>ReflectedFunction</code> - reflected function
* {{Side|shared=1}} <code>ReflectedFunction</code> - reflected function
* {{Side|shared=1}} <code>Resource</code> - resource
* {{Side|shared=1}} <code>Resource</code> - resource
Line 39: Line 38:
** {{Side|client=1}} <code>Texture</code> - texture - derives from <code>Surface</code>
** {{Side|client=1}} <code>Texture</code> - texture - derives from <code>Surface</code>
* {{Side|shared=1}} <code>Timer</code> - timer
* {{Side|shared=1}} <code>Timer</code> - timer
* {{Side|shared=1}} <code>Vec2</code> - vector of 2 numbers
* {{Side|shared=1}} <code>Vec2</code> - vector of 2 decimal numbers
* {{Side|shared=1}} <code>Vec3</code> - vector of 3 numbers
* {{Side|shared=1}} <code>Vec3</code> - vector of 3 decimal numbers
* {{Side|shared=1}} <code>XmlDocument</code> - xml document
* {{Side|shared=1}} <code>XmlDocument</code> - xml document
* {{Side|shared=1}} <code>XmlElement</code> - xml element
* {{Side|shared=1}} <code>XmlElement</code> - xml element
Line 49: Line 48:


{{InformationBox|1=
{{InformationBox|1=
Blip : Transformable : Element
Blip : Element
Building : Entity : Transformable : Element
Building : Entity : Element
Marker : Transformable : Element
Marker : Element
Object : Physical : Entity : Transformable : Element
Object : Physical : Entity : Element
Pickup : Transformable : Element
Pickup : Element
Player : Ped : Physical : Entity : Transformable : Element
Player : Ped : Physical : Entity : Element
Train : Vehicle : Physical : Entity : Transformable : Element}}
Train : Vehicle : Physical : Entity : Element}}


==Abstract Base Types==
==Abstract Base Types==
Line 70: Line 69:
* <code>function</code> - For callbacks.
* <code>function</code> - For callbacks.
* <code>int</code> - <code>Number</code> if the scripting language only uses 1 numerical type for ints and floats.
* <code>int</code> - <code>Number</code> if the scripting language only uses 1 numerical type for ints and floats.
* <code>null</code> - Also known as <code>nil</code>.
* <code>object</code> - For elements. <code>Userdata</code> if Lua.
* <code>object</code> - For elements. <code>Userdata</code> if Lua.
* <code>null</code> - Also known as <code>nil</code>.
* <code>string</code>
* <code>string</code>
* <code>undefined</code> - Used in JS.


Container types.
Container types.
* <code>array&lt;Type&gt;</code> - <code>Table</code> if Lua. Keys start at 1 if Lua, otherwise keys start at 0.
* <code>array&lt;Type&gt;</code> - <code>Table</code> if Lua. Keys start at 1 if Lua, otherwise keys start at 0.
* <code>dictionary&lt;KeyType,ValueType&gt;</code> - <code>Table</code> if Lua.
* <code>dictionary&lt;KeyType,ValueType&gt;</code> - <code>Table</code> if Lua.
Other types.
* <code>void</code> - Represents no arguments or no returns.
==Handle Existence Span==
{| class="wikitable"
!Type
!Side
!Handle Creation
!Handle Destruction (With 0 handle references left in scripting too)
|-
|Client
|Server-Side
|When a client is attempting to join the server. [[OnPlayerJoin|OnPlayerJoin]].
|When a client has begun leaving the server. [[OnPlayerQuit|OnPlayerQuit]].
|-
|Client (Local)
|Client-Side
|When a client has joined the server, and the local client's client-side has been notified.
|n/a
|-
|Client (Remote)
|Client-Side
|When a client has joined the server, and the remote clients' client-side have been notified.
|When a client has begun leaving the server, and the remote clients' client-side have been notified.
|-
|Player
|Server-Side
|When the client's player-ped has spawned. [[OnPedSpawn|OnPedSpawn]].
|When the client's player-ped has de-spawned. [[OnPedWasted|OnPedWasted]].
|-
|Player (Local)
|Client-Side
|When the local client's player-ped has spawned. [[OnPedSpawn|OnPedSpawn]].
|When the local client's player-ped has de-spawned. [[OnPedWasted|OnPedWasted]].
|-
|Player (Remote)
|Client-Side
|When any of these qualifying conditions occur:<br>
* The remote client's player-ped has spawned, assuming the local client's player-ped is spawned.<br>
* The remote client's player-ped has streamed back into streaming range of the<br>local client's player-ped 3D position, assuming both the local client's player-ped is spawned and<br>depending on qualifying <code>NetFlags</code> values for all applicable elements.<br>
* The local client's player-ped has spawned.<br>
[[OnPedSpawn|OnPedSpawn]] [[OnElementStreamIn|OnElementStreamIn]].
|When any of these qualifying conditions occur:<br>
* The remote client's player-ped has de-spawned, assuming the local client's player-ped is spawned.<br>
* The remote client's player-ped has streamed out of streaming range of the<br>local client's player-ped 3D position, assuming both the local client's player-ped is spawned and<br>depending on qualifying <code>NetFlags</code> values for all applicable elements.<br>
* The local client's player-ped has de-spawned.<br>
[[OnPedWasted|OnPedWasted]] [[OnElementStreamOut|OnElementStreamOut]].
|}
Please note, a handle that is not properly de-referenced will cause the handle to not be internally destructed.<br>
As a result, this can give the illusion that some functions are broken when they aren't, such as the result of [[getElementsByType|getElementsByType]] including more than one array entry for the "same element", which are unequal in scripting comparison operators, after internal re-construction, eg. when a client-side player streams out of distance radius of the local player and then streams back in.<br>
To properly de-reference a handle when it's no longer needed, be sure to use <code>delete myVariable;</code> or <code>myVariable = null;</code> in JS, or <code>myVariable = nil</code> in Lua, where applicable.<br>
Continuous attempts of internal destruction of a handle occurs when the qualifying internal destruction reason has occurred, until there are no references remaining in scripting for the handle, rather than only one internal destruction attempt.<br>
A handle becomes invalidated when a handle destruction attempt has first occurred.<br>
Attempting to hold onto a reference of invalidated handles could cause memory exhaustion, and usage of an invalid handle with the scripting API should give a scripting error.<br><br>
Also, when the local client's player-ped is not spawned, applicable handles will not be usable in client-side scripting.<br>
For example, remote clients' player-ped handles are internally attempted to be destructed when the local client's player-ped de-spawns, until the local client's player-ped re-spawns.<br>


==Previous Versions==
==Previous Versions==


Type <code>Civilian</code> was removed. All functionality from type <code>Civilian</code>was moved to type <code>Ped</code>.
Type <code>Civilian</code> was removed. All functionality from type <code>Civilian</code>was moved to type <code>Ped</code>.<br>
Type <code>Transformable</code> was removed. All functionality from type <code>Transformable</code>was moved to type <code>Element</code>.<br>

Latest revision as of 18:48, 5 September 2023

This page hosts a list of used data types for scripting.

Types

These types are used in Scripting.
A Sharedtype means that the type is available to be used on both the server and the client in scripting.

  • Shared Client - client representation
  • Client Effect - effect (FX)
  • Shared Element - element
    • Shared Blip - blip
    • Shared Entity - entity
      • Shared Building - building (GTA Building)
      • Shared Physical - object that interacts with physics
        • Shared Object - placeable object
        • Shared Ped - pedestrian
          • Shared Player - player
        • Shared Vehicle - any vehicle
          • Shared Train - train
    • Shared Marker - marker
    • Shared Pickup - pickup
  • Shared Event - event
    • Shared CancellableEvent - cancellable event
    • Shared KeyEvent - key event
  • Client Font - font
  • Client GUIElement - gui element
  • Client GUIHtmlElement - gui html element
  • Client GUIHtmlView - gui html view
  • Client GUIPage - gui page
  • Client GUIWindow - gui window
  • Shared Matrix4x4 - matrix of 4 by 4 decimal numbers
  • Shared ReflectedFunction - reflected function
  • Shared Resource - resource
  • Client Sound
  • Shared Stream
  • Client Surface
    • Client RenderTarget - client representation - derives from Surface
    • Client Texture - texture - derives from Surface
  • Shared Timer - timer
  • Shared Vec2 - vector of 2 decimal numbers
  • Shared Vec3 - vector of 3 decimal numbers
  • Shared XmlDocument - xml document
  • Shared XmlElement - xml element

Types Derived From Element

Types derived from type Element, as shown in the list above.

Blip : Element
Building : Entity : Element
Marker : Element
Object : Physical : Entity : Element
Pickup : Element
Player : Ped : Physical : Entity : Element
Train : Vehicle : Physical : Entity : Element

Abstract Base Types

These types aren't used directly in Scripting. They just represent abstract types used behind the scenes.

  • Surface - Anything that is drawable (RenderTarget, Texture)

Scripting-Language Types

These scripting-language types are used in the scripting interface.

Scalar types.

  • bool - Also known as boolean.
  • float - Number if the scripting language only uses 1 numerical type for ints and floats.
  • function - For callbacks.
  • int - Number if the scripting language only uses 1 numerical type for ints and floats.
  • null - Also known as nil.
  • object - For elements. Userdata if Lua.
  • string
  • undefined - Used in JS.

Container types.

  • array<Type> - Table if Lua. Keys start at 1 if Lua, otherwise keys start at 0.
  • dictionary<KeyType,ValueType> - Table if Lua.

Other types.

  • void - Represents no arguments or no returns.

Handle Existence Span

Type Side Handle Creation Handle Destruction (With 0 handle references left in scripting too)
Client Server-Side When a client is attempting to join the server. OnPlayerJoin. When a client has begun leaving the server. OnPlayerQuit.
Client (Local) Client-Side When a client has joined the server, and the local client's client-side has been notified. n/a
Client (Remote) Client-Side When a client has joined the server, and the remote clients' client-side have been notified. When a client has begun leaving the server, and the remote clients' client-side have been notified.
Player Server-Side When the client's player-ped has spawned. OnPedSpawn. When the client's player-ped has de-spawned. OnPedWasted.
Player (Local) Client-Side When the local client's player-ped has spawned. OnPedSpawn. When the local client's player-ped has de-spawned. OnPedWasted.
Player (Remote) Client-Side When any of these qualifying conditions occur:
  • The remote client's player-ped has spawned, assuming the local client's player-ped is spawned.
  • The remote client's player-ped has streamed back into streaming range of the
    local client's player-ped 3D position, assuming both the local client's player-ped is spawned and
    depending on qualifying NetFlags values for all applicable elements.
  • The local client's player-ped has spawned.

OnPedSpawn OnElementStreamIn.

When any of these qualifying conditions occur:
  • The remote client's player-ped has de-spawned, assuming the local client's player-ped is spawned.
  • The remote client's player-ped has streamed out of streaming range of the
    local client's player-ped 3D position, assuming both the local client's player-ped is spawned and
    depending on qualifying NetFlags values for all applicable elements.
  • The local client's player-ped has de-spawned.

OnPedWasted OnElementStreamOut.

Please note, a handle that is not properly de-referenced will cause the handle to not be internally destructed.
As a result, this can give the illusion that some functions are broken when they aren't, such as the result of getElementsByType including more than one array entry for the "same element", which are unequal in scripting comparison operators, after internal re-construction, eg. when a client-side player streams out of distance radius of the local player and then streams back in.
To properly de-reference a handle when it's no longer needed, be sure to use delete myVariable; or myVariable = null; in JS, or myVariable = nil in Lua, where applicable.
Continuous attempts of internal destruction of a handle occurs when the qualifying internal destruction reason has occurred, until there are no references remaining in scripting for the handle, rather than only one internal destruction attempt.
A handle becomes invalidated when a handle destruction attempt has first occurred.
Attempting to hold onto a reference of invalidated handles could cause memory exhaustion, and usage of an invalid handle with the scripting API should give a scripting error.

Also, when the local client's player-ped is not spawned, applicable handles will not be usable in client-side scripting.
For example, remote clients' player-ped handles are internally attempted to be destructed when the local client's player-ped de-spawns, until the local client's player-ped re-spawns.

Previous Versions

Type Civilian was removed. All functionality from type Civilianwas moved to type Ped.
Type Transformable was removed. All functionality from type Transformablewas moved to type Element.