W4 Component System

Scope

The W4 framework comes with a component system. In this case, a component is the ability to extend the functionality of an object without inheritance.

System features:

• All components inherit from the base IComponent class.
• Each component has a unique identifier for its type, by which the component can always be obtained from the container.
• The container for components is the Node class (see W4 Coordinate system and Node structure).
• A global list of components is maintained, allowing access to all components of a particular type from anywhere in the application.

IComponent class

Let's consider the main methods of the IComponent public interface:

• const Id& id() const;
  

  - this method allows you to get the id of the component;

• void enable(bool isEnabled);
  

  - enable/disable component. Using this method, you can temporarily disable the functionality of the component and avoid construction and destruction (save the component internal state). A disabled component disappears from the global list of components, and the update() method is no longer called for it;

• bool isEnabled() const;
  

  - this method lets you know if the component is enabled;

• template<typename T> T& as();
  

  - this method casts the pointer/reference to the base component to the component of the desired type;

• ::w4::core::Node & getOwner();
  

  - this method allows you to get the owner of the given component (the container in which it is contained);

• const core::TypeInfo& getTypeInfo() const;
  

  - this method allows you to get information about the type of the component by the pointer/reference to the base component.

This class has methods that are not recommended to be called directly (this can lead to incorrect application behavior). But these methods can be overloaded if you write your own component (when overloading, do not forget to call the same method on the parent class Super::someMethod(args)):

• virtual void initialize(const variant::Variant & data);
  

  - this method is called when a component is added to the container. Data required for initialization of a specific component type can be passed as an argument;

• virtual void finalize();
  

  - this method is called when a component is removed from a container and then destroyed. When writing your own component, if you need to perform any actions before destroying the component, all these actions should be performed in the overloaded finalize method;

• virtual void update(float dt);
  

  - this method is called every frame for all components that have this method overloaded. The incoming parameter is the time elapsed since the last call;

• virtual void onEnabled(bool value);
  

  - this method is called when the component is enabled. The method can be overloaded to respond to event data.

Component container

Container public interface for components (Node):

• template<typename T> T& addComponent(const IComponent::Id& id, const variant::Variant& data);
  

  - this method allows you to add a component of type T with id (if necessary, you can pass initialization data). If a component of type T with this identifier already exists, the application execution is stopped with an error;

• template<typename T> T& addComponent(const variant::Variant& data);
  

  - this method is similar to the previous one, but the id is generated automatically to exclude possible errors during execution;

• template<typename T> void removeComponent(const IComponent::Id& id);
  

  - this method allows you to remove a component with a specific id from the container and then destroy the component. If a component with such an identifier does not exist, a warning is displayed, but the program continues to run;

• template<typename T> void removeFirstComponent();
  

  - this method allows you to remove one component of type T from the list (Note! The components in the list are not stored in the order they were added, so you cannot know which component will be removed. You should use this method only if you are sure that the component of type T is the only one). If components of this type do not exist, a warning is displayed, but program execution continues;

• template<typename T> void removeAllComponents();
  

  - this method allows you to remove all components of type T from the container and then destroy them;

• template<typename T> bool hasComponent(const IComponent::Id& id) const;
  

  - this method lets you know if the container has a component of type T with the specified id;

• template<typename T> T& getComponent(const IComponent::Id& id);
  

  - this method allows you to get from the container a component of type T with the specified id. If a component of this type with this id does not exist, the program execution is interrupted;

• template<typename T> T& Node::getFirstComponent();
  

  - this method allows you to get from the container one of the components of type T (Note! The components in the list are not stored in the order they were added, so you cannot know which component will be removed. You should use this method only if you are sure that the component of type T is the only one). If there are no components of this type, then the program execution is interrupted;

• template<typename T> const std::unordered_set<T*>& getAllComponents() const;
  

  - this method allows you to get from the container a list of all components of type T (or inherited from type T) stored in it.

Global Component List

The following method is used to interact with the global list of components:

static const std::unordered_set<T*>& ComponentsSystem::getComponents();

- this static method allows you to get a list of all components of type T or those inherited from type T.

Component creation

Let's consider an example of creating a component that will rotate a container:

//Declare a class inheriting from IComponent
class MyComponent: public IComponent
{
//Mandatory macro. The first argument is your class, the second one is a base class
W4_COMPONENT(MyComponent, IComponent)
//If it is necessary to prohibit cloning of a component when cloning a container,
//add a call to the W4_COMPONENT_DISABLE_CLONING macro
public:
    //If you have not forbidden cloning of the component,
    //you need to implement the cloning constructor
    MyComponent(CloneTag, const MyComponent& from, Node& owner)
            : Super(CloneTag{}, from, owner) //call the parental clone constructor
    {
        //clone the necessary data
        m_rotationPerSecond = from.m_rotationPerSecond;
    }
    //Do not forget about the virtual destructor in case you plan 
    //to inherit from this component
    virtual ~MyComponent()
    {
    }

    //If you need to perform any action immediately after creating a component, 
    //overload this method. Input - data for initialization (it may be empty)
    virtual void initialize(const variant::Variant& data) override
    {
        //Note! Do not forget to call the parental method!
        Super::initialize(data);
        //Check if there is data for initialization
        if (data.valid() && data.is<float>())
        {
            //If data is passed for initialization,
            //then we initialize rotational speed with this data
            m_rotationPerSecond = data.get<float>();
        }
        else
        {
            //If the required data is not passed, 
            //the rotational speed is initialized to zero
            m_rotationPerSecond = PI;
        }
        W4_LOG_INFO("Component created with speed %f", m_rotationPerSecond);
    }
    //If you need to perform any additional actions before destroying 
    //the component, you must overload this method
    virtual void finalize() override
    {
        W4_LOG_INFO("Component will be removed with speed %f", m_rotationPerSecond);
        //Note! Do not forget to call the parental method!
        Super::finalize();
    }

    //Add the ability to change the rotation speed
    void setSpeed(float speed)
    {
        m_rotationPerSecond = speed;
    }

    //If the component needs to update its state depending on time,
    //you need to overload this method
    virtual void update(float dt) override
    {
        //Rotate the container
        auto dr = m_rotationPerSecond * dt;
        getOwner().rotateLocal(Rotator{dr, dr, dr});
        //Note! Do not forget to call the parental method!
        Super::update(dt);
    }
protected:
    //if you need to perform any actions when turning on or off the component,
    //you must overload this method
    virtual void onEnabled(bool enabled) override
    {
        if (enabled)
        {
            W4_LOG_INFO("component enabled");
        }
        else
        {
            W4_LOG_INFO("component disabled");
        }
        //Note! Do not forget to call the parental method!
        Super::onEnabled(enabled);
    }
private:
    //The component stores the rotational speed
    float m_rotationPerSecond;
};

Usage example

Now let's write a simple app that will rotate a cube using the above component:

#include "W4Framework.h"

W4_USE_UNSTRICT_INTERFACE

//Объявляем класс-наследник IComponent
class MyComponent: public IComponent
{
//обязательный макрос, первый аргумент - ваш класс, второй аргумент - базовый класс
W4_COMPONENT(MyComponent, IComponent)
//если необходимо запретить клонирование компонента при клонировании контейнера
//нужно добавить вызов макроса W4_COMPONENT_DISABLE_CLONING
public:
    //если Вы не запретили клонирование компонента -
    //необходимо реализовать конструктор клонирования
    MyComponent(CloneTag, const MyComponent& from, Node& owner)
            : Super(CloneTag{}, from, owner) //вызываем родительский конструктор клонирования
    {
        //здесь клонируем нужные данные
        m_rotationPerSecond = from.m_rotationPerSecond;
    }
    //не забываем о виртуальном деструкторе в случае, если Вы планируете
    //наследоваться от этого компонента
    virtual ~MyComponent()
    {
    }

    //если сразу после создания компонента необходимо произвести какие-либо действие
    //то перегружаем этот метод. На входе - данные для инициализации
    //данные для инициализации могут быть пустыми
    virtual void initialize(const variant::Variant& data) override
    {
        //НЕ ЗАБЫВАЕМ ЗВАТЬ МЕТОД РОДИТЕЛЯ!
        Super::initialize(data);
        //проверяем, есть ли данные для инициализации
        if (data.valid() && data.is<float>())
        {
            //если переданы данные для инициализации
            //то инициализируем значение скорости вращения этими данными
            m_rotationPerSecond = data.get<float>();
        }
        else
        {
            //если нужные нам данные не переданы
            //инициализируем значение скорости вращения нулём
            m_rotationPerSecond = PI;
        }
        W4_LOG_INFO("Component created with speed %f", m_rotationPerSecond);
    }
    //если перед разрушением компонента необходимо произвести какие-то
    //дополнительные действия - необходимо перегрузить этот метод
    virtual void finalize() override
    {
        W4_LOG_INFO("Component will be removed with speed %f", m_rotationPerSecond);
        //НЕ ЗАБЫВАЕМ ЗВАТЬ МЕТОД РОДИТЕЛЯ!
        Super::finalize();
    }

    //даём возможность изменять скорость вращения
    void setSpeed(float speed)
    {
        m_rotationPerSecond = speed;
    }

    //если в вашем компоненте необходимо обновлять состояние в зависимости от времени
    //необходимо перегрузить этот метод
    virtual void update(float dt) override
    {
        //будем вращать контейнер
        auto dr = m_rotationPerSecond * dt;
        getOwner().rotateLocal(Rotator{dr, dr, dr});
        //НЕ ЗАБЫВАЕМ ЗВАТЬ МЕТОД РОДИТЕЛЯ!
        Super::update(dt);
    }
protected:
    //если нужно производить какие-либо действия при включении/выключении компонента
    //необходимо перегрузить этот метод
    virtual void onEnabled(bool enabled) override
    {
        if (enabled)
        {
            W4_LOG_INFO("component enabled");
        }
        else
        {
            W4_LOG_INFO("component disabled");
        }
        //НЕ ЗАБЫВАЕМ ЗВАТЬ МЕТОД РОДИТЕЛЯ!
        Super::onEnabled(enabled);
    }
private:
    //компонент хранит значение скорости вращения
    float m_rotationPerSecond;
};

class MyGame: public IGame
{
    void onStart() override
    {
        //создаём куб
        m_cube = Mesh::create::cube({1.f, 1.f, 1.f});

        //добавляем его в рут
        Render::getRoot()->addChild(m_cube);

        //добавляем кубу наш компонент
        m_cube->addComponent<MyComponent>(PI);
    }
    void onKey(const event::Keyboard::Down& evt) override
    {
        if (evt.key == event::Keyboard::Key::W)
        {
            //при нажатии на кнопку W вращаем куб против часовой стрелки
            m_cube->getFirstComponent<MyComponent>().setSpeed(PI);
        }
        else if (evt.key == event::Keyboard::Key::S)
        {
            //при нажатии на кнопку S вращаем куб по часовой стрелке
            m_cube->getFirstComponent<MyComponent>().setSpeed(-PI);
        }
        else if (evt.key == event::Keyboard::Key::Space)
        {
            //при нажатии пробела включаем/выключаем вращение
            m_cube->getFirstComponent<MyComponent>().enable(!m_cube->getFirstComponent<MyComponent>().isEnabled());
        }
    }
    sptr<Mesh> m_cube;
};

W4_RUN(MyGame)