Class entity
Synopsis
#include <include/flecs/cpp/entity.hpp>
class entity :
public entity_view,
public entity_builder<entity>,
public entity_deprecated<entity>,
public entity_builder_deprecated<entity>
Description
Entity class This class provides access to entities.
Mentioned in
- Readme / Example
- FAQ / When to use each vs. iter when evaluating a query or system?
- FAQ / Why can I create queries and systems both as template parameters and as strings?
- Quickstart / Queries
- Manual / Modules in C++
- Manual / Traits as entity relationships
Inheritance
Ancestors: entity_view, entity_builder, entity_deprecated, entity_builder_deprecated
Decsendents: prefab
Methods
entity overload | Default constructor. | |
entity overload | Create entity. | |
entity overload | Create a named entity | |
entity overload | Wrap an existing entity id. | |
entity overload | Implicit conversion from flecs::entity_t to flecs::entity. | |
clear | Clear an entity | |
destruct | Delete an entity | |
get_mut overload | Get mutable component value | |
get_mut overload | Get mutable component value (untyped) | |
get_mut overload | Get mutable pointer for a pair | |
get_mut overload | Get mutable pointer for a pair (untyped) | |
get_mut_object | Get mutable pointer for the object from a pair | |
get_ref | Get reference to component | |
id | Get entity id. | |
invoke | Used by builder class | |
modified overload | Signal that component was modified. | |
modified overload | Signal that the relation part of a pair was modified. | |
modified overload | Signal that a pair has modified (untyped) | |
world | Return the world. |
Source
Lines 1150-1431 in include/flecs/cpp/entity.hpp.
class entity :
public entity_view,
public entity_builder<entity>,
public entity_deprecated<entity>,
public entity_builder_deprecated<entity>
{
public:
/** Default constructor.
*/
explicit entity()
: flecs::entity_view() { }
/** Create entity.
*
* @param world The world in which to create the entity.
*/
explicit entity(const flecs::world& world)
: flecs::entity_view()
{
m_world = world.c_ptr();
m_id = ecs_new_w_type(world.c_ptr(), 0);
}
/** Create a named entity.
* Named entities can be looked up with the lookup functions. Entity names
* may be scoped, where each element in the name is separated by "::".
* For example: "Foo::Bar". If parts of the hierarchy in the scoped name do
* not yet exist, they will be automatically created.
*
* @param world The world in which to create the entity.
* @param name The entity name.
* @param is_component If true, the entity will be created from the pool of component ids (default = false).
*/
explicit entity(const flecs::world& world, const char *name, bool is_component = false)
: flecs::entity_view()
{
m_world = world.c_ptr();
m_id = ecs_lookup_path_w_sep(m_world, 0, name, "::", "::");
if (!m_id) {
if (is_component) {
m_id = ecs_new_component_id(m_world);
}
m_id = ecs_add_path_w_sep(
world.c_ptr(), m_id, 0, name, "::", "::");
}
}
/** Wrap an existing entity id.
*
* @param world The world in which the entity is created.
* @param id The entity id.
*/
explicit entity(const flecs::world& world, const entity& id)
: flecs::entity_view()
{
m_world = world.c_ptr();
m_id = id.id();
}
/** Wrap an existing entity id.
*
* @param world Pointer to the world in which the entity is created.
* @param id The entity id.
*/
explicit entity(world_t *world, const entity& id)
: flecs::entity_view()
{
m_world = world;
m_id = id.id();
}
/** Implicit conversion from flecs::entity_t to flecs::entity. */
entity(entity_t id)
: flecs::entity_view( nullptr, id ) { }
/** Get entity id.
* @return The integer entity id.
*/
entity_t id() const {
return m_id;
}
/** Return the world.
*
* @return The world the entity is stored in.
*/
flecs::world world() const {
return flecs::world(m_world);
}
/** Get mutable component value.
* This operation returns a mutable pointer to the component. If the entity
* did not yet have the component, it will be added. If a base entity had
* the component, it will be overridden, and the value of the base component
* will be copied to the entity before this function returns.
*
* @tparam T The component to get.
* @param is_added If provided, this parameter will be set to true if the component was added.
* @return Pointer to the component value.
*/
template <typename T>
T* get_mut(bool *is_added = nullptr) const {
auto comp_id = _::cpp_type<T>::id(m_world);
ecs_assert(_::cpp_type<T>::size() != 0, ECS_INVALID_PARAMETER, NULL);
return static_cast<T*>(
ecs_get_mut_w_entity(m_world, m_id, comp_id, is_added));
}
/** Get mutable component value (untyped).
* This operation returns a mutable pointer to the component. If the entity
* did not yet have the component, it will be added. If a base entity had
* the component, it will be overridden, and the value of the base component
* will be copied to the entity before this function returns.
*
* @param component The component to get.
* @param is_added If provided, this parameter will be set to true if the component was added.
* @return Pointer to the component value.
*/
void* get_mut(flecs::entity component, bool *is_added = nullptr) const {
return ecs_get_mut_w_entity(m_world, m_id, component.id(), is_added);
}
/** Get mutable component value (untyped).
* This operation returns a mutable pointer to the component. If the entity
* did not yet have the component, it will be added. If a base entity had
* the component, it will be overridden, and the value of the base component
* will be copied to the entity before this function returns.
*
* @param component The id of the component to get.
* @param is_added If provided, this parameter will be set to true if the component was added.
* @return Pointer to the component value.
*/
void* get_mut(entity_t component_id, bool *is_added = nullptr) const {
return ecs_get_mut_w_entity(m_world, m_id, component_id, is_added);
}
/** Get mutable pointer for a pair.
* This operation gets the value for a pair from the entity.
*
* @tparam Relation the relation type.
* @tparam Object the object type.
*/
template <typename Relation, typename Object>
Relation* get_mut(bool *is_added = nullptr) const {
return this->get_mut<Relation>(
_::cpp_type<Object>::id(m_world), is_added);
}
/** Get mutable pointer for a pair.
* This operation gets the value for a pair from the entity.
*
* @tparam Relation the relation type.
* @param object the object.
*/
template <typename Relation>
Relation* get_mut(const flecs::entity& object, bool *is_added = nullptr) const {
auto comp_id = _::cpp_type<Relation>::id(m_world);
ecs_assert(_::cpp_type<Relation>::size() != 0, ECS_INVALID_PARAMETER, NULL);
return static_cast<Relation*>(
ecs_get_mut_w_entity(m_world, m_id,
ecs_pair(comp_id, object.id()), is_added));
}
/** Get mutable pointer for a pair (untyped).
* This operation gets the value for a pair from the entity. If neither the
* relation or object are a component, the operation will fail.
*
* @param relation the relation.
* @param object the object.
*/
void* get_mut(const flecs::entity& relation, const flecs::entity& object, bool *is_added = nullptr) const {
return ecs_get_mut_w_entity(m_world, m_id,
ecs_pair(relation.id(), object.id()), is_added);
}
/** Get mutable pointer for the object from a pair.
* This operation gets the value for a pair from the entity.
*
* @tparam Object the object type.
* @param relation the relation.
*/
template <typename Object>
Object* get_mut_object(const flecs::entity& relation, bool *is_added = nullptr) const {
auto comp_id = _::cpp_type<Object>::id(m_world);
ecs_assert(_::cpp_type<Object>::size() != 0, ECS_INVALID_PARAMETER, NULL);
return static_cast<Object*>(
ecs_get_mut_w_entity(m_world, m_id,
ecs_pair(relation.id(), comp_id), is_added));
}
/** Signal that component was modified.
*
* @tparam T component that was modified.
*/
template <typename T>
void modified() const {
auto comp_id = _::cpp_type<T>::id(m_world);
ecs_assert(_::cpp_type<T>::size() != 0, ECS_INVALID_PARAMETER, NULL);
ecs_modified_w_entity(m_world, m_id, comp_id);
}
/** Signal that component was modified.
*
* @param component component that was modified.
*/
void modified(const flecs::entity& component) const {
ecs_modified_w_entity(m_world, m_id, component.id());
}
/** Signal that the relation part of a pair was modified.
*
* @tparam Relation the relation type.
* @tparam Object the object type.
*/
template <typename Relation, typename Object>
void modified() const {
this->modified<Relation>(_::cpp_type<Object>::id(m_world));
}
/** Signal that the relation part of a pair was modified.
*
* @tparam Relation the relation type.
* @param object the object.
*/
template <typename Relation>
void modified(const flecs::entity& object) const {
auto comp_id = _::cpp_type<Relation>::id(m_world);
ecs_assert(_::cpp_type<Relation>::size() != 0, ECS_INVALID_PARAMETER, NULL);
ecs_modified_w_entity(m_world, m_id, ecs_pair(comp_id, object.id()));
}
/** Signal that a pair has modified (untyped).
* If neither the relation or object part of the pair are a component, the
* operation will fail.
*
* @param relation the relation.
* @param object the object.
*/
void modified(const flecs::entity& relation, const flecs::entity& object) const {
ecs_modified_w_entity(m_world, m_id,
ecs_pair(relation.id(), object.id()));
}
/** Get reference to component.
* A reference allows for quick and safe access to a component value, and is
* a faster alternative to repeatedly calling 'get' for the same component.
*
* @tparam T component for which to get a reference.
* @return The reference.
*/
template <typename T>
ref<T> get_ref() const {
// Ensure component is registered
_::cpp_type<T>::id(m_world);
ecs_assert(_::cpp_type<T>::size() != 0, ECS_INVALID_PARAMETER, NULL);
return ref<T>(m_world, m_id);
}
/** Clear an entity.
* This operation removes all components from an entity without recycling
* the entity id.
*/
void clear() const {
ecs_clear(m_world, m_id);
}
/** Delete an entity.
* Entities have to be deleted explicitly, and are not deleted when the
* flecs::entity object goes out of scope.
*/
void destruct() const {
ecs_delete(m_world, m_id);
}
/** Used by builder class. Do not invoke (deprecated). */
template <typename Func>
void invoke(Func&& action) const {
action(m_world, m_id);
}
};