NebulaChunks

public static class NebulaChunks

Reports the runtime chunks available on each role so your game can load their content. NebulaBootstrap activates the public world's grid when NebulaConfig.ChunkedWorld and NebulaConfig.RuntimeWorld are configured.

Each scope, a separately identified simulation area, has its own grid. Grid returns the public world's grid. Activate additional grids with NebulaChunkedWorld.ActivateGrid and retrieve them with GridFor. Each grid has its own cell size, planar setting, allocator, container assignments, and persistence identifiers.

A scope can also hold grids hosted by a container with a physics frame of its own, such as a planet carried through the scope (NebulaChunkedWorld.ActivateHostedGrid, docs/container-tree.md D22). A hosted grid is registered under its own grid key, so GridFor, EnsureAt and AllocatorFor take that key exactly as they take a scope's; its chunks report the scope they are in (ChunkContext.ScopeKey).

Chunks are Nebula runtime containers, so "which chunks exist" means something slightly different per role and that is exactly the point: a worker sees the cells it and its neighbors lease, a client sees the containers the gateway told it about (its interest window), and both learn about them through the same two events. A game's callback therefore never needs to know which role it is running on, nor to poll.

Loaded back-fills: subscribing after chunks already exist raises the event for each of them at once, so a handler added from Start on a late-loaded scene object cannot miss a chunk and no game has to write the "and now walk the existing ones" loop that every hand-rolled chunk loader begins with.

Properties

Grid

public static RuntimeGrid Grid { get; }

The public world's grid, or null when this process runs no public chunked world.

IsActive

public static bool IsActive { get; }

Whether any chunked world is wired up in this process.

Role

public static NebulaRoles Role { get; }

The roles this process runs, as reported to every ChunkContext.

IsHeadless

public static bool IsHeadless { get; } = true;

Whether this process draws anything (see ChunkContext.IsHeadless).

Allocator

public static RuntimeGridAllocator Allocator { get; }

The public world's worker-side allocator, when this process is a worker; null otherwise.

Grids

public static IEnumerable<RuntimeGrid> Grids { get; }

Every grid active in this process, public world first if it has one.

ActiveScopeKeys

public static IEnumerable<string> ActiveScopeKeys { get; }

The keys with a grid in this process ("" is the public world): scope keys for scopes' root grids, and the grid keys of hosted grids.

All

public static IReadOnlyList<Container> All { get; }

Chunks resident in this process right now, across every scope.

LoadedCount

public static int LoadedCount { get; }

How many chunks are resident in this process right now, across every scope.

Events

Loaded

public static event ChunkHandler Loaded;

A chunk now exists in this process: build its content. Subscribing back-fills every chunk that is already here, so subscription order never decides what a game sees.

Unloading

public static event ChunkHandler Unloading;

A chunk is about to go: its container object, and everything under ChunkContext.Root, is destroyed right after. Only a game holding references outside the chunk has anything to do here.

Methods

GridFor

public static RuntimeGrid GridFor(string scopeKey);

The grid registered under a key, or null when there is none here: a scope's root grid by the scope's key ("" for the public world), or a hosted grid by its own grid key.

AllocatorFor

public static RuntimeGridAllocator AllocatorFor(string scopeKey);

The worker-side allocator of the grid registered under a key (GridFor), or null (not a worker, or no such grid).

IsActiveFor

public static bool IsActiveFor(string scopeKey);

Whether a grid is registered under a key in this process (GridFor).

HostedGridsIn

public static IReadOnlyList<RuntimeGrid> HostedGridsIn(string scopeKey);

The grids hosted in a scope that this process knows (docs/container-tree.md D22); empty when there are none.

GridOf

public static RuntimeGrid GridOf(Container container);
public static RuntimeGrid GridOf(ulong id);

The grid a container belongs to, or null when it is not a chunk of any grid here. The central "which scope does this container belong to" query: a dictionary lookup on the container's isolation id, which every role already carries on the container (Container.InstanceId).

GridHolding

public static RuntimeGrid GridHolding(Container container);

The grid of the chunk container stands in, at any depth: the container itself when it is a chunk, otherwise the chunk at the bottom of its carrier chain, so a ship's interior finds the chunk the ship is in. Null when that chunk belongs to no grid here, or when a carrier in the chain is in no container.

ScopeOf

public static string ScopeOf(Container container);

The scope key a container belongs to ("" for the public world and for anything not in a grid). A chunk of a hosted grid belongs to the scope its host is in, not to the grid's key.

BoundsOfId

public static Bounds BoundsOfId(ulong id, Bounds fallback);

The bounds hook (ContainerRegistry.RuntimeBoundsInFrame) for every grid at once: the box a chunk id has in this process's frame, whichever scope's grid named it, and the caller's own box for an id no grid here knows. Installed by Activate; a game with one grid and no scopes can keep using RuntimeGrid.UseAsRuntimeBounds instead.

CoordOf

public static Vector3Int CoordOf(Vector3 framePosition);
public static Vector3Int CoordOf(Vector3 framePosition, string scopeKey);

The chunk coordinate a position in the current floating-origin frame falls in, in the public world.

At

public static Container At(Vector3 framePosition);
public static Container At(Vector3 framePosition, string scopeKey);

The public-world chunk holding framePosition if it is resident in this process, else null.

IsLoadedAt

public static bool IsLoadedAt(Vector3 framePosition);

Whether the public-world chunk holding framePosition is resident in this process.

RootOf

public static Transform RootOf(ulong id);

The content root of a chunk (see ChunkContext.Root), or null if it is not resident.

EnsureAt

public static void EnsureAt(Vector3 framePosition, Action<Container> onReady);
public static void EnsureAt(Vector3 framePosition, string scopeKey, Action<Container> onReady);
public static void EnsureAt(Vector3Int coord, Action<Container> onReady);
public static void EnsureAt(Vector3Int coord, string scopeKey, Action<Container> onReady);

Make sure the chunk holding framePosition exists, then hand it over. The spawn-point helper: a game mode that wants to put a player or an object somewhere must not assume a container is there, and must not poll for one either. On a worker this requests the lease; on any role it waits for the registration event, and calls back at once when the chunk is already here.

SeedOf

public static int SeedOf(ulong id);
public static int SeedOf(Vector3Int coord);
public static int SeedOf(Vector3Int coord, string scopeKey);

The deterministic per-chunk seed (ChunkContext.Seed). A 64-bit finalizer mix of the packed id, so neighboring coordinates — whose ids differ in one low bit — produce unrelated seeds. Never zero-sensitive: chunk (0,0,0) gets a seed like any other.

IsDrawn

public static bool IsDrawn(in ChunkContext chunk);

Whether a chunk's content is drawn on this client: false for a chunk of a scoped grid while the local pawn is in another scope that is not kept drawn (InstanceScenes.KeepDrawn), true otherwise. A client is told about another scope's chunks while its pawn stands in the window of an open portal link (docs/portals.md D20), or while it prepares to cross into another scope. Content a game adds to a chunk after Loaded should start hidden when this is false; the public world's chunks are always drawn, as they always were.