EnTT  3.6.0
Classes | Public Types | Public Member Functions | Static 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 traits_type::version_type
 Underlying version type.
 
using size_type = std::size_t
 Unsigned integer type.
 
using poly_storage = typename poly_storage_traits< Entity >::storage_type
 Poly storage type.
 

Public Member Functions

 basic_registry ()=default
 Default constructor.
 
 basic_registry (basic_registry &&)=default
 Default move constructor.
 
basic_registryoperator= (basic_registry &&)=default
 Default move assignment operator. More...
 
template<typename Component >
void prepare ()
 Prepares a pool for the given type if required. More...
 
poly_storage storage (const type_info info)
 Returns a poly storage for a given type. More...
 
poly_storage storage (const type_info info) const
 Returns a poly storage for a given type. More...
 
template<typename Component >
size_type size () const
 Returns the number of existing components of the given type. More...
 
size_type size () const noexcept
 Returns the number of entities created so far. More...
 
size_type alive () const
 Returns the number of entities still in use. More...
 
template<typename... Component>
void reserve (const size_type cap)
 Increases the capacity of the registry or of the pools for the given components. More...
 
void reserve_pools (const size_t count)
 Reserves enough space to store count pools. More...
 
template<typename Component >
size_type capacity () const
 Returns the capacity of the pool for the given component. More...
 
size_type capacity () const noexcept
 Returns the number of entities that a registry has currently allocated space for. More...
 
template<typename... Component>
void shrink_to_fit ()
 Requests the removal of unused capacity for the given components. More...
 
template<typename... Component>
bool empty () const
 Checks whether the registry or the pools of the given components are empty. More...
 
template<typename Component >
const Component * raw () const
 Direct access to the list of components of a given pool. More...
 
template<typename Component >
Component * raw ()
 Direct access to the list of components of a given pool. More...
 
template<typename Component >
const entity_typedata () const
 Direct access to the list of entities of a given pool. More...
 
const entity_typedata () const noexcept
 Direct access to the list of entities of a registry. More...
 
entity_type destroyed () const noexcept
 Returns the head of the list of destroyed entities. More...
 
bool valid (const entity_type entity) const
 Checks if an entity identifier refers to a valid entity. More...
 
version_type current (const entity_type entity) const
 Returns the actual version for an entity identifier. More...
 
entity_type create ()
 Creates a new entity and returns it. More...
 
entity_type create (const entity_type hint)
 Creates a new entity and returns it. More...
 
template<typename It >
void create (It first, It last)
 Assigns each element in a range an entity. More...
 
template<typename It >
void assign (It first, It last, const entity_type destroyed)
 Assigns entities to an empty registry. More...
 
void destroy (const entity_type entity)
 Destroys an entity. More...
 
void destroy (const entity_type entity, const version_type version)
 Destroys an entity. More...
 
template<typename It >
void destroy (It first, It last)
 Destroys all the entities in a range. 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 >
void insert (EIt first, EIt last, CIt from, CIt to)
 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>
void remove (const entity_type entity)
 Removes the given components from an entity. More...
 
template<typename... Component, typename It >
void remove (It first, It last)
 Removes the given components from all the entities in a range. More...
 
template<typename... Component>
size_type remove_if_exists (const entity_type entity)
 Removes the given components from an entity. More...
 
void remove_all (const entity_type entity)
 Removes all the components from an entity and makes it orphaned. More...
 
template<typename... Component>
bool has (const entity_type entity) const
 Checks if an entity has all the given components. More...
 
template<typename... Component>
bool any (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 Func >
void orphans (Func func) const
 Iterates orphans and applies them the given function object. 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... Exclude>
basic_view< Entity, exclude_t< Exclude... >, Component... > view (exclude_t< Exclude... >={}) const
 Returns a view for the given components. More...
 
template<typename... Component, typename... Exclude>
basic_view< Entity, exclude_t< Exclude... >, Component... > 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, exclude_t< Exclude... >, get_t< Get... >, Owned... > 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, exclude_t< Exclude... >, get_t< Get... >, Owned... > 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, exclude_t< Exclude... >, get_t<>, Owned... > group (exclude_t< Exclude... >={})
 Returns a group for the given components. More...
 
template<typename... Owned, typename... Exclude>
basic_group< Entity, exclude_t< Exclude... >, get_t<>, Owned... > 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, exclude_t< Exclude... >, get_t< Get... >, Owned... > &) noexcept
 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 pool of entities for the given component. More...
 
template<typename To , typename From >
void sort ()
 Sorts two pools of components in the same way. More...
 
template<typename Func >
void visit (entity_type entity, Func func) const
 Visits an entity and returns the type info for its components. More...
 
template<typename Func >
void visit (Func func) const
 Visits a registry and returns the type info for its components. 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 >
const 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 >
const 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...
 

Static Public Member Functions

static entity_type entity (const entity_type entity) noexcept
 Returns the entity identifier without the version. More...
 
static version_type version (const entity_type entity) noexcept
 Returns the version stored along with an entity identifier. More...
 

Detailed Description

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

Fast and reliable entity-component system.

The registry is the core class of the entity-component framework.
It stores entities and arranges pools of components on a per request basis. By means of a registry, users can manage entities and components, then create views or groups to iterate them.

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

Definition at line 44 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 221 of file registry.hpp.

◆ any()

template<typename Entity >
template<typename... Component>
bool entt::basic_registry< Entity >::any ( 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 entity identifier.
Returns
True if the entity has at least one of the given components, false otherwise.

Definition at line 828 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 entities to an empty registry.

This function is intended for use in conjunction with raw and assign.
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
All pools must be empty 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 520 of file registry.hpp.

◆ capacity() [1/2]

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

Returns the capacity of the pool for the given component.

Template Parameters
ComponentType of component in which one is interested.
Returns
Capacity of the pool of the given component.

Definition at line 268 of file registry.hpp.

◆ capacity() [2/2]

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

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

Returns
Capacity of the registry.

Definition at line 278 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 939 of file registry.hpp.

◆ create() [1/3]

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

Creates a new entity and returns it.

There are two kinds of possible entity identifiers:

  • Newly created ones in case no entities have been previously destroyed.
  • Recycled ones with updated versions.
Returns
A valid entity identifier.

Definition at line 443 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 and returns it.

See also
create

If the requested entity isn't in use, the suggested identifier is created and returned. Otherwise, a new one will be generated for this purpose.

Parameters
hintA desired entity identifier.
Returns
A valid entity identifier.

Definition at line 458 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 entity.

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 492 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 1612 of file registry.hpp.

◆ ctx() [2/3]

template<typename Entity >
template<typename Type >
const 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 1604 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
Warning
It's not specified whether a context variable created during the visit is returned or not to the caller.
Template Parameters
FuncType of the function object to invoke.
Parameters
funcA valid function object.

Definition at line 1638 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 1570 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 entity identifier.

Warning
Attempting to use an entity that doesn't belong to the registry results in undefined behavior. An entity belongs to the registry even if it has been previously destroyed and/or recycled.
Parameters
entityA valid entity identifier.
Returns
Actual version for the given entity identifier.

Definition at line 427 of file registry.hpp.

◆ data() [1/2]

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

Direct access to the list of entities of a given pool.

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

Entities are in the reverse order as imposed by the sorting functionalities.

Template Parameters
ComponentType of component in which one is interested.
Returns
A pointer to the array of entities.

Definition at line 355 of file registry.hpp.

◆ data() [2/2]

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

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 container 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 372 of file registry.hpp.

◆ destroy() [1/3]

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

Destroys an entity.

When an entity is destroyed, its version is updated and the identifier can be recycled at any time.

See also
remove_all
Parameters
entityA valid entity identifier.

Definition at line 536 of file registry.hpp.

◆ destroy() [2/3]

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

Destroys an entity.

If the entity isn't already destroyed, the suggested version is used instead of the implicitly generated one.

See also
remove_all
Parameters
entityA valid entity identifier.
versionA desired version upon destruction.

Definition at line 551 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 the entities in a range.

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 566 of file registry.hpp.

◆ destroyed()

template<typename Entity >
entity_type entt::basic_registry< Entity >::destroyed ( ) const
inlinenoexcept

Returns the head of the list of destroyed 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 destroyed entities.

Definition at line 384 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 function object is invoked for each entity that is still in use.
The signature of the function should be equivalent to the following:

void(const Entity);

This function is fairly slow and should not be used frequently. However, it's useful for iterating all the entities still in use, regardless of their components.

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

Definition at line 977 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.

A new instance of the given component is created and initialized with the arguments provided (the component must have a proper constructor or be of aggregate type). Then the component is assigned to the given entity.

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 entity identifier.
argsParameters to use to initialize the component.
Returns
A reference to the newly created component.

Definition at line 590 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.

Equivalent to the following snippet (pseudocode):

auto &component = registry.has<Component>(entity) ? registry.replace<Component>(entity, args...) : registry.emplace<Component>(entity, args...);

Prefer this function anyway because it has slightly better performance.

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 entity identifier.
argsParameters to use to initialize the component.
Returns
A reference to the newly created component.

Definition at line 653 of file registry.hpp.

◆ empty()

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

Checks whether the registry or the pools of the given components are empty.

A registry is considered empty when it doesn't contain entities that are still in use.

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

Definition at line 304 of file registry.hpp.

◆ entity()

template<typename Entity >
static entity_type entt::basic_registry< Entity >::entity ( const entity_type  entity)
inlinestaticnoexcept

Returns the entity identifier without the version.

Parameters
entityAn entity identifier, either valid or not.
Returns
The entity identifier without the version.

Definition at line 403 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 entity identifier.
Returns
References to the components owned by the entity.

Definition at line 857 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 entity identifier.
Returns
References to the components owned by the entity.

Definition at line 845 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.
Equivalent to the following snippet (pseudocode):

auto &component = registry.has<Component>(entity) ? registry.get<Component>(entity) : registry.emplace<Component>(entity, args...);

Prefer this function anyway because it has slightly better performance.

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 entity identifier.
argsParameters to use to initialize the component.
Returns
Reference to the component owned by the entity.

Definition at line 890 of file registry.hpp.

◆ group() [1/2]

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

Returns a group for the given components.

See also
group
Template Parameters
OwnedTypes of components owned by the group.
ExcludeTypes of components used to filter the group.
Returns
A newly created group.

Definition at line 1336 of file registry.hpp.

◆ group() [2/2]

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

Returns a group for the given components.

This kind of objects are created on the fly and share with the registry its internal data structures.
Feel free to discard a group after the use. Creating and destroying a group is an incredibly cheap operation because they do not require any type of initialization, but for the first time they are requested.
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, which will consequently be slightly slower (nothing that can be noticed in most cases).

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 1219 of file registry.hpp.

◆ group_if_exists() [1/2]

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

Returns a group for the given components.

See also
group_if_exists
Template Parameters
OwnedTypes of components owned by the group.
ExcludeTypes of components used to filter the group.
Returns
A newly created group.

Definition at line 1350 of file registry.hpp.

◆ group_if_exists() [2/2]

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

Returns a group for the given components.

See also
group
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 1309 of file registry.hpp.

◆ has()

template<typename Entity >
template<typename... Component>
bool entt::basic_registry< Entity >::has ( 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 entity identifier.
Returns
True if the entity has all the components, false otherwise.

Definition at line 811 of file registry.hpp.

◆ insert() [1/2]

template<typename Entity >
template<typename Component , typename EIt , typename CIt >
void entt::basic_registry< Entity >::insert ( EIt  first,
EIt  last,
CIt  from,
CIt  to 
)
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.
toAn iterator past the last element of the range of components.

Definition at line 626 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 607 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.

The sink returned by this function can be used 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 the component has been assigned 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 1047 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.

The sink returned by this function can be used 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 the component has been removed 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 1095 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.

The sink returned by this function can be used 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 the component has been updated.

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

Definition at line 1070 of file registry.hpp.

◆ operator=()

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

Default move assignment operator.

Returns
This registry.

◆ 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 entity identifier.
Returns
True if the entity has no components assigned, false otherwise.

Definition at line 996 of file registry.hpp.

◆ orphans()

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

Iterates orphans and applies them the given function object.

The function object is invoked for each entity that is still in use and has no components assigned.
The signature of the function should be equivalent to the following:

void(const Entity);

This function can be very slow and should not be used frequently.

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

Definition at line 1018 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 functions 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 entity identifier.
funcValid function objects.
Returns
A reference to the patched component.

Definition at line 687 of file registry.hpp.

◆ prepare()

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

Prepares a pool for the given type if required.

Template Parameters
ComponentType of component for which to prepare a pool.

Definition at line 177 of file registry.hpp.

◆ raw() [1/2]

template<typename Entity >
template<typename Component >
Component* entt::basic_registry< Entity >::raw ( )
inline

Direct access to the list of components of a given pool.

The returned pointer is such that range [raw<Component>(), raw<Component>() + size<Component>()) is always a valid range, even if the container is empty.

Components are in the reverse order as imposed by the sorting functionalities.

Note
Empty components aren't explicitly instantiated. Therefore, this function isn't available for them. A compilation error will occur if invoked.
Template Parameters
ComponentType of component in which one is interested.
Returns
A pointer to the array of components of the given type.

Definition at line 337 of file registry.hpp.

◆ raw() [2/2]

template<typename Entity >
template<typename Component >
const Component* entt::basic_registry< Entity >::raw ( ) const
inline

Direct access to the list of components of a given pool.

The returned pointer is such that range [raw<Component>(), raw<Component>() + size<Component>()) is always a valid range, even if the container is empty.

Components are in the reverse order as imposed by the sorting functionalities.

Note
Empty components aren't explicitly instantiated. Therefore, this function isn't available for them. A compilation error will occur if invoked.
Template Parameters
ComponentType of component in which one is interested.
Returns
A pointer to the array of components of the given type.

Definition at line 330 of file registry.hpp.

◆ remove() [1/2]

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

Removes the given components from an entity.

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

Definition at line 725 of file registry.hpp.

◆ remove() [2/2]

template<typename Entity >
template<typename... Component, typename It >
void 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.
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 742 of file registry.hpp.

◆ remove_all()

template<typename Entity >
void entt::basic_registry< Entity >::remove_all ( const entity_type  entity)
inline

Removes all the components from an entity and makes it orphaned.

Warning
In case there are listeners that observe the destruction of components and assign other components to the entity in their bodies, the result of invoking this function may not be as expected. In the worst case, it could lead to undefined behavior.
Attempting to use an invalid entity results in undefined behavior.
Parameters
entityA valid entity identifier.

Definition at line 789 of file registry.hpp.

◆ remove_if_exists()

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

Removes the given components from an entity.

Equivalent to the following snippet (pseudocode):

if(registry.has<Component>(entity)) { registry.remove<Component>(entity) }

Prefer this function anyway because it has slightly better performance.

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

Definition at line 767 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.

A new instance of the given component is created and initialized with the arguments provided (the component must have a proper constructor or be of aggregate type). Then the component is assigned to the given entity.

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 entity identifier.
argsParameters to use to initialize the component.
Returns
A reference to the component being replaced.

Definition at line 710 of file registry.hpp.

◆ reserve()

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

Increases the capacity of the registry or of the pools for the given components.

If no components are specified, the capacity of the registry is increased, that is the number of entities it contains. Otherwise the capacity of the pools for the given components is increased.
In both cases, if the new capacity is greater than the current capacity, new storage is allocated, otherwise the method does nothing.

Template Parameters
ComponentTypes of components for which to reserve storage.
Parameters
capDesired capacity.

Definition at line 246 of file registry.hpp.

◆ reserve_pools()

template<typename Entity >
void entt::basic_registry< Entity >::reserve_pools ( const size_t  count)
inline

Reserves enough space to store count pools.

Parameters
countNumber of pools to reserve space for.

Definition at line 258 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.

This kind of objects are created on the fly and share with the registry its internal data structures.
Users should throw away the view after use. Fortunately, creating and destroying a runtime view is an incredibly cheap operation because they do not require any type of initialization.
As a rule of thumb, storing a view should never be an option.

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 1174 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 1541 of file registry.hpp.

◆ shrink_to_fit()

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

Requests the removal of unused capacity for the given components.

Template Parameters
ComponentTypes of components for which to reclaim unused capacity.

Definition at line 288 of file registry.hpp.

◆ size() [1/2]

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

Returns the number of existing components of the given type.

Template Parameters
ComponentType of component of which to return the size.
Returns
Number of existing components of the given type.

Definition at line 204 of file registry.hpp.

◆ size() [2/2]

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

Returns the number of entities created so far.

Returns
Number of entities created so far.

Definition at line 213 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.

The order of the elements in a pool is highly affected by assignments of components to entities and deletions. Components are arranged to maximize the performance during iterations and users should not make any assumption on the order.

It happens that different pools of components must be sorted the same way because of runtime and/or performance constraints. This function can be used to order a pool of components according to the order between the entities in another pool of components.

How it works

Being A and B the two sets where B is the master (the one the order of which rules) and A is the slave (the one to sort), after a call to this function an iterator for A will return the entities according to the following rules:

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

Any subsequent change to B won't affect the order in A.

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 1465 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 pool of entities for the given component.

The order of the elements in a pool is highly affected by assignments of components to entities and deletions. Components are arranged to maximize the performance during iterations and users should not make any assumption on the order.
This function can be used to impose an order to the elements in the pool of the given component. The order is kept valid until a component of the given type is assigned or removed from an entity.

The comparison function object must return true if the first element is less than the second one, false otherwise. The signature of the comparison function should be equivalent to one of the following:

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

Moreover, the comparison function object shall induce a strict weak ordering on the values.

The sort function oject must offer a member function template operator() that accepts three arguments:

  • 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 to use to compare the elements.

The comparison funtion object received by the sort 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 1426 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 1361 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, exclude_t< Exclude... >, get_t< Get... >, Owned... > &  )
inlinenoexcept

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 1373 of file registry.hpp.

◆ storage() [1/2]

template<typename Entity >
poly_storage entt::basic_registry< Entity >::storage ( const type_info  info)
inline

Returns a poly storage for a given type.

Parameters
infoThe type for which to return a poly storage.
Returns
A valid poly storage if a pool for the given type exists, an empty and thus invalid element otherwise.

Definition at line 188 of file registry.hpp.

◆ storage() [2/2]

template<typename Entity >
poly_storage entt::basic_registry< Entity >::storage ( const type_info  info) const
inline

Returns a poly storage for a given type.

Parameters
infoThe type for which to return a poly storage.
Returns
A valid poly storage if a pool for the given type exists, an empty and thus invalid element otherwise.

Definition at line 193 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 1589 of file registry.hpp.

◆ try_ctx() [2/2]

template<typename Entity >
template<typename Type >
const 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 1582 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 entity identifier.
Returns
Pointers to the components owned by the entity.

Definition at line 923 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 entity identifier.
Returns
Pointers to the components owned by the entity.

Definition at line 910 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 1552 of file registry.hpp.

◆ valid()

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

Checks if an entity identifier refers to a valid entity.

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

Definition at line 393 of file registry.hpp.

◆ version()

template<typename Entity >
static version_type entt::basic_registry< Entity >::version ( const entity_type  entity)
inlinestaticnoexcept

Returns the version stored along with an entity identifier.

Parameters
entityAn entity identifier, either valid or not.
Returns
The version stored along with the given entity identifier.

Definition at line 412 of file registry.hpp.

◆ view() [1/2]

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

Returns a view for the given components.

This kind of objects are created on the fly and share with the registry its internal data structures.
Feel free to discard a view after the use. Creating and destroying a view is an incredibly cheap operation because they do not require any type of initialization.
As a rule of thumb, storing a view should never be an option.

Views do their best to iterate the smallest set of candidate entities. In particular:

  • Single component views are incredibly fast and iterate a packed array of entities, all of which has the given component.
  • Multi component views look at the number of entities available for each component and pick up a reference to the smallest set of candidates to test for the given components.

Views in no way affect the functionalities of the registry nor those of the underlying pools.

Note
Multi component views are pretty fast. However their performance tend to degenerate when the number of components to iterate grows up and the most of the entities have all the given components.
To get a performance boost, consider using a group instead.
Template Parameters
ComponentType of components used to construct the view.
ExcludeTypes of components used to filter the view.
Returns
A newly created view.

Definition at line 1140 of file registry.hpp.

◆ view() [2/2]

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

Returns a view for the given components.

This kind of objects are created on the fly and share with the registry its internal data structures.
Feel free to discard a view after the use. Creating and destroying a view is an incredibly cheap operation because they do not require any type of initialization.
As a rule of thumb, storing a view should never be an option.

Views do their best to iterate the smallest set of candidate entities. In particular:

  • Single component views are incredibly fast and iterate a packed array of entities, all of which has the given component.
  • Multi component views look at the number of entities available for each component and pick up a reference to the smallest set of candidates to test for the given components.

Views in no way affect the functionalities of the registry nor those of the underlying pools.

Note
Multi component views are pretty fast. However their performance tend to degenerate when the number of components to iterate grows up and the most of the entities have all the given components.
To get a performance boost, consider using a group instead.
Template Parameters
ComponentType of components used to construct the view.
ExcludeTypes of components used to filter the view.
Returns
A newly created view.

Definition at line 1132 of file registry.hpp.

◆ visit() [1/2]

template<typename Entity >
template<typename Func >
void entt::basic_registry< Entity >::visit ( entity_type  entity,
Func  func 
) const
inline

Visits an entity and returns the type info for its components.

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

void(const type_info);

Returned identifiers are those of the components owned by the entity.

See also
type_info
Warning
It's not specified whether a component attached to or removed from the given entity during the visit is returned or not to the caller.
Template Parameters
FuncType of the function object to invoke.
Parameters
entityA valid entity identifier.
funcA valid function object.

Definition at line 1492 of file registry.hpp.

◆ visit() [2/2]

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

Visits a registry and returns the type info for its components.

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

void(const type_info);

Returned identifiers are those of the components managed by the registry.

See also
type_info
Warning
It's not specified whether a component for which a pool is created during the visit is returned or not to the caller.
Template Parameters
FuncType of the function object to invoke.
Parameters
funcA valid function object.

Definition at line 1521 of file registry.hpp.


The documentation for this class was generated from the following files:
entt::basic_registry::entity
static entity_type entity(const entity_type entity) noexcept
Returns the entity identifier without the version.
Definition: registry.hpp:403
entt::registry
basic_registry< entity > registry
Alias declaration for the most common use case.
Definition: fwd.hpp:76