GameWorld Class
Central game state container for entities, resources, and the active level. More...
Declaration
Public Constructors Index
| GameWorld (const size_t capacity=ENTITY_MANAGER_DEFAULT_CAPACITY) | |
| GameWorld (const GameWorld &)=delete | |
|
Non-copyable. More... | |
| GameWorld (const GameWorld &&)=delete | |
|
Non-movable. More... | |
Public Operators Index
| GameWorld | operator= (const GameWorld &)=delete |
|
Non-copyable. More... | |
| GameWorld | operator= (const GameWorld &&)=delete |
|
Non-movable. More... | |
Public Member Functions Index
| Session & | session () |
|
Returns a reference to the current game session. More... | |
| helios::engine::ecs::EntityManager & | entityManager () |
|
Returns a reference to the underlying EntityManager. More... | |
| void | init () |
|
Initializes all registered managers. More... | |
| void | setLevel (std::unique_ptr< Level > level) noexcept |
|
Sets the current level for the game world. More... | |
| bool | hasLevel () const noexcept |
|
Checks if a level is currently loaded. More... | |
| const Level * | level () const noexcept |
|
Retrieves the currently loaded level. More... | |
template <typename T> | |
| bool | hasManager () const |
template <typename T> | |
| bool | hasCommandBuffer () const |
|
Checks whether a CommandBuffer of type T is registered. More... | |
template <typename T, typename... Args> | |
| T & | registerManager (Args &&... args) |
template <typename T, typename... Args> | |
| T & | registerCommandBuffer (Args &&... args) |
|
Registers and constructs a CommandBuffer of type T. More... | |
template <typename T> | |
| T & | manager () const noexcept |
template <typename T> | |
| T * | tryManager () const noexcept |
|
Retrieves a registered Manager by type, or nullptr if not found. More... | |
template <typename T> | |
| T * | tryCommandBuffer () const noexcept |
|
Retrieves a registered CommandBuffer by type, or nullptr if not found. More... | |
template <typename... CommandType, typename OwningT> | |
| void | registerCommandHandler (OwningT &owner) |
|
Registers a command handler for one or more command types. More... | |
| CommandHandlerRegistry & | commandHandlerRegistry () noexcept |
|
Returns a reference to the CommandHandlerRegistry. More... | |
| void | flushManagers (UpdateContext &updateContext) |
|
Flushes all registered Managers. More... | |
| void | flushCommandBuffers (UpdateContext &updateContext) |
|
Flushes all registered CommandBuffers. More... | |
| helios::engine::ecs::GameObject | addGameObject () |
|
Creates a new GameObject in the world. More... | |
template <typename... Components> | |
| auto | view () |
|
Creates a View for iterating entities with specific components. More... | |
template <typename... Components> | |
| auto | view () const |
|
Creates a const View for iterating entities with specific components. More... | |
| std::optional< helios::engine::ecs::GameObject > | find (const helios::engine::ecs::EntityHandle handle) |
|
Finds a GameObject by its EntityHandle. More... | |
| std::optional< helios::engine::ecs::GameObject > | find (const helios::engine::ecs::EntityHandle handle) const |
|
Finds a GameObject by its EntityHandle (const version). More... | |
| helios::engine::ecs::GameObject | clone (const helios::engine::ecs::GameObject gameObject) |
|
Clones a GameObject and all its components. More... | |
| void | reset () |
|
Resets all managers and the session to their initial state. More... | |
| ResourceRegistry & | resourceRegistry () noexcept |
|
Returns a reference to the ResourceRegistry. More... | |
| const ResourceRegistry & | resourceRegistry () const noexcept |
|
Returns a reference to the ResourceRegistry. More... | |
Protected Member Attributes Index
| std::unique_ptr< Level > | level_ = nullptr |
|
The current level loaded in the game world. More... | |
| ResourceRegistry | resourceRegistry_ |
|
Type-indexed registry for Managers and CommandBuffers. More... | |
| CommandHandlerRegistry | commandHandlerRegistry_ |
|
Registry mapping command types to their handler function pointers. More... | |
| helios::engine::ecs::EntityRegistry | entityRegistry_ {} |
|
Entity registry for handle allocation and validation. More... | |
| helios::engine::ecs::EntityManager | em_ |
|
Entity manager for component storage. More... | |
| Session | session_ |
|
The current game session holding state data. More... | |
Protected Static Attributes Index
| static const helios::util::log::Logger & | logger_ = ... |
Description
Central game state container for entities, resources, and the active level.
GameWorld is the root container for all runtime game state. It owns the EntityRegistry/EntityManager for entity lifecycle, a ResourceRegistry for type-indexed O(1) access to Managers, CommandBuffers, and CommandHandlers, a Session for cross-frame state tracking, and the current Level.
## Key Responsibilities
- **Entity Management:** Creates entities via `addGameObject()` returning lightweight (~16 bytes) `GameObject` wrappers. Entities are identified by versioned `EntityHandle` for stale reference detection.
- **Resource Registry:** Provides `resourceRegistry()` for registering and looking up Managers, CommandBuffers, and CommandHandlers with O(1) access.
- **Component Queries:** Efficient iteration via `view<Components...>()` with optional `.whereEnabled()` and `.exclude<T>()` filtering.
- **Entity Cloning:** Deep-copies entities with all components via `clone()`.
- **Manager Coordination:** Initializes, flushes, and resets Managers that handle cross-cutting concerns (spawning, scoring, pooling).
- **Session:** Holds per-run state (tracked game/match states, scores).
- **Level Management:** Holds the active Level with arena bounds.
## Usage with GameLoop
Systems access the GameWorld indirectly via UpdateContext. Entity queries use views, while mutations are performed through commands submitted via `UpdateContext::queueCommand<T>()`.
```cpp void update(UpdateContext& ctx) noexcept { for (auto [entity, transform, velocity, active] : ctx.view< TransformComponent, VelocityComponent, Active >().whereEnabled()) { // Process matching entities }
ctx.queueCommand<DespawnCommand>(handle, profileId); } ```
## Resource Registration
```cpp auto& poolMgr = gameWorld.registerManager<GameObjectPoolManager>(); auto& spawnMgr = gameWorld.registerManager<SpawnManager>(); auto& cmdBuf = gameWorld.registerCommandBuffer<EngineCommandBuffer>();
gameWorld.init(); // Calls init() on all Managers in registration order ```
## Entity Lifecycle
```cpp auto player = gameWorld.addGameObject(); player.add<TransformComponent>(position); player.add<HealthComponent>(100.0f); player.setActive(true);
if (auto entity = gameWorld.find(handle)) { entity->get<HealthComponent>()->takeDamage(10.0f); }
auto clone = gameWorld.clone(player); ```
- See Also
- See Also
GameObject
- See Also
EntityHandle
- See Also
EntityManager
- See Also
View
- See Also
- See Also
- See Also
- See Also
Definition at line 129 of file GameWorld.ixx.
Public Constructors
GameWorld()
| inline explicit |
Constructs the GameWorld.
Initializes the EntityManager with the internal EntityRegistry and creates a Session backed by a dedicated GameObject.
- Parameters
-
capacity Initial capacity for the underlying SparseSets. Must be large enough to accommodate the total number of entities (including pooled clones) to avoid reallocation during cloning. Defaults to ENTITY_MANAGER_DEFAULT_CAPACITY.
Definition at line 207 of file GameWorld.ixx.
References addGameObject, em_, entityRegistry_ and session_.
Referenced by GameWorld, GameWorld, operator= and operator=.
GameWorld()
| delete |
GameWorld()
| delete |
Public Operators
operator=()
| delete |
operator=()
| delete |
Public Member Functions
addGameObject()
| inline nodiscard |
Creates a new GameObject in the world.
Allocates an entity handle via the EntityRegistry and returns a lightweight GameObject wrapper. The returned GameObject is ~16 bytes and should be passed by value.
- Returns
A new GameObject ready for component attachment.
- See Also
GameObject
- See Also
EntityManager::create
Definition at line 463 of file GameWorld.ixx.
Reference em_.
clone()
| inline nodiscard |
Clones a GameObject and all its components.
Creates a new entity and copies all components from the source to the target. The new GameObject is initially inactive. Components with `onClone()` hooks will have them invoked after copy construction.
- Parameters
-
gameObject The source GameObject to clone.
- Returns
A new inactive GameObject with cloned components.
- See Also
EntityManager::clone
Definition at line 555 of file GameWorld.ixx.
References addGameObject, em_ and helios::engine::ecs::GameObject::entityHandle.
commandHandlerRegistry()
| inline nodiscard noexcept |
Returns a reference to the CommandHandlerRegistry.
- Returns
Reference to the CommandHandlerRegistry.
Definition at line 417 of file GameWorld.ixx.
Reference commandHandlerRegistry_.
entityManager()
| inline nodiscard |
Returns a reference to the underlying EntityManager.
- Returns
Reference to the EntityManager.
Definition at line 236 of file GameWorld.ixx.
Reference em_.
find()
| inline nodiscard |
Finds a GameObject by its EntityHandle.
Validates the handle and returns a GameObject wrapper if valid. Returns std::nullopt if the handle is stale or invalid.
- Parameters
-
handle The EntityHandle to look up.
- Returns
Optional containing the GameObject if found, std::nullopt otherwise.
Definition at line 518 of file GameWorld.ixx.
Reference em_.
find()
| inline nodiscard |
Finds a GameObject by its EntityHandle (const version).
- Parameters
-
handle The EntityHandle to look up.
- Returns
Optional containing the GameObject if found, std::nullopt otherwise.
Definition at line 533 of file GameWorld.ixx.
Reference em_.
flushCommandBuffers()
| inline |
Flushes all registered CommandBuffers.
Iterates over all CommandBuffers in registration order and invokes `flush(*this, updateContext)` on each. Called by the GameLoop at commit points before Managers are flushed.
- Parameters
-
updateContext The current frame's update context.
Definition at line 445 of file GameWorld.ixx.
Reference resourceRegistry_.
Referenced by helios::engine::runtime::gameloop::GameLoop::phaseCommit.
flushManagers()
| inline |
Flushes all registered Managers.
Iterates over all Managers in registration order and invokes `flush(updateContext)` on each. Called by the GameLoop at commit points after the CommandBuffer has been flushed.
- Parameters
-
updateContext The current frame's update context.
Definition at line 430 of file GameWorld.ixx.
Reference resourceRegistry_.
Referenced by helios::engine::runtime::gameloop::GameLoop::phaseCommit.
hasCommandBuffer()
| inline nodiscard |
Checks whether a CommandBuffer of type T is registered.
- Template Parameters
-
T The CommandBuffer type. Must satisfy IsCommandBufferLike.
- Returns
True if the CommandBuffer is registered.
Definition at line 304 of file GameWorld.ixx.
Reference resourceRegistry_.
hasLevel()
| inline nodiscard noexcept |
hasManager()
| inline nodiscard |
Checks whether a Manager of type T is registered.
- Template Parameters
-
T The Manager type. Must satisfy IsManagerLike.
- Returns
True if the Manager is registered.
Definition at line 291 of file GameWorld.ixx.
Reference resourceRegistry_.
init()
| inline |
Initializes all registered managers.
Should be called after all managers have been added and before the game loop starts. Each manager's init() method is invoked with a reference to this GameWorld.
Definition at line 247 of file GameWorld.ixx.
Reference resourceRegistry_.
level()
| inline nodiscard noexcept |
Retrieves the currently loaded level.
- Returns
Const pointer to the active Level.
Calling this method when hasLevel() returns false results in undefined behavior.
Definition at line 278 of file GameWorld.ixx.
Reference level_.
Referenced by setLevel.
manager()
| inline noexcept |
Retrieves a registered Manager by type.
- Template Parameters
-
T The Manager type. Must satisfy IsManagerLike.
- Returns
Reference to the Manager.
- Precondition
A Manager of type T must be registered.
Definition at line 359 of file GameWorld.ixx.
Reference resourceRegistry_.
registerCommandBuffer()
| inline |
Registers and constructs a CommandBuffer of type T.
Delegates to ResourceRegistry::emplace. The buffer is constructed in-place with forwarded arguments and owned by the CommandBufferRegistry.
- Template Parameters
-
T The CommandBuffer type. Must satisfy IsCommandBufferLike.
Args Constructor argument types.
- Parameters
-
args Arguments forwarded to the T constructor.
- Returns
Reference to the newly registered CommandBuffer.
Definition at line 344 of file GameWorld.ixx.
Reference resourceRegistry_.
registerCommandHandler()
| inline |
Registers a command handler for one or more command types.
Stores a type-erased function pointer for each CommandType that routes to `owner.submit(cmd)`. During flush, the TypedCommandBuffer uses the CommandHandlerRegistry to dispatch queued commands to the registered handler.
- Template Parameters
-
CommandType The command types to register handlers for.
OwningT The handler type. Must satisfy IsCommandHandlerLike.
- Parameters
-
owner Reference to the handler instance. Must outlive the GameWorld.
- See Also
Definition at line 408 of file GameWorld.ixx.
Reference commandHandlerRegistry_.
Referenced by helios::engine::mechanics::lifecycle::WorldLifecycleManager::init, helios::engine::mechanics::scoring::ScorePoolManager::init, helios::engine::modules::ui::UiActionCommandManager::init and helios::engine::state::StateManager< types::GameState >::init.
registerManager()
| inline |
Registers and constructs a Manager of type T.
Delegates to ResourceRegistry::emplace. The Manager is constructed in-place with forwarded arguments and owned by the ManagerRegistry.
- Template Parameters
-
T The Manager type. Must satisfy IsManagerLike.
Args Constructor argument types.
- Parameters
-
args Arguments forwarded to the T constructor.
- Returns
Reference to the newly registered Manager.
Definition at line 324 of file GameWorld.ixx.
Reference resourceRegistry_.
reset()
| inline |
Resets all managers and the session to their initial state.
Called during level transitions or game restarts to clear accumulated state. Invokes reset() on all managers and the session.
Definition at line 573 of file GameWorld.ixx.
References resourceRegistry_ and session_.
resourceRegistry()
| inline noexcept |
Returns a reference to the ResourceRegistry.
Use for direct resource access. Prefer the convenience methods `registerManager()`, `registerCommandBuffer()`, `manager()`, `tryManager()`, and `tryCommandBuffer()` for type-constrained access.
- Returns
Reference to the ResourceRegistry.
Definition at line 592 of file GameWorld.ixx.
Reference resourceRegistry_.
resourceRegistry()
| inline noexcept |
Returns a reference to the ResourceRegistry.
Use for direct resource access. Prefer the convenience methods `registerManager()`, `registerCommandBuffer()`, `manager()`, `tryManager()`, and `tryCommandBuffer()` for type-constrained access.
- Returns
Reference to the ResourceRegistry.
Definition at line 599 of file GameWorld.ixx.
Reference resourceRegistry_.
session()
| inline nodiscard |
setLevel()
| inline noexcept |
Sets the current level for the game world.
Definition at line 258 of file GameWorld.ixx.
tryCommandBuffer()
| inline noexcept |
Retrieves a registered CommandBuffer by type, or nullptr if not found.
- Template Parameters
-
T The CommandBuffer type. Must satisfy IsCommandBufferLike.
- Returns
Pointer to the CommandBuffer, or nullptr if not registered.
Definition at line 386 of file GameWorld.ixx.
Reference resourceRegistry_.
tryManager()
| inline noexcept |
Retrieves a registered Manager by type, or nullptr if not found.
- Template Parameters
-
T The Manager type. Must satisfy IsManagerLike.
- Returns
Pointer to the Manager, or nullptr if not registered.
Definition at line 373 of file GameWorld.ixx.
Reference resourceRegistry_.
Referenced by helios::engine::runtime::spawn::policy::amount::SpawnAll::getAmount.
view()
| inline nodiscard |
Creates a View for iterating entities with specific components.
Returns a lightweight view that iterates over all entities possessing the specified component types. Use with range-based for loops and structured bindings.
```cpp for (auto [entity, transform, velocity, active] : gameWorld.view< TransformComponent, VelocityComponent, Active >().whereEnabled()) { // Process matching entities } ```
- Template Parameters
-
Components The component types to query for.
- Returns
A View for iterating matching entities.
- See Also
View
Definition at line 492 of file GameWorld.ixx.
Reference em_.
Referenced by helios::engine::runtime::pooling::GameObjectPoolManager::init.
view()
| inline nodiscard |
Creates a const View for iterating entities with specific components.
- Template Parameters
-
Components The component types to query for.
- Returns
A const View for iterating matching entities.
Definition at line 504 of file GameWorld.ixx.
Reference em_.
Protected Member Attributes
commandHandlerRegistry_
| protected |
Registry mapping command types to their handler function pointers.
Used by TypedCommandBuffer during flush to route commands to the correct handler. Handlers are registered via `registerCommandHandler<CommandTypes...>(owner)`.
Definition at line 168 of file GameWorld.ixx.
Referenced by commandHandlerRegistry and registerCommandHandler.
em_
| protected mutable |
Entity manager for component storage.
Stores components in type-indexed SparseSets and provides methods for component manipulation. Marked `mutable` to allow const methods to use it without const_cast.
Definition at line 185 of file GameWorld.ixx.
Referenced by addGameObject, clone, entityManager, find, find, GameWorld, view and view.
entityRegistry_
| protected |
Entity registry for handle allocation and validation.
Manages entity lifecycle including creation, destruction, and stale handle detection via versioning.
Definition at line 176 of file GameWorld.ixx.
Referenced by GameWorld.
level_
| protected |
resourceRegistry_
| protected |
Type-indexed registry for Managers and CommandBuffers.
Provides O(1) type-based access via ManagerRegistry and CommandBufferRegistry. Owns all registered Manager and CommandBuffer instances via ConceptModelRegistry.
Definition at line 159 of file GameWorld.ixx.
Referenced by flushCommandBuffers, flushManagers, hasCommandBuffer, hasManager, init, manager, registerCommandBuffer, registerManager, reset, resourceRegistry, resourceRegistry, tryCommandBuffer and tryManager.
session_
Protected Static Attributes
logger_
| protected static |
The logger used with this GameWorld instance.
- Initialiser
Defaults to HELIOS_LOG_SCOPE.
Definition at line 141 of file GameWorld.ixx.
The documentation for this class was generated from the following file:
Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.