Stores entities and their component data in a Structure-of-Arrays layout for a specific archetype. More...

#include <archetype.hpp>

Public Types
using	size_type = size_t
using	RowIndex = uint32_t

Public Member Functions
	Archetype (ArchetypeId id)
	Constructs an archetype for the given archetype id.
	Archetype (const Archetype &)=delete
	Archetype (Archetype &&) noexcept=default
	~Archetype ()=default
Archetype &	operator= (const Archetype &)=delete
Archetype &	operator= (Archetype &&) noexcept=default
void	Clear ()
	Removes all entities and component data from this archetype.
RowIndex	AllocateRow (Entity entity)
	Allocates a new row for an entity without initializing component data.
template<ComponentTrait... Ts> requires utils::UniqueTypes<Ts...> && (sizeof...(Ts) > 0)
RowIndex	Add (Entity entity, Ts &&... components)
	Adds an entity with multiple components.
Entity	Remove (Entity entity)
	Removes an entity from this archetype using swap-and-pop.
template<ComponentTrait T>
void	Set (Entity entity, T &&component)
	Sets (overwrites) a component value for an existing entity.
template<ComponentTrait T, typename... Args> requires std::constructible_from<T, Args...>
void	Emplace (Entity entity, Args &&... args)
	Emplaces (overwrites) a component for an existing entity.
template<ComponentTrait T>
T &	Get (Entity entity)
	Gets a mutable reference to a component for an entity.
template<ComponentTrait T>
const T &	Get (Entity entity) const
	Gets a const reference to a component for an entity.
template<ComponentTrait T>
T *	TryGet (Entity entity)
	Tries to get a mutable pointer to a component for an entity.
template<ComponentTrait T>
const T *	TryGet (Entity entity) const
	Tries to get a const pointer to a component for an entity.
template<ComponentTrait T>
auto	ComponentColumn () -> std::span< T >
	Gets a typed span over an entire component column.
template<ComponentTrait T>
auto	ComponentColumn () const -> std::span< const T >
	Gets a const typed span over an entire component column.
container::TypedBufferArray &	Column (ComponentTypeIndex index) noexcept
	Gets a raw column by component type index.
const container::TypedBufferArray &	Column (ComponentTypeIndex index) const noexcept
	Gets a const raw column by component type index.
container::TypedBufferArray *	TryColumn (ComponentTypeIndex index) noexcept
	Tries to get a raw column by component type index.
const container::TypedBufferArray *	TryColumn (ComponentTypeIndex index) const noexcept
	Tries to get a const raw column by component type index.
RowIndex	Row (Entity entity) const
	Gets the row index for an entity.
Entity	EntityAt (RowIndex row) const
	Gets the entity at a given row.
bool	Empty () const noexcept
	Returns true if no entities are stored.
bool	Contains (Entity entity) const noexcept
	Checks if the archetype contains the given entity.
template<ComponentTrait T>
bool	HasColumn () const noexcept
	Checks if this archetype has a column for the given component type.
bool	HasColumn (ComponentTypeIndex index) const noexcept
	Checks if this archetype has a column for the given component index.
size_type	EntityCount () const noexcept
	Gets the number of entities stored in this archetype.
size_type	ColumnCount () const noexcept
	Gets the number of component columns in this archetype.
auto	Entities () const noexcept -> std::span< const Entity >
	Gets a span of all entities stored in this archetype.
const ArchetypeId &	Id () const noexcept
	Gets the archetype id.

Static Public Attributes
static constexpr RowIndex	kInvalidRow = std::numeric_limits<RowIndex>::max()

Detailed Description

Stores entities and their component data in a Structure-of-Arrays layout for a specific archetype.

An archetype represents a unique combination of component types. All entities sharing the same set of archetype-storage components are stored together for cache-friendly iteration.

Internally maintains:

A dense entity list for fast iteration
One TypedBufferArray column per component type, indexed by ComponentTypeIndex
An entity-to-row mapping for O(1) lookup by entity index

Removal uses swap-and-pop to maintain dense packing without leaving holes.

Component data migration between archetypes is handled externally by ComponentManager, which uses typed function pointers from ComponentMetadata to avoid virtual calls and raw byte manipulation of non-trivial types.

Note: Not thread-safe.

Definition at line 50 of file archetype.hpp.

Member Typedef Documentation

◆ RowIndex

using helios::ecs::Archetype::RowIndex = uint32_t

Definition at line 53 of file archetype.hpp.

◆ size_type

using helios::ecs::Archetype::size_type = size_t

Definition at line 52 of file archetype.hpp.

Constructor & Destructor Documentation

◆ Archetype() [1/3]

helios::ecs::Archetype::Archetype ( ArchetypeId id )

inlineexplicit

Constructs an archetype for the given archetype id.

Initializes one column per component type in the id. Columns are created untyped; they will be typed on first insert via ComponentManager.

Parameters

id	The archetype id defining which component types this archetype stores

Definition at line 342 of file archetype.hpp.

◆ Archetype() [2/3]

helios::ecs::Archetype::Archetype ( const Archetype & )

delete

◆ Archetype() [3/3]

helios::ecs::Archetype::Archetype ( Archetype && )

defaultnoexcept

◆ ~Archetype()

helios::ecs::Archetype::~Archetype ( )

default

Member Function Documentation

◆ Add()

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

auto helios::ecs::Archetype::Add	(	Entity	entity,
		Ts &&...	components ) -> RowIndex

inline

Adds an entity with multiple components.

Warning

Triggers assertion in next cases:

Entity is invalid.
Entity already exists in this archetype.
Any component type is not part of this archetype.

Template Parameters

Ts	Component types, must be unique and at least 1 type

Parameters

entity	Entity to add
components	Component values

Returns: Row index of the new entity

Definition at line 371 of file archetype.hpp.

◆ AllocateRow()

auto helios::ecs::Archetype::AllocateRow ( Entity entity )

inline

Allocates a new row for an entity without initializing component data.

Appends the entity to the entity list and returns the row index. The caller is responsible for pushing component data into each column afterwards. This is the primary entry point used by ComponentManager during entity migration.

Warning: Triggers assertion if entity is invalid or already present.

Parameters

entity Entity to allocate a row for

Returns: Row index of the newly allocated row

Definition at line 358 of file archetype.hpp.

◆ Clear()

void helios::ecs::Archetype::Clear ( )

inline

Removes all entities and component data from this archetype.

Definition at line 350 of file archetype.hpp.

◆ Column() [1/2]

auto helios::ecs::Archetype::Column ( ComponentTypeIndex index ) const

inlinenodiscardnoexcept

Gets a const raw column by component type index.

Warning: Triggers assertion if type index not found.

Parameters

index Component type index

Returns: Const reference to the column

Definition at line 613 of file archetype.hpp.

◆ Column() [2/2]

auto helios::ecs::Archetype::Column ( ComponentTypeIndex index )

inlinenodiscardnoexcept

Gets a raw column by component type index.

Warning: Triggers assertion if type index not found.

Parameters

index Component type index

Returns: Reference to the column

Definition at line 604 of file archetype.hpp.

◆ ColumnCount()

size_type helios::ecs::Archetype::ColumnCount ( ) const

inlinenodiscardnoexcept

Gets the number of component columns in this archetype.

Returns: Column count

Definition at line 299 of file archetype.hpp.

◆ ComponentColumn() [1/2]

template<ComponentTrait T>

auto helios::ecs::Archetype::ComponentColumn ( ) -> std::span< T >

inlinenodiscard

Gets a typed span over an entire component column.

Template Parameters

T	Component type

Returns: Span of all component values of this type

Definition at line 579 of file archetype.hpp.

◆ ComponentColumn() [2/2]

template<ComponentTrait T>

auto helios::ecs::Archetype::ComponentColumn ( ) const -> std::span< const T >

inlinenodiscard

Gets a const typed span over an entire component column.

Template Parameters

T	Component type

Returns: Const span of all component values of this type

Definition at line 592 of file archetype.hpp.

◆ Contains()

bool helios::ecs::Archetype::Contains ( Entity entity ) const

inlinenodiscardnoexcept

Checks if the archetype contains the given entity.

Parameters

entity Entity to check

Returns: True if the entity is stored in this archetype, false otherwise

Definition at line 653 of file archetype.hpp.

◆ Emplace()

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

void helios::ecs::Archetype::Emplace	(	Entity	entity,
		Args &&...	args )

inline

Emplaces (overwrites) a component for an existing entity.

Warning

Triggers assertion in next cases:

Entity is invalid.
Entity is not present in this archetype.
Component type is not part of this archetype.

Template Parameters

T	Component type
Args	Constructor argument types

Parameters

entity	Entity to modify
args	Arguments forwarded to component constructor

Definition at line 476 of file archetype.hpp.

◆ Empty()

bool helios::ecs::Archetype::Empty ( ) const

inlinenodiscardnoexcept

Returns true if no entities are stored.

Returns: True if the archetype is empty, false otherwise

Definition at line 259 of file archetype.hpp.

◆ Entities()

auto helios::ecs::Archetype::Entities ( ) const -> std::span< const Entity >

inlinenodiscardnoexcept

Gets a span of all entities stored in this archetype.

Returns: Const span of entities

Definition at line 307 of file archetype.hpp.

◆ EntityAt()

Entity helios::ecs::Archetype::EntityAt ( RowIndex row ) const

inlinenodiscard

Gets the entity at a given row.

Warning: Triggers assertion if row is out of bounds.

Parameters

row Row index

Returns: Entity at the given row

Definition at line 646 of file archetype.hpp.

◆ EntityCount()

size_type helios::ecs::Archetype::EntityCount ( ) const

inlinenodiscardnoexcept

Gets the number of entities stored in this archetype.

Returns: Entity count

Definition at line 291 of file archetype.hpp.

◆ Get() [1/2]

template<ComponentTrait T>

T & helios::ecs::Archetype::Get ( Entity entity )

inlinenodiscard

Gets a mutable reference to a component for an entity.

Warning

Triggers assertion in next cases:

Entity is invalid.
Entity is not present in this archetype.
Component type is not part of this archetype.

Template Parameters

T	Component type

Parameters

entity Entity to query

Returns: Mutable reference to component

Definition at line 509 of file archetype.hpp.

◆ Get() [2/2]

template<ComponentTrait T>

const T & helios::ecs::Archetype::Get ( Entity entity ) const

inlinenodiscard

Gets a const reference to a component for an entity.

Warning

Triggers assertion in next cases:

Entity is invalid.
Entity is not present in this archetype.
Component type is not part of this archetype.

Template Parameters

T	Component type

Parameters

entity Entity to query

Returns: Const reference to component

Definition at line 525 of file archetype.hpp.

◆ HasColumn() [1/2]

template<ComponentTrait T>

bool helios::ecs::Archetype::HasColumn ( ) const

inlinenodiscardnoexcept

Checks if this archetype has a column for the given component type.

Template Parameters

T	Component type

Returns: True if the archetype stores this component type, false otherwise

Definition at line 274 of file archetype.hpp.

◆ HasColumn() [2/2]

bool helios::ecs::Archetype::HasColumn ( ComponentTypeIndex index ) const

inlinenodiscardnoexcept

Checks if this archetype has a column for the given component index.

Parameters

index Component type index

Returns: True if the archetype stores this component type, false otherwise

Definition at line 283 of file archetype.hpp.

◆ Id()

const ArchetypeId & helios::ecs::Archetype::Id ( ) const

inlinenodiscardnoexcept

Gets the archetype id.

Returns: ArchetypeId of this archetype

Definition at line 315 of file archetype.hpp.

◆ operator=() [1/2]

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

defaultnoexcept

◆ operator=() [2/2]

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

delete

◆ Remove()

Entity helios::ecs::Archetype::Remove ( Entity entity )

inline

Removes an entity from this archetype using swap-and-pop.

Warning

Triggers assertion in next cases:

Entity is invalid.
Entity is not present in this archetype.

Parameters

entity Entity to remove

Returns: The entity that was swapped into the removed row, or invalid entity if the removed entity was last

Definition at line 408 of file archetype.hpp.

◆ Row()

auto helios::ecs::Archetype::Row ( Entity entity ) const

inlinenodiscard

Gets the row index for an entity.

Warning: Triggers assertion if entity is not present.

Parameters

entity Entity to look up

Returns: Row index

Definition at line 640 of file archetype.hpp.

◆ Set()

template<ComponentTrait T>

void helios::ecs::Archetype::Set	(	Entity	entity,
		T &&	component )

inline

Sets (overwrites) a component value for an existing entity.

Warning

Triggers assertion in next cases:

Entity is invalid.
Entity is not present in this archetype.
Component type is not part of this archetype.

Template Parameters

T	Component type

Parameters

entity	Entity to modify
component	New component value

Definition at line 445 of file archetype.hpp.

◆ TryColumn() [1/2]

auto helios::ecs::Archetype::TryColumn ( ComponentTypeIndex index ) const

inlinenodiscardnoexcept

Tries to get a const raw column by component type index.

Parameters

index Component type index

Returns: Const pointer to column or nullptr if type index not found

Definition at line 631 of file archetype.hpp.

◆ TryColumn() [2/2]

auto helios::ecs::Archetype::TryColumn ( ComponentTypeIndex index )

inlinenodiscardnoexcept

Tries to get a raw column by component type index.

Parameters

index Component type index

Returns: Pointer to column or nullptr if type index not found

Definition at line 622 of file archetype.hpp.

◆ TryGet() [1/2]

template<ComponentTrait T>

T * helios::ecs::Archetype::TryGet ( Entity entity )

inlinenodiscard

Tries to get a mutable pointer to a component for an entity.

Warning: Triggers assertion if entity is invalid.

Template Parameters

T	Component type

Parameters

entity Entity to query

Returns: Pointer to component or nullptr if entity or type not found

Definition at line 541 of file archetype.hpp.

◆ TryGet() [2/2]

template<ComponentTrait T>

const T * helios::ecs::Archetype::TryGet ( Entity entity ) const

inlinenodiscard

Tries to get a const pointer to a component for an entity.

Warning: Triggers assertion if entity is invalid.

Template Parameters

T	Component type

Parameters

entity Entity to query

Returns: Const pointer to component or nullptr if entity or type not found

Definition at line 560 of file archetype.hpp.

Member Data Documentation

◆ kInvalidRow

RowIndex helios::ecs::Archetype::kInvalidRow = std::numeric_limits<RowIndex>::max()

staticconstexpr

Definition at line 55 of file archetype.hpp.

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ RowIndex

◆ size_type

Constructor & Destructor Documentation

◆ Archetype() [1/3]

◆ Archetype() [2/3]

◆ Archetype() [3/3]

◆ ~Archetype()

Member Function Documentation

◆ Add()

◆ AllocateRow()

◆ Clear()

◆ Column() [1/2]

◆ Column() [2/2]

◆ ColumnCount()

◆ ComponentColumn() [1/2]

◆ ComponentColumn() [2/2]

◆ Contains()

◆ Emplace()

◆ Empty()

◆ Entities()

◆ EntityAt()

◆ EntityCount()

◆ Get() [1/2]

◆ Get() [2/2]

◆ HasColumn() [1/2]

◆ HasColumn() [2/2]

◆ Id()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Remove()

◆ Row()

◆ Set()

◆ TryColumn() [1/2]

◆ TryColumn() [2/2]

◆ TryGet() [1/2]

◆ TryGet() [2/2]

Member Data Documentation

◆ kInvalidRow