Skip to content

Entity IDs and game handles

An entity has a Revo ID and, while loaded in GTA, a game handle. On the client, networked entities also expose the ID assigned by the server.

Value Meaning Lookup
Server id Identifies the object on the server. For a networked entity, clients receive this value as networkId. Server Vehicle.getById(id), or the corresponding entity class.
Client id Identifies the object within that client. It can differ between clients and from the server ID. Client Vehicle.getById(id).
Client networkId Matches the entity’s server id. It is null for client-only entities. Client Vehicle.getByNetworkId(networkId).
Client scriptId GTA handle used by entity natives. It is 0 while the entity is not streamed in. Client Entity.getByScriptId(scriptId).

When sending an entity’s ID from the server, send entity.id. Resolve it on the client with getByNetworkId(). In the other direction, send the client’s entity.networkId and use getById() on the server.

LocalPed, LocalVehicle, and LocalObject exist only on their client and have no network ID. Network ID 0 is valid, so check for null explicitly.

Use the class that matches the entity, such as Vehicle or Player. Ped queries return NPCs. Player lookups use Player.

A lookup returns null when no matching object is available in that runtime. Sending an ID to a client does not stream the entity in. getByScriptId() only finds entities already managed by Revo, so an ambient GTA entity can have a valid game handle without a matching Revo object.

ready confirms that the entity exists in GTA and its initial server state has been applied. Checking vehicle?.ready is sufficient for the immediate native call below.

This client function accepts a vehicle’s server ID and reads its speed in metres per second. It returns null if the vehicle is unavailable or still loading:

// @ts-check
/// <reference types="@revomp/types-client" />
/// <reference types="@revomp/types-natives" />
import { Vehicle } from 'revo-client';
import { getEntitySpeed } from 'natives';
/** @param {number} serverId */
export function getVehicleSpeedByServerId(serverId) {
const vehicle = Vehicle.getByNetworkId(serverId);
if (!vehicle?.ready) {
return null;
}
return getEntitySpeed(vehicle.scriptId);
}

Read scriptId immediately before the native call. Streaming out or replacing the model can remove the GTA instance, so retrieve the handle again after a frame or an await.

IDs can be reused after destruction. Keep the entity object when tracking it within a script, and check valid after asynchronous work. An old object remains invalid even if a new entity receives the same numeric ID.

Use project-defined identifiers for saved vehicles or characters. Revo IDs and GTA handles are temporary runtime values.