Function syncInstantiate

syncInstantiate(
    object: Object3D<Object3DEventMap> | IGameObject,
    opts: SyncInstantiateOptions,
    hostData?: HostData,
    save?: boolean,
): null | IGameObject
Instantiate an object across the network. The object is cloned locally and a network message is sent so all connected clients create the same clone. Late joiners receive the message via room state replay (unless deleteOnDisconnect is set or save is false).

How it works internally
1. The prefab is cloned locally using a seeded InstantiateIdProvider
2. The seed ensures all clients generate identical deterministic guids for the clone and all its children — no need to send individual guids over the network
3. A NewInstanceModel message is sent containing the prefab's originalGuid, the clone's guid, the seed, and transform data
4. On receiving clients, the prefab is resolved via registerPrefabProvider or by searching the scene for an object with matching guid, then cloned with the same seed
Runtime-created prefabs (no GLB)
If the object has a guid but no prefab provider is registered for it, syncInstantiate will auto-register the object as a prefab provider. This means for code-only prefabs you just need to set a guid — no manual registerPrefabProvider call needed, as long as all clients run the same setup code that creates the same prefab with the same guid.
Parameters
- object: Object3D<Object3DEventMap> | IGameObject
  The object to instantiate. Must have a guid property (set one for runtime objects).
- opts: SyncInstantiateOptions
  Options for the instantiation, including the network context to send the instantiate event to
- OptionalhostData: HostData
  Optional data about a file to download when this object is instantiated (e.g. when instantiated via file drop)
- Optionalsave: boolean
  When false, the state of this instance will not be saved in the networking backend. Default is true.
Returns null | IGameObject
The instantiated object, or null if instantiation failed (e.g. missing guid or network context)
See
- syncDestroy - Destroy objects across the network
- onSyncInstantiate - Register a callback to get references to remotely instantiated objects
- registerPrefabProvider - Manually register a prefab provider (auto-registered by syncInstantiate)
- unregisterPrefabProvider - Remove a registered prefab provider
Example: Basic usage with a runtime-created prefab
```
const cookie = ObjectUtils.createPrimitive("Cube", { color: 0xff8c00 });
cookie.guid = "cookie-prefab";
// No need to call registerPrefabProvider — syncInstantiate auto-registers it
syncInstantiate(cookie, { parent: ctx.scene, deleteOnDisconnect: false });
```
Example: With deterministic seed (advanced)
```
const idProvider = new InstantiateIdProvider("my-seed");
const instance = syncInstantiate(prefab, { context, idProvider });
```
The seed generates deterministic guids via UUID v5, so all clients produce identical identifiers for the clone and its children without sending them over the network.

Function syncInstantiate

How it works internally

Runtime-created prefabs (no GLB)

Parameters

Returns null | IGameObject

See

Example: Basic usage with a runtime-created prefab

Example: With deterministic seed (advanced)

Settings

On This Page