entity systems games design massively multiplayer programming

Entity System 1: Java/Android

Please note: the design described in this blog post has been much improved and updated and put up – with full source – on

On the wiki linked above, there is now a wholly new Entity System design, based on this one, but much improved. There’s a brief post about it here, recommended instead of this ES design:

I’ve been writing about Entity Systems sporadically for the last few years. Recently, I finally had the time and the excuse to build one of my own (i.e. not owned by an employer). If you haven’t read the main series of ES posts, you should do that first. There are many things in the world masquerading under the Entity/Component banner – and even more that just coincidentally share the name, but describe something else completely. It’s worth understanding which variant I’m talking about before you read about what I’ve done :).

Why build an Entity System?

At a generic level, this is covered in the other posts. But it’s taken years for me to have the time/inclination to write a new one from scratch outside of my day-job. What happened?

  1. I left my iPhone in America, and it took 2 months to get it back
  2. Google gave me a free Nexus One, in the hope I’d write something for it (ha! Their cunning plan worked…)
  3. The Android marketplace is such a miserable morasss of third-rate crap that eventually I was compelled to write my own Android game … just so that I would have something to play (there are very few games on the Android store that are even worth the time it takes to download them)

I’ve been making games for a long time. I know how much effort will go into it, how much time, and how much slog there is before it becomes worth it. Writing a game on your own often means putting in 90% of the effort to get 10% of the reward.

Enter … the Entity System. If I were to pick a game-design that mostly used data-driven game features, I could implement it around an ES, and massively reduce the amount of planning needed to get the game running. I could maybe have a working game after a mere 20% of the effort. Hmm…

Building the ES for Android

Android runs something that’s *almost* Java (although more on that later – Android’s version of Java is very slow at some of the core libraries, and it really shouldn’t be). Technically, Android supports all the core data structures from Java (Collections), and the templating system (Generics).

If I were writing an ES in C++, I’d do it using templates without pausing to think; I wondered how well the same might work with Generics, given that Generics is *not* a complete templating system, although it provides quite a lot.

Getting started: early ES decisions

How to design/implement this thing? Well, we know one thing for sure:

Entities have a single name/label/global-ID. Entities MUST NOT contain ANY DATA: these are NOT objects, this is NOT OOP!

There you go, the Entity class wrote itself:
public class Entity
public int id;
This immediately raised some concerns for me, being the seasoned coder I am (ha!). How the heck was I going to write any code that dealt with these things if I didn’t have references to them? Obviously, sometimes you do have references, but other times you expect to follow refs from within the objects you have, to get to the objects you need. That wouldn’t be happening here, since there are no inter-object refs.

public class BaseEntitySystem implements EntitySystem
/** I’m too lazy to write a "safe" method to get a globally-unique ID; for now,
I just return 1 the first time I’m called, 2 the second time, etc… */
protected int getNextAvailableID();

/** Whenever you create an entity, you’d better invoke this method too!*/
public void registerEntity( Entity e );

/** The method to solve my fears above */
public Entity getEntity( int id )

* Merely removes the entity from the store. It becomes a GC candidate
* almost immediately (since all other refs are transient)
public void killEntity( Entity e )

…but, again, being a Veteran coder, the survivor of many painful battles on the field of programming … I didn’t trust myself in the slightest to “always remember” to invoke registerEntity. Quick trick: give the Entity class a static reference to a default EntitySystem, and have each EntitySystem check if that reference is null when starting; if so, set itself as the “default”.

public class Entity

public static EntitySystem defaultEntitySystem;

public Entity( int i )
id = i;

if( defaultEntitySystem == null )
throw new IllegalArgumentException( "There is no global EntitySystem; create a new EntitySystem before creating Entity’s" );

defaultEntitySystem.registerEntity( this );


public class BaseEntitySystem implements EntitySystem

public BaseEntitySystem()
if( Entity.defaultEntitySystem == null )
slog( "Setting myself as default entity system (Entity.default… is currently null) self = " + this );
Entity.defaultEntitySystem = this;


W00t! I can create Entity’s, and I can find them later on. Awesome. What about those Components, then?

Getting started: Components in Java

I’ve done ES in C++ before, with real templates, so I wasn’t really thinking at this point … I just ran with what seemed natural based on prior experience. The thought process (had there been one) would have been something like this:

  1. This is java, I use Eclipse: I absolutely *must* have the IDE know what data/fields exist in each component so that Content-Assist/Autocomplete works 100%. Otherwise I will gouge my own eyes out having to remember, and doubly so each time the app compiles but dies at runtime because of a typo in a field-name.
    • Requirement: each unique Component must be defined as a java Class, with each of the fields being a public member of that class
    • Requirement: to access a Component of a given Entity, you must invoke a method which returns something that is typed (as in language typing) to the correct Class

I made a Component class, and had all Components extend it; there is a particular reason for this, but it doesn’t matter right now – essentially, it lets you define shared behaviour for all Component subclasses, and just saves you time on typing.

My first real Component:

(NB: I defined this *inside* another class, because I couldn’t be bothered having N source files for the (large number of) N Components I was bound to create. Hence the “static”):
public class MyEntitySystemExperiment

static class Position extends Component
float x, y;
int width, height;
float rotationDegrees;

@Override public String toString()
return "("+super.toString()+" @ ("+x+","+y+") * rot."+rotationDegrees+")";


Great. I have a component. Now comes the largest single piece of work in the entire implementation of the ES: writing the methods to:

  1. Add a component to an Entity
  2. Fetch a component from an Entity
  3. Remove a component from an Entity

Fetching a Component from an Entity

This is the win/lose point: if this works well, our ES will be nice and easy to use. The other two methods (add and remove) are simply twiddling bits of data. This one is the challenge: can you make it *easy* to write code that uses the ES, and for that code to be clearly *understandable*?

public class EntitySystemSimple extends BaseEntitySystem
HashMap<Class, HashMap<Entity, ? extends Component>> componentStores;

public <T> T getComponent( Entity e, Class<T> exampleClass )
HashMap<Entity, ? extends Component> store = componentStores.get( exampleClass );

T result = (T) store.get( e );
if( result == null )
throw new IllegalArgumentException( "GET FAIL: "+e+" does not
possess Component of class\n missing: "+exampleClass );

return result;


Boom! It works.

Let’s just stop briefly and I’ll explain why. Reading Java generics code from cold (just like reading C++ templates) often takes a lot of hard thinking.

Looking at the “result” of this method, we want it to be (enforced by the compiler):

  1. “an instance of a class that extends Component”
  2. “an instance of the particular class/Component that we requested – not just any old subclass”

/** based on comments at end of blog post, think this is correct,
but not checked */
public <T extends Component> T getComponent( Entity e, Class<T> exampleClass )

It causes you to write application code that looks something like this:

public void doSomethingWithAnEntity( int globalId )
// remember, we NEVER hold refs to Entity objects for long
Entity e = entitySystem.get( globalId );

Position position = entitySystem.getComponent( e, Position.class );
position.x = 5;

…and what’s important is that the “type” of the “Position position = …” line is already hard-typed to “Position”. So, the content-assist will *auto-complete* anything put after a dot on the end of that line, e.g.:

entitySystem.getComponent( e, Position.class ).AUTO_COMPLETE

…so you can instead write your method much quicker, and yet very clearly, as:

public void doSomethingWithAnEntity( int globalId )
// remember, we NEVER hold refs to Entity objects for long
Entity e = entitySystem.get( globalId );

entitySystem.getComponent( e, Position.class ).x = 5;
entitySystem.getComponent( e, Damage.class ).hitpoints = 145;
entitySystem.getComponent( e, Renderable.class ).foregroundColour =;

Time-out: HashMap

HashMap is the “correct” class to use in Java for this setup: it’s the exact equivalent of Hashtable / Dictionary / etc in other languages. We need to map (somewhere, somehow) from one thing (an entity) to another thing (a component).

NB: this does not mean that you have to use HashMap as your data-store for the ES; I positively encourage you to consider other options. I used it here as the most obvious, simplest possible structure that would do the job. If you think back to my posts on Entity Systems for MMO development, I’ve often suggested that the data store could *and should* be any of many different things. In particular, SQL databases make for an excellent data-store (and remember you can get in-memory SQL implementations that do away with all the expensive write-to-disk stuff).

Unfortunately … Android seems to only partially support HashMap. You can use the class, but it runs an order of magnitude slower than you expect for a normal JVM (compared to the speed with which it runs other methods). It seems to have problems with the hashcode methods, but also even with basic iteration over the Map contents. Odd. Later on, I had to do some tricks to speed up the ES, just because of this problem.

Fetching a Component from an Entity: Redux

The examples I gave above for accessing components were lean and clear on the right hand side (thanks to autocomplete and strong typing), but terrible on the left-hand-side. By the magic of OOP, I’m going to clean up the LHS. BUT (and this is a big “but”) … make sure you fully understand what I’m doing here. With what I’m about to do, it would be very easy to fall into one of the traps of ES development: slipping back into OOP techniques.

Looking at the example:

entitySystem.getComponent( e, Position.class ).x = 5;
entitySystem.getComponent( e, Damage.class ).hitpoints = 145;
entitySystem.getComponent( e, Renderable.class ).foregroundColour =;

… applying OOP mindset, we see that the first argument is redundant; the Entity already knows about the EntitySystem to which it’s registered.

Also, we know that the Entity class will never have any methods or data other than the ID. If that’s the case, the only thing we’d ever “get” from an Entity is a Component. So, we can add this to Entity:

public class Entity

/** Gets a filtered view of the entity’s data, only returning the subset that
* corresponds to a particular one of its components */
public <T extends Component> T getAs( Class<T> type )
return source.getComponent( this, type );


…which converts our usage example to:

e.getAs( Position.class ).x = 5;
e.getAs( Damage.class ).hitpoints = 145;
e.getAs( Renderable.class ).foregroundColour =;

Using the ES with Systems

Recap: right now, we can:

  1. Create entities
  2. Add components to entities
  3. Read/Write the data inside each component, on a per-entity basis
  4. Fetch entities by globally unique ID

One last thing is needed before the ES can work: we need a way to fetch Entities “by component”.


public class MyEntitySystemExperiment

public void runLoop()
while( true )
// move all the entities
positionSystem.move( MOVEABLE_ENTITIES );

// check for collisions
collisionDetectionSystem.process( MOVEABLE_ENTITIES );

// render all the visible entities
renderingSystem.render( RENDERABLE_ENTITIES );


We need a way to provide the arguments that are capitalized above. We know that these should be plain-old lists of entities. We know they have to come from the EntitySystem. Finally, we know that the only defining characteristic of these lists is that everything in the list has *at least* a particular Component.

(respectively, in the example above, the lists contain: “all entities that are moveable”, “all entities that are moveable AND all entities that are barriers to movement (e.g. solid walls)”, and “all entities that should be displayed on-screen”)

So, one more method for the EntitySystem interface:

public interface EntitySystem

public List<Entity> getAllEntitiesPossessing( Class… requiredComponents );


“Class…” is just a convenience; in many cases, you’ll be insisting on a single Component. In many other cases, you’ll be insisting on a set of components. Java varargs provide the minor convenience of doing both of those in one method, while retaining type-safety.

The implementation of this method is obvious: it iterates over every entity that’s been registered, and checks it against ALL the required components. If it possesses all of them, it goes into the output list.


That’s it. So easy! Obviously, there’s more to it – the other methods you need to create should be mostly self-evident – but this should be enough to get you started.

Now, I’m not sure where to go from here. I’ve got a working Java ES. I’ve got some performance improvements and feature improvements. But … in practice, hardly anyone writes games in Java (except Android programmers, and there aren’t many of those), so … is it worth it?

Alternatively, I might just run through some of the practical pros and cons I encountered when actually using the ES in writing the game-logic. There’s some interesting things that came up which most people encounter sooner or later when doing their first ES, and which might be worth looking at in more detail.

One last thought…

Did it work? Did this ES allow me to write a decent Android game?

Yep. I wrote a space-invaders / bullet-hell game with it. It worked fine on Android phones for a hundred-odd enemies and bullets on screen. On Android, thanks to the crappy JVM, it started to chug after that (dropped below 30 FPS), so I had to make some substantial performance improvements, and now it’s happily rendering 300 things all flying around at 20-30 FPS. The game is far from finished, but it’s playable and fun for a minute or so – a definite achievement considering how little of it I’ve written so far.


NB: it’s got some way to go before I’ll be happy releasing it. But, given a few more spare evenings, I hope to get this up on the Android Market as a free download in the near future.

I’m pleasantly surprised that the Android phones can handle something as high-level as an ES, in a pure, unoptimized “simplest possible” implementation.

Did this post help you?

You can say “thank you” by giving me your email address, and letting me contact you next time I make a game of my own:

[smlsubform emailtxt=”” showname=” mailinglist=”pif-entity-systems”]

177 replies on “Entity System 1: Java/Android”

I started to read your blog when I found it researching for “entity system” in google. I can more or less understand them, but I also have my doubts. Could it be possible to see some day a example? You say that that game was easy and fast to produce, would you release the code of it, so I can see a “complete example” running?

Thank you very much either case (If you don’t publish it, don’t mind, I really understand!)

Thanks for your article! I’ve used a implementation from game programming gems and never finished the project because it was a big mess. Now I’ve implemented your java-system in c++ and it looks much more usable. One question about the system: is it allowed to have only one component-type per entity or can the user for example add two position-components to one entity?

a first version is available here: but beware, it’s really not tested and only for reference :) it would be great to remove the template-parameter in the getAs like in the addComponent, but C++ only allows template-deduction from input-types and not from output ones…



(that was the first “non-essential” feature I added to the ES; it made life simpler when I wanted my player space-ship to have extra guns ;))

However … having done that … it adds a lot of complexity to the ES implementation (read: on Android, reduced performance), and I’m not convinced you ever need to do it. It’s usually a sign that you’ve skipped an entity somewhere.

I believe the signature you are looking for is

public T getComponent( Entity e, Class exampleClass )

Lets try this again without treating generic tags as html tags

public T getComponent( Entity e, Class exampleClass )

Third times the charm?

I believe the signature you are looking for is

public <T extends Component> T getComponent( Entity e, Class<T> exampleClass )

Very interesting articles!

Can you extrapolate on how you associate entities with components? For example, in your space invaders game, how does an individual “alien” entity have its Position component associated with it?


The flip side of “getComponent” (which I provided in the post) is “addComponent”, which looks something like this:

1. Fetches exactly the same hashmap that getComponent fetched:

HashMap<Entity, ? extends Component> store = componentStores.get( exampleClass );

2. Adds a mapping from this Entity to that Component:

store.put( e, c );

So, to make a new alien, you would do e.g.:

Entity alien1 = new Entity( entitySystem.nextAvailableID() );
Position pos = new Position();
pos.x = 10;
pos.y = 0;
entitySystem.addComponent( alien1, pos );

NB: with this setup, you *must* instantiate a new Position for each Entity; this is a definite flaw (it’s preferable to work with some kind of flyweight object). Usually, though, Java is so very fast at instantiating new objects that this isn’t a practical concern (NB: on Android, I am having some minor GC hiccups, but I’ve been very lazy / profligate with object creation there).

On the other hand, it lets you write code like this:

Entity alien1 = new Entity( entitySystem.nextAvailableID(), new Position(10,0), new Weapon(100,10,3), new Enemy(500) );

…assuming you add an extra constructor to Entity that takes a varags of Component instances, and iterates through them, calling “addComponent( this, c )” for each c.

Good article, gives me some new ideas.

One of the problem I’ve encountered in entity/component systems is how you prioritize rendering in 2D. I’m making a RTS game whereas I can select a unit. That unit has some highlighting when it’s selected. The highlighting needs to be rendered atop of everything. This may seem trivial at first glance, but it’s not.

renderingSystem.render(ALL) doesn’t really go into much depth.

I’ve actually solved this problem in my own system, whereas each component type has a primary rendering priority and a entity type group has a secondary rendering priority. E.g. Highlighting component would has a high z-index order while a Units entity group would have a low z-index order. Sum of both determine the rendering z-index.

Another issue I’m worried about is the danger of the system implementations becoming a blob class.

In my system I have the data and logic in the components, and no systems. I have interface for e.g. Health for communication between components, and concrete implementations like RegenerativeHealth or StandardHealth.

If I were to do as you suggest, keep the logic in systems, would I need RegenerativeHealthSystem and StandardHealthSystem?
If it’s only a single HealthSystem, how does it determine what logic code to apply to that component data?

Of course, a article that raises more new questions than it answers, is a good article ;)


Highlighting is not part.of an entity system. It MAY be part of a custom renderer that touve written, but thats an entirely different set of design.

you need to look at your game and see it as many independent bits, only one of which is the game logic (whwre ES becones most useful). one common source of confusion is that its possible (not required!) to write a renderer that pulls all its data from the ES. but many renderers cannot be done purely this way.

in your example, you *might* have a “boolean highlighted ” field on one of your components, but that’s as detailed as you’d go.

re: blobs … you can write the systems with full-on OOP. since they fit what oop was designed for, they tend not to blob.


looking good… youre right that killEntity also neesa to deal with the components; i left that to subclasses, becauae my base entitysystem ONLY deals with entity maintenance.

this is probably a dumb setup, but i wanted it to be easy to write a crap data structure for store/retriwve componnts, and then easily swap in a better one later. i should probable have written some factory class(es), but i hate them on unthinking principle (so much indirectikn and waffle!).

ill probably change this in future, but in the meantime, its an interesting experiment: how much can you decouple the storage of entities from the storage of components?

alsk, nb: this ia nit acadwmic; in the long run, you want to move your components tp flyweight / striding steicuts

Ps: the garbled comments are because I’m.writing.on android phone. Android os has MAJOR bugs in b


ok, fair enough.

One final thing. I am a bit confused about the relation between EntitySystem and the positionSystem, collisionDetectionSystem, and renderingSystem in the game loop.

Your code code-bits contain multiple references to EntitySystem as being some sort of a manager, maybe EntityManager is a better name, whilst the other systems implement EntitySystem?


Yes, you’re right – I gave that interface a very very stupid name. EntityManager is, exactly What I meant :)

two notes: the c++ system could be a little bit smarter by using the runtime type information, but I don’t like rtti and emulated my own (in position the “static const FamilyId familyId = 1;” is the typeinformation that is used)

second: you can learn from my mistakes: don’t ever put logic into the components besides output for debugging or serialization! In my first try I’ve put update-logic into the components and with this approach one component needs access to other components (for example the physics component needed access to the position component) and things got very quickly very messy and unhandable :/ instead use systems that work on entities like positionSystem, collisionDetectionSystem and so on.

keep us informed about your progress on the android-implementation, I think I can still learn a lot from your articles :)

Regarding the performance issue you mention:

I assume each system needs to look-up all dependencies for a component in each iteration from the map? This causes heavy performance decrease IMO.

It’s probably best to resolve the dependencies only once, and store the appropriate references in the components themselves. Hitting the map heavily can be performance draining.


With a production system, especially a server-based one (e.g. for MMO servers), you’d make the meta system that runs the whole game a bit cleverer.

For instance, rather than just a simple game-loop that blindly iterates, you do careful management and batching of component queries. Ideally, you pass to each sub-system a pre-batched “set” of entities + components that it needs. This obviously requres each subsystem to implement some protocol that lets them tell the meta-system what they will be needing.

My quick-fix on Android is a very basic entity-system query-cache. This was very easy to write, since we’re only dealing with data – and because I’m not doing any flyweighting (yet).

My cache is only caching the “find the entities that match X” right now – I haven’t even tried to cache component fetches.

NB: before writing a better cache … I’d want to seriously look at directly plugging-in to SQLite or similar, and tweaking the SQL caching.

I’m afraid (i.e. I haven’t tested it – I’m just being pessimistic here) that SQLite perfomance on Android is likely to be way too low for real-time, but … there’s plenty of java-based in-memory SQL cache systems around, and Android has a lot of RAM. I *expect* that one of those caches would be lean enough to effortlessly improve things here – even with the trudging slowness of a full SQLite behind it.

Hey adam.

I made a “rough” draft of an entity system. I’d appreciate your input on it. What I’m doing wrong and right. Hopefully I’ll be able to build on that.

The source files are zipped together here (should be easy enough to simply drag it into Eclipse if you wish to run it):

I still have some questions on the matter.

For example, in collision detection, what do you do when you detect a collision?

I understand that th “collisionDetectionSystem.process( MOVEABLE_ENTITIES );” method picks all entities with the moveable component (and, I assume, the collidable component) and check if they did collide. And when they collide… you call a script that is defined in the collision component? Is that ES-friendly? Or you trigger a event that someone other system picks? (kind of ExpolionSystem.checkTrigger(EXPLOSIVE_ENTITIES)” )

I’m trying to implement such a system and while I understand the basics (entitie just are IDs, Components store data and Systems do the work) I don’t find a way to implement it…


Whatever you want. The purpose of the ES is *not* to implement a CD system for you.

The ES keeps track of *what* is collidable, *where* it is, etc – while attaching that info to the game-logic-info (e..g “this collidable is … a spaceship; that collidable is … an orc chieftain”) – in a way that you can write your CD system to *be completely unaware of* the “extra” info that is attached.

This brings some interesting crazy ideas:

Let’s suppose I have a system that runs on all collidable objects. Then if one of them collisions with other, will add a “collided” component to both with all relevant information.

Then run a system for “collided missiles” that triggers a great explosion.

Is that a valid way to go or I’m just crazy?

Sounds pretty cool :).

I’ve not done so much with this aspect – using the frame-to-frame presence/abscence of a component as a key part of the logic. It works very nicely (I use it for a lot of complex state-changing. Instead of having a complex state machine, just check for presence of components. It’s de-facto still a state machine but ITS MANY MANY TIMES easier to debug!)

Going the other way … instead of add/remove the components, leave them always present, but perhaps with “empty” data … My Android game is going very nicely with a similar two-step process for movement.

I have:
– Movable (containing a delta-x, and delta-y)
– Position (containing an x and y)

Everything that moves objects affects the Movable. Then my core CD system runs once per frame and applies all “movable”s to all “positions” – I did it this way so I could implement a swept-CD more easily.

When I know something wont move for a while, I subtract the movable component, so there’s less processing (although this doesn’t matter hugely).

It goes horribly wrong when you want more detail than Movable. For instance, I quickly switched to using parametric position for enemies (i.e. there is no “velocity / delta”, instead there is “at time T, one exact value for x,y”.

It was quite easy to fudge – I read the “next” value for x,y, then subtrace the “current” value, and set that as the movable.deltax/y.

But I’m sure there’s a better way to handle this. Perhaps a cleverer way to handle the difference between “absolute” and “relative” movement?

Hi again

Adam, could you please elaborate on the rendering aspect:
“renderingSystem.render( RENDERABLE_ENTITIES );”

I see in your game you have all sorts of things there, healthbar, player spaceship, enemies, bullets, etc.

How exactly does the renderingSystem go about displaying all these different things?

Also, isn’t the renderingSystem dependent on the environment it is rendering in? For a 2d game there would be some sort of graphics context to write into.

If I understand all your articles correctly, there should be multiple renderingSystems, e.g.: PlayerShipRenderingSystem, HealthBarRenderingSystem, BaddiesRenderingSystem, BulletsRenderingSystem etc.?

95% of things are rendered using a common system, as with most traditional 2D game programming. The only special case here is the HUD, because I didn’t want to include the HUD itself in the entity-system.

(although, NB: there are some potential benefits to doing so. For instance, rendering your health-bar as an integral part of your player-ship-graphic – like some of the FPS shooters used to do with ammo-readouts on the in-game weapons)

player, baddies, bullets – these are all just “things that render a sprite”, so I have a component that contains the name of the sprite to render, and I scale the sprite according to the objects “size” (which actually comes from the collision-detection component in this case, although it could have come from elsewhere).

(obviously, I have a cache of “sprite name” -> “image data”, so one image is shared across all things rendering that sprite)

Clearly, not everything is a sprite image.

You mentioned in some article that components were handled by their corresponding systems, in most cases. I assume this is the case for renderable components also?

In my RTS game that I am developing I have a FogOfWar component. Now, in order to render this special component I would need to have some sort of:

Unless you have some sort of sub-systems within the RenderingSystem to deal with all rendering-aspects?

After doing some prototypes of these entity systems I’ve concluded that heavy usage of maps/dictionaries makes them impractical, I’m experiencing a huge drop in the framerate. I will need to think how each system processes the entities and their components without doing hashmap lookups.

Incidentally, the new Android update fixes some of the HashMap performance problems in Google’s JVM – my game framerate under heay load went from about 15 FPS to 40 ish, without changing any code :).

But yes, I wouldn’t recommend Maps except as a “first pass” implementation. A good starting point is to look at the architecture of your game, work out where it’s going to stress the system, and think about suitable approaches.

For instance, how far will caching get you?

How far will batching (especially MAP(function, data)) get you?


Here’s how each system is designed in my prototype:

A “System” has two methods, (1) initialize() takes care of retrieving all the entities from the EntityManager which possess certain component(s), (2) and it has update() method which processes those entities.
Now, the system only has a collection of the entities, not their components. So, for each entity it processes it needs to lookup the components it will use from the EntityManager. This is really the bottleneck. Doing this each game loop, for all entities, in all systems, kills the framerate. I’m already seeing 50% fps drop with only 2-3 test systems doing not much but drawing 10 sprites. A few more systems and I’ll be down to unplayable fps.

What I could probably do is to encapsulate the entity+components into a special SystemEntity container class, which has references to the components of that entity (strong references).
I could even put the processing logic into those SystemEntity classes, so the System really just iterates a collection and invokes some sort of “process()” method on those.

Now, but what would then be the point of the Systems if they were just there to execute the SystemEntities? I might as well just have one System which did that, or none?

Why couldn’t I create something like RegenerateHealthEntity class which had the logic to regenerate the health of an Entity using the RegenerativeHealth and Health components? E.g.
SystemEntity se = new RegenerateHealthEntity(entity, regHealthComp, healthComp);

But that’s code duplication, memory overload, and just bad design.

Caching, batching, I’m not sure what you mean. FlyWeight I use though.

But without a better idea how to really implement a good fast well designed architecture around I’m really just going to drop this idea as “impractical”.

Stop thinking about entities as having any importance – that’s classic OOP, and has no place here. You fetch components, not entities. Most of the time, your systems don’t even look at the “entity” – they never have any reason to. Also, Systems SHOULD NOT HAVE A COLLECTION OF ANYTHING, they are merely data-processors – you hand them a list of bunched components, they iterate over them, The End.

Why is the “components that match criteria X” function slow? This is one of the parts in an ES that needs to be lean and fast. Which methods / stacktraces are the bulk of your lost CPU time? Standard profiler questions, etc…

I’m sorry, but this:
“you hand them a list of bunched components”


positionSystem.move( MOVEABLE_ENTITIES );
public List getAllEntitiesPossessing( Class… requiredComponents )

Do systems process entities, and then look up their components, or do they process components? Perhaps as:

regenerateHealthSystem.process(healthComponents); ?

Yep. That was shorthand. By “ENTITIES” I meant “whatever custom datastructure you use to hold a bunch of components as a single entity and put those bunches – one per matching entity – into a single container”.

e.g. I’ve made ES’s where the arguments were a single pointer, and an int. Receiving systems then stuck one or more structs over the top, and zoomed through memory, fast, hoovering up long stretches at once, stopping only after (int) bytes.

e.g. Equally, my Android system hands-in a List-of-Lists. Each sub-list is “the components for a particular entity, but only the ones you actually want, Mr System – whichever ones you asked for”. Much less efficient, but easy enough to switch to a faster version later, and conceptually the same thing.

Anyone trying this needs to read the original ES articles carefully first, and be sure within themself that they can “think” in ES terms, before going further. It’s so easy to accidentally slip into OOP design, some people (myself included) have to really push themselves to stop doing OOP when they start ES.

(the MMO ES articles go on at length about how you use the ES and why the bits that are there are … the way they are. I believe they explain reasonably well how/why *in practice* you do all your interaction with references to Components, and never concern yourself with which “entity” they are part of, unless you’re debugging your ES library itself, or serializing it or something else where you want to store/retrieve some identifying lable)

I thinking I’ll really like this approach once I understand it, however I’m a little confused about the systems, components, and individual entity behaviors. In this example it looks like an entity is just a place holder and components are just bags of data associated with that place holder. And I’m guessing a system is the code the actually manipulates those components. Is that about correct?

As an example lets say I’m writing a game where all the enemies are chess pieces and they must move like chess pieces. I believe I would create components for position on the board, rendering information, and one that describes which chess piece it is (White or Black and Rook, Queen, Pawn, etc). Then would I have a ChessPieceMovementSystem that manipulates the pieces and moves them around?

Why not use an approach where entities have Components and Behaviors? Components hold the data and behaviors contain the code that manipulates those components. The behaviors could be very generic or very specific depending on the need of the game. I could write it using a single ChessPieceMovementBehavior or I could write it with multiple behaviors like QueenMovementBehaviour. In the later case all the piece movement handlers would work against the same position component. Is there some major disadvantage to this approach that I’m missing?

You can have behaviours if you want – they just aren’t part of the ES. The internal implementation of a system can be *anything* you like – it doesn’t matter, just so long as the entities themselves are pure data, no code.

In your description, why do you think “entities have .. behaviours”? Unnecessary – the entity doesn’t need to have any awareness of this “behaviour” thing – the movement system can handle that mapping internally, perhaps it has a lookup table of “PieceComponent.Knight == BehaviourKnight” etc.

Thanks for the informative articles.

I was curious, since Entity is never anything more than an identifier and you are trying to avoid getting OOP in your ES, why did you choose having an Entity class at all? Would it not be enough to simply pass the id itself around?

yes, indeed.

The only reason for a class is for convenience – you can, for instance, instantiate it. And put convenience methods on it.

(you have to write your constructors to do something a bit clever, since the real reason for “instantiating” it isn’t to get an OOP objct, but to cause the ES (somewhere) to allocate a new ID and reserve it for you. e.g. “find the singleton EntityManager, request creation of a new entity, grab that ID, and stick it in my public variables”)

No plans right now – just haven’t thought about it. The ES part I’m more likely to, but I wouldn’t bother unless I or someone else was committed to maintaining it as a project. I hate “dead” open-source projects.

The first challenge is to finish it and get it up on the Marketplace – there’ll definitely be a free download, but I MIGHT do a paid version too (mainly just to get more practice using the Google payments system).

@adam – I’m interested in ES part + for example Movement/Render systems. More in form of a complete code to back the article then the game itself.. There are some issues I’m having issues implementing ES that I’m sure you had to solve in your game that are to hard to explain in form of a comment to a blog post.

Just found your blog and I love it. Exactly the kind of stuff I’m interested in.

In one of your earlier articles, you write
“There is a one to one relationship between Systems and AVAILABLE aspects (i.e. types of Component)”

Reading this article, it looks more like a given system will work on entities that contain a given set of one or more components. So the rendering system would operate on all the entities that have both a position component and a renderable component. Maybe you would go to write a new system, and it doesn’t even need a new type of component, just a different permutation of the existing component types.

Is this what you mean, or am I missing something?

@adam – That makes sense I guess. A behavior in my model would have basically been a system, just tied to the entity. It really wouldn’t have saved me much code wise but would have sucked up more memory and possibly performance. In my example I could just as easily write a system for each chess piece if I really needed.

The code would probably be interesting to see, however the entity system isn’t really where I’m having a problem. I’ve got a basic entity system based on the above code that I think will work great. (Thanks for the great article!) Where I’m having issues is with the systems. As an example, one of my design decisions was to include the game background as an entity. It would allow me to animate it if I wanted, or apply effects to it, etc. I also have buttons that will be constructed of a sprite and then a label overlay (and occasionally another overlay on top of that. The problem I’m having is figuring out a good way to handle the z-order of my entities during rendering. I may just settle with a TreeMap for now and just ensure that I instantiate objects in the order they need to be rendered.


You’re right – the 1-to-1 thing was a theoretical ideal, rather than what tends to happen in practice.

My point was that you should *generally* assume a 1:1 relationship. Even in a large project, it will be roughly that – because, frankly, why bother adding a new component type unless it’s because you need a system that requires it?


I’d still expect just one system to handle movement of all pieces – it might use Behaviour objects internally, or it might have a giant “switch” statement internally.

re: Z ordering, why don’t you just assing things to named virtual layers, and use that to sort them? Or, more powerfully, standard practice these days seems to be to create a hierarchy of nested containers (seems like almost every language has used that paradigm since the 1990s)

Using a C ES system as an example, is wiring Components via pointers to an individual data item of other component an acceptable approach, for example:

Vec2* pos;; // set to &pos of Position2DComponent
Vec2 vel;
Vec2 acc;

Vec2 pos;

I would imagine with Sql you would store the comp_id and the wiring as some type of required struct meta-data, where the struct is simply a mapping of the component data.

I am also assuming when iterating components it would be acceptable as well as performant to use a switch/jump-table on component->type to update/render/etc ?

Thanks for the fantastic series of articles, I started writing a component based system without even knowing what it was simply for performance and flexibility, and I am definitely looking at sql for clean scalable storage, with raw byte code caching for performance.

Comments are closed.