EnTT  3.9.0
Classes | Public Types | Public Member Functions | List of all members
entt::basic_registry< Entity > Class Template Reference

Fast and reliable entity-component system. More...

#include <registry.hpp>

Public Types

using entity_type = Entity
 Underlying entity identifier.
 
using version_type = typename entity_traits::version_type
 Underlying version type.
 
using size_type = std::size_t
 Unsigned integer type.
 
using base_type = basic_common_type
 Common type among all storage types.
 

Public Member Functions

 basic_registry ()=default
 Default constructor.
 
 basic_registry (basic_registry &&other)
 Move constructor. More...
 
basic_registryoperator= (basic_registry &&other)
 Move assignment operator. More...
 
auto storage ()
 Returns an iterable object to use to visit a registry. More...
 
auto storage () const
 Returns an iterable object to use to visit a registry. More...
 
template<typename Component >
decltype(auto) storage (const id_type id=type_hash< Component >::value())
 Returns the storage for a given component type. More...
 
template<typename Component >
decltype(auto) storage (const id_type id=type_hash< Component >::value()) const
 Returns an iterable object to use to visit a registry. More...
 
size_type size () const
 Returns the number of entities created so far. More...
 
size_type alive () const
 Returns the number of entities still in use. More...
 
void reserve (const size_type cap)
 Increases the capacity (number of entities) of the registry. More...
 
size_type capacity () const
 Returns the number of entities that a registry has currently allocated space for. More...
 
bool empty () const
 Checks whether the registry is empty (no entities still in use). More...
 
const entity_typedata () const
 Direct access to the list of entities of a registry. More...
 
entity_type released () const
 Returns the head of the list of released entities. More...
 
bool valid (const entity_type entity) const
 Checks if an identifier refers to a valid entity. More...
 
version_type current (const entity_type entity) const
 Returns the actual version for an identifier. More...
 
entity_type create ()
 Creates a new entity or recycles a destroyed one. More...
 
entity_type create (const entity_type hint)
 Creates a new entity or recycles a destroyed one. More...
 
template<typename It >
void create (It first, It last)
 Assigns each element in a range an identifier. More...
 
template<typename It >
void assign (It first, It last, const entity_type destroyed)
 Assigns identifiers to an empty registry. More...
 
version_type release (const entity_type entity)
 Releases an identifier. More...
 
version_type release (const entity_type entity, const version_type version)
 Releases an identifier. More...
 
template<typename It >
void release (It first, It last)
 Releases all identifiers in a range. More...
 
version_type destroy (const entity_type entity)
 Destroys an entity and releases its identifier. More...
 
version_type destroy (const entity_type entity, const version_type version)
 Destroys an entity and releases its identifier. More...
 
template<typename It >
void destroy (It first, It last)
 Destroys all entities in a range and releases their identifiers. More...
 
template<typename Component , typename... Args>
decltype(auto) emplace (const entity_type entity, Args &&...args)
 Assigns the given component to an entity. More...
 
template<typename Component , typename It >
void insert (It first, It last, const Component &value={})
 Assigns each entity in a range the given component. More...
 
template<typename Component , typename EIt , typename CIt , typename = std::enable_if_t<std::is_same_v<std::decay_t<typename std::iterator_traits<CIt>::value_type>, Component>>>
void insert (EIt first, EIt last, CIt from)
 Assigns each entity in a range the given components. More...
 
template<typename Component , typename... Args>
decltype(auto) emplace_or_replace (const entity_type entity, Args &&...args)
 Assigns or replaces the given component for an entity. More...
 
template<typename Component , typename... Func>
decltype(auto) patch (const entity_type entity, Func &&...func)
 Patches the given component for an entity. More...
 
template<typename Component , typename... Args>
decltype(auto) replace (const entity_type entity, Args &&...args)
 Replaces the given component for an entity. More...
 
template<typename Component , typename... Other>
size_type remove (const entity_type entity)
 Removes the given components from an entity. More...
 
template<typename Component , typename... Other, typename It >
size_type remove (It first, It last)
 Removes the given components from all the entities in a range. More...
 
template<typename Component , typename... Other>
void erase (const entity_type entity)
 Erases the given components from an entity. More...
 
template<typename Component , typename... Other, typename It >
void erase (It first, It last)
 Erases the given components from all the entities in a range. More...
 
template<typename... Component>
void compact ()
 Removes all tombstones from a registry or only the pools for the given components. More...
 
template<typename... Component>
bool all_of (const entity_type entity) const
 Checks if an entity has all the given components. More...
 
template<typename... Component>
bool any_of (const entity_type entity) const
 Checks if an entity has at least one of the given components. More...
 
template<typename... Component>
decltype(auto) get ([[maybe_unused]] const entity_type entity) const
 Returns references to the given components for an entity. More...
 
template<typename... Component>
decltype(auto) get ([[maybe_unused]] const entity_type entity)
 Returns references to the given components for an entity. More...
 
template<typename Component , typename... Args>
decltype(auto) get_or_emplace (const entity_type entity, Args &&...args)
 Returns a reference to the given component for an entity. More...
 
template<typename... Component>
auto try_get ([[maybe_unused]] const entity_type entity) const
 Returns pointers to the given components for an entity. More...
 
template<typename... Component>
auto try_get ([[maybe_unused]] const entity_type entity)
 Returns pointers to the given components for an entity. More...
 
template<typename... Component>
void clear ()
 Clears a whole registry or the pools for the given components. More...
 
template<typename Func >
void each (Func func) const
 Iterates all the entities that are still in use. More...
 
bool orphan (const entity_type entity) const
 Checks if an entity has components assigned. More...
 
template<typename Component >
auto on_construct ()
 Returns a sink object for the given component. More...
 
template<typename Component >
auto on_update ()
 Returns a sink object for the given component. More...
 
template<typename Component >
auto on_destroy ()
 Returns a sink object for the given component. More...
 
template<typename Component , typename... Other, typename... Exclude>
basic_view< Entity, get_t< std::add_const_t< Component >, std::add_const_t< Other >... >, exclude_t< Exclude... > > view (exclude_t< Exclude... >={}) const
 Returns a view for the given components. More...
 
template<typename Component , typename... Other, typename... Exclude>
basic_view< Entity, get_t< Component, Other... >, exclude_t< Exclude... > > view (exclude_t< Exclude... >={})
 Returns a view for the given components. More...
 
template<typename ItComp , typename ItExcl = id_type *>
basic_runtime_view< Entity > runtime_view (ItComp first, ItComp last, ItExcl from={}, ItExcl to={}) const
 Returns a runtime view for the given components. More...
 
template<typename... Owned, typename... Get, typename... Exclude>
basic_group< Entity, owned_t< Owned... >, get_t< Get... >, exclude_t< Exclude... > > group (get_t< Get... >, exclude_t< Exclude... >={})
 Returns a group for the given components. More...
 
template<typename... Owned, typename... Get, typename... Exclude>
basic_group< Entity, owned_t< std::add_const_t< Owned >... >, get_t< std::add_const_t< Get >... >, exclude_t< Exclude... > > group_if_exists (get_t< Get... >, exclude_t< Exclude... >={}) const
 Returns a group for the given components. More...
 
template<typename... Owned, typename... Exclude>
basic_group< Entity, owned_t< Owned... >, get_t<>, exclude_t< Exclude... > > group (exclude_t< Exclude... >={})
 Returns a group for the given components. More...
 
template<typename... Owned, typename... Exclude>
basic_group< Entity, owned_t< std::add_const_t< Owned >... >, get_t<>, exclude_t< Exclude... > > group_if_exists (exclude_t< Exclude... >={}) const
 Returns a group for the given components. More...
 
template<typename... Component>
bool sortable () const
 Checks whether the given components belong to any group. More...
 
template<typename... Owned, typename... Get, typename... Exclude>
bool sortable (const basic_group< Entity, owned_t< Owned... >, get_t< Get... >, exclude_t< Exclude... >> &)
 Checks whether a group can be sorted. More...
 
template<typename Component , typename Compare , typename Sort = std_sort, typename... Args>
void sort (Compare compare, Sort algo=Sort{}, Args &&...args)
 Sorts the elements of a given component. More...
 
template<typename To , typename From >
void sort ()
 Sorts two pools of components in the same way. More...
 
template<typename Type , typename... Args>
Type & set (Args &&...args)
 Binds an object to the context of the registry. More...
 
template<typename Type >
void unset ()
 Unsets a context variable if it exists. More...
 
template<typename Type , typename... Args>
Type & ctx_or_set (Args &&...args)
 Binds an object to the context of the registry. More...
 
template<typename Type >
std::add_const_t< Type > * try_ctx () const
 Returns a pointer to an object in the context of the registry. More...
 
template<typename Type >
Type * try_ctx ()
 Returns a pointer to an object in the context of the registry. More...
 
template<typename Type >
std::add_const_t< Type > & ctx () const
 Returns a reference to an object in the context of the registry. More...
 
template<typename Type >
Type & ctx ()
 Returns a reference to an object in the context of the registry. More...
 
template<typename Func >
void ctx (Func func) const
 Visits a registry and returns the type info for its context variables. More...
 

Detailed Description

template<typename Entity>
class entt::basic_registry< Entity >

Fast and reliable entity-component system.

Template Parameters
EntityA valid entity type (see entt_traits for more details).

Definition at line 173 of file registry.hpp.

Constructor & Destructor Documentation

◆ basic_registry()

template<typename Entity >
entt::basic_registry< Entity >::basic_registry ( basic_registry< Entity > &&  other)
inline

Move constructor.

Parameters
otherThe instance to move from.

Definition at line 290 of file registry.hpp.

Member Function Documentation

◆ alive()

template<typename Entity >
size_type entt::basic_registry< Entity >::alive ( ) const
inline

Returns the number of entities still in use.

Returns
Number of entities still in use.

Definition at line 376 of file registry.hpp.

◆ all_of()

template<typename Entity >
template<typename... Component>
bool entt::basic_registry< Entity >::all_of ( const entity_type  entity) const
inline

Checks if an entity has all the given components.

Warning
Attempting to use an invalid entity results in undefined behavior.
Template Parameters
ComponentComponents for which to perform the check.
Parameters
entityA valid identifier.
Returns
True if the entity has all the components, false otherwise.

Definition at line 893 of file registry.hpp.

◆ any_of()

template<typename Entity >
template<typename... Component>
bool entt::basic_registry< Entity >::any_of ( const entity_type  entity) const
inline

Checks if an entity has at least one of the given components.

Warning
Attempting to use an invalid entity results in undefined behavior.
Template Parameters
ComponentComponents for which to perform the check.
Parameters
entityA valid identifier.
Returns
True if the entity has at least one of the given components, false otherwise.

Definition at line 910 of file registry.hpp.

◆ assign()

template<typename Entity >
template<typename It >
void entt::basic_registry< Entity >::assign ( It  first,
It  last,
const entity_type  destroyed 
)
inline

Assigns identifiers to an empty registry.

This function is intended for use in conjunction with data, size and destroyed.
Don't try to inject ranges of randomly generated entities nor the wrong head for the list of destroyed entities. There is no guarantee that a registry will continue to work properly in this case.

Warning
There must be no entities still alive for this to work properly.
Template Parameters
ItType of input iterator.
Parameters
firstAn iterator to the first element of the range of entities.
lastAn iterator past the last element of the range of entities.
destroyedThe head of the list of destroyed entities.

Definition at line 541 of file registry.hpp.

◆ capacity()

template<typename Entity >
size_type entt::basic_registry< Entity >::capacity ( ) const
inline

Returns the number of entities that a registry has currently allocated space for.

Returns
Capacity of the registry.

Definition at line 399 of file registry.hpp.

◆ clear()

template<typename Entity >
template<typename... Component>
void entt::basic_registry< Entity >::clear ( )
inline

Clears a whole registry or the pools for the given components.

Template Parameters
ComponentTypes of components to remove from their entities.

Definition at line 1001 of file registry.hpp.

◆ compact()

template<typename Entity >
template<typename... Component>
void entt::basic_registry< Entity >::compact ( )
inline

Removes all tombstones from a registry or only the pools for the given components.

Template Parameters
ComponentTypes of components for which to clear all tombstones.

Definition at line 872 of file registry.hpp.

◆ create() [1/3]

template<typename Entity >
entity_type entt::basic_registry< Entity >::create ( )
inline

Creates a new entity or recycles a destroyed one.

Returns
A valid identifier.

Definition at line 464 of file registry.hpp.

◆ create() [2/3]

template<typename Entity >
entity_type entt::basic_registry< Entity >::create ( const entity_type  hint)
inline

Creates a new entity or recycles a destroyed one.

If the requested entity isn't in use, the suggested identifier is used. Otherwise, a new identifier is generated.

Parameters
hintRequired identifier.
Returns
A valid identifier.

Definition at line 477 of file registry.hpp.

◆ create() [3/3]

template<typename Entity >
template<typename It >
void entt::basic_registry< Entity >::create ( It  first,
It  last 
)
inline

Assigns each element in a range an identifier.

See also
create
Template Parameters
ItType of forward iterator.
Parameters
firstAn iterator to the first element of the range to generate.
lastAn iterator past the last element of the range to generate.

Definition at line 510 of file registry.hpp.

◆ ctx() [1/3]

template<typename Entity >
template<typename Type >
Type& entt::basic_registry< Entity >::ctx ( )
inline

Returns a reference to an object in the context of the registry.

Warning
Attempting to get a context variable that doesn't exist results in undefined behavior.
Template Parameters
TypeType of object to get.
Returns
A valid reference to the object in the context of the registry.

Definition at line 1508 of file registry.hpp.

◆ ctx() [2/3]

template<typename Entity >
template<typename Type >
std::add_const_t<Type>& entt::basic_registry< Entity >::ctx ( ) const
inline

Returns a reference to an object in the context of the registry.

Warning
Attempting to get a context variable that doesn't exist results in undefined behavior.
Template Parameters
TypeType of object to get.
Returns
A valid reference to the object in the context of the registry.

Definition at line 1500 of file registry.hpp.

◆ ctx() [3/3]

template<typename Entity >
template<typename Func >
void entt::basic_registry< Entity >::ctx ( Func  func) const
inline

Visits a registry and returns the type info for its context variables.

The signature of the function should be equivalent to the following:

void(const type_info &);

Returned identifiers are those of the context variables currently set.

See also
type_info
Template Parameters
FuncType of the function object to invoke.
Parameters
funcA valid function object.

Definition at line 1532 of file registry.hpp.

◆ ctx_or_set()

template<typename Entity >
template<typename Type , typename... Args>
Type& entt::basic_registry< Entity >::ctx_or_set ( Args &&...  args)
inline

Binds an object to the context of the registry.

In case the context doesn't contain the given object, the parameters provided are used to construct it.

Template Parameters
TypeType of object to set.
ArgsTypes of arguments to use to construct the object.
Parameters
argsParameters to use to initialize the object.
Returns
A reference to the object in the context of the registry.

Definition at line 1461 of file registry.hpp.

◆ current()

template<typename Entity >
version_type entt::basic_registry< Entity >::current ( const entity_type  entity) const
inline

Returns the actual version for an identifier.

Parameters
entityA valid identifier.
Returns
The version for the given identifier if valid, the tombstone version otherwise.

Definition at line 455 of file registry.hpp.

◆ data()

template<typename Entity >
const entity_type* entt::basic_registry< Entity >::data ( ) const
inline

Direct access to the list of entities of a registry.

The returned pointer is such that range [data(), data() + size()) is always a valid range, even if the registry is empty.

Warning
This list contains both valid and destroyed entities and isn't suitable for direct use.
Returns
A pointer to the array of entities.

Definition at line 423 of file registry.hpp.

◆ destroy() [1/3]

template<typename Entity >
version_type entt::basic_registry< Entity >::destroy ( const entity_type  entity)
inline

Destroys an entity and releases its identifier.

See also
release
Warning
Adding or removing components to an entity that is being destroyed can result in undefined behavior. Attempting to use an invalid entity results in undefined behavior.
Parameters
entityA valid identifier.
Returns
The version of the recycled entity.

Definition at line 608 of file registry.hpp.

◆ destroy() [2/3]

template<typename Entity >
version_type entt::basic_registry< Entity >::destroy ( const entity_type  entity,
const version_type  version 
)
inline

Destroys an entity and releases its identifier.

The suggested version or the valid version closest to the suggested one is used instead of the implicitly generated version.

See also
destroy
Parameters
entityA valid identifier.
versionA desired version upon destruction.
Returns
The version actually assigned to the entity.

Definition at line 624 of file registry.hpp.

◆ destroy() [3/3]

template<typename Entity >
template<typename It >
void entt::basic_registry< Entity >::destroy ( It  first,
It  last 
)
inline

Destroys all entities in a range and releases their identifiers.

See also
destroy
Template Parameters
ItType of input iterator.
Parameters
firstAn iterator to the first element of the range of entities.
lastAn iterator past the last element of the range of entities.

Definition at line 644 of file registry.hpp.

◆ each()

template<typename Entity >
template<typename Func >
void entt::basic_registry< Entity >::each ( Func  func) const
inline

Iterates all the entities that are still in use.

The signature of the function should be equivalent to the following:

void(const Entity);

It's not defined whether entities created during iteration are returned.

Template Parameters
FuncType of the function object to invoke.
Parameters
funcA valid function object.

Definition at line 1028 of file registry.hpp.

◆ emplace()

template<typename Entity >
template<typename Component , typename... Args>
decltype(auto) entt::basic_registry< Entity >::emplace ( const entity_type  entity,
Args &&...  args 
)
inline

Assigns the given component to an entity.

The component must have a proper constructor or be of aggregate type.

Warning
Attempting to use an invalid entity or to assign a component to an entity that already owns it results in undefined behavior.
Template Parameters
ComponentType of component to create.
ArgsTypes of arguments to use to construct the component.
Parameters
entityA valid identifier.
argsParameters to use to initialize the component.
Returns
A reference to the newly created component.

Definition at line 674 of file registry.hpp.

◆ emplace_or_replace()

template<typename Entity >
template<typename Component , typename... Args>
decltype(auto) entt::basic_registry< Entity >::emplace_or_replace ( const entity_type  entity,
Args &&...  args 
)
inline

Assigns or replaces the given component for an entity.

Warning
Attempting to use an invalid entity results in undefined behavior.
Template Parameters
ComponentType of component to assign or replace.
ArgsTypes of arguments to use to construct the component.
Parameters
entityA valid identifier.
argsParameters to use to initialize the component.
Returns
A reference to the newly created component.

Definition at line 727 of file registry.hpp.

◆ empty()

template<typename Entity >
bool entt::basic_registry< Entity >::empty ( ) const
inline

Checks whether the registry is empty (no entities still in use).

Returns
True if the registry is empty, false otherwise.

Definition at line 407 of file registry.hpp.

◆ erase() [1/2]

template<typename Entity >
template<typename Component , typename... Other>
void entt::basic_registry< Entity >::erase ( const entity_type  entity)
inline

Erases the given components from an entity.

Warning
Attempting to use an invalid entity or to erase a component from an entity that doesn't own it results in undefined behavior.
Template Parameters
ComponentTypes of components to erase.
OtherOther types of components to erase.
Parameters
entityA valid identifier.

Definition at line 841 of file registry.hpp.

◆ erase() [2/2]

template<typename Entity >
template<typename Component , typename... Other, typename It >
void entt::basic_registry< Entity >::erase ( It  first,
It  last 
)
inline

Erases the given components from all the entities in a range.

See also
erase
Template Parameters
ComponentTypes of components to erase.
OtherOther types of components to erase.
ItType of input iterator.
Parameters
firstAn iterator to the first element of the range of entities.
lastAn iterator past the last element of the range of entities.

Definition at line 858 of file registry.hpp.

◆ get() [1/2]

template<typename Entity >
template<typename... Component>
decltype(auto) entt::basic_registry< Entity >::get ( [[maybe_unused] ] const entity_type  entity)
inline

Returns references to the given components for an entity.

Warning
Attempting to use an invalid entity or to get a component from an entity that doesn't own it results in undefined behavior.
Template Parameters
ComponentTypes of components to get.
Parameters
entityA valid identifier.
Returns
References to the components owned by the entity.

Definition at line 934 of file registry.hpp.

◆ get() [2/2]

template<typename Entity >
template<typename... Component>
decltype(auto) entt::basic_registry< Entity >::get ( [[maybe_unused] ] const entity_type  entity) const
inline

Returns references to the given components for an entity.

Warning
Attempting to use an invalid entity or to get a component from an entity that doesn't own it results in undefined behavior.
Template Parameters
ComponentTypes of components to get.
Parameters
entityA valid identifier.
Returns
References to the components owned by the entity.

Definition at line 927 of file registry.hpp.

◆ get_or_emplace()

template<typename Entity >
template<typename Component , typename... Args>
decltype(auto) entt::basic_registry< Entity >::get_or_emplace ( const entity_type  entity,
Args &&...  args 
)
inline

Returns a reference to the given component for an entity.

In case the entity doesn't own the component, the parameters provided are used to construct it.

Warning
Attempting to use an invalid entity results in undefined behavior.
Template Parameters
ComponentType of component to get.
ArgsTypes of arguments to use to construct the component.
Parameters
entityA valid identifier.
argsParameters to use to initialize the component.
Returns
Reference to the component owned by the entity.

Definition at line 955 of file registry.hpp.

◆ group() [1/2]

template<typename Entity >
template<typename... Owned, typename... Exclude>
basic_group<Entity, owned_t<Owned...>, get_t<>, exclude_t<Exclude...> > entt::basic_registry< Entity >::group ( exclude_t< Exclude... >  = {})
inline

Returns a group for the given components.

Groups are created on the fly and share with the registry its internal data structures. Feel free to discard them after the use.
Creating and destroying a group is an incredibly cheap operation. As a rule of thumb, storing a group should never be an option.

Groups support exclusion lists and can own types of components. The more types are owned by a group, the faster it is to iterate entities and components.
However, groups also affect some features of the registry such as the creation and destruction of components.

Note
Pools of components that are owned by a group cannot be sorted anymore. The group takes the ownership of the pools and arrange components so as to iterate them as fast as possible.
Template Parameters
OwnedTypes of components owned by the group.
GetTypes of components observed by the group.
ExcludeTypes of components used to filter the group.
Returns
A newly created group.

Definition at line 1314 of file registry.hpp.

◆ group() [2/2]

template<typename Entity >
template<typename... Owned, typename... Get, typename... Exclude>
basic_group<Entity, owned_t<Owned...>, get_t<Get...>, exclude_t<Exclude...> > entt::basic_registry< Entity >::group ( get_t< Get... >  ,
exclude_t< Exclude... >  = {} 
)
inline

Returns a group for the given components.

Groups are created on the fly and share with the registry its internal data structures. Feel free to discard them after the use.
Creating and destroying a group is an incredibly cheap operation. As a rule of thumb, storing a group should never be an option.

Groups support exclusion lists and can own types of components. The more types are owned by a group, the faster it is to iterate entities and components.
However, groups also affect some features of the registry such as the creation and destruction of components.

Note
Pools of components that are owned by a group cannot be sorted anymore. The group takes the ownership of the pools and arrange components so as to iterate them as fast as possible.
Template Parameters
OwnedTypes of components owned by the group.
GetTypes of components observed by the group.
ExcludeTypes of components used to filter the group.
Returns
A newly created group.

Definition at line 1214 of file registry.hpp.

◆ group_if_exists() [1/2]

template<typename Entity >
template<typename... Owned, typename... Exclude>
basic_group<Entity, owned_t<std::add_const_t<Owned>...>, get_t<>, exclude_t<Exclude...> > entt::basic_registry< Entity >::group_if_exists ( exclude_t< Exclude... >  = {}) const
inline

Returns a group for the given components.

Groups are created on the fly and share with the registry its internal data structures. Feel free to discard them after the use.
Creating and destroying a group is an incredibly cheap operation. As a rule of thumb, storing a group should never be an option.

Groups support exclusion lists and can own types of components. The more types are owned by a group, the faster it is to iterate entities and components.
However, groups also affect some features of the registry such as the creation and destruction of components.

Note
Pools of components that are owned by a group cannot be sorted anymore. The group takes the ownership of the pools and arrange components so as to iterate them as fast as possible.
Template Parameters
OwnedTypes of components owned by the group.
GetTypes of components observed by the group.
ExcludeTypes of components used to filter the group.
Returns
A newly created group.

Definition at line 1320 of file registry.hpp.

◆ group_if_exists() [2/2]

template<typename Entity >
template<typename... Owned, typename... Get, typename... Exclude>
basic_group<Entity, owned_t<std::add_const_t<Owned>...>, get_t<std::add_const_t<Get>...>, exclude_t<Exclude...> > entt::basic_registry< Entity >::group_if_exists ( get_t< Get... >  ,
exclude_t< Exclude... >  = {} 
) const
inline

Returns a group for the given components.

Groups are created on the fly and share with the registry its internal data structures. Feel free to discard them after the use.
Creating and destroying a group is an incredibly cheap operation. As a rule of thumb, storing a group should never be an option.

Groups support exclusion lists and can own types of components. The more types are owned by a group, the faster it is to iterate entities and components.
However, groups also affect some features of the registry such as the creation and destruction of components.

Note
Pools of components that are owned by a group cannot be sorted anymore. The group takes the ownership of the pools and arrange components so as to iterate them as fast as possible.
Template Parameters
OwnedTypes of components owned by the group.
GetTypes of components observed by the group.
ExcludeTypes of components used to filter the group.
Returns
A newly created group.

Definition at line 1296 of file registry.hpp.

◆ insert() [1/2]

template<typename Entity >
template<typename Component , typename EIt , typename CIt , typename = std::enable_if_t<std::is_same_v<std::decay_t<typename std::iterator_traits<CIt>::value_type>, Component>>>
void entt::basic_registry< Entity >::insert ( EIt  first,
EIt  last,
CIt  from 
)
inline

Assigns each entity in a range the given components.

See also
emplace
Template Parameters
ComponentType of component to create.
EItType of input iterator.
CItType of input iterator.
Parameters
firstAn iterator to the first element of the range of entities.
lastAn iterator past the last element of the range of entities.
fromAn iterator to the first element of the range of components.

Definition at line 709 of file registry.hpp.

◆ insert() [2/2]

template<typename Entity >
template<typename Component , typename It >
void entt::basic_registry< Entity >::insert ( It  first,
It  last,
const Component &  value = {} 
)
inline

Assigns each entity in a range the given component.

See also
emplace
Template Parameters
ComponentType of component to create.
ItType of input iterator.
Parameters
firstAn iterator to the first element of the range of entities.
lastAn iterator past the last element of the range of entities.
valueAn instance of the component to assign.

Definition at line 691 of file registry.hpp.

◆ on_construct()

template<typename Entity >
template<typename Component >
auto entt::basic_registry< Entity >::on_construct ( )
inline

Returns a sink object for the given component.

Use this function to receive notifications whenever a new instance of the given component is created and assigned to an entity.
The function type for a listener is equivalent to:

void(basic_registry<Entity> &, Entity);

Listeners are invoked after assigning the component to the entity.

See also
sink
Template Parameters
ComponentType of component of which to get the sink.
Returns
A temporary sink object.

Definition at line 1071 of file registry.hpp.

◆ on_destroy()

template<typename Entity >
template<typename Component >
auto entt::basic_registry< Entity >::on_destroy ( )
inline

Returns a sink object for the given component.

Use this function to receive notifications whenever an instance of the given component is removed from an entity and thus destroyed.
The function type for a listener is equivalent to:

void(basic_registry<Entity> &, Entity);

Listeners are invoked before removing the component from the entity.

See also
sink
Template Parameters
ComponentType of component of which to get the sink.
Returns
A temporary sink object.

Definition at line 1117 of file registry.hpp.

◆ on_update()

template<typename Entity >
template<typename Component >
auto entt::basic_registry< Entity >::on_update ( )
inline

Returns a sink object for the given component.

Use this function to receive notifications whenever an instance of the given component is explicitly updated.
The function type for a listener is equivalent to:

void(basic_registry<Entity> &, Entity);

Listeners are invoked after updating the component.

See also
sink
Template Parameters
ComponentType of component of which to get the sink.
Returns
A temporary sink object.

Definition at line 1094 of file registry.hpp.

◆ operator=()

template<typename Entity >
basic_registry& entt::basic_registry< Entity >::operator= ( basic_registry< Entity > &&  other)
inline

Move assignment operator.

Parameters
otherThe instance to move from.
Returns
This registry.

Definition at line 306 of file registry.hpp.

◆ orphan()

template<typename Entity >
bool entt::basic_registry< Entity >::orphan ( const entity_type  entity) const
inline

Checks if an entity has components assigned.

Parameters
entityA valid identifier.
Returns
True if the entity has no components assigned, false otherwise.

Definition at line 1047 of file registry.hpp.

◆ patch()

template<typename Entity >
template<typename Component , typename... Func>
decltype(auto) entt::basic_registry< Entity >::patch ( const entity_type  entity,
Func &&...  func 
)
inline

Patches the given component for an entity.

The signature of the function should be equivalent to the following:

void(Component &);
Note
Empty types aren't explicitly instantiated and therefore they are never returned. However, this function can be used to trigger an update signal for them.
Warning
Attempting to use an invalid entity or to patch a component of an entity that doesn't own it results in undefined behavior.
Template Parameters
ComponentType of component to patch.
FuncTypes of the function objects to invoke.
Parameters
entityA valid identifier.
funcValid function objects.
Returns
A reference to the patched component.

Definition at line 761 of file registry.hpp.

◆ release() [1/3]

template<typename Entity >
version_type entt::basic_registry< Entity >::release ( const entity_type  entity)
inline

Releases an identifier.

The version is updated and the identifier can be recycled at any time.

Warning
Attempting to use an invalid entity results in undefined behavior.
Parameters
entityA valid identifier.
Returns
The version of the recycled entity.

Definition at line 558 of file registry.hpp.

◆ release() [2/3]

template<typename Entity >
version_type entt::basic_registry< Entity >::release ( const entity_type  entity,
const version_type  version 
)
inline

Releases an identifier.

The suggested version or the valid version closest to the suggested one is used instead of the implicitly generated version.

See also
release
Parameters
entityA valid identifier.
versionA desired version upon destruction.
Returns
The version actually assigned to the entity.

Definition at line 574 of file registry.hpp.

◆ release() [3/3]

template<typename Entity >
template<typename It >
void entt::basic_registry< Entity >::release ( It  first,
It  last 
)
inline

Releases all identifiers in a range.

See also
release
Template Parameters
ItType of input iterator.
Parameters
firstAn iterator to the first element of the range of entities.
lastAn iterator past the last element of the range of entities.

Definition at line 589 of file registry.hpp.

◆ released()

template<typename Entity >
entity_type entt::basic_registry< Entity >::released ( ) const
inline

Returns the head of the list of released entities.

This function is intended for use in conjunction with assign.
The returned entity has an invalid identifier in all cases.

Returns
The head of the list of released entities.

Definition at line 435 of file registry.hpp.

◆ remove() [1/2]

template<typename Entity >
template<typename Component , typename... Other>
size_type entt::basic_registry< Entity >::remove ( const entity_type  entity)
inline

Removes the given components from an entity.

Warning
Attempting to use an invalid entity results in undefined behavior.
Template Parameters
ComponentType of component to remove.
OtherOther types of components to remove.
Parameters
entityA valid identifier.
Returns
The number of components actually removed.

Definition at line 799 of file registry.hpp.

◆ remove() [2/2]

template<typename Entity >
template<typename Component , typename... Other, typename It >
size_type entt::basic_registry< Entity >::remove ( It  first,
It  last 
)
inline

Removes the given components from all the entities in a range.

See also
remove
Template Parameters
ComponentTypes of components to remove.
OtherOther types of components to remove.
ItType of input iterator.
Parameters
firstAn iterator to the first element of the range of entities.
lastAn iterator past the last element of the range of entities.
Returns
The number of components actually removed.

Definition at line 817 of file registry.hpp.

◆ replace()

template<typename Entity >
template<typename Component , typename... Args>
decltype(auto) entt::basic_registry< Entity >::replace ( const entity_type  entity,
Args &&...  args 
)
inline

Replaces the given component for an entity.

The component must have a proper constructor or be of aggregate type.

Warning
Attempting to use an invalid entity or to replace a component of an entity that doesn't own it results in undefined behavior.
Template Parameters
ComponentType of component to replace.
ArgsTypes of arguments to use to construct the component.
Parameters
entityA valid identifier.
argsParameters to use to initialize the component.
Returns
A reference to the component being replaced.

Definition at line 782 of file registry.hpp.

◆ reserve()

template<typename Entity >
void entt::basic_registry< Entity >::reserve ( const size_type  cap)
inline

Increases the capacity (number of entities) of the registry.

Parameters
capDesired capacity.

Definition at line 390 of file registry.hpp.

◆ runtime_view()

template<typename Entity >
template<typename ItComp , typename ItExcl = id_type *>
basic_runtime_view<Entity> entt::basic_registry< Entity >::runtime_view ( ItComp  first,
ItComp  last,
ItExcl  from = {},
ItExcl  to = {} 
) const
inline

Returns a runtime view for the given components.

See also
view

Runtime views are to be used when users want to construct a view from some external inputs and don't know at compile-time what are the required components.

Template Parameters
ItCompType of input iterator for the components to use to construct the view.
ItExclType of input iterator for the components to use to filter the view.
Parameters
firstAn iterator to the first element of the range of components to use to construct the view.
lastAn iterator past the last element of the range of components to use to construct the view.
fromAn iterator to the first element of the range of components to use to filter the view.
toAn iterator past the last element of the range of components to use to filter the view.
Returns
A newly created runtime view.

Definition at line 1169 of file registry.hpp.

◆ set()

template<typename Entity >
template<typename Type , typename... Args>
Type& entt::basic_registry< Entity >::set ( Args &&...  args)
inline

Binds an object to the context of the registry.

If the value already exists it is overwritten, otherwise a new instance of the given type is created and initialized with the arguments provided.

Template Parameters
TypeType of object to set.
ArgsTypes of arguments to use to construct the object.
Parameters
argsParameters to use to initialize the value.
Returns
A reference to the newly created object.

Definition at line 1434 of file registry.hpp.

◆ size()

template<typename Entity >
size_type entt::basic_registry< Entity >::size ( ) const
inline

Returns the number of entities created so far.

Returns
Number of entities created so far.

Definition at line 368 of file registry.hpp.

◆ sort() [1/2]

template<typename Entity >
template<typename To , typename From >
void entt::basic_registry< Entity >::sort ( )
inline

Sorts two pools of components in the same way.

Being To and From the two sets, after invoking this function an iterator for To returns elements according to the following rules:

  • All entities in To that are also in From are returned first according to the order they have in From.
  • All entities in To that are not in From are returned in no particular order after all the other entities.

Any subsequent change to From won't affect the order in To.

Warning
Pools of components owned by a group cannot be sorted.
Template Parameters
ToType of components to sort.
FromType of components to use to sort.

Definition at line 1417 of file registry.hpp.

◆ sort() [2/2]

template<typename Entity >
template<typename Component , typename Compare , typename Sort = std_sort, typename... Args>
void entt::basic_registry< Entity >::sort ( Compare  compare,
Sort  algo = Sort{},
Args &&...  args 
)
inline

Sorts the elements of a given component.

The order remains valid until a component of the given type is assigned to or removed from an entity.
The comparison function object returns true if the first element is less than the second one, false otherwise. Its signature is also equivalent to one of the following:

bool(const Entity, const Entity);
bool(const Component &, const Component &);

Moreover, it shall induce a strict weak ordering on the values.
The sort function object offers an operator() that accepts:

  • An iterator to the first element of the range to sort.
  • An iterator past the last element of the range to sort.
  • A comparison function object to use to compare the elements.

The comparison function object hasn't necessarily the type of the one passed along with the other parameters to this member function.

Warning
Pools of components owned by a group cannot be sorted.
Template Parameters
ComponentType of components to sort.
CompareType of comparison function object.
SortType of sort function object.
ArgsTypes of arguments to forward to the sort function object.
Parameters
compareA valid comparison function object.
algoA valid sort function object.
argsArguments to forward to the sort function object, if any.

Definition at line 1385 of file registry.hpp.

◆ sortable() [1/2]

template<typename Entity >
template<typename... Component>
bool entt::basic_registry< Entity >::sortable ( ) const
inline

Checks whether the given components belong to any group.

Template Parameters
ComponentTypes of components in which one is interested.
Returns
True if the pools of the given components are sortable, false otherwise.

Definition at line 1331 of file registry.hpp.

◆ sortable() [2/2]

template<typename Entity >
template<typename... Owned, typename... Get, typename... Exclude>
bool entt::basic_registry< Entity >::sortable ( const basic_group< Entity, owned_t< Owned... >, get_t< Get... >, exclude_t< Exclude... >> &  )
inline

Checks whether a group can be sorted.

Template Parameters
OwnedTypes of components owned by the group.
GetTypes of components observed by the group.
ExcludeTypes of components used to filter the group.
Returns
True if the group can be sorted, false otherwise.

Definition at line 1343 of file registry.hpp.

◆ storage() [1/4]

template<typename Entity >
auto entt::basic_registry< Entity >::storage ( )
inline

Returns an iterable object to use to visit a registry.

The iterable object returns a pair that contains the name and a reference to the current storage.

Returns
An iterable object to use to visit the registry.

Definition at line 328 of file registry.hpp.

◆ storage() [2/4]

template<typename Entity >
auto entt::basic_registry< Entity >::storage ( ) const
inline

Returns an iterable object to use to visit a registry.

The iterable object returns a pair that contains the name and a reference to the current storage.

Returns
An iterable object to use to visit the registry.

Definition at line 333 of file registry.hpp.

◆ storage() [3/4]

template<typename Entity >
template<typename Component >
decltype(auto) entt::basic_registry< Entity >::storage ( const id_type  id = type_hash<Component>::value())
inline

Returns the storage for a given component type.

Template Parameters
ComponentType of component of which to return the storage.
Parameters
idOptional name used to map the storage for a given component.
Returns
The storage for the given component type.

Definition at line 344 of file registry.hpp.

◆ storage() [4/4]

template<typename Entity >
template<typename Component >
decltype(auto) entt::basic_registry< Entity >::storage ( const id_type  id = type_hash<Component>::value()) const
inline

Returns an iterable object to use to visit a registry.

Warning
If a storage for the given component doesn't exist yet, a temporary placeholder is returned instead.
Template Parameters
ComponentType of component of which to return the storage.
Parameters
idOptional name used to map the storage for a given component.
Returns
The storage for the given component type.

Definition at line 360 of file registry.hpp.

◆ try_ctx() [1/2]

template<typename Entity >
template<typename Type >
Type* entt::basic_registry< Entity >::try_ctx ( )
inline

Returns a pointer to an object in the context of the registry.

Template Parameters
TypeType of object to get.
Returns
A pointer to the object if it exists in the context of the registry, a null pointer otherwise.

Definition at line 1480 of file registry.hpp.

◆ try_ctx() [2/2]

template<typename Entity >
template<typename Type >
std::add_const_t<Type>* entt::basic_registry< Entity >::try_ctx ( ) const
inline

Returns a pointer to an object in the context of the registry.

Template Parameters
TypeType of object to get.
Returns
A pointer to the object if it exists in the context of the registry, a null pointer otherwise.

Definition at line 1473 of file registry.hpp.

◆ try_get() [1/2]

template<typename Entity >
template<typename... Component>
auto entt::basic_registry< Entity >::try_get ( [[maybe_unused] ] const entity_type  entity)
inline

Returns pointers to the given components for an entity.

Warning
Attempting to use an invalid entity results in undefined behavior.
Note
The registry retains ownership of the pointed-to components.
Template Parameters
ComponentTypes of components to get.
Parameters
entityA valid identifier.
Returns
Pointers to the components owned by the entity.

Definition at line 988 of file registry.hpp.

◆ try_get() [2/2]

template<typename Entity >
template<typename... Component>
auto entt::basic_registry< Entity >::try_get ( [[maybe_unused] ] const entity_type  entity) const
inline

Returns pointers to the given components for an entity.

Warning
Attempting to use an invalid entity results in undefined behavior.
Note
The registry retains ownership of the pointed-to components.
Template Parameters
ComponentTypes of components to get.
Parameters
entityA valid identifier.
Returns
Pointers to the components owned by the entity.

Definition at line 975 of file registry.hpp.

◆ unset()

template<typename Entity >
template<typename Type >
void entt::basic_registry< Entity >::unset ( )
inline

Unsets a context variable if it exists.

Template Parameters
TypeType of object to set.

Definition at line 1445 of file registry.hpp.

◆ valid()

template<typename Entity >
bool entt::basic_registry< Entity >::valid ( const entity_type  entity) const
inline

Checks if an identifier refers to a valid entity.

Parameters
entityAn identifier, either valid or not.
Returns
True if the identifier is valid, false otherwise.

Definition at line 444 of file registry.hpp.

◆ view() [1/2]

template<typename Entity >
template<typename Component , typename... Other, typename... Exclude>
basic_view<Entity, get_t<Component, Other...>, exclude_t<Exclude...> > entt::basic_registry< Entity >::view ( exclude_t< Exclude... >  = {})
inline

Returns a view for the given components.

Views are created on the fly and share with the registry its internal data structures. Feel free to discard them after the use.
Creating and destroying a view is an incredibly cheap operation. As a rule of thumb, storing a view should never be an option.

Template Parameters
ComponentType of component used to construct the view.
OtherOther types of components used to construct the view.
ExcludeTypes of components used to filter the view.
Returns
A newly created view.

Definition at line 1141 of file registry.hpp.

◆ view() [2/2]

template<typename Entity >
template<typename Component , typename... Other, typename... Exclude>
basic_view<Entity, get_t<std::add_const_t<Component>, std::add_const_t<Other>...>, exclude_t<Exclude...> > entt::basic_registry< Entity >::view ( exclude_t< Exclude... >  = {}) const
inline

Returns a view for the given components.

Views are created on the fly and share with the registry its internal data structures. Feel free to discard them after the use.
Creating and destroying a view is an incredibly cheap operation. As a rule of thumb, storing a view should never be an option.

Template Parameters
ComponentType of component used to construct the view.
OtherOther types of components used to construct the view.
ExcludeTypes of components used to filter the view.
Returns
A newly created view.

Definition at line 1135 of file registry.hpp.


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