Skip to content

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.

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.

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.

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:

  1. The native’s return value comes first.
  2. 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.

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.

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.