Repository files navigation

EnTT is a header-only, tiny and easy to use library for game programming andmuch more written inmodern C++.
Among others, it's usedinMinecraft by Mojang, theArcGIS Runtime SDKs by Esriand the amazingRagdoll.
If you don't see your project in the list, please open an issue, submit a PR oradd the#entt tag to yourtopics! 👍

Do you want tokeep up with changes or do you have aquestion thatdoesn't require you to open an issue?
Join thegitter channel and thediscord server, meet other users like you. Themore we are, the better for everyone.
Don't forget to check theFAQs and thewiki too. Your answers may already bethere.

Do you want to supportEnTT? Consider becoming asponsor.Many thanks tothese people andspecial thanks to:

• Introduction
  • Code Example
  • Motivation
  • Performance
• Integration
  • Requirements
  • CMake
  • Packaging Tools
  • pkg-config
• Documentation
• Tests
• EnTT in Action
• Contributors
• License

The entity-component-system (also known asECS) is an architectural patternused mostly in game development. For further details:

• Entity Systems Wiki
• Evolve Your Hierarchy
• ECS on Wikipedia

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

• Statically generated integeridentifiers for types (assigned either atcompile-time or at runtime).
• Aconstexpr utility for human readableresource names.
• A minimalconfiguration system built using the monostate pattern.
• An incredibly fastentity-component system based on sparse sets, with itsownpay for what you use policy to adjust performance and memory usageaccording to the users' requirements.
• Views and groups to iterate entities and components and allow different accesspatterns, fromperfect SoA to fully random.
• A lot offacilities built on top of the entity-component system to helpthe users and avoid reinventing the wheel (dependencies, snapshot, handles,support forreactive systems and so on).
• The smallest and most basic implementation of aservice locator ever seen.
• A built-in, non-intrusive and macro-free runtimereflection system.
• Static polymorphism made simple and within everyone's reach.
• Acooperative scheduler for processes of any type.
• All that is needed forresource management (cache, loaders, handles).
• Delegates,signal handlers (with built-in support for collectors) and atiny event dispatcher for immediate and delayed events to integrate in loops.
• A general purposeevent emitter as a CRTP idiom based class template.
• Andmuch more! Check out thewiki.

Consider this list a work in progress as well as the project. The whole API isfully documented in-code for those who are brave enough to read it.

It is also known thatEnTT is used inMinecraft.
Given that the game is available literally everywhere, I can confidently saythat the library has been sufficiently tested on every platform that can come tomind.

#include<entt/entt.hpp>structposition {float x;float y;};structvelocity {float dx;float dy;};voidupdate(entt::registry &registry) {auto view = registry.view<const position, velocity>();// use a callback    view.each([](constauto &pos,auto &vel) {/* ...*/ });// use an extended callback    view.each([](constauto entity,constauto &pos,auto &vel) {/* ...*/ });// use a range-forfor(auto [entity, pos, vel]: view.each()) {// ...    }// use forward iterators and get only the components of interestfor(auto entity: view) {auto &vel = view.get<velocity>(entity);// ...    }}intmain() {    entt::registry registry;for(auto i =0u; i <10u; ++i) {constauto 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);}

I started developingEnTT for thewrong reason: my goal was to design anentity-component system to beat another well known open source solution both interms of performance and possibly memory usage.
In the end, I did it, but it wasn't very satisfying. Actually it wasn'tsatisfying at all. The fastest and nothing more, fairly little indeed. When Irealized it, I tried hard to keep intact the great performance ofEnTT and toadd all the features I wanted to see inmy own library at the same time.

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

The proposed entity-component system is incredibly fast to iterate entities andcomponents, this is a fact. Some compilers make a lot of optimizations becauseof howEnTT works, some others aren't that good. In general, if we considerreal world cases,EnTT is somewhere between a bit and much faster than many ofthe other solutions around, although I couldn't check them all for obviousreasons.

If you are interested, you can compile thebenchmark test in release mode (toenable compiler optimizations, otherwise it would make little sense) by settingtheENTT_BUILD_BENCHMARK option ofCMake toON, then evaluate yourselfwhether you're satisfied with the results or not.

Honestly I got tired of updating the README file whenever there is animprovement.
There are already a lot of projects out there that useEnTT as a basis forcomparison (this should already tell you a lot). Many of these benchmarks arecompletely wrong, many others are simply incomplete, good at omitting someinformation and using the wrong function to compare a given feature. Certainlythere are also good ones but they age quickly if nobody updates them, especiallywhen the library they are dealing with is actively developed.

The choice to useEnTT should be based on its carefully designed API, itsset of features and the general performance,not because some singlebenchmark shows it to be the fastest tool available.

In the future I'll likely try to get even better performance while still addingnew features, mainly for fun.
If you want to contribute and/or have suggestions, feel free to make a PR oropen an issue to discuss your idea.

EnTT is a header-only library. This means that including theentt.hpp headeris enough to include the library as a whole and use it. For those who areinterested only in the entity-component system, consider to include the soleentity/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 thesrc directory tothe include paths.

To be able to useEnTT, users must provide a full-featured compiler thatsupports at least C++17.
The requirements below are mandatory to compile the tests and to extract thedocumentation:

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

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

To useEnTT from aCMake project, just link an existing target to theEnTT::EnTT alias.
The library offers everything you need for locating (as infind_package),embedding (as inadd_subdirectory), fetching (as inFetchContent) or usingit in many of the ways that you can think of and that involveCMake.
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 aboutand can useEnTT from aCMake project without problems.

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

• Conan, the C/C++ PackageManager for Developers.

• vcpkg, Microsoft VC++ PackagingTool.
  You can download and installEnTT 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 theexperimental feature to test the latest changes:

  vcpkg install entt[experimental] --head

  TheEnTT port invcpkg is kept up to date by Microsoft team members andcommunity contributors.
  If the version is out of date, pleasecreate an issue or pull request on thevcpkg repository.

• Homebrew, the missing packagemanager 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 Cand C++ code.
  In order to use theentt package in abuild2project, add the following line or a similar one to themanifest file:

  depends: entt ^3.0.0

  Also check that the configuration refers to a valid repository, so that thepackage can be found bybuild2:

  • cppget.org, the open-source community centralrepository, accessible ashttps://pkg.cppget.org/1/stable.

  • Package source repository:accessible as eitherhttps://github.com/build2-packaging/entt.git orssh://git@github.com/build2-packaging/entt.git.Feel free toreport issues withthis package.

  Both can be used withbpkg add-repo or added in a projectrepositories.manifest. See the officialdocumentationfor more details.

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

EnTT also supportspkg-config (for some definition ofsupports at least).A suitable file calledentt.pc is generated and installed in a properdirectory when runningCMake.
This should also make it easier to use with tools such asMeson or similar.

The documentation is based ondoxygen. To build it:

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

The API reference will be created in HTML format within the directorybuild/docs/html. To navigate it with your favorite browser:

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

The same version is also availableonlinefor the latest release, that is the last stable tag. If you are looking forsomething more pleasing to the eye, consider reading the nice-looking versionavailable ondocsforge: same documentation, muchmore pleasant to read.
Moreover, there exists awiki dedicatedto the project where users can find all related documentation pages.

To compile and run the tests,EnTT requiresgoogletest.
cmake will download and compile the library before compiling anything else.In order to build the tests, set theCMake optionENTT_BUILD_TESTING toON.

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.

EnTT is widely used in private and commercial applications. I cannot evenmention most of them because of some signatures I put on some documents timeago. Fortunately, there are also people who took the time to implement opensource projects based onEnTT and did not hold back when it came todocumenting them.

Here you can find anincomplete list of games, applications and articles that can be used as areference.

If you know of other resources out there that are aboutEnTT, feel free toopen an issue or a PR and I'll be glad to add them to the list.

Requests for features, PRs, suggestions ad feedback are highly appreciated.

If you find you can help and want to contribute to the project with yourexperience or you do want to get part of the project for some other reason, feelfree to contact me directly (you can find the mail in theprofile).
I can't promise that each and every contribution will be accepted, but I canassure that I'll do my best to take them all as soon as possible.

If you decide to participate, please see the guidelines forcontributing before to create issues or pullrequests.
Take also a look at thecontributors list toknow who has participated so far.

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

Code released underthe MIT license.
Documentation released underCC BY 4.0.
All logos released underCC BY-SA 4.0.