The World class manages entities with their components and systems. More...

#include <world.hpp>

Public Member Functions
	World ()
	World (const World &)=delete
	World (World &&) noexcept=default
	~World ()=default
World &	operator= (const World &)=delete
World &	operator= (World &&) noexcept=default
void	Update ()
	Flushes buffer of pending operations.
void	Flush ()
	Flushes entity reservations and executes pending commands.
void	Clear ()
	Clears the world, removing all data.
void	ClearEntities () noexcept
	Clears all entities and components from the world.
Entity	CreateEntity ()
	Creates new entity.
Entity	ReserveEntity ()
	Reserves an entity ID for deferred creation.
void	DestroyEntity (Entity entity)
	Destroys entity and removes it from the world.
void	TryDestroyEntity (Entity entity)
	Tries to destroy entity if it exists in the world.
template<std::ranges::input_range R> requires std::same_as<std::ranges::range_value_t<R>, Entity>
void	DestroyEntities (const R &entities)
	Destroys entities and removes them from the world.
template<std::ranges::input_range R> requires std::same_as<std::ranges::range_value_t<R>, Entity>
void	TryDestroyEntities (const R &entities)
	Tries to destroy entities if they exist in the world.
template<QueryArg... Args, typename Allocator = std::allocator<ComponentTypeIndex>>
auto	Query (Allocator alloc={}) noexcept -> BasicQuery< World, Allocator, Args... >
	Creates a query over entities matching the specified component criteria.
template<QueryArg... Args>
auto	Query (std::pmr::memory_resource *resource) noexcept -> BasicQuery< World, std::pmr::polymorphic_allocator<>, Args... >
	Creates a query using a PMR memory resource.
template<QueryArg... Args>
auto	Query (std::nullptr_t) -> BasicQuery< World, std::pmr::polymorphic_allocator<>, Args... >=delete
template<QueryArg... Args, typename Allocator = std::allocator<ComponentTypeIndex>> requires details::ValidWorldComponentAccessFromTuple< const World, typename details::QueryArgSplit<Args...>::Components>::kValue
auto	ReadOnlyQuery (Allocator alloc={}) const noexcept -> BasicQuery< const World, Allocator, Args... >
	Creates a read-only query over entities matching the specified component criteria.
template<QueryArg... Args> requires details::ValidWorldComponentAccessFromTuple< const World, typename details::QueryArgSplit<Args...>::Components>::kValue
auto	ReadOnlyQuery (std::pmr::memory_resource *resource) const noexcept -> BasicQuery< const World, std::pmr::polymorphic_allocator<>, Args... >
	Creates a read-only query using a PMR memory resource.
template<QueryArg... Args> requires details::ValidWorldComponentAccessFromTuple< const World, typename details::QueryArgSplit<Args...>::Components>::kValue
auto	ReadOnlyQuery (std::nullptr_t) const -> BasicQuery< const World, std::pmr::polymorphic_allocator<>, Args... >=delete
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)
void	AddComponents (Entity entity, Ts &&... components)
	Adds components to the entity.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)
auto	TryAddComponents (Entity entity, Ts &&... components) -> std::conditional_t< sizeof...(Ts)==1, bool, std::array< bool, sizeof...(Ts)> >
	Tries to add components to the entity if they don't exist.
template<ComponentTrait T, typename... Args> requires std::constructible_from<T, Args...>
void	EmplaceComponent (Entity entity, Args &&... args)
	Emplaces component for the entity.
template<ComponentTrait T, typename... Args> requires std::constructible_from<T, Args...>
bool	TryEmplaceComponent (Entity entity, Args &&... args)
	Tries to emplace component for the entity.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)
void	RemoveComponents (Entity entity)
	Removes components from the entity.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)
auto	TryRemoveComponents (Entity entity) -> std::conditional_t< sizeof...(Ts)==1, bool, std::array< bool, sizeof...(Ts)> >
	Tries to remove components from the entity if they exist.
void	ClearComponents (Entity entity)
	Removes all components from the entity.
template<ComponentTrait T>
T &	WriteComponent (Entity entity)
	Gets a mutable reference to a component.
template<ComponentTrait T>
const T &	ReadComponent (Entity entity) const
	Gets a const reference to a component.
template<ComponentTrait T>
T *	TryWriteComponent (Entity entity)
	Tries to get a mutable pointer to a component.
template<ComponentTrait T>
const T *	TryReadComponent (Entity entity) const
	Tries to get a const pointer to a component.
template<ResourceTrait T>
void	InsertResources (T &&resource)
	Inserts a resource into the world.
template<ResourceTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 1)
void	InsertResources (Ts &&... resources)
	Inserts resources into the world.
template<ResourceTrait T>
bool	TryInsertResources (T &&resource)
	Tries to insert resource if not present.
template<ResourceTrait... Ts>
auto	TryInsertResources (Ts &&... resources) -> std::array< bool, sizeof...(Ts)>
	Tries to insert resources if not present.
template<ResourceTrait T, typename... Args> requires std::constructible_from<T, Args...>
void	EmplaceResource (Args &&... args)
	Emplaces a resource in-place.
template<ResourceTrait T, typename... Args> requires std::constructible_from<T, Args...>
bool	TryEmplaceResource (Args &&... args)
	Tries to emplace a resource if not present.
template<ResourceTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)
void	RemoveResources ()
	Removes resources from the world.
template<ResourceTrait T>
bool	TryRemoveResources ()
	Tries to remove resource.
template<ResourceTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 1)
auto	TryRemoveResources () -> std::array< bool, sizeof...(Ts)>
	Tries to remove resources.
template<ResourceTrait T>
T &	WriteResource () noexcept
	Gets reference to a resource.
template<ResourceTrait T>
const T &	ReadResource () const noexcept
	Gets const reference to a resource.
template<ResourceTrait T>
T *	TryWriteResource () noexcept
	Tries to get mutable pointer to a resource.
template<ResourceTrait T>
const T *	TryReadResource () const noexcept
	Tries to get const pointer to a resource.
template<AnyMessageTrait T>
void	AddMessage ()
	Registers an message type for use.
template<AnyMessageTrait... Ts> requires (sizeof...(Ts) > 0)
void	AddMessages ()
	Registers multiple message types for use.
void	AddBuiltinMessages ()
	Registers all built-in non-template message types.
void	ClearMessages () noexcept
	Clears all messages without removing registration.
template<AnyMessageTrait... Ts> requires (sizeof...(Ts) > 0)
void	ClearMessages ()
	Manually clears messages of specific types from both queues.
template<MessageTrait T>
auto	ReadMessages () const noexcept -> MessageReader< T >
	Gets a reader for messages of type T without consume support.
template<ConsumableMessageTrait T>
auto	ReadConsumableMessages () noexcept -> ConsumableMessageReader< T >
	Gets a consumable reader for messages of type T without consume support.
template<MessageTrait T>
auto	WriteMessages () noexcept -> BasicMessageWriter< T >
	Gets a writer for messages of type T.
template<AsyncMessageTrait T>
auto	ReadAsyncMessages () noexcept -> AsyncMessageReader< T >
	Gets a reader for messages of type T.
template<AsyncMessageTrait T>
auto	WriteAsyncMessages () noexcept -> AsyncMessageWriter< T >
	Gets a writer for messages of type T.
void	ReserveCommands (size_t count)
	Reserves capacity in the command queue to avoid reallocations.
template<CommandTrait Cmd>
void	EnqueueCommand (Cmd &&command)
	Enqueues a command to be executed during the next Update().
template<std::ranges::input_range R> requires CommandTrait<std::ranges::range_value_t<R>>
void	EnqueueCommandBulk (R &&range)
	Enqueues multiple commands to be executed during the next Update().
bool	Exists (Entity entity) const noexcept
	Checks if entity exists in the world.
template<ComponentTrait T>
bool	HasComponent (Entity entity) const
	Checks if entity has component.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)
auto	HasComponents (Entity entity) const -> std::array< bool, sizeof...(Ts)>
	Checks if entity has components.
template<ResourceTrait T>
bool	HasResource () const
	Checks if a resource exists.
template<AnyMessageTrait T>
bool	HasMessage () const noexcept
	Checks if a message added.
template<AnyMessageTrait T>
bool	HasMessages () const noexcept
	Checks if messages of a specific type exist in message queue.
bool	HasCommands () const noexcept
	Checks if there are any pending commands in the command queue.
size_t	EntityCount () const noexcept
	Gets the number of entities in the world.
size_t	ResourceCount () const noexcept
	Gets the number of resources in the world.
size_t	CommandCount () const noexcept
	Gets the number of pending commands in the command queue.
EntityManager &	Entities () noexcept
	Gets the entity manager.
const EntityManager &	Entities () const noexcept
	Gets the entity manager.
ComponentManager &	Components () noexcept
	Gets the component manager.
const ComponentManager &	Components () const noexcept
	Gets the component manager (const).
ResourceManager &	Resources () noexcept
	Gets the resource manager.
const ResourceManager &	Resources () const noexcept
	Gets the resource manager (const).
MessageManager &	Messages () noexcept
	Gets the message manager.
const MessageManager &	Messages () const noexcept
	Gets the message manager (const).

Detailed Description

The World class manages entities with their components and systems.

All modifications to the world (adding/removing entities or components) should be done via command buffers to defer changes until the next update.

Note: Partially thread safe.

Definition at line 39 of file world.hpp.

Constructor & Destructor Documentation

◆ World() [1/3]

helios::ecs::World::World ( )

inline

Definition at line 41 of file world.hpp.

◆ World() [2/3]

helios::ecs::World::World ( const World & )

delete

◆ World() [3/3]

helios::ecs::World::World ( World && )

defaultnoexcept

◆ ~World()

helios::ecs::World::~World ( )

default

Member Function Documentation

◆ AddBuiltinMessages()

void helios::ecs::World::AddBuiltinMessages ( )

inline

Registers all built-in non-template message types.

This is called automatically during World construction.

Note: Not thread-safe.

Definition at line 1238 of file world.hpp.

◆ AddComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)

void helios::ecs::World::AddComponents	(	Entity	entity,
		Ts &&...	components )

inline

Adds components to the entity.

If entity already has component of provided type then it will be replaced.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.

Template Parameters

Ts	Components types to add

Parameters

entity	Entity to add components to
components	Components to add

Definition at line 972 of file world.hpp.

◆ AddMessage()

template<AnyMessageTrait T>

void helios::ecs::World::AddMessage ( )

inline

Registers an message type for use.

Note: Not thread-safe. Should be called during initialization.

Template Parameters

T	Message type

Definition at line 1232 of file world.hpp.

◆ AddMessages()

template<AnyMessageTrait... Ts>
requires (sizeof...(Ts) > 0)

void helios::ecs::World::AddMessages ( )

inline

Registers multiple message types for use.

Note: Not thread-safe. Should be called during initialization.

Template Parameters

Ts	Message types to add

Definition at line 590 of file world.hpp.

◆ Clear()

void helios::ecs::World::Clear ( )

inline

Clears the world, removing all data.

Note: Not thread-safe.

Definition at line 909 of file world.hpp.

◆ ClearComponents()

void helios::ecs::World::ClearComponents ( Entity entity )

inline

Removes all components from the entity.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.

Parameters

entity Entity to remove all components from

Definition at line 1084 of file world.hpp.

◆ ClearEntities()

void helios::ecs::World::ClearEntities ( )

inlinenoexcept

Clears all entities and components from the world.

Note: Not thread-safe.

Definition at line 918 of file world.hpp.

◆ ClearMessages() [1/2]

template<AnyMessageTrait... Ts>
requires (sizeof...(Ts) > 0)

void helios::ecs::World::ClearMessages ( )

inline

Manually clears messages of specific types from both queues.

Should only be used for manually-managed messages (auto_clear = false).

Note: Thread-safe if message is async, not thread-safe otherwise.

Warning: Triggers assertion if message type is not added.

Template Parameters

Ts	Message types

Definition at line 1260 of file world.hpp.

◆ ClearMessages() [2/2]

void helios::ecs::World::ClearMessages ( )

inlinenoexcept

Clears all messages without removing registration.

Messages can still be written/read after calling this method. To completely reset the message system including registration, use Clear().

Note: Not thread-safe.

Definition at line 608 of file world.hpp.

◆ CommandCount()

size_t helios::ecs::World::CommandCount ( ) const

inlinenodiscardnoexcept

Gets the number of pending commands in the command queue.

Note: Thread-safe for read operations.

Returns: Number of pending commands in the command queue

Definition at line 807 of file world.hpp.

◆ Components() [1/2]

const ComponentManager & helios::ecs::World::Components ( ) const

inlinenodiscardnoexcept

Gets the component manager (const).

Note: Thread-safe.

Returns: Const reference to component manager

Definition at line 841 of file world.hpp.

◆ Components() [2/2]

ComponentManager & helios::ecs::World::Components ( )

inlinenodiscardnoexcept

Gets the component manager.

Note: Thread-safe.

Returns: Mutable reference to component manager

Definition at line 832 of file world.hpp.

◆ CreateEntity()

Entity helios::ecs::World::CreateEntity ( )

inlinenodiscard

Creates new entity.

Note: Not thread-safe.

Returns: Newly created entity.

Definition at line 923 of file world.hpp.

◆ DestroyEntities()

template<std::ranges::input_range R>
requires std::same_as<std::ranges::range_value_t<R>, Entity>

void helios::ecs::World::DestroyEntities ( const R & entities )

inline

Destroys entities and removes them from the world.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Any entity is invalid.
Any entity does not exist in the world.

Template Parameters

R	Range type containing Entity elements

Parameters

entities Entities to destroy

Definition at line 953 of file world.hpp.

◆ DestroyEntity()

void helios::ecs::World::DestroyEntity ( Entity entity )

inline

Destroys entity and removes it from the world.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.

Parameters

entity Entity to destroy

Definition at line 930 of file world.hpp.

◆ EmplaceComponent()

template<ComponentTrait T, typename... Args>
requires std::constructible_from<T, Args...>

void helios::ecs::World::EmplaceComponent	(	Entity	entity,
		Args &&...	args )

inline

Emplaces component for the entity.

Constructs component in-place. If entity already has component of provided type then it will be replaced.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.

Template Parameters

T	Component type to emplace
Args	Argument types to forward to T's constructor

Parameters

entity	Entity to emplace component to
args	Arguments to forward to component constructor

Definition at line 1016 of file world.hpp.

◆ EmplaceResource()

template<ResourceTrait T, typename... Args>
requires std::constructible_from<T, Args...>

void helios::ecs::World::EmplaceResource ( Args &&... args )

inline

Emplaces a resource in-place.

Note: Not thread-safe.

Template Parameters

T	Resource type
Args	Constructor argument types

Parameters

args	Arguments to forward to resource constructor

Definition at line 1149 of file world.hpp.

◆ EnqueueCommand()

template<CommandTrait Cmd>

void helios::ecs::World::EnqueueCommand ( Cmd && command )

inline

Enqueues a command to be executed during the next Update().

Note: Not thread-safe.

Template Parameters

Cmd	Command type, must satisfy CommandTrait

Parameters

command Command to enqueue

Definition at line 688 of file world.hpp.

◆ EnqueueCommandBulk()

template<std::ranges::input_range R>
requires CommandTrait<std::ranges::range_value_t<R>>

void helios::ecs::World::EnqueueCommandBulk ( R && range )

inline

Enqueues multiple commands to be executed during the next Update().

Note: Not thread-safe.

Template Parameters

R	Range type containing command elements that must satisfy and CommandTrait

Parameters

range Commands to enqueue

Definition at line 702 of file world.hpp.

◆ Entities() [1/2]

const EntityManager & helios::ecs::World::Entities ( ) const

inlinenodiscardnoexcept

Gets the entity manager.

Note: Thread-safe.

Returns: Const reference to entity manager

Definition at line 823 of file world.hpp.

◆ Entities() [2/2]

EntityManager & helios::ecs::World::Entities ( )

inlinenodiscardnoexcept

Gets the entity manager.

Note: Thread-safe.

Returns: Reference to entity manager

Definition at line 816 of file world.hpp.

◆ EntityCount()

size_t helios::ecs::World::EntityCount ( ) const

inlinenodiscardnoexcept

Gets the number of entities in the world.

Note: Thread-safe for read operations.

Returns: Number of entities in the world

Definition at line 789 of file world.hpp.

◆ Exists()

bool helios::ecs::World::Exists ( Entity entity ) const

inlinenodiscardnoexcept

Checks if entity exists in the world.

Note: Thread-safe for read operations.

Warning: Triggers assertion if entity is invalid.

Parameters

entity Entity to check

Returns: True if entity exists, false otherwise

Definition at line 1307 of file world.hpp.

◆ Flush()

void helios::ecs::World::Flush ( )

inline

Flushes entity reservations and executes pending commands.

Does not advance the message lifecycle. Call Update() to also swap message buffers and clear aged automatic messages.

Note: Not thread-safe.

Definition at line 901 of file world.hpp.

◆ HasCommands()

bool helios::ecs::World::HasCommands ( ) const

inlinenodiscardnoexcept

Checks if there are any pending commands in the command queue.

Note: Thread-safe for read operations.

Returns: True if there are pending commands, false otherwise

Definition at line 780 of file world.hpp.

◆ HasComponent()

template<ComponentTrait T>

bool helios::ecs::World::HasComponent ( Entity entity ) const

inlinenodiscard

Checks if entity has component.

Note: Thread-safe for read operations.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.

Template Parameters

T	Component type to check

Parameters

entity Entity to check

Returns: True if entity has the component

Definition at line 1313 of file world.hpp.

◆ HasComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)

auto helios::ecs::World::HasComponents ( Entity entity ) const -> std::array< bool, sizeof...(Ts)>

inlinenodiscard

Checks if entity has components.

Note: Thread-safe for read operations.

Warning: Triggers assertion if entity is invalid.

Template Parameters

Ts	Components types

Parameters

entity Entity to check

Returns: Array of bools indicating whether entity has each component (true if entity has component, false otherwise)

Definition at line 1322 of file world.hpp.

◆ HasMessage()

template<AnyMessageTrait T>

bool helios::ecs::World::HasMessage ( ) const

inlinenodiscardnoexcept

Checks if a message added.

Note: Thread-safe for read operations.

Template Parameters

T	Message type

Returns: True if message exists, false otherwise

Definition at line 760 of file world.hpp.

◆ HasMessages()

template<AnyMessageTrait T>

bool helios::ecs::World::HasMessages ( ) const

inlinenodiscardnoexcept

Checks if messages of a specific type exist in message queue.

Note: Thread-safe for read operations.

Template Parameters

T	Message type

Returns: True if messages exist, false otherwise

Definition at line 771 of file world.hpp.

◆ HasResource()

template<ResourceTrait T>

bool helios::ecs::World::HasResource ( ) const

inlinenodiscard

Checks if a resource exists.

Note: Thread-safe for read operations.

Template Parameters

T	Resource type

Returns: True if resource exists, false otherwise

Definition at line 749 of file world.hpp.

◆ InsertResources() [1/2]

template<ResourceTrait T>

void helios::ecs::World::InsertResources ( T && resource )

inline

Inserts a resource into the world.

Replaces existing resource if present.

Note: Not thread-safe.

Template Parameters

T	Resource type

Parameters

resource Resource to insert

Definition at line 1126 of file world.hpp.

◆ InsertResources() [2/2]

template<ResourceTrait... Ts>
requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 1)

void helios::ecs::World::InsertResources ( Ts &&... resources )

inline

Inserts resources into the world.

Replaces existing resources if present.

Note: Not thread-safe.

Template Parameters

Ts	Resource types

Parameters

resources Resources to insert

Definition at line 450 of file world.hpp.

◆ Messages() [1/2]

const MessageManager & helios::ecs::World::Messages ( ) const

inlinenodiscardnoexcept

Gets the message manager (const).

Note: Thread-safe.

Returns: Const reference to message manager

Definition at line 873 of file world.hpp.

◆ Messages() [2/2]

MessageManager & helios::ecs::World::Messages ( )

inlinenodiscardnoexcept

Gets the message manager.

Note: Thread-safe.

Returns: Mutable reference to message manager

Definition at line 866 of file world.hpp.

◆ operator=() [1/2]

World & helios::ecs::World::operator= ( const World & )

delete

◆ operator=() [2/2]

World & helios::ecs::World::operator= ( World && )

defaultnoexcept

◆ Query() [1/3]

template<QueryArg... Args, typename Allocator = std::allocator<ComponentTypeIndex>>

auto helios::ecs::World::Query ( Allocator alloc = {} ) -> BasicQuery< World, Allocator, Args... >

inlinenodiscardnoexcept

Creates a query over entities matching the specified component criteria.

Component filters (With<>, Without<>) and access types (T&, const T&, T*, ...) are all specified as template arguments.

Note: Not thread-safe.

Template Parameters

Args	Component access types and optional With/Without filters
Allocator	Allocator type for internal query storage

Parameters

alloc Allocator instance

Returns: Query object over entities matching the specified criteria

// Default allocator — no argument needed
auto query = world.Query<Transform&, const Velocity&,
                         const Gravity*, With<Player>,
                         Without<Dead>>();
 
for (auto&& [transform, velocity, gravity] : query) {
  transform.position += velocity.direction * velocity.speed;
  if (gravity) {
    transform.position.y += gravity->force;
  }
}

Definition at line 162 of file world.hpp.

◆ Query() [2/3]

template<QueryArg... Args>

auto helios::ecs::World::Query ( std::nullptr_t ) -> BasicQuery< World, std::pmr::polymorphic_allocator<>, Args... >=delete

delete

◆ Query() [3/3]

template<QueryArg... Args>

auto helios::ecs::World::Query ( std::pmr::memory_resource * resource ) -> BasicQuery< World, std::pmr::polymorphic_allocator<>, Args... >

inlinenodiscardnoexcept

Creates a query using a PMR memory resource.

Equivalent to the allocator overload but accepts a pmr::memory_resource* directly, constructing a pmr::polymorphic_allocator internally.

Note: Not thread-safe.

Template Parameters

Args	Component access types and optional With/Without filters

Parameters

resource Memory resource for internal query storage

Returns: Query object over entities matching the specified criteria

auto query = world.Query<Transform&, const Velocity&>(&resource);
 
for (auto&& [transform, velocity] : query) {
  transform.position += velocity.direction * velocity.speed;
}

Definition at line 188 of file world.hpp.

◆ ReadAsyncMessages()

template<AsyncMessageTrait T>

auto helios::ecs::World::ReadAsyncMessages ( ) -> AsyncMessageReader< T >

inlinenodiscardnoexcept

Gets a reader for messages of type T.

Note: Thread-safe.

Warning: Triggers assertion if message type is not added.

Template Parameters

T	Async message type

Returns: Async message reader for type T

Definition at line 1245 of file world.hpp.

◆ ReadComponent()

template<ComponentTrait T>

const T & helios::ecs::World::ReadComponent ( Entity entity ) const

inlinenodiscard

Gets a const reference to a component.

Note: Thread-safe for read operations.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.
Entity does not have the component.

Template Parameters

T	Component type

Parameters

entity Entity to get component from

Returns: Const reference to component

Definition at line 1102 of file world.hpp.

◆ ReadConsumableMessages()

template<ConsumableMessageTrait T>

auto helios::ecs::World::ReadConsumableMessages ( ) -> ConsumableMessageReader< T >

inlinenodiscardnoexcept

Gets a consumable reader for messages of type T without consume support.

Note: Thread-safe.

Warning: Triggers assertion if message type is not added.

Template Parameters

T	Consumable message type

Returns: Consumable message reader for type T

Definition at line 1293 of file world.hpp.

◆ ReadMessages()

template<MessageTrait T>

auto helios::ecs::World::ReadMessages ( ) const -> MessageReader< T >

inlinenodiscardnoexcept

Gets a reader for messages of type T without consume support.

Note: Thread-safe.

Warning: Triggers assertion if message type is not added.

Template Parameters

T	Message type

Returns: Message reader for type T

Definition at line 1286 of file world.hpp.

◆ ReadOnlyQuery() [1/3]

template<QueryArg... Args, typename Allocator = std::allocator<ComponentTypeIndex>>
requires details::ValidWorldComponentAccessFromTuple< const World, typename details::QueryArgSplit<Args...>::Components>::kValue

auto helios::ecs::World::ReadOnlyQuery ( Allocator alloc = {} ) const -> BasicQuery< const World, Allocator, Args... >

inlinenodiscardnoexcept

Creates a read-only query over entities matching the specified component criteria.

All component accesses must be const-qualified or be values (being copied) — T& and T* are rejected at compile time.

Note: Not thread-safe.

Template Parameters

Args	Component access types and optional With/Without filters
Allocator	Allocator type for internal query storage

Parameters

alloc Allocator instance

Returns: Query object over entities matching the specified criteria

// Default allocator — no argument needed
auto query = world.ReadOnlyQuery<Health, const Status*,
                                 With<Player>, Without<Dead>>();
 
for (auto&& [health, status] : query) {
  if (status) {
    helios::log::Trace("health: {}, status: {}", health, *status);
  }
}

Definition at line 226 of file world.hpp.

◆ ReadOnlyQuery() [2/3]

template<QueryArg... Args>
requires details::ValidWorldComponentAccessFromTuple< const World, typename details::QueryArgSplit<Args...>::Components>::kValue

auto helios::ecs::World::ReadOnlyQuery ( std::nullptr_t ) const -> BasicQuery< const World, std::pmr::polymorphic_allocator<>, Args... >=delete

delete

◆ ReadOnlyQuery() [3/3]

template<QueryArg... Args>
requires details::ValidWorldComponentAccessFromTuple< const World, typename details::QueryArgSplit<Args...>::Components>::kValue

auto helios::ecs::World::ReadOnlyQuery ( std::pmr::memory_resource * resource ) const -> BasicQuery< const World, std::pmr::polymorphic_allocator<>, Args... >

inlinenodiscardnoexcept

Creates a read-only query using a PMR memory resource.

All component accesses must be const-qualified — see the allocator overload for details.

Note: Not thread-safe.

Template Parameters

Args	Component access types and optional With/Without filters

Parameters

resource Memory resource for internal query storage

Returns: Query object over entities matching the specified criteria

auto query = world.ReadOnlyQuery<Health, const Status*>(&resource);
 
for (auto&& [health, status] : query) {
  if (status) {
    helios::log::Trace("health: {}, status: {}", health, *status);
  }
}

Definition at line 256 of file world.hpp.

◆ ReadResource()

template<ResourceTrait T>

const T & helios::ecs::World::ReadResource ( ) const

inlinenodiscardnoexcept

Gets const reference to a resource.

Note: Thread-safe for read operations.

Warning: Triggers assertion if resource doesn't exist.

Template Parameters

T	Resource type

Returns: Const reference to resource

Definition at line 1225 of file world.hpp.

◆ RemoveComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)

void helios::ecs::World::RemoveComponents ( Entity entity )

inline

Removes components from the entity.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.
Entity does not have any of the components.

Template Parameters

Ts	Components types to remove

Parameters

entity Entity to remove components from

Definition at line 1044 of file world.hpp.

◆ RemoveResources()

template<ResourceTrait... Ts>
requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)

void helios::ecs::World::RemoveResources ( )

inline

Removes resources from the world.

Note: Not thread-safe.

Warning: Triggers assertion if resource does not exist.

Template Parameters

Ts	Resource types

Definition at line 1175 of file world.hpp.

◆ ReserveCommands()

void helios::ecs::World::ReserveCommands ( size_t count )

inline

Reserves capacity in the command queue to avoid reallocations.

Note: Not thread-safe.

Parameters

count Number of commands to reserve space for

Definition at line 679 of file world.hpp.

◆ ReserveEntity()

Entity helios::ecs::World::ReserveEntity ( )

inlinenodiscard

Reserves an entity ID for deferred creation.

The actual entity creation is deferred until Update() is called.

Note: Thread-safe.

Returns: Reserved entity ID

Definition at line 88 of file world.hpp.

◆ ResourceCount()

size_t helios::ecs::World::ResourceCount ( ) const

inlinenodiscardnoexcept

Gets the number of resources in the world.

Note: Thread-safe for read operations.

Returns: Number of resources in the world

Definition at line 798 of file world.hpp.

◆ Resources() [1/2]

const ResourceManager & helios::ecs::World::Resources ( ) const

inlinenodiscardnoexcept

Gets the resource manager (const).

Note: Thread-safe.

Returns: Const reference to resource manager

Definition at line 857 of file world.hpp.

◆ Resources() [2/2]

ResourceManager & helios::ecs::World::Resources ( )

inlinenodiscardnoexcept

Gets the resource manager.

Note: Thread-safe.

Returns: Mutable reference to resource manager

Definition at line 850 of file world.hpp.

◆ TryAddComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)

auto helios::ecs::World::TryAddComponents	(	Entity	entity,
		Ts &&...	components ) -> std::conditional_t< sizeof...(Ts)==1, bool, std::array< bool, sizeof...(Ts)> >

inline

Tries to add components to the entity if they don't exist.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.

Template Parameters

Ts	Components types to add

Parameters

entity	Entity to add components to
components	Components to add

Returns: Array of bools indicating whether each component was added (true if added, false otherwise) if more than one component was added, otherwise returns a single bool indicating whether the component was added.

Definition at line 985 of file world.hpp.

◆ TryDestroyEntities()

template<std::ranges::input_range R>
requires std::same_as<std::ranges::range_value_t<R>, Entity>

void helios::ecs::World::TryDestroyEntities ( const R & entities )

inline

Tries to destroy entities if they exist in the world.

Note: Not thread-safe.

Warning: Triggers assertion only if any entity is invalid (non-existing entities are skipped).

Template Parameters

R	Range type containing Entity elements

Parameters

entities Entities to destroy

Definition at line 964 of file world.hpp.

◆ TryDestroyEntity()

void helios::ecs::World::TryDestroyEntity ( Entity entity )

inline

Tries to destroy entity if it exists in the world.

Note: Not thread-safe.

Warning: Triggers assertion if entity is invalid.

Parameters

entity Entity to destroy

Definition at line 940 of file world.hpp.

◆ TryEmplaceComponent()

template<ComponentTrait T, typename... Args>
requires std::constructible_from<T, Args...>

bool helios::ecs::World::TryEmplaceComponent	(	Entity	entity,
		Args &&...	args )

inline

Tries to emplace component for the entity.

Constructs component in-place. Returns false if component is already on the entity.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.

Template Parameters

T	Component type to emplace
Args	Argument types to forward to T's constructor

Parameters

entity	Entity to emplace component to
args	Arguments to forward to component constructor

Returns: True if component was emplaced, false otherwise

Definition at line 1028 of file world.hpp.

◆ TryEmplaceResource()

template<ResourceTrait T, typename... Args>
requires std::constructible_from<T, Args...>

bool helios::ecs::World::TryEmplaceResource ( Args &&... args )

inline

Tries to emplace a resource if not present.

Note: Not thread-safe.

Template Parameters

T	Resource type
Args	Constructor argument types

Parameters

args	Arguments to forward to resource constructor

Returns: True if emplaced, false if resource already exists

Definition at line 1160 of file world.hpp.

◆ TryInsertResources() [1/2]

template<ResourceTrait T>

bool helios::ecs::World::TryInsertResources ( T && resource )

inline

Tries to insert resource if not present.

Note: Not thread-safe.

Template Parameters

T	Resource type

Parameters

resource Resource to insert

Returns: True if inserted, false if resource already exists

Definition at line 1135 of file world.hpp.

◆ TryInsertResources() [2/2]

template<ResourceTrait... Ts>

auto helios::ecs::World::TryInsertResources ( Ts &&... resources ) -> std::array< bool, sizeof...(Ts)>

inline

Tries to insert resources if not present.

Note: Not thread-safe.

Template Parameters

Ts	Resource types

Parameters

resources Resources to insert

Returns: Array of bools indicating whether each resource was inserted

Definition at line 472 of file world.hpp.

◆ TryReadComponent()

template<ComponentTrait T>

const T * helios::ecs::World::TryReadComponent ( Entity entity ) const

inlinenodiscard

Tries to get a const pointer to a component.

Note: Thread-safe for read operations.

Template Parameters

T	Component type

Parameters

entity Entity to get component from

Returns: Const pointer to component, or nullptr if not found

Definition at line 1118 of file world.hpp.

◆ TryReadResource()

template<ResourceTrait T>

const T * helios::ecs::World::TryReadResource ( ) const

inlinenodiscardnoexcept

Tries to get const pointer to a resource.

Note: Thread-safe for read operations.

Template Parameters

T	Resource type

Returns: Const pointer to resource, or nullptr if not found

Definition at line 569 of file world.hpp.

◆ TryRemoveComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)

auto helios::ecs::World::TryRemoveComponents ( Entity entity ) -> std::conditional_t< sizeof...(Ts)==1, bool, std::array< bool, sizeof...(Ts)> >

inline

Tries to remove components from the entity if they exist.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.

Template Parameters

Ts	Components types to remove

Parameters

entity Entity to remove components from

Returns: Array of bools indicating whether each component was removed if more than one component was passed, otherwise returns a single bool indicating whether the component was removed.

Definition at line 1056 of file world.hpp.

◆ TryRemoveResources() [1/2]

template<ResourceTrait T>

bool helios::ecs::World::TryRemoveResources ( )

inline

Tries to remove resource.

Note: Not thread-safe.

Template Parameters

T	Resource type

Returns: True if removed, false if resource didn't exist

Definition at line 1204 of file world.hpp.

◆ TryRemoveResources() [2/2]

template<ResourceTrait... Ts>
requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 1)

auto helios::ecs::World::TryRemoveResources ( ) -> std::array< bool, sizeof...(Ts)>

inline

Tries to remove resources.

Note: Not thread-safe.

Template Parameters

Ts	Resource types

Returns: Array of bools indicating whether each resource was removed

Definition at line 527 of file world.hpp.

◆ TryWriteComponent()

template<ComponentTrait T>

T * helios::ecs::World::TryWriteComponent ( Entity entity )

inlinenodiscard

Tries to get a mutable pointer to a component.

Note: Not thread-safe.

Template Parameters

T	Component type

Parameters

entity Entity to get component from

Returns: Pointer to component, or nullptr if not found

Definition at line 1110 of file world.hpp.

◆ TryWriteResource()

template<ResourceTrait T>

T * helios::ecs::World::TryWriteResource ( )

inlinenodiscardnoexcept

Tries to get mutable pointer to a resource.

Note: Thread-safe for read operations.

Template Parameters

T	Resource type

Returns: Pointer to resource, or nullptr if not found

Definition at line 558 of file world.hpp.

◆ Update()

void helios::ecs::World::Update ( )

inline

Flushes buffer of pending operations.

Note: Not thread-safe.

Definition at line 894 of file world.hpp.

◆ WriteAsyncMessages()

template<AsyncMessageTrait T>

auto helios::ecs::World::WriteAsyncMessages ( ) -> AsyncMessageWriter< T >

inlinenodiscardnoexcept

Gets a writer for messages of type T.

Note: Thread-safe.

Warning: Triggers assertion if message type is not added.

Template Parameters

T	Async message type

Returns: Async message writer for type T

Definition at line 1252 of file world.hpp.

◆ WriteComponent()

template<ComponentTrait T>

T & helios::ecs::World::WriteComponent ( Entity entity )

inlinenodiscard

Gets a mutable reference to a component.

Note: Not thread-safe.

Warning

Triggers assertion in next cases:

Entity is invalid.
World does not own entity.
Entity does not have the component.

Template Parameters

T	Component type

Parameters

entity Entity to get component from

Returns: Mutable reference to component

Definition at line 1094 of file world.hpp.

◆ WriteMessages()

template<MessageTrait T>

auto helios::ecs::World::WriteMessages ( ) -> BasicMessageWriter< T >

inlinenodiscardnoexcept

Gets a writer for messages of type T.

Note: Not thread-safe.

Warning: Triggers assertion if message type is not added.

Template Parameters

T	Message type

Returns: Message writer for type T

Definition at line 1301 of file world.hpp.

◆ WriteResource()

template<ResourceTrait T>

T & helios::ecs::World::WriteResource ( )

inlinenodiscardnoexcept

Gets reference to a resource.

Note: Not thread-safe.

Warning: Triggers assertion if resource does not exist.

Template Parameters

T	Resource type

Returns: Reference to resource

Definition at line 1218 of file world.hpp.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ World() [1/3]

◆ World() [2/3]

◆ World() [3/3]

◆ ~World()

Member Function Documentation

◆ AddBuiltinMessages()

◆ AddComponents()

◆ AddMessage()

◆ AddMessages()

◆ Clear()

◆ ClearComponents()

◆ ClearEntities()

◆ ClearMessages() [1/2]

◆ ClearMessages() [2/2]

◆ CommandCount()

◆ Components() [1/2]

◆ Components() [2/2]

◆ CreateEntity()

◆ DestroyEntities()

◆ DestroyEntity()

◆ EmplaceComponent()

◆ EmplaceResource()

◆ EnqueueCommand()

◆ EnqueueCommandBulk()

◆ Entities() [1/2]

◆ Entities() [2/2]

◆ EntityCount()

◆ Exists()

◆ Flush()

◆ HasCommands()

◆ HasComponent()

◆ HasComponents()

◆ HasMessage()

◆ HasMessages()

◆ HasResource()

◆ InsertResources() [1/2]

◆ InsertResources() [2/2]

◆ Messages() [1/2]

◆ Messages() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Query() [1/3]

◆ Query() [2/3]

◆ Query() [3/3]

◆ ReadAsyncMessages()

◆ ReadComponent()

◆ ReadConsumableMessages()

◆ ReadMessages()

◆ ReadOnlyQuery() [1/3]

◆ ReadOnlyQuery() [2/3]

◆ ReadOnlyQuery() [3/3]

◆ ReadResource()

◆ RemoveComponents()

◆ RemoveResources()

◆ ReserveCommands()

◆ ReserveEntity()

◆ ResourceCount()

◆ Resources() [1/2]

◆ Resources() [2/2]

◆ TryAddComponents()

◆ TryDestroyEntities()

◆ TryDestroyEntity()

◆ TryEmplaceComponent()

◆ TryEmplaceResource()

◆ TryInsertResources() [1/2]

◆ TryInsertResources() [2/2]

◆ TryReadComponent()

◆ TryReadResource()

◆ TryRemoveComponents()

◆ TryRemoveResources() [1/2]

◆ TryRemoveResources() [2/2]

◆ TryWriteComponent()

◆ TryWriteResource()

◆ Update()

◆ WriteAsyncMessages()

◆ WriteComponent()

◆ WriteMessages()