ChunkKeys

public static class ChunkKeys

How a chunk coordinate becomes the ids a scope's containers are named by. Two derivations, one per scope kind, and the choice is the whole of docs/scoped-chunk-grids.md D2:

• the public scope keeps the pinned three-axis 21-bit packing (RuntimeGrid.PackId / InterestGrid.PackRegion), so every id persisted before scoped grids existed still resolves to the cell it always did;
• a scoped grid derives its ids exactly as every other scope does (ScopeKeys.ContainerId of the key and the chunk's part id), so chunk (x,y,z) of two scopes is two container ids, two lease rows and two persistence records without a bit of the runtime id being spent on a scope field.

Pure C#, so the gateway, the orchestrator and a test name a scope's chunks without Unity.

Fields

MinCoordinate

public const int MinCoordinate = -(1 << 20);

Coordinates outside this range cannot be packed into a public runtime id.

MaxCoordinate

public const int MaxCoordinate = (1 << 20) - 1;

Methods

IsValidCoordinate

public static bool IsValidCoordinate(Vector3Int c);

PartId

public static string PartId(Vector3Int coord);

The scope part id of a chunk: c/x/y/z. It is hashed with the scope key into the container id and carried on the lease row (InstanceContainerInfo.PartId), which is how a role that never computed the id — a client, a gateway — recovers the coordinate from a row it was handed.

TryParsePartId

public static bool TryParsePartId(string partId, out Vector3Int coord);

Inverse of PartId. False for any other part id (an instance's "interior").

HostedPartId

public static string HostedPartId(string gridKey, Vector3Int coord);

The part id of a chunk of a hosted grid (docs/container-tree.md D22): the grid's key, then the chunk's own part id, <gridKey>/c/x/y/z. A hosted chunk belongs to the scope its host lives in, so its lease row and its records carry that scope's key; the grid key travels here instead, and a role that was only handed the row (a client, a gateway) learns from it which grid and which chunk the box is. Its container id is still RuntimeId of the grid key and the coordinate, which is the hash of this very string.

TryParseHostedPartId

public static bool TryParseHostedPartId(string partId, out string gridKey, out Vector3Int coord);

Inverse of HostedPartId: the grid key and the coordinate. False for a root chunk's part id (c/x/y/z, with no grid key in front) and for any other part id.

TryHostedCoordOf

public static bool TryHostedCoordOf(PersistedEntityRecord record, out string gridKey, out Vector3Int coord);
public static bool TryHostedCoordOf(PersistedEntityRecord record, Func<string, IChunkGridGeometry> geometryOf, out string gridKey, out Vector3Int coord);

The chunk of a hosted grid a persisted record was saved in, from the record alone: its grid key and coordinate, when its PersistedEntityRecord.PartId is a hosted part id (HostedPartId) that hashes to the record's container id. False for a record in a root chunk (see TryCoordOf), inside a carrier, or in any other container.

RuntimeId

public static ulong RuntimeId(string scopeKey, Vector3Int coord);

The 64-bit runtime container id of chunk coord in scopeKey. An empty key is the public world and gets the pinned packing; any other key gets the scope's hash. A hosted grid's chunks pass the grid's own key here, not its scope's.

ContainerId

public static string ContainerId(string scopeKey, Vector3Int coord);

The control-plane container id of a chunk: RuntimeId in the rt_ form.

TryParseContainerId

public static bool TryParseContainerId(string containerId, out ulong runtimeId);

The 64-bit id in a runtime container id (rt_<id>); false for any other form.

TryCoordOf

public static bool TryCoordOf(PersistedEntityRecord record, out Vector3Int coord);

The chunk a persisted record was saved in, from the record alone, so any process can place it without having named the chunk or holding its lease. True when the record's PersistedEntityRecord.ContainerId is a runtime container id and either:

• its PersistedEntityRecord.PartId is a chunk part id (c/x/y/z) that hashes, with the record's scope key, to that very id (RuntimeId), so a part id that names another container is never trusted; or
• the record is in the public world, whose chunk ids are the pinned packing and always unpack.

False for a record in no container, inside a carrier, in a static container or an instance's part, and for a scoped record saved before part ids were recorded, whose part is unknown: place that one with RuntimeGrid.TryFindCoordNear and an approximate position. In the public world every runtime id unpacks, so whether the container really was a chunk is for the game to know. RuntimeGrid.TryCoordOf(PersistedEntityRecord, out Vector3Int) does the same and also teaches the grid the id.