- # EntityX - A fast, type-safe C++ Entity Component System \r
- \r
- [](https://travis-ci.org/alecthomas/entityx)\r
- \r
- Entity 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.\r
- \r
- EntityX 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.\r
- \r
- ## Contact\r
- \r
- EntityX now has a mailing list! Send a mail to [entityx@librelist.com](mailto:entityx@librelist.com) to subscribe. Instructions will follow.\r
- \r
- You can also contact me directly via [email](mailto:alec@swapoff.org) or [Twitter](https://twitter.com/alecthomas).\r
- \r
- \r
- ## Recent Notable Changes\r
- \r
- - 2013-10-29 - The 'no-boost' branch now exists to remove boost as a dependency for builds not using python.\r
- - 2013-08-21 - Remove dependency on `boost::signal` and switch to embedded [Simple::Signal](http://timj.testbit.eu/2013/cpp11-signal-system-performance/).\r
- - 2013-08-18 - Destroying an entity invalidates all other references\r
- - 2013-08-17 - Python scripting, and a more robust build system\r
- \r
- See the [ChangeLog](https://github.com/alecthomas/entityx/blob/master/CHANGES.md) for details.\r
- \r
- ## Overview\r
- \r
- In 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.\r
- \r
- As 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.\r
- \r
- ## Tutorial\r
- \r
- Following 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.\r
- \r
- To start with, add the following line to your source file:\r
- \r
- ```c++\r
- #include "entityx/entityx.h"\r
- ```\r
- \r
- ### Entities\r
- \r
- An `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.\r
- \r
- Creating an entity is as simple as:\r
- \r
- ```c++\r
- entityx::ptr<entityx::EventManager> events(new entityx::EventManager());\r
- entityx::ptr<entityx::EntityManager> entities(new entityx::EntityManager(event));\r
- \r
- entityx::Entity entity = entities->create();\r
- ```\r
- \r
- And destroying an entity is done with:\r
- \r
- ```c++\r
- entity.destroy();\r
- ```\r
- \r
- #### Implementation details\r
- \r
- - Each `entityx::Entity` is a convenience class wrapping an `entityx::Entity::Id`.\r
- - An `entityx::Entity` handle can be invalidated with `invalidate()`. This does not affect the underlying entity.\r
- - When an entity is destroyed the manager adds its ID to a free list and invalidates the `entityx::Entity` handle.\r
- - When an entity is created IDs are recycled from the free list before allocating new ones.\r
- - 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.\r
- - EntityX uses a reference counting smart pointer`entityx::ptr<T>` to manage object lifetimes. As a general rule, passing a pointer to any EntityX method will convert to a smart pointer and take ownership. To maintain your own reference to the pointer you will need to wrap it in `entityx::ptr<T>`.\r
- \r
- ### Components (entity data)\r
- \r
- The general idea with the EntityX interpretation of ECS is to have as little functionality in components as possible. All logic should be contained in Systems.\r
- \r
- To that end Components are typically [POD types](http://en.wikipedia.org/wiki/Plain_Old_Data_Structures) consisting of self-contained sets of related data. Implementations are [curiously recurring template pattern](http://en.wikipedia.org/wiki/Curiously_recurring_template_pattern) (CRTP) subclasses of `entityx::Component<T>`.\r
- \r
- #### Creating components\r
- \r
- As an example, position and direction information might be represented as:\r
- \r
- ```c++\r
- struct Position : entityx::Component<Position> {\r
- Position(float x = 0.0f, float y = 0.0f) : x(x), y(y) {}\r
- \r
- float x, y;\r
- };\r
- \r
- struct Direction : entityx::Component<Direction> {\r
- Direction(float x = 0.0f, float y = 0.0f) : x(x), y(y) {}\r
- \r
- float x, y;\r
- };\r
- ```\r
- \r
- #### Assigning components to entities\r
- \r
- To associate a component with a previously created entity call ``entityx::Entity::assign<C>()`` with the component type, and any component constructor arguments:\r
- \r
- ```c++\r
- // Assign a Position with x=1.0f and y=2.0f to "entity"\r
- entity.assign<Position>(1.0f, 2.0f);\r
- ```\r
- \r
- You can also assign existing instances of components:\r
- \r
- ```c++\r
- entityx::ptr<Position> position = new Position(1.0f, 2.0f);\r
- entity.assign(position);\r
- ```\r
- \r
- #### Querying entities and their components\r
- \r
- To query all entities with a set of components assigned, use ``entityx::EntityManager::entities_with_components()``. This method will return only those entities that have *all* of the specified components associated with them, assigning each component pointer to the corresponding component instance:\r
- \r
- ```c++\r
- for (auto entity : entities->entities_with_components<Position, Direction>()) {\r
- entityx::ptr<Position> position = entity.component<Position>();\r
- entityx::ptr<Direction> direction = entity.component<Direction>();\r
- \r
- // Do things with entity, position and direction.\r
- }\r
- ```\r
- \r
- To retrieve a component associated with an entity use ``entityx::Entity::component<C>()``:\r
- \r
- ```c++\r
- entityx::ptr<Position> position = entity.component<Position>();\r
- if (position) {\r
- // Do stuff with position\r
- }\r
- ```\r
- \r
- #### Component dependencies\r
- \r
- In the case where a component has dependencies on other components, a helper class exists that will automatically create these dependencies.\r
- \r
- eg. The following will also add `Position` and `Direction` components when a `Physics` component is added to an entity.\r
- \r
- ```c++\r
- #include "entityx/deps/Dependency.h"\r
- \r
- system_manager->add<entityx::deps::Depdendency<Physics, Position, Direction>>();\r
- ```\r
- \r
- #### Implementation notes\r
- \r
- - Components must provide a no-argument constructor.\r
- - The default implementation can handle up to 64 components in total. This can be extended by changing the `entityx::EntityManager::MAX_COMPONENTS` constant.\r
- \r
- ### Systems (implementing behavior)\r
- \r
- Systems implement behavior using one or more components. Implementations are subclasses of `System<T>` and *must* implement the `update()` method, as shown below.\r
- \r
- A basic movement system might be implemented with something like the following:\r
- \r
- ```c++\r
- struct MovementSystem : public System<MovementSystem> {\r
- void update(entityx::ptr<entityx::EntityManager> es, entityx::ptr<entityx::EventManager> events, double dt) override {\r
- for (auto entity : es->entities_with_components<Position, Direction>()) {\r
- entityx::ptr<Position> position = entity.component<Position>();\r
- entityx::ptr<Direction> direction = entity.component<Direction>();\r
- \r
- position->x += direction->x * dt;\r
- position->y += direction->y * dt;\r
- }\r
- }\r
- };\r
- ```\r
- \r
- ### Events (communicating between systems)\r
- \r
- Events 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.\r
- Events are not part of the original ECS pattern, but they are an efficient alternative to component flags for sending infrequent data.\r
- \r
- As an example, we might want to implement a very basic collision system using our ``Position`` data from above.\r
- \r
- #### Creating event types\r
- \r
- First, we define the event type, which for our example is simply the two entities that collided:\r
- \r
- ```c++\r
- struct Collision : public Event<Collision> {\r
- Collision(entityx::Entity left, entityx::Entity right) : left(left), right(right) {}\r
- \r
- entityx::Entity left, right;\r
- };\r
- ```\r
- \r
- #### Emitting events\r
- \r
- Next we implement our collision system, which emits ``Collision`` objects via an ``entityx::EventManager`` instance whenever two entities collide.\r
- \r
- ```c++\r
- class CollisionSystem : public System<CollisionSystem> {\r
- public:\r
- void update(entityx::ptr<entityx::EntityManager> es, entityx::ptr<entityx::EventManager> events, double dt) override {\r
- entityx::ptr<Position> left_position, right_position;\r
- for (auto left_entity : es->entities_with_components<Position>(left_position)) {\r
- for (auto right_entity : es->entities_with_components<Position>(right_position)) {\r
- if (collide(left_position, right_position)) {\r
- events->emit<Collision>(left_entity, right_entity);\r
- }\r
- }\r
- }\r
- }\r
- };\r
- ```\r
- \r
- #### Subscribing to events\r
- \r
- Objects interested in receiving collision information can subscribe to ``Collision`` events by first subclassing the CRTP class ``Receiver<T>``:\r
- \r
- ```c++\r
- struct DebugSystem : public System<DebugSystem>, Receiver<DebugSystem> {\r
- void configure(entityx::ptr<entityx::EventManager> event_manager) {\r
- event_manager->subscribe<Collision>(*this);\r
- }\r
- \r
- void update(ptr<entityx::EntityManager> entities, ptr<entityx::EventManager> events, double dt) {}\r
- \r
- void receive(const Collision &collision) {\r
- LOG(DEBUG) << "entities collided: " << collision.left << " and " << collision.right << endl;\r
- }\r
- };\r
- ```\r
- \r
- #### Builtin events\r
- \r
- Several events are emitted by EntityX itself:\r
- \r
- - `EntityCreatedEvent` - emitted when a new entityx::Entity has been created.\r
- - `entityx::Entity entity` - Newly created entityx::Entity.\r
- - `EntityDestroyedEvent` - emitted when an entityx::Entity is *about to be* destroyed.\r
- - `entityx::Entity entity` - entityx::Entity about to be destroyed.\r
- - `ComponentAddedEvent<T>` - emitted when a new component is added to an entity.\r
- - `entityx::Entity entity` - entityx::Entity that component was added to.\r
- - `entityx::ptr<T> component` - The component added.\r
- - `ComponentRemovedEvent<T>` - emitted when a component is removed from an entity.\r
- - `entityx::Entity entity` - entityx::Entity that component was removed from.\r
- - `entityx::ptr<T> component` - The component removed.\r
- \r
- #### Implementation notes\r
- \r
- - There can be more than one subscriber for an event; each one will be called.\r
- - Event objects are destroyed after delivery, so references should not be retained.\r
- - A single class can receive any number of types of events by implementing a ``receive(const EventType &)`` method for each event type.\r
- - Any class implementing `Receiver` can receive events, but typical usage is to make `System`s also be `Receiver`s.\r
- \r
- ### Manager (tying it all together)\r
- \r
- Managing systems, components and entities can be streamlined by subclassing `Manager`. It is not necessary, but it provides callbacks for configuring systems, initializing entities, and so on.\r
- \r
- To use it, subclass `Manager` and implement `configure()`, `initialize()` and `update()`:\r
- \r
- ```c++\r
- class GameManager : public Manager {\r
- protected:\r
- void configure() {\r
- system_manager->add<DebugSystem>();\r
- system_manager->add<MovementSystem>();\r
- system_manager->add<CollisionSystem>();\r
- system_manager->configure();\r
- }\r
- \r
- void initialize() {\r
- // Create some entities in random locations heading in random directions\r
- for (int i = 0; i < 100; ++i) {\r
- entityx::Entity entity = entity_manager->create();\r
- entity.assign<Position>(rand() % 100, rand() % 100);\r
- entity.assign<Direction>((rand() % 10) - 5, (rand() % 10) - 5);\r
- }\r
- }\r
- \r
- void update(double dt) {\r
- system_manager->update<MovementSystem>(dt);\r
- system_manager->update<CollisionSystem>(dt);\r
- }\r
- };\r
- ```\r
- \r
- ## Installation\r
- \r
- EntityX has the following build and runtime requirements:\r
- \r
- - A C++ compiler that supports a basic set of C++11 features (ie. Clang >= 3.1, GCC >= 4.7, and maybe (untested) VC++ with the [Nov 2012 CTP](http://www.microsoft.com/en-us/download/details.aspx?id=35515)).\r
- - [CMake](http://cmake.org/)\r
- \r
- ### C++11 compiler and library support\r
- \r
- C++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.\r
- \r
- ### Installing on OSX Mountain Lion\r
- \r
- On OSX you must use Clang as the GCC version is practically prehistoric.\r
- \r
- EntityX can build against libstdc++ (GCC with no C++11 library support) or libc++ (Clang with C++11 library support), though you will need to ensure that Boost is built with the same standard library.\r
- \r
- I use Homebrew, and the following works for me:\r
- \r
- For libstdc++:\r
- \r
- ```bash\r
- cmake -DENTITYX_BUILD_SHARED=0 -DENTITYX_BUILD_TESTING=1 -DENTITYX_USE_CPP11_STDLIB=0 ..\r
- ```\r
- \r
- For libc++ (with C++11 support):\r
- \r
- ```bash\r
- cmake -DENTITYX_BUILD_SHARED=0 -DENTITYX_BUILD_TESTING=1 -DENTITYX_USE_CPP11_STDLIB=1 ..\r
- ```\r
- \r
- ### Installing on Ubuntu 12.04\r
- \r
- On 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.\r
- \r
- For gcc-4.7:\r
- \r
- ```bash\r
- sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test\r
- sudo apt-get update -qq\r
- sudo apt-get install gcc-4.7 g++4.7\r
- CC=gcc-4.7 CXX=g++4.7 cmake ...\r
- ```\r
- \r
- For clang-3.1 (or 3.2 or 3.3):\r
- \r
- ```bash\r
- sudo apt-add-repository ppa:h-rayflood/llvm\r
- sudo apt-get update -qq\r
- sudo apt-get install clang-3.1\r
- CC=clang-3.1 CXX=clang++3.1 cmake ...\r
- ```\r
- \r
- ### Options\r
- \r
- Once 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:\r
- \r
- - `-DENTITYX_BUILD_PYTHON=1` - Build Python scripting integration.\r
- - `-DENTITYX_BUILD_TESTING=1` - Build tests (run with `make test`).\r
- - `-DENTITYX_RUN_BENCHMARKS=1` - In conjunction with `-DENTITYX_BUILD_TESTING=1`, also build benchmarks.\r
- - `-DENTITYX_USE_CPP11_STDLIB=1` - For Clang, specify whether to use `-stdlib=libc++`.\r
- - `-DENTITYX_MAX_COMPONENTS=64` - Override the maximum number of components that can be assigned to each entity.\r
- - `-DENTITYX_BUILD_SHARED=1` - Whether to build shared libraries (defaults to 1).\r
- - `-DENTITYX_BUILD_TESTING=0` - Whether to build tests (defaults to 0). Run with "make && make test".\r
- \r
- Once you have selected your flags, build and install with:\r
- \r
- ```sh\r
- mkdir build\r
- cd build\r
- cmake <flags> ..\r
- make\r
- make install\r
- ```\r
- \r
- EntityX has currently only been tested on Mac OSX (Lion and Mountain Lion), and Linux Debian 12.04. Reports and patches for builds on other platforms are welcome.\r
-# EntityX - A fast, type-safe C++ Entity Component System
++# EntityX - A fast, type-safe C++ Entity Component System
+
+ [](https://travis-ci.org/alecthomas/entityx)
+
+ Entity 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.
+
+ EntityX 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.
+
+ ## Contact
+
+ EntityX now has a mailing list! Send a mail to [entityx@librelist.com](mailto:entityx@librelist.com) to subscribe. Instructions will follow.
+
+ You can also contact me directly via [email](mailto:alec@swapoff.org) or [Twitter](https://twitter.com/alecthomas).
+
+
+ ## Recent Notable Changes
+
++- 2013-10-29 - Boost has been removed as a primary dependency for builds not using python.
+ - 2013-08-21 - Remove dependency on `boost::signal` and switch to embedded [Simple::Signal](http://timj.testbit.eu/2013/cpp11-signal-system-performance/).
+ - 2013-08-18 - Destroying an entity invalidates all other references
+ - 2013-08-17 - Python scripting, and a more robust build system
+
+ See the [ChangeLog](https://github.com/alecthomas/entityx/blob/master/CHANGES.md) for details.
+
+ ## Overview
+
+ In 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.
+
+ As 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.
+
+ ## Tutorial
+
+ Following 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.
+
+ To start with, add the following line to your source file:
+
+ ```c++
+ #include "entityx/entityx.h"
+ ```
+
+ ### Entities
+
+ An `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.
+
+ Creating an entity is as simple as:
+
+ ```c++
+ entityx::ptr<entityx::EventManager> events(new entityx::EventManager());
+ entityx::ptr<entityx::EntityManager> entities(new entityx::EntityManager(event));
+
+ entityx::Entity entity = entities->create();
+ ```
+
+ And destroying an entity is done with:
+
+ ```c++
+ entity.destroy();
+ ```
+
+ #### Implementation details
+
+ - Each `entityx::Entity` is a convenience class wrapping an `entityx::Entity::Id`.
+ - An `entityx::Entity` handle can be invalidated with `invalidate()`. This does not affect the underlying entity.
+ - When an entity is destroyed the manager adds its ID to a free list and invalidates the `entityx::Entity` handle.
+ - When an entity is created IDs are recycled from the free list before allocating new ones.
+ - 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.
+ - EntityX uses a reference counting smart pointer`entityx::ptr<T>` to manage object lifetimes. As a general rule, passing a pointer to any EntityX method will convert to a smart pointer and take ownership. To maintain your own reference to the pointer you will need to wrap it in `entityx::ptr<T>`.
+
+ ### Components (entity data)
+
+ The general idea with the EntityX interpretation of ECS is to have as little functionality in components as possible. All logic should be contained in Systems.
+
+ To that end Components are typically [POD types](http://en.wikipedia.org/wiki/Plain_Old_Data_Structures) consisting of self-contained sets of related data. Implementations are [curiously recurring template pattern](http://en.wikipedia.org/wiki/Curiously_recurring_template_pattern) (CRTP) subclasses of `entityx::Component<T>`.
+
+ #### Creating components
+
+ As an example, position and direction information might be represented as:
+
+ ```c++
+ struct Position : entityx::Component<Position> {
+ Position(float x = 0.0f, float y = 0.0f) : x(x), y(y) {}
+
+ float x, y;
+ };
+
+ struct Direction : entityx::Component<Direction> {
+ Direction(float x = 0.0f, float y = 0.0f) : x(x), y(y) {}
+
+ float x, y;
+ };
+ ```
+
+ #### Assigning components to entities
+
+ To associate a component with a previously created entity call ``entityx::Entity::assign<C>()`` with the component type, and any component constructor arguments:
+
+ ```c++
+ // Assign a Position with x=1.0f and y=2.0f to "entity"
+ entity.assign<Position>(1.0f, 2.0f);
+ ```
+
+ You can also assign existing instances of components:
+
+ ```c++
+ entityx::ptr<Position> position = new Position(1.0f, 2.0f);
+ entity.assign(position);
+ ```
+
+ #### Querying entities and their components
+
+ To query all entities with a set of components assigned, use ``entityx::EntityManager::entities_with_components()``. This method will return only those entities that have *all* of the specified components associated with them, assigning each component pointer to the corresponding component instance:
+
+ ```c++
+ for (auto entity : entities->entities_with_components<Position, Direction>()) {
+ entityx::ptr<Position> position = entity.component<Position>();
+ entityx::ptr<Direction> direction = entity.component<Direction>();
+
+ // Do things with entity, position and direction.
+ }
+ ```
+
+ To retrieve a component associated with an entity use ``entityx::Entity::component<C>()``:
+
+ ```c++
+ entityx::ptr<Position> position = entity.component<Position>();
+ if (position) {
+ // Do stuff with position
+ }
+ ```
+
+ #### Component dependencies
+
+ In the case where a component has dependencies on other components, a helper class exists that will automatically create these dependencies.
+
+ eg. The following will also add `Position` and `Direction` components when a `Physics` component is added to an entity.
+
+ ```c++
+ #include "entityx/deps/Dependencies.h"
+
+ system_manager->add<entityx::deps::Depdendency<Physics, Position, Direction>>();
+ ```
+
+ #### Implementation notes
+
+ - Components must provide a no-argument constructor.
+ - The default implementation can handle up to 64 components in total. This can be extended by changing the `entityx::EntityManager::MAX_COMPONENTS` constant.
+
+ ### Systems (implementing behavior)
+
+ Systems implement behavior using one or more components. Implementations are subclasses of `System<T>` and *must* implement the `update()` method, as shown below.
+
+ A basic movement system might be implemented with something like the following:
+
+ ```c++
+ struct MovementSystem : public System<MovementSystem> {
+ void update(entityx::ptr<entityx::EntityManager> es, entityx::ptr<entityx::EventManager> events, double dt) override {
+ for (auto entity : es->entities_with_components<Position, Direction>()) {
+ entityx::ptr<Position> position = entity.component<Position>();
+ entityx::ptr<Direction> direction = entity.component<Direction>();
+
+ position->x += direction->x * dt;
+ position->y += direction->y * dt;
+ }
+ }
+ };
+ ```
+
+ ### Events (communicating between systems)
+
+ Events 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.
+ Events are not part of the original ECS pattern, but they are an efficient alternative to component flags for sending infrequent data.
+
+ As an example, we might want to implement a very basic collision system using our ``Position`` data from above.
+
+ #### Creating event types
+
+ First, we define the event type, which for our example is simply the two entities that collided:
+
+ ```c++
+ struct Collision : public Event<Collision> {
+ Collision(entityx::Entity left, entityx::Entity right) : left(left), right(right) {}
+
+ entityx::Entity left, right;
+ };
+ ```
+
+ #### Emitting events
+
+ Next we implement our collision system, which emits ``Collision`` objects via an ``entityx::EventManager`` instance whenever two entities collide.
+
+ ```c++
+ class CollisionSystem : public System<CollisionSystem> {
+ public:
+ void update(entityx::ptr<entityx::EntityManager> es, entityx::ptr<entityx::EventManager> events, double dt) override {
+ entityx::ptr<Position> left_position, right_position;
+ for (auto left_entity : es->entities_with_components<Position>(left_position)) {
+ for (auto right_entity : es->entities_with_components<Position>(right_position)) {
+ if (collide(left_position, right_position)) {
+ events->emit<Collision>(left_entity, right_entity);
+ }
+ }
+ }
+ }
+ };
+ ```
+
+ #### Subscribing to events
+
+ Objects interested in receiving collision information can subscribe to ``Collision`` events by first subclassing the CRTP class ``Receiver<T>``:
+
+ ```c++
+ struct DebugSystem : public System<DebugSystem>, Receiver<DebugSystem> {
+ void configure(entityx::ptr<entityx::EventManager> event_manager) {
+ event_manager->subscribe<Collision>(*this);
+ }
+
+ void update(ptr<entityx::EntityManager> entities, ptr<entityx::EventManager> events, double dt) {}
+
+ void receive(const Collision &collision) {
+ LOG(DEBUG) << "entities collided: " << collision.left << " and " << collision.right << endl;
+ }
+ };
+ ```
+
+ #### Builtin events
+
+ Several events are emitted by EntityX itself:
+
+ - `EntityCreatedEvent` - emitted when a new entityx::Entity has been created.
+ - `entityx::Entity entity` - Newly created entityx::Entity.
+ - `EntityDestroyedEvent` - emitted when an entityx::Entity is *about to be* destroyed.
+ - `entityx::Entity entity` - entityx::Entity about to be destroyed.
+ - `ComponentAddedEvent<T>` - emitted when a new component is added to an entity.
+ - `entityx::Entity entity` - entityx::Entity that component was added to.
+ - `entityx::ptr<T> component` - The component added.
+ - `ComponentRemovedEvent<T>` - emitted when a component is removed from an entity.
+ - `entityx::Entity entity` - entityx::Entity that component was removed from.
+ - `entityx::ptr<T> component` - The component removed.
+
+ #### Implementation notes
+
+ - There can be more than one subscriber for an event; each one will be called.
+ - Event objects are destroyed after delivery, so references should not be retained.
+ - A single class can receive any number of types of events by implementing a ``receive(const EventType &)`` method for each event type.
+ - Any class implementing `Receiver` can receive events, but typical usage is to make `System`s also be `Receiver`s.
+
+ ### Manager (tying it all together)
+
+ Managing systems, components and entities can be streamlined by subclassing `Manager`. It is not necessary, but it provides callbacks for configuring systems, initializing entities, and so on.
+
+ To use it, subclass `Manager` and implement `configure()`, `initialize()` and `update()`:
+
+ ```c++
+ class GameManager : public Manager {
+ protected:
+ void configure() {
+ system_manager->add<DebugSystem>();
+ system_manager->add<MovementSystem>();
+ system_manager->add<CollisionSystem>();
+ system_manager->configure();
+ }
+
+ void initialize() {
+ // Create some entities in random locations heading in random directions
+ for (int i = 0; i < 100; ++i) {
+ entityx::Entity entity = entity_manager->create();
+ entity.assign<Position>(rand() % 100, rand() % 100);
+ entity.assign<Direction>((rand() % 10) - 5, (rand() % 10) - 5);
+ }
+ }
+
+ void update(double dt) {
+ system_manager->update<MovementSystem>(dt);
+ system_manager->update<CollisionSystem>(dt);
+ }
+ };
+ ```
+
+ ## Installation
+
+ EntityX has the following build and runtime requirements:
+
+ - A C++ compiler that supports a basic set of C++11 features (ie. Clang >= 3.1, GCC >= 4.7, and maybe (untested) VC++ with the [Nov 2012 CTP](http://www.microsoft.com/en-us/download/details.aspx?id=35515)).
+ - [CMake](http://cmake.org/)
-- [Boost](http://boost.org) `1.48.0` (headers only unless using boost::python).
+
+ ### C++11 compiler and library support
+
+ C++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.
+
+ ### Installing on OSX Mountain Lion
+
+ On OSX you must use Clang as the GCC version is practically prehistoric.
+
+ EntityX can build against libstdc++ (GCC with no C++11 library support) or libc++ (Clang with C++11 library support), though you will need to ensure that Boost is built with the same standard library.
+
+ I use Homebrew, and the following works for me:
+
+ For libstdc++:
+
+ ```bash
-brew install boost
-cmake -DENTITYX_BUILD_SHARED=0 -DENTITYX_BUILD_TESTING=1 -DENTITYX_USE_STD_SHARED_PTR=1 -DENTITYX_USE_CPP11_STDLIB=0 ..
++cmake -DENTITYX_BUILD_SHARED=0 -DENTITYX_BUILD_TESTING=1 -DENTITYX_USE_CPP11_STDLIB=0 ..
+ ```
+
+ For libc++ (with C++11 support):
+
+ ```bash
-brew install boost --with-c++11
-cmake -DENTITYX_BUILD_SHARED=0 -DENTITYX_BUILD_TESTING=1 -DENTITYX_USE_STD_SHARED_PTR=1 -DENTITYX_USE_CPP11_STDLIB=1 ..
++cmake -DENTITYX_BUILD_SHARED=0 -DENTITYX_BUILD_TESTING=1 -DENTITYX_USE_CPP11_STDLIB=1 ..
+ ```
+
+ ### Installing on Ubuntu 12.04
+
+ On 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.
+
+ For gcc-4.7:
+
+ ```bash
+ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
+ sudo apt-get update -qq
+ sudo apt-get install gcc-4.7 g++4.7
+ CC=gcc-4.7 CXX=g++4.7 cmake ...
+ ```
+
+ For clang-3.1 (or 3.2 or 3.3):
+
+ ```bash
+ sudo apt-add-repository ppa:h-rayflood/llvm
+ sudo apt-get update -qq
+ sudo apt-get install clang-3.1
+ CC=clang-3.1 CXX=clang++3.1 cmake ...
+ ```
+
+ ### Options
+
+ Once 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:
+
+ - `-DENTITYX_BUILD_PYTHON=1` - Build Python scripting integration.
+ - `-DENTITYX_BUILD_TESTING=1` - Build tests (run with `make test`).
+ - `-DENTITYX_RUN_BENCHMARKS=1` - In conjunction with `-DENTITYX_BUILD_TESTING=1`, also build benchmarks.
+ - `-DENTITYX_USE_CPP11_STDLIB=1` - For Clang, specify whether to use `-stdlib=libc++`.
-- `-DENTITYX_USE_STD_SHARED_PTR=1` - Use `std::shared_ptr<T>` (and friends) rather than the Boost equivalents. This does not eliminate the need for Boost, but is useful if the rest of your application uses `std::shared_ptr<T>`.
+ - `-DENTITYX_MAX_COMPONENTS=64` - Override the maximum number of components that can be assigned to each entity.
+ - `-DENTITYX_BUILD_SHARED=1` - Whether to build shared libraries (defaults to 1).
+ - `-DENTITYX_BUILD_TESTING=0` - Whether to build tests (defaults to 0). Run with "make && make test".
+
-For a production build, you'll typically only need the `-DENTITYX_USE_STD_SHARED_PTR=1` flag, if any.
-
+ Once you have selected your flags, build and install with:
+
+ ```sh
+ mkdir build
+ cd build
+ cmake <flags> ..
+ make
+ make install
+ ```
+
-EntityX has currently only been tested on Mac OSX (Lion and Mountain Lion), and Linux Debian 12.04. Reports and patches for builds on other platforms are welcome.
++EntityX has currently only been tested on Mac OSX (Lion and Mountain Lion), and Linux Debian 12.04. Reports and patches for builds on other platforms are welcome.
projects / clyne / entityx.git / commitdiff