Class entity_view

Synopsis

#include <include/flecs/cpp/entity.hpp>

class entity_view : public id

Description

Entity view class This class provides readonly access to entities. Using this class to store entities in components ensures valid handles, as this class will always store the actual world vs. a stage. The constructors of this class will never create a new entity.

To obtain a mutable handle to the entity, use the "mut" function.

Inheritance

Ancestors: id

Decsendents: entity

Methods

entity_view overloadWrap an existing entity id.
entity_view overloadImplicit conversion from flecs::entity_t to flecs::entity_view.
childrenReturn iterator to entity children
delta_timeGet current delta time
each overloadIterate contents (type) of an entity.
each overloadIterate contents (type) of an entity for a specific relationship.
enabled
get overloadGet component value.
get overloadGet component value (untyped).
get overloadGet a pair
get overloadGet a pair (untyped)
get_case overloadGet case for switch.
get_objectGet the object part from a pair
get_parent overloadGet parent from an entity
has overloadCheck if entity has the provided type.
has overloadCheck if entity has the provided entity.
has overloadCheck if entity has the provided component.
has overloadCheck if entity has the provided pair.
has_case overloadCheck if entity has the provided case.
has_objectCheck if entity has the provided pair.
has_switchCheck if entity has the provided switch.
idGet entity id.
is_aliveCheck is entity is alive.
is_enabled overloadTest if component is enabled.
is_validCheck is entity is valid.
lookupLookup an entity by name
mut overloadReturn mutable entity handle for current stage When an entity handle created from the world is used while the world is in staged mode, it will only allow for readonly operations since structural changes are not allowed on the world while in staged mode.
mut overloadSame as mut(world), but for iterator
mut overloadSame as mut(world), but for entity
nameReturn the entity name.
null overloadEntity id 0
operator bool
operator!=Inequality operator.
operator==Equality operator.
owns overloadCheck if entity owns the provided type
owns overloadCheck if entity owns the provided entity
owns overloadCheck if entity owns the provided component
pathReturn the entity path.
to_typeReturn type containing the entity.
typeReturn the type.
worldReturn the world.

Source

Lines 146-621 in include/flecs/cpp/entity.hpp.

class entity_view : public id {
public:
    explicit entity_view() : flecs::id() { }

    /** Wrap an existing entity id.
     *
     * @param world The world in which the entity is created.
     * @param id The entity id.
     */
    explicit entity_view(const flecs::world& world, const entity_view& id)
        : flecs::id( world.get_world(), 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_view(world_t *world, const entity_view& id) 
        : flecs::id( flecs::world(world).get_world(), id.id() ) { }

    /** Implicit conversion from flecs::entity_t to flecs::entity_view. */
    entity_view(entity_t id) 
        : flecs::id( nullptr, id ) { }

    /** Equality operator. */
    bool operator==(const entity_view& e) {
        return this->id() == e.id();
    }  

    /** Inequality operator. */
    bool operator!=(const entity_view& e) {
        return this->id() != e.id();
    }            

    explicit operator bool() {
        return m_id != 0;
    }

    /** Entity id 0.
     * This function is useful when the API must provide an entity object that
     * belongs to a world, but the entity id is 0.
     *
     * @param world The world.
     */
    static
    flecs::entity_view null(const flecs::world& world) {
        return flecs::entity_view(world.get_world().c_ptr(), static_cast<entity_t>(0));
    }

    static
    flecs::entity_view null() {
        return flecs::entity_view(static_cast<entity_t>(0));
    }

    /** Get entity id.
     * @return The integer entity id.
     */
    entity_t id() const {
        return m_id;
    }

    /** Check is entity is valid.
     *
     * @return True if the entity is alive, false otherwise.
     */
    bool is_valid() {
        return ecs_is_valid(m_world, m_id);
    }

    /** Check is entity is alive.
     *
     * @return True if the entity is alive, false otherwise.
     */
    bool is_alive() {
        return ecs_is_alive(m_world, m_id);
    }

    /** Return the entity name.
     *
     * @return The entity name, or an empty string if the entity has no name.
     */
    flecs::string_view name() const {
        const EcsName *name = static_cast<const EcsName*>(
            ecs_get_w_entity(m_world, m_id, static_cast<ecs_entity_t>(ecs_id(EcsName))));
        return flecs::string_view(name ? name->value : nullptr);
    }

    /** Return the entity path.
     *
     * @return The hierarchical entity path, or an empty string if the entity 
     *         has no name.
     */
    flecs::string path(const char *sep = "::", const char *init_sep = "::") const {
        char *path = ecs_get_path_w_sep(m_world, 0, m_id, 0, sep, init_sep);
        return flecs::string(path);
    }   

    bool enabled() {
        return !ecs_has_entity(m_world, m_id, flecs::Disabled);
    }

    /** Return the world.
     *
     * @return The world the entity is stored in.
     */
    flecs::world world() const {
        return flecs::world(m_world);
    }

    /** Return the type.
     *
     * @return Returns the entity type.
     */
    flecs::type type() const;

    /** Return type containing the entity.
     *
     * @return A type that contains only this entity.
     */
    flecs::type to_type() const;

    /** Iterate contents (type) of an entity.
     */
    template <typename Func>
    void each(const Func& func) const;

    /** Iterate contents (type) of an entity for a specific relationship.
     */
    template <typename Func>
    void each(const flecs::entity_view& rel, const Func& func) const;

    /** Iterate contents (type) of an entity for a specific relationship.
     */
    template <typename Rel, typename Func>
    void each(const Func& func) const { 
        return each(_::cpp_type<Rel>::id(m_world), func);
    }

    /** Get component value.
     * 
     * @tparam T The component to get.
     * @return Pointer to the component value, nullptr if the entity does not
     *         have the component.
     */
    template <typename T>
    const T* get() const {
        auto comp_id = _::cpp_type<T>::id(m_world);
        ecs_assert(_::cpp_type<T>::size() != 0, ECS_INVALID_PARAMETER, NULL);
        return static_cast<const T*>(
            ecs_get_w_entity(m_world, m_id, comp_id));
    }

    /** Get component value (untyped).
     * 
     * @param component The component to get.
     * @return Pointer to the component value, nullptr if the entity does not
     *         have the component.
     */
    const void* get(const flecs::entity_view& component) const {
        return ecs_get_w_entity(m_world, m_id, component.id());
    }

    /** Get 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>
    const Relation* get() const {
        return this->get<Relation>(_::cpp_type<Object>::id(m_world));
    }

    /** Get 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>
    const Relation* get(const flecs::entity_view& object) const {
        auto comp_id = _::cpp_type<Relation>::id(m_world);
        ecs_assert(_::cpp_type<Relation>::size() != 0, ECS_INVALID_PARAMETER, NULL);
        return static_cast<const Relation*>(
            ecs_get_w_entity(m_world, m_id, ecs_pair(comp_id, object.id())));
    }

    /** Get a pair (untyped).
     * This operation gets the value for a pair from the entity. If neither the
     * relation nor the object part of the pair are components, the operation 
     * will fail.
     *
     * @param relation the relation.
     * @param object the object.
     */
    const void* get(const flecs::entity_view& relation, const flecs::entity_view& object) const {
        return ecs_get_w_entity(m_world, m_id, ecs_pair(relation.id(), object.id()));
    }

    /** Get the object part from a pair.
     * This operation gets the value for a pair from the entity. The relation
     * part of the pair should not be a component.
     *
     * @tparam Object the object type.
     * @param relation the relation.
     */
    template<typename Object>
    const Object* get_object(const flecs::entity_view& relation) const {
        auto comp_id = _::cpp_type<Object>::id(m_world);
        ecs_assert(_::cpp_type<Object>::size() != 0, ECS_INVALID_PARAMETER, NULL);
        return static_cast<const Object*>(
            ecs_get_w_entity(m_world, m_id, ecs_pair(relation.id(), comp_id)));
    }

    /** Get parent from an entity.
     * This operation retrieves the parent entity that has the specified 
     * component. If no parent with the specified component is found, an entity
     * with id 0 is returned. If multiple parents have the specified component,
     * the operation returns the first encountered one.
     *
     * @tparam T The component for which to find the parent.
     * @return The parent entity.
     */
    template <typename T>
    flecs::entity_view get_parent() {
        return flecs::entity_view(m_world, ecs_get_parent_w_entity(m_world, m_id, 
            _::cpp_type<T>::id(m_world)));
    }

    flecs::entity_view get_parent(flecs::entity_view e) {
        return flecs::entity_view(m_world, ecs_get_parent_w_entity(m_world, m_id, e.id()));
    }    

    /** Lookup an entity by name.
     * Lookup an entity in the scope of this entity. The provided path may
     * contain double colons as scope separators, for example: "Foo::Bar".
     *
     * @param path The name of the entity to lookup.
     * @return The found entity, or entity::null if no entity matched.
     */
    flecs::entity_view lookup(const char *path) const {
        auto id = ecs_lookup_path_w_sep(m_world, m_id, path, "::", "::");
        return flecs::entity_view(m_world, id);
    }

    /** Check if entity has the provided type.
     *
     * @param entity The type pointer to check.
     * @return True if the entity has the provided type, false otherwise.
     */
    bool has(type_t type) const {
        return ecs_has_type(m_world, m_id, type);
    }

    /** Check if entity has the provided entity.
     *
     * @param entity The entity to check.
     * @return True if the entity has the provided entity, false otherwise.
     */
    bool has(const flecs::entity_view& e) const {
        return ecs_has_entity(m_world, m_id, e.id());
    }     

    /** Check if entity has the provided component.
     *
     * @tparam T The component to check.
     * @return True if the entity has the provided component, false otherwise.
     */
    template <typename T>
    bool has() const {
        return ecs_has_entity(m_world, m_id, _::cpp_type<T>::id(m_world));
    }

    /** Check if entity has the provided pair.
     *
     * @tparam Relation The relation type.
     * @param Object The object type.
     * @return True if the entity has the provided component, false otherwise.
     */
    template <typename Relation, typename Object>
    bool has() const {
        return this->has<Relation>(_::cpp_type<Object>::id(m_world));
    }

    /** Check if entity has the provided pair.
     *
     * @tparam Relation The relation type.
     * @param object The object.
     * @return True if the entity has the provided component, false otherwise.
     */
    template <typename Relation>
    bool has(const flecs::entity_view& object) const {
        auto comp_id = _::cpp_type<Relation>::id(m_world);
        ecs_assert(_::cpp_type<Relation>::size() != 0, 
            ECS_INVALID_PARAMETER, NULL);
        return ecs_has_entity(m_world, m_id, 
            ecs_pair(comp_id, object.id()));
    }

    /** Check if entity has the provided pair.
     *
     * @param relation The relation.
     * @param object The object.
     * @return True if the entity has the provided component, false otherwise.
     */
    bool has(const flecs::entity_view& relation, const flecs::entity_view& object) const {
        return ecs_has_entity(m_world, m_id, 
            ecs_pair(relation.id(), object.id()));
    }

    /** Check if entity has the provided pair.
     *
     * @tparam Object The object type.
     * @param relation The relation.
     * @return True if the entity has the provided component, false otherwise.
     */
    template <typename Object>
    bool has_object(const flecs::entity_view& relation) const {
        auto comp_id = _::cpp_type<Object>::id(m_world);
        ecs_assert(_::cpp_type<Object>::size() != 0, 
            ECS_INVALID_PARAMETER, NULL);
        return ecs_has_entity(m_world, m_id, 
            ecs_pair(relation.id(), comp_id));
    }

    /** Check if entity owns the provided type.
     * An type is owned if it is not shared from a base entity.
     *
     * @param type The type to check.
     * @return True if the entity owns the provided type, false otherwise.
     */
    bool owns(type_t type) const {
        return ecs_type_owns_type(
            m_world, ecs_get_type(m_world, m_id), type, true);
    }

    /** Check if entity owns the provided entity.
     * An entity is owned if it is not shared from a base entity.
     *
     * @param entity The entity to check.
     * @return True if the entity owns the provided entity, false otherwise.
     */
    bool owns(const flecs::entity_view& e) const {
        return ecs_owns_entity(m_world, m_id, e.id(), true);
    }

    /** Check if entity owns the provided component.
     * An component is owned if it is not shared from a base entity.
     *
     * @tparam T The component to check.
     * @return True if the entity owns the provided component, false otherwise.
     */
    template <typename T>
    bool owns() const {
        return owns(_::cpp_type<T>::id(m_world));
    }

    /** Check if entity has the provided switch.
     *
     * @param sw The switch to check.
     * @return True if the entity has the provided switch, false otherwise.
     */
    bool has_switch(const flecs::type& sw) const;

    /** Check if entity has the provided case.
     *
     * @param sw_case The case to check.
     * @return True if the entity has the provided case, false otherwise.
     */
    bool has_case(const flecs::entity_view& sw_case) const {
        return ecs_has_entity(m_world, m_id, flecs::Case | sw_case.id());
    }

    template<typename T>
    bool has_case() const {
        return this->has_case(_::cpp_type<T>::id(m_world));
    }

    /** Get case for switch.
     *
     * @param sw The switch for which to obtain the case.
     * @return True if the entity has the provided case, false otherwise.
     */
    flecs::entity_view get_case(const flecs::type& sw) const;

    /** Get case for switch.
     *
     * @param sw The switch for which to obtain the case.
     * @return True if the entity has the provided case, false otherwise.
     */
    flecs::entity_view get_case(const flecs::entity_view& sw) const {
        return flecs::entity_view(m_world, ecs_get_case(m_world, m_id, sw.id()));
    }

    /** Test if component is enabled.
     *
     * @tparam T The component to test.
     * @return True if the component is enabled, false if it has been disabled.
     */
    template<typename T>
    bool is_enabled() {
        return ecs_is_component_enabled_w_entity(
            m_world, m_id, _::cpp_type<T>::id(m_world));
    }

    /** Test if component is enabled.
     *
     * @param entity The component to test.
     * @return True if the component is enabled, false if it has been disabled.
     */
    bool is_enabled(const flecs::entity_view& e) {
        return ecs_is_component_enabled_w_entity(
            m_world, m_id, e.id());
    }

    /** Get current delta time.
     * Convenience function so system implementations can get delta_time, even
     * if they are using the .each() function.
     *
     * @return Current delta_time.
     */
    FLECS_FLOAT delta_time() const {
        const ecs_world_info_t *stats = ecs_get_world_info(m_world);
        return stats->delta_time;
    }

    /** Return iterator to entity children.
     * Enables depth-first iteration over entity children.
     *
     * @return Iterator to child entities.
     */
    child_iterator children() const;

    /** Return mutable entity handle for current stage 
     * When an entity handle created from the world is used while the world is
     * in staged mode, it will only allow for readonly operations since 
     * structural changes are not allowed on the world while in staged mode.
     * 
     * To do mutations on the entity, this operation provides a handle to the
     * entity that uses the stage instead of the actual world.
     *
     * Note that staged entity handles should never be stored persistently, in
     * components or elsewhere. An entity handle should always point to the
     * main world.
     *
     * Also note that this operation is not necessary when doing mutations on an
     * entity outside of a system. It is allowed to do entity operations 
     * directly on the world, as long as the world is not in staged mode.
     *
     * @param stage The current stage.
     * @return An entity handle that allows for mutations in the current stage.
     */
    flecs::entity mut(const flecs::world& stage) const;

    /** Same as mut(world), but for iterator.
     * This operation allows for the construction of a mutable entity handle
     * from an iterator.
     *
     * @param stage An created for the current stage.
     * @return An entity handle that allows for mutations in the current stage.
     */
    flecs::entity mut(const flecs::iter& it) const;

    /** Same as mut(world), but for entity.
     * This operation allows for the construction of a mutable entity handle
     * from another entity. This is useful in each() functions, which only 
     * provide a handle to the entity being iterated over.
     *
     * @param stage An created for the current stage.
     * @return An entity handle that allows for mutations in the current stage.
     */
    flecs::entity mut(const flecs::entity_view& e) const;

private:
    flecs::entity set_stage(world_t *stage);
};