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);
    }
};