Make entity identifier truly unique

[waynemwashuma]

Objective

Introduces generational entity IDs to the ECS core, ensuring truly unique entity IDs are allocated in a given World.

• Fixes Make Entity truly unique in a given World #45

Note

The generational entity system prevents a critical class of bugs where stale entity references could accidentally access components of newly created entities that reused the same index. This is particularly important for long-running applications with dynamic entity creation and destruction.

Solution

• Generational Entities: Added generation tracking to entity IDs to prevent reuse conflicts
• 64-bit Entity IDs: Implemented packing of entity indices and generations into 64-bit integers
• Safety Validation: Updated all entity access points to validate generations before operations
• Comprehensive Coverage: Modified ECS core systems, queries, and tests to support generational entities

Key changes include:

• Modified Entity class to store both index and generation
• Updated EntityLocation to track generation for validation
• Enhanced EntityCell to check generations before accessing components
• Modified Query system to validate entity generations
• Updated World methods to handle generational entity lifecycle

Showcase

The generational entity system provides automatic protection against stale references:

Entity creation now includes generation tracking:

const world = new World();

// Spawn entities with automatic generation management
const entity1 = world.spawn([new Position(), new Velocity()]);
console.log(entity1.id()); // 64-bit ID containing index and generation

// After despawning, new entities get incremented generations
world.despawn(entity1);
const entity2 = world.spawn([new Position(), new Velocity()]);

// entity1 can no longer access components even though it has the same index
const cell1 = world.getEntity(entity1); // Returns invalid entity cell
const cell2 = world.getEntity(entity2); // Returns valid entity cell

Migration Guide

This does not break for most users except where handling the raw entity indices.
Things to consider:

• Existing code that stores entity indices will need to migrate to storing full entity IDs
• Custom entity management systems will need to incorporate generation validation or use the full entity ID.
• Serialized entity references will need to be updated to use 64-bit IDs

Checklist

• My change requires a change to the documentation
• I have updated the documentation accordingly (updated JSDoc comments and type definitions)
• I have added tests to cover my changes (expanded test coverage for generation handling)