helios::ecs::World Class Reference

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

#include <world.hpp>

Public Member Functions
	World ()=default
	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	Clear ()
	Clears the world, removing all data.
void	ClearEntities () noexcept
	Clears all entities and components from the world.
void	ClearAllEventQueues () noexcept
	Clears all event queues without removing event registration.
void	MergeEventQueue (details::EventQueue &other)
	Merges events from another event queue into the main queue.
template<std::ranges::range R> requires std::same_as<std::ranges::range_value_t<R>, std::unique_ptr<Command>>
void	MergeCommands (R &&commands)
	Merges commands from a command range into the main queue.
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::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::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<ComponentTrait T>
void	AddComponent (Entity entity, T &&component)
	Adds component to the entity.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...>
void	AddComponents (Entity entity, Ts &&... components)
	Adds components to the entity.
template<ComponentTrait T>
bool	TryAddComponent (Entity entity, T &&component)
	Tries to remove component from the entity.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...>
auto	TryAddComponents (Entity entity, Ts &&... components) -> 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 T>
void	RemoveComponent (Entity entity)
	Removes component from the entity.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...>
void	RemoveComponents (Entity entity)
	Removes components from the entity.
template<ComponentTrait T>
bool	TryRemoveComponent (Entity entity)
	Tries to removes component from the entity if it exists.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...>
auto	TryRemoveComponents (Entity entity) -> std::array< bool, sizeof...(Ts)>
	Gets component from the entity (const version).
void	ClearComponents (Entity entity)
	Removes all components from the entity.
template<ResourceTrait T>
void	InsertResource (T &&resource)
	Inserts a resource into the world.
template<ResourceTrait T>
bool	TryInsertResource (T &&resource)
	Tries to insert a resource 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 T>
void	RemoveResource ()
	Removes a resource from the world.
template<ResourceTrait T>
bool	TryRemoveResource ()
	Tries to remove a resource.
template<ResourceTrait T>
T &	WriteResource ()
	Gets reference to a resource.
template<ResourceTrait T>
const T &	ReadResource () const
	Gets const reference to a resource.
template<ResourceTrait T>
T *	TryWriteResource ()
	Tries to get mutable pointer to a resource.
template<ResourceTrait T>
const T *	TryReadResource () const
	Tries to get const pointer to a resource.
template<EventTrait T>
void	AddEvent ()
	Registers an event type for use.
template<EventTrait... Events> requires (sizeof...(Events) > 1)
void	AddEvents ()
	Registers multiple event types for use.
template<EventTrait T>
void	ClearEvents ()
	Manually clears events of a specific type from both queues.
template<EventTrait T>
auto	ReadEvents () const noexcept -> EventReader< T >
	Gets an event reader for type T.
template<EventTrait T>
auto	WriteEvents () -> EventWriter< T >
	Gets an event writer for type T.
bool	Exists (Entity entity) const
	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...>
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<ResourceTrait T>
bool	HasEvent () const
	Checks if a event registered.
template<ResourceTrait T>
bool	HasEvents () const
	Checks if events of a specific type exist in event queue.
size_t	EntityCount () const noexcept
	Gets the number of entities in the world.

Friends
template<WorldType WorldT, typename Allocator , ComponentTrait... Components>
class	BasicQuery
template<WorldType WorldT, typename Allocator , ComponentTrait... Components>
class	BasicQueryWithEntity

Detailed Description

The World class manages entities with their components and systems.

Note

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

Definition at line 53 of file world.hpp.

Constructor & Destructor Documentation

World() [1/3]

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

default

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

AddComponent()

template<ComponentTrait T>

void helios::ecs::World::AddComponent ( Entity  entity, T &&  component  )

inline

Adds component 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

T	Component type to add

Parameters

entity	Entity to add component to
component	Component to add

Definition at line 757 of file world.hpp.

                                                            {
  HELIOS_ASSERT(entity.Valid(), "Failed to add component: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to add component: World does not own entity with index '{}'!", entity.Index());
 
  components_.AddComponent(entity, std::forward<T>(component));
  UpdateEntityArchetypeOnAdd<std::remove_cvref_t<T>>(entity);
}

AddComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...>

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 767 of file world.hpp.

                                                                  {
  HELIOS_ASSERT(entity.Valid(), "Failed to add components: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to add components: World does not own entity with index '{}'!", entity.Index());
 
  (components_.AddComponent(entity, std::forward<Ts>(components)), ...);
  UpdateEntityArchetype(entity);
}

AddEvent()

template<EventTrait T>

void helios::ecs::World::AddEvent ( )

inline

Registers an event type for use.

Events must be registered before they can be written or read. Built-in events (EntitySpawnedEvent, EntityDestroyedEvent) are registered with is_builtin flag.

Note

Not thread-safe. Should be called during initialization.

Template Parameters

T	Event type

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 967 of file world.hpp.

                            {
  if (event_manager_.IsRegistered<T>()) [[unlikely]] {
    HELIOS_WARN("Event '{}' is already registered in the world!", EventNameOf<T>());
    return;
  }
 
  event_manager_.RegisterEvent<T>();
}

AddEvents()

template<EventTrait... Events>
requires (sizeof...(Events) > 1)

void helios::ecs::World::AddEvents ( )

inline

Registers multiple event types for use.

Note

Not thread-safe. Should be called during initialization.

Template Parameters

Events

Event types to register

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 451 of file world.hpp.

                   {
    (AddEvent<Events>(), ...);
  }

Clear()

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

inline

Clears the world, removing all data.

Note

Not thread-safe.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 645 of file world.hpp.

                         {
  entities_.Clear();
  components_.Clear();
  archetypes_.Clear();
  resources_.Clear();
  command_queue_.Clear();
  event_manager_.Clear();
}

ClearAllEventQueues()

void helios::ecs::World::ClearAllEventQueues ( )

inlinenoexcept

Clears all event queues without removing event registration.

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

Note

Not thread-safe.

Definition at line 88 of file world.hpp.

{ event_manager_.ClearAllQueues(); }

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 917 of file world.hpp.

                                                {
  HELIOS_ASSERT(entity.Valid(), "Failed to clear components: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to clear components: World does not own entity with index '{}'!",
                entity.Index());
 
  components_.RemoveAllComponents(entity);
  archetypes_.RemoveEntity(entity);
}

ClearEntities()

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

inlinenoexcept

Clears all entities and components from the world.

Note

Not thread-safe.

Definition at line 654 of file world.hpp.

                                          {
  entities_.Clear();
  components_.Clear();
  archetypes_.Clear();
}

ClearEvents()

template<EventTrait T>

void helios::ecs::World::ClearEvents ( )

inline

Manually clears events of a specific type from both queues.

Should only be used for manually-managed events (auto_clear = false). Built-in events cannot be manually cleared.

Note

Not thread-safe.

Warning

Triggers assertion if event type is not registered.

Template Parameters

T	Event type

Definition at line 977 of file world.hpp.

                               {
  HELIOS_ASSERT(event_manager_.IsRegistered<T>(), "Failed to clear events of type '{}': Event type is not registered!",
                EventNameOf<T>());
 
  event_manager_.ManualClear<T>();
}

CreateEntity()

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

inline

Creates new entity.

If EntitySpawnedEvent is registered, emits the event automatically.

Note

Not thread-safe.

Returns

Newly created entity.

Definition at line 660 of file world.hpp.

                                  {
  Entity entity = entities_.CreateEntity();
 
  // Emit EntitySpawnedEvent if registered
  if (event_manager_.IsRegistered<EntitySpawnedEvent>()) {
    event_manager_.Write(EntitySpawnedEvent{entity});
  }
 
  return entity;
}

DestroyEntities()

template<std::ranges::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 715 of file world.hpp.

                                                          {
  const bool emit_events = event_manager_.IsRegistered<EntityDestroyedEvent>();
 
  for (const Entity& entity : entities_range) {
    HELIOS_ASSERT(entity.Valid(), "Failed to destroy entities: Entity is invalid!");
    HELIOS_ASSERT(Exists(entity), "Failed to destroy entities: World does not own entity with index '{}'!",
                  entity.Index());
 
    // Emit EntityDestroyedEvent if registered
    if (emit_events) {
      event_manager_.Write(EntityDestroyedEvent{entity});
    }
 
    components_.RemoveAllComponents(entity);
    archetypes_.RemoveEntity(entity);
  }
  entities_.Destroy(entities_range);
}

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 683 of file world.hpp.

                                              {
  HELIOS_ASSERT(entity.Valid(), "Failed to destroy entity: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to destroy entity: World does not own entity with index '{}'!", entity.Index());
 
  // Emit EntityDestroyedEvent if registered
  if (event_manager_.IsRegistered<EntityDestroyedEvent>()) {
    event_manager_.Write(EntityDestroyedEvent{entity});
  }
 
  components_.RemoveAllComponents(entity);
  archetypes_.RemoveEntity(entity);
  entities_.Destroy(entity);
}

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 825 of file world.hpp.

                                                                 {
  HELIOS_ASSERT(entity.Valid(), "Failed to emplace component: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to emplace component: World does not own entity with index '{}'!",
                entity.Index());
 
  components_.EmplaceComponent<T>(entity, std::forward<Args>(args)...);
  UpdateEntityArchetypeOnAdd<T>(entity);
}

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

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 352 of file world.hpp.

                                       {
    resources_.Emplace<T>(std::forward<Args>(args)...);
  }

EntityCount()

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

inlinenoexcept

Gets the number of entities in the world.

Note

Thread-safe for read operations.

Returns

Number of entities in the world

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 565 of file world.hpp.

{ return entities_.Count(); }

Exists()

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

inline

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

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 944 of file world.hpp.

                                             {
  HELIOS_ASSERT(entity.Valid(), "Failed to check if entity exists: Entity is invalid!");
  return entities_.IsValid(entity);
}

HasComponent()

template<ComponentTrait T>

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

inline

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

Array of bools indicating whether entity has each component

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 950 of file world.hpp.

                                                   {
  HELIOS_ASSERT(entity.Valid(), "Failed to check if entity has component: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to check if entity has component: World does not own entity with index '{}'!",
                entity.Index());
  return components_.HasComponent<T>(entity);
}

HasComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...>

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

inline

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 959 of file world.hpp.

                                                                                     {
  HELIOS_ASSERT(entity.Valid(), "Failed to check if entity has components: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to check if entity has components: World does not own entity with index '{}'!",
                entity.Index());
  return {components_.HasComponent<Ts>(entity)...};
}

HasEvent()

template<ResourceTrait T>

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

inline

Checks if a event registered.

Note

Thread-safe for read operations.

Template Parameters

T	Event type

Returns

True if event exists, false otherwise

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 545 of file world.hpp.

                                      {
    return event_manager_.IsRegistered<T>();
  }

HasEvents()

template<ResourceTrait T>

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

inline

Checks if events of a specific type exist in event queue.

Note

Thread-safe for read operations.

Template Parameters

T	Event type

Returns

True if event exists, false otherwise

Definition at line 556 of file world.hpp.

                                       {
    return event_manager_.HasEvents<T>();
  }

HasResource()

template<ResourceTrait T>

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

inline

Checks if a resource exists.

Note

Thread-safe for read operations.

Template Parameters

T	Resource type

Returns

True if resource exists, false otherwise

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 534 of file world.hpp.

                                         {
    return resources_.Has<T>();
  }

InsertResource()

template<ResourceTrait T>

void helios::ecs::World::InsertResource ( 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

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 327 of file world.hpp.

                                    {
    resources_.Insert(std::forward<T>(resource));
  }

MergeCommands()

template<std::ranges::range R>
requires std::same_as<std::ranges::range_value_t<R>, std::unique_ptr<Command>>

void helios::ecs::World::MergeCommands ( R &&  commands )

inline

Merges commands from a command range into the main queue.

Note

Not thread-safe.

Template Parameters

R	Range type containing unique_ptr<Command> elements

Parameters

commands

Range of commands to merge from

Definition at line 673 of file world.hpp.

                                             {
  if (commands.empty()) [[unlikely]] {
    return;
  }
 
  // Enqueue all commands from the range to the command queue
  command_queue_.EnqueueBulk(std::forward<R>(commands));
  commands.clear();
}

MergeEventQueue()

void helios::ecs::World::MergeEventQueue ( details::EventQueue &  other )

inline

Merges events from another event queue into the main queue.

Note

Not thread-safe.

Parameters

other

Event queue to merge from

Definition at line 95 of file world.hpp.

{ event_manager_.Merge(other); }

operator=() [1/2]

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

delete

operator=() [2/2]

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

defaultnoexcept

ReadEvents()

template<EventTrait T>

auto helios::ecs::World::ReadEvents ( ) const -> EventReader<T>

inlinenoexcept

Gets an event reader for type T.

Provides a type-safe, ergonomic API for reading events with support for iteration, filtering, and searching. Event must be registered via AddEvent<T>() first.

Note

Thread-safe for read operations.

Warning

Triggers assertion if event type is not registered.

Template Parameters

T	Event type

Returns

EventReader for type T

Definition at line 985 of file world.hpp.

                                                               {
  HELIOS_ASSERT(event_manager_.IsRegistered<T>(),
                "Failed to get event reader for type '{}': Event type is not registered!", EventNameOf<T>());
 
  return EventReader<T>(event_manager_);
}

ReadResource()

template<ResourceTrait T>

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

inline

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

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 939 of file world.hpp.

                                          {
  HELIOS_ASSERT(HasResource<T>(), "Failed to read resource '{}': Resource does not exist!", ResourceNameOf<T>());
  return resources_.Get<T>();
}

RemoveComponent()

template<ComponentTrait T>

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

inline

Removes component from 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 remove

Parameters

entity

Entity to remove component from

Definition at line 851 of file world.hpp.

                                                {
  HELIOS_ASSERT(entity.Valid(), "Failed to remove component: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to remove component: World does not own entity with index '{}'!",
                entity.Index());
 
  components_.RemoveComponent<T>(entity);
  UpdateEntityArchetypeOnRemove<T>(entity);
}

RemoveComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...>

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.

Template Parameters

Ts	Components types to remove

Parameters

entity

Entity to remove components from

Definition at line 862 of file world.hpp.

                                                 {
  HELIOS_ASSERT(entity.Valid(), "Failed to remove components: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to remove components: World does not own entity with index '{}'!",
                entity.Index());
 
  (components_.RemoveComponent<Ts>(entity), ...);
  UpdateEntityArchetype(entity);
}

RemoveResource()

template<ResourceTrait T>

void helios::ecs::World::RemoveResource ( )

inline

Removes a resource from the world.

Note

Not thread-safe.

Warning

Triggers assertion if resource does not exist.

Template Parameters

T	Resource type

Definition at line 927 of file world.hpp.

                                  {
  HELIOS_ASSERT(HasResource<T>(), "Failed to remove resource '{}': Resource does not exist!", ResourceNameOf<T>());
  resources_.Remove<T>();
}

ReserveEntity()

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

inline

Reserves an entity ID for deferred creation.

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

Note

Thread-safe.

Returns

Reserved entity ID

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 121 of file world.hpp.

{ return entities_.ReserveEntity(); }

TryAddComponent()

template<ComponentTrait T>

bool helios::ecs::World::TryAddComponent ( Entity  entity, T &&  component  )

inline

Tries to remove component from the entity.

Returns false if component is not 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 remove

Parameters

entity

Entity to remove component from

Returns

True if component was removed, false otherwise

Definition at line 776 of file world.hpp.

                                                               {
  HELIOS_ASSERT(entity.Valid(), "Failed to try add component: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to try add component: World does not own entity with index '{}'!",
                entity.Index());
 
  using ComponentType = std::decay_t<T>;
  if (components_.HasComponent<ComponentType>(entity)) {
    return false;
  }
 
  components_.AddComponent(entity, std::forward<T>(component));
  UpdateEntityArchetypeOnAdd<ComponentType>(entity);
  return true;
}

TryAddComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...>

auto helios::ecs::World::TryAddComponents ( Entity  entity, Ts &&...  components  ) -> 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)

Definition at line 793 of file world.hpp.

                                                                                                      {
  HELIOS_ASSERT(entity.Valid(), "Failed to try add components: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to try add components: World does not own entity with index '{}'!",
                entity.Index());
 
  std::array<bool, sizeof...(Ts)> result = {!components_.HasComponent<std::decay_t<Ts>>(entity)...};
  bool any_added = false;
 
  size_t idx = 0;
  auto add_if_missing = [this, &result, &any_added, &idx, entity](auto&& component) {
    using ComponentType = std::decay_t<decltype(component)>;
    if (!components_.HasComponent<ComponentType>(entity)) {
      components_.AddComponent(entity, std::forward<decltype(component)>(component));
      result[idx] = true;
      any_added = true;
    } else {
      result[idx] = false;
    }
    ++idx;
  };
 
  (add_if_missing(std::forward<Ts>(components)), ...);
 
  if (any_added) {
    UpdateEntityArchetype(entity);
  }
 
  return result;
}

TryDestroyEntities()

template<std::ranges::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 736 of file world.hpp.

                                                             {
  const bool emit_events = event_manager_.IsRegistered<EntityDestroyedEvent>();
 
  for (const Entity& entity : entities_range) {
    HELIOS_ASSERT(entity.Valid(), "Failed to try destroy entities: Entity is invalid!");
    if (!Exists(entity)) [[unlikely]] {
      continue;
    }
 
    // Emit EntityDestroyedEvent if registered
    if (emit_events) {
      event_manager_.Write(EntityDestroyedEvent{entity});
    }
 
    components_.RemoveAllComponents(entity);
    archetypes_.RemoveEntity(entity);
  }
  entities_.Destroy(entities_range);
}

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 only if entity is invalid (does not assert when entity does not exist in the world).

Parameters

entity

Entity to destroy

Definition at line 697 of file world.hpp.

                                                 {
  HELIOS_ASSERT(entity.Valid(), "Failed to try destroy entity: Entity is invalid!");
  if (!Exists(entity)) {
    return;
  }
 
  // Emit EntityDestroyedEvent if registered
  if (event_manager_.IsRegistered<EntityDestroyedEvent>()) {
    event_manager_.Write(EntityDestroyedEvent{entity});
  }
 
  components_.RemoveAllComponents(entity);
  archetypes_.RemoveEntity(entity);
  entities_.Destroy(entity);
}

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 836 of file world.hpp.

                                                                    {
  HELIOS_ASSERT(entity.Valid(), "Failed to try emplace component: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to try emplace component: World does not own entity with index '{}'!",
                entity.Index());
 
  if (components_.HasComponent<T>(entity)) {
    return false;
  }
 
  components_.EmplaceComponent<T>(entity, std::forward<Args>(args)...);
  UpdateEntityArchetypeOnAdd<T>(entity);
  return true;
}

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 366 of file world.hpp.

                                          {
    return resources_.TryEmplace<T>(std::forward<Args>(args)...);
  }

TryInsertResource()

template<ResourceTrait T>

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

inline

Tries to insert a 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 339 of file world.hpp.

                                       {
    return resources_.TryInsert(std::forward<T>(resource));
  }

TryReadResource()

template<ResourceTrait T>

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

inline

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

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 428 of file world.hpp.

                                                 {
    return resources_.TryGet<T>();
  }

TryRemoveComponent()

template<ComponentTrait T>

bool helios::ecs::World::TryRemoveComponent ( Entity  entity )

inline

Tries to removes component from the entity if it exists.

Note

Not thread-safe.

Warning

Triggers assertion in next cases:

• Entity is invalid.
• World does not own entity.

Template Parameters

T	Component type to remove

Parameters

entity

Entity to remove component from

Returns

True if component will be removed, false otherwise

Definition at line 872 of file world.hpp.

                                                   {
  HELIOS_ASSERT(entity.Valid(), "Failed to try remove component: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to try remove component: World does not own entity with index '{}'!",
                entity.Index());
 
  const bool had_component = components_.HasComponent<T>(entity);
  if (had_component) {
    components_.RemoveComponent<T>(entity);
    UpdateEntityArchetypeOnRemove<T>(entity);
  }
  return had_component;
}

TryRemoveComponents()

template<ComponentTrait... Ts>
requires utils::UniqueTypes<Ts...>

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

inline

Gets component from the entity (const version).

Note

Not thread-safe.

Warning

Triggers assertion in next cases:

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

Template Parameters

T	Component type to get

Parameters

entity

Entity to get component from

Returns

Const reference to component

Definition at line 887 of file world.hpp.

                                                                                     {
  HELIOS_ASSERT(entity.Valid(), "Failed to try remove components: Entity is invalid!");
  HELIOS_ASSERT(Exists(entity), "Failed to try remove components: World does not own entity with index '{}'!",
                entity.Index());
 
  std::array<bool, sizeof...(Ts)> result = {};
  bool any_removed = false;
 
  size_t index = 0;
  auto try_remove_single = [this, &index, &result, &any_removed, entity](auto type_identity_tag) {
    using ComponentType = typename decltype(type_identity_tag)::type;
    if (components_.HasComponent<ComponentType>(entity)) {
      components_.RemoveComponent<ComponentType>(entity);
      result[index] = true;
      any_removed = true;
    } else {
      result[index] = false;
    }
    ++index;
  };
 
  (try_remove_single(std::type_identity<Ts>{}), ...);
 
  if (any_removed) {
    UpdateEntityArchetype(entity);
  }
 
  return result;
}

TryRemoveResource()

template<ResourceTrait T>

bool helios::ecs::World::TryRemoveResource ( )

inline

Tries to remove a resource.

Note

Not thread-safe.

Template Parameters

T	Resource type

Returns

True if removed, false if resource didn't exist

Definition at line 386 of file world.hpp.

                           {
    return resources_.TryRemove<T>();
  }

TryWriteResource()

template<ResourceTrait T>

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

inline

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

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 417 of file world.hpp.

                                      {
    return resources_.TryGet<T>();
  }

Update()

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

inline

Flushes buffer of pending operations.

Note

This method should be called once per frame after all systems have been updated. Not thread-safe.

Definition at line 627 of file world.hpp.

                          {
  // First, flush reserved entities to ensure all reserved IDs are created.
  entities_.FlushReservedEntities();
 
  // Then, execute all commands in the command queue.
  if (!command_queue_.Empty()) [[likely]] {
    auto commands = command_queue_.DequeueAll();
    for (auto& command : commands) {
      if (command) [[likely]] {
        command->Execute(*this);
      }
    }
  }
 
  // Update event lifecycle - swap buffers and clear old events
  event_manager_.Update();
}

WriteEvents()

template<EventTrait T>

auto helios::ecs::World::WriteEvents ( ) -> EventWriter<T>

inline

Gets an event writer for type T.

Provides a type-safe, ergonomic API for writing events with support for bulk operations and in-place construction. Event must be registered via AddEvent<T>() first.

Note

Not thread-safe.

Warning

Triggers assertion if event type is not registered.

Template Parameters

T	Event type

Returns

EventWriter for type T

Definition at line 993 of file world.hpp.

                                                 {
  HELIOS_ASSERT(event_manager_.IsRegistered<T>(),
                "Failed to get event writer for type '{}': Event type is not registered!", EventNameOf<T>());
 
  return EventWriter<T>(event_manager_);
}

WriteResource()

template<ResourceTrait T>

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

inline

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

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/system_context.hpp.

Definition at line 933 of file world.hpp.

                               {
  HELIOS_ASSERT(HasResource<T>(), "Failed to write resource '{}': Resource does not exist!", ResourceNameOf<T>());
  return resources_.Get<T>();
}

Friends And Related Symbol Documentation

BasicQuery

template<WorldType WorldT, typename Allocator , ComponentTrait... Components>

friend class BasicQuery

friend

Definition at line 620 of file world.hpp.

BasicQueryWithEntity

template<WorldType WorldT, typename Allocator , ComponentTrait... Components>

friend class BasicQueryWithEntity

friend

Definition at line 624 of file world.hpp.