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.

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.hpp
index 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.hpp
index 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, ProjectionType
diff --git a/src/esengine/ecs/DynamicComponent.hpp b/src/esengine/ecs/DynamicComponent.hpp
index 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.hpp
index 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 entity
schemaRegistry_.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.hpp
index 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 reallocation
std::vector<u8> data_; ///< Contiguous component data
std::vector<u32> sparse_; ///< Entity -> dense index
std::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.hpp
index 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.cpp
index 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 std
return 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 paths
std::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.hpp
index 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.hpp
index 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 resource
u32 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: