scene2d

The scene2d package is a 2D scene graph, which is useful for managing hierarchical groups of actors. It provides support for handling input and drawing rotated and scaled actors in a coordinate system relative to the parent actor. It also provides an action framework for manipulating actors over time (tweening). The scene2d.ui package provides actors useful for building GUIs.

Important classes

The Stage class has a "root" group to which applications will add their actors. The stage has a camera and a SpriteBatch. The camera's viewport is the size of the screen. When the stage is drawn, the SpriteBatch is passed to the root group. The stage is an InputProcessor and passes input events to the root group.

The Group class is an Actor that contains other actors. Rotation and scale of a group affects its children. A group delegates drawing and input handling to the appropriate children. The group transforms coordinates so the children receive coordinates in their own coordinate system.

The Actor class provides all the base functionality for a node in the scene graph. It has a position, size, scale, rotation, origin, and color. It has an optional name, which allows actors to be looked up by name and can aid in debugging by printing the actor hierarchy with meaningful names.

Stage setup

A stage has a viewport size. While this can be specified in the constructor, it is usually a good idea to set the stage's viewport when the application is resized. The constructor also takes a boolean named "stretch". If true, the stage will be stretched to the device's resolution, if not the same size. If false, the larger dimension of the stage will be increased to match the device's resolution. If setting the viewport to the device's resolution in the "resized" method, the stretch setting doesn't not matter.

The stage has an "act" method that takes a delta time since last frame. This causes the act method on every actor in the scene to be called, allowing the actors to take some action over time. Calling act on the stage is optional.

private Stage stage;

public void create () {
	stage = new Stage(0, 0, true);
}

public void resize (int width, int height) {
	stage.setViewport(width, height, true);
}

public void render () {
	Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT);
	stage.act(Gdx.graphics.getDeltaTime());
	stage.draw();
}

public void dispose() {
	stage.dispose();
}

Actors

Extend the Actor abstract class to draw, do hit detection, and to handle input in the scene graph.

Drawing

When draw is called on the stage, it calls draw on the root group. Group calls draw on its children. To draw an actor, implement the draw method:

TextureRegion region;

public void draw (SpriteBatch batch, float parentAlpha) {
	batch.setColor(1, 1, 1, parentAlpha);
	batch.draw(region, x, y, width, height);
}

The SpriteBatch an actor receives has already been transformed by the parent group so that the actor's position, size, rotation, and scale is relative to the bottom left corner of the parent group. This makes drawing in the correct place with the SpriteBatch very easy. In the code above, the x, y, width, and height are public fields on the Actor class.

If visible is set to false on an actor, Group will not call draw for the actor.

The parentAlpha that is passed to draw is the alpha from the parent's color. If drawing takes this into account, a group and all its children can be translucent.

SpriteBatch begin has already been called when the actor's draw method is invoked. If an actor needs to perform drawing some other way, such as with a ShapeRenderer, the batch should be ended and then begun again. Of course, this causes the batch to be flushed, so should be used judiciously. The transformation and projection matrices from the SpriteBatch can be used:

private ShapeRenderer renderer;

public void draw (SpriteBatch batch, float parentAlpha) {
	batch.end();

	renderer.setProjectionMatrix(batch.getProjectionMatrix());
	renderer.setTransformMatrix(batch.getTransformMatrix());
	renderer.translate(x, y, 0);

	renderer.begin(ShapeType.Rectangle);
	renderer.rect(0, 0, width, height);
	renderer.end();

	batch.begin();
}

Hit detection

When hit is called on the stage, it calls hit on the root group. Group calls hit on its children. The first call to hit that returns an actor is returned by stage. To do hit detection, implement the hit method:

public Actor hit (float x, float y) {
	return x > 0 && x < width && y > 0 && y < height ? this : null;
}

The hit method returns the actor that was hit, or null if none was hit. The coordinates are given in the actor's coordinate system. The above is a typical implementation, returning "this" if the point is within the actor's rectangular bounds.

Input handling

To handle touches, implement the touchDown, touchDragged, and touchUp methods:

public boolean touchDown (float x, float y, int pointer) {
	return true;
}

public void touchDragged (float x, float y, int pointer) {
}

public void touchUp (float x, float y, int pointer) {
}

When a touchDown occurs on the stage, it calls touchDown on the root group. Group calls hit on its children. The touchDown method is called on the first actor returned by a call to hit. If touchDown return false, it means the actor chose to ignore the touch down and the process continues on the next actor. If touchDown returns true, the actor becomes the focused actor. This means it will receive touchDragged and touchUp calls, even if they do not occur over the actor. When touchUp is called, which is guaranteed to happen, the actor loses focus.

The Group touchDown method is what propagates the touchDown events to the group's children. When a Group's touchDown method is overridden, if the super method is not called, children will not receive any touch events.

There is an additional touch handling method that may be overridden, touchMoved. This is only ever be called on the desktop and is called when the mouse is moved.

Like the hit method, coordinates passed to the touch handling methods are given in the actor's coordinate system.

If touchable is set to false on an actor, Group will not call touch handling methods for that actor.

To handle key input, override the keyDown, keyUp, and keyTyped methods. These will only be called on the actor with keyboard focus, which is set and cleared by calling keyboardFocus on Stage.

To handle mouse scrolling, which only occurs on the desktop, override the scrolled method. This will only be called on the actor with scroll focus, which is set and cleared by calling scrollFocus on Stage.

Actions

The current action system will be refactored soon. This section will be left blank until then.