Scene entities
Replicate a door, lift, turret, or other networked object that already exists in a scene.
Use a scene entity for a networked GameObject that already exists in a scene, such as a door, lift, or turret. Nebula connects replicated state to that existing object instead of instantiating a prefab.
Use a spawned entity when workers must create and destroy copies from a registered prefab. See Spawning.
Authoring
Add NetworkIdentity and your NetworkBehaviour components to the scene object. When you save the scene, the Editor assigns a nonzero random SceneId. The ID is unique across the scenes open at that time and remains on the object.
A prefab asset should keep SceneId 0. A prefab instance placed in a scene receives an overridden ID, so you can both register the prefab for spawning and place instances in scenes.
The Editor does not clear the ID when you create a prefab. If you drag an object that already has a SceneId into the Project window, the new prefab asset keeps that ID. NetworkPrefabs.Instantiate clears the ID on every copy it creates and logs a warning the first time. Nebula > Validate Project reports the prefab. Set SceneId to 0 on the prefab asset to clear the warning.
Keep the object active when its scene loads so Awake can register it. You can use NetworkVariable, RPCs, NetworkTick, sync behaviors, and handover state as you would on a spawned entity.
[RequireComponent(typeof(NetworkIdentity))]
public sealed class ProximityDoor : NetworkBehaviour
{
public NetworkVariable<bool> IsOpen = new NetworkVariable<bool>(false);
public override void NetworkTick(uint tick, float deltaTime) // authority only
{
IsOpen.Value = SomeoneIsNear();
}
private void Update() // every copy
{
SlideLeavesTowards(IsOpen.Value);
}
}Lifecycle
| Moment | What happens |
|---|---|
| Scene loads (any role) | The identity initialises itself and registers in SceneEntities. It is resident but not spawned: IsSpawned is false, NetId is 0, no hooks have run. |
| Worker owns the container it stands in | After holding the lease for NebulaConfig.SceneEntityGraceSeconds, the worker creates its entity ID, runs OnNetworkSpawn and OnGainedAuthority, and tells the gateway. |
| Spawn reaches a client or a neighbouring worker | Instead of instantiating a prefab, the process binds its own copy: the message names the scene id, the registry finds the object, and it takes the net id, epoch, container and variables. If that process has not loaded the cell yet, the spawn waits and binds the moment the cell streams in; variable updates that arrive meanwhile are folded into the waiting record. |
| Lease moves to another worker | An ordinary handover. The new owner's copy is bound by the transfer (or was already a ghost); the old owner's copy becomes a ghost and is eventually forgotten. The grace period exists so the new owner does not spawn a second life before the handover lands. |
| Despawn, ghost expiry, disconnect | The object is unbound: OnNetworkDespawn runs and it returns to the unspawned state it loaded in, keeping the last replicated values. The GameObject is never destroyed by the network. |
| Cell unloads while bound | A client holds the entity's record and re-binds when the cell comes back. A worker with authority despawns it (a re-lease spawns it again); a ghost is forgotten. |
Because the object stays in its scene's hierarchy, it is never re-parented under a container, and in a partitioned world the streamer moves it with its cell on an origin shift (its cached poses and interpolator follow, as for any entity).
What it is not
Exactly one worker simulates a scene entity, based on the container that contains it. Other workers and clients receive its replicated state. A scene entity ID is not a reusable prefab ID; the controlling worker creates it when the entity enters the mesh.
The gateway announces scene entities to clients allowed to observe their instance. A map with thousands of scene entities therefore sends thousands of small spawn messages to a joining client. After the spawn, the gateway reduces state update frequency for entities farther from the client's pawn. Variables and RPCs follow their usual delivery rules.
Run crowds of server-owned entities
Keep hundreds of server-driven characters per worker within a tick budget and a client's bandwidth, with update intervals, relevance priorities, gateway distance tiers, distance-rated sync state and sleep.
RPCs and worker messages
Run methods on clients or authoritative workers, and exchange game-defined messages between workers.