Skip to content

Streaming and readiness

An entity can exist on the server before a client receives it. Even after a client lookup succeeds, GTA may still be loading its model. Distance, dimension and the client’s streaming capacity affect which entities are loaded.

These client properties describe different stages:

Property Meaning
valid The Revo object still exists on this client.
isStreamedIn Its GTA instance exists.
ready Its GTA instance exists and the initial synchronized state has been applied. For client-only entities, this follows isStreamedIn.

Use ready before work that requires the loaded entity and its synchronized state. It already includes the GTA availability check. Creating an entity or receiving its ID does not make it ready immediately, and a fixed delay cannot guarantee readiness.

Client event When it fires
entityStreamIn(entity) The GTA instance is ready to use, with its initial synchronized state applied.
networkEntityReadyChanged(entity, ready) A networked entity gains or loses readiness.
entityStreamOut(entity) A previously announced GTA instance has been removed or replaced. Discard state tied to that instance.

Use entityStreamIn for initialization on both networked and client-only entities. Client-only entities fire it after local initialization and do not receive network readiness events.

An entity removed before becoming ready produces neither a public stream-in nor a stream-out. Each new GTA instance can produce a new pair, including after a model replacement.

Registering a handler does not replay earlier events. If a resource starts after entities have loaded, inspect the current entities as well. After asynchronous work, check ready again before using a GTA handle. See Entity IDs and game handles.

Removing the GTA instance can leave the Revo object available to scripts. In that case, valid stays true, isStreamedIn and ready become false, and scriptId becomes 0. Position and rotation remain readable. The entity can load again later, so handle stream-in more than once.

The server can also stop sending an entity to a client. This can remove its Revo object even while the entity still exists on the server. The old reference becomes invalid, and a lookup by network ID returns null until the client receives the entity again. On return, resolve the new object.

During removal, networkEntityReadyChanged can receive false with an already invalid entity. Clean up using the reference or identity you stored earlier, without reading its gameplay properties.

A resource can change these settings on its own local entities:

Property Effect
streamDistance A positive distance in metres. Set null to restore the default.
streamingEnabled Set false to preserve the current loaded or unloaded state instead of automatically changing it with distance. A dimension mismatch still removes the GTA instance.

Setting streamingEnabled to false does not force an unloaded entity into GTA. Client scripts cannot change these settings on server-owned entities.