ludus::gameplay::world::WorldBindingTable

Ludus Wiki · API overview · Browse API

Class

Durable-key resolution layer owned at the World boundary.

Holds the two derived mappings the architecture requires, published and removed together with object activation and destruction:

1. PersistentObjectKey -> EntityId (durable key to runtime handle), and
2. runtime slot -> optional durable binding, validated by owner and generation so a recycled slot never inherits a former object's UUID.

Neither mapping is a second source of truth: the authored records and the registry remain authoritative, and these mappings are rebuilt rather than authored. The table advances a monotonic revision on every publish/removal so a cached negative result is invalidated once the bindings change.

The initial implementation is a sorted contiguous table (SortedMap) with exact key equality, suitable for small immutable candidate worlds. Capacity is reserved before a batch commits; a reservation failure leaves the table and the active world unchanged. Structural mutation is owner-thread only, like the registry it serves. The table borrows the registry to validate incarnations and never owns or destroys entities.

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

#include <ludus/gameplay/world/binding_table.h>

class ludus::gameplay::world::WorldBindingTable final

Methods

WorldBindingTable

ludus::gameplay::world::WorldBindingTable::WorldBindingTable() noexcept=default

Empty table that owns no storage; size it with TryInitialize() before use.

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

WorldBindingTable

ludus::gameplay::world::WorldBindingTable::WorldBindingTable(const WorldBindingTable &)=delete

Copying is disabled: the table is the single owner of its world's bindings.

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

operator=

WorldBindingTable & ludus::gameplay::world::WorldBindingTable::operator=(const WorldBindingTable &)=delete

Copying is disabled: the table is the single owner of its world's bindings.

Related types: WorldBindingTable

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

WorldBindingTable

ludus::gameplay::world::WorldBindingTable::WorldBindingTable(WorldBindingTable &&other) noexcept=default

Transfer the mappings and revision; the source becomes empty.

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

operator=

WorldBindingTable & ludus::gameplay::world::WorldBindingTable::operator=(WorldBindingTable &&other) noexcept=default

Transfer the mappings and revision; the source becomes empty.

Related types: WorldBindingTable

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

~WorldBindingTable

ludus::gameplay::world::WorldBindingTable::~WorldBindingTable()=default

Release both mappings.

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

TryInitialize

Status ludus::gameplay::world::WorldBindingTable::TryInitialize(foundation::uint32 slotCapacity) noexcept

Size the slot-indexed reverse mapping to match a registry's capacity.

Call once before activation, with the capacity the owning registry was initialized to. Transactional: on allocation failure the table is left empty and Status::AllocationFailure is returned.

Parameter	Description
slotCapacity	The owning registry's slot capacity (GetCapacity()).

Returns

Success, or AllocationFailure when the reverse array cannot be sized.

Related types: foundation::uint32 · Status

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

TryReserve

Status ludus::gameplay::world::WorldBindingTable::TryReserve(foundation::usize additional) noexcept

Reserve capacity for additional new bindings before a commit.

Reserves forward-map capacity through the allocation-failure-capable seam so a later TryActivate() of the same batch cannot fail partway. Never shrinks.

Parameter	Description
additional	Number of bindings the next batch will publish.

Returns

Success, or AllocationFailure when capacity cannot be reserved.

Related types: foundation::usize · Status

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

TryActivate

Status ludus::gameplay::world::WorldBindingTable::TryActivate(const EntityRegistry &registry, std::span< const BindingCandidate > candidates) noexcept

Publish a batch of durable bindings as one all-or-nothing step.

Validates every candidate against the registry (owner match and live incarnation) and against the existing bindings, reserves capacity, then publishes both mappings and advances the revision once. If any candidate is invalid or duplicates an existing key, nothing is published and the active world is unchanged.

Parameter	Description
registry	The owning registry that issued the candidate handles.
candidates	The bindings to publish; keys must be unique within the batch.

Returns

Success; InvalidEntity for a dead/foreign handle; InvalidConfiguration for a nil key, an out-of-range slot or a duplicate key; AllocationFailure when capacity cannot be reserved.

Related types: EntityRegistry · Status · BindingCandidate

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

DetachBinding

Status ludus::gameplay::world::WorldBindingTable::DetachBinding(const EntityRegistry &registry, EntityId entity) noexcept

Detach the durable binding of one entity before its slot is recycled.

Call inside the registry's destruction order, after access is closed and before the slot is released, so the recycled slot carries no stale binding. Removes both mappings for the entity and advances the revision. Detaching an entity that holds no binding is a no-op that still succeeds.

Parameter	Description
registry	The owning registry (its world token identifies ownership).
entity	The entity whose durable binding is being detached.

Returns

Success, or InvalidEntity when entity belongs to another registry.

Related types: EntityRegistry · Status · EntityId

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

TryResolve

ResolveStatus ludus::gameplay::world::WorldBindingTable::TryResolve(const EntityRegistry &registry, const foundation::identity::PersistentObjectKey &key, EntityId &outEntity) noexcept

Resolve a durable key to a live runtime handle. No I/O, no loading.

Looks the key up in the forward mapping and, on a hit, validates the stored handle against the registry (owner and generation). A binding whose incarnation is gone is removed and reported as Missing. The output is written only when the result is Resolved; it is left unchanged otherwise.

Parameter	Description
registry	The owning registry used to validate the incarnation.
key	The durable key to resolve.
outEntity	Receives the live handle on Resolved; unchanged otherwise.

Returns

A ResolveStatus describing the key/binding relationship.

Related types: EntityRegistry · ResolveStatus · foundation::identity::PersistentObjectKey · EntityId

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

TryGetBinding

bool ludus::gameplay::world::WorldBindingTable::TryGetBinding(EntityId entity, foundation::identity::PersistentObjectKey &outKey) const noexcept

The reverse binding recorded for a runtime slot, if any.

Returns the durable key bound to entity's slot only when the recorded owner and generation match entity exactly, so a recycled slot never reports a former object's key. Writes outKey only when it returns true.

Parameter	Description
entity	The runtime handle whose durable binding is queried.
outKey	Receives the durable key when a matching binding exists.

Returns

True when a matching durable binding exists for the entity.

Related types: foundation::identity::PersistentObjectKey · EntityId

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

GetBindingCount

foundation::usize ludus::gameplay::world::WorldBindingTable::GetBindingCount() const noexcept

Number of live durable bindings currently published.

Related types: foundation::usize

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h

GetBindingRevision

foundation::uint64 ludus::gameplay::world::WorldBindingTable::GetBindingRevision() const noexcept

Monotonic revision advanced on every publish or removal.

A cached resolution result (including a negative Missing/NotResident result) is stale once this value changes, so callers invalidate such caches by comparing the revision they recorded. See the "Resolution and streaming" section of docs/architecture/object-handles-uuid.md.

Related types: foundation::uint64

Declared in modules/gameplay/world/include/ludus/gameplay/world/binding_table.h