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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include <doctest.h>
#include <esengine/ESEngine.hpp>
#include <esengine/resource/ResourcePool.hpp>
#include <string>
#include <memory>
namespace test {
struct DummyResource {
int value = 0;
explicit DummyResource(int v = 0) : value(v) {}
};
using DummyHandle = esengine::resource::Handle<DummyResource>;
using DummyPool = esengine::resource::ResourcePool<DummyResource>;
constexpr esengine::usize SENTINEL_SIZE = 0;
} // namespace test
TEST_CASE("handle_invalid_by_default") {
test::DummyHandle handle;
CHECK(!handle.isValid());
CHECK_EQ(handle.id(), test::DummyHandle::INVALID);
CHECK(!static_cast<bool>(handle));
}
TEST_CASE("handle_from_parts") {
auto handle = test::DummyHandle::fromParts(42, 3);
CHECK(handle.isValid());
CHECK_EQ(handle.index(), 42u);
CHECK_EQ(handle.generation(), 3u);
}
TEST_CASE("handle_equality") {
auto h1 = test::DummyHandle::fromParts(1, 0);
auto h2 = test::DummyHandle::fromParts(1, 0);
auto h3 = test::DummyHandle::fromParts(2, 0);
auto h4 = test::DummyHandle::fromParts(1, 1);
CHECK(h1 == h2);
CHECK(h1 != h3);
CHECK(h1 != h4);
}
TEST_CASE("handle_extract_static") {
auto handle = test::DummyHandle::fromParts(123, 7);
auto id = handle.id();
CHECK_EQ(test::DummyHandle::extractIndex(id), 123u);
CHECK_EQ(test::DummyHandle::extractGeneration(id), 7u);
}
TEST_CASE("pool_add_and_get") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(42));
CHECK(handle.isValid());
CHECK_EQ(pool.size(), 1u + test::SENTINEL_SIZE);
auto* resource = pool.get(handle);
CHECK(resource != nullptr);
CHECK_EQ(resource->value, 42);
}
TEST_CASE("pool_add_multiple") {
test::DummyPool pool;
auto h1 = pool.add(esengine::makeUnique<test::DummyResource>(1));
auto h2 = pool.add(esengine::makeUnique<test::DummyResource>(2));
auto h3 = pool.add(esengine::makeUnique<test::DummyResource>(3));
CHECK_EQ(pool.size(), 3u + test::SENTINEL_SIZE);
CHECK(h1 != h2);
CHECK(h2 != h3);
CHECK_EQ(pool.get(h1)->value, 1);
CHECK_EQ(pool.get(h2)->value, 2);
CHECK_EQ(pool.get(h3)->value, 3);
}
TEST_CASE("pool_initial_ref_count") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(10));
CHECK_EQ(pool.getRefCount(handle), 1u);
}
TEST_CASE("pool_add_ref") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(10));
pool.addRef(handle);
CHECK_EQ(pool.getRefCount(handle), 2u);
pool.addRef(handle);
CHECK_EQ(pool.getRefCount(handle), 3u);
}
TEST_CASE("pool_release_decrements_ref_count") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(10));
pool.addRef(handle);
CHECK_EQ(pool.getRefCount(handle), 2u);
pool.release(handle.id());
CHECK_EQ(pool.getRefCount(handle), 1u);
auto* resource = pool.get(handle);
CHECK(resource != nullptr);
CHECK_EQ(resource->value, 10);
}
TEST_CASE("pool_release_frees_at_zero") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(10));
CHECK_EQ(pool.size(), 1u + test::SENTINEL_SIZE);
pool.release(handle.id());
CHECK_EQ(pool.size(), 0u + test::SENTINEL_SIZE);
CHECK(pool.get(handle) == nullptr);
}
TEST_CASE("pool_slot_reuse_with_generation") {
test::DummyPool pool;
auto h1 = pool.add(esengine::makeUnique<test::DummyResource>(1));
auto h1Index = h1.index();
pool.release(h1.id());
auto h2 = pool.add(esengine::makeUnique<test::DummyResource>(2));
CHECK_EQ(h2.index(), h1Index);
CHECK_NE(h1.generation(), h2.generation());
CHECK(pool.get(h1) == nullptr);
CHECK_EQ(pool.get(h2)->value, 2);
}
TEST_CASE("pool_stale_handle_returns_null") {
test::DummyPool pool;
auto h1 = pool.add(esengine::makeUnique<test::DummyResource>(1));
pool.release(h1.id());
auto h2 = pool.add(esengine::makeUnique<test::DummyResource>(2));
(void)h2;
CHECK(pool.get(h1) == nullptr);
}
TEST_CASE("pool_path_based_lookup") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(42), "textures/player.png");
auto found = pool.findByPath("textures/player.png");
CHECK(found.isValid());
CHECK_EQ(found.id(), handle.id());
auto notFound = pool.findByPath("textures/enemy.png");
CHECK(!notFound.isValid());
}
TEST_CASE("pool_set_path") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(42));
pool.setPath(handle, "shaders/default.glsl");
auto found = pool.findByPath("shaders/default.glsl");
CHECK(found.isValid());
CHECK_EQ(found.id(), handle.id());
CHECK_EQ(pool.getPath(handle), "shaders/default.glsl");
}
TEST_CASE("pool_path_cleared_on_release") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(1), "asset.png");
pool.release(handle.id());
auto found = pool.findByPath("asset.png");
CHECK(!found.isValid());
}
TEST_CASE("pool_clear") {
test::DummyPool pool;
auto h1 = pool.add(esengine::makeUnique<test::DummyResource>(1), "a.png");
auto h2 = pool.add(esengine::makeUnique<test::DummyResource>(2), "b.png");
pool.clear();
CHECK_EQ(pool.size(), 0u);
CHECK(pool.get(h1) == nullptr);
CHECK(pool.get(h2) == nullptr);
CHECK(!pool.findByPath("a.png").isValid());
}
TEST_CASE("pool_const_get") {
test::DummyPool pool;
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(55));
const auto& constPool = pool;
const auto* resource = constPool.get(handle);
CHECK(resource != nullptr);
CHECK_EQ(resource->value, 55);
}
TEST_CASE("pool_multiple_release_cycles") {
test::DummyPool pool;
for (int cycle = 0; cycle < 10; ++cycle) {
auto handle = pool.add(esengine::makeUnique<test::DummyResource>(cycle));
CHECK_EQ(pool.get(handle)->value, cycle);
pool.release(handle.id());
CHECK_EQ(pool.size(), 0u + test::SENTINEL_SIZE);
}
}
TEST_CASE("pool_mixed_operations") {
test::DummyPool pool;
auto h1 = pool.add(esengine::makeUnique<test::DummyResource>(1));
auto h2 = pool.add(esengine::makeUnique<test::DummyResource>(2));
auto h3 = pool.add(esengine::makeUnique<test::DummyResource>(3));
CHECK_EQ(pool.size(), 3u + test::SENTINEL_SIZE);
pool.release(h2.id());
CHECK_EQ(pool.size(), 2u + test::SENTINEL_SIZE);
auto h4 = pool.add(esengine::makeUnique<test::DummyResource>(4));
CHECK_EQ(pool.size(), 3u + test::SENTINEL_SIZE);
CHECK_EQ(pool.get(h1)->value, 1);
CHECK(pool.get(h2) == nullptr);
CHECK_EQ(pool.get(h3)->value, 3);
CHECK_EQ(pool.get(h4)->value, 4);
pool.addRef(h1);
pool.release(h1.id());
CHECK_EQ(pool.getRefCount(h1), 1u);
CHECK_EQ(pool.get(h1)->value, 1);
pool.release(h1.id());
CHECK(pool.get(h1) == nullptr);
}
// =============================================================================
// Eviction budget + LRU: held → evictable → evicted
// =============================================================================
TEST_CASE("pool_budget_zero_frees_immediately") {
// Default (budget 0) is unchanged: refCount 0 → freed at once, not cached.
test::DummyPool pool;
auto h = pool.add(esengine::makeUnique<test::DummyResource>(1), "a", 100);
pool.release(h.id());
CHECK_EQ(pool.residentBytes(), 0u);
CHECK_EQ(pool.evictableCount(), 0u);
CHECK(!pool.findByPath("a").isValid());
CHECK(pool.get(h) == nullptr);
}
TEST_CASE("pool_budget_retains_released_as_evictable_cache") {
test::DummyPool pool;
pool.setBudget(1000);
auto h = pool.add(esengine::makeUnique<test::DummyResource>(7), "a.png", 100);
CHECK_EQ(pool.residentBytes(), 100u);
pool.release(h.id());
// Not freed — retained as an evictable cache entry: still resident + findable.
CHECK_EQ(pool.residentBytes(), 100u);
CHECK(pool.isEvictable(h));
CHECK_EQ(pool.evictableCount(), 1u);
CHECK(pool.get(h) == nullptr); // refCount 0 → must revive before use
CHECK(pool.findByPath("a.png").isValid()); // but a cache hit can still find it
}
TEST_CASE("pool_budget_revive_on_cache_hit") {
test::DummyPool pool;
pool.setBudget(1000);
auto h = pool.add(esengine::makeUnique<test::DummyResource>(7), "a.png", 100);
pool.release(h.id());
CHECK(pool.isEvictable(h));
auto found = pool.findByPath("a.png");
pool.addRef(found); // revive the cached entry
CHECK(!pool.isEvictable(h));
CHECK_EQ(pool.getRefCount(h), 1u);
CHECK(pool.get(h) != nullptr);
CHECK_EQ(pool.get(h)->value, 7);
CHECK_EQ(pool.evictableCount(), 0u);
}
TEST_CASE("pool_budget_evicts_oldest_first") {
test::DummyPool pool;
pool.setBudget(250);
auto a = pool.add(esengine::makeUnique<test::DummyResource>(1), "a", 100);
auto b = pool.add(esengine::makeUnique<test::DummyResource>(2), "b", 100);
auto c = pool.add(esengine::makeUnique<test::DummyResource>(3), "c", 100);
CHECK_EQ(pool.residentBytes(), 300u); // all held — allowed to exceed the budget
pool.release(a.id()); // a evictable; 300 > 250 → evict oldest (a) → 200
CHECK_EQ(pool.residentBytes(), 200u);
CHECK(pool.get(a) == nullptr);
CHECK(!pool.findByPath("a").isValid());
pool.release(b.id()); // b evictable; 200 ≤ 250 → retained as cache
CHECK_EQ(pool.residentBytes(), 200u);
CHECK(pool.isEvictable(b));
CHECK(pool.findByPath("b").isValid());
CHECK(pool.get(c) != nullptr); // c still held
}
TEST_CASE("pool_budget_never_evicts_held") {
test::DummyPool pool;
pool.setBudget(50); // smaller than even one resource
auto a = pool.add(esengine::makeUnique<test::DummyResource>(1), "a", 100);
auto b = pool.add(esengine::makeUnique<test::DummyResource>(2), "b", 100);
// Both held → never evicted, even though resident far exceeds the budget.
CHECK_EQ(pool.residentBytes(), 200u);
CHECK_EQ(pool.evictableCount(), 0u);
CHECK(pool.get(a) != nullptr);
CHECK(pool.get(b) != nullptr);
}
TEST_CASE("pool_set_budget_evicts_now") {
test::DummyPool pool;
pool.setBudget(1000);
auto a = pool.add(esengine::makeUnique<test::DummyResource>(1), "a", 100);
auto b = pool.add(esengine::makeUnique<test::DummyResource>(2), "b", 100);
pool.release(a.id());
pool.release(b.id());
CHECK_EQ(pool.evictableCount(), 2u);
pool.setBudget(100); // shrink → evict oldest until ≤ 100: a goes, b (100) stays
CHECK_EQ(pool.residentBytes(), 100u);
CHECK(!pool.findByPath("a").isValid());
CHECK(pool.findByPath("b").isValid());
}
TEST_CASE("pool_budget_pathless_frees_immediately") {
// A pathless entry can never be revived (findByPath is the only revive
// channel), so even under a budget it frees at refCount 0 instead of
// squatting on the budget as an unreachable cache entry.
test::DummyPool pool;
pool.setBudget(1000);
auto h = pool.add(esengine::makeUnique<test::DummyResource>(1), "", 100);
pool.release(h.id());
CHECK_EQ(pool.residentBytes(), 0u);
CHECK_EQ(pool.evictableCount(), 0u);
CHECK(pool.get(h) == nullptr);
}
TEST_CASE("pool_invalidate_path_frees_evictable") {
test::DummyPool pool;
pool.setBudget(1000);
auto h = pool.add(esengine::makeUnique<test::DummyResource>(1), "a.png", 100);
pool.release(h.id());
CHECK(pool.isEvictable(h));
CHECK(pool.invalidatePath("a.png"));
CHECK_EQ(pool.residentBytes(), 0u);
CHECK_EQ(pool.evictableCount(), 0u);
CHECK(!pool.findByPath("a.png").isValid());
CHECK(!pool.invalidatePath("a.png")); // already gone
}
TEST_CASE("pool_invalidate_path_on_held_entry") {
// A held entry stays alive for its current holders but loses its cache
// identity: no future cache hit, and its final release frees it outright.
test::DummyPool pool;
pool.setBudget(1000);
auto h = pool.add(esengine::makeUnique<test::DummyResource>(9), "a.png", 100);
CHECK(pool.invalidatePath("a.png"));
CHECK(pool.get(h) != nullptr); // still usable while held
CHECK(!pool.findByPath("a.png").isValid()); // but no longer findable
pool.release(h.id()); // pathless now → freed, not cached
CHECK_EQ(pool.residentBytes(), 0u);
CHECK_EQ(pool.evictableCount(), 0u);
CHECK(pool.get(h) == nullptr);
}
TEST_CASE("pool_trim_evictables_drops_warm_cache_only") {
// Memory pressure: the whole warm cache goes at once, held entries and
// the budget survive, and the cache can refill afterwards.
test::DummyPool pool;
pool.setBudget(1000);
auto held = pool.add(esengine::makeUnique<test::DummyResource>(1), "held", 100);
auto a = pool.add(esengine::makeUnique<test::DummyResource>(2), "a", 100);
auto b = pool.add(esengine::makeUnique<test::DummyResource>(3), "b", 100);
pool.release(a.id());
pool.release(b.id());
CHECK_EQ(pool.evictableCount(), 2u);
CHECK_EQ(pool.trimEvictables(), 2u);
CHECK_EQ(pool.evictableCount(), 0u);
CHECK_EQ(pool.residentBytes(), 100u); // only the held entry remains
CHECK(pool.get(held) != nullptr);
CHECK(!pool.findByPath("a").isValid());
CHECK_EQ(pool.budget(), 1000u); // budget untouched
pool.release(held.id()); // cache refills after the trim
CHECK_EQ(pool.evictableCount(), 1u);
CHECK_EQ(pool.trimEvictables(), 1u);
CHECK_EQ(pool.residentBytes(), 0u);
}
TEST_CASE("pool_invalidate_path_then_reload_same_path") {
// Hot-reload sequence: invalidate, then a fresh add() under the same path
// becomes the new cache identity for it.
test::DummyPool pool;
pool.setBudget(1000);
auto stale = pool.add(esengine::makeUnique<test::DummyResource>(1), "a.png", 100);
pool.invalidatePath("a.png");
auto fresh = pool.add(esengine::makeUnique<test::DummyResource>(2), "a.png", 100);
auto found = pool.findByPath("a.png");
CHECK(found.isValid());
CHECK_EQ(found.id(), fresh.id());
CHECK(found != stale);
pool.release(stale.id()); // stale holder done → freed (pathless)
CHECK(pool.findByPath("a.png").isValid()); // fresh identity unaffected
CHECK_EQ(pool.get(fresh)->value, 2);
}