search

alecthomas / entityx

EntityX - A fast, type-safe C++ Entity-Component system
MIT License
2.23k stars 295 forks source link

readme

EntityX - A fast, type-safe C++ Entity Component System

Build Status Build status Gitter chat

NOTE: The current stable release 1.0.0 breaks backward compatibility with < 1.0.0. See the change log for details.

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 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.

Downloading

You can acquire stable releases here.

Alternatively, you can check out the current development version with:

git clone https://github.com/alecthomas/entityx.git

See below for installation instructions.

Contact

Feel free to jump on my Gitter channel 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.

You can also contact me directly via email or Twitter.

Benchmarks / Comparisons

EntityX includes its own benchmarks, but @abeimler has created a benchmark suite testing up to 2M entities in EntityX, the EntityX compile-time branch, Anax, and Artemis C++.

Recent Notable Changes

See the ChangeLog for details.

EntityX extensions and example applications

DEPRECATED - 0.1.x ONLY

Example

An SFML2 example application is available 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.

It illustrates:

Compile with:

c++ -O3 -std=c++11 -Wall -lsfml-system -lsfml-window -lsfml-graphics -lentityx example.cc -o example

Or enable the CMake option ENTITYX_ENABLE_EXAMPLE_TARGET to enable the 'entityx_example' target which fetches SFML and builds the example.

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:

#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:

#include <entityx/entityx.h>

entityx::EntityX ex;

entityx::Entity entity = ex.entities.create();

And destroying an entity is done with:

entity.destroy();

Implementation details

Components (entity data)

The 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.

To that end Components are typically POD types consisting of self-contained sets of related data. Components can be any user defined struct/class.

Creating components

As an example, position and direction information might be represented as:

struct Position {
  Position(float x = 0.0f, float y = 0.0f) : x(x), y(y) {}

  float x, y;
};

struct 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:

// Assign a Position with x=1.0f and y=2.0f to "entity"
entity.assign<Position>(1.0f, 2.0f);

Querying entities and their components

To query all entities with a set of components assigned you can use two methods. Both methods will return only those entities that have all of the specified components associated with them.

entityx::EntityManager::each(f) provides functional-style iteration over entity components:

entities.each<Position, Direction>([](Entity entity, Position &position, Direction &direction) {
  // Do things with entity, position and direction.
});

For iterator-style traversal of components, use entityx::EntityManager::entities_with_components():

ComponentHandle<Position> position;
ComponentHandle<Direction> direction;
for (Entity entity : entities.entities_with_components(position, direction)) {
  // Do things with entity, position and direction.
}

To retrieve a component associated with an entity use entityx::Entity::component<C>():

ComponentHandle<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.

#include "entityx/deps/Dependencies.h"

system_manager->add<entityx::deps::Dependency<Physics, Position, Direction>>();

Implementation notes

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:

struct MovementSystem : public System<MovementSystem> {
  void update(entityx::EntityManager &es, entityx::EventManager &events, TimeDelta dt) override {
    es.each<Position, Direction>([dt](Entity entity, Position &position, Direction &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:

struct 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.

class CollisionSystem : public System<CollisionSystem> {
 public:
  void update(entityx::EntityManager &es, entityx::EventManager &events, TimeDelta dt) override {
    ComponentHandle<Position> left_position, right_position;
    for (Entity left_entity : es.entities_with_components(left_position)) {
      for (Entity right_entity : es.entities_with_components(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>:

struct DebugSystem : public System<DebugSystem>, public Receiver<DebugSystem> {
  void configure(entityx::EventManager &event_manager) {
    event_manager.subscribe<Collision>(*this);
  }

  void update(entityx::EntityManager &entities, entityx::EventManager &events, TimeDelta 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:

Implementation notes

Manager (tying it all together)

Managing systems, components and entities can be streamlined by using the "quick start" class EntityX. It simply provides pre-initialized EventManager, EntityManager and SystemManager instances.

To use it, subclass EntityX:

class Level : public EntityX {
public:
  explicit Level(filename string) {
    systems.add<DebugSystem>();
    systems.add<MovementSystem>();
    systems.add<CollisionSystem>();
    systems.configure();

    level.load(filename);

    for (auto e : level.entity_data()) {
      entityx::Entity entity = entities.create();
      entity.assign<Position>(rand() % 100, rand() % 100);
      entity.assign<Direction>((rand() % 10) - 5, (rand() % 10) - 5);
    }
  }

  void update(TimeDelta dt) {
    systems.update<DebugSystem>(dt);
    systems.update<MovementSystem>(dt);
    systems.update<CollisionSystem>(dt);
  }

  Level level;
};

You can then step the entities explicitly inside your own game loop:

while (true) {
  level.update(0.1);
}

Installation

Arch Linux

pacman -S entityx

OSX

brew install entityx

Windows

Build it manually.

Requirements:

Building entityx - Using vcpkg

You can download and install entityx using the vcpkg dependency manager:

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

The 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 on the vcpkg repository.

Other systems

Build it manually.

Requirements:

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. EntityX tries to support the most common options, including the default C++ library for the compiler/platform, and libstdc++.

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:

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):

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:

Once you have selected your flags, build and install with:

mkdir build
cd build
cmake <flags> ..
make
make install

EntityX 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.