Apollo Entity Framework

Shared Code
#1

Hurray, yet another entity framework ;D what can I say, I love them… but this one has been dwelling in idle folders for a while, so instead of letting it to into byte oblivion I decided to freshen it up and put on google projects, so here is my post I posted on the Slick forums:

I haven’t been doing much game programming lately, but I have been working on this neat entity/component framework for a while and wanted to push it out into the world now that I think it’s relatively useful.

What’s the similarities between this and Artemis? Not a lot, but Apollo is more of an traditional way of using entities in your games, where you have an Entity object like a jar encapsulating the components, managers and other things. I will create a proper documentation once I get feedback. It’s a generic framework, meaning it can be used for 2D or 3D and whatever libraries.

I won’t go into much details here, I had previously submitted a thread on Apollo when it was in its infancy, but it has evolved more now.

So, without further delay I have provided Google projects (mercurial) access to both Apollo framework an example game (very simple):

Apollo homepage: http://gamadu.com/apollo/

Apollo Entity Framework
http://code.google.com/p/apollo-entity-framework/

Apollo warrior example game
http://code.google.com/p/apollo-warrior/

You can check both projects out (eclipse) and run without much trouble. Apollo warrior has all the dependencies it needs, and the Apollo framework has no external dependencies.

Please provide feedback.

Some clarification:

Managers: Used as something that has a specially organized collection of entities, or something that provides a special functionality to all entities. E.g. “Managing entities”, it’s an outside hands manipulating entities or something that keeps track of entities in some special manner, like tagging them, grouping them, etc.

Entities: Just a shell for components really. If you’re doing something in entities you’re doing it wrong, the Entity class should not really be extended in any way. There’s a built in event system as well.

Components: Data and functionality. Not much else to say.

Builders: Encourages you to put entity creation (templating) into these special builders that create new instances of entities along with all their components and events.

Spatials: Anything that is displayed needs to be a spatial. Spatial is a component and is rendered using a provided RenderManager. Node is spatial as well and allows you to attach multiple spatials to an entity, and that is useful beyond belief.

#2

You might consider some docs, as it is a big commitment to try it out just to find out what it is and how it is used. I find a single page that goes through the high level functionality start to finish is both easy to write and usually better than the jumbled mess that happens any other way. Just define “high level” as appropriate to keep the amount you need to write reasonable.

#3

That and an example project that is “slightly less simple”.

#4

Will write it and put it up tonight.

#5

I’ve added a short introduction page for the framework:

http://gamadu.com/apollo/

#6

Cool, thanks. It is a little hard to follow (it jumps around rather than having a logical order of concept introduction), but there are docs so I won’t complain any further. :wink: One tip though, if docs don’t use the word “you”, they are more concise.

Apollo looks interesting. My experience with entity systems is a few internet articles and trying to reimplement an existing game with them. I gave up because getting anything done required grabbing the right components and was annoying. It’s hard to see if the Apollo way of doing things is better and if it is flexible enough for games. I would have to implement a real game with it before I can really give any useful feedback. I would like to try out an entity system again, so Apollo is on my short list. :slight_smile:

#7

Reusing components is clever, but I don’t know if bundling ready-to-use components with Apollo will benefit anyone because every game (and programmer) has it’s own requirements.

But I’m just quickly writing up some documentation. Later it will hopefully evolve into a better manual that isn’t all scattered on a single page.

#8

I’m not finished with the documentation page right now… But I just wanted to say, that I love the way you explain stuff in the overview page. :slight_smile:

#9

Okey… sorry for double-post, but I’m just gonna go ahead and do this :stuck_out_tongue:

I really like the Idea of a Entity-Framework, even though I think it is pretty hard to write a Library for something being extremly different between two different game-ideas.

You seemed to have accomplished that pretty good. The only thing I don’t like (besides not shipping jars :P) is, that you implemented the access to managers and especially the access to the entity or other components from a component with annotations, and Unsafe (I think?).

I would propably only let the Comonent have a “Entity” argument in the constructor, which will be saved, if wanted. And then you are able to access the entity the Component belongs to and also the other Components the Entity has. For me that would be better, because of no use of Unsafe, or reflection api in general.

#10

Not quite sure what you mean, but once I manually resolved all the dependencies for a component inside the component. The result was a ugly mess of having to look up this and that entity, components and managers in every initialize method for every component. I wanted more convenience, only defining the fields and let something else do all the connections (dependency resolving), resulting in a much cleaner code and easier/faster to use. Actually jojoh added that for me, because he had nightmares over the hard labor doing all that, and I’m pleased he did.

So, now I have three annotations, @InjectComponent, @InjectManager and @InjectTaggedEntity(tag).

I honestly don’t know why that’s so bad.

#11

Yes right. I just took a look at your source code.

You did not use Unsafe, but you used Reflection api… (“field.setAccsessible(true);”, “field.set(…);”).

And now I also understood the purpose for the Annotations. It’s something like a shortcut? So you don’t have to write:

getWorld().getManager(Class.class.cast(field.getType()));

for example?
Okey, then I’d say that’s fine :slight_smile:
Some pretty strange magic happening there… because some object aren’t null anymore… but fun :smiley:

I’m right now looking at more code now…
wait for my edits (btw, already found a little mistake in “Bag.java”. The comment says the initial size would be 64, but it seems to be 16)

#12

Ah, I will take a better look at Bag later, right now it does what it does, but I’ll have to ensure it does it better :slight_smile:

But yes, the annotations are “shortcuts” or “convenience” to reduce lines of code. If there wasn’t a @InjectComponent you’d have to do:

initialize() {
  this.transform = owner.getComponent(Transform.class);
}

or in case of @InjectTaggedEntity:

initialize() {
  TagManager tagManager = world.getManager(TagManager.class);
  this.playerEntity = tagManager.getEntity("Player");
}

instead of

@InjectTaggedEntity("Player")
Entity playerEntity;
#13

why not use proper dependency injection, like guice.

You could also use the standard annotations so that each user can choose which DI framework he wants to use.

#14

Not everyone are very DI savvy. I don’t like to introduce complex things to the framework when I don’t need to, it can make people shy away from using the framework. Having dependencies on other libraries adds overhead, if only a mental one. I like the fact Apollo comes in one jar and there’s no hassle.

Also, the purpose is not advocating the use of dependency injection throughout the game, what comes with Apollo is just to do very limited simple things that occur frequently.

#15

Very good, keep that up please.

Annotations are great, but if every API and framework out there starts to use them then you end up putting a dozen annotations everywhere. The JEE environment is already starting to move in that direction, it isn’t pretty.

Moderation is the key.

#16

It’s a good thing I’m not the warlord of Java. I’d been adding contracts and compiler hints (via annotations) right-and-left. Although they would mostly be of interest for high-performance & libraries.

#17

:slight_smile: Yup.
The annotations included in Apollo are just for convenience. Nothing requires you to use them. You can still code your dependencies in the initialize method of each component. If you dislike them, forget about them.

But I’m hoping there’ll be other questions than about annotations :slight_smile: