{"id":13417944,"url":"https://github.com/alecthomas/entityx","last_synced_at":"2025-05-15T04:07:55.846Z","repository":{"id":5202129,"uuid":"6377564","full_name":"alecthomas/entityx","owner":"alecthomas","description":"EntityX - A fast, type-safe C++ Entity-Component system","archived":false,"fork":false,"pushed_at":"2024-01-02T21:45:56.000Z","size":2916,"stargazers_count":2251,"open_issues_count":18,"forks_count":296,"subscribers_count":118,"default_branch":"master","last_synced_at":"2025-04-14T05:56:43.676Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alecthomas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":".github/FUNDING.yml","license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["alecthomas"]}},"created_at":"2012-10-24T21:07:42.000Z","updated_at":"2025-04-12T13:24:49.000Z","dependencies_parsed_at":"2024-01-03T00:07:35.047Z","dependency_job_id":"d83fde07-02e5-436b-b29d-1999250264f2","html_url":"https://github.com/alecthomas/entityx","commit_stats":{"total_commits":259,"total_committers":46,"mean_commits":5.630434782608695,"dds":0.4208494208494209,"last_synced_commit":"3989cf4cf81da1077a501a1d53e6114f55b812f9"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecthomas%2Fentityx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecthomas%2Fentityx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecthomas%2Fentityx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecthomas%2Fentityx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alecthomas","download_url":"https://codeload.github.com/alecthomas/entityx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270656,"owners_count":22042860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T22:00:55.938Z","updated_at":"2025-05-15T04:07:50.832Z","avatar_url":"https://github.com/alecthomas.png","language":"C++","readme":"# EntityX - A fast, type-safe C++ Entity Component System\n[![Build Status](https://travis-ci.org/alecthomas/entityx.png)](https://travis-ci.org/alecthomas/entityx) [![Build status](https://ci.appveyor.com/api/projects/status/qc8s0pqb5ci092iv/branch/master)](https://ci.appveyor.com/project/alecthomas/entityx/branch/master) [![Gitter chat](https://badges.gitter.im/alecthomas.png)](https://gitter.im/alecthomas/Lobby)\n\n\n***NOTE: The current stable release 1.0.0 breaks backward compatibility with \u003c 1.0.0. See the [change log](CHANGES.md) for details.***\n\nEntity Component Systems (ECS) are a form of decomposition that completely decouples entity logic and data from the entity \"objects\" themselves. The [Evolve your Hierarchy](http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/) article provides a solid overview of EC systems and why you should use them.\n\nEntityX is an EC system that uses C++11 features to provide type-safe component management, event delivery, etc. It was built during the creation of a 2D space shooter.\n\n## Downloading\n\nYou can acquire stable releases [here](https://github.com/alecthomas/entityx/releases).\n\nAlternatively, you can check out the current development version with:\n\n```\ngit clone https://github.com/alecthomas/entityx.git\n```\n\nSee [below](#installation) for installation instructions.\n\n## Contact\n\nFeel free to jump on my [Gitter channel](https://gitter.im/alecthomas/Lobby) if you have any questions/comments. This is a single channel for all of my projects, so please mention you're asking about EntityX to avoid (my) confusion.\n\nYou can also contact me directly via [email](mailto:alec@swapoff.org) or [Twitter](https://twitter.com/alecthomas).\n\n## Benchmarks / Comparisons\n\nEntityX includes its own benchmarks, but @abeimler has created [a benchmark suite](https://github.com/abeimler/ecs_benchmark/blob/master/doc/BenchmarkResultDetails2.md) testing up to 2M entities in EntityX, the EntityX compile-time branch, Anax, and Artemis C++.\n\n## Recent Notable Changes\n\n- 2014-03-02 - (1.0.0alpha1) Switch to using cache friendly component storage (big breaking change). Also eradicated use of `std::shared_ptr` for components.\n- 2014-02-13 - Visual C++ support thanks to [Jarrett Chisholm](https://github.com/jarrettchisholm)!\n- 2013-10-29 - Boost has been removed as a primary dependency for builds not using python.\n- 2013-08-21 - Remove dependency on `boost::signal` and switch to embedded [Simple::Signal](http://timj.testbit.eu/2013/cpp11-signal-system-performance/).\n- 2013-08-18 - Destroying an entity invalidates all other references\n- 2013-08-17 - Python scripting, and a more robust build system\n\nSee the [ChangeLog](https://github.com/alecthomas/entityx/blob/master/CHANGES.md) for details.\n\n## EntityX extensions and example applications\n\n- [Will Usher](https://github.com/Twinklebear) has also written an [Asteroids clone](https://github.com/Twinklebear/asteroids).\n- [Roc Solid Productions](https://github.com/RocSolidProductions) have written a [space shooter](https://github.com/RocSolidProductions/Space-Shooter)!\n- Giovani Milanez's first [game](https://github.com/giovani-milanez/SpaceTD).\n- [A game](https://github.com/ggc87/BattleCity2014) using Ogre3D and EntityX.\n\n**DEPRECATED - 0.1.x ONLY**\n\n- [Wu Zhenwei](https://github.com/acaly) has written [Lua bindings](https://github.com/acaly/entityx_lua) for EntityX, allowing entity logic to be extended through Lua scripts.\n- [Python bindings](https://github.com/alecthomas/entityx_python) allowing entity logic to be extended through Python scripts.\n- [Rodrigo Setti](https://github.com/rodrigosetti) has written an OpenGL [Asteroids clone](https://github.com/rodrigosetti/azteroids) which uses EntityX.\n\n## Example\n\nAn SFML2 example application is [available](/examples/example.cc) that shows most of EntityX's concepts. It spawns random circles on a 2D plane moving in random directions. If two circles collide they will explode and emit particles. All circles and particles are entities.\n\nIt illustrates:\n\n- Separation of data via components.\n- Separation of logic via systems.\n- Use of events (colliding bodies trigger a CollisionEvent).\n\nCompile with:\n\n    c++ -O3 -std=c++11 -Wall -lsfml-system -lsfml-window -lsfml-graphics -lentityx example.cc -o example\n\nOr enable the CMake option ENTITYX_ENABLE_EXAMPLE_TARGET to enable the 'entityx_example' target which\nfetches SFML and builds the example.\n\n## Overview\n\nIn EntityX data associated with an entity is called a `entityx::Component`. `Systems` encapsulate logic and can use as many component types as necessary. An `entityx::EventManager` allows systems to interact without being tightly coupled. Finally, a `Manager` object ties all of the systems together for convenience.\n\nAs an example, a physics system might need *position* and *mass* data, while a collision system might only need *position* - the data would be logically separated into two components, but usable by any system. The physics system might emit *collision* events whenever two entities collide.\n\n## Tutorial\n\nFollowing is some skeleton code that implements `Position` and `Direction` components, a `MovementSystem` using these data components, and a `CollisionSystem` that emits `Collision` events when two entities collide.\n\nTo start with, add the following line to your source file:\n\n```c++\n#include \"entityx/entityx.h\"\n```\n\n### Entities\n\nAn `entityx::Entity` is a convenience class wrapping an opaque `uint64_t` value allocated by the `entityx::EntityManager`. Each entity has a set of components associated with it that can be added, queried or retrieved directly.\n\nCreating an entity is as simple as:\n\n```c++\n#include \u003centityx/entityx.h\u003e\n\nentityx::EntityX ex;\n\nentityx::Entity entity = ex.entities.create();\n```\n\nAnd destroying an entity is done with:\n\n```c++\nentity.destroy();\n```\n\n#### Implementation details\n\n- Each `entityx::Entity` is a convenience class wrapping an `entityx::Entity::Id`.\n- An `entityx::Entity` handle can be invalidated with `invalidate()`. This does not affect the underlying entity.\n- When an entity is destroyed the manager adds its ID to a free list and invalidates the `entityx::Entity` handle.\n- When an entity is created IDs are recycled from the free list first, before allocating new ones.\n- An `entityx::Entity` ID contains an index and a version. When an entity is destroyed, the version associated with the index is incremented, invalidating all previous entities referencing the previous ID.\n- To improve cache coherence, components are constructed in contiguous memory ranges by using `entityx::EntityManager::assign\u003cC\u003e(id, ...)`.\n\n### Components (entity data)\n\nThe general idea with the EntityX interpretation of ECS is to have as little logic in components as possible. All logic should be contained in Systems.\n\nTo that end Components are typically [POD types](http://en.wikipedia.org/wiki/Plain_Old_Data_Structures) consisting of self-contained sets of related data. Components can be any user defined struct/class.\n\n#### Creating components\n\nAs an example, position and direction information might be represented as:\n\n```c++\nstruct Position {\n  Position(float x = 0.0f, float y = 0.0f) : x(x), y(y) {}\n\n  float x, y;\n};\n\nstruct Direction {\n  Direction(float x = 0.0f, float y = 0.0f) : x(x), y(y) {}\n\n  float x, y;\n};\n```\n\n#### Assigning components to entities\n\nTo associate a component with a previously created entity call ``entityx::Entity::assign\u003cC\u003e()`` with the component type, and any component constructor arguments:\n\n```c++\n// Assign a Position with x=1.0f and y=2.0f to \"entity\"\nentity.assign\u003cPosition\u003e(1.0f, 2.0f);\n```\n\n#### Querying entities and their components\n\nTo query all entities with a set of components assigned you can use two\nmethods. Both methods will return only those entities that have *all* of the\nspecified components associated with them.\n\n`entityx::EntityManager::each(f)` provides functional-style iteration over\nentity components:\n\n```c++\nentities.each\u003cPosition, Direction\u003e([](Entity entity, Position \u0026position, Direction \u0026direction) {\n  // Do things with entity, position and direction.\n});\n```\n\n\nFor iterator-style traversal of components, use\n``entityx::EntityManager::entities_with_components()``:\n\n```c++\nComponentHandle\u003cPosition\u003e position;\nComponentHandle\u003cDirection\u003e direction;\nfor (Entity entity : entities.entities_with_components(position, direction)) {\n  // Do things with entity, position and direction.\n}\n```\n\nTo retrieve a component associated with an entity use ``entityx::Entity::component\u003cC\u003e()``:\n\n```c++\nComponentHandle\u003cPosition\u003e position = entity.component\u003cPosition\u003e();\nif (position) {\n  // Do stuff with position\n}\n```\n\n#### Component dependencies\n\nIn the case where a component has dependencies on other components, a helper class exists that will automatically create these dependencies.\n\neg. The following will also add `Position` and `Direction` components when a `Physics` component is added to an entity.\n\n```c++\n#include \"entityx/deps/Dependencies.h\"\n\nsystem_manager-\u003eadd\u003centityx::deps::Dependency\u003cPhysics, Position, Direction\u003e\u003e();\n```\n\n#### Implementation notes\n\n- Components must provide a no-argument constructor.\n- The default implementation can handle up to 64 components in total. This can be extended by changing the `entityx::EntityManager::MAX_COMPONENTS` constant.\n- Each type of component is allocated in (mostly) contiguous blocks to improve cache coherency.\n\n### Systems (implementing behavior)\n\nSystems implement behavior using one or more components. Implementations are subclasses of `System\u003cT\u003e` and *must* implement the `update()` method, as shown below.\n\nA basic movement system might be implemented with something like the following:\n\n```c++\nstruct MovementSystem : public System\u003cMovementSystem\u003e {\n  void update(entityx::EntityManager \u0026es, entityx::EventManager \u0026events, TimeDelta dt) override {\n    es.each\u003cPosition, Direction\u003e([dt](Entity entity, Position \u0026position, Direction \u0026direction) {\n      position.x += direction.x * dt;\n      position.y += direction.y * dt;\n    });\n  };\n};\n```\n\n### Events (communicating between systems)\n\nEvents are objects emitted by systems, typically when some condition is met. Listeners subscribe to an event type and will receive a callback for each event object emitted. An ``entityx::EventManager`` coordinates subscription and delivery of events between subscribers and emitters. Typically subscribers will be other systems, but need not be.\nEvents are not part of the original ECS pattern, but they are an efficient alternative to component flags for sending infrequent data.\n\nAs an example, we might want to implement a very basic collision system using our ``Position`` data from above.\n\n#### Creating event types\n\nFirst, we define the event type, which for our example is simply the two entities that collided:\n\n```c++\nstruct Collision {\n  Collision(entityx::Entity left, entityx::Entity right) : left(left), right(right) {}\n\n  entityx::Entity left, right;\n};\n```\n\n#### Emitting events\n\nNext we implement our collision system, which emits ``Collision`` objects via an ``entityx::EventManager`` instance whenever two entities collide.\n\n```c++\nclass CollisionSystem : public System\u003cCollisionSystem\u003e {\n public:\n  void update(entityx::EntityManager \u0026es, entityx::EventManager \u0026events, TimeDelta dt) override {\n    ComponentHandle\u003cPosition\u003e left_position, right_position;\n    for (Entity left_entity : es.entities_with_components(left_position)) {\n      for (Entity right_entity : es.entities_with_components(right_position)) {\n        if (collide(left_position, right_position)) {\n          events.emit\u003cCollision\u003e(left_entity, right_entity);\n        }\n      }\n    }\n  };\n};\n```\n\n#### Subscribing to events\n\nObjects interested in receiving collision information can subscribe to ``Collision`` events by first subclassing the CRTP class ``Receiver\u003cT\u003e``:\n\n```c++\nstruct DebugSystem : public System\u003cDebugSystem\u003e, public Receiver\u003cDebugSystem\u003e {\n  void configure(entityx::EventManager \u0026event_manager) {\n    event_manager.subscribe\u003cCollision\u003e(*this);\n  }\n\n  void update(entityx::EntityManager \u0026entities, entityx::EventManager \u0026events, TimeDelta dt) {}\n\n  void receive(const Collision \u0026collision) {\n    LOG(DEBUG) \u003c\u003c \"entities collided: \" \u003c\u003c collision.left \u003c\u003c \" and \" \u003c\u003c collision.right \u003c\u003c endl;\n  }\n};\n```\n\n#### Builtin events\n\nSeveral events are emitted by EntityX itself:\n\n- `EntityCreatedEvent` - emitted when a new entityx::Entity has been created.\n  - `entityx::Entity entity` - Newly created entityx::Entity.\n- `EntityDestroyedEvent` - emitted when an entityx::Entity is *about to be* destroyed.\n  - `entityx::Entity entity` - entityx::Entity about to be destroyed.\n- `ComponentAddedEvent\u003cC\u003e` - emitted when a new component is added to an entity.\n  - `entityx::Entity entity` - entityx::Entity that component was added to.\n  - `ComponentHandle\u003cC\u003e component` - The component added.\n- `ComponentRemovedEvent\u003cC\u003e` - emitted when a component is removed from an entity.\n  - `entityx::Entity entity` - entityx::Entity that component was removed from.\n  - `ComponentHandle\u003cC\u003e component` - The component removed.\n\n#### Implementation notes\n\n- There can be more than one subscriber for an event; each one will be called.\n- Event objects are destroyed after delivery, so references should not be retained.\n- A single class can receive any number of types of events by implementing a ``receive(const EventType \u0026)`` method for each event type.\n- Any class implementing `Receiver` can receive events, but typical usage is to make `System`s also be `Receiver`s.\n- When an `Entity` is destroyed it will cause all of its components to be removed. This triggers `ComponentRemovedEvent`s to be triggered for each of its components. These events are triggered before the `EntityDestroyedEvent`.\n\n### Manager (tying it all together)\n\nManaging systems, components and entities can be streamlined by using the\n\"quick start\" class `EntityX`. It simply provides pre-initialized\n`EventManager`, `EntityManager` and `SystemManager` instances.\n\nTo use it, subclass `EntityX`:\n\n```c++\nclass Level : public EntityX {\npublic:\n  explicit Level(filename string) {\n    systems.add\u003cDebugSystem\u003e();\n    systems.add\u003cMovementSystem\u003e();\n    systems.add\u003cCollisionSystem\u003e();\n    systems.configure();\n\n    level.load(filename);\n\n    for (auto e : level.entity_data()) {\n      entityx::Entity entity = entities.create();\n      entity.assign\u003cPosition\u003e(rand() % 100, rand() % 100);\n      entity.assign\u003cDirection\u003e((rand() % 10) - 5, (rand() % 10) - 5);\n    }\n  }\n\n  void update(TimeDelta dt) {\n    systems.update\u003cDebugSystem\u003e(dt);\n    systems.update\u003cMovementSystem\u003e(dt);\n    systems.update\u003cCollisionSystem\u003e(dt);\n  }\n\n  Level level;\n};\n```\n\n\nYou can then step the entities explicitly inside your own game loop:\n\n```c++\nwhile (true) {\n  level.update(0.1);\n}\n```\n\n## Installation\n\n### Arch Linux\n\n    pacman -S entityx\n\n### OSX\n\n    brew install entityx\n\n### Windows\n\nBuild it manually.\n\nRequirements:\n\n* [Visual Studio 2015](https://www.visualstudio.com/en-us/downloads/visual-studio-2015-downloads-vs.aspx) or later, or a C++ compiler that supports a basic set of C++11 features (ie. Clang \u003e= 3.1 or GCC \u003e= 4.7).\n* [CMake](http://cmake.org/)\n\n### Building entityx - Using vcpkg\n\nYou can download and install entityx using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:\n\n    git clone https://github.com/Microsoft/vcpkg.git\n    cd vcpkg\n    ./bootstrap-vcpkg.sh\n    ./vcpkg integrate install\n    ./vcpkg install entityx\n\nThe entityx 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](https://github.com/Microsoft/vcpkg) on the vcpkg repository.\n\n### Other systems\n\nBuild it manually.\n\nRequirements:\n\n* A C++ compiler that supports a basic set of C++11 features (ie. Clang \u003e= 3.1, GCC \u003e= 4.7).\n* [CMake](http://cmake.org/)\n\n### C++11 compiler and library support\n\nC++11 support is quite...raw. To make life more interesting, C++ support really means two things: language features supported by the compiler, and library features. EntityX tries to support the most common options, including the default C++ library for the compiler/platform, and libstdc++.\n\n### Installing on Ubuntu 12.04\n\nOn Ubuntu LTS (12.04, Precise) you will need to add some PPAs to get either clang-3.1 or gcc-4.7. Respective versions prior to these do not work.\n\nFor gcc-4.7:\n\n```bash\nsudo add-apt-repository -y ppa:ubuntu-toolchain-r/test\nsudo apt-get update -qq\nsudo apt-get install gcc-4.7 g++-4.7\nCC=gcc-4.7 CXX=g++4.7 cmake ...\n```\n\nFor clang-3.1 (or 3.2 or 3.3):\n\n```bash\nsudo apt-add-repository ppa:h-rayflood/llvm\nsudo apt-get update -qq\nsudo apt-get install clang-3.1\nCC=clang-3.1 CXX=clang++3.1 cmake ...\n```\n\n### Options\n\nOnce these dependencies are installed you should be able to build and install EntityX as below. The following options can be passed to cmake to modify how EntityX is built:\n\n- `-DENTITYX_RUN_BENCHMARKS=1` - In conjunction with `-DENTITYX_BUILD_TESTING=1`, also build benchmarks.\n- `-DENTITYX_MAX_COMPONENTS=64` - Override the maximum number of components that can be assigned to each entity.\n- `-DENTITYX_BUILD_SHARED=1` - Whether to build shared libraries (defaults to 1).\n- `-DENTITYX_BUILD_TESTING=1` - Whether to build tests (defaults to 0). Run with \"make \u0026\u0026 make test\".\n- `-DENTITYX_DT_TYPE=double` - The type used for delta time in EntityX update methods.\n\nOnce you have selected your flags, build and install with:\n\n```sh\nmkdir build\ncd build\ncmake \u003cflags\u003e ..\nmake\nmake install\n```\n\nEntityX has currently only been tested on Mac OSX (Lion and Mountain Lion), Linux Debian 12.04 and Arch Linux. Reports and patches for builds on other platforms are welcome.\n","funding_links":["https://github.com/sponsors/alecthomas"],"categories":["TODO scan for Android support in followings","[ECS Libraries](#contents)","ECS Libraries","Libraries \u0026 Frameworks:","C++","GameProgramming","Libraries"],"sub_categories":["ECS","C++"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falecthomas%2Fentityx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falecthomas%2Fentityx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falecthomas%2Fentityx/lists"}