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.
Which value to use
Section titled “Which value to use”| 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.
Look up an entity
Section titled “Look up an entity”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.
Use a GTA handle
Section titled “Use a GTA handle”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.
ID reuse
Section titled “ID reuse”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.