• Stars
    star
    2,170
  • Rank 21,251 (Top 0.5 %)
  • Language
    C++
  • License
    MIT License
  • Created about 12 years ago
  • Updated 10 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

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

  • 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.
  • 2014-02-13 - Visual C++ support thanks to Jarrett Chisholm!
  • 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.
  • 2013-08-18 - Destroying an entity invalidates all other references
  • 2013-08-17 - Python scripting, and a more robust build system

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:

  • Separation of data via components.
  • Separation of logic via systems.
  • Use of events (colliding bodies trigger a CollisionEvent).

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

  • 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 first, 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.
  • To improve cache coherence, components are constructed in contiguous memory ranges by using entityx::EntityManager::assign<C>(id, ...).

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

  • 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.
  • Each type of component is allocated in (mostly) contiguous blocks to improve cache coherency.

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:

  • 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<C> - emitted when a new component is added to an entity.
    • entityx::Entity entity - entityx::Entity that component was added to.
    • ComponentHandle<C> component - The component added.
  • ComponentRemovedEvent<C> - emitted when a component is removed from an entity.
    • entityx::Entity entity - entityx::Entity that component was removed from.
    • ComponentHandle<C> 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 Systems also be Receivers.
  • When an Entity is destroyed it will cause all of its components to be removed. This triggers ComponentRemovedEvents to be triggered for each of its components. These events are triggered before the EntityDestroyedEvent.

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:

  • Visual Studio 2015 or later, or a C++ compiler that supports a basic set of C++11 features (ie. Clang >= 3.1 or GCC >= 4.7).
  • CMake

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:

  • A C++ compiler that supports a basic set of C++11 features (ie. Clang >= 3.1, GCC >= 4.7).
  • CMake

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:

  • -DENTITYX_RUN_BENCHMARKS=1 - In conjunction with -DENTITYX_BUILD_TESTING=1, also build benchmarks.
  • -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=1 - Whether to build tests (defaults to 0). Run with "make && make test".
  • -DENTITYX_DT_TYPE=double - The type used for delta time in EntityX update methods.

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.

More Repositories

1

chroma

A general purpose syntax highlighter in pure Go
Go
4,360
star
2

gometalinter

DEPRECATED: Use https://github.com/golangci/golangci-lint
Go
3,507
star
3

kingpin

CONTRIBUTIONS ONLY: A Go (golang) command line and flag parser
Go
3,497
star
4

participle

A parser library for Go
Go
3,479
star
5

kong

Kong is a command-line parser for Go
Go
2,132
star
6

voluptuous

CONTRIBUTIONS ONLY: Voluptuous, despite the name, is a Python data validation library.
Python
1,793
star
7

go_serialization_benchmarks

Benchmarks of Go serialization methods
Go
1,560
star
8

jsonschema

Maintenance has moved to https://github.com/invopop/jsonschema
Go
750
star
9

pawk

PAWK - A Python line processor (like AWK)
Python
516
star
10

gozmq

Go (golang) bindings for the 0mq (zmq, zeromq) C API
Go
468
star
11

log4go

Logging package similar to log4j for the Go programming language
Go
309
star
12

ondir

OnDir is a small program to automate tasks specific to certain directories
C
195
star
13

mph

Minimal Perfect Hashing for Go
Go
173
star
14

repr

Python's repr() for Go
Go
163
star
15

assert

A simple assertion library using Go generics
Go
147
star
16

units

Helpful unit multipliers and functions for Go
Go
123
star
17

importmagic

A Python library for finding unresolved symbols in Python code, and the corresponding imports
Python
120
star
18

gorx

A package and tool providing Reactive eXtensions for Go.
Go
94
star
19

devtodo2

DevTodo the Second
Go
89
star
20

template

Fork of Go's text/template adding newline elision
Go
56
star
21

hcl

Parsing, encoding and decoding of HCL to and from Go types and an AST.
Go
49
star
22

binary

General purpose binary encoder/decoder
Go
48
star
23

SublimeLinter-contrib-gometalinter

SublimeLinter plugin for gometalinter
Python
47
star
24

localcache

Local file-based atomic cache manager
Go
44
star
25

gobundle

DEPRECATED: I recommend https://github.com/GeertJohan/go.rice
Go
39
star
26

geoip

A pure Go interface to the free MaxMind GeoIP database
Go
38
star
27

unsafeslice

Unsafe zero-copy slice casts for Go
Go
37
star
28

SublimePythonImportMagic

This Sublime Text 2 plugin attempts to automatically manage Python imports.
Python
34
star
29

inject

Guice-ish dependency injection for Go.
Go
31
star
30

sequel

Sequel - A Go <-> SQL mapping package
Go
26
star
31

multiplex

This Go package multiplexes streams over a single underlying transport io.ReadWriteCloser.
Go
25
star
32

arena

A very fast arena allocator for Go
Go
22
star
33

tuplespace

A RESTful tuple space server
Go
21
star
34

langx

Language experimentation.
Go
21
star
35

mango-kong

Mango (man page generator) integration for Kong
Go
20
star
36

go-check-sumtype

A simple utility for running exhaustiveness checks on Go "sum types."
Go
20
star
37

atomic

Type-safe atomic values for Go
Go
19
star
38

go-rpcgen

Generates Go RPC server and client boilerplate for interfaces.
Go
17
star
39

SublimeFoldPythonDocstrings

Automatically folds Python docstrings longer than 1 line.
Python
16
star
40

colour

Quake-style colour formatting for Unix terminals
Go
15
star
41

protobuf

A Protobuf IDL parser for Go
Go
15
star
42

oink

Oink is a Python to Javascript translator.
Python
15
star
43

entityx_python

Python bindings for EntityX
C++
14
star
44

kong-yaml

Go
14
star
45

bit

Bit - A simple yet powerful build tool
Go
12
star
46

shreq

This utility verifies all commands used by a shell script against an allow list
Go
11
star
47

types

Useful generic types for Go
Go
11
star
48

app

Modular application framework for Go.
Go
11
star
49

kdl

Go parser for KDL
Go
10
star
50

vheap

Fast, persistent, mmapped, virtual heap.
Go
8
star
51

errors

A simple errors package for Go
Go
8
star
52

kong-hcl

Go
8
star
53

rapid

RESTful API Daemons (and Clients) for Go
Go
7
star
54

genh

genh is an opinionated tool for generating request-handler boilerplate for Go
Go
7
star
55

ReactiveDataStructures

Reactive data structures for Swift based on RxSwift
Swift
7
star
56

lunatic-go

Lunatic bindings for (Tiny)Go
Go
6
star
57

chrysalis

Chrysalis - Source to a 2D Platformer from 1994
C++
6
star
58

dotfiles

My dotfiles.
Vim Script
6
star
59

bootstrap

Go application bootstrapping
Go
6
star
60

devtodo

DevTodo (legacy)
C
6
star
61

waffle

Waffle - A Dependency-Injection-based application framework for Python
Python
5
star
62

porpoise

Porpoise - A Redis-based analytics framework
Python
5
star
63

waitgroup

Like sync.WaitGroup and ergroup.Group had a baby.
Go
5
star
64

esfmt

An opinionated, zero-configuration formatter for ES/TS/ESX/TSX
Go
5
star
65

flam

flam /flæm/ noun, verb, flammed, flam⋅ming. Informal. –noun 1. a deception or trick. 2. a falsehood; lie. –verb (used with object), verb (used without object) 3. to deceive; delude; cheat.
Python
5
star
66

cly

A Python module for adding powerful text-based consoles to your application.
Python
4
star
67

expr

Runtime evaluation of Go-like expressions
Go
4
star
68

simplenotefs

simplenotefs
Python
4
star
69

concurrency

Types and functions for managing concurrency in Go.
Go
4
star
70

replaylog

A type safe implementation of an op replay log
Go
3
star
71

Cache.swift

A flexible RAM and disk-backed cache for Swift
Swift
3
star
72

wit-go

A partial WIT parser and code generator for Go
Go
3
star
73

SublimeLinter-contrib-errcheck

SublimeLinter integration for the Go errcheck utility
Python
3
star
74

SublimeLinter-contrib-golang-cilint

DEPRECATED: Use https://github.com/cixtor/SublimeLinter-golangcilint
Python
2
star
75

aspect

Lightweight Aspect-oriented Module for Python
Python
2
star
76

gptcc

Add Conventional Commits to commit messages using ChatGPT
Shell
2
star
77

WaveGrowl.app

Wave notifications via Growl on Mac
Python
2
star
78

cut

Core Utilities - A set of core utility classes for Python.
Python
2
star
79

kong-toml

Kong configuration loader for TOML
Shell
2
star
80

rest

Go
2
star
81

prototemplate

Process Protocol Buffer definitions with text templates and JavaScript functions
Go
2
star
82

webservice

A webservice dispatcher for Go
Go
1
star
83

pathways

Pathways - An opinionated RESTful web service framework for Go
Go
1
star
84

cktphotography.com

Christine Knight Thomas Photography (website)
JavaScript
1
star
85

psmap

Persistent static maps for Go
Go
1
star