Repository files navigation

The Koala engine is a game engine entirely implemented as anEntity Component System (ECS).

The engine is based onEnTT. Integration with other pieces of software usingEnTT should be straightforward. This documentation assumes at least basic knowledge ofEnTT and its terminology (entity,registry,handle...).

Theexample 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'sconstexpr std::string andstd::vector.

The engine requires aC++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, andEnTT 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 withEnTT. All features remain the same, and this will give me more time to work on useful helpers, which can work with otherEnTT projects.

Many parts of the engine (such as the scripting systems or the ImGui entity editor) make use ofputils'reflection API. Most of the components in the following samples are thus defined as reflectible.

The engine code is organized in three categories:

• components: hold dataor functions (seeComponent categories below)
• systems: entities that implement an engine feature
• helpers: functions to simplify component manipulation

Note thatsystems aren't objects of a specific class. Systems are simply entities with anexecute component (or anything else they need to do their work). The entity then lives in theregistry 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.:

• core
• pathfinding
• render
• ...

Note that some libraries contain sub-libraries, e.g.:

• imgui/entity_editor
• pathfinding/recast
• render/sfml
• ...

TheCMake 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
• function components
• meta components

Data components hold data about their entity.

Data components are what first comes to mind when thinking of a component, such as atransform or aname.

Data components can sometimes hold functions:

• input::handler lets an entity hold callbacks to be called whenever an input event occurs
• collision lets an entity be notified when it collides with another

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:

• attach behaviors to entities:execute is called by the main loop each frame
• register callbacks for system-wide events:on_click is called whenever the user clicks the entity
• provide new functionality that is implemented in a specific system:query_position is typically implemented by a physics system

Function components are types that inherit frombase_function, giving it the function signature as a template parameter.

To call a function component, one can use itsoperator() or itscall function.

entt::registry r;constauto e = r.create();r.emplace<main_loop::execute>(e,    [](float delta_time) { std::cout <<"Yay!" << std::endl; });constauto & execute = r.get<main_loop::execute>(e);// Get the functionexecute(0.f);// Call it with its parametersexecute.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 usingImGui for the given entity. The following code will display a window to edite'sname component.

// r is a registry with the "type entity" for `name` already setupconstauto e = r.create();r.emplace<core::name>(e);constauto type_entity = type_helper::get_type_entity<core::name>(r);constauto & 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 componentsif (ImGui::Begin("Edit entity"))for (constauto & [type_entity, edit] : r.view<meta::imgui::edit>()) {edit({ r, e });    }ImGui::End();

SeeCMake for instructions on how to enable each library.

• kengine_core: components and helpers that are accessed by most (if not all) other libraries
  • kengine_core_assert: engine-level assertions
  • kengine_core_log: generic logging support
    • kengine_core_log_file: log to a file
    • kengine_core_log_imgui: log to an ImGui window
    • kengine_core_log_standard_output: log stdout
    • kengine_core_log_visual_studio: log to VS's output window
  • kengine_core_profiling: profiling usingTracy
  • kengine_core_sort: entity sorting helpers
• kengine_config: expose global values that the user may adjust
  • kengine_config_imgui: display config values in an ImGui window
• kengine_async: run asynchronous tasks
  • kengine_async_imgui: display running tasks in an ImGui window
• kengine_command_line: manipulate the command-line
• kengine_glm: useGLM
• kengine_imgui: useImGui
  • kengine_imgui_tool: enable/disable ImGui tools from the main menu bar
• kengine_input: handle user input
• kengine_json_scene_loader: load scenes from JSON files
• kengine_main_loop: run a game's main loop, handling delta time
• kengine_meta: meta components and reflection facilities
  • kengine_meta_imgui: meta components for ImGui
    • kengine_meta_imgui_engine_stats: display engine stats in an ImGui window
    • kengine_meta_imgui_entity_editor: edit entities in ImGui windows
    • kengine_meta_imgui_entity_selector: select entities in an ImGui window
  • kengine_meta_json: meta components for JSON
• kengine_model: use model entities, which other entities can be instances of
  • kengine_model_find: template system to find an entity's model by a given component
  • kengine_model_find_by_name: find an entity's model by its name
• kengine_pathfinding: add pathfinding capabilities to entities
  • kengine_pathfinding_recast: implement pathfinding usingRecast
• kengine_physics: move and query entities in space
  • kengine_physics_bullet: implement physics usingBullet
• kengine_render: display entities in graphical applications
  • kengine_render_animation: play animations on entities
  • kengine_render_find_model_by_asset: find an entity's model by its asset
  • kengine_render_kreogl: implement rendering usingkreogl
  • kengine_render_on_click: notify entities that are clicked by the user
  • kengine_render_sfml: implement rendering usingSFML
• kengine_scripting: run scripts from other languages
  • kengine_scripting_imgui_prompt: interpret scripting commands in an ImGui window
  • kengine_scripting_lua: run scripts in Lua
  • kengine_scripting_python: run scripts in Python
• kengine_skeleton: manipulate entities' skeletons
• kengine_system_creator: helpers to manipulate system entities

Agenerate_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 isabsolutely not mandatory.

The engine usesCMake as a build system. A custom framework has been put in place to simplify the creation of libraries. Theroot CMakeLists iterates over sub-directories and automatically adds them as libraries if they match a few conditions.

A basekengineinterface library is created that links against all enabled libraries, so clients may simply link against that.

The following CMake options are exposed.

Compiles test executables for the libraries that implement tests.

Disables debug code.

Will generatetype registration code for engine types. This is central to many of the engine's reflection capabilities, as it provides the implementation formeta components.

Will update thereflection 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 toON. SeeLibrary naming for the option name.

Alternatively, all libraries can be enabled with theKENGINE_ALL_SYSTEMS option.

Note that sub-libraries need their parent library to be enabled:kengine_imgui_entity_editor requireskengine_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_core
• kengine/imgui/tool:kengine_imgui_tool

These names are:

• used when linking against a specific library
• used for the CMake option to enable a library (e.g.KENGINE_CORE forkengine_core)
• used for a library's internalexport macro (e.g.KENGINE_CORE_EXPORT forkengine_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 ofvcpkg for dependency management.

Since libraries are automatically detected by the rootCMakeLists.txt, creating a new library is fairly easy.

Libraries automatically link againstkengine_core, since it provides helpers that should be used by all libraries (such as thelog_helper and theprofiling_helper).

Sub-libraries automatically link against their parent. For instance,kengine_imgui_entity_editor automatically links againstkengine_imgui.

Source files from a library'shelpers andsystems subdirectories are automatically added. If none are found, the library will be a CMake interface library.

Type registration andreflection code may be automatically generated for components. By default, all headers in a library'sdata andfunctions subdirectories will be passed to the generation scripts.

Similarly to source files, if any*.tests.cpp files are found in a library'shelpers/tests orsystems/tests subdirectories, a GoogleTest executable will be automatically added.

Basic libraries shouldn't need their ownCMakeLists.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 ownCMakeLists.txt. ThatCMakeLists.txt will be calledafter the call toadd_library.

The following variables and functions are defined before calling theCMakeLists.txt:

• kengine_library_name: the library's name
• kengine_library_tests_name: the library's GoogleTest target's name
• link_type: the library's link type (PUBLIC orINTERFACE, 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 whichtype registration andreflection headers may be generated
• subdirectory_is_not_kengine_library(path): indicates to the rootCMakeLists.txt that it shouldn't processpath as a kengine library