Quick tutorial

This is a quick tutorial to get you started using Artemis inside a libgdx game. We will implement a very simple example of an object moving across the screen.

There's a separate gdx-artemis-demo project that contains the source code for this tutorial tutorial in com.artemis.demo.quick. Feel free to check it out and play around with it.

Game Setup

First we will create a simple game class that will instantiate an Artemis world and execute the game loop.

import com.artemis.Entity;
import com.artemis.World;
import com.artemis.demo.quick.components.PositionComponent;
import com.artemis.demo.quick.components.VelocityComponent;
import com.artemis.demo.quick.systems.MovementSystem;
import com.artemis.demo.quick.systems.RenderingSystem;
import com.badlogic.gdx.Game;
import com.badlogic.gdx.Gdx;
import com.badlogic.gdx.graphics.OrthographicCamera;

public class QuickGameDemo extends Game {

    public static final int GAME_WIDTH = 400;
    public static final int GAME_HEIGHT = 400;

    World world;
    OrthographicCamera camera;

    /**
     * Initializes all of the in-game objects
     */
    @Override
    public void create() {

        // create a camera
        camera = new OrthographicCamera();

        createWorld();

        //create a few of entities
        createEntity(200, 200, 20, 20);
        createEntity(200, 200, -20, 20);
        createEntity(200, 200, 20, -20);
        createEntity(200, 200, -20, -20);
    }

    /**
     * Creates the world and adds entity systems to it.
     */
    protected void createWorld() {
        world = new World();

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

        world.initialize();
    }

    /**
     * Creates an entity with a given position (x, y) and velocity (vx, vy)
     */
    protected void createEntity(float x, float y, float vx, float vy) {
        Entity e = world.createEntity();

        PositionComponent pc = world.createComponent(PositionComponent.class);
        pc.position.set(x, y);
        e.addComponent(pc);

        VelocityComponent vc = world.createComponent(VelocityComponent.class);
        vc.velocity.set(vx, vy);
        e.addComponent(vc);

        e.addToWorld();
    }

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

    /**
     * Update the camera if the game screen is resized.
     */
    @Override
    public void resize(int width, int height) {
        float centerX = width / 2.0f;
        float centerY = height / 2.0f;

        this.camera.position.set(centerX, centerY, 0);
        this.camera.viewportWidth = width;
        this.camera.viewportHeight = height;
    }
}

Let's take a look at what's going on here:

• Class MyGame extends the libgdx Game.
• We have two member variables, an Artemis World and a libgdx OrthographicCamera.
• In the create() method we initialize the camera, create the world and create a few entities.
• createWorld() method instantiates the world, adds a couple of entity systems to it, and calls world.initialize(), which in turn initializes all the systems.
• createEntity() method takes an entity's initial position and velocity and creates an entity with the appropriate components. ** Note here that we need to create both the entity and the components by calling world.createEntity() and world.createComponent() respectively to ensure that both entities and components are pooled correctly.
• The render() method will update the delta of the world and call world.process() to execute the systems.

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.