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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file View.hpp
* @brief ECS View for querying entities with specific components
* @details Provides efficient iteration over entities that have a specific
* set of components. Views are the primary way to query the ECS.
*
* @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/Types.hpp"
#include "../core/Log.hpp"
#include "Entity.hpp"
#include "SparseSet.hpp"
// Standard library
#include <tuple>
namespace esengine::ecs {
// Forward declaration
class Registry;
// =============================================================================
// ViewIterator
// =============================================================================
/**
* @brief Iterator for multi-component views
*
* @tparam Components The component types required
*
* @details Iterates over entities from the smallest pool while filtering
* for entities that have all required components. Automatically
* skips entities that don't match the full component set.
*/
template<typename... Components>
class ViewIterator {
public:
/** @brief Tuple type holding pointers to all component pools */
using PoolsTuple = std::tuple<SparseSet<Components>*...>;
/**
* @brief Constructs an iterator
* @param entities Pointer to the entity array being iterated
* @param index Current position in the entity array
* @param pools Tuple of component pool pointers
*/
ViewIterator(const std::vector<Entity>* entities, usize index, PoolsTuple pools)
: entities_(entities), index_(index), pools_(pools) {
// Skip to first valid entity
if (entities_ && index_ < entities_->size()) {
skipInvalid();
}
}
/**
* @brief Dereferences to get the current entity
* @return The current entity ID
*/
Entity operator*() const {
// Kept as ES_ASSERT (not ES_VERIFY) deliberately: this is the ECS query
// hot path, and entities_ is structurally non-null for any iterator the
// View API hands out (begin()/end() always pass a live pointer). Only a
// manually default-constructed iterator violates it — a pure-logic
// misuse, not a runtime-data boundary — so no per-deref branch here.
ES_ASSERT(entities_ != nullptr, "Dereferencing null ViewIterator");
return (*entities_)[index_];
}
/**
* @brief Advances to the next matching entity
* @return Reference to this iterator
*/
ViewIterator& operator++() {
++index_;
skipInvalid();
return *this;
}
/**
* @brief Inequality comparison
* @param other Iterator to compare with
* @return True if iterators are at different positions
*/
bool operator!=(const ViewIterator& other) const {
return index_ != other.index_;
}
/**
* @brief Equality comparison
* @param other Iterator to compare with
* @return True if iterators are at the same position
*/
bool operator==(const ViewIterator& other) const {
return index_ == other.index_;
}
private:
/**
* @brief Skips entities that don't have all required components
*
* @details Advances index_ until we find an entity that has
* all components in the view, or we reach the end.
*/
void skipInvalid() {
if (!entities_) return;
while (index_ < entities_->size()) {
Entity entity = (*entities_)[index_];
if (allHave(entity)) {
break;
}
++index_;
}
}
/**
* @brief Checks if an entity has all required components
* @param entity The entity to check
* @return True if entity has all components
*/
bool allHave(Entity entity) const {
return allHaveImpl(entity, std::index_sequence_for<Components...>{});
}
/**
* @brief Implementation helper using index sequence
* @tparam Is Index sequence for component types
* @param entity The entity to check
* @return True if entity has all components
*/
template<usize... Is>
bool allHaveImpl(Entity entity, std::index_sequence<Is...>) const {
return (std::get<Is>(pools_)->contains(entity) && ...);
}
const std::vector<Entity>* entities_;
usize index_;
PoolsTuple pools_;
};
// =============================================================================
// Multi-Component View
// =============================================================================
/**
* @brief View for iterating entities with multiple required components
*
* @tparam Components The component types that entities must have
*
* @details Provides iteration over all entities that have ALL of the
* specified component types. Optimizes by iterating over the
* smallest pool and filtering by other components.
*
* @code
* // Iterate entities with Position AND Velocity
* auto view = registry.view<Position, Velocity>();
*
* // Range-based for loop
* for (Entity e : view) {
* auto& pos = view.get<Position>(e);
* auto& vel = view.get<Velocity>(e);
* pos.x += vel.x * dt;
* }
*
* // Each with callback
* view.each([&](Entity e, Position& p, Velocity& v) {
* p.x += v.x * dt;
* });
* @endcode
*/
template<typename... Components>
class View {
public:
/** @brief Iterator type */
using Iterator = ViewIterator<Components...>;
/** @brief Tuple type for pool pointers */
using PoolsTuple = std::tuple<SparseSet<Components>*...>;
/**
* @brief Constructs a view from component pools
* @param pools Tuple of pointers to component pools
*/
View(PoolsTuple pools) : pools_(pools) {
// Find the smallest pool to iterate over
findSmallestPool();
}
/**
* @brief Returns iterator to the first matching entity
* @return Begin iterator
*/
Iterator begin() const {
if (!smallest_) return end();
return Iterator(&smallest_->entities(), 0, pools_);
}
/**
* @brief Returns iterator past the last entity
* @return End iterator
*/
Iterator end() const {
if (!smallest_) return Iterator(nullptr, 0, pools_);
return Iterator(&smallest_->entities(), smallest_->size(), pools_);
}
// =========================================================================
// Component Access
// =========================================================================
/**
* @brief Gets a specific component from an entity
* @tparam T The component type to get
* @param entity The entity (must be valid in view)
* @return Reference to the component
*/
template<typename T>
T& get(Entity entity) {
return std::get<SparseSet<T>*>(pools_)->get(entity);
}
/** @copydoc get() */
template<typename T>
const T& get(Entity entity) const {
return std::get<SparseSet<T>*>(pools_)->get(entity);
}
/**
* @brief Gets all components for an entity as a tuple
* @param entity The entity
* @return Tuple of component references
*/
std::tuple<Components&...> getAll(Entity entity) {
return std::tuple<Components&...>(
std::get<SparseSet<Components>*>(pools_)->get(entity)...);
}
// =========================================================================
// View Properties
// =========================================================================
/**
* @brief Checks if the view is empty
* @return True if no entities match
*/
bool empty() const {
return !smallest_ || smallest_->empty();
}
/**
* @brief Gets the estimated number of matching entities
* @return Upper bound on entity count (actual may be lower)
*
* @details Returns the size of the smallest pool. Actual matches
* may be fewer due to filtering by other components.
*/
usize sizeHint() const {
return smallest_ ? smallest_->size() : 0;
}
// =========================================================================
// Functional Iteration
// =========================================================================
template<typename Func>
void each(Func&& func) {
if (!smallest_) return;
// Snapshot tolerates emplace/remove on the smallest pool during the callback.
std::vector<Entity> entities = smallest_->entities();
for (Entity entity : entities) {
if (!smallest_->contains(entity)) continue;
if (!allHaveExceptSmallest(entity)) continue;
if constexpr (std::is_invocable_v<Func, Entity, Components&...>) {
func(entity, getByEntity<Components>(entity)...);
} else if constexpr (std::is_invocable_v<Func, Components&...>) {
func(getByEntity<Components>(entity)...);
} else {
func(entity);
}
}
}
/**
* @brief Like each(), but iterates the live dense array with no defensive copy.
* @warning The callback MUST NOT emplace/remove ANY of the iterated components —
* that reallocates or swap-pops the array being walked. Use for the
* read-only per-frame pass; use each() when the callback may mutate.
*/
template<typename Func>
void eachLive(Func&& func) {
if (!smallest_) return;
const std::vector<Entity>& dense = smallest_->entities();
for (usize i = 0; i < dense.size(); ++i) {
Entity entity = dense[i];
if (!allHaveExceptSmallest(entity)) continue;
if constexpr (std::is_invocable_v<Func, Entity, Components&...>) {
func(entity, getByEntity<Components>(entity)...);
} else if constexpr (std::is_invocable_v<Func, Components&...>) {
func(getByEntity<Components>(entity)...);
} else {
func(entity);
}
}
}
private:
template<typename T>
T& getByEntity(Entity entity) {
return std::get<SparseSet<T>*>(pools_)->getUnchecked(entity);
}
bool allHaveExceptSmallest(Entity entity) const {
return allHaveExceptSmallestImpl(entity, std::index_sequence_for<Components...>{});
}
template<usize... Is>
bool allHaveExceptSmallestImpl(Entity entity, std::index_sequence<Is...>) const {
return ((static_cast<SparseSetBase*>(std::get<Is>(pools_)) == smallest_ ||
std::get<Is>(pools_)->contains(entity)) && ...);
}
/**
* @brief Finds the smallest component pool
*
* @details The view iterates over the smallest pool for efficiency,
* as it minimizes the number of entities to filter.
*/
void findSmallestPool() {
smallest_ = nullptr;
usize minSize = std::numeric_limits<usize>::max();
findSmallestImpl(minSize, std::index_sequence_for<Components...>{});
}
template<usize... Is>
void findSmallestImpl(usize& minSize, std::index_sequence<Is...>) {
((checkPool<Is>(minSize)), ...);
}
template<usize I>
void checkPool(usize& minSize) {
auto* pool = std::get<I>(pools_);
if (pool && pool->size() < minSize) {
minSize = pool->size();
smallest_ = static_cast<SparseSetBase*>(pool);
}
}
/** @brief Tuple of component pool pointers */
PoolsTuple pools_;
/** @brief Pointer to the smallest pool (for iteration) */
SparseSetBase* smallest_ = nullptr;
};
// =============================================================================
// Single-Component View Specialization
// =============================================================================
/**
* @brief Optimized view for single-component queries
*
* @tparam T The single component type
*
* @details When querying for only one component type, no filtering is
* needed. This specialization directly iterates the component
* pool for maximum efficiency.
*
* @code
* // Iterate all entities with Position
* for (Entity e : registry.view<Position>()) {
* auto& pos = registry.get<Position>(e);
* }
*
* // Direct component iteration (most efficient)
* registry.view<Position>().each([](Entity e, Position& p) {
* p.x += 1.0f;
* });
* @endcode
*/
template<typename T>
class View<T> {
public:
/** @brief Iterator type (directly iterates pool) */
using Iterator = typename std::vector<Entity>::const_iterator;
/**
* @brief Constructs a single-component view
* @param pool Pointer to the component pool
*/
explicit View(SparseSet<T>* pool) : pool_(pool) {}
/**
* @brief Returns iterator to the first entity
* @return Begin iterator
*/
Iterator begin() const { return pool_ ? pool_->begin() : Iterator{}; }
/**
* @brief Returns iterator past the last entity
* @return End iterator
*/
Iterator end() const { return pool_ ? pool_->end() : Iterator{}; }
/**
* @brief Gets the component for an entity
* @param entity The entity
* @return Reference to the component
*/
T& get(Entity entity) { return pool_->get(entity); }
/** @copydoc get() */
const T& get(Entity entity) const { return pool_->get(entity); }
/**
* @brief Gets all components for an entity as a tuple
* @param entity The entity
* @return Tuple of component references
*/
std::tuple<T&> getAll(Entity entity) { return std::tuple<T&>(pool_->get(entity)); }
/**
* @brief Checks if the view is empty
* @return True if no entities have this component
*/
bool empty() const { return !pool_ || pool_->empty(); }
/**
* @brief Gets the exact number of entities in the view
* @return Entity count
*/
usize size() const { return pool_ ? pool_->size() : 0; }
/**
* @brief Upper bound on matching entities — exact here, since nothing filters.
* @return Entity count
*/
usize sizeHint() const { return size(); }
/**
* @brief Executes a function for each entity
* @tparam Func Callback type
* @param func The callback to invoke
*
* @details Optimized direct iteration without any filtering.
* Callback signatures:
* - `void(Entity, T&)` - entity and component
* - `void(T&)` - component only
* - `void(Entity)` - entity only
*/
template<typename Func>
void each(Func&& func) {
if (!pool_) return;
// Snapshot tolerates emplace/remove on the pool during the callback — the
// same contract as the multi-component view's each. Live forward iteration
// would re-visit mid-iteration emplaces and skip swap-popped removals.
std::vector<Entity> entities = pool_->entities();
for (Entity entity : entities) {
if (!pool_->contains(entity)) continue;
if constexpr (std::is_invocable_v<Func, Entity, T&>) {
func(entity, pool_->getUnchecked(entity));
} else if constexpr (std::is_invocable_v<Func, T&>) {
func(pool_->getUnchecked(entity));
} else {
func(entity);
}
}
}
/**
* @brief Like each(), but iterates the live dense array with no defensive copy.
* @warning The callback MUST NOT emplace/remove T during iteration — that would
* invalidate the dense array. Use for read-only per-frame system passes
* (the common hot path); use each() when the callback may mutate the pool.
*/
template<typename Func>
void eachLive(Func&& func) {
if (!pool_) return;
const std::vector<Entity>& dense = pool_->entities();
for (usize i = 0; i < dense.size(); ++i) {
Entity entity = dense[i];
if constexpr (std::is_invocable_v<Func, Entity, T&>) {
func(entity, pool_->getUnchecked(entity));
} else if constexpr (std::is_invocable_v<Func, T&>) {
func(pool_->getUnchecked(entity));
} else {
func(entity);
}
}
}
private:
/** @brief Pointer to the component pool */
SparseSet<T>* pool_;
};
} // namespace esengine::ecs