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.
When an entity is ready
Section titled “When an entity is ready”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.
Loading events
Section titled “Loading events”| 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.
What happens on stream-out
Section titled “What happens on stream-out”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.
Client-only streaming settings
Section titled “Client-only streaming settings”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.