Game engine with an Entity-Component-System (ECS) architecture. Focus on ease-of-use, runtime extensibility and compile-time type safety.
MIT License
The Koala engine is a game engine entirely implemented as an Entity Component System (ECS).
The engine is based on EnTT. Integration with other pieces of software using EnTT
should be straightforward. This documentation assumes at least basic knowledge of EnTT
and its terminology (entity
, registry
, handle
...).
The example project showcases some of the core features. It should give you an idea of what the engine's support for reflection and runtime extensibility have to offer.
The engine uses Git submodules, and should therefore be cloned recursively with
git clone https://github.com/phisko/kengine --recursive
The engine has been tested on Windows with MSVC and MinGW.
Linux compilation works with GCC. At the time of writing, clang doesn't support C++ 20's constexpr std::string
and std::vector
.
The engine requires a C++20 compiler.
The engine started as a passion/student project in 2016-17. My friends/colleagues and I had a go at implementing an ECS from the ground up. We wanted absolute type safety and clarity, and while we'd already toyed with template metaprogramming, this was a chance for us to learn more about it.
Once the core ECS was working, the engine turned into a playground to learn more about game development. I learned OpenGL rendering, how to use navmeshes with Recast/Detour, setup physics with Bullet... All the while developing useful helpers and runtime reflection facilities compatible with an ECS.
After now over 5 years working on the engine, I realized the core ECS itself is no longer the focus of this project. Other libraries, and EnTT
in particular, offers a very similar API, with much more advanced features. So I took the time to completely gut out the internal ECS and replace it with EnTT
. All features remain the same, and this will give me more time to work on useful helpers, which can work with other EnTT
projects.
Many parts of the engine (such as the scripting systems or the ImGui entity editor) make use of putils
' reflection API. Most of the components in the following samples are thus defined as reflectible.
The engine code is organized in three categories:
Note that systems
aren't objects of a specific class. Systems are simply entities with an execute component (or anything else they need to do their work). The entity then lives in the registry
with the rest of the game state. This lets users introspect systems or add behavior to them just like any other entity.
These three categories are split into various libraries, e.g.:
Note that some libraries contain sub-libraries, e.g.:
The CMake section goes into more detail of how to work with these libraries.
The engine comes with a (fairly large) number of pre-built components that can be used to bootstrap a game, or simply as examples that you can base your own implementations upon.
These components fit into three categories:
Data components hold data about their entity.
Data components are what first comes to mind when thinking of a component, such as a transform or a name.
Data components can sometimes hold functions:
Function components hold functions to query, alter, or notify their entity.
Function components are simply holders for functors that can be attached as components to entities. This mechanic can be used to:
Function components are types that inherit from base_function, giving it the function signature as a template parameter.
To call a function component, one can use its operator()
or its call
function.
entt::registry r;
const auto e = r.create();
r.emplace<main_loop::execute>(e,
[](float delta_time) { std::cout << "Yay!" << std::endl; }
);
const auto & execute = r.get<main_loop::execute>(e); // Get the function
execute(0.f); // Call it with its parameters
execute.call(42.f); // Alternatively
Meta components are components for components.
The engine uses "type entities" to hold information about the various components in use. Each type entity represents a different component type, and can be used to query the component's properties at runtime.
Meta components are attached to these "type entities", and hold a generic function's implementation for that specific type. Because they hold functions, they are very similar to function components.
An example makes this clearer: meta::imgui::edit is a meta component that, when called, will draw its "parent component"'s properties using ImGui for the given entity. The following code will display a window to edit e
's name component.
// r is a registry with the "type entity" for `name` already setup
const auto e = r.create();
r.emplace<core::name>(e);
const auto type_entity = type_helper::get_type_entity<core::name>(r);
const auto & edit = r.get<meta::imgui::edit>(type_entity);
if (ImGui::Begin("Edit name"))
edit({ r, e });
ImGui::End();
If you generalize this, you can edit all the components for an entity with the following code:
// r is a registry with the "type entities" for all used components already setup
// e is an entity with an unknown set of components
if (ImGui::Begin("Edit entity"))
for (const auto & [type_entity, edit] : r.view<meta::imgui::edit>()) {
edit({ r, e });
}
ImGui::End();
See CMake for instructions on how to enable each library.
A generate_type_registration Python script is provided, which can be used to generate C++ files containing functions that will register a set of given types with the engine.
This is absolutely not mandatory.
The engine uses CMake as a build system. A custom framework has been put in place to simplify the creation of libraries. The root CMakeLists iterates over sub-directories and automatically adds them as libraries if they match a few conditions.
A base kengine
interface library is created that links against all enabled libraries, so clients may simply link against that.
The following CMake options are exposed.
KENGINE_TESTS
Compiles test executables for the libraries that implement tests.
KENGINE_NDEBUG
Disables debug code.
KENGINE_TYPE_REGISTRATION
Will generate type registration code for engine types. This is central to many of the engine's reflection capabilities, as it provides the implementation for meta components.
KENGINE_GENERATE_REFLECTION
Will update the reflection headers for engine types. These are pre-generated, so unless you're modifying the engine's source code you shouldn't need to enable this.
All libraries are disabled by default, to avoid building unwanted dependencies. Each library can be enabled individually by setting its CMake option to ON
. See Library naming for the option name.
Alternatively, all libraries can be enabled with the KENGINE_ALL_SYSTEMS
option.
Note that sub-libraries need their parent library to be enabled: kengine_imgui_entity_editor requires kengine_imgui.
Libraries are named depending on their relative path to the engine root. The slashes in the path are simply replaced by underscores, e.g.:
kengine_core
kengine_imgui_tool
These names are:
KENGINE_CORE
for kengine_core
)KENGINE_CORE_EXPORT
for kengine_core
)It is possible to test for the existence of a library during compilation thanks to C++ define macros. These have the same name as the CMake options, e.g.:
#ifdef KENGINE_CORE
// The kengine_core library exists
#endif
Some libraries make use of vcpkg for dependency management.
Since libraries are automatically detected by the root CMakeLists.txt
, creating a new library is fairly easy.
Libraries automatically link against kengine_core
, since it provides helpers that should be used by all libraries (such as the log_helper and the profiling_helper).
Sub-libraries automatically link against their parent. For instance, kengine_imgui_entity_editor automatically links against kengine_imgui.
Source files from a library's helpers
and systems
subdirectories are automatically added. If none are found, the library will be a CMake interface library.
Type registration and reflection code may be automatically generated for components. By default, all headers in a library's data
and functions
subdirectories will be passed to the generation scripts.
Similarly to source files, if any *.tests.cpp
files are found in a library's helpers/tests
or systems/tests
subdirectories, a GoogleTest executable will be automatically added.
CMakeLists.txt
Basic libraries shouldn't need their own CMakeLists.txt
, since their source files will be automatically. However, if a library needs custom behavior (e.g. to add extra sources or to link against a third-party library), it may add its own CMakeLists.txt
. That CMakeLists.txt
will be called after the call to add_library
.
The following variables and functions are defined before calling the CMakeLists.txt
:
kengine_library_name
: the library's namekengine_library_tests_name
: the library's GoogleTest target's namelink_type
: the library's link type (PUBLIC
or INTERFACE
, depending on whether sources were found or not)kengine_library_link_public_libraries(libraries)
: links against other libraries (publicly)kengine_library_link_private_libraries(libraries)
: links against other libraries (privately)register_types_from_headers(headers)
: adds headers for which type registration and reflection headers may be generatedsubdirectory_is_not_kengine_library(path)
: indicates to the root CMakeLists.txt
that it shouldn't process path
as a kengine library