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
perf: optimize ECS registry with flat vector pools and generational handles
esengine47367e45e1a4
diff --git a/src/esengine/core/Log.hpp b/src/esengine/core/Log.hppindex 32172f3fb..ee6dc2a96 100644--- a/src/esengine/core/Log.hpp+++ b/src/esengine/core/Log.hpp@@ -196,17 +196,14 @@ private:static void log(LogLevel level, const char* fmt, Args&&... args) {if (level < level_) return;- std::ostringstream msgOss;- formatTo(msgOss, fmt, std::forward<Args>(args)...);- std::string message = msgOss.str();-std::ostringstream oss;- oss << "[" << levelToString(level) << "] " << message << "\n";+ formatTo(oss, fmt, std::forward<Args>(args)...);+ std::string message = oss.str();if (level >= LogLevel::Error) {- std::cerr << oss.str();+ std::cerr << "[" << levelToString(level) << "] " << message << "\n";} else {- std::cout << oss.str();+ std::cout << "[" << levelToString(level) << "] " << message << "\n";}notifySinks(level, message);diff --git a/src/esengine/ecs/Component.hpp b/src/esengine/ecs/Component.hppindex 5bf801e40..646ae1b46 100644--- a/src/esengine/ecs/Component.hpp+++ b/src/esengine/ecs/Component.hpp@@ -6,7 +6,7 @@* reduced compile times in larger projects.** Component files:- * - components/Transform.hpp - LocalTransform, WorldTransform, TransformDirty, TransformStatic+ * - components/Transform.hpp - Transform, TransformDirty, TransformStatic* - components/Hierarchy.hpp - Parent, Children, HierarchyDepth* - components/Sprite.hpp - Sprite* - components/Camera.hpp - Camera, ProjectionTypediff --git a/src/esengine/ecs/DynamicComponent.hpp b/src/esengine/ecs/DynamicComponent.hppindex bb5dce870..1b7abc8c0 100644--- a/src/esengine/ecs/DynamicComponent.hpp+++ b/src/esengine/ecs/DynamicComponent.hpp@@ -125,7 +125,7 @@ public:const auto index = sparse_[entity];dense_[index] = last;- values_[index] = std::move(values_.back());+ std::swap(values_[index], values_.back());sparse_[last] = index;dense_.pop_back();diff --git a/src/esengine/ecs/Registry.hpp b/src/esengine/ecs/Registry.hppindex f185526ad..144cd17bf 100644--- a/src/esengine/ecs/Registry.hpp+++ b/src/esengine/ecs/Registry.hpp@@ -29,7 +29,6 @@#include <any>#include <functional>#include <queue>-#include <unordered_map>namespace esengine::ecs {@@ -61,6 +60,8 @@ namespace esengine::ecs {*/class Registry {public:+ static constexpr u32 MAX_TRACKED_COMPONENTS = 64;+Registry() = default;~Registry() = default;@@ -94,9 +95,11 @@ public:if (entity >= entityValid_.size()) {entityValid_.resize(entity + 1, false);generations_.resize(entity + 1, 0);+ component_masks_.resize(entity + 1, 0);}entityValid_[entity] = true;generations_[entity]++;+ component_masks_[entity] = 0;++entity_count_;ES_LOG_TRACE("Created entity {}", entity);@@ -130,9 +133,11 @@ public:if (entity >= entityValid_.size()) {entityValid_.resize(entity + 1, false);generations_.resize(entity + 1, 0);+ component_masks_.resize(entity + 1, 0);}entityValid_[entity] = true;generations_[entity]++;+ component_masks_[entity] = 0;++entity_count_;if (entity >= nextEntity_) {@@ -153,14 +158,23 @@ public:void destroy(Entity entity) {if (!valid(entity)) return;- // Remove all static components from this entity- for (auto& [typeId, pool] : pools_) {- pool->remove(entity);+ u64 mask = component_masks_[entity];+ while (mask != 0) {+ u32 bit = static_cast<u32>(__builtin_ctzll(mask));+ if (bit < pools_.size() && pools_[bit]) {+ pools_[bit]->remove(entity);+ }+ mask &= mask - 1;+ }+ for (usize i = MAX_TRACKED_COMPONENTS; i < pools_.size(); ++i) {+ if (pools_[i]) {+ pools_[i]->remove(entity);+ }}- // Remove all schema components from this entityschemaRegistry_.removeAll(entity);+ component_masks_[entity] = 0;entityValid_[entity] = false;--entity_count_;recycled_.push(entity);@@ -229,7 +243,12 @@ public:T& emplace(Entity entity, Args&&... args) {ES_ASSERT(valid(entity), "Invalid entity");auto& pool = assurePool<T>();- return pool.emplace(entity, std::forward<Args>(args)...);+ auto& result = pool.emplace(entity, std::forward<Args>(args)...);+ TypeId typeId = getTypeId<T>();+ if (typeId < MAX_TRACKED_COMPONENTS) {+ component_masks_[entity] |= (u64{1} << typeId);+ }+ return result;}/**@@ -251,7 +270,12 @@ public:pool.get(entity) = T(std::forward<Args>(args)...);return pool.get(entity);}- return pool.emplace(entity, std::forward<Args>(args)...);+ auto& result = pool.emplace(entity, std::forward<Args>(args)...);+ TypeId typeId = getTypeId<T>();+ if (typeId < MAX_TRACKED_COMPONENTS) {+ component_masks_[entity] |= (u64{1} << typeId);+ }+ return result;}/**@@ -266,6 +290,10 @@ public:auto* pool = getPool<T>();if (pool) {pool->remove(entity);+ TypeId typeId = getTypeId<T>();+ if (typeId < MAX_TRACKED_COMPONENTS && entity < component_masks_.size()) {+ component_masks_[entity] &= ~(u64{1} << typeId);+ }}}@@ -325,7 +353,12 @@ public:if (pool.contains(entity)) {return pool.get(entity);}- return pool.emplace(entity, std::forward<Args>(args)...);+ auto& result = pool.emplace(entity, std::forward<Args>(args)...);+ TypeId typeId = getTypeId<T>();+ if (typeId < MAX_TRACKED_COMPONENTS) {+ component_masks_[entity] |= (u64{1} << typeId);+ }+ return result;}/**@@ -402,11 +435,14 @@ public:* @details Resets the registry to its initial empty state.*/void clear() {- for (auto& [typeId, pool] : pools_) {- pool->clear();+ for (auto& pool : pools_) {+ if (pool) {+ pool->clear();+ }}entityValid_.clear();generations_.clear();+ component_masks_.clear();while (!recycled_.empty()) recycled_.pop();nextEntity_ = 0;entity_count_ = 0;@@ -511,6 +547,11 @@ public:return schemaRegistry_.getPoolStride(poolId);}+ /** @brief Gets schema pool version (detects reallocation) */+ u32 getSchemaPoolVersion(u32 poolId) const {+ return schemaRegistry_.getPoolVersion(poolId);+ }+/** @brief Gets entities with schema component */const std::vector<Entity>& getSchemaEntities(u32 poolId) const {return schemaRegistry_.getEntities(poolId);@@ -533,14 +574,13 @@ private:template<typename T>SparseSet<T>& assurePool() {TypeId typeId = getTypeId<T>();- auto it = pools_.find(typeId);- if (it == pools_.end()) {- auto pool = makeUnique<SparseSet<T>>();- auto& ref = *pool;- pools_[typeId] = std::move(pool);- return ref;+ if (typeId >= pools_.size()) {+ pools_.resize(typeId + 1);+ }+ if (!pools_[typeId]) {+ pools_[typeId] = makeUnique<SparseSet<T>>();}- return *static_cast<SparseSet<T>*>(it->second.get());+ return *static_cast<SparseSet<T>*>(pools_[typeId].get());}/**@@ -551,17 +591,15 @@ private:template<typename T>SparseSet<T>* getPool() {TypeId typeId = getTypeId<T>();- auto it = pools_.find(typeId);- if (it == pools_.end()) return nullptr;- return static_cast<SparseSet<T>*>(it->second.get());+ 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 = getTypeId<T>();- auto it = pools_.find(typeId);- if (it == pools_.end()) return nullptr;- return static_cast<const SparseSet<T>*>(it->second.get());+ if (typeId >= pools_.size() || !pools_[typeId]) return nullptr;+ return static_cast<const SparseSet<T>*>(pools_[typeId].get());}// =========================================================================@@ -570,12 +608,13 @@ private:std::vector<bool> entityValid_;std::vector<u32> generations_;+ std::vector<u64> component_masks_;std::queue<Entity> recycled_;Entity nextEntity_ = 0;usize entity_count_ = 0;/** @brief Type-erased component pools indexed by TypeId */- std::unordered_map<TypeId, Unique<SparseSetBase>> pools_;+ std::vector<Unique<SparseSetBase>> pools_;/** @brief Schema component registry for script-defined components */SchemaRegistry schemaRegistry_;diff --git a/src/esengine/ecs/SchemaComponent.hpp b/src/esengine/ecs/SchemaComponent.hppindex 4177be962..54137f0e8 100644--- a/src/esengine/ecs/SchemaComponent.hpp+++ b/src/esengine/ecs/SchemaComponent.hpp@@ -47,6 +47,7 @@ class SchemaComponentPool {public:explicit SchemaComponentPool(u32 stride, u32 initialCapacity = 64): stride_(stride) {+ ES_ASSERT(stride > 0, "stride must be > 0");data_.reserve(initialCapacity * stride);}@@ -79,9 +80,12 @@ public:sparse_[entity] = index;dense_.push_back(entity);- // Allocate space for component data (zero-initialized)usize oldSize = data_.size();+ const u8* oldPtr = data_.data();data_.resize(oldSize + stride_, 0);+ if (data_.data() != oldPtr) {+ pool_version_++;+ }return static_cast<u32>(oldSize);}@@ -134,11 +138,18 @@ public:// Memory Access// =========================================================================- /** @brief Gets base pointer for direct memory access from JS */+ /**+ * @brief Gets base pointer for direct memory access from JS+ * @warning This pointer may be invalidated by add() if the internal+ * vector reallocates. Check poolVersion() to detect changes.+ */uintptr_t basePtr() const {return reinterpret_cast<uintptr_t>(data_.data());}+ /** @brief Version counter incremented on each potential reallocation */+ u32 poolVersion() const { return pool_version_; }+/** @brief Gets the stride (bytes per component) */u32 stride() const { return stride_; }@@ -173,6 +184,7 @@ public:private:u32 stride_; ///< Bytes per component+ u32 pool_version_ = 0; ///< Incremented on potential reallocationstd::vector<u8> data_; ///< Contiguous component datastd::vector<u32> sparse_; ///< Entity -> dense indexstd::vector<Entity> dense_; ///< Dense entity array@@ -269,6 +281,12 @@ public:return pools_[poolId]->stride();}+ /** @brief Gets pool version (incremented on reallocation) */+ u32 getPoolVersion(u32 poolId) const {+ if (poolId >= pools_.size()) return 0;+ return pools_[poolId]->poolVersion();+ }+/** @brief Gets entities with component */const std::vector<Entity>& getEntities(u32 poolId) const {static const std::vector<Entity> empty;diff --git a/src/esengine/resource/Handle.hpp b/src/esengine/resource/Handle.hppindex d637c2fce..b4931d590 100644--- a/src/esengine/resource/Handle.hpp+++ b/src/esengine/resource/Handle.hpp@@ -48,23 +48,49 @@ template<typename T>class Handle {public:using IdType = u32;++ static constexpr u32 INDEX_BITS = 20;+ static constexpr u32 GEN_BITS = 12;+ static constexpr u32 INDEX_MASK = (1u << INDEX_BITS) - 1;+ static constexpr u32 GEN_MASK = (1u << GEN_BITS) - 1;static constexpr IdType INVALID = std::numeric_limits<IdType>::max();/** @brief Creates an invalid handle */Handle() = default;/**- * @brief Creates a handle with the given ID- * @param id The resource identifier+ * @brief Creates a handle from a packed ID (index + generation)+ * @param id The packed resource identifier*/explicit Handle(IdType id) : id_(id) {}+ /**+ * @brief Creates a handle from separate index and generation+ * @param index Slot index in the resource pool (max ~1M)+ * @param generation Reuse counter for the slot (max 4095)+ */+ static Handle fromParts(u32 index, u32 generation) {+ return Handle(((generation & GEN_MASK) << INDEX_BITS) | (index & INDEX_MASK));+ }+/** @brief Checks if the handle references a valid resource */bool isValid() const { return id_ != INVALID; }- /** @brief Gets the raw identifier */+ /** @brief Gets the packed identifier (index + generation) */IdType id() const { return id_; }+ /** @brief Extracts the slot index from the packed handle */+ u32 index() const { return id_ & INDEX_MASK; }++ /** @brief Extracts the generation from the packed handle */+ u32 generation() const { return (id_ >> INDEX_BITS) & GEN_MASK; }++ /** @brief Extracts index from a raw packed ID */+ static u32 extractIndex(IdType packed) { return packed & INDEX_MASK; }++ /** @brief Extracts generation from a raw packed ID */+ static u32 extractGeneration(IdType packed) { return (packed >> INDEX_BITS) & GEN_MASK; }+/** @brief Equality comparison */bool operator==(const Handle& other) const { return id_ == other.id_; }diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cppindex a90ab6d12..602cf30bd 100644--- a/src/esengine/resource/ResourceManager.cpp+++ b/src/esengine/resource/ResourceManager.cpp@@ -86,6 +86,16 @@ ShaderHandle ResourceManager::createShader(const std::string& vertSrc, const stdreturn shaders_.add(std::move(shader));}+ShaderHandle ResourceManager::createShaderWithBindings(const std::string& vertSrc, const std::string& fragSrc,+ std::initializer_list<AttribBinding> bindings) {+ auto shader = Shader::createWithBindings(vertSrc, fragSrc, bindings);+ if (!shader) {+ ES_LOG_ERROR("Failed to create shader with bindings from source");+ return ShaderHandle();+ }+ return shaders_.add(std::move(shader));+}+ShaderHandle ResourceManager::loadShader(const std::string& vertPath, const std::string& fragPath) {// Create cache key from pathsstd::string cacheKey = vertPath + ":" + fragPath;@@ -260,6 +270,16 @@ const Texture* ResourceManager::getTexture(TextureHandle handle) const {void ResourceManager::releaseTexture(TextureHandle handle) {if (handle.isValid()) {+ if (textures_.getRefCount(handle) == 1) {+ textureMetadata_.erase(handle.id());+ for (auto it = guidToTexture_.begin(); it != guidToTexture_.end(); ) {+ if (it->second == handle) {+ it = guidToTexture_.erase(it);+ } else {+ ++it;+ }+ }+ }textures_.release(handle.id());}}diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hppindex 93b93ab0f..70f7cefd8 100644--- a/src/esengine/resource/ResourceManager.hpp+++ b/src/esengine/resource/ResourceManager.hpp@@ -140,6 +140,8 @@ public:* @return Handle to the shader, or invalid handle on failure*/ShaderHandle createShader(const std::string& vertSrc, const std::string& fragSrc);+ ShaderHandle createShaderWithBindings(const std::string& vertSrc, const std::string& fragSrc,+ std::initializer_list<AttribBinding> bindings);/*** @brief Loads a shader from file paths (with caching)diff --git a/src/esengine/resource/ResourcePool.hpp b/src/esengine/resource/ResourcePool.hppindex 46654fd7d..b901e633a 100644--- a/src/esengine/resource/ResourcePool.hpp+++ b/src/esengine/resource/ResourcePool.hpp@@ -89,6 +89,7 @@ public:Unique<T> resource; ///< The owned resourceu32 refCount = 0; ///< Reference count (0 = freed)std::string path; ///< Optional path for caching+ u32 generation = 0; ///< Reuse counter for stale handle detection};ResourcePool() = default;@@ -107,19 +108,23 @@ public:* @return Handle to the added resource*/Handle<T> add(Unique<T> resource, const std::string& path = "") {- u32 id;+ u32 index;+ u32 gen;if (!freeList_.empty()) {- id = freeList_.back();+ index = freeList_.back();freeList_.pop_back();- entries_[id] = {std::move(resource), 1, path};+ gen = entries_[index].generation;+ entries_[index] = {std::move(resource), 1, path, gen};} else {- id = static_cast<u32>(entries_.size());- entries_.push_back({std::move(resource), 1, path});+ index = static_cast<u32>(entries_.size());+ gen = 0;+ entries_.push_back({std::move(resource), 1, path, 0});}+ auto handle = Handle<T>::fromParts(index, gen);if (!path.empty()) {- pathToId_[path] = id;+ pathToId_[path] = handle.id();}- return Handle<T>(id);+ return handle;}/**@@ -128,11 +133,14 @@ public:* @return Pointer to the resource, or nullptr if invalid*/T* get(Handle<T> handle) {- if (!handle.isValid() || handle.id() >= entries_.size()) {+ if (!handle.isValid()) return nullptr;+ u32 idx = handle.index();+ if (idx >= entries_.size()) return nullptr;+ auto& entry = entries_[idx];+ if (entry.refCount == 0 || entry.generation != handle.generation()) {return nullptr;}- auto& entry = entries_[handle.id()];- return entry.refCount > 0 ? entry.resource.get() : nullptr;+ return entry.resource.get();}/**@@ -141,11 +149,14 @@ public:* @return Const pointer to the resource, or nullptr if invalid*/const T* get(Handle<T> handle) const {- if (!handle.isValid() || handle.id() >= entries_.size()) {+ if (!handle.isValid()) return nullptr;+ u32 idx = handle.index();+ if (idx >= entries_.size()) return nullptr;+ const auto& entry = entries_[idx];+ if (entry.refCount == 0 || entry.generation != handle.generation()) {return nullptr;}- const auto& entry = entries_[handle.id()];- return entry.refCount > 0 ? entry.resource.get() : nullptr;+ return entry.resource.get();}/**@@ -155,7 +166,13 @@ public:*/Handle<T> findByPath(const std::string& path) const {auto it = pathToId_.find(path);- return it != pathToId_.end() ? Handle<T>(it->second) : Handle<T>();+ if (it == pathToId_.end()) return Handle<T>();+ auto handle = Handle<T>(it->second);+ u32 idx = handle.index();+ if (idx < entries_.size() && entries_[idx].generation == handle.generation()) {+ return handle;+ }+ return Handle<T>();}/**@@ -164,9 +181,11 @@ public:* @param path The path to associate*/void setPath(Handle<T> handle, const std::string& path) {- if (!handle.isValid() || handle.id() >= entries_.size()) return;- auto& entry = entries_[handle.id()];- if (entry.refCount > 0 && !path.empty()) {+ if (!handle.isValid()) return;+ u32 idx = handle.index();+ if (idx >= entries_.size()) return;+ auto& entry = entries_[idx];+ if (entry.refCount > 0 && entry.generation == handle.generation() && !path.empty()) {if (!entry.path.empty()) {pathToId_.erase(entry.path);}@@ -180,9 +199,11 @@ public:* @param handle The resource handle*/void addRef(Handle<T> handle) {- if (handle.isValid() && handle.id() < entries_.size()) {- auto& entry = entries_[handle.id()];- if (entry.refCount > 0) {+ if (!handle.isValid()) return;+ u32 idx = handle.index();+ if (idx < entries_.size()) {+ auto& entry = entries_[idx];+ if (entry.refCount > 0 && entry.generation == handle.generation()) {entry.refCount++;}}@@ -193,15 +214,19 @@ public:* @param id The resource identifier*/void release(u32 id) override {- if (id < entries_.size() && entries_[id].refCount > 0) {- if (--entries_[id].refCount == 0) {- if (!entries_[id].path.empty()) {- pathToId_.erase(entries_[id].path);- }- entries_[id].resource.reset();- entries_[id].path.clear();- freeList_.push_back(id);+ u32 index = Handle<T>::extractIndex(id);+ u32 gen = Handle<T>::extractGeneration(id);+ if (index >= entries_.size()) return;+ auto& entry = entries_[index];+ if (entry.refCount == 0 || entry.generation != gen) return;+ if (--entry.refCount == 0) {+ if (!entry.path.empty()) {+ pathToId_.erase(entry.path);}+ entry.resource.reset();+ entry.path.clear();+ entry.generation = (entry.generation + 1) & Handle<T>::GEN_MASK;+ freeList_.push_back(index);}}@@ -228,10 +253,12 @@ public:* @return Reference count, or 0 if invalid*/u32 getRefCount(Handle<T> handle) const {- if (!handle.isValid() || handle.id() >= entries_.size()) {- return 0;- }- return entries_[handle.id()].refCount;+ if (!handle.isValid()) return 0;+ u32 idx = handle.index();+ if (idx >= entries_.size()) return 0;+ const auto& entry = entries_[idx];+ if (entry.generation != handle.generation()) return 0;+ return entry.refCount;}/**@@ -241,10 +268,12 @@ public:*/const std::string& getPath(Handle<T> handle) const {static const std::string empty;- if (!handle.isValid() || handle.id() >= entries_.size()) {- return empty;- }- return entries_[handle.id()].path;+ if (!handle.isValid()) return empty;+ u32 idx = handle.index();+ if (idx >= entries_.size()) return empty;+ const auto& entry = entries_[idx];+ if (entry.generation != handle.generation()) return empty;+ return entry.path;}private: