shiva
Search…
How to create/build/install a system plugin

Let's write some code

To start create two files system_example_plugin.hpp and system_example_plugin.cpp
system_example_plugin.hpp
#include <shiva/entt/entt.hpp>
#include <shiva/ecs/system.hpp>
namespace my_game::plugins
{
//! Depending on the system_type, the inheritance can be different.
class system_example final : public shiva::ecs::post_update_system<system_example>
{
public:
//! Destructor
~system_example() noexcept final = default;
/* Only this constructor is allowed in plugins */
//! Constructor
system_example(shiva::entt::dispatcher &dispatcher,
shiva::entt::entity_registry &registry,
const float &fixed_delta_time) noexcept;
//! The creator function (entry point of your plugins)
//! Return should always be a unique_ptr on base_system in plugins
static std::unique_ptr<shiva::ecs::base_system> system_creator(entt::dispatcher &dispatcher,
entt::entity_registry &registry,
const float &fixed_delta_time) noexcept;
//! override from base_system
//! The logic of the system will be inside this function
void update() noexcept final;
//! Reflection (mandatory by a type_traits)
reflect_class(render_system)
static constexpr auto reflected_functions() noexcept;
static constexpr auto reflected_members() noexcept;
private:
//! You can have additional data here
}
}
system_example_plugin.cpp
#include <boost/dll.hpp> //! For BOOST_DLL_ALIAS
#include "system_example_plugin.hpp"
namespace my_game::plugins
{
//! Implementation of the constructor
system_example::system_example(shiva::entt::dispatcher &dispatcher, shiva::entt::entity_registry &registry,
const float &fixed_delta_time) noexcept :
system(dispatcher, registry, fixed_delta_time, true) //! true means im_a_plugin
{
//! You can set user data here if you want to share data betweens plugins
user_data_ = /* whatever you want */;
//! Also if you need to initialize some things for the system is here.
}
//! The creator factory implementation
std::unique_ptr<shiva::ecs::base_system> example_system::system_creator(shiva::entt::dispatcher &dispatcher,
shiva::entt::entity_registry &registry,
const float &fixed_delta_time) noexcept
{
return std::make_unique<my_game::plugins::system_example>(dispatcher, registry, fixed_delta_time);
}
//! override from base system
void system_example::update() noexcept
{
/* Write your code here. */
}
//! Reflection
constexpr auto system_example::reflected_functions() noexcept
{
return meta::makeMap(reflect_function(&system_example::update));
}
constexpr auto system_example::reflected_members() noexcept
{
return meta::makeMap();
}
}
BOOST_DLL_ALIAS(
my_game::plugins::system_example::system_creator, // <-- this function is exported with... (from boost)
create_plugin // <-- ...this alias name (from boost)
)

How to share data between plugins (without the dispatcher)

We assume here that you have set the user_data as shown in the example above
sfml-example.hpp
namespace shiva::examples::sfml
{
class example_world : public shiva::world
{
public:
~example_world() noexcept = default;
example_world() noexcept
{
bool res = system_manager_.load_plugins();
if (!res) {
std::cerr << "error loading plugins" << std::endl;
} else {
auto &lua_system = system_manager_.create_system<shiva::scripting::lua_system>();
auto render_system = system_manager_.get_system_by_name("render_system",
shiva::ecs::system_type::post_update);
auto input_system = system_manager_.get_system_by_name("input_system",
shiva::ecs::system_type::pre_update);
auto resources_system = system_manager_.get_system_by_name("resources_system",
shiva::ecs::system_type::pre_update);
auto animation_system = system_manager_.get_system_by_name("animation_system",
shiva::ecs::system_type::logic_update);
if (render_system != nullptr &&
animation_system != nullptr &&
resources_system != nullptr &&
input_system != nullptr) {
resources_system->set_user_data(&lua_system.get_state());
animation_system->set_user_data(&lua_system.get_state());
input_system->set_user_data(render_system->get_user_data());
lua_system.load_all_scripted_systems();
}
}
}
};
}
In the example you see above which is directly derived from the shiva code for the shiva-sfml module, I needed to share the SFML window in several different modules, for input and rendering, for example. through functions like set_user_data && get_user_data, I'm able to transfer data that only concerns plugins.

How to subscribe/emit event from a system plugin (or header-only)

Here's an example of how you could do it
//! system_example.hpp
class system_example
{
public:
/* ... other class things */
//! Callback (you will receive the event in this function)
void receive(const shiva::event::key_pressed &evt);
};
//! system_example.cpp
system_example::system_example(shiva::entt::dispatcher &dispatcher, shiva::entt::entity_registry &registry,
const float &fixed_delta_time) noexcept :
system(dispatcher, registry, fixed_delta_time, true) //! true means im_a_plugin
{
//! You can set user data here if you want to share data betweens plugins
user_data_ = /* whatever you want */;
//! Also if you need to initialize some things for the system is here.
//! Subscribe to an event
this->dispatcher_.sink<shiva::event::key_pressed>().connect(this);
//! emit an event
this->dispatcher_.trigger<shiva::event::key_pressed>(shiva::input::keyboard::TKey::A);
}
void system_example::receive(const shiva::event::key_pressed &evt)
{
//! Treat your event here
}

CMake

Here are two examples of CMake possible for the implementation of a plugin with shiva, one in the project directly if you are contributors, one externally if you make plugins for shiva in another repository

Inside shiva project

include(shiva/${module_name}/CMakeSources.cmake)
set(MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
CREATE_MODULE_PLUGIN(shiva::${module_name} "${MODULE_SOURCES}" ${MODULE_PATH} "systems" "${module_name}/shiva")
target_link_libraries(${module_name} PUBLIC shiva::ecs)
AUTO_TARGETS_PLUGINS_INSTALL(${module_name} shiva-${module_name})
PREPARE_MODULE_INSTALLATION(shiva-${module_name})
You can find a more concrete example here.

Outside shiva project

find_package(shiva CONFIG REQUIRED)
file(GLOB_RECURSE MODULE_NAME_SOURCES my_plugin/*.cpp prerequisites/*.cpp)
file(GLOB_RECURSE MODULE_NAME_HEADERS my_plugin/*.hpp)
set(MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
set(MODULE_FULL_SOURCES ${MODULE_NAME_SOURCES} ${MODULE_NAME_HEADERS})
##! CREATE_MODULE_PLUGIN ModuleAlias LibSources BuildInterfaceDirectory OutputDirectory InstallPath
CREATE_MODULE_PLUGIN(shiva::my_plugin "${MODULE_FULL_SOURCES}" ${MODULE_PATH} "systems" "my_plugin/shiva")
target_link_libraries(my_plugin PUBLIC
shiva::shiva
${LUA_LIBRARIES}) ##! additional libraries
AUTO_TARGETS_PLUGINS_INSTALL(my_plugin shiva-my_plugin)
PREPARE_MODULE_INSTALLATION(shiva-my_plugin)

Additional hints

If some things seem complicated, or parts not included in this tutorial, you will find more information on the following pages: