Quick tutorial

Game Setup

Here you'll see a demonstration how to set up Artemis to use within a libgdx game loop.

import com.artemis.World;
import com.badlogic.gdx.Game;
import com.badlogic.gdx.Gdx;

public class MyGame extends Game {

    World world;

    @Override
    public void create() {
        world = new World();

        world.setSystem(new MovementSystem());
        world.setSystem(new RotationSystem());
        world.setSystem(new RenderingSystem());

        world.initialize();
    }

    @Override
    public void render() {
        world.setDelta(Gdx.graphics.getDeltaTime());
        world.process();
    }
}

That's all you need to get your world running with a few systems. Of course there are no entities yet in the world.

Defining a component

All you need to create your own component is to implement the Component interface.

import com.artemis.Component;
import com.badlogic.gdx.math.Vector2;

public class PositionComponent implements Component {

    public Vector2 position;

    public PositionComponent() {
        position = new Vector2();
    }

    public void add(float x, float y) {
        position.add(x, y);
    }

    @Override
    public void reset() {
        position.set(0, 0);
    }
}

Please note that components do not contain any logic code. It may however contain getters and setters, and other methods that can assist in that regard. For simplicity (and speed) we will use public fields instead. Note the required reset() method. It is called when a component is release back into the component pool.

Creating an entity

To create an entity you need to retrieve an entity instance from the world. Then you can start adding components into it.

The lifecycle of an entity is a little more complex than this. Entity.addToWorld() will activate the entity in the world, Entity.deleteFromWorld() will delete the entity from the world, but Entity.changedInWorld() has to be called whenever you've made a modification to an entity that has been added to the world, e.g. adding or removing components. Defining an entity system Now we need to add the logic part into the game. EntitySystems process the components of entities and manipulate them. We'll demonstrate how by defining a MovementSystem that uses the aspect consisting of Position and Velocity.

When defining an entity system class you need to pass an instance of Aspect into the super constructor. You need to use Aspect.getAspectForAll(Class<? extends Component>... types). You can compose Aspects with AND, OR and exclusion conditions. ComponentMappers are the optimal way of retrieving a component from an entity. Using the @Mapper annotation they are automagically injected into your system.