Artemis Entity System Framework

Quick tutorial

Please note that the code shown here should be considered a pseudo-code.

Setting up Artemis in a game container and game loop

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

public class MyGame {
	
	public void MyGame() {
		world = new World();
		
		world.setSystem(new MovementSystem());
		world.setSystem(new RotationSystem());
		world.setSystem(new RenderingSystem());
		
		world.initialize();
		
		while(true) {
		    world.setDelta(MyGameTimer.getDelta());
			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.

Now, for the part where true is passed as an argument when adding RenderingSystem to the world, that means the RenderingSystem is marked as "passive", meaning it won't get processed when calling World.process(), allowing you to call RenderingSystem.process() manually where and when you want to do the rendering.

Defining a component

All you need to create your own component is to extend the Component class.

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.

public class Position extends Component {
	private float x;
	private float y;
	
	public Position() {
	}
	
	public Position(float x, float y) {
		this.x = x;
		this.y = y;
	}
	
	public float getX() {
		return x;
	}
	
	public float getY() {
		return y;
	}
	
	public void setX(float x) {
		this.x = x;
	}
	
	public void setY(float y) {
		this.y = y;
	}
	
	public void setPosition(float x, float y) {
		this.x = x;
		this.y = y;
	}
	
	public void addX(float x) {
		this.x += x;
	}
	
	public void addY(float y) {
		this.y += y;
	}
}

Using a constructor and getters/setters is up to you. You could define your fields are public and simply work with them like that.

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.

Entity e = world.createEntity();
e.addComponent(new Position(200,400));
e.addComponent(new Velocity(2.4f,0.9f));
e.addComponent(new Rotation(180));
e.addToWorld();

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.

public class MovementSystem extends EntityProcessingSystem {
	@Mapper ComponentMapper<Position> pm;
	@Mapper ComponentMapper<Velocity> vm;
	
	public MovementSystem() {
		super(Aspect.getAspectForAll(Position.class, Velocity.class));
	}
	
	protected void process(Entity e) {
		// Get the components from the entity using component mappers.
		Position position = pm.get(e);
		Velocity velocity = vm.get(e);
		
		// Update the position.
		position.addX(velocity.getXVector() * world.getDelta());
		position.addY(velocity.getYVector() * world.getDelta());
	}
}

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.

Other useful tutorials and articles on external sites

Adam Martin's T-Machine.org

http://t-machine.org/ (recommended, but search for "entity system")

Quick tutorial

Setting up Artemis in a game container and game loop

Defining a component

Creating an entity

Defining an entity system

Other useful tutorials and articles on external sites

Entity/Component Game Design: A Primer

Entity/Component Game Design That Works: The Artemis Framework

Introducing: Artemoids

Reusing Artemis entities by enabling, disabling and storing them

How we use Box2D with Artemis

Scripting with Artemis Entity System Framework

Object-Oriented? No, this is an entity system

Entity Oriented Programming

Entity Systems Project

Entity System 1: Java/Android

Adam Martin's T-Machine.org