ecs Folder

Folders Index

folder	components
folder	concepts
folder	strategies
folder	types

Files Index

file	helios/ecs/_module.ixx
	Module aggregator for helios.ecs. More...
file	ecs/ComponentOpsRegistry.ixx
	Global registry mapping ComponentTypeId to ComponentOps. More...
file	ecs/ComponentReflector.ixx
	Compile-time reflection for component lifecycle hook registration. More...
file	Entity.ixx
	High-level facade for entity manipulation in the ECS. More...
file	ecs/EntityManager.ixx
	Central manager for entity lifecycle and component storage. More...
file	ecs/EntityRegistry.ixx
	Generic, policy-based entity registry for managing entity lifecycles. More...
file	ecs/EntityResolver.ixx
	Lightweight callable for resolving EntityHandles to Entity wrappers. More...
file	ecs/registry.ixx
	Component registration for ecs module. More...
file	ecs/SparseSet.ixx
	Generic sparse set data structure for efficient entity-keyed storage. More...
file	TypedHandleWorld.ixx
	Multi-domain entity world with compile-time handle-to-manager dispatch. More...
file	ecs/View.ixx
	Lightweight view for iterating entities with specific components. More...

Description

helios::ecs

Generic, reusable ECS primitives shared across the engine.

Overview

This module provides the complete set of building blocks for entity management, component storage, querying and lifecycle reflection. All types are policy-based templates that can be specialised for different domains (e.g. game entities, UI widgets, audio sources).

The classes were previously located in helios.ecs (which is now retained only for backward compatibility) and have been generalised through template parameters so they are independent of any specific engine subsystem.

Module Structure

The helios.ecs module exports the following types:

Entity Management

Class	Template Parameters	Purpose
EntityHandle<TStrongId>	TStrongId — domain-specific strong ID type	Versioned, strongly-typed entity reference
EntityRegistry<TStrongId, TLookupStrategy, TAllowRemoval, TCapacity>	Strong ID type, lookup strategy, removal policy, capacity	Handle allocation, version tracking, validation
EntityManager<THandle, TEntityRegistry, TCapacity>	Handle type, registry type, capacity	Unified entity creation and component storage
Entity<THandle, TEntityManager>	Handle type, manager type	Lightweight entity facade (~16 bytes, pass-by-value)
EntityResolver<TEntityManager>	Manager type	Callable for resolving handles to Entity wrappers
TypedHandleWorld<TEntityManagers...>	One or more EntityManager specialisations	Multi-domain world with compile-time handle dispatch

Component Infrastructure

Class	Template Parameters	Purpose
ComponentTypeId<THandle>	Handle type (scoping)	Compile-time unique type identifier for components
ComponentOps	(none)	Type-erased function pointers for lifecycle callbacks
ComponentOpsRegistry<THandle>	Handle type (scoping)	Global O(1) registry mapping type IDs to ComponentOps
ComponentReflector<THandle, TEntityManager>	Handle type, manager type	Compile-time trait-based lifecycle registration

Storage & Iteration

Class	Template Parameters	Purpose
SparseSet<T>	Element type	Generic O(1) entity-keyed storage
SparseSetBase	(none)	Type-erased base for polymorphic sparse set access
View<TEntityManager, Components...>	Manager type, component types	Lightweight component-based entity queries

Lookup Strategies

Strategy	Lookup	Insertion	Removal	Use Case
HashedLookupStrategy	O(1) avg	O(1) avg	O(1) avg	Default — large registries
LinearLookupStrategy	O(n)	O(n)	O(1)	Small registries

Traits (Compile-Time Concepts)

Trait	Required Method(s)	Purpose
HasOnAcquire	onAcquire()	Pool acquisition callback
HasOnRelease	onRelease()	Pool release callback
HasOnRemove	onRemove() → bool	Removal interception
HasToggleable	enable(), disable()	Component enable/disable
HasClone	onClone(const T&)	Post-copy initialisation
HasActivatable	onActivate(), onDeactivate()	Entity activation response

Template Parameter Overview

The move from helios.engine.ecs to helios.ecs introduced the following new template parameters:

Parameter	Used In	Purpose
TStrongId	EntityHandle, EntityRegistry	Domain-specific strong ID type satisfying IsStrongIdLike
THandle	EntityManager, Entity, ComponentTypeId, ComponentOpsRegistry, ComponentReflector	The concrete EntityHandle<TStrongId> specialisation, scoping type IDs and ops per domain
TEntityRegistry	EntityManager	The concrete EntityRegistry specialisation used for handle allocation
TEntityManager	Entity, View, EntityResolver, ComponentReflector	The concrete EntityManager specialisation providing component storage
TLookupStrategy	EntityRegistry	Pluggable collision detection strategy for strong IDs
TAllowRemoval	EntityRegistry	bool policy — false disables destroy() at compile time
TCapacity	EntityRegistry, EntityManager	Default initial capacity hint

TypedHandleWorld

TypedHandleWorld<TEntityManagers...> is a multi-domain entity world that holds one EntityManager per domain inside a std::tuple. The handle type of each manager serves as a compile-time key: calling world.addEntity<MyHandle>() selects the correct manager automatically.

 using GameHandle = EntityHandle<GameStrongId>;

 using UiHandle = EntityHandle<UiStrongId>;

 

 using GameEM = EntityManager<GameHandle, GameRegistry, 4096>;

 using UiEM = EntityManager<UiHandle, UiRegistry, 512>;

 

 TypedHandleWorld<GameEM, UiEM> world;

 

 auto player = world.addEntity<GameHandle>(); // → GameEM

 auto button = world.addEntity<UiHandle>(); // → UiEM

Quick Start

 import helios.ecs;

 

 // 1 Define domain types

 struct MyStrongId { /* ... */ };

 using Handle = helios::ecs::types::EntityHandle<MyStrongId>;

 using Registry = helios::ecs::EntityRegistry<MyStrongId>;

 using Manager = helios::ecs::EntityManager<Handle, Registry, 1024>;

 

 // 2 Create manager and entity

 Manager em;

 auto handle = em.create();

 

 // 3 Attach components

 auto* transform = em.emplace<TransformComponent>(handle, position);

 

 // 4 Use the Entity facade

 helios::ecs::Entity<Handle, Manager> entity{handle, &em};

 entity.add<HealthComponent>(100.0f);

 

 // 5 Iterate via View

 for (auto [e, t, v] :

  helios::ecs::View<Manager, TransformComponent, VelocityComponent>(&em)) {

  // process

 }

See Also

• Engine ECS — backward-compatible wrappers (GameObject, etc.)
• Core Types — EntityId, VersionId, EntityTombstone, StrongId_t

---

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.