Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

42.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Registry.hpp
 * @brief   Central ECS registry for entity and component management
 * @details The Registry is the core container for the ECS system. It manages
 *          entity creation/destruction, component storage, and provides
 *          query functionality through Views.
 *
 * @author  ESEngine Team
 * @date    2025
 *
 * @copyright Copyright (c) 2025 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#pragma once

// =============================================================================
// Includes
// =============================================================================

// Project includes
#include "../core/Log.hpp"
#include "../core/Revision.hpp"
#include "../core/Types.hpp"
#include "ComponentMask.hpp"
#include "Entity.hpp"
#include "SparseSet.hpp"
#include "View.hpp"
#include "ActiveView.hpp"
#include "EntityChangeJournal.hpp"
#include "components/Hierarchy.hpp"
#include "../events/Sink.hpp"

// Standard library
#include <algorithm>
#include <any>
#include <functional>
#include <queue>
#include <span>
#include <string>

namespace esengine::ecs {

// =============================================================================
// Registry Class
// =============================================================================

/**
 * @brief Central container for all entities and components
 *
 * @details The Registry provides:
 * - Entity lifecycle management (create, destroy, recycle)
 * - Component storage with O(1) access via SparseSet pools
 * - View-based queries for iterating entities with specific components
 *
 * @code
 * Registry registry;
 *
 * // Create entities and add components
 * Entity player = registry.create();
 * registry.emplace<Position>(player, 0.0f, 0.0f);
 * registry.emplace<Velocity>(player, 1.0f, 0.0f);
 *
 * // Query and iterate
 * registry.each<Position, Velocity>([&](Entity e, Position& pos, Velocity& vel) {
 *     pos.x += vel.x * deltaTime;
 * });
 * @endcode
 */
class Registry {
public:
    Registry() = default;
    ~Registry() = default;

    // Non-copyable, movable
    Registry(const Registry&) = delete;
    Registry& operator=(const Registry&) = delete;
    Registry(Registry&&) noexcept = default;
    Registry& operator=(Registry&&) noexcept = default;

    /**
     * @brief Which registry this is — unique for the process, never reused.
     *
     * @details Entity ids are only meaningful WITHIN a registry: a fresh one
     *          hands out 1, 2, 3 again, so anything caching per entity across
     *          registries (a scene reload, an editor play/stop) would silently
     *          serve the previous world's data for the new world's entities.
     *          Comparing addresses cannot answer this — a destroyed registry's
     *          storage is routinely reused by the next one. Systems that keep
     *          per-entity state hold this alongside it and drop the lot when it
     *          changes; see UISystem's retained Yoga nodes.
     */
    u64 instanceId() const { return instance_id_; }

    // Local authoring state is distinct from effective activity. Disabling a
    // parent never overwrites a child's own switch. All engine consumers share
    // this derived answer, including JS queries through the registry binding.
    bool setEntityEnabled(Entity e, bool enabled) {
        if (!valid(e)) return false;
        const u8 off = enabled ? 0 : 1;
        if (disabled_[e.index()] == off) return true;
        disabled_[e.index()] = off;
        if (off) ++disabled_count_; else --disabled_count_;
        ++activity_epoch_;
        recordEntityChange(e, ENTITY_CHANGE_SUBTREE);
        return true;
    }
    bool isEntityEnabled(Entity e) const {
        return valid(e) && disabled_[e.index()] == 0;
    }

    bool isEntityActive(Entity e) const {
        if (!valid(e)) return false;
        if (disabled_count_ == 0) return true;
        ensureActivity();
        return inactive_[e.index()] == 0;
    }
    bool hasInactiveEntities() const { return disabled_count_ != 0; }
    u32 activityEpoch() const { return activity_epoch_; }
    void invalidateActivityHierarchy(Entity root = INVALID_ENTITY) {
        if (disabled_count_) ++activity_epoch_;
        recordEntityChange(root, root == INVALID_ENTITY ? ENTITY_CHANGE_RESET : ENTITY_CHANGE_SUBTREE);
    }

    u32 watchEntityChanges() { return entity_changes_.watch(); }
    void unwatchEntityChanges(u32 reader) { entity_changes_.unwatch(reader); }
    double entityChangeSequence() const { return entity_changes_.sequence(); }
    double entityChangeResetEpoch() const {
        return entity_reset_epoch_ == RESET_EPOCH_LIMIT ? -1 : static_cast<double>(entity_reset_epoch_);
    }
    double componentMutationRevision(u32 component, bool topology) const {
        return entity_changes_.componentRevision(component, topology);
    }
    i32 readEntityChanges(double after, std::span<EntityChangeRow> output) const {
        return entity_changes_.read(after, output);
    }
    // Raw component producers publish their logical mutation here; merely
    // borrowing a mutable reference does not announce a write.
    void recordEntityChange(Entity entity, u32 flags = 0, u32 component = ENTITY_CHANGE_NO_COMPONENT) {
        entity_changes_.record(entity.id(), flags, component);
    }

    // =========================================================================
    // Change Detection
    // =========================================================================
    //
    // Every component carries the tick of its last write. A write stamps the tick that is current; a reader asks
    // beginChangeRead(), which hands back the tick it read at and moves the clock on, and next time takes as changed whatever is
    // stamped after that. A write made after a reader looked is stamped later than what it read at, so it is seen the next time,
    // whichever frame it happened in.
    //
    // What writes says so: patch<T>() (a mutable reference that stamps), markChanged<T>() (after writing through a reference
    // already held), add, replace and remove. get<T>() announces nothing; setChangeAudit() reports what changed without saying.

    /** @brief The tick a write made now is stamped with. */
    u32 changeTick() const { return change_tick_; }

    /**
     * @brief Which registry this is, never shared with another made in this process (a registry assigned over this one brings
     *        its own). Ticks and entities are each registry's own, so a reader that keeps what it derived from one asks this
     *        before trusting a tick or an entity it kept.
     */
    u64 identity() const { return identity_; }

    /**
     * @brief For a reader about to look: the tick it is looking at, after which the clock moves on.
     * @details Keep the answer; next time, changedSince(it) is what was written since this look. Stamps older than half the
     *          counter's range are lifted on the way, so an untouched component never reads as newer once the tick wraps.
     */
    u32 beginChangeRead() {
        const u32 seen = change_tick_;
        ++change_tick_;
        if (change_tick_ == 0) change_tick_ = 1;
        if ((change_tick_ & ((1u << 20) - 1)) == 0) {
            const u32 floor = change_tick_ - (1u << 30);
            for (auto& pool : pools_) if (pool) pool->clampStamps(floor);
        }
        return seen;
    }

    /** @brief Mutable access that says it writes: @p entity's T, stamped. Fatal where it has none, as get<T>() is. */
    template<typename T>
    T& patch(Entity entity) {
        auto* pool = getPool<T>();
        ES_VERIFY_FATAL(pool != nullptr, noPoolMessage(entity));
        T& component = pool->get(entity);
        pool->markChanged(entity, change_tick_);
        return component;
    }

    /** @brief Says @p entity's T was written, through a reference held from before. */
    template<typename T>
    void markChanged(Entity entity) {
        if (auto* pool = getPool<T>()) pool->markChanged(entity, change_tick_);
    }

    /** @brief markChanged by a component type id (componentTypeId): for a writer that names the type at run time, a script. */
    void markChangedById(u32 typeId, Entity entity) {
        if (typeId < pools_.size() && pools_[typeId]) pools_[typeId]->markChanged(entity, change_tick_);
    }

    /** @brief Whether @p entity's T was written, added or replaced after @p tick (an answer of beginChangeRead). */
    template<typename T>
    bool changedSince(Entity entity, u32 tick) const {
        const auto* pool = getPool<T>();
        return pool && tickAfter(pool->changedTick(entity), tick);
    }

    /** @brief changedSince by a component type id (componentTypeId), for a reader that names the type at run time. */
    bool changedSinceById(u32 typeId, Entity entity, u32 tick) const {
        if (typeId >= pools_.size() || !pools_[typeId]) return false;
        return tickAfter(pools_[typeId]->changedTickOf(entity), tick);
    }

    /** @brief Whether any T was written, added or removed after @p tick: the question a frame that may skip its walk asks first. */
    template<typename T>
    bool anyChangedSince(u32 tick) const {
        const auto* pool = getPool<T>();
        return pool && tickAfter(pool->lastChangedTick(), tick);
    }

    /**
     * @brief Calls @p visit(entity) for each T written or added after @p tick, until it returns true; returns whether one did.
     * @details A pass over the stamps alone, which sit in one array beside the components: the answer to "did any of the many
     *          that changed matter to me" without a lookup per component. A removal leaves nothing to visit (anyChangedSince
     *          sees it).
     */
    template<typename T, typename Visit>
    bool anyChangedSinceWhere(u32 tick, Visit&& visit) const {
        const auto* pool = getPool<T>();
        if (!pool || !tickAfter(pool->lastChangedTick(), tick)) return false;
        const u32* stamps = pool->changeTicks();
        const auto& entities = pool->entities();
        for (usize i = 0, n = entities.size(); i < n; ++i) {
            if (tickAfter(stamps[i], tick) && visit(entities[i])) return true;
        }
        return false;
    }

    /** @brief How many entities have a T. */
    template<typename T>
    usize countOf() const {
        const auto* pool = getPool<T>();
        return pool ? pool->size() : 0;
    }

    /** @brief The tick of the latest write, addition or removal of any T; 0 when there has been none. */
    template<typename T>
    u32 lastChangedTick() const {
        const auto* pool = getPool<T>();
        return pool ? pool->lastChangedTick() : 0;
    }

    /**
     * @brief Turns the change audit on or off. On, auditChanges() compares every auditable component with the copy it kept and
     *        reports each one whose bytes changed with no stamp to say so — a write some consumer will never see.
     * @details A check for tests and gates: it copies every component once per audit.
     */
    void setChangeAudit(bool enabled) {
        change_audit_ = enabled;
        audit_copies_.clear();
        audit_reported_.clear();
        if (enabled) auditChanges();
    }
    bool changeAuditEnabled() const { return change_audit_; }

    /**
     * @brief Compares, reports, and keeps a new copy. @return The unstamped writes found since the last call (0 while off).
     * @details Each component type is named in the log the first time one of its writes goes unstamped, with the entity; every
     *          one is counted. A type that can be neither copied as bytes nor compared is named once, at the first audit, as unchecked.
     */
    u32 auditChanges() {
        if (!change_audit_) return 0;
        u32 found = 0;
        if (audit_copies_.size() < pools_.size()) audit_copies_.resize(pools_.size());
        if (audit_reported_.size() < pools_.size()) audit_reported_.resize(pools_.size(), 0);
        for (usize id = 0; id < pools_.size(); ++id) {
            const auto& pool = pools_[id];
            if (!pool) continue;
            if (!pool->auditable()) {
                if (!audit_reported_[id]) {
                    audit_reported_[id] = 2;
                    ES_LOG_INFO("change audit: {} can be neither copied as bytes nor compared with ==, and is not checked", std::string(pool->typeName()));
                }
                continue;
            }
            auto& copy = audit_copies_[id];
            if (!copy.entities.empty() || copy.tick != 0) {
                struct Sink { Registry* self; usize id; Entity first = INVALID_ENTITY; };
                Sink sink{this, id};
                const u32 here = pool->auditCompare(copy, [](void* user, Entity entity) {
                    auto* s = static_cast<Sink*>(user);
                    if (s->first == INVALID_ENTITY) s->first = entity;
                }, &sink);
                if (here && audit_reported_[id] != 1) {
                    audit_reported_[id] = 1;
                    ES_LOG_WARN("change audit: {} was written without a stamp (entity {}, {} this frame) - a consumer of changes "
                                "will not see it", std::string(pool->typeName()), sink.first.index(), here);
                }
                found += here;
                audit_unstamped_total_ += here;
            }
            pool->auditKeep(copy, change_tick_);
        }
        // The copies were taken at this tick: a write from here on has to be stamped later than it to count as said.
        beginChangeRead();
        return found;
    }

    /** @brief Unstamped writes the audit has found since it was turned on. */
    u32 changeAuditTotal() const { return audit_unstamped_total_; }

    template<class... C> auto activeView() {
        return ActiveView<View<C...>, Registry>(view<C...>(), *this);
    }

    // =========================================================================
    // Entity Management
    // =========================================================================

    /**
     * @brief Creates a new entity
     * @return A valid entity ID
     *
     * @details Recycles previously destroyed entities when available.
     *          New entities are allocated sequentially when no recycled
     *          entities exist.
     */
    Entity create() {
        u32 index;
        while (!recycled_.empty()) {
            index = recycled_.front();
            recycled_.pop();
            if (index < entityValid_.size() && entityValid_[index]) {
                continue;
            }
            return activateIndex(index);
        }
        index = next_index_++;
        return activateIndex(index);
    }

    /**
     * @brief Creates multiple entities at once
     * @param count Number of entities to create
     * @return Vector containing all created entity IDs
     */
    std::vector<Entity> create(usize count) {
        std::vector<Entity> entities;
        entities.reserve(count);
        for (usize i = 0; i < count; ++i) {
            entities.push_back(create());
        }
        return entities;
    }

    /**
     * @brief Restores an entity at a specific index
     * @param index The entity index to restore
     * @return The newly created Entity, or INVALID_ENTITY if index is already alive
     */
    Entity restore(u32 index) {
        // Release-safe: reject a deserialized index beyond the addressable range
        // up front, before mutating next_index_ below (activateIndex would also
        // refuse, but only after next_index_ was already advanced, leaving the
        // registry unable to allocate fresh indices).
        ES_VERIFY(index <= Entity::INDEX_MASK, return INVALID_ENTITY);
        if (index < entityValid_.size() && entityValid_[index]) {
            return INVALID_ENTITY;
        }

        if (index >= next_index_) {
            next_index_ = index + 1;
        }

        return activateIndex(index);
    }

    /** Internal subtree ownership. Components remain readable for callbacks,
     * but a pending entity cannot receive links or be reserved a second time. */
    bool reserveDestruction(Entity entity) {
        if (!valid(entity) || destruction_pending_[entity.index()]) return false;
        destruction_pending_[entity.index()] = 1;
        return true;
    }
    void releaseDestruction(Entity entity) {
        const u32 index = entity.index();
        // An old owner's finalizer can run after this slot was recycled and
        // reserved by a new owner. Only its original generation may clear it.
        if (index < destruction_pending_.size() && generations_[index] == entity.generation()) {
            destruction_pending_[index] = 0;
        }
    }
    bool destructionPending(Entity entity) const {
        const u32 index = entity.index();
        return index < destruction_pending_.size() && destruction_pending_[index]
            && generations_[index] == entity.generation();
    }

    /**
     * @brief Destroys an entity and removes all its components
     * @param entity The entity to destroy
     *
     * @details The entity ID is recycled for future use.
     *          All components attached to the entity are removed.
     */
    void destroy(Entity entity) {
        if (!valid(entity)) return;

        if (entity_changes_.readerCount()) {
            recordEntityChange(entity);
            if (const auto* children = tryGet<Children>(entity)) {
                for (const auto child : children->entities) recordEntityChange(child, ENTITY_CHANGE_SUBTREE);
            }
        }

        const u32 idx = entity.index();

        // Mark invalid up-front so a re-entrant destroy(entity) from an onDestroy
        // callback short-circuits at valid() above. Otherwise the teardown below
        // runs twice: entity_count_ underflows and idx is pushed onto recycled_
        // twice, later aliasing two distinct entities to the same index.
        entityValid_[idx] = false;
        const bool hadDisabled = disabled_count_ != 0;
        if (disabled_[idx]) { disabled_[idx] = 0; --disabled_count_; }
        if (hadDisabled) ++activity_epoch_;

        // Signal handles re-entrant connect/disconnect during publish; its RAII
        // Connection (via Sink::connect) keeps subscriber lifetimes safe in both
        // teardown orders — Registry-first or system-first (RC12, fixes A12).
        on_destroy_signal_.publish(entity);

        component_masks_[idx].forEachSet([&](u32 bit) {
            if (bit < pools_.size() && pools_[bit]) {
                pools_[bit]->remove(entity);
                pools_[bit]->noteStructural(change_tick_);
            }
        });

        component_masks_[idx].reset();
        --entity_count_;
        // A slot on its last generation is RETIRED, not recycled: reusing it wraps
        // the counter to 1 and mints an id this slot already issued, which a caller
        // may hold and valid() would confirm. Costs index space, only where it aliases.
        if (generations_[idx] < Entity::GEN_MASK) {
            recycled_.push(idx);
        } else {
            ++retired_slots_;
            ES_LOG_TRACE("Retired entity slot {} (generation exhausted)", idx);
        }

        ES_LOG_TRACE("Destroyed entity raw={} (index={})", entity.raw, idx);
    }

    using DestroyCallback = std::function<void(Entity)>;

    /**
     * @brief Subscribe to entity destruction.
     * @return An RAII Connection. The callback stays registered for as long as
     *         the returned Connection is alive; on its destruction the callback
     *         is removed. The Connection is also safe to outlive the Registry —
     *         it no-ops against a destroyed signal — so subscribers and the
     *         Registry can tear down in either order without a dangling callback.
     */
    [[nodiscard]] Connection onDestroy(DestroyCallback callback) {
        return sink(on_destroy_signal_).connect(std::move(callback));
    }

    /**
     * @brief Checks if an entity is currently valid
     * @param entity The entity to check
     * @return True if the entity exists and generation matches
     */
    bool valid(Entity entity) const {
        const u32 idx = entity.index();
        return idx < entityValid_.size() &&
               entityValid_[idx] &&
               generations_[idx] == entity.generation();
    }

    usize entityCount() const {
        return entity_count_;
    }

    /**
     * @brief Slots permanently out of circulation, their generation spent.
     *
     * Zero for anything but sustained create/destroy on the same indices. Rising
     * steadily is the signal that churn is eating index space — the price paid so
     * a destroyed entity's handle can never come back as a live one.
     */
    u32 retiredSlots() const { return retired_slots_; }

    /**
     * @brief Executes a function for each valid entity
     * @tparam Func The callback type
     * @param func Callback receiving Entity
     */
    template<typename Func>
    void forEachEntity(Func&& func) const {
        for (u32 i = 0; i < entityValid_.size(); ++i) {
            if (entityValid_[i]) {
                func(Entity::make(i, generations_[i]));
            }
        }
    }

    // =========================================================================
    // Component Management
    // =========================================================================

    /**
     * @brief Adds a component to an entity with in-place construction
     * @tparam T The component type
     * @tparam Args Constructor argument types
     * @param entity The target entity
     * @param args Arguments forwarded to T's constructor
     * @return Reference to the newly created component
     *
     * @note An invalid entity is fatal in every build; the component already
     *       being there degrades to the existing one (see SparseSet::emplace).
     */
    template<typename T, typename... Args>
    T& emplace(Entity entity, Args&&... args) {
        // An invalid entity would index component_masks_ out of bounds below (the
        // sentinel's index() is the mask), and there is no component to hand back.
        ES_VERIFY_FATAL(valid(entity), invalidEntityMessage("emplace", entity));
        auto& pool = assurePool<T>();
        auto& result = pool.emplace(entity, std::forward<Args>(args)...);
        component_masks_[entity.index()].set(componentTypeId<T>());
        pool.markChanged(entity, change_tick_);
        recordComponentChange<T>(entity);
        return result;
    }

    /**
     * @brief Adds or replaces a component on an entity
     * @tparam T The component type
     * @tparam Args Constructor argument types
     * @param entity The target entity
     * @param args Arguments forwarded to T's constructor
     * @return Reference to the component
     *
     * @details If the entity already has the component, it is replaced.
     */
    template<typename T, typename... Args>
    T& emplaceOrReplace(Entity entity, Args&&... args) {
        ES_VERIFY_FATAL(valid(entity), invalidEntityMessage("emplaceOrReplace", entity));
        auto& pool = assurePool<T>();

        if (pool.contains(entity)) {
            auto& comp = pool.get(entity);
            comp = T(std::forward<Args>(args)...);
            pool.markChanged(entity, change_tick_);
            recordComponentChange<T>(entity, ENTITY_CHANGE_REPLACED);
            return comp;
        }
        auto& result = pool.emplace(entity, std::forward<Args>(args)...);
        component_masks_[entity.index()].set(componentTypeId<T>());
        pool.markChanged(entity, change_tick_);
        recordComponentChange<T>(entity);
        return result;
    }

    /**
     * @brief Removes a component from an entity
     * @tparam T The component type to remove
     * @param entity The target entity
     *
     * @details No-op if the entity doesn't have the component.
     */
    template<typename T>
    void remove(Entity entity) {
        auto* pool = getPool<T>();
        if (pool && pool->contains(entity)) {
            pool->remove(entity);
            pool->noteStructural(change_tick_);
            recordComponentChange<T>(entity);
            const u32 idx = entity.index();
            if (idx < component_masks_.size()) {
                component_masks_[idx].clear(componentTypeId<T>());
            }
        }
    }

    /**
     * @brief Gets a component from an entity (must exist)
     * @tparam T The component type
     * @param entity The target entity
     * @return Reference to the component
     *
     * @note A missing component is fatal in every build — the contract is that the
     *       caller knows it is there. Use tryGet() where absence is expected and
     *       getOrEmplace() where the component should be created.
     */
    template<typename T>
    T& get(Entity entity) {
        auto* pool = getPool<T>();
        ES_VERIFY_FATAL(pool != nullptr, noPoolMessage(entity));
        return pool->get(entity);  // itself fatal on a non-member
    }

    /** @copydoc get() */
    template<typename T>
    const T& get(Entity entity) const {
        auto* pool = getPool<T>();
        ES_VERIFY_FATAL(pool != nullptr, noPoolMessage(entity));
        return pool->get(entity);
    }

    /**
     * @brief Tries to get a component from an entity
     * @tparam T The component type
     * @param entity The target entity
     * @return Pointer to the component, or nullptr if not found
     */
    template<typename T>
    T* tryGet(Entity entity) {
        auto* pool = getPool<T>();
        return pool ? pool->tryGet(entity) : nullptr;
    }

    /** @copydoc tryGet() */
    template<typename T>
    const T* tryGet(Entity entity) const {
        auto* pool = getPool<T>();
        return pool ? pool->tryGet(entity) : nullptr;
    }

    /**
     * @brief Gets an existing component or creates a new one
     * @tparam T The component type
     * @tparam Args Constructor argument types (for new component)
     * @param entity The target entity
     * @param args Arguments forwarded to T's constructor if creating
     * @return Reference to the component
     */
    template<typename T, typename... Args>
    T& getOrEmplace(Entity entity, Args&&... args) {
        auto& pool = assurePool<T>();
        if (pool.contains(entity)) {
            return pool.get(entity);
        }
        ES_VERIFY_FATAL(valid(entity), invalidEntityMessage("getOrEmplace", entity));
        auto& result = pool.emplace(entity, std::forward<Args>(args)...);
        component_masks_[entity.index()].set(componentTypeId<T>());
        pool.markChanged(entity, change_tick_);
        recordComponentChange<T>(entity);
        return result;
    }

    /**
     * @brief Checks if an entity has a specific component
     * @tparam T The component type to check
     * @param entity The entity to check
     * @return True if the entity has the component
     */
    template<typename T>
    bool has(Entity entity) const {
        auto* pool = getPool<T>();
        return pool && pool->contains(entity);
    }

    /**
     * @brief Checks if an entity has all specified components
     * @tparam Ts The component types to check
     * @param entity The entity to check
     * @return True if the entity has all components
     */
    template<typename... Ts>
    bool hasAll(Entity entity) const {
        return (has<Ts>(entity) && ...);
    }

    /**
     * @brief Checks if an entity has any of the specified components
     * @tparam Ts The component types to check
     * @param entity The entity to check
     * @return True if the entity has at least one component
     */
    template<typename... Ts>
    bool hasAny(Entity entity) const {
        return (has<Ts>(entity) || ...);
    }

    // =========================================================================
    // View Query System
    // =========================================================================

    /**
     * @brief Creates a view for iterating entities with specific components
     * @tparam Components The component types to query
     * @return A View for iterating matching entities
     *
     * @code
     * // Single component view
     * for (auto entity : registry.view<Position>()) {
     *     auto& pos = registry.get<Position>(entity);
     * }
     *
     * // Multi-component view: range-for yields the entities that have them all
     * auto view = registry.view<Position, Velocity>();
     * for (Entity e : view) {
     *     view.get<Position>(e).x += view.get<Velocity>(e).x * dt;
     * }
     * @endcode
     */
    template<typename... Components>
    View<Components...> view() {
        if constexpr (sizeof...(Components) == 1) {
            return View<Components...>(&assurePool<Components...>());
        } else {
            return View<Components...>(
                std::make_tuple(&assurePool<Components>()...));
        }
    }

    // =========================================================================
    // Utility
    // =========================================================================

    /**
     * @brief Clears all entities and components
     * @details Resets the registry to its initial empty state.
     */
    void clear() {
        if (entity_reset_epoch_ < RESET_EPOCH_LIMIT) ++entity_reset_epoch_;
        recordEntityChange(INVALID_ENTITY, ENTITY_CHANGE_RESET);
        for (auto& pool : pools_) {
            if (pool) {
                pool->clear();
            }
        }
        entityValid_.clear();
        disabled_.clear();
        inactive_.clear();
        activity_state_.clear();
        disabled_count_ = 0;
        ++activity_epoch_;
        generations_.clear();
        component_masks_.clear();
        while (!recycled_.empty()) recycled_.pop();
        next_index_ = 0;
        entity_count_ = 0;
        retired_slots_ = 0;
    }

    /**
     * @brief Reorders every component pool to follow the given entity order
     * @param order    Entities in the desired iteration order (first iterates first)
     * @param count    How many entries @p order holds
     *
     * @details Component storage order IS iteration order, and iteration order is
     *          the renderer's painter order within a sorting layer — so a scene's
     *          authored entity order only reaches the draw list because a load
     *          happens to spawn in that order. This applies an order to a registry
     *          that is already populated: the same picture, without respawning
     *          anything (entity ids, component values, and every subsystem keyed on
     *          them survive untouched).
     *
     *          Entities absent from @p order keep their relative order after the
     *          listed ones. Pools already in the requested order are left alone, so
     *          a redundant call costs a scan and bumps no pool version.
     */
    void applyEntityOrder(const Entity* order, usize count) {
        if (!order || count == 0) return;
        applyEntityRank(buildEntityRank(order, count));
    }

    /**
     * @brief Rank table (by Entity::index()) for an ordered entity list
     * @details Split out of {@link applyEntityOrder} so a caller that ranks other
     *          entity lists too — child lists, in applySceneEntityOrder — builds it
     *          once. Unlisted entities read {@link SparseSetBase::UNRANKED}.
     */
    std::vector<u32> buildEntityRank(const Entity* order, usize count) const {
        // entityValid_ spans every index ever activated (activateIndex grows it),
        // so it is the safe bound for a rank table keyed by Entity::index().
        std::vector<u32> rank(entityValid_.size(), SparseSetBase::UNRANKED);
        if (!order) return rank;
        u32 nextRank = 0;
        for (usize i = 0; i < count; ++i) {
            const u32 idx = order[i].index();
            if (idx >= rank.size()) continue;                     // never allocated here
            if (rank[idx] != SparseSetBase::UNRANKED) continue;   // duplicate: first wins
            rank[idx] = nextRank++;
        }
        return rank;
    }

    /**
     * @brief Sum of every pool's version — one number for "did anything move"
     * @return Equal across two reads ⇒ no stored component changed address
     *
     * @details A holder of RAW ADDRESSES (the AOT row table) needs one cheap
     *          question, and one that covers pools it never asked about: a C++
     *          insert moves that pool with no JS call in it. u64 so it cannot
     *          wrap onto a value already seen; double because JS takes that.
     */
    double layoutEpoch() const {
        u64 sum = 0;
        for (const auto& pool : pools_) {
            if (pool) sum += pool->version();
        }
        return static_cast<double>(sum);
    }

    /** @brief Reorders every component pool by a rank table from buildEntityRank. */
    void applyEntityRank(const std::vector<u32>& rank) {
        for (auto& pool : pools_) {
            if (pool) pool->reorderBy(rank);
        }
    }

    /**
     * @brief Executes a function for each entity with specified components
     * @tparam Components The required component types
     * @tparam Func The callback type
     * @param func Callback receiving (Entity, Component&...)
     *
     * @code
     * registry.each<Position, Velocity>([](Entity e, Position& p, Velocity& v) {
     *     p.x += v.x;
     * });
     * @endcode
     */
    template<typename... Components, typename Func>
    void each(Func&& func) {
        view<Components...>().each(std::forward<Func>(func));
    }

    /**
     * @brief each() without the per-call snapshot copy, for read-only passes.
     * @warning The callback must not emplace/remove the iterated component(s).
     */
    template<typename... Components, typename Func>
    void eachLive(Func&& func) {
        view<Components...>().eachLive(std::forward<Func>(func));
    }

    /**
     * @brief Sorts components by a comparison function
     * @tparam T The component type to sort
     * @tparam Compare The comparison function type
     * @param compare Comparison function returning true if first < second
     *
     * @details Sorts the component pool so iteration order matches
     *          the comparison result.
     */
    template<typename T, typename Compare>
    void sort(Compare compare) {
        auto* pool = getPool<T>();
        if (!pool) return;

        const auto& components = pool->components();
        const usize n = components.size();
        if (n <= 1) return;

        std::vector<usize> perm(n);
        for (usize i = 0; i < n; ++i) perm[i] = i;

        std::sort(perm.begin(), perm.end(), [&](usize a, usize b) {
            return compare(components[a], components[b]);
        });
        // The entity, its component and its stamp move together.
        pool->permute(perm);
    }

    /**
     * @brief The entities that carry T, densely
     * @return The pool's dense entity array, or an empty span where no pool exists
     *
     * @details What {@link View} narrows to internally, opened for a caller that
     *          assembles its query at run time from NAMES, as the AOT host does.
     *          Empty means nobody has it — never "ask everybody".
     */
    template<typename T>
    std::span<const Entity> entitiesWith() const {
        const auto* pool = getPool<T>();
        if (pool == nullptr) return {};
        const std::vector<Entity>& dense = pool->entities();
        return std::span<const Entity>(dense.data(), dense.size());
    }

private:
    // Handed out once per registry and never recycled, so it survives one being
    // destroyed and the next taking its address. See instanceId().
    static inline u64 next_instance_id_{0};
    u64 instance_id_{++next_instance_id_};

    // =========================================================================
    // Private Helpers
    // =========================================================================

    /**
     * @brief Gets or creates a component pool for type T
     * @tparam T The component type
     * @return Reference to the SparseSet for type T
     */
    template<typename T>
    SparseSet<T>& assurePool() {
        TypeId typeId = componentTypeId<T>();
        if (typeId >= pools_.size()) {
            pools_.resize(typeId + 1);
        }
        if (!pools_[typeId]) {
            pools_[typeId] = makeUnique<SparseSet<T>>();
        }
        return *static_cast<SparseSet<T>*>(pools_[typeId].get());
    }

    /**
     * @brief Gets an existing component pool (may return nullptr)
     * @tparam T The component type
     * @return Pointer to the SparseSet, or nullptr if not found
     */
    template<typename T>
    SparseSet<T>* getPool() {
        TypeId typeId = componentTypeId<T>();
        if (typeId >= pools_.size() || !pools_[typeId]) return nullptr;
        return static_cast<SparseSet<T>*>(pools_[typeId].get());
    }

    template<typename T>
    const SparseSet<T>* getPool() const {
        TypeId typeId = componentTypeId<T>();
        if (typeId >= pools_.size() || !pools_[typeId]) return nullptr;
        return static_cast<const SparseSet<T>*>(pools_[typeId].get());
    }

    /// Built only when a contract guard is about to abort; names what was asked.
    static std::string noPoolMessage(Entity entity) {
        return "Registry::get: no pool for this component type (entity "
               + std::to_string(entity.index()) + ":" + std::to_string(entity.generation())
               + "); use tryGet() when absence is expected";
    }
    static std::string invalidEntityMessage(const char* op, Entity entity) {
        return std::string("Registry::") + op + " on an invalid entity ("
               + std::to_string(entity.index()) + ":" + std::to_string(entity.generation()) + ")";
    }

    /**
     * @brief Activates an entity index: resizes arrays, bumps generation, returns packed Entity
     */
    Entity activateIndex(u32 index) {
        // Release-safe: an index past the index field would silently alias an
        // existing slot via Entity::make's mask (ES_ASSERT is stripped in
        // release). Refuse before any state mutation. restore() passes a
        // deserialized index here, so this also guards scene loading. Say it out
        // loud: running out is a state someone has to be able to see, and slot
        // retirement below spends this space to buy handle uniqueness.
        if (index > Entity::INDEX_MASK) {
            ES_LOG_ERROR("Registry: entity index space exhausted ({} slots, {} retired to "
                         "generation wrap); create() returns an invalid entity from here on",
                         static_cast<u32>(Entity::INDEX_MASK) + 1u, retired_slots_);
            return INVALID_ENTITY;
        }
        if (index >= entityValid_.size()) {
            entityValid_.resize(index + 1, false);
            disabled_.resize(index + 1, 0);
            destruction_pending_.resize(index + 1, 0);
            generations_.resize(index + 1, 0);
            component_masks_.resize(index + 1);
        }
        entityValid_[index] = true;
        disabled_[index] = 0;
        destruction_pending_[index] = 0;
        if (disabled_count_) ++activity_epoch_;
        generations_[index] = (generations_[index] + 1) & Entity::GEN_MASK;
        if (generations_[index] == 0) generations_[index] = 1;
        component_masks_[index].reset();
        ++entity_count_;
        const auto entity = Entity::make(index, generations_[index]);
        recordEntityChange(entity);
        return entity;
    }

    // =========================================================================
    // Data Members
    // =========================================================================

    std::vector<u8> entityValid_;
    EntityChangeJournal entity_changes_;
    static constexpr u64 RESET_EPOCH_LIMIT = (u64{1} << 53) - 1;
    u64 entity_reset_epoch_ = 0;

    template<typename T>
    void recordComponentChange(Entity entity, u32 flags = 0) {
        if constexpr (std::is_same_v<T, Parent>) flags |= ENTITY_CHANGE_SUBTREE;
        if constexpr (std::is_same_v<T, Parent> || std::is_same_v<T, Children>) {
            if (disabled_count_) ++activity_epoch_;
        }
        recordEntityChange(entity, flags, componentTypeId<T>());
    }
    std::vector<u8> disabled_;
    usize disabled_count_ = 0;
    u32 activity_epoch_ = 1;
    mutable u32 resolved_activity_epoch_ = 0;
    mutable std::vector<u8> inactive_, activity_state_;
    mutable std::vector<u32> activity_path_;

    void ensureActivity() const {
        if (resolved_activity_epoch_ == activity_epoch_) return;
        inactive_.assign(entityValid_.size(), 0);
        activity_state_.assign(entityValid_.size(), 0);
        const auto* parents = getPool<Parent>();
        // Each entity is resolved once, iteratively: deep chains do not recurse
        // or repeatedly walk their ancestors. O(entities + parent links).
        for (usize start = 0; start < entityValid_.size(); ++start) {
            if (!entityValid_[start] || activity_state_[start] == 2) continue;
            activity_path_.clear();
            u32 at = static_cast<u32>(start);
            bool off = false;
            for (;;) {
                if (activity_state_[at] == 2) { off = inactive_[at] != 0; break; }
                if (activity_state_[at] == 1) { off = true; break; }
                activity_state_[at] = 1;
                activity_path_.push_back(at);
                if (disabled_[at]) { off = true; break; }
                const auto* parent = parents ? parents->tryGet(Entity::make(at, generations_[at])) : nullptr;
                if (!parent || !valid(parent->entity)) break;
                at = parent->entity.index();
            }
            for (u32 index : activity_path_) {
                inactive_[index] = off ? 1 : 0;
                activity_state_[index] = 2;
            }
        }
        resolved_activity_epoch_ = activity_epoch_;
    }
    std::vector<u32> generations_;
    std::vector<ComponentMask> component_masks_;
    std::queue<u32> recycled_;      ///< Recycled entity indices
    /// Slots taken out of circulation because their generation ran out. Counted
    /// rather than stored: nothing may hand them out again, so the only use for
    /// them is telling an operator that churn is consuming index space.
    u32 retired_slots_ = 0;
    u32 next_index_ = 0;            ///< Next fresh entity index
    usize entity_count_ = 0;

    /** @brief Type-erased component pools indexed by TypeId */
    std::vector<Unique<SparseSetBase>> pools_;

    /// The tick a write is stamped with (see beginChangeRead). Starts at 1: 0 is "never written".
    u32 change_tick_ = 1;
    /// See identity(): drawn from the counter every revision comes from, so no two registries share one.
    u64 identity_ = nextRevision();
    bool change_audit_ = false;
    std::vector<SparseSetBase::AuditCopy> audit_copies_;
    std::vector<u8> audit_reported_;
    u32 audit_unstamped_total_ = 0;

    Signal<void(Entity)> on_destroy_signal_;
    // Indexed by the canonical entity slot/generation. Grow during activation,
    // never allocate one hash node per teardown or a whole-world array on the
    // first deletion. Recycled slots start unreserved.
    std::vector<u8> destruction_pending_;
};

}  // namespace esengine::ecs