Class entity_builder

Synopsis

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

template <typename Base>
class entity_builder : public entity_builder_base<entity_builder_tag, Base>

Description

No description yet.

Inheritance

Ancestors: entity_builder_base

Methods

add overloadAdd a component to an entity
add overloadAdd an entity to an entity
add overloadAdd a pair
add_case overloadAdd a switch to an entity by id
add_switch overloadAdd a switch to an entity by id
add_switch overloadAdd a switch to an entity by C++ type
add_switch overloadAdd a switch to an entity
add_w_objectAdd a pair with object type
child_of overloadShortcut for add(ChildOf
componentAssociate entity with type
disable overloadDisable an entity
disable overloadDisable a component
emplaceEmplace component
enable overloadEnable an entity
enable overloadEnable a component
is_a overloadShortcut for add(IsA
override overloadAdd owned flag for component (forces ownership when instantiating)
remove overloadRemove a component from an entity.
remove overloadRemove an entity from an entity.
remove overloadRemove a pair
remove overloadRemoves a pair
remove_case overloadRemove a case from an entity by id
remove_case overloadRemove a switch from an entity by id
remove_switch overloadRemove a switch from an entity by id.
remove_switch overloadAdd a switch to an entity by C++ type
remove_switch overloadRemove a switch from an entity
remove_w_objectRemoves a pair with object type
scopeThe function will be ran with the scope set to the current entity.
set overloadSet a pair for an entity
set overloadSet 1..N components
set_name
set_overrideSet value, add owned flag.
set_ptr overload
set_w_object overloadSet a pair for an entity
with overloadEntities created in function will have the current entity.
with overloadEntities created in function will have (Relation, this) This operation is thread safe.
with overloadEntities created in function will have (relation, this)

Source

Lines 43-608 in include/flecs/addons/cpp/entity.hpp.

template <typename Base>
class entity_builder : public entity_builder_base<entity_builder_tag, Base> {
public:
    /** Add a component to an entity.
     * To ensure the component is initialized, it should have a constructor.
     * 
     * @tparam T the component type to add.
     */
    template <typename T>
    const Base& add() const {
        flecs_static_assert(is_flecs_constructible<T>::value,
            "cannot default construct type: add T::T() or use emplace<T>()");
        ecs_add_id(this->base_world(), this->base_id(), _::cpp_type<T>::id(this->base_world()));
        return *this;
    }

    /** Add an entity to an entity.
     * Add an entity to the entity. This is typically used for tagging.
     *
     * @param entity The entity to add.
     */
    const Base& add(entity_t entity) const {
        ecs_add_id(this->base_world(), this->base_id(), entity);
        return *this;
    }

    /** Add a pair.
     * This operation adds a pair to the entity.
     *
     * @param relation The relation id.
     * @param object The object id.
     */
    const Base& add(entity_t relation, entity_t object) const {
        ecs_add_pair(this->base_world(), this->base_id(), relation, object);
        return *this;
    }

    /** Add a pair.
     * This operation adds a pair to the entity.
     *
     * @tparam R the relation type.
     * @tparam O the object type.
     */
    template<typename R, typename O>
    const Base& add() const {
        return this->add<R>(_::cpp_type<O>::id(this->base_world()));
    }

    /** Add a pair.
     * This operation adds a pair to the entity.
     *
     * @tparam R the relation type.
     * @param object the object type.
     */
    template<typename R>
    const Base& add(entity_t object) const {
        flecs_static_assert(is_flecs_constructible<R>::value,
            "cannot default construct type: add T::T() or use emplace<T>()");      
        return this->add(_::cpp_type<R>::id(this->base_world()), object);
    }

    /** Shortcut for add(IsA. obj).
     *
     * @param object the object id.
     */
    const Base& is_a(entity_t object) const {
        return this->add(flecs::IsA, object);
    }

    template <typename T>
    const Base& is_a() const {
        return this->add(flecs::IsA, _::cpp_type<T>::id(this->base_world()));
    }

    /** Shortcut for add(ChildOf. obj).
     *
     * @param object the object id.
     */
    const Base& child_of(entity_t object) const {
        return this->add(flecs::ChildOf, object);
    }

    /** Shortcut for add(ChildOf. obj).
     *
     * @param object the object id.
     */
    template <typename T>
    const Base& child_of() const {
        return this->add(flecs::ChildOf, _::cpp_type<T>::id(this->base_world()));
    }

    /** Add a pair with object type.
     * This operation adds a pair to the entity. The relation part of the pair
     * should not be a component.
     *
     * @param relation the relation type.
     * @tparam O the object type.
     */
    template<typename O>
    const Base& add_w_object(entity_t relation) const {
        flecs_static_assert(is_flecs_constructible<O>::value,
            "cannot default construct type: add T::T() or use emplace<T>()");      
        return this->add(relation,  _::cpp_type<O>::id(this->base_world()));
    }

    /** Remove a component from an entity.
     *
     * @tparam T the type of the component to remove.
     */
    template <typename T>
    const Base& remove() const {
        ecs_remove_id(this->base_world(), this->base_id(), _::cpp_type<T>::id(this->base_world()));
        return *this;
    }

    /** Remove an entity from an entity.
     *
     * @param entity The entity to remove.
     */
    const Base& remove(entity_t entity) const {
        ecs_remove_id(this->base_world(), this->base_id(), entity);
        return *this;
    }

    /** Remove a pair.
     * This operation removes a pair from the entity.
     *
     * @param relation The relation id.
     * @param object The object id.
     */
    const Base& remove(entity_t relation, entity_t object) const {
        ecs_remove_pair(this->base_world(), this->base_id(), relation, object);
        return *this;
    }

    /** Removes a pair.
     * This operation removes a pair from the entity.
     *
     * @tparam Relation the relation type.
     * @tparam Object the object type.
     */
    template<typename Relation, typename Object>
    const Base& remove() const {
        return this->remove<Relation>(_::cpp_type<Object>::id(this->base_world()));
    }

    /** Remove a pair.
     * This operation adds a pair to the entity.
     *
     * @tparam Relation the relation type.
     * @param object the object type.
     */
    template<typename Relation>
    const Base& remove(entity_t object) const {
        return this->remove(_::cpp_type<Relation>::id(this->base_world()), object);
    }  

    /** Removes a pair with object type.
     * This operation removes a pair from the entity.
     *
     * @param relation the relation type.
     * @tparam Object the object type.
     */
    template<typename Object>
    const Base& remove_w_object(entity_t relation) const {
        return this->remove(relation, _::cpp_type<Object>::id(this->base_world()));
    }    

    /** Add owned flag for component (forces ownership when instantiating)
     *
     * @param entity The entity for which to add the OVERRIDE flag
     */    
    const Base& override(entity_t entity) const {
        ecs_add_id(this->base_world(), this->base_id(), ECS_OVERRIDE | entity);
        return *this;  
    }

    /** Add owned flag for component (forces ownership when instantiating)
     *
     * @tparam T The component for which to add the OVERRIDE flag
     */    
    template <typename T>
    const Base& override() const {
        ecs_add_id(this->base_world(), this->base_id(), ECS_OVERRIDE | _::cpp_type<T>::id(this->base_world()));
        return *this;  
    }

    /** Set value, add owned flag.
     *
     * @tparam T The component to set and for which to add the OVERRIDE flag
     */    
    template <typename T>
    const Base& set_override(T&& val) const {
        this->override<T>();
        this->set<T>(std::forward<T>(val));
        return *this;  
    }    

    /** Add a switch to an entity by id.
     * The switch entity must be a type, that is it must have the EcsType
     * component. Entities created with flecs::type are valid here.
     *
     * @param sw The switch entity id to add.
     */    
    const Base& add_switch(entity_t sw) const {
        ecs_add_id(this->base_world(), this->base_id(), ECS_SWITCH | sw);
        return *this;  
    }

    /** Add a switch to an entity by C++ type.
     * The C++ type must be associated with a switch type.
     *
     * @param sw The switch to add.
     */ 
    template <typename T>
    const Base& add_switch() const {
        ecs_add_id(this->base_world(), this->base_id(), 
            ECS_SWITCH | _::cpp_type<T>::id());
        return *this;  
    }

    /** Add a switch to an entity.
     * Any instance of flecs::type can be used as a switch.
     *
     * @param sw The switch to add.
     */     
    const Base& add_switch(const type& sw) const;

    /** Remove a switch from an entity by id.
     *
     * @param sw The switch entity id to remove.
     */    
    const Base& remove_switch(entity_t sw) const {
        ecs_remove_id(this->base_world(), this->base_id(), ECS_SWITCH | sw);
        return *this;  
    }

    /** Add a switch to an entity by C++ type.
     * The C++ type must be associated with a switch type.
     *
     * @param sw The switch to add.
     */ 
    template <typename T>
    const Base& remove_switch() const {
        ecs_remove_id(this->base_world(), this->base_id(), 
            ECS_SWITCH | _::cpp_type<T>::id());
        return *this;  
    }

    /** Remove a switch from an entity.
     * Any instance of flecs::type can be used as a switch.
     *
     * @param sw The switch to remove.
     */      
    const Base& remove_switch(const type& sw) const;

    /** Add a switch to an entity by id.
     * The case must belong to a switch that is already added to the entity.
     *
     * @param sw_case The case entity id to add.
     */    
    const Base& add_case(entity_t sw_case) const {
        ecs_add_id(this->base_world(), this->base_id(), ECS_CASE | sw_case);
        return *this;
    }

    /** Add a switch to an entity by id.
     * The case must belong to a switch that is already added to the entity.
     *
     * @tparam T The case to add.
     */   
    template<typename T>
    const Base& add_case() const {
        return this->add_case(_::cpp_type<T>::id());
    }

    /** Remove a case from an entity by id.
     * The case must belong to a switch that is already added to the entity.
     *
     * @param sw_case The case entity id to remove.
     */    
    const Base& remove_case(entity_t sw_case) const {
        ecs_remove_id(this->base_world(), this->base_id(), ECS_CASE | sw_case);
        return *this;  
    }

    /** Remove a switch from an entity by id.
     * The case must belong to a switch that is already added to the entity.
     *
     * @tparam T The case to remove.
     */   
    template<typename T>
    const Base& remove_case() const {
        return this->remove_case(_::cpp_type<T>::id());
    }

    /** Enable an entity.
     * Enabled entities are matched with systems and can be searched with
     * queries.
     */
    const Base& enable() const {
        ecs_enable(this->base_world(), this->base_id(), true);
        return *this;
    }

    /** Disable an entity.
     * Disabled entities are not matched with systems and cannot be searched 
     * with queries, unless explicitly specified in the query expression.
     */
    const Base& disable() const {
        ecs_enable(this->base_world(), this->base_id(), false);
        return *this;
    }

    /** Enable a component.
     * This sets the enabled bit for this component. If this is the first time
     * the component is enabled or disabled, the bitset is added.
     *
     * @tparam T The component to enable.
     */   
    template<typename T>
    const Base& enable() const {
        ecs_enable_component_w_id(this->base_world(), this->base_id(), _::cpp_type<T>::id(), true);
        return *this;
    }  

    /** Disable a component.
     * This sets the enabled bit for this component. If this is the first time
     * the component is enabled or disabled, the bitset is added.
     *
     * @tparam T The component to enable.
     */   
    template<typename T>
    const Base& disable() const {
        ecs_enable_component_w_id(this->base_world(), this->base_id(), _::cpp_type<T>::id(), false);
        return *this;
    }  

    /** Enable a component.
     * See enable<T>.
     *
     * @param component The component to enable.
     */   
    const Base& enable(entity_t comp) const {
        ecs_enable_component_w_id(this->base_world(), this->base_id(), comp, true);
        return *this;       
    }

    /** Disable a component.
     * See disable<T>.
     *
     * @param component The component to disable.
     */   
    const Base& disable(entity_t comp) const {
        ecs_enable_component_w_id(this->base_world(), this->base_id(), comp, false);
        return *this;       
    }

    const Base& set_ptr(entity_t comp, size_t size, const void *ptr) {
        ecs_set_id(this->base_world(), this->base_id(), comp, size, ptr);
        return *this;
    }

    const Base& set_ptr(entity_t comp, const void *ptr) {
        const flecs::Component *cptr = ecs_get(
            this->base_world(), comp, EcsComponent);

        /* Can't set if it's not a component */
        ecs_assert(cptr != NULL, ECS_INVALID_PARAMETER, NULL);

        return set_ptr(comp, cptr->size, ptr);
    }

    template<typename T, if_t< 
        !is_callable<T>::value && is_actual<T>::value> = 0 >
    const Base& set(T&& value) const {
        flecs::set<T>(this->base_world(), this->base_id(), std::forward<T&&>(value));
        return *this;
    }

    template<typename T, if_t< 
        !is_callable<T>::value && is_actual<T>::value > = 0>
    const Base& set(const T& value) const {
        flecs::set<T>(this->base_world(), this->base_id(), value);
        return *this;
    }

    template<typename T, typename A = actual_type_t<T>, if_not_t< 
        is_callable<T>::value || is_actual<T>::value > = 0>
    const Base& set(A&& value) const {
        flecs::set<T>(this->base_world(), this->base_id(), std::forward<A&&>(value));
        return *this;
    }

    template<typename T, typename A = actual_type_t<T>, if_not_t<
        is_callable<T>::value || is_actual<T>::value > = 0>
    const Base& set(const A& value) const {
        flecs::set<T>(this->base_world(), this->base_id(), value);
        return *this;
    }

    /** Set a pair for an entity.
     * This operation sets the pair value, and uses the relation as type. If the
     * entity did not yet have the pair, it will be added.
     *
     * @tparam R The relation part of the pair.
     * @tparam O The object part of the pair.
     * @param value The value to set.
     */
    template <typename R, typename O, typename P = pair<R, O>, 
        typename A = actual_type_t<P>, if_not_t< is_pair<R>::value> = 0>
    const Base& set(const A& value) const {
        flecs::set<P>(this->base_world(), this->base_id(), value);
        return *this;
    }

    /** Set a pair for an entity.
     * This operation sets the pair value, and uses the relation as type. If the
     * entity did not yet have the pair, it will be added.
     *
     * @tparam R The relation part of the pair.
     * @param object The object part of the pair.
     * @param value The value to set.
     */
    template <typename R>
    const Base& set(entity_t object, const R& value) const {
        auto relation = _::cpp_type<R>::id(this->base_world());
        flecs::set(this->base_world(), this->base_id(), value, 
            ecs_pair(relation, object));
        return *this;
    }

    /** Set a pair for an entity.
     * This operation sets the pair value, and uses the relation as type. If the
     * entity did not yet have the pair, it will be added.
     *
     * @tparam Object The object part of the pair.
     * @param relation The relation part of the pair.
     * @param value The value to set.
     */
    template <typename O>
    const Base& set_w_object(entity_t relation, const O& value) const {
        auto object = _::cpp_type<O>::id(this->base_world());
        flecs::set(this->base_world(), this->base_id(), value, 
            ecs_pair(relation, object));
        return *this;
    }

    template <typename R, typename O>
    const Base& set_w_object(const O& value) const {
        flecs::set<pair_object<R, O>>(this->base_world(), this->base_id(), value);
        return *this;
    }    

    /** Set 1..N components.
     * This operation accepts a callback with as arguments the components to
     * set. If the entity does not have all of the provided components, they
     * will be added.
     *
     * This operation is faster than individually calling get for each component
     * as it only obtains entity metadata once. When this operation is called
     * while deferred, its performance is equivalent to that of calling get_mut
     * for each component separately.
     *
     * The operation will invoke modified for each component after the callback
     * has been invoked.
     *
     * @param func The callback to invoke.
     */
    template <typename Func, if_t< is_callable<Func>::value > = 0>
    const Base& set(const Func& func) const;

    /** Emplace component.
     * Emplace constructs a component in the storage, which prevents calling the
     * destructor on the object passed into the function.
     *
     * Emplace attempts the following signatures to construct the component:
     *  T{Args...}
     *  T{flecs::entity, Args...}
     *
     * If the second signature matches, emplace will pass in the current entity 
     * as argument to the constructor, which is useful if the component needs
     * to be aware of the entity to which it has been added.
     *
     * Emplace may only be called for components that have not yet been added
     * to the entity.
     *
     * @tparam T the component to emplace
     * @param args The arguments to pass to the constructor of T
     */
    template <typename T, typename ... Args>
    const Base& emplace(Args&&... args) const {
        flecs::emplace<T>(this->base_world(), this->base_id(), 
            std::forward<Args>(args)...);
        return *this;
    }

    /** Entities created in function will have the current entity.
     *
     * @param func The function to call.
     */
    template <typename Func>
    const Base& with(const Func& func) const {
        ecs_id_t prev = ecs_set_with(this->base_world(), this->base_id());
        func();
        ecs_set_with(this->base_world(), prev);
        return *this;
    }

    /** Entities created in function will have (Relation, this) 
     * This operation is thread safe.
     *
     * @tparam Relation The relation to use.
     * @param func The function to call.
     */
    template <typename Relation, typename Func>
    const Base& with(const Func& func) const {
        with(_::cpp_type<Relation>::id(this->base_world()), func);
        return *this;
    }  

    /** Entities created in function will have (relation, this) 
     *
     * @param relation The relation to use.
     * @param func The function to call.
     */
    template <typename Func>
    const Base& with(id_t relation, const Func& func) const {
        ecs_id_t prev = ecs_set_with(this->base_world(), 
            ecs_pair(relation, this->base_id()));
        func();
        ecs_set_with(this->base_world(), prev);
        return *this;
    }

    /** The function will be ran with the scope set to the current entity. */
    template <typename Func>
    const Base& scope(const Func& func) const {
        ecs_entity_t prev = ecs_set_scope(this->base_world(), this->base_id());
        func();
        ecs_set_scope(this->base_world(), prev);
        return *this;
    }

    /** Associate entity with type.
     * This operation enables using a type to refer to an entity, as it
     * associates the entity id with the provided type.
     *
     * If the entity does not have a name, a name will be derived from the type.
     * If the entity already is a component, the provided type must match in
     * size with the component size of the entity. After this operation the
     * entity will be a component (it will have the EcsComponent component) if
     * the type has a non-zero size.
     *
     * @tparam T the type to associate with the entity.
     */
    template <typename T>
    const Base& component() const;

    /* Set the entity name.
     */
    const Base& set_name(const char *name) const {
        ecs_set_name(this->base_world(), this->base_id(), name);
        return *this;
    }    
};