Central registry managing entities and an open set of component types. More...

#include <scene.h>

Public Member Functions
EntityId	createEntity ()
	Create a new entity and assign a unique EntityId.
EntityId	createEntityAt (uint32_t index)
	Allocate an entity at the requested slot index.
void	destroyEntity (EntityId id)
	Destroy an entity by removing all of its components and recycling its slot.
EntityId	entityAt (uint32_t index) const
	The full id of the entity in slot `index`, generation included.
template<typename T>
auto &	add (EntityId entity, T &&component)
	Give an entity a component it does not have yet.
template<typename T>
void	remove (EntityId entity)
	Take a component of type T off an entity.
template<typename T>
bool	has (EntityId entity) const
	Check if an entity has a component of type T.
template<typename T>
T &	get (EntityId entity)
	Get a mutable reference to an entity's component of type T.
template<typename T>
const T &	get (EntityId entity) const
	Get a const reference to an entity's component of type T.
template<typename T>
T *	tryGet (EntityId entity)
	The entity's T, or null when it has none.
template<typename T>
const T *	tryGet (EntityId entity) const
	The entity's T, or null when it has none.
template<typename T>
size_t	count () const
	Number of live components of type T.
template<typename First, typename... Rest, typename Fn>
void	forEach (Fn &&fn)
	Iterate all live components densely (no holes).
template<typename Fn>
void	forEachEntity (Fn &&fn) const
	Invoke fn(EntityId) for every live entity in this scene.
void	clear ()
	Drop every component set and reset the entity allocator, the environment and the physics settings in one pass.
void	compact ()
	Compact every component SparseSet to reclaim wasted memory.
void	swap (Scene &other) noexcept
	Swap internal state with another Scene.
void	addObserver (ISceneObserver *observer)
	Register an observer, notified at the start of every destroyEntity.
void	removeObserver (ISceneObserver *observer)
	Unregister an observer added with addObserver.
template<typename T>
SparseSet< T > *	storage ()
	Direct access to the typed SparseSet for component type T.
uint64_t	epoch () const
	Identity of the world these entities belong to, bumped by clear() and swap().
Environment &	environment ()
	The scene's lighting environment, saved with it.
PhysicsSettings &	physics ()
	The scene's physics world parameters, saved with it.

Detailed Description

Central registry managing entities and an open set of component types.

Entities come from a SlotAllocator; components live in SparseSet<T>s created on first use, so any type can be a component.

Member Function Documentation

◆ createEntity()

EntityId Vkm::Engine::Scene::createEntity ( )

inline

Create a new entity and assign a unique EntityId.

A recycled slot is emptied first: add() only asserts against a dead id, so without asserts a stale write leaves a component on the free slot, which the next entity there would inherit.

Returns: The created entity's id.

◆ createEntityAt()

EntityId Vkm::Engine::Scene::createEntityAt ( uint32_t index )

inline

Allocate an entity at the requested slot index.

For recreating an entity at a recorded slot (a scene file, an undo step, a peer) with no id remap. Empties the slot as createEntity() does.

Parameters

index Slot to claim; must not hold a live entity.

Returns: The new entity, or null when the slot was taken, is 0, or lies past SlotAllocator::MAX_CLAIMED_INDEX.

◆ destroyEntity()

void Vkm::Engine::Scene::destroyEntity ( EntityId id )

inline

Destroy an entity by removing all of its components and recycling its slot.

The teardown is keyed on the bare slot, so a stale id asserts and is refused, or it would destroy the slot's new owner.

Parameters

id	Entity to destroy.

◆ entityAt()

EntityId Vkm::Engine::Scene::entityAt ( uint32_t index ) const

inline

The full id of the entity in slot index, generation included.

Total: a dead slot yields an id that fails isAlive().

Parameters

index Slot index; any value is accepted.

Returns: The entity id for that slot, null when the slot is out of reach.

◆ add()

template<typename T>

auto & Vkm::Engine::Scene::add	(	EntityId	entity,
		T &&	component )

inline

Give an entity a component it does not have yet.

A second T asserts; without asserts the existing one is kept. To overwrite, remove<T>() then add, or assign through get<T>().

Template Parameters

T	Component type; storage is created on first use.

Parameters

entity	Entity to add to; alive, without a T.
component	Moved or copied in.

Returns: The component in storage.

◆ remove()

template<typename T>

void Vkm::Engine::Scene::remove ( EntityId entity )

inline

Take a component of type T off an entity.

A missing T is fine. A stale entity asserts and is refused, or the removal would hit the slot's new owner.

Template Parameters

T	Component type.

Parameters

entity Entity to take it from; must be alive.

◆ has()

template<typename T>

bool Vkm::Engine::Scene::has ( EntityId entity ) const

inline

Check if an entity has a component of type T.

Template Parameters

T	Component type.

Parameters

entity Entity to look on; any value is accepted.

Returns: True when that entity is alive and carries a T.

◆ get() [1/2]

template<typename T>

T & Vkm::Engine::Scene::get ( EntityId entity )

inline

Get a mutable reference to an entity's component of type T.

Template Parameters

T	Component type.

Parameters

entity Entity to read; must be alive and carry a T.

Returns: The component in storage.

◆ get() [2/2]

template<typename T>

const T & Vkm::Engine::Scene::get ( EntityId entity ) const

inline

Get a const reference to an entity's component of type T.

Template Parameters

T	Component type.

Parameters

entity Entity to read; must be alive and carry a T.

Returns: The component in storage.

◆ tryGet() [1/2]

template<typename T>

T * Vkm::Engine::Scene::tryGet ( EntityId entity )

inline

The entity's T, or null when it has none.

Template Parameters

T	Component type.

Parameters

entity Entity to look on; any value is accepted.

Returns: Pointer to its component, or nullptr.

◆ tryGet() [2/2]

template<typename T>

const T * Vkm::Engine::Scene::tryGet ( EntityId entity ) const

inline

The entity's T, or null when it has none.

Template Parameters

T	Component type.

Parameters

entity Entity to look on; any value is accepted.

Returns: Pointer to its component, or nullptr.

◆ count()

template<typename T>

size_t Vkm::Engine::Scene::count ( ) const

inline

Number of live components of type T.

Template Parameters

T	Component type.

Returns: How many entities carry a T.

◆ forEach()

template<typename First, typename... Rest, typename Fn>

void Vkm::Engine::Scene::forEach ( Fn && fn )

inline

Iterate all live components densely (no holes).

Walks First, yielding entities that also carry every Rest; put the rarest first. Do not add or remove a First, or create or destroy entities, during the walk (see SparseSet::forEach); collect and act after.

Template Parameters

First	Component type iterated.
Rest	Further required component types.

Parameters

fn	Callable as void(EntityId, First&, Rest&...).

◆ forEachEntity()

template<typename Fn>

void Vkm::Engine::Scene::forEachEntity ( Fn && fn ) const

inline

Invoke fn(EntityId) for every live entity in this scene.

Template Parameters

Fn	Callable taking an EntityId.

Parameters

fn	Called once per live entity, ascending by slot.

◆ clear()

void Vkm::Engine::Scene::clear ( )

inline

Drop every component set and reset the entity allocator, the environment and the physics settings in one pass.

The sets are destroyed, not emptied: a set's vtable may live in the gameplay module, which a project switch unloads next.

◆ swap()

void Vkm::Engine::Scene::swap ( Scene & other )

inlinenoexcept

Swap internal state with another Scene.

For committing a staging scene atomically. Re-fetch any storage<T>() pointer held across it; it now names the other scene's set.

Parameters

other Scene to exchange state with.

◆ addObserver()

void Vkm::Engine::Scene::addObserver ( ISceneObserver * observer )

inline

Register an observer, notified at the start of every destroyEntity.

Survives swap() and clear(); remove it before it is destroyed.

Parameters

observer Observer to notify; not owned.

◆ removeObserver()

void Vkm::Engine::Scene::removeObserver ( ISceneObserver * observer )

inline

Unregister an observer added with addObserver.

Parameters

observer Observer to stop notifying; absent is a no-op.

◆ storage()

template<typename T>

SparseSet< T > * Vkm::Engine::Scene::storage ( )

inline

Direct access to the typed SparseSet for component type T.

For index-based or parallel iteration.

Template Parameters

T	Component type.

Returns: The storage, or nullptr if no entity has ever added a T.

◆ epoch()

uint64_t Vkm::Engine::Scene::epoch ( ) const

inline

Identity of the world these entities belong to, bumped by clear() and swap().

A replacement world can reuse the old ids (createEntityAt), so a cache keyed on an entity or a pose must drop its capture when this moves.

Returns: The current epoch.

◆ environment()

Environment & Vkm::Engine::Scene::environment ( )

inline

The scene's lighting environment, saved with it.

Returns: This scene's Environment.

◆ physics()

PhysicsSettings & Vkm::Engine::Scene::physics ( )

inline

The scene's physics world parameters, saved with it.

Returns: This scene's PhysicsSettings.

The documentation for this class was generated from the following file:

ecs/scene.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ createEntity()

◆ createEntityAt()

◆ destroyEntity()

◆ entityAt()

◆ add()

◆ remove()

◆ has()

◆ get() [1/2]

◆ get() [2/2]

◆ tryGet() [1/2]

◆ tryGet() [2/2]

◆ count()

◆ forEach()

◆ forEachEntity()

◆ clear()

◆ swap()

◆ addObserver()

◆ removeObserver()

◆ storage()

◆ epoch()

◆ environment()

◆ physics()