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.

8.8 KB
Raw Blame
// Native harness for Registry/SparseSet release-safety (Audit A6 + A7).
//
// Header-only against Registry.hpp (no esengine link), runs on any C++20 toolchain.
// IMPORTANT: compiled WITHOUT -DES_DEBUG, so ES_ASSERT expands to ((void)0) —
// exactly the release config where these bugs bite. Under the old code:
//   A6: get<T> on a non-member entity indexed components_[INVALID_INDEX] (OOB read).
//   A7: a re-entrant destroy(entity) from an onDestroy callback ran teardown twice,
//       underflowing entity_count_ and double-recycling the index.
//
//   clang++ -std=c++20 -I src tests/ecs/test_registry_safety.cpp \
//     src/esengine/core/Log.cpp -o /tmp/test_reg && /tmp/test_reg

#include "esengine/ecs/Registry.hpp"

#include <cstdio>

using esengine::Entity;
using esengine::u32;
using esengine::ecs::Registry;

namespace {
struct Pos { float x = 1.0f; float y = 2.0f; };
struct Vel { float dx = 0.0f; };
}

static int g_failures = 0;
#define CHECK(cond, msg)                                                        \
    do {                                                                        \
        if (!(cond)) { std::printf("FAIL: %s\n", msg); ++g_failures; }          \
        else { std::printf("ok:   %s\n", msg); }                                \
    } while (0)

// Counts ES_VERIFY failures so tests can assert "the guard fired and the
// recovery is the real value" rather than just "it didn't crash".
static int g_verifyHits = 0;
static void countingVerifyHook(const char*, const char*, int) { ++g_verifyHits; }

int main() {
    // --- get<T> has a contract; absence goes through the checked API ---
    // A miss aborts, so absence is asked with has/tryGet and created with
    // getOrEmplace — the three doors, each exercised below.
    {
        Registry r;
        Entity e = r.create();
        r.emplace<Pos>(e, Pos{10.0f, 20.0f});

        CHECK(r.get<Pos>(e).x == 10.0f, "get returns the real component when present");
        CHECK(r.tryGet<Pos>(e) == &r.get<Pos>(e), "tryGet points at the same component");

        // Pool exists, but this entity is not a member.
        Entity other = r.create();
        CHECK(!r.has<Pos>(other), "has<Pos> is false for a non-member");
        CHECK(r.tryGet<Pos>(other) == nullptr, "tryGet<Pos> on a non-member is null");

        // Pool does not exist at all.
        CHECK(!r.has<Vel>(e), "has<Vel> is false with no Vel pool");
        CHECK(r.tryGet<Vel>(e) == nullptr, "tryGet<Vel> with no Vel pool is null");

        // getOrEmplace is the third door: create it rather than assume or check.
        Vel& v = r.getOrEmplace<Vel>(e, Vel{3.0f});
        CHECK(v.dx == 3.0f && r.has<Vel>(e), "getOrEmplace creates the missing component");
        CHECK(&r.getOrEmplace<Vel>(e) == &v, "getOrEmplace returns the existing one on the next call");
    }

    // --- A7: re-entrant destroy(entity) from onDestroy must not double-teardown ---
    {
        Registry r;
        Entity e = r.create();
        int calls = 0;
        // Hold the Connection: onDestroy now returns an RAII handle (RC12); a
        // discarded return would disconnect immediately and the callback would
        // never fire, making the re-entrancy below untested.
        esengine::Connection conn = r.onDestroy([&](Entity ent) {
            if (calls++ == 0) r.destroy(ent);  // re-entrant destroy of the SAME entity
        });
        CHECK(r.entityCount() == 1u, "one live entity before destroy");

        r.destroy(e);
        CHECK(r.entityCount() == 0u, "entity_count is 0 after re-entrant destroy (no underflow)");

        // Weak assertion (kept for documentation): create()'s `if (entityValid_[index])`
        // guard masks the double-recycle — the duplicate idx is skipped on the second
        // pop — so this passes even against the old code. The real, testable harm of
        // double-recycle is the entity_count underflow asserted above.
        Entity a = r.create();
        Entity b = r.create();
        CHECK(a.index() != b.index(), "indices not aliased after re-entrant destroy");
        CHECK(r.valid(a) && r.valid(b), "both recreated entities are valid");
    }

    // --- onDestroy: the RAII Connection auto-unregisters on scope exit ---
    // A system that held a raw callback id and forgot to remove it left a
    // dangling `this` in the registry (the ParticleSystem / SpineSystem bug).
    // The Connection makes that impossible: the callback is gone once the
    // returned Connection is destroyed. ASAN here would catch a disconnect
    // that reached into freed memory.
    {
        Registry r;
        int hits = 0;
        {
            auto conn = r.onDestroy([&](Entity) { ++hits; });
            Entity e = r.create();
            r.destroy(e);
            CHECK(hits == 1, "scoped onDestroy fires while the Connection is alive");
        }
        // Connection destroyed -> callback unregistered.
        Entity e2 = r.create();
        r.destroy(e2);
        CHECK(hits == 1, "callback no longer fires once the Connection is destroyed");
    }

    // emplace on an invalid entity would write component_masks_[sentinel] out of
    // bounds and has no component to return: fatal, not a fallback. valid() is
    // how a caller asks beforehand; the abort itself is not exercised here.
    {
        Registry r;
        CHECK(!r.valid(Entity{}), "the invalid sentinel does not pass valid()");
        Entity e = r.create();
        r.destroy(e);
        CHECK(!r.valid(e), "a destroyed entity does not pass valid()");
    }

    // --- ES_VERIFY: restore() with an over-range (deserialized) index is refused ---
    // This is the scene-loading path: a corrupt/huge index must not silently
    // alias an existing slot via Entity::make's 20-bit mask.
    {
        esengine::detail::verifyHook() = countingVerifyHook;
        Registry r;
        Entity a = r.create();  // real entity at index 0

        g_verifyHits = 0;
        Entity bad = r.restore(Entity::INDEX_MASK + 1);  // beyond the 20-bit range
        CHECK(g_verifyHits == 1, "restore(over-range) fires the verify hook");
        CHECK(!bad.isValid(), "restore(over-range) returns INVALID_ENTITY (no silent alias)");
        CHECK(r.valid(a), "the pre-existing entity is untouched after a bad restore");

        // next_index_ must not be corrupted by the rejected restore: fresh
        // allocation still works and does not alias the survivor.
        Entity c = r.create();
        CHECK(r.valid(c) && c.index() != a.index(), "create() still works after a rejected restore");

        esengine::detail::verifyHook() = nullptr;
    }

    // --- ES_VERIFY: duplicate emplace degrades to the existing component ---
    // A second emplace on the same entity would push a duplicate dense slot and
    // overwrite the sparse mapping (corruption). The guard degrades to get().
    {
        esengine::detail::verifyHook() = countingVerifyHook;
        Registry r;
        Entity e = r.create();
        r.emplace<Pos>(e, Pos{3.0f, 4.0f});

        g_verifyHits = 0;
        Pos& dup = r.emplace<Pos>(e, Pos{100.0f, 200.0f});  // duplicate
        CHECK(g_verifyHits == 1, "duplicate emplace fires the verify hook");
        CHECK(dup.x == 3.0f && dup.y == 4.0f, "duplicate emplace returns the existing component (no corruption)");
        CHECK(r.get<Pos>(e).x == 3.0f, "entity still maps to the original component");

        esengine::detail::verifyHook() = nullptr;
    }

    // --- PackedId / Entity 22+10 packing is correct and round-trips ---
    {
        CHECK(Entity::INDEX_BITS == 22u && Entity::GEN_BITS == 10u, "Entity split is 22+10");
        CHECK(Entity::INDEX_MASK == 0x3FFFFFu, "index mask is 2^22-1");
        CHECK(Entity::GEN_MASK == 0x3FFu, "generation mask is 2^10-1");

        // Round-trip across the corners, including the max generation that would
        // overflow a signed-32 shift on the JS side (here it's unsigned C++).
        const u32 idxs[] = {0u, 1u, 1234u, Entity::INDEX_MASK};
        const u32 gens[] = {1u, 2u, 512u, Entity::GEN_MASK};
        bool roundtrip_ok = true;
        for (u32 idx : idxs) {
            for (u32 gen : gens) {
                Entity e = Entity::make(idx, gen);
                if (e.index() != idx || e.generation() != gen) roundtrip_ok = false;
                if (Entity::fromRaw(e.id()) != e) roundtrip_ok = false;
            }
        }
        CHECK(roundtrip_ok, "Entity::make/index/generation/fromRaw round-trip for all corners");

        // PackedId is the single source the split is derived from.
        using L = esengine::PackedId<22, 10>;
        CHECK(L::pack(7u, 3u) == Entity::make(7u, 3u).raw, "PackedId::pack matches Entity::make");
        CHECK(L::indexOf(L::pack(99u, 5u)) == 99u, "PackedId index round-trips");
        CHECK(L::generationOf(L::pack(99u, 5u)) == 5u, "PackedId generation round-trips");
    }

    if (g_failures == 0) {
        std::printf("\nALL ECS SAFETY TESTS PASSED\n");
        return 0;
    }
    std::printf("\n%d FAILURE(S)\n", g_failures);
    return 1;
}