Note: This demo has been updated considerably since this original post. The common elements have been factored out into their own library and the application mavenised to provide an easier build process. You can find all the details here.

This is the original post so some of the details have changed…..

I have written a simple demo using LibGDX and some of the ideas I had kicking around from a previous demo. I am quite pleased how this has turned out. I’m going to join the chorus of praise for LibGDX and say it is a lot easier to use than I thought it would be. I was putting off ditching my own framework and adopting it but it was actually fun to use and has an impressive amount of  knowledge behind it. The ability to develop on the desktop and then run it on Android is a killer feature.

This demo is a kind of mixture of framework items and source artefacts to implement a noddy shoot-em-up. The point is to show off how to assemble something which uses mostly the Scene2d classes.

Here is the application running on the desktop.

Game Test

So what is interesting about this demo?

  • Uses Scene2d classes throughout i.e. Actor, Group and Action.
  • Framesprite class which will take spritesheet and run animated sprite.
  • Animated sprite class which composes Framesprite and will respond to actions like  rotate and scale.
  • Director class which routes events and updates actions and maintains the current “scene”.
  • Event driven design which is used to post and respond to actions in the view.
  • Scenes and layers which are used to build up the view.
  • Simple collision detection between Actors
  • Resizable window with constant viewport where touch and mouse position events are adjusted to the window size.
  • Spaceship sprite class with nice interpolated drag-follow action.
  • Texture cache backed by a Texture Atlas (to be honest I’m still not sure if I am using this properly).
  • Nice background Sprite which loops a star-field image down the screen in old-skool fashion.

This is a bit of an experiment to see if I could take what I had and make it scale up a bit more. The key concept is as follows:

  • You do not have a big blob of code which maintains a world state which is examined and updated according to a set of rules with lots of if..then and case statements
  • You do have pooled objects which can send and receive events as the render loop runs and respond to events to perform some action on the view.  Actors in the view are more autonomous and encapsulate their logic and the actions which they can perform.

The demo code is here.

Demo in detail



Some of the source code below is abbreviated, use the source download rather than cutting and pasting if you are interested in the source.


The Frame animation Sprite implements an Actor which takes spritesheet and implements straightforward animation. You cannot run actions like rotate on this as Actor does not have this attribute. You can make it move though. This lifts some of the example code from the LibGDX samples and reworks it into an Actor.

public class FrameSprite extends Actor
{
	private TextureRegion[] frames;

	private Animation animation;

	private TextureRegion currentFrame;

	private float stateTime;
	private boolean looping;

	public FrameSprite(TextureRegion texture, int rows, int cols, float frameDuration, boolean looping)
	{
		this.looping = looping;

		int tileWidth = texture.getRegionWidth() / cols;
		int tileHeight = texture.getRegionHeight() / rows;
		TextureRegion[][] tmp = texture.split(tileWidth, tileHeight);
		frames = new TextureRegion[cols * rows];

		int tileWidth = texture.getRegionWidth() / cols;
		int tileHeight = texture.getRegionHeight() / rows;
		TextureRegion[][] tmp = texture.split(tileWidth, tileHeight);
		frames = new TextureRegion[cols * rows];

		int index = 0;
		for (int i = 0; i < rows; i++)
		{
			for (int j = 0; j < cols; j++)
			{
				frames[index++] = tmp[i][j];
			}
		}

		width = tileWidth;
		height = tileHeight;

		animation = new Animation(frameDuration, frames);
		stateTime = 0f;

	}

	/**
	 * Reset animation.
	 *
	 * You can use this to ensure the animation plays from the start again. It's
	 * handy if you have one-shot animations like explosions but you are using
	 * re-usable Sprites. You must reset the animation to ensure the animation
	 * plays back again.
	 */
	public void resetAnimation()
	{
		stateTime = 0;
	}

	/**
	 * Check to see if animation finished.
	 *
	 * @param stateTime
	 *
	 * @return True if finished.
	 */
	public boolean isAnimationFinished()
	{
		return animation.isAnimationFinished(stateTime);
	}

}

The Animated Sprite class composes the FrameSprite to allow actions such as rotate and scale to work upon it.

public class AnimatedSprite extends Group
{
	private FrameSprite frameSprite;

	/**
	 * Create sprite.
	 *
	 * @param texture
	 *            The animation texture.
	 * @param rows
	 *            The animation texture rows.
	 * @param cols
	 *            The animation texture rows.
	 * @param frameDuration
	 *            The animation frame duration.
	 */
	public AnimatedSprite(TextureRegion textureRegion, int rows, int cols, float frameDuration)
	{
		frameSprite = new FrameSprite(textureRegion, rows, cols, frameDuration, true);

		this.width = frameSprite.width;
		this.height = frameSprite.height;

		addActor(frameSprite);
	}

	@Override
	public Actor hit(float x, float y)
	{
	    return super.hit(x, y);
	}
}

A scene is a Stage whichs maps to the size of the view and implements an InputMultiplexer to which input events are routed. When the Director makes a scene active it sets the chosen Scene multiplexer as the destination for all input events. Note also “entry” and “exit” scene methods. These get called when a scene is activated and removed respectively.

public class Scene extends Stage implements Node
{
	private static final int DEFAULT_LAYER_CAPACITY = 10;

	/**
	 * Associated input multiplexer.
	 */
	private InputMultiplexer inputMultiplexer;

	/**
	 * Stage elements as nodes. We need this so we can call enter and exit on
	 * actors in order to manage registration and de-registration of event
	 * handlers.
	 */
	private Array nodes;

	public Scene()
	{
		super(Director.instance().getWidth(), Director.instance().getHeight(), Director.instance().isStretch());

		inputMultiplexer = new InputMultiplexer(this);

		nodes = new Array(DEFAULT_LAYER_CAPACITY);
	}

	/**
	 * Get input multiplexer.
	 *
	 * @return The input multiplexer.
	 */
	public InputMultiplexer getInputMultiplexer()
	{
		return inputMultiplexer;
	}

	/**
	 * Add scene layer ensuring it adopts the same size as the owning scene.
	 *
	 * Note layer in nodes list.
	 *
	 * @param group
	 */
	public void addLayer(Layer layer)
	{
		layer.width = this.width;
		layer.height = this.height;

		nodes.add(layer);

		super.addActor(layer);
	}

	/**
	 * Handle pre-display tasks.
	 *
	 */
	@Override
	public void enter()
	{
		int size = nodes.size;
		for (int i = 0; i < size; i++)
		{
			nodes.get(i).enter();
		}
	}

	/**
	 * Handle post-display tasks.
	 *
	 */
	@Override
	public void exit()
	{
		int size = nodes.size;
		for (int i = 0; i < size; i++)
		{
			nodes.get(i).exit();
		}
	}

}

The Director maintains a note of the chosen size. It handles setting the current scene, running the render “tick”, updating the event mechanism and updating current actions associated with the active scene. It also handles recalculating the scaling offsets for touch/mouse events if you stretch the size of the screen.

public class Director
{
	private static final boolean DEFAULT_STRETCH = true;

	private static Director instance = null;

	private ActorEventSource eventSource;

	private int width;
	private int height;
	private boolean stretch;

	private Scene scene;

	private float scaleFactorX;
	private float scaleFactorY;

	/**
	 * Access singleton instance
	 *
	 * @return instance of class
	 */
	public synchronized static Director instance()
	{
		if (instance == null)
		{
			instance = new Director();
		}

		return instance;
	}

	/**
	 * Create reference to command pipeline.
	 *
	 */
	public Director()
	{
		scene = null;

		stretch = DEFAULT_STRETCH;

		// Latch onto event source.
		eventSource = ActorEventSource.instance();

		// These are scale factors for adjusting touch events to the actual size
		// of the view-port.
		scaleFactorX = 1;
		scaleFactorY = 1;
	}

	/**
	 * Update main loop.
	 *
	 */
	public void update()
	{
		// Update events.
		eventSource.update();

		// Update View
		Gdx.gl.glClearColor(0, 0, 0, 1);
		Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT);

		if (scene != null)
		{
			scene.act(Gdx.graphics.getDeltaTime());

			scene.draw();
		}
		else
		{
			Gdx.app.log("WTF!", "No scene");
		}
	}

	/**
	 * Set the current scene.
	 *
	 * @param scene
	 */
	public synchronized void setScene(Scene scene)
	{
		// If already active scene...
		if (this.scene != null)
		{
			// Exit stage left..
			this.scene.exit();
		}

		this.scene = scene;

		if (this.scene != null)
		{
			// Enter stage right..
			this.scene.enter();

			// NOTE: Route input events to the scene.
			Gdx.input.setInputProcessor(scene.getInputMultiplexer());
		}

	}

	/**
	 * Adjust the scale factors for touch/mouse events to match the size of the
	 * stage.
	 *
	 * @param width
	 *            The new width.
	 * @param height
	 *            The new height.
	 */
	public void recalcScaleFactors(int width, int height)
	{
		scaleFactorX = (float) this.width / width;
		scaleFactorY = (float) this.height / height;
	}
}

A Layer is a holder which implements InputProcessor and the default “enter” and “exit” handlers.

A scene can hold multiple layers which may or may not receive input. Here is the main GameScene.

public class GameScene extends Scene
{
	private Layer gameLayer;
	private Layer shipLayer;
	private Layer pulseLayer;
	private Layer asteroidLayer;
	private Layer explosionLayer;
	private Layer statsLayer;

	/**
	 * Main game scene.
	 *
	 */
	public GameScene()
	{
		// ---------------------------------------------------------------
		// Control layer
		// ---------------------------------------------------------------
		gameLayer = new GameLayer(this.width, this.height);

		getInputMultiplexer().addProcessor(gameLayer);

		addLayer(gameLayer);

		// ---------------------------------------------------------------
		// Pulse layer.
		// ---------------------------------------------------------------
		pulseLayer = new PulseLayer(this.width, this.height);

		addLayer(pulseLayer);

		// ---------------------------------------------------------------
		// Asteroid Layer
		// ---------------------------------------------------------------
		asteroidLayer = new AsteroidLayer(this.width, this.height);

		addLayer(asteroidLayer);

		explosionLayer = new ExplosionLayer(this.width, this.height);

		addLayer(explosionLayer);

		// ---------------------------------------------------------------
		// Ship layer
		// ---------------------------------------------------------------
		shipLayer = new ShipLayer(this.width, this.height);

		getInputMultiplexer().addProcessor(shipLayer);

		addLayer(shipLayer);

		// ---------------------------------------------------------------
		// Statistics layer
		// ---------------------------------------------------------------
		statsLayer = new StatsLayer(this.width, this.height);

		addLayer(statsLayer);
	}

	public Layer getShipLayer()
	{
		return shipLayer;
	}

	public Group getPulseLayer()
	{
		return pulseLayer;
	}

	public Group getAsteroidLayer()
	{
		return asteroidLayer;
	}

}

Implemented layers register themselves with the event mechanism when visible and de-register when they are no longer within an active scene. This is to avoid routing events to elements which do not need them and also means you can (technically) generate new instances without having to get weird behaviour where events are getting sucked up elsewhere. NOTE: I learnt the hard way to keep this stuff as simple as possible from my previous attempt at this demo. I was routing everything through source and observers including input events and it was a nightmare to debug.

Events

Lets look into the event handling more closely.

The  AsteroidLayer has a delayed callback which when triggered launches an Asteroid from the top of the screen by generating a random position and running the associated actions for the sprite.
/**
 * Launch a sprite from pool (if one available).
 *
 */
private void handleStartAsteroid()
{
	// Get free sprite from pool.
	AsteroidSprite sprite = pool.obtain();

	// Set running.
	sprite.run();

	// Add to view.
	addActor(sprite);
}

Once the asteroid is “running” it too has a periodic call back which checks to see if it has collided with anything and if so send an event to indicate which kind of collision.

Listening for collision events are the layers:

  • PulseLayer which will remove the Pulse which ‘hit’ the Asteroid from the view.
  • AsteroidLayer which will remove the Asteroid Sprite and replace it with a one-shot “explosion” animation. Also it will update the global score value which the StatsLayer will pick up and display.
  • ShipLayer which would normally do something like remove the ship and run an explosion but here just spins the ship around because I am shit at creating explosion graphics.

Lets take a look at an event handler for the AsteroidLayer:

/**
 * Handle events.
 *
 */
@Override
public boolean handleEvent(ActorEvent event)
{
	boolean handled = false;

	switch (event.getId())
	{
		case GameActorEvents.EVENT_START_ASTEROID:
			handleStartAsteroid();
			handled = true;
			break;
		case GameActorEvents.EVENT_COLLISION_ASTEROID_PULSE:
			handlePulseCollision(event.getActor());
			handled = true;
			break;
		case GameActorEvents.EVENT_END_ASTEROID:
			handleEndAsteroid(event.getActor());
			handled = true;
			break;
		default:
			break;
	}

	return handled;
}

/**
 * Launch a sprite from pool (if one available).
 *
 */
private void handleStartAsteroid()
{
	// Get free sprite from pool.
	AsteroidSprite sprite = pool.obtain();

	// Set running.
	sprite.run();

	// Add to view.
	addActor(sprite);
}

/**
 * Handle pulse hitting asteroid.
 *
 * @param actor
 */
private void handlePulseCollision(Actor actor)
{
	// Run explosion sprite
	this.director.sendEvent(GameActorEvents.EVENT_START_ASTEROID_EXPLOSION, actor);

	handleEndAsteroid(actor);

	// Update score.
	GameStats.instance().incScore();
}

/**
 * Handle controller events.
 *
 * @param event
 *            The actor event.
 *
 * @return True if handled.
 */
private void handleEndAsteroid(Actor source)
{
	// Free this from pool so it can be re-used.
	pool.free((AsteroidSprite) source);

	// Remove from view.
	removeActor(source);
}

You can see that as events are routed to the layer it responds accordingly. If the handler returns true the event will be removed from the event list and will not be passed on to any any other handlers.

Actions

Actions are used to run the sprite movements. As an example lets examine the PulseSprite, which is a simple animation, it has to move from the ship position to the top of the screen.


/**
 * Run actions for actor.
 *
 * @param x
 * @param y
 *
 * @return The main actions object.
 */
public void run(float x, float y)
{
	// ---------------------------------------------------------------
	// BECAUSE THE 'ACTION' METHOD DOES NOT CLEAR THE EXISTING LIST IT ADDS
	// TO IT YOU MUST CLEAR ACTIONS ASSOCIATED WITH ACTOR. THIS IS
	// BECAUSE WE ARE RECYCLING SPRITES.
	// ---------------------------------------------------------------
	clearActions();

	// Set initial position
	this.x = x;
	this.y = y;

	// Calculate the duration to cover distance at pixels-per-sec.
	float height = Director.instance().getHeight();
	float distance = height - y;
	float duration = PIXELS_PER_SEC_FACTOR * distance;

	// Move from source to top of screen.
	MoveTo moveTo = MoveTo.$(x, height, duration);
	moveTo.setCompletionListener(this);

	// Run
	action(moveTo);
}

/**
 * Handles pulse action complete.
 *
 */
@Override
public void completed(Action action)
{
        // Send notification that pulse has completed.
	Director.instance().sendEvent(GameActorEvents.EVENT_END_PULSE, this);
}

Note, we assign a completion handler to the move actions. If the pulse reaches the top of the screen without hitting anything then the completion handler will get triggered and it will send a event from the sprite to the PulseLayer which will remove it from the view, killing any further action execution as of course actions are associated with their Actor.

Because the PulseSprite is pooled we have to clear the associated action list when it is reused to clear out any unfinished or complete actions.

The demo code is here. This uses 0.9.3 snapshot from the Google Code subversion repository.

I am currently rewriting this again to bring in the Universal Tween Engine. That will be the next post.

Important

Only the “Menu”, “About” and “Game” view are implemented. To navigate out of a view PRESS THE ESC KEY. In Android you can press the back key.

Update #1

This project has been moved to gitHub. There have been a lot of improvements to the codebase including mavenizing it and separating out my netthreads-libgdx extensions library which grew out of this and subsequent demos.