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 executes the internals of the game loop by setting the delta of the world and calling world.process() to process the systems.
• Lastly, the override of the resize method ensures that the camera is updated correctly.

Defining a component

We instantiated a couple of components in the QuickGameDemo class. Let's take a look at their declarations.

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

public class PositionComponent implements Component {

    public Vector2 position;

    public PositionComponent() {
        this(0, 0);
    }

    public PositionComponent(float x, float y) {
        position = new Vector2(x, y);
    }

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

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

public class VelocityComponent implements Component {

    public Vector2 velocity;

    public VelocityComponent() {
        this(0, 0);
    }

    public VelocityComponent(float x, float y) {
        velocity = new Vector2(x, y);
    }

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

Note that components do not contain any logic. They are usually simple data container objects.

In this example the components' member variables are given public access this is done for speed and simplicity of access. However, if you feel strongly about encapsulation, you are more than welcome to wrap the member variables with get/set functions appropriately. Other simple methods may be added here for example add/subtract. However, anything more complex should be relegated to Entity Systems.

Also note the required reset() method. It is called when a component is release back into the component pool.

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.