GTA natives
Import GTA functions in client scripts with import * as natives from 'natives'.
The @revomp/types-natives package provides their JavaScript names, argument
types and return values. Its declarations also include the GTA name and hash,
which help identify functions in NativeDB.
See TypeScript setup for installation.
Pass entities
Section titled “Pass entities”Parameters declared as Entity, Ped, Vehicle or Object accept a matching
client entity object or a numeric GTA handle. Passing the object lets the binding
resolve its current game instance.
This example reads a vehicle’s position and projects it onto the screen. It
returns null while the vehicle is unavailable or if the projection fails:
// @ts-check/// <reference types="@revomp/types-client" />/// <reference types="@revomp/types-natives" />
import * as natives from 'natives';
/** @param {import('revo-client').Vehicle} vehicle */function projectVehicle(vehicle) { if (!vehicle.ready) return null;
const position = natives.getEntityCoords(vehicle, true); const [projected, x, y] = natives.getScreenCoordFromWorldCoord( position.x, position.y, position.z, );
return projected ? { x, y } : null;}vehicle.ready confirms that its game instance and initial network state are
ready. Check it again after asynchronous work that may allow the vehicle to
stream out. For numeric handles, use scriptId. See
Entity IDs and game handles.
Player arguments
Section titled “Player arguments”A GTA Player parameter uses a player index. natives.playerId() returns the
local player’s GTA index. A client Player object is accepted when GTA can map
its ped to a player index. A remote player may have no such index, in which case
passing its object throws.
Functions with a Ped parameter can take the client Player object directly,
using its ped’s game handle.
Read return and output values
Section titled “Read return and output values”Functions with an ordinary return value return it directly. For example,
getEntityCoords() returns a Vector3 with x, y and z properties.
Entity handles returned by natives are numbers. You can look up a managed entity
with revo.Entity.getByScriptId(handle).
For functions with output parameters, the result is an array:
- The native’s return value comes first.
- Output values follow in the order of the output parameters.
In the example, getScreenCoordFromWorldCoord() returns
[boolean, number, number]. The boolean indicates whether the projection
succeeded. Read the coordinates when it is true.
A function with no ordinary return value uses undefined in the first slot.
For example, getEntityMatrix(vehicle) returns
[undefined, forward, right, up, position], with four Vector3 values.
Trailing optional output parameters can be omitted. If an output parameter
appears before required inputs, pass null in its place, as in
natives.getGroundZFor3dCoord(x, y, z, null, false, false).
For in/out parameters, pass the initial value and read the updated value from
the returned array. Supplied vector objects are left unchanged.
Argument validation and availability
Section titled “Argument validation and availability”Arguments must match the declaration. Use booleans for boolean parameters,
finite numbers for numeric parameters, and revo.hash(name) when a function
expects a model or weapon hash.
Invalid arguments, stale entity objects and unsupported calls throw.
Functions marked Unavailable in the declarations include the reason and
return never in their type signature. For example, use
client timers and waits for scheduling in
place of natives.wait().
Managed entities use their own destruction API. Call destroy() on a local
entity, or destroy a server-created entity from its server script. Raw deletion
natives such as deleteEntity() reject managed entities.
Loading and synchronized state
Section titled “Loading and synchronized state”Native calls execute synchronously, but functions that request an asset can return before it has loaded. Check the matching loaded query before using it. The client API handles model loading for local entity constructors, as covered in Streaming and readiness.
Native calls run on the current client. Use the server and entity APIs for synchronized state changes, following the ownership rules.