Artemis - Entity System framework

Shared Code
#1

Me and Spiegel (Tiago Costa) have been working for a few weeks on this framework. It’s meant to separate data, logic and view. It’s currently just experimental and is meant for review purposes only, use at your own risk.

It’s inspired by Adam Martin’s “Entity Systems are the future of MMORPG” articles published on http://t-machine.org/.

This framework requires different thinking when it comes to game programming. No longer are entities just self-contained objects, but consist of data/state components which are processed by systems/aspects.

Entity is an irrelevant object, it however still exists for design simplicity and convenience.

Components are attached to entities and they contain data or state for that entity. Imagine a components like Transform and Velocity.

Systems “process” certain “aspects” of entities. You can imagine one aspect being “Movement”, and you would create a MovementSystem which processes all entities containing the Transform and Velocity components.

Currently there are 3 types of systems you can extend from:

  • EntitySystem: the very basic raw system, which simply allows you to handle the processing loop however you want.
  • EntityProcessingSystem: used to process individual entities of a certain aspect sequentially. If you always need to process all entities use this.
  • IntervalEntitySystem: a very basic and raw system but is only executed at certain intervals, e.g. it runs processing every 100 ms. This way you can tune your game better for performance.

This is a very fast system and offers a lot of flexibility, whilst keeping your code clean. It’s NOT dependent on any particular graphics library or any library, you can use this for your Java2D, Slick, or raw OpenGL games.

Click here for demo game, code and jars for everything:
Game demo: http://gamadu.com/games/starwarrior/
Artemis here: http://gamadu.com/artemis/

We’re looking for feedback, so please provide if you can.

Any questions? Please ask here.

#2

Very nice and clean!

I did it a little different and have most of the logic in the components. I also have systems but use them mostly to integrate with external libraries like physics, scenegraphs etc. I find it a little bit tedious to keep track of component “peers” in the systems. For example your RenderSystem must keep track of the spatials for all the entities.

#3

It’s not so tedious really:


// Insert.
spatials.set(e.getId(), spatial);
...
// Retrieve and render.
Spatial spatial = spatials.get(e.getId());
spatial.render(g);

I use the bag like a map, only much faster.

You could make a component that is a ContextHolder for that entity, and all systems requiring this contextHolder can process it as well. That way you can just do:

ContextHolder ctx = contextHolderMapping.get(e);
Spatial s = ctx.getSpatial();
s.render(g);

Really up to you how you use the framework. But the general principal is that components are pure data, they do not contain logic for data processing, except for getter/setter purposes. The idea is that you can flush all those components into a savefile, and easily load it back in the game later. And even if you change the components or systems, you can still use old savefiles. Well, Adam talks about this idea, but he focuses on databases. I don’t care about those, and there is nothing in Artemis that supports that, but you can make your own saving/loading that uses a database. Components are then just tables, with a entityId reference.

#4

I have to admit the Bag is some nifty piece of code.

I use a custom property system instead of beans in my components. The component data is specified by the properties. I can automatically serialise the world to and from xml. So in that sense it is not a big difference.

#5

You might want to fix up the cardinal directions for your sin/cos lookup table:
http://code.google.com/p/libgdx/source/browse/trunk/gdx/src/com/badlogic/gdx/utils/MathUtils.java

#6

Nice, very clean, and some really good ideas.

There are two parts here, I think - the part about splitting data away from functionality, entities with components, etc - and that looks very nice. The other part brings a wrapper for the processing logic into the framework.

I’m a bit wary of the inversion of control the second part brings. It makes the user rely on the framework to do everything they need flow-wise, and also imo makes it harder to understand the flow.

For example, I don’t see any mechanism for transitioning between game states, and since the framework controls the run loop, it seems difficult to add that. It also makes it more difficult to use in an existing project.

So my question is, why not leave the main loop to the user? EntitySystem et al seem to be just a wrapper for iterating over a collection of stuff, so if there was just a way to get the right collection (say, “give me everything that has a Velocity”), it’d be easy to iterate over it and just do whatever you want with the entities. I’m not seeing what EntitySystem adds that justifies giving up control of the run loop.

All in all, though, very nicely done.

#7

I do not quite understand this comment.

Regarding the game states, this is not a game engine, it’s simply a entity framework. Slick has support for game states, and you can use the entity framework within one of those, but use something else in other game states, e.g. for menus.
I’m not quite sure what you mean with the “main loop”. You can execute the systems in whatever game loop you choose. The demo provided runs in Slick, but you could run it as a simple Java2D app, or as a pure LWJGL app. The game loop is controlled by you.

EntitySystems does not take over the loop, they process a set of entities of certain aspect. You could make a VelocitySystem that just processes Velocity.

#8

Oops, I didn’t see the part where it’s using Slick’s AppGameContainer. Sorry about that - I thought bit was part of your framework as well. So never mind most of what I said :slight_smile:

Edit: Hmm, the more I look at it, the more interesting it is.

A few minor questions:
Why is there a Component class? Having to extend it means you can’t extend something else.

In ComponentMapper:


public T get(Entity e) {
  return classType.cast(em.getComponent(e, type));
}

Could that be a (T) instead of the an extra cast() method call? I only mention it because as a result of this framework, this function is going to get called a lot.

Really, that’d be my main hesitation in using this - seems like there’s going to be a fair bit of time spent getting components of entities, which is all overhead compared to a more standard approach. I wonder how it’ll hold up. Performance concerns are usually overblown, but if one is using this framework and it becomes an issue, it’d be kind of hard to optimize this part or switch to a different approach. It looks like you’ve put a lot of effort into making it efficient, though.

#9

Hey, thanks for the feedback.

  1. A class or a interface, well, I need to give that more thought. Interface may be too flexible, and although we like to have a flexible framework, there is a difference between flexibility and using the framework in a wrong way.

  2. The casting has not been an issue in my mind. We’re doing the method casting instead of (T) casting, which gives a “unchecked cast” type safety warning. I’ve run the framework with tens of thousands of entities and this doesn’t get reported in the profiler. Although, I’d surely like to run more tests, I doubt we can be without casting. To provide some reckless statements, I’d say this would take 0,000000001% of the game loop time. :slight_smile:

#10

  1. What’s the reason to require components to extend/implement something?

  2. Ah. Well, if it doesn’t show up at all in a performance analysis, then it’s not an issue :slight_smile:

I wish Java had a language feature to support this type of design explicitly. Something like saying, “my class implements interface using implementation of it”, letting you build up a class out of components. You can do it now by having member variables for the components and tons of delegate methods, but it’s a pain.

I’m using something halfway similar to Artemis in my code, by the way - a data store that sorts objects you add to it based on the classes they are/interfaces they implement. Then you can just say “give me a list of everything that implements Collidable” and iterate over it. Artemis is going much further with it, though.

#11

I did write a Entity/Component system with those characteristics, based on the “GOCS” article in Game Gems 5 (I think). You have a “family” of a component type, and you can have a interface, e.g. Health, and then implementations like RegenerativeHealth or StandardHealth. Then you could have components communicating with each other (of external packages) using just the Health interface.

That’s a fine design, and probably easier to understand than the framework discussed here.

I did write a precursor to Artemis (incidentally called “Artemis” as well) at here: http://slick.javaunlimited.net/viewtopic.php?t=2937
However, the rendering is part of the components. It does provide simplicity, but if I were to do it again I’d only have logic/data in components and have Spatials that take care of rendering for each entity.
There’s no perfect way of doing this stuff really, and you can easily go insane by trying to make the perfect system.

#12

Hmm, yeah. It seems better to have all rendering logic for a single entity in one place, instead of spread over several components.

I hear you. I’ve pretty much given up on that and just refactor every time I need something the current architechture doesn’t handle. Thankfully modern IDEs make it easy, or at least doable.

Rather, first I try to hack it. If that doesn’t work, then refactor :slight_smile:

#13

There’s a SVN and github now, and now a special “site”:

#14

I updated the site to contain a little more information:

Now being ported to C# and probably going to be used in a engine for a game made in Brazil.