sgtcodfish / ashleycpp

A C++ clone of Ashley, a Java entity framework.

AshleyCPP - C++11 ECS Framework

AshleyCPP is a lightweight, cross-platform and easy to use Entity framework for C++11 based on the Java entity framework Ashley, targeted towards game development. It contains all the classes you need to get started making a game using a pure, ECS-oriented style.

It prioritises speed and simplicity and mirrors the public API of the original where possible to make it easy to learn, quick to run and simple to debug - and doubly so for users of the Java original.

The original is inspired by the Ash and Artemis frameworks.

AshleyCPP is a personal project and while there are no guarantees that it will compile and work, the master branch on GitHub should compile and function properly and should be usable for making projects right now. There is currently no guarantee of API stability between versions, or indeed any meaningful versioning.

Building

AshleyCPP uses the CMake build system and comes with three build targets; the debug library, "AshleyCPP-d", the release library "AshleyCPP" and the (imaginatively named) executable "AshleyCPPTest". The test program uses GTest, which is bundled.

To build the library from source, install a relatively recent version of CMake, navigate to a copy of the source and do the following:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=<CHOOSE ONE: Debug/Release> ..

and proceed as normal for your environment. If you don't care about the tests, you can run cmake -DEXCLUDE_TESTS=TRUE .. leaving you with just the library.

Usage Notes and API Changes

While AshleyCPP strives to match the exported public API of the Java original, differences in the languages mean that some differences exist. Such changes are listed in detail in APICHANGES.md, but a quickstart is given below.

First in foremost: In situations where in Java you'd use .class to get a Java class, in C++ you can #include <typeinfo> and:

typeid(ComponentClass); // Equivalent to ComponentClass.class in Java.  

// e.g. get a Family* that matches Entity having both ComponentA and ComponentB
ashley::Family::getFor({typeid(ComponentA), typeid(ComponentB)});

• The whole library is enclosed in the ashley namespace. Use using namespace ashley; to save typing if you want.
• You can #include individual headers (organised similarly to the Java packages) or #include "Ashley/Ashley.hpp"
• Java generic functions that take vararg lists of Class<? extends Component> are replaced by std::initializer_list<std::type_index>. Some functions also provide template overloads which may be easier and faster to use; check the documentation for specific occurrences.
• The library enforces ownership using std::unique_ptr; the engine owns all entities and systems that are passed into it and unless they're removed, all entities and systems die with the engine. Likewise, each Entity strictly owns its attached components. This minimises the risk of leaking memory.

For more specific changes, see the APICHANGES.md file.

Implementation Status

Ticked classes have both their implementation and tests complete.

• Core
  • Component
  • ComponentMapper
  • ComponentType
  • Engine
  • Entity
  • EntityListener
  • EntitySystem
  • Family
• Signals
  • Signal
  • Listener
• Systems
  • IteratingSystem
  • IntervalSystem
  • IntervalIteratingSystem
  • SortedIteratingSystem
• Util
  • ObjectPool
  • Poolable

NB:

• Bag and ImmutableArray will probably not be implemented, there are better native C++ choices without reinventing the wheel.
• Currently implements as far as Ashley commit #a276fe45.

Nice to have features:

• Refactor/rewrite handling of entity ids, using a C++11 constexpr compile time hash and a templated Component class to prevent using a virtual method and vtable. Will lead to smaller components and better cache coherency.

License

AshleyCPP has the same license as the original, as shown here:

Ashley is licensed under the Apache 2 License, meaning you can use it free of charge, without strings attached in commercial and non-commercial projects. We love to get (non-mandatory) credit in case you release a game or app using Ashley!

A mention if you find AshleyCPP useful would be very much appreciated!

ashleycpp's Issues

Creating ComponentMapper in Global Scope Fails

Results in a confusing math error when accessing Component IDs, since none exist yet.

This is probably unavoidable short of fixing the library to use constexpr Component IDs.

Remove dependence on exceptions

I.e. should allow compilation with -fno-exceptions at the very least. This is apparently an issue when working with cocos2d-x.

Raised on twitter

Fix Creating IteratingSystem with nullptr Family

Currently fails confusingly while trying to create the Family hash - should fail sooner.

Implement Optional Instrumentation

Add an optional (toggled by a define) instrumentation system which allows users to track various statistics about the usage of various entities, systems and components.

It's important that this is all entirely optional, to avoid any performance impact in releases.

Examples of stats we could collect:

• System ordering
• Number of fetches within an update (i.e. usage of componentmapper)
• The number of matching entities in an update cycle

Multithreading systems

It would be nice to have a base class, which called the component processEntities with multiple threads (from a pool). So it can be much faster (hopefully). The original ashley doesn't have this feature, but it would be a nice addition to this one.

See this theoretical post: https://gamedev.stackexchange.com/a/62754

Consider using bitset2

https://github.com/ClaasBontus/bitset2/tree/cpp14 is an implementation of <bitset> which makes better use of constexpr, alongside providing other features. There might be a performance benefit to using this.

Feature Parity with Java Original

Currently README.md suggests we have parity as of this commit.

We should get up to date, and update the README.

Todo:

• Add EntitySystem::getEngine commit
  | see #9
• Add EntityListener priority commit
• Check what happens when adding the same entity to and engine twice, and define behaviour if neccessary issue
• Check (+ test?) this issue
• Consider splitting Engine class into smaller classes as in ashley PR#196