Build an infinite runtime world

Create an empty world definition and turn on the chunked world

In the Project window, select Create > Nebula > World Definition and name the asset InfiniteWorld.

Set these fields:

The empty cell list is intentional. WorldDefinition supplies the cell size; the runtime grid supplies chunk coordinates as players explore. The 256 m Y size gives a ground-level container enough vertical room for players and placed objects.

Select Resources/NebulaConfig. In the Inspector:

• Assign InfiniteWorld to Runtime World (NebulaConfig.RuntimeWorld) and leave World Manifest (NebulaConfig.WorldManifest) empty.
• Enable Chunked World (NebulaConfig.ChunkedWorld).
• Leave Chunk Planar (NebulaConfig.ChunkPlanar) on. Chunks stay a single layer of columns at y = 0, which matches the ground world this tutorial builds.

With ChunkedWorld on and a RuntimeWorld assigned, every process — client, worker, gateway, and orchestrator — builds the same chunk grid and container bounds from configuration alone. No scene component or game-mode wiring is required to get chunks leasing, ghosting, and handing over across seams; the rest of this tutorial only adds content and gameplay.

Generate ground for each loaded chunk

Add one ChunkContent subclass. Nebula calls it once per chunk your process needs, on every role:

using Nebula;
using Nebula.World;
using UnityEngine;

public sealed class ChunkGround : ChunkContent
{
    [SerializeField] private Material groundMaterial;

    protected override void OnChunkLoaded(in ChunkContext chunk)
    {
        var ground = GameObject.CreatePrimitive(PrimitiveType.Cube);
        ground.name = $"Ground {chunk.Coord}";
        ground.transform.SetParent(chunk.Root, false);

        var size = NebulaChunks.Grid.CellSize;
        ground.transform.localPosition = new Vector3(0f, -size.y * 0.5f - 0.5f, 0f);
        ground.transform.localScale = new Vector3(size.x, 1f, size.z);

        var renderer = ground.GetComponent<Renderer>();
        if (chunk.IsHeadless)
            Object.Destroy(renderer);
        else if (groundMaterial != null)
            renderer.sharedMaterial = groundMaterial;
    }
}

Create an empty GameObject named Chunk Content in the game scene and add ChunkGround to it. Assign a material to Ground Material.

• chunk.Root is a child object created under the chunk's container the first time content is dispatched to it. Objects parented to it are destroyed automatically when the chunk retires, so a Loaded handler that only creates content needs no matching Unloading handler.
• chunk.IsHeadless is true on a worker, or on any process running without a graphics device. Workers still need the ground's collider; they do not need its renderer.
• NebulaChunks.Grid.CellSize is the same size you set on InfiniteWorld, read back from the active grid rather than duplicated in this script.

Replace the cube with your deterministic terrain, voxel, or content loader. Generate the same collision surface on the worker that the client presents to the player. Do not put NetworkIdentity or NetworkBehaviour components on content created under chunk.Root. Spawn interactive networked objects as registered prefabs instead, into chunk.Container.

Create the player input and controller

Create the input value that the owning client sends every tick:

using Nebula;
using UnityEngine;

public struct PlayerInput : INetworkInput
{
    public Vector2 Move;
    public float Yaw;

    public void Serialize(NetworkWriter writer)
    {
        writer.WriteVector2(Move);
        writer.WriteFloat(Yaw);
    }

    public void Deserialize(NetworkReader reader)
    {
        Move = reader.ReadVector2();
        Yaw = reader.ReadFloat();
    }
}

Then create the predicted controller. Movement travels through Nebula's input and reconciliation path. On the owning client, the scene camera follows behind the predicted player. Pressing F sends a reliable ServerRpc to the authoritative worker, which validates the request and spawns the block.

using Nebula;
using UnityEngine;
using UnityEngine.InputSystem;
using Nebula.World;

public sealed class PlayerController : PredictedBehaviour<PlayerInput>
{
    [SerializeField] private GameObject blockPrefab;
    [SerializeField] private float speed = 6f;
    [SerializeField] private float placementDistance = 2.5f;
    [SerializeField] private Vector3 cameraOffset = new(0f, 2.5f, -5f);
    [SerializeField] private float cameraLookHeight = 1f;
    [SerializeField] private float cameraFollowSharpness = 12f;

    private float yaw;
    private float nextPlacementAt;
    private Camera ownerCamera;
    private bool cameraInitialized;

    private void Update()
    {
        if (!IsOwner) return;
        var mouse = Mouse.current;
        if (mouse != null) yaw += mouse.delta.ReadValue().x * 0.08f;

        var keyboard = Keyboard.current;
        if (keyboard != null && keyboard.fKey.wasPressedThisFrame)
            ServerRpc(RpcPlaceBlock);
    }

    private void LateUpdate()
    {
        if (!IsOwner) return;
        if (ownerCamera == null) ownerCamera = Camera.main;
        if (ownerCamera == null) return;

        var cameraTransform = ownerCamera.transform;
        var desiredPosition = transform.TransformPoint(cameraOffset);
        if (!cameraInitialized)
        {
            cameraTransform.position = desiredPosition;
            cameraInitialized = true;
        }
        else
        {
            float blend = 1f - Mathf.Exp(-cameraFollowSharpness * Time.unscaledDeltaTime);
            cameraTransform.position = Vector3.Lerp(cameraTransform.position, desiredPosition, blend);
        }

        var lookTarget = transform.position + Vector3.up * cameraLookHeight;
        cameraTransform.rotation = Quaternion.LookRotation(
            lookTarget - cameraTransform.position,
            Vector3.up);
    }

    protected override PlayerInput GatherInput()
    {
        var keyboard = Keyboard.current;
        var move = Vector2.zero;
        if (keyboard != null)
        {
            move.x = (keyboard.dKey.isPressed ? 1f : 0f) -
                     (keyboard.aKey.isPressed ? 1f : 0f);
            move.y = (keyboard.wKey.isPressed ? 1f : 0f) -
                     (keyboard.sKey.isPressed ? 1f : 0f);
        }

        return new PlayerInput
        {
            Move = Vector2.ClampMagnitude(move, 1f),
            Yaw = yaw,
        };
    }

    protected override void Simulate(uint tick, in PlayerInput input, float deltaTime)
    {
        transform.rotation = Quaternion.Euler(0f, input.Yaw, 0f);
        var velocity =
            (transform.right * input.Move.x + transform.forward * input.Move.y) * speed;
        transform.position += velocity * deltaTime;
        Identity.Motion.Velocity = velocity;
    }

    [ServerRpc]
    private void RpcPlaceBlock()
    {
        if (!HasAuthority || Time.unscaledTime < nextPlacementAt) return;
        nextPlacementAt = Time.unscaledTime + 0.15f;

        var position = transform.position + transform.forward * placementDistance;
        position.x = Mathf.Round(position.x - 0.5f) + 0.5f;
        position.y = Identity.Container.WorldBounds.min.y + 0.5f;
        position.z = Mathf.Round(position.z - 0.5f) + 0.5f;

        if (Physics.CheckBox(position, Vector3.one * 0.45f, Quaternion.identity,
                Physics.AllLayers, QueryTriggerInteraction.Ignore)) return;

        var worker = NebulaBootstrap.Instance.Worker;

        var chunkCoord = NebulaChunks.Grid.CoordOf(position);
        var chunkOffset = position - NebulaChunks.Grid.BoundsOf(chunkCoord).center;
        NebulaChunks.EnsureAt(chunkCoord, container =>
        {
            if (container == null) return;
            var spawnPosition = container.WorldBounds.center + chunkOffset;
            var block = worker.SpawnPrefab(blockPrefab, spawnPosition, Quaternion.identity, container);

            // New persistent entities are checkpointed automatically. SaveNow narrows the window
            // between confirming the placement and its first durable checkpoint.
            worker.Persistence?.SaveNow(block);
        });
    }
}

Keep one camera in the game scene and set its tag to MainCamera. Do not add a camera to the Player prefab: every remote player copy would otherwise bring another active camera. LateUpdate runs the follow behavior only when IsOwner identifies this entity as the local player, and it follows the predicted transform after movement for the frame. Adjust Camera Offset, Camera Look Height, and Camera Follow Sharpness on the prefab to tune the view.

The client never instantiates a networked block. It only asks through ServerRpc; the worker checks authority, rate-limits the request, rejects overlaps, and calls NebulaChunks.EnsureAt so the chunk under the target position is leased (creating it if this is the first entity to reach that spot) before spawning into it. Add your game's permissions, inventory cost, reach test, and placement rules in the same handler.

NebulaChunks.EnsureAt on a worker requests the chunk's lease through the allocator and waits; on a client or gateway it only waits, because a client does not decide which chunks exist. The callback waits for container registration, which does not guarantee that this worker owns the lease. The example preserves the target as a chunk coordinate and offset while it waits, then resolves it into the current floating-origin frame before spawning. Nebula routes authority as the entity enters the container. Recheck game-specific placement rules in the callback if they may change while waiting.

Create the player and block prefabs

Create a capsule prefab named Player with these root components:

• NetworkIdentity
• NetworkTransform
• PlayerController

On NetworkTransform, keep server authority, position and rotation synchronization, interpolation, and unreliable deltas enabled.

Keep the scene's Main Camera as a separate scene object with the MainCamera tag. The PlayerController finds and moves it for the local player, so the player prefab itself does not need a Camera or AudioListener.

Create a 1 m cube prefab named Block with these root components:

• NetworkIdentity
• PersistentEntity

Leave PersistentEntity.PersistPose enabled. The block does not move after placement, so it does not need NetworkTransform; its spawn includes its complete initial pose. Leave the persistence key empty so Nebula generates a unique key on the first save.

After both prefab assets exist, connect and register them:

1. Open the Player prefab.
2. On PlayerController, drag the Block prefab into Block Prefab. Save the prefab.
3. Run Nebula > Network Prefabs > Register All Network Prefabs.
4. Select Resources/NebulaConfig and expand Network Prefabs. Confirm that it contains both Player and Block, with no empty or duplicate entries.
5. Open each prefab and confirm that NetworkIdentity.SceneId is 0.

Nebula assigns each registered prefab a network ID from its position in NetworkPrefabs. Every worker and client build must contain the same list in the same order.

Spawn players from the game mode

Create this game mode script:

using Nebula;
using Nebula.World;
using UnityEngine;

public sealed class InfiniteWorldGameMode : NebulaGameMode
{
    [SerializeField] private GameObject playerPrefab;

    public override NetworkIdentity OnSpawnPlayer(
        NebulaWorker worker,
        ulong clientId,
        string playerName,
        Container requestedContainer)
    {
        var container = requestedContainer;
        var bounds = container.WorldBounds;
        var position = new Vector3(bounds.center.x, bounds.min.y + 1f, bounds.center.z);

        var player = worker.SpawnPrefab(
            playerPrefab,
            position,
            Quaternion.identity,
            container,
            clientId);
        player.name = $"Player {playerName} ({clientId})";
        return player;
    }
}

Return to the game scene and connect the game mode:

1. Create an empty GameObject named Game.
2. Add InfiniteWorldGameMode to it.
3. Drag the Player prefab into Player Prefab.
4. Save the scene.

The scene must contain exactly one enabled NebulaGameMode. NebulaChunkedWorld anchors chunk (0, 0, 0) permanently — the guaranteed spawn area — so the gateway always has a leased container to offer a joining player, even before anyone has walked there. requestedContainer in OnSpawnPlayer is one of the currently leased chunks; this example spawns directly into it rather than picking a fixed coordinate, so a new player always lands somewhere already loaded.

The dashboard World map shows every authoritative entity in the public world. It is an operator view, not the client's content radius: a block remains on the map while its container is leased, even when that block is too far away for the client-side terrain loader. Nebula continues to replicate public entities within interest range in every leased container in the same instance; use game-side rendering or level-of-detail rules if a distant active block should be hidden for other reasons.

Configure persistence and run the mesh

Keep NebulaConfig.PersistenceMode at auto. For a local mesh, the standalone orchestrator stores blocks in the SQLite database configured by mesh.database, which defaults to Library/Nebula/nebula.db.

Before building, verify the complete setup:

• Resources/NebulaConfig has InfiniteWorld in Runtime World, nothing in World Manifest, Chunked World enabled, and both prefabs in Network Prefabs.
• The game scene has one NebulaBootstrap, one Chunk Content object with ChunkGround and its Ground Material assigned, and one InfiniteWorldGameMode with Player Prefab assigned.
• The game scene has one enabled camera tagged MainCamera; the Player prefab has no camera of its own.
• The Player prefab has Block Prefab assigned on PlayerController.
• The Player and Block prefab roots each have NetworkIdentity with SceneId set to 0.

Run Nebula > Validate Project. A configured RuntimeWorld tells the validator that the game intentionally has no authored containers. Fix any prefab, game-mode, scene, or transform issues it reports.

From the Unity project root, build and start the mesh:

nebula build
nebula start --workers 2 --open-ui

Press Play in the Editor as a client and connect to 127.0.0.1:7000. Walk with WASD, turn with the mouse, and press F to place blocks.

Use the dashboard's World map to watch chunk containers appear and move between workers. Cross a chunk edge and confirm that the player keeps moving while the overlay's container and worker values change.

Verify chunk retirement and restore

Place a block outside the permanently anchored spawn area. With the settings above, the allocator keeps a four-cell ring around every pawn and the origin anchor (NearCells + 1), so choose a chunk more than four cells from the origin. Move every player more than four cells from that chunk, then wait longer than ChunkRetireSeconds (default 30 seconds). The owning worker releases the old chunk. Nebula checkpoints and despawns the block before removing the lease.

Walk back. The runtime allocator requests the chunk again, the control plane leases it, and persistence restores the block into the same runtime container at its saved pose. The restore starts after PersistenceRestoreGraceSeconds, which defaults to 3 seconds, so wait briefly before treating a missing block as a failure.

To verify restart persistence:

nebula stop
nebula start --workers 2 --open-ui

The anchored spawn chunk returns as soon as a worker starts. Blocks elsewhere return when a player approaches and the runtime allocator requests their chunk.

Do not pass --reset-persistence during this test. That option deletes every saved entity before the mesh starts.