EnTT 3.13.0
Loading...
Searching...
No Matches
EnTT

EnTT: Gaming meets modern C++

Introduction

The entity-component-system (also known as ECS) is an architectural pattern used mostly in game development. For further details:

This project started off as a pure entity-component system. Over time the codebase has grown as more and more classes and functionalities were added.
Here is a brief, yet incomplete list of what it offers today:

  • Built-in RTTI system mostly similar to the standard one.
  • A constexpr utility for human-readable resource names.
  • Minimal configuration system built using the monostate pattern.
  • Incredibly fast entity-component system with its own pay for what you use policy, unconstrained component types with optional pointer stability and hooks for storage customization.
  • Views and groups to iterate entities and components and allow different access patterns, from perfect SoA to fully random.
  • A lot of facilities built on top of the entity-component system to help the users and avoid reinventing the wheel.
  • General purpose execution graph builder for optimal scheduling.
  • The smallest and most basic implementation of a service locator ever seen.
  • A built-in, non-intrusive and macro-free runtime reflection system.
  • Static polymorphism made simple and within everyone's reach.
  • A few homemade containers, like a sparse set based hash map.
  • A cooperative scheduler for processes of any type.
  • All that is needed for resource management (cache, loaders, handles).
  • Delegates, signal handlers and a tiny event dispatcher.
  • A general purpose event emitter as a CRTP idiom based class template.
  • And much more! Check out the wiki.

Consider this list a work in progress as well as the project. The whole API is fully documented in-code for those who are brave enough to read it.
Please, do note that all tools are also DLL-friendly now and run smoothly across boundaries.

One thing known to most is that EnTT is also used in Minecraft.
Given that the game is available literally everywhere, I can confidently say that the library has been sufficiently tested on every platform that can come to mind.

Code Example

#include <entt/entt.hpp>
struct position {
float x;
float y;
};
struct velocity {
float dx;
float dy;
};
void update(entt::registry &registry) {
auto view = registry.view<const position, velocity>();
// use a callback
view.each([](const auto &pos, auto &vel) { /* ... */ });
// use an extended callback
view.each([](const auto entity, const auto &pos, auto &vel) { /* ... */ });
// use a range-for
for(auto [entity, pos, vel]: view.each()) {
// ...
}
// use forward iterators and get only the components of interest
for(auto entity: view) {
auto &vel = view.get<velocity>(entity);
// ...
}
}
int main() {
for(auto i = 0u; i < 10u; ++i) {
const auto entity = registry.create();
registry.emplace<position>(entity, i * 1.f, i * 1.f);
if(i % 2 == 0) { registry.emplace<velocity>(entity, i * .1f, i * .1f); }
}
update(registry);
}
Fast and reliable entity-component system.
Definition registry.hpp:233
entity
Default entity identifier.
Definition fwd.hpp:13
basic_view< type_list_transform_t< Get, storage_for >, type_list_transform_t< Exclude, storage_for > > view
Alias declaration for the most common use case.
Definition fwd.hpp:253
basic_registry<> registry
Alias declaration for the most common use case.
Definition fwd.hpp:82

Motivation

I started developing EnTT for the wrong reason: my goal was to design an entity-component system to beat another well known open source library both in terms of performance and possibly memory usage.
In the end, I did it, but it wasn't very satisfying. Actually it wasn't satisfying at all. The fastest and nothing more, fairly little indeed. When I realized it, I tried hard to keep intact the great performance of EnTT and to add all the features I wanted to see in my own library at the same time.

Nowadays, EnTT is finally what I was looking for: still faster than its competitors, lower memory usage in the average case, a really good API and an amazing set of features. And even more, of course.

Benchmark

For what it's worth, you'll never see me trying to make other projects look bad or offer dubious comparisons just to make this library seem cooler.
I leave this activity to others, if they enjoy it (and it seems that some people actually like it). I prefer to make better use of my time.

If you are interested, you can compile the benchmark test in release mode (to enable compiler optimizations, otherwise it would make little sense) by setting the ENTT_BUILD_BENCHMARK option of CMake to ON, then evaluate yourself whether you're satisfied with the results or not.

There are also a lot of projects out there that use EnTT as a basis for comparison (this should already tell you a lot). Many of these benchmarks are completely wrong, many others are simply incomplete, good at omitting some information and using the wrong function to compare a given feature. Certainly there are also good ones but they age quickly if nobody updates them, especially when the library they are dealing with is actively developed.
Out of all of them, this seems like the most up-to-date project and also covers a certain number of libraries. I can't say exactly whether EnTT is used correctly or not. However, even if used poorly, it should still give the reader an idea of where it's going to operate.

Integration

EnTT is a header-only library. This means that including the entt.hpp header is enough to include the library as a whole and use it. For those who are interested only in the entity-component system, consider to include the sole entity/registry.hpp header instead.
It's a matter of adding the following line to the top of a file:

#include <entt/entt.hpp>

Use the line below to include only the entity-component system instead:

#include <entt/entity/registry.hpp>

Then pass the proper -I argument to the compiler to add the src directory to the include paths.

Requirements

To be able to use EnTT, users must provide a full-featured compiler that supports at least C++17.
The requirements below are mandatory to compile the tests and to extract the documentation:

  • CMake version 3.7 or later.
  • Doxygen version 1.8 or later.

Alternatively, Bazel is also supported as a build system (credits to zaucy who offered to maintain it).
In the documentation below I'll still refer to CMake, this being the official build system of the library.

CMake

To use EnTT from a CMake project, just link an existing target to the EnTT::EnTT alias.
The library offers everything you need for locating (as in find_package), embedding (as in add_subdirectory), fetching (as in FetchContent) or using it in many of the ways that you can think of and that involve CMake.
Covering all possible cases would require a treaty and not a simple README file, but I'm confident that anyone reading this section also knows what it's about and can use EnTT from a CMake project without problems.

Natvis support

When using CMake, just enable the option ENTT_INCLUDE_NATVIS and enjoy it.
Otherwise, most of the tools are covered via Natvis and all files can be found in the natvis directory, divided by module.
If you spot errors or have suggestions, any contribution is welcome!

Packaging Tools

EnTT is available for some of the most known packaging tools. In particular:

  • Conan, the C/C++ Package Manager for Developers.
  • vcpkg, Microsoft VC++ Packaging Tool.
    You can download and install EnTT in just a few simple steps:

    $ git clone https://github.com/Microsoft/vcpkg.git
    $ cd vcpkg
    $ ./bootstrap-vcpkg.sh
    $ ./vcpkg integrate install
    $ vcpkg install entt

    Or you can use the experimental feature to test the latest changes:

    vcpkg install entt[experimental] --head

    The EnTT port in vcpkg is kept up to date by Microsoft team members and community contributors.
    If the version is out of date, please create an issue or pull request on the vcpkg repository.

  • Homebrew, the missing package manager for macOS.
    Available as a homebrew formula. Just type the following to install it:

    brew install skypjack/entt/entt
  • build2, build toolchain for developing and packaging C and C++ code.
    In order to use the entt package in a build2 project, add the following line or a similar one to the manifest file:

    depends: entt ^3.0.0

    Also check that the configuration refers to a valid repository, so that the package can be found by build2:

    Both can be used with bpkg add-repo or added in a project repositories.manifest. See the official documentation for more details.

  • bzlmod, Bazel's external dependency management system.
    To use the entt module in a bazel project, add the following to your MODULE.bazel file:

    bazel_dep(name = "entt", version = "3.12.2")

    EnTT will now be available as @entt (short for @entt//:entt) to be used in your cc_* rule deps.

Consider this list a work in progress and help me to make it longer if you like.

pkg-config

EnTT also supports pkg-config (for some definition of supports at least). A suitable file called entt.pc is generated and installed in a proper directory when running CMake.
This should also make it easier to use with tools such as Meson or similar.

Documentation

The documentation is based on doxygen. To build it:

$ cd build
$ cmake .. -DENTT_BUILD_DOCS=ON
$ make

The API reference is created in HTML format in the build/docs/html directory. To navigate it with your favorite browser:

$ cd build
$ your_favorite_browser docs/html/index.html

Tests

To compile and run the tests, EnTT requires googletest.
cmake downloads and compiles the library before compiling anything else. In order to build the tests, set the CMake option ENTT_BUILD_TESTING to ON.

To build the most basic set of tests:

  • $ cd build
  • $ cmake -DENTT_BUILD_TESTING=ON ..
  • $ make
  • $ make test

Note that benchmarks are not part of this set.

License

Code and documentation Copyright (c) 2017-2023 Michele Caini.
Colorful logo Copyright (c) 2018-2021 Richard Caseres.

Code released under the MIT license.
Documentation released under CC BY 4.0.
All logos released under CC BY-SA 4.0.