Scarfski/entt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated readme

Browse Source
This commit is contained in:
Michele Caini
2017-10-28 00:15:42 +02:00
parent 71b464f44a
commit b4f3b6f7bd
1 changed files with 157 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
README.md
View File

@@ -1,4 +1,4 @@
# The EnTT Framework
# EnTT Framework
[![Build Status](https://travis-ci.org/skypjack/entt.svg?branch=master)](https://travis-ci.org/skypjack/entt)
[![Build status](https://ci.appveyor.com/api/projects/status/rvhaabjmghg715ck?svg=true)](https://ci.appveyor.com/project/skypjack/entt)
@@ -9,22 +9,66 @@
`EnTT` is a header-only, tiny and easy to use framework written in modern
C++.<br/>
It's entirely designed around an architectural pattern pattern called _ECS_ that
is used mostly in game development. For further details:
It was originally designed entirely around an architectural pattern called _ECS_
that is used mostly in game development. For further details:
* [Entity Systems Wiki](http://entity-systems.wikidot.com/)
* [Evolve Your Hierarchy](http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/)
* [ECS on Wikipedia](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system)
Originally, `EnTT` was written as a faster alternative to other well known and
open source entity-component systems.<br/>
After a while the codebase has grown and more features have become part of the
framework.
A long time ago, the sole entity-component system was part of the project. After
a while the codebase has grown and more and more classes have become part
of the repository.<br/>
That's why today it's called _the EnTT Framework_.
## The framework
`EnTT` was written initially as a faster alternative to other well known and
open source entity-component systems. Nowadays the `EnTT` framework is moving
its first steps. Much more will come in the future and hopefully I'm going to
work on it for a long time.<br/>
Requests for feature, PR, suggestions ad feedback are highly appreciated.
If you find you can help me and want to contribute to the `EnTT` framework with
your experience or you do want to get part of the project for some other
reason, feel free to contact me directly (you can find the mail in the
[profile](https://github.com/skypjack)).<br/>
I can't promise that each and every contribution will be accepted, but I can
assure that I'll do my best to take them all seriously.
### State of the art
Here is a brief list of what it offers today:
* Statically generated integer identifiers for types (assigned either at
compile-time or at runtime).
* An incredibly fast entity-component system based on sparse sets, with its own
views and a _pay for what you use_ policy to adjust performance and memory
pressure according to the users' requirements.
* Signal handlers of any type, delegates and an event bus.
* A general purpose event emitter, that is a CRTP idiom based class template.
* An event dispatcher for immediate and delayed events to integrate in loops.
* The smallest and most basic implementation of a service locator ever seen.
* ...
* Any other business.
Consider it a work in progress. For more details and an updated list, please
refer to the [online documentation](https://skypjack.github.io/entt/).
### A note about the README
The README file stays true to the original project and it describes only the
entity-component system. However, the whole API is fully documented in-code and
the [online documentation](https://skypjack.github.io/entt/) contains much
more.<br/>
Continue reading to know how the core part of the project works or follow the
link above to take a look at the API reference for all other available classes.
## Code Example
```cpp
#include <registry.hpp>
#include <entt/entt.hpp>
#include <cstdint>
struct Position {
float x;
@@ -40,22 +84,40 @@ void update(entt::DefaultRegistry &registry) {
auto view = registry.view<Position, Velocity>();
for(auto entity: view) {
auto &position = view.get<Position>(entity);
// gets only the components that are going to be used ...
auto &velocity = view.get<Velocity>(entity);
velocity.dx = 0.;
velocity.dy = 0.;
// ...
}
}
void update(std::uint64_t dt, entt::DefaultRegistry &registry) {
registry.view<Position, Velocity>().each([dt](auto entity, auto &position, auto &velocity) {
// gets all the components of the view at once ...
position.x += velocity.dx * dt;
position.y += velocity.dy * dt;
// ...
});
}
int main() {
entt::DefaultRegistry registry;
std::uint64_t dt = 16;
for(auto i = 0; i < 10; ++i) {
auto entity = registry.create();
registry.assign<Position>(entity, i * 1.f, i * 1.f);
auto entity = registry.create(Position{i * 1.f, i * 1.f});
if(i % 2 == 0) { registry.assign<Velocity>(entity, i * .1f, i * .1f); }
}
update(dt, registry);
update(registry);
// ...
}
```
@@ -71,8 +133,9 @@ realized it, I tried hard to keep intact the great performance of `EnTT` and to
add all the features I wanted to see in *my* entity-component system at the same
time.
Today `EnTT` is finally what I was looking for: still faster than its _rivals_,
a really good API and an amazing set of features. And even more, of course.
Today `EnTT` is finally what I was looking for: still faster than its
_competitors_, a really good API and an amazing set of features. And even more,
of course.
## Performance
@@ -182,6 +245,26 @@ Benchmarks are compiled only in release mode currently.
# Crash Course
## Design choices
`EnTT` is entirely designed around the principle that users have to pay only for
what they want.
When it comes to use an entity-componet system, the tradeoff is usually between
performance and memory usage. The faster it is, the more memory it uses.
However, slightly worse performance along non-critical paths are the right price
to pay to reduce memory usage and I've always wondered why this kind of tools do
not leave me the choice.<br/>
`EnTT` follows a completely different approach. It squezees the best from the
basic data structures and gives users the possibility to pay more for higher
performance where needed.<br/>
The disadvantage of this approach is that users need to know the systems they
are working on and the tools they are using. Otherwise, the risk to ruin the
performance along critical paths is high.
So far, this choice has proved to be a good one and I really hope it can be for
many others besides me.
## Vademecum
The `Registry` to store, the `View`s to iterate. That's all.
@@ -194,17 +277,18 @@ functionalities to query them out-of-the-box. The underlying type of an entity
when defining a registry (actually the DefaultRegistry is nothing more than a
Registry where the type of the entities is `std::uint32_t`).<br/>
Components (the _C_ of an _ECS_) should be plain old data structures or more
complex and moveable data structures with a proper constructor. They are list
initialized by using the parameters provided to construct the component. No need
to register components or their types neither with the registry nor with the
entity-component system at all.<br/>
complex and moveable data structures with a proper constructor. Actually, the
sole requirement of a component type is that it must be both move constructible
and move assignable. They are list initialized by using the parameters provided
to construct the component itself. No need to register components or their types
neither with the registry nor with the entity-component system at all.<br/>
Systems (the _S_ of an _ECS_) are just plain functions, functors, lambdas or
whatever the users want. They can accept a Registry, a View or a PersistentView
and use them the way they prefer. No need to register systems or their types
neither with the registry nor with the entity-component system at all.
The following sections will explain in short how to use the entity-component
system, the core part of the `EnTT` framework.<br/>
system, the core part of the whole framework.<br/>
In fact, the framework is composed of many other classes in addition to those
describe below. For more details, please refer to the
[online documentation](https://skypjack.github.io/entt/).
@@ -286,8 +370,8 @@ velocity.dy = 0.;
In case users want to assign a component to an entity, but it's unknown whether
the entity already has it or not, `accomodate` does the work in a single call
(of course, there is a performance penalty to pay for that mainly due to the
fact that it must check if `entity` already has the given component or not):
(there is a performance penalty to pay for that mainly due to the fact that it
must check if `entity` already has the given component or not):
```cpp
registry.accomodate<Position>(entity, 0., 0.);
@@ -367,7 +451,8 @@ entity stored in the underlying data structures of the registry.
### Sorting: is it possible?
Of course, sorting entities and components is possible with `EnTT`.<br/>
It goes without saying that sorting entities and components is possible with
`EnTT`.<br/>
In fact, there are two functions that respond to slightly different needs:
* Components can be sorted directly:
@@ -437,8 +522,9 @@ To sum up and as a rule of thumb, use a standard view:
Use a persistent view in all the other cases.
To easily iterate entities, all the views offer _C++-ish_ `begin` and `end`
member functions that allow users to use them in a typical range-for loop.<br/>
To easily iterate entities, all the views offer the common `begin` and `end`
member functions that allow users to use a view in a typical range-for
loop.<br/>
Continue reading for more details or refer to the
[official documentation](https://skypjack.github.io/entt/).
@@ -474,7 +560,7 @@ There is no need to store views around for they are extremely cheap to
construct, even though they can be copied without problems and reused
freely. In fact, they return newly created and correctly initialized iterators
whenever `begin` or `end` are invoked.<br/>
To iterate a single component standard view, just use it in range-for:
To iterate a single component standard view, either use it in range-for loop:
```cpp
auto view = registry.view<Renderable>();
@@ -486,8 +572,21 @@ for(auto entity: view) {
}
```
**Note**: prefer the `get` member function of the view instead of the `get`
member function template of the registry during iterations.
Or rely on the `each` member function to iterate entities and get all their
components at once:
```cpp
registry.view<Renderable>().each([](auto entity, auto &renderable) {
// ...
});
```
Performance are more or less the same. The best approach depends mainly on
whether all the components have to be accessed or not.
**Note**: prefer the `get` member function of a view instead of the `get` member
function template of a registry during iterations, if possible. However, keep in
mind that it works only with the components of the view itself.
#### Multi component standard view
@@ -505,7 +604,7 @@ There is no need to store views around for they are extremely cheap to
construct, even though they can be copied without problems and reused
freely. In fact, they return newly created and correctly initialized iterators
whenever `begin` or `end` are invoked.<br/>
To iterate a multi component standard view, just use it in range-for:
To iterate a multi component standard view, either use it in range-for loop:
```cpp
auto view = registry.view<Position, Velocity>();
@@ -518,8 +617,21 @@ for(auto entity: view) {
}
```
**Note**: prefer the `get` member function template of the view instead of the
`get` member function template of the registry during iterations.
Or rely on the `each` member function to iterate entities and get all their
components at once:
```cpp
registry.view<Position, Velocity>().each([](auto entity, auto &position, auto &velocity) {
// ...
});
```
Performance are more or less the same. The best approach depends mainly on
whether all the components have to be accessed or not.
**Note**: prefer the `get` member function of a view instead of the `get` member
function template of a registry during iterations, if possible. However, keep in
mind that it works only with the components of the view itself.
### Persistent View
@@ -560,7 +672,7 @@ of the components for which it has been constructed.<br/>
Refer to the [official documentation](https://skypjack.github.io/entt/) for all
the details.
To iterate a persistent view, just use it in range-for:
To iterate a persistent view, either use it in range-for loop:
```cpp
auto view = registry.persistent<Position, Velocity>();
@@ -573,8 +685,21 @@ for(auto entity: view) {
}
```
**Note**: prefer the `get` member function template of the view instead of the
`get` member function template of the registry during iterations.
Or rely on the `each` member function to iterate entities and get all their
components at once:
```cpp
registry.persistent<Position, Velocity>().each([](auto entity, auto &position, auto &velocity) {
// ...
});
```
Performance are more or less the same. The best approach depends mainly on
whether all the components have to be accessed or not.
**Note**: prefer the `get` member function of a view instead of the `get` member
function template of a registry during iterations, if possible. However, keep in
mind that it works only with the components of the view itself.
## Side notes
@@ -622,21 +747,6 @@ for(auto entity: view) {
renderable entities while updating a physic component concurrently on a
separate thread if needed.
## What else?
The `EnTT` framework is moving its first steps. More and more will come in the
future and hopefully I'm going to work on it for a long time.<br/>
Here is a brief list of what it offers today:
* Statically generated integer identifiers for types.
* An entity-component system based on sparse sets.
* Signal handlers and event emitters of any type.
* ...
* Any other business.
Consider it a work in progress. For more details and an updated list, please
refer to the [online documentation](https://skypjack.github.io/entt/).
# Contributors
If you want to contribute, please send patches as pull requests against the