cubos::core::ecs::Blueprint class final
#include <core/ecs/blueprint.hpp>

Collection of entities and their respective components and relations.

Blueprints are in a way the 'Prefab' of Cubos They act as a tiny World which can then be spawned into an actual World, as many times as needed.

When a blueprint is spawned, all of its components and relations are scanned using the Reflection system for any references to other entities in the blueprint. These references are then replaced with the actual spawned entities. This has the side effect that if you do not expose an Entity field to the Reflection system, it will not be replaced and thus continue referencing the original entity in the blueprint.

Public types

using Create = Entity(*)(void*userData, std::string name): Function used by instantiate to create entities.
using Add = void(*)(void*userData, Entity entity, memory::AnyValue component): Function used by instantiate to add components to entities.
using Relate = void(*)(void*userData, Entity fromEntity, Entity toEntity, memory::AnyValue relation): Function used by instantiate to add relations to entities.

Public static functions

static auto validEntityName(const std::string& name) -> bool: Checks if the given name is a valid entity name.

Public functions

auto create(std::string name) -> Entity: Creates a new entity in the blueprint and returns it.
void add(Entity entity, memory::AnyValue component): Adds a component to an entity. Overwrites the existing component, if there's any.
template<typename... Ts> void add(Entity entity, Ts... components): Adds components to an entity. Overwrites the existing components, if there's any.
void relate(Entity fromEntity, Entity toEntity, memory::AnyValue relation): Adds a relation between two entities. Overwrites the existing relation, if there's any.
template<typename T> void relate(Entity fromEntity, Entity toEntity, T relation): Adds a relation between two entities. Overwrites the existing relation, if there's any.
void merge(const std::string& prefix, const Blueprint& other): Merges another blueprint into this one.
void clear(): Clears the blueprint.
auto bimap() const -> const memory::UnorderedBimap<Entity, std::string, EntityHash>&: Returns a bimap which maps entities to their names.
void instantiate(void* userData, Create create, Add add, Relate relate, bool withName) const: Instantiates the blueprint by calling the given functions.
template<typename C, typename A, typename R> void instantiate(C create, A add, R relate, bool withName) const: Instantiates the blueprint by calling the given functors.
auto entities() const -> memory::UnorderedBimap<Entity, std::string, EntityHash>: Gets the map relating entities to their name.
auto components() const -> memory::TypeMap<EntityMap<memory::AnyValue>>: Gets the map relating types of components to maps of entities to the component values.
auto relations() const -> memory::TypeMap<EntityMap<EntityMap<memory::AnyValue>>>: Gets the map relating types of relations to maps of entities to maps of entities to the component values.

Function documentation

static bool cubos::core::ecs::Blueprint::validEntityName(const std::string& name)

Checks if the given name is a valid entity name.

Returns	Whether the name is valid.

Entity names must contain only lowercase alphanumerical characters and hyphens.

Entity cubos::core::ecs::Blueprint::create(std::string name)

Creates a new entity in the blueprint and returns it.

Parameters
name	Entity name.
Returns	Entity.

An entity with the same name must not exist. The name must be valid.

void cubos::core::ecs::Blueprint::add(Entity entity, memory::AnyValue component)

Adds a component to an entity. Overwrites the existing component, if there's any.

Parameters
entity	Entity.
component	Component to move.

template<typename... Ts>
void cubos::core::ecs::Blueprint::add(Entity entity, Ts... components)

Adds components to an entity. Overwrites the existing components, if there's any.

Template parameters
Ts	Component types.
Parameters
entity	Entity.
components	Components to move.

void cubos::core::ecs::Blueprint::relate(Entity fromEntity, Entity toEntity, memory::AnyValue relation)

Adds a relation between two entities. Overwrites the existing relation, if there's any.

Parameters
fromEntity	From entity.
toEntity	To entity.
relation	Relation to move.

template<typename T>
void cubos::core::ecs::Blueprint::relate(Entity fromEntity, Entity toEntity, T relation)

Adds a relation between two entities. Overwrites the existing relation, if there's any.

Template parameters
T	Relation type.
Parameters
fromEntity	From entity.
toEntity	To entity.
relation	Relation to move.

void cubos::core::ecs::Blueprint::merge(const std::string& prefix, const Blueprint& other)

Merges another blueprint into this one.

Parameters
prefix	Name to prefix with the merged blueprint.
other	Blueprint to merge.

Entities in the other blueprint will have their names prefixed with the specified string.

const memory::UnorderedBimap<Entity, std::string, EntityHash>& cubos::core::ecs::Blueprint::bimap() const

Returns a bimap which maps entities to their names.

Returns	Bimap of entities to names.

void cubos::core::ecs::Blueprint::instantiate(void* userData, Create create, Add add, Relate relate, bool withName) const

Instantiates the blueprint by calling the given functions.

Parameters
userData	User data to pass into the functions.
create	Function used to create entities.
add	Function used to add components to entities.
relate	Function used to add relations to entities.
withName	Whether to add the 'Name' component to instantiated entities.

template<typename C, typename A, typename R>
void cubos::core::ecs::Blueprint::instantiate(C create, A add, R relate, bool withName) const

Instantiates the blueprint by calling the given functors.

Template parameters
C	Create functor type.
A	Add functor type.
R	Relate functor type.
Parameters
create	Functor used to create entities.
add	Functor used to add components to entities.
relate	Functor used to add relations to entities.
withName	Whether to use the entity names from the blueprint.

memory::UnorderedBimap<Entity, std::string, EntityHash> cubos::core::ecs::Blueprint::entities() const

Gets the map relating entities to their name.

Returns	Bimap relating entities and names

memory::TypeMap<EntityMap<memory::AnyValue>> cubos::core::ecs::Blueprint::components() const

Gets the map relating types of components to maps of entities to the component values.

Returns	TypeMap of an EntityMap to component values

memory::TypeMap<EntityMap<EntityMap<memory::AnyValue>>> cubos::core::ecs::Blueprint::relations() const

Gets the map relating types of relations to maps of entities to maps of entities to the component values.

Returns	TypeMap of an EntityMap to another EntityMap to component values