Entity Lifecycle

</blockquote>

Handle Spaces

The Registry manages three independent handle/index spaces. Index 0 is reserved/invalid in all three.

Deferred recycling prevents ABA aliasing: a stale LHandle held by OOP code (or a stale NetHandle held by a remote client) could alias a newly created entity if the index were reused immediately. Freed local/net indices sit in pending lists until ConfirmLocalRecycles()/ConfirmNetRecycles() is called after the safety window.

Spawn

The calling thread provides a lambda and performs a synchronized handshake with the Logic thread at the top of its frame. The Logic thread allows the spawning thread to write new entity data, then the spawning thread signals Logic to continue.

This handshake is synchronous, thread-safe, and wraps the fundamental contract behind all spawning variants: deferred, queued, and batched.

Registration outside the handshake window is deferred to the next handshake. One pattern for all state mutation: spawning, despawning, tick registration, tick deregistration.

Despawn

Entity lifecycle on destruction:

1. Tombstone. Destroy(LHandle) resolves to GHandle, defers to PendingDestructions. The Active flag is cleared immediately — the tombstone propagates through all systems for free:
   • GPU predicate pass sees Active=0, skips it
   • Physics awake-only pull sees no body awakening
   • 64-entity bitplane scan sees a zero bit, skips it
2. Deferred destroy. ProcessDeferredDestructions() runs on the Logic thread: generation-checks each GHandle, calls RemoveEntity (tombstone in archetype), then FreeGlobalHandle.
3. Slot reclaim. FreeGlobalHandle reclaims the record index immediately (generation-bumped). Local/net handle indices enter PendingLocalRecycles/PendingNetRecycles.
4. Handle recycling. ConfirmLocalRecycles()/ConfirmNetRecycles() moves pending indices to the free pool after the safety window.

Visual and physics despawn happen at tombstone time. Memory reclamation happens at deferred destroy time. These are decoupled but aligned — the bitplane skip handles the gap at zero overhead.

Archetype Slot Management

Each archetype tracks entity slots with two independent counters:

RemoveEntity tombstones in place — clears the Active flag and moves the slot to InactiveEntitySlots but does not compact data. Iteration bounds use AllocatedEntityCount (the high-water mark) so loops never skip live entities near the tail of a chunk.

PushEntities reuses tombstoned slots from InactiveEntitySlots before allocating fresh slots at the high-water mark. Reuse does not increment AllocatedEntityCount.

ArchetypeFieldLayout

ArchetypeFieldLayout (FlatMap<FieldKey, FieldDescriptor>) is the single source of truth for every field in the archetype — its chunk slot index, cache tier, frame count, stride, and element size.

BuildFieldArrayTable resolves all fields uniformly: outTable[idx] = base + (frame % fieldFrameCount) * fieldFrameStride Cold fields degenerate to base + 0 (frameCount=1, frameStride=0) — no tier branching needed.

Defragmentation

Defrag improves slab locality but is incompatible with determinism builds for authoritative data, since moving an entity changes its EntityCacheIndex — the column coordinate that all tiers share.

View Rehydration Contract

ConstructView<TEntity> and entity EntityView hydrations register for identity-change notifications. When defrag fires EntityIDChanged(oldIndex, newIndex):

1. The FieldProxy cursor updates to the new array position
2. The Construct does not need to manually repair anything
3. The defrag system is responsible for firing this hook for all subscribers before returning

ConstructView also rehydrates automatically when the write frame advances (every logic tick). This handles the normal case where the slab ring buffer wraps and field array base pointers change.