[entity system framework] artemis-odb 0.5.0 and agrotera 0.3.0

[junkdog]

Introduction
If you haven’t heard of artemis or entity systems before, the blurb:

Artemis is a high performance Entity System framework for games, written in Java, and is a framework to manage entities in a game world. It is inspired by Entity Systems are the future of MMORPG blog series by Adam Martin. We also borrowed ideas from Ted Brown who implemented a simple high-performance Entity System in Processing based on Adam Martin’s blog.

The framework is based on the concept that entities in a game world exist as pure identifiers, their components contain only data, and systems process entities based on their aspects. This promotes separation of concern and simplifies game design tremendously.

artemis-odb aims to preserve the simplicity of the original artemis framework while at the same time extending it with new features. The recently released 0.5.0 introduces “packed” components and pooling of entities and optionally components.

agrotera is a small annotation-driven compile-time plugin for reducing boilerplate associated with configuring EntitySystems, Managers and - new in 0.3.0 - general classes. Since agrotera solely relies on compile-time weaving, there is no performance or memory cost associated with its features.

artemis-odb compared to original artemis:

• All known bugs present in original artemis have been resolved.
• Less object allocation.
• New component types:
  • PooledComponent: automatically recycled.
  • PackedComponent: single instance component backed by a static array
• Optional compile-time bytecode weaving: @PooledWeaver and @PackedWeaver annotations rewrites normal com.artemis.Component classes into the requested type.
  • Since weaving takes place during compile-time, this works on android too.

The PackedComponent implementation, while harboring noble ideals, is somewhat naive at the moment:

• Requires setters/getters for all values (I personally much prefer direct field access for components).
• Assumes that the component will be present in all entities (internally, the entity id is used as index in the component’s backing array). Still applicable for Position and similarly ommipresent properties.
• @PackedWeaver requires that all fields share the same primitive type.

Future releases will offer more flexibility in regard to automatically weaving packed components (see here).

The benefit of using the @*Weaver annotations is that the components still look like “normal” POJO components and hence are less prone to mundane errors. Additionally, it may make debugging slightly easier since reverting a woven component back to a normal is a simple as removing the annotation.

agrotera

agrotera removes nearly all boilerplate from systems (well, it could be argued that it’s simply been moved to annotations instead, but the net result is less code):

// inject profiling, invoked at start of begin() and before any exit points in end()
@Profile(using=Profiler.class, enabled=Profiler.PERF_PROFILE)
// Injects ComponentMapper fields for all referenced component types
// and any referenced systems and managers.
// Eclipse's editor/compiler is aware of any injected fields.
@ArtemisSystem(
    requires={Position.class, Thrust.class, PrecomputedThrust.class, GravityAffected.class, RepulseAffected.class},
    systems=GravityFieldComputer.class)
public final class PrecomputedThrustSystem extends EntityProcessingSystem
{
    public PrecomputedThrustSystem()
    {
        // null is replaced with the appropriate Aspect, deduced from @ArtemisSystem
        super(null);
    }
    
    @Override
    protected void process(Entity e)
    {
        Position position = positionMapper.get(e);
        Thrust thrust = thrustMapper.get(e);
        
        gravityFieldComputer.cachedGravity(thrust, position.x(), position.y());
    }
}

From the annotated classes, agrotera can generate a system overview from artemis’ point-of-view:

https://raw.github.com/wiki/junkdog/agrotera/images/matrix_small.png

Bytecode weaving - for both artemis and agrotera - is quite fast. On my laptop (i7 @ 3ghz):

[INFO] --- artemis-odb-maven-plugin:0.5.0:artemis (default) @ hallucinolog-core ---
[INFO] Processed 10 PackedComponents and 11 PooledComponents in 67ms.
[INFO] --- agrotera-maven-plugin:0.3.0:agrotera (default) @ hallucinolog-core ---
[INFO] Processed 25 EntitySystems, 5 Managers and 1 Injected types in 75ms.

Caveats

• There’s a pretty heavy reliance on maven (for bytecode weaving), although most things can still work outside a maven context, as an eclipse builder or as part of an ant script.

• (only agrotera) lombok-pg and lombok aren’t compatible, and lombok-pg hasn’t been updated for some time. I’ve seen some forks that have been busy keeping lombok-pg up to date with lombok - should look into those in the future. lombok-pg is responsible for injecting fields early enough for Eclipse to see them.

• (also mostly agrotera) Eclipse is the only IDE officially “supported”, with projects preferably setup as maven modules. Furthermore, lombok-pg (a fork of the my all-time favorite Project Lombok) is required to make agrotera fly. I’m not sure to what degree other IDE:s are used, but let me know if you think I should add support for others.