Space Invaders - 2D Rendering in Java

This tutorial can be discussed here

Disclaimer: This tutorial is provided as is. I don't guarantee that the provided source is perfect or that that it provides best practices.

Space Invaders 101 - An Accelerated Java 2D Tutorial

Introduction


This tutorial hopes to give the reader a simple introduction to the world of 2D games using Java. We're going to cover the following areas at a fairly simplistic level:



• Accelerated Mode Graphics
• Simple game loops
• Keyboard Input
• Brute force collision detection


The final game can be see here. The complete source for the tutorial can be found here. Its intended that you read through this tutorial with the source code at your side. The tutorial isn't going to cover every line of code but should give you enough to fully understand how it works.

Context highlighted source is also available here:
Game.java
SpriteStore.java
Sprite.java
Entity.java
ShipEntity.java
ShotEntity.java
AlienEntity.java

Disclaimer: This tutorial is provided as is. I don't guarantee that the provided source is perfect or that that it provides best practices.

Design


Before starting any game its always a good idea to work out what's going to be in the game and how you're going to build your classes around that. You don't need to read this section unless you're interested in why the source is written the way it is.

For our space invaders game we're going to have a main window. The window needs to use acceleated graphics. It also needs to respond to the player's key presses to move our player's ship around. For now we can call this class Game since it represents our main game.

In that window we want to see some things moving around. The player's ship, the aliens and the shots that the players fire. Since all of these things have common properites (i.e. they display a graphic and move around the screen) we can infer a common class to represent each one with potentially subclasses to define the specific behaviours of these different types. Since "thing" is such a terrible name for a class, for our design I'm going to call them Entities. From this we get 4 classes. Entity with 3 subclasses, ShipEntity, AlienEntity and ShotEntity

Finally for each Entity we have we'd like to have an image displayed, using an old term, a Sprite. However, we might use the same Sprite for multiple entities, for instance the aliens. It seems logically therefore to keep the sprite as a seperate object from the entity. In addition we don't want to waste graphics memory so we'd like to only load each sprite once. To manage this it'd be nice to add a class to manage loading of the Sprites and storing them for future use. So we add a pair of classes to our design, Sprite and SpriteStore.

The Basic Window

Our basic window is going to be created and maintained by a central class, Game. The following sections cover the initial sections of code in the main class.

Game Entry Point

In java our entry point is "public static void main(String arg[])". This is where the application starts when its run. From here we're going to create an instance of our main class which will start everything else running. Game will be a subclass of Canvas, since it will be the main element displaying the graphics. Note, that it needs to be a subclass of Canvas since its one of the only components that supports using accelerated graphics.

public static void main(String argv[]) {
	Game g = new Game();
        g.gameLoop();
}

Creating the window

First we need to create our window and configure its contents. We're going to fix our resolution to 800x600. However, since the window may have decoration the content must be set to 800x600 and we must rely on pack() (shown a little later) to actually size the window appropriately.

// create a frame to contain our game

JFrame container = new JFrame("Space Invaders 101");
		
// get hold the content of the frame and set up the 
// resolution of the game
JPanel panel = (JPanel) container.getContentPane();
panel.setPreferredSize(new Dimension(800,600));
panel.setLayout(null);
		
// setup our canvas size and put it into the content of the frame
setBounds(0,0,800,600);
panel.add(this);

Since the canvas we're working with is going to be actively redrawn (i.e. accelerated graphics) we need to prevent Java AWT attempting to redraw our
surface. Finally, we get the window to resolve its size, prevent the
user resizing it and make it visible.

// Tell AWT not to bother repainting our canvas since we're
// going to do that our self in accelerated mode
setIgnoreRepaint(true);
		
// finally make the window visible 
container.pack();
container.setResizable(false);
container.setVisible(true);

Accelerated Graphics

To manage our accelerated graphics canvas we're going to rely on a class provided from the JDK. The BufferStrategy is named that because its a strategy for managing buffers, or rather the swapping of buffers. This supports us using page flipping and accelerated graphics.

Creating a BufferStrategy couldn't be simpler. We simply ask the Canvas to do it for us. The only thing that needs to be specified is how many buffers to use to manage the screen, in this case we're going to use just 2.

// create the buffering strategy which will allow AWT
// to manage our accelerated graphics
createBufferStrategy(2);
strategy = getBufferStrategy();

The Game Loop

The game loop is a remarkably important part of any game. Client side games tend to be single threaded. This helps prevent a whole bunch of complexities synchronising game updates and game drawing. Generally this results in more stable and maintainble code. There are good arguments to use threading, however for the purposes of this tutorial we're not going to consider it.

The normal game loop runs something like this:



• Work out how long its been since we last looped
  
• Process any input from the user/player
  
• Move everything based on the time since last loop
  
• Draw everything on screen
  
• Swap the buffers over to make the new image visible
  
• Wait for a set period
  

At this stage we're just interested in getting the screen swap and timing done, so we add a function called gameLoop that does this:

while (gameRunning) {
	// work out how long its been since the last update, this
	// will be used to calculate how far the entities should
	// move this loop
	long delta = System.currentTimeMillis() - lastLoopTime;
	lastLoopTime = System.currentTimeMillis();
			
	// Get hold of a graphics context for the accelerated 
	// surface and blank it out
	Graphics2D g = (Graphics2D) strategy.getDrawGraphics();
	g.setColor(Color.black);
	g.fillRect(0,0,800,600);

	// finally, we've completed drawing so clear up the graphics
	// and flip the buffer over
	g.dispose();
	strategy.show();

	// finally pause for a bit. Note: this should run us at about
	// 100 fps but on windows this might vary each loop due to
	// a bad implementation of timer
	try { Thread.sleep(10); } catch (Exception e) {}
}

Finally we call gameLoop from the bottom of the constructor of Game. This just starts the game loop running around. If you've been following this code you should be able to run what you currently have and a window should be displayed with an accelerated canvas that shows a black screen.

Sprites and Resource Management

The Sprite class


The sprite class will act as a wrapper round the standard java.awt.Image. However, its going to give us a place holder to expand things later on.

So heres the sprite class. Essentially it just takes and holds an image which can be drawn at a specified location onto a graphics context.

public class Sprite {
	/** The image to be drawn for this sprite */
	private Image image;
	
	/**
	 * Create a new sprite based on an image
	 * 
	 * @param image The image that is this sprite
	 */
	public Sprite(Image image) {
		this.image = image;
	}
	
	/**
	 * Get the width of the drawn sprite
	 * 
	 * @return The width in pixels of this sprite
	 */
	public int getWidth() {
		return image.getWidth(null);
	}

	/**
	 * Get the height of the drawn sprite
	 * 
	 * @return The height in pixels of this sprite
	 */
	public int getHeight() {
		return image.getHeight(null);
	}
	
	/**
	 * Draw the sprite onto the graphics context provided
	 * 
	 * @param g The graphics context on which to draw the sprite
	 * @param x The x location at which to draw the sprite
	 * @param y The y location at which to draw the sprite
	 */
	public void draw(Graphics g,int x,int y) {
		g.drawImage(image,x,y,null);
	}
}

Sprite Loading and Management


An important part of any game is managing the resources that are used. In our case we're just looking at sprites. However, we do only want to load any single sprite once. It would also be handy if the collection of sprites existing in one central location. With this in mind we'll implement a SpriteStore object. This will be responsible for loading and caching sprites. To make it easy to get hold of the sprite store we'll implement it as a singleton.


Implementing the singleton


A singleton simply means thats theres a single instance of the object available statically. In many cases this is done simply for convienience, however sometimes there are good design reasons for enforcing that there is only a single instance of the class ever created.

Implementing this in our sprite store looks like this:

/** The single instance of this class */
private static SpriteStore single = new SpriteStore();
	
/**
 * Get the single instance of this class 
 * 
 * @return The single instance of this class
 */
public static SpriteStore get() {
	return single;
}

The "single" is the single instance of the class ever created. The static get method gives us access to the single instance.

Loading the Sprites


The first step is to retrieve the sprite image from disk. Generally in Java it makes sense to use the ClassLoader to find the image for you. This makes it much easier to deploy games with the resources packaged up. However, some people are more comfortable to use direct file access which is also perfectly viable. For this tutorial we'll stick to the ClassLoader since it makes webstart possible.

The first step is locate the sprite:

URL url = this.getClass().getClassLoader().getResource(ref);

Its important to note that the chain of functions used to get to the class is only there to support specialised class loaders (like the one found in WebStart). The retrieved URL will point to the image specified in the string "ref" relative to the classpath.

The next step is to actually load in the image. In Java this is a simple matter of using the utlity class ImageIO. To load our image we use this code:

sourceImage = ImageIO.read(url);

Finally, we need to allocate some accelerated graphics memory to store our image in. This will allow the image to be drawn without the CPU getting involved, we just want the graphics card to do the work for us.

Allocating the graphics memory is achieved like so:

// create an accelerated image of the right size to store our sprite in
GraphicsConfiguration gc = GraphicsEnvironment.getLocalGraphicsEnvironment().
                             getDefaultScreenDevice().getDefaultConfiguration();
Image image = gc.createCompatibleImage(sourceImage.getWidth(),
                                       sourceImage.getHeight(),
                                       Transparency.BITMASK);

The final step is to draw our loaded image into our accelerated graphics image. This essentially creates our sprite:

// draw our source image into the accelerated image
image.getGraphics().drawImage(sourceImage,0,0,null);

The only thing we have left to do is create our actual Sprite object.

Caching the Sprites


The other responsibility of our SpriteStore is to cahce the images that have been loaded. To achieve this we add a HashMap. This map will link the string references to images to the sprites that our loaded. Whenever we load a sprite we add it to the map like this:

// create a sprite, add it the cache then return it
Sprite sprite = new Sprite(image);
sprites.put(ref,sprite);

Likewise, whenever a sprite is requested we check whether its already in the map. If it is, we return our cached copy instead of loading a new copy:

// if we've already got the sprite in the cache
// then just return the existing version
if (sprites.get(ref) != null) {
	return (Sprite) sprites.get(ref);
}

Movement


Lets get things moving! Movement in our case is going to be handled by our Entity class. Each loop we'll ask the entities in the game to move themself. To facilitate this we add a list of entities to the main game class. Each loop we'll cycle round this list asking each entity to move and then draw itself. In our game loop, that looks like this:

// cycle round asking each entity to move itself
for (int i=0;i<entities.size();i++) {
	Entity entity = (Entity) entities.get(i);
					
	entity.move(delta);
}
			
// cycle round drawing all the entities we have in the game
for (int i=0;i<entities.size();i++) {
	Entity entity = (Entity) entities.get(i);
	
	entity.draw(g);
}

Rememebr we calculated how long it'd been since we looped round. This can be used to work out how far an entity should move on the current loop. Right, now we know what Entity needs to be able to do, on to the implementation.

The Entity class


The entity class will contain its currently location, its current movement and its visual representation. When an Entity is constructed these values will be defined. This includes retrieving the sprite from the store that should represent this entity. The location and movement associated with the entity will be definable and retriveable via get and set methods.

Once these properties are defined we can cover the two methods that we require of Entity. The move() method looks like this:

public void move(long delta) {
	// update the location of the entity based on move speeds
	x += (delta * dx) / 1000;
	y += (delta * dy) / 1000;
}

Simple! We take how every much time has passed, multiply it by the movement in each direction and add this on to the location. The division by 1000 is to adjust for the fact that the movement value is specified in pixels per second, but the time is specified in milliseconds. Each loop all the entities will be moved in accordance with their currently movement values (velocities).

Next we need to be able to draw an Entity onto our accelerated graphics context. draw() is implemented like this:

public void draw(Graphics g) {
	sprite.draw(g,(int) x,(int) y);
}

Essentially, this just draws the sprite onto the supplied graphics context at its current location. So each loop, the entity moves and is then redrawn at the right location.

Now we've defined our basic entity we should create a few subclasses as placeholders for some more functionality we'll add later on. We simply need to create the 3 subclasses of Entity; ShipEntity, ShotEntity and AlienEntity. For now we won't bother adding anything extra but it normally pays to be aware and add these things up front.

The final step is to create our entities and add them to the game world. If we add a utility method to central Game class called initEntities(). This will initialise a set of entities at the game start. The current implementation looks like this:

private void initEntities() {
	// create the player ship and place it roughly in the center of the screen
	ship = new ShipEntity(this,"sprites/ship.gif",370,550);
	entities.add(ship);
		
	// create a block of aliens (5 rows, by 12 aliens, spaced evenly)
	alienCount = 0;
	for (int row=0;row<5;row++) {
		for (int x=0;x<12;x++) {
			Entity alien = new AlienEntity(this,
                                             "sprites/alien.gif",
                                             100+(x*50),
                                             (50)+row*30);
			entities.add(alien);
			alienCount++;
		}
	}
}

As you can see, the initialisation takes two steps. The first is to create the player's ship. We simply create a ShipEntity with the appropriate graphic and center it at the bottom of our canvas.

The second step is to create all the aliens. We loop through creating a block of aliens. Again each alien is just the creation of the AlienEntity positioned at the right location. In addition we count how many aliens we've created so we can track whether the player has won the game.

Assuming the code to support moving and displaying the entities has been added to main game loop, running the game should now show the player's ship and a bunch of aliens.

Now each type of Entity moves in its own way and with its own contraints. Lets look at each one.

Ship Entity


Since the ship will be controlled by the player (see a little lower down) we have very little to do here. However, we do want to prevent the ship moving off the sides of the screen so we add this bit of code to the move() method in ShipEntity:

public void move(long delta) {
	// if we're moving left and have reached the left hand side
	// of the screen, don't move
	if ((dx < 0) && (x < 10)) {
		return;
	}
	// if we're moving right and have reached the right hand side
	// of the screen, don't move
	if ((dx > 0) && (x > 750)) {
		return;
	}
	
	super.move(delta);
}

What we essentially are saying here is that if we're moving left and we're about to move off the left hand side of the screen then don't allow the movement (i.e. return). In reverse if we're moving to the right and are about to move off the right hand side of the screen then don't allow the movement. Otherwise we just do the normal Entity movement routine.

Shot Entity

The shot entity is pretty simple, it just wants to run up the screen until it either hits an alien (see Collision later on) or runs off the top of the screen, at which point we'd like to remove it from the entity list (for details of the remove entity method check out the source).

To start the shot moving with initialise the vertical movement to a negative number based on the speed we'd like the shot to move. The movement method itself looks like this:

public void move(long delta) {
	// proceed with normal move
	super.move(delta);
		
	// if we shot off the screen, remove ourselfs
	if (y < -100) {
		game.removeEntity(this);
	}
}

Simply put, if the shot moves off the top of the screen, remove it.

Alien Entity

Aliens are the most tricky part of our space invaders game. As they move around we need to notice when they hit the side of the screen and start them moving in the opposite direction. In conjuction each time they change direction we'd like them all to move down a step. Part of this will be covered in the movement routine and part in the game logic. Game logic is used in this case since we need to first detect that the aliens should change direction then change them all (rather than a localised change like the other entities)

Hopefully, we now know what we want to do, so how? First we initialise the movement of the aliens to start them moving to the left based on the predefined speed. Next we put the detection of an alien hitting the side in the movement routine like this:

public void move(long delta) {
	// if we have reached the left hand side of the screen and
	// are moving left then request a logic update 
	if ((dx < 0) && (x < 10)) {
		game.updateLogic();
	}
	// and vice vesa, if we have reached the right hand side of 
	// the screen and are moving right, request a logic update
	if ((dx > 0) && (x > 750)) {
		game.updateLogic();

	}
	
	// proceed with normal move
	super.move(delta);
}

In the same way as in ShipEntity, we check whether the entity has hit the edge of the screen. However, in this case we notify the game that the game logic for all entities need to be run. We'll make this logic adapt the movement of the aliens but more on this later.

Keyboard Input


Our next step is to make the ship controllable. To do this we need to add a simple inner class to our main game. It looks like this:

private class KeyInputHandler extends KeyAdapter {
		
	public void keyPressed(KeyEvent e) {
		if (e.getKeyCode() == KeyEvent.VK_LEFT) {
			leftPressed = true;
		}
		if (e.getKeyCode() == KeyEvent.VK_RIGHT) {
			rightPressed = true;
		}
		if (e.getKeyCode() == KeyEvent.VK_SPACE) {
			firePressed = true;
		}
	} 
		
		
	public void keyReleased(KeyEvent e) {			
		if (e.getKeyCode() == KeyEvent.VK_LEFT) {
			leftPressed = false;
		}
		if (e.getKeyCode() == KeyEvent.VK_RIGHT) {
			rightPressed = false;
		}
		if (e.getKeyCode() == KeyEvent.VK_SPACE) {
			firePressed = false;
		}
	}

	public void keyTyped(KeyEvent e) {
		// if we hit escape, then quit the game
		if (e.getKeyChar() == 27) {
			System.exit(0);
		}
	}
}

This class simply picks up keys being pressed and released and records their states in a set of boolean variables in the main class. In addition it checks for escape being pressed (which in our case exits the game)

To make this class work we need to add it to our canvas as a "KeyListener". This is done by adding the following line to the constructor of our Game class:

addKeyListener(new KeyInputHandler());

With this source code in place the boolean flags will be set to appropriate values as the keys are pressed. The next step is to respond to these boolean flags being set in the game loop. If we add this in the game loop we can add keyboard control to the ship:

// resolve the movement of the ship. First assume the ship 
// isn't moving. If either cursor key is pressed then
// update the movement appropraitely
ship.setHorizontalMovement(0);
			
if ((leftPressed) && (!rightPressed)) {
	ship.setHorizontalMovement(-moveSpeed);
} else if ((rightPressed) && (!leftPressed)) {
	ship.setHorizontalMovement(moveSpeed);
}

As you can see we check if left or right is pressed. If they are we update the movement values associated with the player's ship. Hence when we hit the entity movement code the ship will move left or right.

If the player holds the fire key we'd like the ship to fire a shot up towards the aliens. However, we don't want to let the player just keep firing. It'd be good to limit how often they can fire. We'll put this functionality in a utility method called (somewhat logically) "tryToFire()"

// if we're pressing fire, attempt to fire
if (firePressed) {
	tryToFire();
}

To prevent the player firing too often we'll record the time whenever they take a shot and prevent them taking a shot if the last shot was less than a set interval ago. Hmm, sounds complicated, its not! really! Here it is:

public void tryToFire() {
	// check that we have waiting long enough to fire
	if (System.currentTimeMillis() - lastFire < firingInterval) {
		return;
	}
	
	// if we waited long enough, create the shot entity, and record the time.
	lastFire = System.currentTimeMillis();
	ShotEntity shot = new ShotEntity(this,"sprites/shot.gif",ship.getX()+10,ship.getY()-30);
	entities.add(shot);
}

First we check if the last time the player took a shot was long enough ago. If it wasn't we don't bother firing and just return. If it was we record the current time. Next we create and add an entity to represent the shot fired by the player. Since our shot is setup to move up the screen it shoots off from the player towards the aliens.

Collision Detection


Lets start by saying there are better ways to implement collision detection than the method outlined here. It could be described a "brute force". In our main game loop we're going to cycle round check whether each entity has collided with every other entity.

First, we'll need to implement a check to resolve whether two entities have in fact collided. We'll do this in the Entity class like this:

public boolean collidesWith(Entity other) {
	me.setBounds((int) x,(int) y,sprite.getWidth(),sprite.getHeight());
	him.setBounds((int) other.x,(int) other.y,other.sprite.getWidth(),other.sprite.getHeight());

	return me.intersects(him);
}

This method checks if the entity itself collides with the other entity specified. We're going to rely on rectangular intersection regions and the AWT class Rectangle. In this case the variables "me" and "him" are instances of Rectangle that are held at the class level.

First we configure the two rectangles to represent the two entities. Next we use the inbuilt functionality of java.awt.Rectangle to check if the two entities intersect with each other. This isn't the smartest way to do this by any means, but for our purposes it will be good enough.

The next thing we'll add is a way to notify entities that they have collided with another. To do this we'll add a method like this to the Entity class:

public abstract void collidedWith(Entity other);

Its been made abstract since different implementations of the Entity class will want to respond to collisions in their own ways, e.g. Alien<->Shot, Ship<->Alien.

ShipEntity


The ship entity needs to react when it hits an entity, i.e. The player should be killed. To facilitate this we'll should do this:

public void collidedWith(Entity other) {
	// if its an alien, notify the game that the player
	// is dead
	if (other instanceof AlienEntity) {
		game.notifyDeath();
	}
}

Again, the result of the collision is based on the game logic (covered later). If the entity that the ship collided with is an Alien then notify the game that player should die.

ShotEntity


When the shot entity hits an alien we want the alien and the shot to be destroyed. This is achieved with the following code:

public void collidedWith(Entity other) {
	// if we've hit an alien, kill it!
	if (other instanceof AlienEntity) {
		// remove the affected entities
		game.removeEntity(this);
		game.removeEntity(other);
		
		// notify the game that the alien has been killed
		game.notifyAlienKilled();
	}
}

If the shot hit and alien then the alien and shot are removed. In addition the game logic is notified that the an alien has been killed (covered later).

Game Loop Additions


The final step in getting the collision detection to work is to add a section to the game loop to cycle through all the entities checking whether they collide with each other. Here's the code:

// brute force collisions, compare every entity against
// every other entity. If any of them collide notify 
// both entities that the collision has occured
for (int p=0;p<entities.size();p++) {
	for (int s=p+1;s<entities.size();s++) {
		Entity me = (Entity) entities.get(p);
		Entity him = (Entity) entities.get(s);
			
		if (me.collidesWith(him)) {
			me.collidedWith(him);
			him.collidedWith(me);
		}
	}
}

For each entity we cycle through all the other entities that we haven't compared against and check whether a collision has occured. If a collision has occured we notify both sides.

A smarter way to do this might be to check for the collisions only every so often. It might also be nice to have a flag on an entity whether it should detect collisions.

Game Logic


The final step of our game is to fill the game logic parts. We're implied the existence of a set of methods on the Game class already. Time to work out what they need to do.


notifyDeath()


This method is called to indicate that the player has been killed. This can happen if an alien hits the player or an alien goes off the bottom of the screen.


notifyWin()


This method id called to indicate that the player has won the game. In the current game this is a result of killing all the aliens.


notifyAlienKilled()


Calling this method indicates that an alien has been killed as a result of a collision registered by the ShotEntity. Once all the aliens have been killed the player has won. The code looks like this:

public void notifyAlienKilled() {
	// reduce the alient count, if there are none left, the player has won!
	alienCount--;
		
	if (alienCount == 0) {
		notifyWin();
	}
		
	// if there are still some aliens left then they all need to get faster, so
	// speed up all the existing aliens
	for (int i=0;i<entities.size();i++) {
		Entity entity = (Entity) entities.get(i);
		
		if (entity instanceof AlienEntity) {
			// speed up by 2%
			entity.setHorizontalMovement(entity.getHorizontalMovement() * 1.02);
		}
	}
}

In addition to recording if all the aliens have been killed we also speed the aliens up a bit. Every time an alien is killed the rest speed up by 2%.

The last step we need is to support entity based game logic. We implied the requirement when building the AlienEntity. When a single alien detects the edge of the screen we want all the aliens to change direction. To support this we're going to add two sections of code.

Entity Logic

Each entity should be allowed to support its own logic. To facilitate this we going to add a method to the Entity class. doLogic() will allow subclasses of Entity to define a bit of logic that will be run whenever game logic is requested (see below). In AlienEntity for instance we request that game logic be run when the edge of the screen is detected. The doLogic() implementation in AlienEntity looks like this:

public void doLogic() {
	// swap over horizontal movement and move down the
	// screen a bit
	dx = -dx;
	y += 10;
	
	// if we've reached the bottom of the screen then the player
	// dies

	if (y > 570) {
		game.notifyDeath();
	}
}

So, when an alien detects the edge of the screen it signals that game logic should be run on entities. The alien entities will change direction (dx = -dx) and move down the screen a bit (y += 10). Finally, if the alien has moved off the bottom of the screen then notify the game that the player is dead.

Entity Logic Infrastructure

To complete the game logic at the entity level we need to add a method on the Game class that will indicate that the entity game logic should be run. First, we add this method on Game:

public void updateLogic() {
	logicRequiredThisLoop = true;
}

This flag indicates that in the game loop we should run the logic associated with every entity currently in the game. To achieve this we add this in the game loop:

// if a game event has indicated that game logic should
// be resolved, cycle round every entity requesting that
// their personal logic should be considered.
if (logicRequiredThisLoop) {
	for (int i=0;i<entities.size();i++) {
		Entity entity = (Entity) entities.get(i);
		entity.doLogic();
	}
	
	logicRequiredThisLoop = false;
}

If the flag is set, then cycle round the entities calling the doLogic() method on each. Finally, reset the flag so the logic doesn't automatically get run next loop.

Finishing Off

Hopefully this tutorial has been of some help. If you look through the provided source code you'll find a selection of additions which complete the game more fully. These arn't covered in the tutorial because of their intricacy. However, the comments in the code should make the extra bits and pieces easy to understand.

If you have any comments or corrects feel free to mail me here

Exercises for the Reader

The following extensions of the game may help in understanding how game hangs together.

Frame Rate Counter

Add a frame rate counter to the screen while the game is playing. This could be done by counting game loops and recording the number counted each second. This value could then be displayed as part of the drawing section of the game loop.

Animated Aliens

Animating the aliens would require updating the Entity class to support multiple sprites. Then depending on the time passed the sprite being drawn for the entity could be swapped.

Alien Return Fire

With the addition of the a new Entity the aliens could be made to fire back. This could either be done by timing it so each alien fires back every so many seconds. Alternatively, this could be based on a random occurance, say the alien has a 1 in a 100 chance of fireing back at any given moement.

Pause Button

Make it possible to pause the game by pressing a key (P?). This should pause all game updates but still continue to render the screen and the entities within the game. It might be nice to add a message indicating the game is paused.

Further Reading


I'd recommend you take a look at the following material, it'll help support taking the current code to the next stage.


• A HowTo Guide for WebStart
  
• The SUN fullscreen tutorial trail
  
• The GAGE Library (Most importantly the high resolution timer)
  

Possible Future Tutorials


Let me know if you'd like to see any of the following tutorials in the future.



• Space Invaders in OpenGL
  
• Multiplayer Space Invaders
  
• Using sprite based Fonts
  
• Music and Sound Effects
  
• Space Invaders with 3D Models (Xith3D)
  

Credits

Tutorial and Source written by Kevin Glass
Game sprites provided by Ari Feldman
A large number of people over at the Java Gaming Forums

Space Invaders 102 - Timing and Animation in Java

Introduction


This tutorial follows on from Space Invaders 101. The tutorial will cover high resolution timers and the issues that raises in Java. In addition to timing the tutorial will adapt the previously developed source to add some basic animation.

The result of this tutorial can be seen here. The complete source for the tutorial can be found here. Its intended that you read through this tutorial with the source code at your side. The tutorial isn't going to cover every line of code but should give you enough to fully understand how it works.

Context highlighted source is also available here:
Game.java
SpriteStore.java
Sprite.java
Entity.java
ShipEntity.java
ShotEntity.java
AlienEntity.java
SystemTimer.java


Disclaimer: This tutorial is provided as is. I don't guarantee that the provided source is perfect or that that it provides best practices.


Timing


What exactly do we mean by timing? Timing is used in many places in games. For many games timing is used to limit the rate at which the screen is updated, the frames per second. Most games use some sort of movement and animation which is normally based on timing.

Currently, Java has some issues with timing. In Java 1.4.2 the simplest way to get hold of the time is to use System.currentTimeMillis(). Infact it was used to time the movement in the first tutorial. However, on some Windows based machines the resolution of the timer (the smallest value you can time) isn't very useful. On most systems (Linux, SunOS, etc) the resolution is at least 1 millisecond. However, on some Windows sytems the resolution is bad enough to mean that timing can be relied on to give a consistant result, which in turn can lead to stuttering in
updates. Lets look at some possible solutions.

Averaging the Time

One way to deal with the inconsistency of timing on Windows is to average the change in time between frames. Historically this was a very common way to deal with the problem. Using this method the change in time between frames is recorded across the last 5 (or more) frames. Instead of using the actual change in time, the average of the last few frames is taken and used instead.

So the algorithm looks something like this:



• Each game loop record the render time between frames.
  
• Average the last 5 frame times
  
• Use the average to move and update game elements
  

While this doesn't give perfect results, it does give "good" results. Its not required on anything other than Windows. So if you do choose to implement this method its nice to add a check on the system property "os.name".

Wait for Java 1.5


The timing issue with Java has been well known for a while. Finally, in Java 1.5 its going to be fixed. However, Java 1.5 is currently in beta (in testing) and its not available for commerical use right now. Sun rarely give fixed dates for releases of Java so no one is quite sure when 1.5 will be available. Most Java releases have also taken a
while to really be ready for use. In addition, its fair to say that games players are only going to upgrade their Java when absolutely required, so most won't have 1.5 for quite a while. That being said, using 1.5 is by far the most simple way to get a high resolution timer.

Using the Java 1.5 timer couldn't be simpler:

long currentTime = System.nanoTime()

There you have it! As a side note, there is a high resolution timer "hidden" in Java 1.4.2, however this tutorial doesn't cover it. Why? There is no guarantee the hidden timer will be available in any given JVM and hence there is no point using it except in very specific circumstances.

EDIT: Obviously this tutorial was written before Java 1.5, 1.6 or any future release of Java. Java 1.5 did indeed bring System.nanoTime(), unfortunately as of now (1.6 being the current release) nanoTime() is still bugged and responds in strange ways on windows and any system with multiple processors. The advice given here to consider a native library still holds true - GAGETimer in particular will adapt based on the current version of Java.

Native Timing Library


Java's problem with timing on Window's isn't actually a result of the operating system not supporting high resolution timers. Windows itself does support high resolution timing, its just not possible to access it directly in Java (well not until 1.5). What we need to do is access the timer from the operating system at a native level.. but how!?

Why do we need native libraries?


Java can be viewed as 3 parts. First, the Java Language. The lanaguge is what makes most developers come to love Java, its pushes you towards writing structured and elegant code. Second, the JDK, the set of Java software libraries that make it easy to put applications together quickly in Java. Finally, we have the Java Virtual Machine (JVM), the interface from Java to the machine and the operating system its running on. The virtual machine, while being a key factor in allowing Java to be platform indepedant is also a key factor in limiting what is possible with Java. If something is possible in C++ it first has to be added to the JVM before its possible in pure Java.

Well, that sounds terrible doesn't it? We have to wait for Sun to update the JVM before we can access the latest and greatest platform dependant feature. Actually, no, this is exactly what the Java Native Interface (JNI) is designed to allow. The interface lets us use native libraries from Java to access features of the platform not yet exposed to the JVM. However, the downside is that unless you implement a native library for every platform your software now only works on a particular operating system. Its a trade off that should be taken pretty seriously when
you're looking at writing Java software.

Native Timing


Where high resolution timing is concerned we get very very lucky. The only platform that the JVM has an issue with getting good timing is Windows. So if we implement a native library to get us a high resolution timer on Windows we're clear for multi-platform development!

Whats even better, is that there are at least a few free implementations of this timing library already available, so we don't even need to touch the C++. A good implementation that a large number of people use is the GAGE Timer. Its freely available and has a good track record.

If you download the GAGE Timer package, you'll have a dynamic link library (DLL) for Windows and a Jar file containing the interface to the timer. To continue with this tutorial the DLL must be in the directory you are running from (only if you're on Windows of course), and the Jar file must be referenced in your classpath.

Wrapping up the Timing


As you can see timing can be implemented in a series of different ways in a set of difference circumstances. With this in mind lets wrap up our use of the timer in a single class. This way if we choose to try out a different timing method then we only have to make our changes in one place.

package org.newdawn.spaceinvaders;

import com.dnsalias.java.timer.AdvancedTimer;

/**
 * A wrapper class that provides timing methods. This class
 * provides us with a central location where we can add
 * our current timing implementation. Initially, we're going to
 * rely on the GAGE timer. (@see http://java.dnsalias.com)
 * 
 * @author Kevin Glass
 */
public class SystemTimer {
	/** Our link into the GAGE timer library */
	private static AdvancedTimer timer = new AdvancedTimer();
	/** The number of "timer ticks" per second */
	private static long timerTicksPerSecond;
	
	/** A little initialisation at startup, we're just going to get the GAGE timer going */
	static {
		timer.start();
		timerTicksPerSecond = AdvancedTimer.getTicksPerSecond();
	}
	
	/**
	 * Get the high resolution time in milliseconds
	 * 
	 * @return The high resolution time in milliseconds
	 */
	public static long getTime() {
		// we get the "timer ticks" from the high resolution timer
		// multiply by 1000 so our end result is in milliseconds
		// then divide by the number of ticks in a second giving
		// us a nice clear time in milliseconds
		return (timer.getClockTicks() * 1000) / timerTicksPerSecond;
	}
	
	/**
	 * Sleep for a fixed number of milliseconds. 
	 * 
	 * @param duration The amount of time in milliseconds to sleep for
	 */
	public static void sleep(long duration) {
		timer.sleep((duration * timerTicksPerSecond) / 1000);
	}
}

This timer class is based on the use of the GAGE timer. We need to support two main operations, getting the time and sleeping for a set period of time. The gage timer supports both of these operations, however it requires you specify the time in "timer ticks" not in milliseconds. The main job of this class is to map between the timer ticks provided
from the native timer to milliseconds and back.

Simply put, we create an "AdvancedTimer", the timer given to us by GAGE. We find out its resolution and start it off running. The final step is to provide our methods based on using the timer.

Updating the Game Loop


Next we need to modify our existing game loop to make use of the high resolution timer. First, lets change how we calculate our delta (change in time) value. Instead of calling System.currentTimeMillis() we'll use our new SystemTimer class. That'll look something like this:

// work out how long its been since the last update, this
// will be used to calculate how far the entities should
// move this loop
long delta = SystemTimer.getTime() - lastLoopTime;
lastLoopTime = SystemTimer.getTime();

Now, in the last tutorial since the timer wasn't designed to be perfect we didn't worry to much about a few lost milliseconds. This time we can rely on our timer to be millisecond accurate so we're going to try and strictly limit our frame time so we get exactly 100 frames per second (FPS).

To do this we're going to want each cycle round the game loop to take exactly 10 milliseconds. We know at what time the cycle started (lastLoopTime) and we know what time it is now, so with a small amount of maths we can sleep for the right amount of time like this:

// we want each frame to take 10 milliseconds, to do this
// we've recorded when we started the frame. We add 10 milliseconds
// to this and then factor in the current time to give 
// us our final value to wait for
SystemTimer.sleep(lastLoopTime+10-SystemTimer.getTime());

Note: GAGE Timer actually supports a "sleepUntil()" method that could be used here. However, since the SystemTimer is trying to allow us to change between timing mechanisms we should try to rely on simply sleeping for the right amount of time.

Animating them Aliens


One of the things directly dependant on accurate timing is any form of animation. Since we've now got acurate timing lets do some animation! The aliens coming down towards our player are little static for traditional space invaders. Lets make them dance around on the way down.

Since we designed our source nicely last time our changes are limited to one class, AlienEntity. Instead of the entity maintaining just a single sprite we'll add a few sprites and flip between them over time, i.e. Animation. Our first step is to add some addition variables to our AlienEntity:

/** The animation frames */
private Sprite[] frames = new Sprite[4];
/** The time since the last frame change took place */
private long lastFrameChange;
/** The frame duration in milliseconds, i.e. how long any given frame of animation lasts */
private long frameDuration = 250;
/** The current frame of animation being displayed */
private int frameNumber;

The frames array is going to hold our frames of animation. lastFrameChange is going to be a record of the last time we changed animation frame. frameDuration will be the length of time that each frame will be displayed on the screen. Making this small will make the aliens dance more quickly. Finally, frameNumber will be the index of the frame we are currently showing in a frames array. This will be incremented to cycle us through the animation.

Next we're going to need to load up our sprites. We're going to modify the constructor to grab the frames. However, our standard Entity class will already load one sprite for us (the one it used to display). So we need to load two additional ones, like so:

public AlienEntity(Game game,int x,int y) {
	super("sprites/alien.gif",x,y);
	
	// setup the animatin frames
	frames[0] = sprite;
	frames[1] = SpriteStore.get().getSprite("sprites/alien2.gif");
	frames[2] = sprite;
	frames[3] = SpriteStore.get().getSprite("sprites/alien3.gif");
	
	this.game = game;
	dx = -moveSpeed;
}

We've asked the Entity class to load "sprites/alien.gif" for us. Then we need to go off and load up a couple of additional sprites. We put the frame loaded by Entity and our two additional frames in the array in the right place to play the animation. Note that we've modified the constructor slightly to remove the name of the sprite, so
the Game class wll need some minor modifications.

The final step in getting our animation to play is to update the current sprite as time progresses. We already have a handy place in which we can perform this action. Our "move()" method already gets told when time passes, so we can update the animation there.

public void move(long delta) {
	// since the move tells us how much time has passed
	// by we can use it to drive the animation, however
	// its the not the prettiest solution
	lastFrameChange += delta;
	
	// if we need to change the frame, update the frame number
	// and flip over the sprite in use
	if (lastFrameChange > frameDuration) {
		// reset our frame change time counter
		lastFrameChange = 0;
		
		// update the frame
		frameNumber++;
		if (frameNumber >= frames.length) {
			frameNumber = 0;
		}
		
		sprite = frames[frameNumber];
	}

	...
}

So, as time passes our lastFrameChange counter will get updated. Once its passed our frameDuration limit we reset it. In addition we move to the next frame number. Then we reset the current sprite by setting the "sprite" member in the Entity super class to the current frame of animation. Next time the entity is rendered a different sprite is
drawn and the animation takes place!

Finishing Off


Hopefully this tutorial has been of some help. While I recommend using the GAGE timer the other methods and other native libraries have been used by a great number of people and are probably just as good. Its worth looking around and choosing the method that suits your need and methods best.

If you have any comments or corrections feel free to mail me here

Exercises for the Reader


The following exercises might help the reader in understanding timing and animation more fully in this context.


Add animation for the shots


This should be a matter of adding some functionality similar to that added to AlienEntity to ShotEntity.

Implement timing using a different timer


There are a few native timer implementations. It should be relatively simple to try a different one. This would help understanding how Java uses native libraries to provide extra functionality.


Implement time averaging.


One of the other methods for providing useful timing on all platforms is to average the change in time across frames. The algorithm for doing is discussed above.


Add an Animated Sprite


Another way to implement the animation would have been to add a "AnimatedSprite". The flip over of images could have been handled within the class. In this way any entity could have been animated by simply using an animated sprite.


Credits

Tutorial and Source written by Kevin Glass
Game sprites provided by Ari Feldman
A large number of people over at the Java Gaming Forums

Space Invaders 103 - Refactoring and OpenGL

Introduction


This tutorial follows on from Space Invaders 102. The initial aim of this tutorial is to understand rendering 2D graphics using JOGL and compare this to Java2D. However, to do this clearly the tutorial attempts to refactor the original space invaders source code to pull out exactly the differences between the two methods of rendering. There are parts of the tutorial that can be ignored if the reader isn't interested in the design side of development and these will be noted throughout.

The result of this tutorial can be seen here. The complete source for the tutorial can be found here. Its intended that you read through this tutorial with the source code at your side. The tutorial isn't going to cover every line of code but should give you enough to fully understand how it works.

Context highlighted source is also available here:

Game.java GameWindow.java GameWindowCallback.java ResourceFactory.java Sprite.java Entity.java ShipEntity.java ShotEntity.java AlienEntity.java SystemTimer.java

Java2DGameWindow.java Java2DSprite.java Java2DSpriteStore.java

JoglGameWindow.java JoglSprite.java Texture.java TextureLoader.java

Keyboard.java


Disclaimer: This tutorial is provided as is. I don't guarantee that the provided source is perfect or that that it provides best practices.


Refactoring Space Invaders


In this section we're going to look at what "refactoring" is and why we're doing it in this case. If you're not interested in design just skip it.

Our last space invaders development was solely based around Java2D. This time round we'd like to support OpenGL. Now we could just rehack the source code to replace the Java2D implementation with an OpenGL version. While in many cases this would be perfectly logical, in this case what'd we'd really like is to be able to compare and contrast the two versions. Even more importantly, in the future we could anticipate using yet another different method of rendering. This is where refactoring comes in.

Refactoring is generally the process of taking a piece of code that put together to a specific job and redesigning it to be more flexible and/or easier to maintain. It happens to most developers at some point, when starting a project the intentions were one thing. Later on, having understood the problem more fully and having realised the mistakes it seems like a good idea to start a fresh piece of code or to rewrite what you have. At this point the best bet is to refactor the code, normally before adding anything else. In this way, often refactoring itself can be a very thankless process since the functionality you have afterwards should be very similar to what you had before. However, as a good Java/OO developer you have to trust that redesigning your source is going to save you time in the long run.

In games its generally desirable to have decided what you're going to use to render at the begining. This means you don't spend alot of time trying to get multiple rendering methods displaying something that is very easy to produce in one of them. For instance, fast alpha blending is difficult to achieve in Java2D, however in OpenGL its very easy. Enforcing that we support both rendering methods can be difficult and apart from anything else a waste of valuable development time. All this being said, in this case we're trying look at the differences in rendering and so thats exactly what we're going to do. We're going introduce a set of interfaces that describe what we need our rendering layer to be able to do for us. Then we'll supply implementations of these interfaces for each of our intended rendering layers.

Rendering


So first off we need to consider what we need to render. Essentially we need a window to draw our game in and a loop to actively keep rendering our game. Here we go then, an interface describing what we need from our window.

package org.newdawn.spaceinvaders;

/**
 * The window in which the game will be displayed. This interface exposes just
 * enough to allow the game logic to interact with, while still maintaining an
 * abstraction away from any physical implementation of windowing (i.e. AWT, LWJGL)
 *
 * @author Kevin Glass
 */
public interface GameWindow {
	
	/**
	 * Set the title of the game window
	 * 
	 * @param title The new title for the game window
	 */
	public void setTitle(String title);
	
	/**
	 * Set the game display resolution
	 * 
         * @param x The new x resolution of the display
	 * @param y The new y resolution of the display
	 */
	public void setResolution(int x,int y);
	
	/**
	 * Start the game window rendering the display
	 */
	public void startRendering();
	
	/**
	 * Set the callback that should be notified of the window
	 * events.
	 * 
	 * @param callback The callback that should be notified of game
	 * window events.
	 */
	public void setGameWindowCallback(GameWindowCallback callback);
	
	/**
	 * Check if a particular key is pressed
	 * 
	 * @param keyCode The code associate with the key to check
	 * @return True if the particular key is pressed
	 */
	public boolean isKeyPressed(int keyCode);
}

setTitle(), setResolution() and startRendering() are directly related to the window and game loop. We have two extra additions here. First off, just like rendering to the screen we need our game window to provide with a way to check if a given key is pressed. In the last version we used standard KeyListeners to do this for us, however if we want to be truely independant of how our game is rendered we need this to be abstract this as well. In addition we've added setGameWindowCallback(), this is how we're going to hook into the game loop. The class that we set as GameWindowCallback is going to be notified each time the frame is being rendered. This will give us a chance to draw our game in frame. The GameWindowCallback interface looks like this:

package org.newdawn.spaceinvaders;

/**
 * An interface describing any class that wishes to be notified 
 * as the game window renders. 
 * 
 * @author Kevin Glass
 */
public interface GameWindowCallback {
	/**
	 * Notification that game should initialise any resources it
	 * needs to use. This includes loading sprites.
	 */
	public void initialise();
	
	/**
	 * Notification that the display is being rendered. The implementor
	 * should render the scene and update any game logic
	 */
	public void frameRendering();
	
	/**
	 * Notification that game window has been closed.
	 */
	public void windowClosed();
}

As you can see the GameWindowCallback has just a bit more than frame rendering notification in it. We have an initialise method, thats going to be called at startup. Many resources that we load are dependant on the rendering layer being in the right state. For instance, in Java2D when we load our sprites we need to make sure we've changed graphics modes first, so the sprites get loaded in the right format. Finally theres an additional hook to notify when the game rendering window has been closed.

So, our game window implementations will be responsible for creating an actual window, and running a game loop. In this game loop the GameWindow is going to call frameRendering() to let us know that we need to draw our game, but how are we going to draw our game without knowing which rendering layer is in use? To solve this we're going to have to create an interface for our main drawing tool, Sprite. Intead of Sprite being a concrete class that draws a sprite to Java2D we're going to make it an interface that can be implemented by the different rendering layers. Here's what we required from the sprite:

package org.newdawn.spaceinvaders;

/**
 * A sprite to be displayed on the screen. Note that a sprite
 * contains no state information, i.e. its just the image and 
 * not the location. This allows us to use a single sprite in
 * lots of different places without having to store multiple 
 * copies of the image.
 * 
 * @author Kevin Glass
 */
public interface Sprite {


	/**
	 * Get the width of the drawn sprite
	 * 
	 * @return The width in pixels of this sprite
	 */
	public int getWidth();

	/**
	 * Get the height of the drawn sprite
	 * 
	 * @return The height in pixels of this sprite
	 */
	public int getHeight();
	
	/**
	 * Draw the sprite onto the graphics context provided
	 * 
	 * @param x The x location at which to draw the sprite
	 * @param y The y location at which to draw the sprite
	 */
	public void draw(int x,int y);
}

For those who followed the first two tutorials this interface should look very familiar. Essentially it matches the interface of the original Sprite class in the Java2D implementations. This happens quite often when refactoring code, its normally called "extracting the interface". What we're trying to say here is that any class that represents a sprite that can be drawn to the screen much be able to do the specified things.

Now we've defined what resources we need to play out game, GameWindow and Sprite, and we've defined what these resources must be able to do for us. Next we can look at how we implement these two resources in the different rendering methods.

Refactorying Java2D Rendering


Since we've already implemented the game in Java2D we should have all the elements we need already coded. We now need to rearrange the old implementation to match up with our interfaces. Lets look at Java2DGameWindow first, this will be the class that implements GameWindow and maintains a normal AWT window. Essentially this class will create a JFrame and maintain a game loop like our old Game class did.

The only significant change is in the game loop, instead of drawing the sprites within the actual loop we're going to call a method on the GameWindowCallback and rely on which ever class implements that interface to draw our sprites. The game loop looks like this:

private void gameLoop() {
	while (gameRunning) {
		// Get hold of a graphics context for the accelerated 
		// surface and blank it out
		g = (Graphics2D) strategy.getDrawGraphics();
		g.setColor(Color.black);
		g.fillRect(0,0,800,600);
		
		if (callback != null) {
			callback.frameRendering();
		}

		// finally, we've completed drawing so clear up the graphics
		// and flip the buffer over
		g.dispose();
		strategy.show();
	}
}

We've extracted a portion of the original Game class which was responsible for setting up the window to be rendered in. Next, if a callback has been registered we notify it that a game frame is being rendered and hence it should draw anything to the screen its going to. Finally, another part of the original class that is responsible for swapping over our Java2D buffer strategy.

Everything else in Java2DGameWindow has been extracted from the original Game class with the exception of the keyboard handling. Since we're going to want similar keyboard handling in both OpenGL and Java2D this has been pulled out into a seperate class called "Keyboard". However, this will be covered further on in this tutorial.

The next thing we should look at is Java2DSprite. If you look through the code you'll find its almost identical to the original Sprite class from the Java2D tutorial. However, there is one small, but very important change, here:

public void draw(int x,int y) {
	window.getDrawGraphics().drawImage(image,x,y,null);
}

Note that the graphics context is no longer passed into the draw method. When we ask a Sprite to draw itself we do so from a class that does not know what type of rendering is going on. However, since a sprite must be being drawn into a window the sprite can now obtain its graphics context from the window itself (which is parameter to its construction).

Thats pretty much it for refactoring. We've made our original code much more abstract by introducing interfaces for each of the resources. In addition we've changed our Java2D code to match up with our new interfaces. Next lets look at the keyboard handling.

Implementing AWT Keyboard Input


In the first two tutorials we were very explicit about which keys we expected to`be pressed. While this suited our purposes for the first tutorial its not very reusable. It would be nice to have a central location to be able to check which keys are pressed. It would`also be nice to be able to hide all the tricky bits of keyboard manipulation away somewhere. Our GameWindow interface already has a isKeyPressed() method so all we need`now is one central class to provide the checks.

public class Keyboard {
	/** The status of the keys on the keyboard */
    private static boolean[] keys = new boolean[1024];
    
    /**
     * Initialise the central keyboard handler
     */
    public static void init() {
        Toolkit.getDefaultToolkit().addAWTEventListener(new KeyHandler(),
                                            AWTEvent.KEY_EVENT_MASK);         
    }
    
    /**
     * Initialise the central keyboard handler
     * 
     * @param c The component that we will listen to
     */
    public static void init(Component c) {
    	c.addKeyListener(new KeyHandler());         
    }
    
    /**
     * Check if a specified key is pressed
     * 
     * @param key The code of the key to check (defined in KeyEvent)
     * @return True if the key is pressed
     */
    public static boolean isPressed(int key) {
        return keys[key];
    }
    
    /**
     * Set the status of the key
     * 
     * @param key The code of the key to set
     * @param pressed The new status of the key
     */
    public static void setPressed(int key,boolean pressed) {
        keys[key] = pressed;
    }

We are trying to write a nice reusable class so there will be some extra functionality in the eyboard class`that isn't used directly here. Its just nice to implement these things up front so there ready and waiting when you get round to needing them.

First in our Keyboard class we need a set of flags to indicate whether a given key is pressed and a couple of accessor methods to allow us to check if a key is pressed and indicate that a key is pressed. When we initialise the Keyboard class we can do it two ways. First, and most commonly`we can pass in a component. A key listener will be added to this component and the state recorded. On the other hand it sometimes helps to be able to respond to key presses on a global scale, not localised to a particular component. With this in mind theres a second init method which allows us to add a AWTEventListener directly to the AWT event queue. This will pick up any keyboard events at a global level.

Now on to the all important key listener class. This is a bit specialised so don't be surprised if it looks a bit complicated,

private static class KeyHandler extends KeyAdapter implements AWTEventListener {
   	/**
    	 * Notification of a key press
    	 *	 
    	 * @param e The event details
    	 */
	public void keyPressed(KeyEvent e) {
    		if (e.isConsumed()) {
    			return;
     		}
            keys[e.getKeyCode()] = true;
 	}
        
      /**
       * Notification of a key release
       * 
       * @param e The event details
       */
      public void keyReleased(KeyEvent e) {
      	if (e.isConsumed()) {
           return;
        }
        	
        KeyEvent nextPress = (KeyEvent) Toolkit.getDefaultToolkit().
                                         getSystemEventQueue().
                                         peekEvent(KeyEvent.KEY_PRESSED);
        	
        if ((nextPress == null) || 
              (nextPress.getWhen() != e.getWhen()) || 
              (nextPress.getKeyCode() != e.getKeyCode())) {
        		keys[e.getKeyCode()] = false;
         }  	
      }
        
      /**
       * Notification that an event has occured in the AWT event
       * system
       * 
       * @param e The event details
       */
      public void eventDispatched(AWTEvent e) {
          	if (e.getID() == KeyEvent.KEY_PRESSED) {
              	keyPressed((KeyEvent) e);
          	}
          	if (e.getID() == KeyEvent.KEY_RELEASED) {
              	keyReleased((KeyEvent) e);
            }
     }   
}

The first thing thats complicated about this class is that its actually being two different things. First of add its a key listener (well its a KeyAdapter) and secondly its implementing the AWTEventListener interface.

AWTEventListener allows us to be notified of events directly as they become available to the AWT event queue. While this is immensely useful, its also a bit dirty in that we get passed the events as AWTEvent. In our case we're only interested in key events so we can check the ID of the event and then palm off the event to the method that would normally recieve it. This all happens in eventDispatched().

The other part that makes this key handler difficult to understand is the extra bits of code in the keyReleased() method. It would seem to be as simple as indicating that the key is no longer pressed by setting the appropriate index in the keys array to false. However, theres an issue here where Java isn't quite as platform independant as we'd like it to be. When you hold a key down on a keyboard you get a slight pause then the key begins to repeat across the screen. This is normal everywhere. However, the notification for this in Java changes from platform to platform. On Windows when the key begins to repeat no extra notifications are sent, the key is considered still to be pressed. However, on Linux when a key begins to repeat a notifcation of release and then pressed is sent for each repeat. This means that if the user was to hold down the key then our little space ship would move a bit, then stop, then move a bit, then stop, and so on.

Getting round this is a little more complicated than you'd think. In this case we end up with the following code:

KeyEvent nextPress = (KeyEvent) Toolkit.getDefaultToolkit().
                                    getSystemEventQueue().
                                    peekEvent(KeyEvent.KEY_PRESSED);
        	
if ((nextPress == null) || 
    (nextPress.getWhen() != e.getWhen()) || 
    (nextPress.getKeyCode() != e.getKeyCode())) {
	keys[e.getKeyCode()] = false;
}  	

When a keyReleased notification is recieved we search the pending AWT events by using peekEvent() for a keyPressed event. If there is a keyPressed event scheduled for the exact same moment the keyReleased event is scheduled then its auto-repeat on linux causing the events. At which point we ignore it. Complicated and annoying, Java has a few things like this that are slowly being sorted out.

Having gone through all that, as long as we've called one of the init methods on our Keyboard class we can now implement our GameWindow's isKeyPressed method by calling keyPressed() here. As we implement other rendering methods that use AWT (JOGL for instance) we can now reuse our class to handle key input.

Completing the Picture


The final step in our refactoring is to integrate our new resource interfaces with our game logic. After this we should be back to a working game, it won't look any different to before (apart from text is no longer supported so we'll use some fixed sprites intead). However, the new code structure is going to make it much easier to look at adding OpenGL.

Resource Factory


First off, how are we going to get hold of our new Java2D implementations of resources. We could just construct them directly but that makes us a bit too dependant on the rendering layer. Theres a fairly common pattern used for this type of problem called the "Factory". Essentially, we ask the factory for a particular type of resource. It returns up a concrete implementation as the interface we asked for. Sounds a bit strange, this is how it works out for instance in ResourceFactory for sprites:

public Sprite getSprite(String ref) {
	if (window == null) {
		throw new RuntimeException(
                   "Attempt to retrieve sprite before game window was created");
	}
	
	switch (renderingType) {
		case JAVA2D:
		{
			return Java2DSpriteStore.get().getSprite(
                                (Java2DGameWindow) window,ref);
		}
		case OPENGL_JOGL:
		{
			return new JoglSprite((JoglGameWindow) window,ref);
		}
	}
	
	throw new RuntimeException("Unknown rendering type: "+renderingType);
}

We ask the ResourceFactory for a sprite given by a specific reference. Depending on the type of rendering we're using the appropriate type of sprite is created (be it Java2DSprite or JoglSprite). However, its passed back as the interface Sprite, this means that caller doesn't need to worry about which type of rendering is being used. Note, we use a JoglSprite here that we're going to go on an implement later in this tutorial.

If you check through the rest of ResourceFactory you'll find its pretty simple after understanding this. The only hook into the type of rendering performed is provided by the rather explcitly named "setRenderingType()". We'll call this from our main game class to set which type of rendering we want to use.

Game Logic Changes


Finally we need to update our main class to make use of all the new exciting bits of code we've added. After this is complete we can move on to adding a new rendering layer, i.e. OpenGL to our simple space invaders game.

The first thing to note is that since we've extracted all the window management and game loop functionality and added it to the Java2DGameWindow we can remove it all from the Game class. This leaves the game class as a collection of bits of game logic and a piece of code to render the game screen. In addition to removing the window management code we can also strip out the keyboard
code since that is also handled by the rendering layer.

Instead of creating the window directly we're going to ask the ResourceFactory class for it. We'll register ourselfs as the GameWindowCallback so we'll get notified of rendering. Finally, instead of starting out own game loop we simply ask the GameWindow to start rendering which is effectively our old game loop.

public Game(int renderingType) {
	// create a window based on a chosen rendering method
	ResourceFactory.get().setRenderingType(renderingType);
	window = ResourceFactory.get().getGameWindow();
	
	window.setResolution(800,600);
	window.setGameWindowCallback(this);
	window.setTitle(windowTitle);
}

public void startGame() {
	window.startRendering();
}

Now, we have a very pure and simple class. The final step in locking together the rendering layer and game logic is to modify the Game class to implement the GameWindowCallback interface. This means moving all resource loading into the initialise() method (note that this includes entity creation),
and modifying the gameLoop() method to be the frameRendering() method. We no longer need to manage the game loop since the GameWindow in use is going to do that for us.

Thats it, we're done. At this stage we should be able to play our Java2D version of the game as before. There are some minor changes in addition to those noted above which complete the picture which are to do with swapping over from explictly creating our resource to asking the ResourceFactory for them. Our next and probably more interesting step is going to be to provide an OpenGL rendering layer. We won't need to touch the game logic again so from here on should be plain sailing.

Implementing OpenGL Rendering


For those just interested in a guideline on how to use JOGL, here we go. We're now going to add a rendering layer using JOGL. However, it seems only fair to first consider alternatives for using OpenGL in Java.

OpenGL Choices


OpenGL is currently only accessable in Java through a native library (for more on these check out the discussion in Space Invaders 102. However, unlike timing, for OpenGL you're going to need a native library for any platform that you deploy on. This can increase your deployment size a great deal. In addition, if you rely on OpenGL you are also relying on the user having up-to-date drivers for their graphics card. However, this is a well known issue to most gamers and so doesn't normally cause any issue.

OpenGL does of course has many advantages. On most platforms you'll get hardware acceleration, there are many special effects that are easily achievable with OpenGL.

GL4Java


One of the original native bindings for Java. Currently this binding is no longer supported and has fallen behind the OpenGL standard. Perfomance is also poor in comparison to other possible APIs.

Lighweight Java Gaming Library (LWJGL)


This binding is far more than simply an access layer to OpenGL. It also contains a binding to OpenAL (the audio library) and some custom interfaces to input controllers. There is a large community of developers around the library and support is always forth coming.

The only downside of the LWJGL is that you need to buy into all of the ideas behind the library or none of them. Assuming you agree with everything the library has been written around then this isn't a problem.

Java OpenGL (JOGL)


JOGL is a simple OpenGL binding produced by the community but spearheaded by Sun. JOGL only exposes OpenGL and does so in a very clean and simple manner. However, it is dependant on AWT and as such isn't suitable for native compilation.

With luck JOGL will be making it into the JDK at some later date. As/when this happens JOGL can be considered part of pure Java. With this in mind I'll use JOGL as our native layer for this tutorial.

JOGL Interface


Next we'll look at producing a rendering layer for our space invaders game based on OpenGL. The first thing we need to do is implement a GameWindow for OpenGL. To do this we're going to implement the main interface that JOGL provides, GLEventListener. This interface consists of four methods described below.

initialise() - Called by JOGL to request that you initialise any resource you require. This maps directly to our GameWindow's initialise() method. The GLDrawable passed in can be used to access GL during this method.

display() - Called by JOGL to request that you render the scene. This effectively our hook into JOGL for our game loop. The GLDrawable passed in can be used render to the screen while in this method.

reshape() - Called to indicate that the window has been resized or moved. Most of the time we don't need to do anything here apart from adapting for resolution.

displayChanged() - Called to indicate that the graphics mode has been changed. For our purposes this will never happen.

Here's how these things look in the our JoglGameWindow. We'll look at the rest of the code piece by piece later on.

public class JoglGameWindow implements GLEventListener,GameWindow {
	/** The frame containing the JOGL display */
	private Frame frame;
	/** The callback which should be notified of window events */
	private GameWindowCallback callback;
	/** The width of the game display area */
	private int width;
	/** The height of the game display area */
	private int height;
	/** The canvas which gives us access to OpenGL */
	private GLCanvas canvas;
	/** The OpenGL content, we use this to access all the OpenGL commands */
	private GL gl;
	/** The loader responsible for converting images into OpenGL textures */
	private TextureLoader textureLoader;
	
	/**
	 * Create a new game window that will use OpenGL to 
	 * render our game.
	 */
	public JoglGameWindow() {
		frame = new Frame();
	}
	
	/**
	 * Retrieve access to the texture loader that converts images
	 * into OpenGL textures. Note, this has been made package level
	 * since only other parts of the JOGL implementations need to access
	 * it.
	 * 
	 * @return The texture loader that can be used to load images into
	 * OpenGL textures.
	 */
	TextureLoader getTextureLoader() {
		return textureLoader;
	}
	
	/**
	 * Get access to the GL context that can be used in JOGL to
	 * call OpenGL commands.
	 * 
	 * @return The GL context which can be used for this window
	 */
	GL getGL() {
		return gl;
	}
	
	/**
	 * Set the title of this window.
	 *
	 * @param title The title to set on this window
	 */
	public void setTitle(String title) {
		frame.setTitle(title);
	}

	/**
	 * Set the resolution of the game display area.
	 *
	 * @param x The width of the game display area
	 * @param y The height of the game display area
	 */
	public void setResolution(int x, int y) {
		width = x;
		height = y;
	}

	/**
	 * Start the rendering process. This method will cause the 
	 * display to redraw as fast as possible.
	 */
	public void startRendering() {
		canvas = GLDrawableFactory.getFactory().createGLCanvas(new GLCapabilities());
		canvas.addGLEventListener(this);		
		canvas.setNoAutoRedrawMode(true);
		canvas.setFocusable(true);

		Keyboard.init(canvas);
		
		Animator animator = new Animator(canvas);
		
		// Setup the canvas inside the main window
		frame.setLayout(new BorderLayout());
		frame.add(canvas);
		frame.setResizable(false);
		canvas.setSize(width, height);
		frame.pack();
		frame.show();
		
		// add a listener to respond to the user closing the window. If they
		// do we'd like to exit the game
		frame.addWindowListener(new WindowAdapter() {
			public void windowClosing(WindowEvent e) {
				if (callback != null) {
					callback.windowClosed();
				} else {
					System.exit(0);
				}
			}
		});
		
		// start a animating thread (provided by JOGL) to actively update
		// the canvas
		animator.start();
	}

	/**
	 * Register a callback that will be notified of game window
	 * events.
	 *
	 * @param callback The callback that should be notified of game
	 * window events. 
	 */
	public void setGameWindowCallback(GameWindowCallback callback) {
		this.callback = callback;
	}

	/**
	 * Check if a particular key is current pressed.
	 *
	 * @param keyCode The code associated with the key to check 
	 * @return True if the specified key is pressed
	 */
	public boolean isKeyPressed(int keyCode) {
		return Keyboard.isPressed(keyCode);
	}

	/**
	 * Called by the JOGL rendering process at initialisation. This method
	 * is responsible for setting up the GL context.
	 *
	 * @param drawable The GL context which is being initialised
	 */
	public void init(GLDrawable drawable) {
		// get hold of the GL content
		gl = drawable.getGL();
		
		// enable textures since we're going to use these for our sprites
		gl.glEnable(GL.GL_TEXTURE_2D);
		
		// set the background colour of the display to black
		gl.glClearColor(0, 0, 0, 0);
		// set the area being rendered
		gl.glViewport(0, 0, width, height);
		// disable the OpenGL depth test since we're rendering 2D graphics
		gl.glDisable(GL.GL_DEPTH_TEST);
		
		textureLoader = new TextureLoader(drawable.getGL());
		
		if (callback != null) {
			callback.initialise();
		}
	}

	/**
	 * Called by the JOGL rendering process to display a frame. In this
	 * case its responsible for blanking the display and then notifing
	 * any registered callback that the screen requires rendering.
	 * 
	 * @param drawable The GL context component being drawn
	 */
	public void display(GLDrawable drawable) {
		// get hold of the GL content
		gl = canvas.getGL();
		
		// clear the screen and setup for rendering
		gl.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
		gl.glMatrixMode(GL.GL_MODELVIEW);
		gl.glLoadIdentity();
		
		// if a callback has been registered notify it that the
		// screen is being rendered
		if (callback != null) {
			callback.frameRendering();
		}
		
		// flush the graphics commands to the card
		gl.glFlush();
	}

	/**
	 * Called by the JOGL rendering process if and when the display is 
	 * resized.
	 *
	 * @param drawable The GL content component being resized
	 * @param x The new x location of the component
	 * @param y The new y location of the component
	 * @param width The width of the component
	 * @param height The height of the component 
	 */
	public void reshape(GLDrawable drawable, int x, int y, int width, int height) {
		gl = canvas.getGL();
		
		// at reshape we're going to tell OPENGL that we'd like to 
		// treat the screen on a pixel by pixel basis by telling
		// it to use Orthographic projection.
		gl.glMatrixMode(GL.GL_PROJECTION);
		gl.glLoadIdentity();

		gl.glOrtho(0, width, height, 0, -1, 1);
	}

	/**
	 * Called by the JOGL rendering process if/when the display mode
	 * is changed.
	 *
	 * @param drawable The GL context which has changed
	 * @param modeChanged True if the display mode has changed
	 * @param deviceChanged True if the device in use has changed 
	 */
	public void displayChanged(GLDrawable drawable, 
                                   boolean modeChanged, 
                                   boolean deviceChanged) {
		// we're not going to do anything here, 
                // we could react to the display 
		// mode changing but for the tutorial there's not much point.
	}

}

As you can see, using GL from inside the initialise() and display() methods is fairly simple. The most complicated part of the game window is the initialisation of the main window, this all takes place in startRendering(). First off lets look at how we initialise JOGL.

canvas = GLDrawableFactory.getFactory().createGLCanvas(new GLCapabilities());
canvas.addGLEventListener(this);		
canvas.setNoAutoRedrawMode(true);
canvas.setFocusable(true);

We first create a canvas based on a set of GLCapabilities. These capabilities can define exactly what abilities the OpenGL context we create must have. For our purposes we'll just use the default set which suits us fine for some simple 2D graphics. Next, we set ourselfs up as the GLEventListener so we'll get notified when intiailisation and rendering happen. Finally, we configure the canvas to be the focused component and to require active redrawing.

Just like in the Java2DGameWindow we create a Frame and add the created canvas to it. The last thing we need to do is start some sort of game loop. Since we want our GLCanvas to be actively redrawn we can use a utility class provided from JOGL, using these two lines:

Animator animator = new Animator(canvas);
...
animator.start();

The animator will cause the GLCanvas to be initialised and to be actively redrawn as fast as possible, which is essentially what we do in Java2DGameWindow except we don't have a useful utility class to do it for us.

And thats it! Setting up an OpenGL rendering surface is very simple using JOGL. However, now we need to look at sprites.

JOGL Sprites


To use images in OpenGL they must first become textures. What we're going to do is create a texture for each image we want to use in the game. Then we'll draw a polygon (a quad to be exact) on which we'll put our sprite image.

Loading Textures


Loading textures isn't a simple matter. First you need to load the image from disk, we're lucky in Java, the ImageIO class can do this for us. Next we need to create a block of memory to store the image in a format that OpenGL can understand. Finally, we need to tell OpenGL where the memory is and to load it as a texture. The details of this procedure are outside of the scope of this tutorial. The source code includes a class that will allow us to load textures (which has been based on a class provided in the Java Gaming Wiki). The class is fairly clear and should be understandable with a bit of looking around.

Drawing the Sprites


Our final step is to create a Sprite implementation that will draw the textures we load into OpenGL. Take a look a JoglSprite, looks familiar right? Its very similar to Java2DSprite. The only ignigicant changes are how we get the image and how we draw it. Lets look first at getting hold of the image:

public JoglSprite(JoglGameWindow window,String ref) {
	try {
		this.window = window;
		texture = window.getTextureLoader().getTexture(ref);
		
		...

The texture loader caches image references and so we don't have to worry about it loading the same image more than once. The texture object returned stores everything we need to use the texture.

The final change is to actually draw the sprite to the screen using OpenGL, that looks like this:

public void draw(int x, int y) {
	// get hold of the GL content from the window in which we're drawning
	GL gl = window.getGL();
	
	// store the current model matrix
	gl.glPushMatrix();
	
	// bind to the appropriate texture for this sprite
	texture.bind(gl);		
	// translate to the right location and prepare to draw
	gl.glTranslatef(x, y, 0);		
	gl.glColor3f(1,1,1);
	
	// draw a quad textured to match the sprite
	gl.glBegin(GL.GL_QUADS);
	{
		gl.glTexCoord2f(0, 0);
		gl.glVertex2f(0, 0);
		gl.glTexCoord2f(0, texture.getHeight());
		gl.glVertex2f(0, height);
		gl.glTexCoord2f(texture.getWidth(), texture.getHeight());
		gl.glVertex2f(width,height);
		gl.glTexCoord2f(texture.getWidth(), 0);
		gl.glVertex2f(width,0);
	}
	gl.glEnd();
		
	// restore the model view matrix to prevent contamination
	gl.glPopMatrix();
}

First we retrieve access to the GL context from the window we're rendering into. Just like in the Java2D version we do this inside the class to prevent the caller having to worry about where the sprite is being rendered.

Next we indicate to OpenGL which texture we're using for this sprite. The texture object returned from the texture loader has a simple bind() method to allow us to do this. Once we've told GL which texture to use we simply draw a quad where we want the sprite to appear. For each vertex on the quad we specify a texture coordinate, normally called texture mapping. Note, the use of texture.getWidth() and texture.getHeight(), this is to adapt the texture mapping for the size of texture that has been allocated. When textures are created they must be certain sizes and only a proprotion of them may need to be mapped across the quad. The texture object returned from the texture contains information decribing what proporption of the texture has been used. This is used to map the texture exactly across the quad.

So, to draw a sprite in OpenGL we load a texture, draw a quad and map the texture across it. There are many other ways of drawing similar sprites in OpenGL (glBitmap for instance). There are also ways to optimize these calls using GL lists and vertex buffers. However, for simple 2D games most this isn't really required.

Finishing Off


As you can see, when completing the game I've added a small window to allow you to choose your rendering type. This code for this is very simple and can be found in the main() method in Game

Hopefully this tutorial has been of some help. Personally, I've only used JOGL, hence the tutorial being oriented towards it, however I've heard LWJGL is a great API and I'd really recommend checking it out.

Another interesting point is that in Java 1.5 the Java 2D is going to support OpenGL, that is it will be possible to render the Java2D graphics using OpenGL. Hopefully this is going to make using OpenGL for 2D graphics in Java redundant.

If you have any comments or corrections feel free to mail me here

Exercises for the Reader




Port to LWJGL


It should be fairly simply to provide a rendering layer that supports LWJGL instead of JOGL. Implementing a new rendering layer should help to understand the abstraction and from what I hear LWJGL is well worth understanding.


Credits


Tutorial and Source written by Kevin Glass

Game sprites provided by Ari Feldman
A large number of people over at the Java Gaming Forums

Space Invaders 104 - Rendering in LWJGL

Introduction

The past tutorials, apart from designing and writing a simple space invaders game, have been building an infrastructure for comparing the use of rendering techniques. So, hopefully this is going to pay off now when we attempt to start using LWJGL. So in this tutorial we're going to cover:



• Initialising LWJGL
  
• Rendering sprites in LWJGL
  
• Keyboard input in LWJGL
  

This is going to a relatively short tutorial for several reasons. LWJGL is very simple to work with and has some strong similarities to JOGL and hence the last tutorial.

The final game can be see here. The complete source for the tutorial can be found here. Its intended that you read through this tutorial with the source code at your side. The tutorial isn't going to cover every line of code but should give you enough to fully understand how it works.

Context hightlighted source is also available here:



• LWJGLGameWindow.java
  
• LWJGLSprite.java
  
• TextureLoader.java
  
• Texture.java
  
• ResourceFactory.java
  

Disclaimer: This tutorial is provided as is. I don't guarantee that the provided source is perfect or that that it provides best practices.

LWJGL


So whats LWJGL then? Well, LWJGL is the Lightweight Java Games Library. Its lightweight because it doesn't rely on much of the internals of Java. This is good because it allows you to keep the final distributable size down (by cutting out the bits you don't need). Java is a no brainer, its written and designed to work with Java. Most importantly its a game library, not just a binding to OpenGL.

This seems like a trivial point, especially when being illustrated by such a simplistic demo as this spaceinvaders game. However, LWJGL provides not just a graphics binding but a binding to OpenAL (an open standards sound system). In addition, LWJGL gives your access to input devices. This means your spaceinvaders game could be controlled from a gamepad and the aliens could squeltch as they die, all from one library. Worth thinking about.

Adding a new rendering implementation for our SpaceInvaders game should be pretty simple (especially as in this case I didn't have to write the code, thanks Matzon). We're going to add 4 classes then plug then into our architecture.

LWJGL Window

Initialisation

As with the other rendering layers the first thing we need to do is create a window and notify the infrastructure. The initial part of understanding LWJGL is to realise there is only a single window, the one in which the game runs. So, to create and configure our game window we need to configure a display mode for that window like this:

	/**
         * Sets the display mode for fullscreen mode
	 */
	private boolean setDisplayMode() {
            try {
		// get modes
		DisplayMode[] dm = org.lwjgl.util.Display.getAvailableDisplayModes(width, 
                                                            height, -1, -1, -1, -1, 60, 60);

                org.lwjgl.util.Display.setDisplayMode(dm, new String[] {
                     "width=" + width,
                     "height=" + height,
                     "freq=" + 60,
                     "bpp=" + org.lwjgl.opengl.Display.getDisplayMode().getBitsPerPixel()
                }); 

                return true;
            } catch (Exception e) {
                e.printStackTrace();
                System.out.println("Unable to enter fullscreen, continuing in windowed mode");
            }

            return false;
	}

Since there is only one window, the static call on the "Display" class makes sense. The next thing to accept is that there is only one OpenGL context at any given time. Hence we can also access this in a purely static way. These sort of assumptions are one of the things that make LWJGL simple to use.

As you can see from the following code, OpenGL calls are simply prefixed with the class "GL11":

public void startRendering() {
	try {
                setDisplayMode();
                Display.create();
      
		// grab the mouse, dont want that hideous cursor when we're playing!
		Mouse.setGrabbed(true);
 
		// enable textures since we're going to use these for our sprites
		GL11.glEnable(GL11.GL_TEXTURE_2D);
		
		// disable the OpenGL depth test since we're rendering 2D graphics
		GL11.glDisable(GL11.GL_DEPTH_TEST);
		
		GL11.glMatrixMode(GL11.GL_PROJECTION);
		GL11.glLoadIdentity();
		
		GL11.glOrtho(0, width, height, 0, -1, 1);
		
		textureLoader = new TextureLoader();
		
		if(callback != null) {
			callback.initialise();
		}
	} catch (LWJGLException le) {
		callback.windowClosed();
	}
   
	gameLoop();
}

So, we create our window, initialise OpenGL by setting our options and using glOrtho() to configure our view (for more on this see SpaceInvaders 103). Next we create a texture loader, which we will use to load our sprite images. Finally we notify the infrastructure that the initialisation has been completed.

Also note the line "Mouse.setGrabbed(true);". As we'll see later, the mouse and keyboard are also monitored from static contexts. This line simple says that the mouse cursor shouldn't be displayed in the window.

Game Loop


Next lets look at the game loop for LWJGL. As you can see from the code below its very similar to the JOGL version in the last tutorial. Essentially we clear the screen, tell the infrastructure to do any rendering it needs to do, and finally update the windows contents.

private void gameLoop() {
	while (gameRunning) {
		// clear screen
		GL11.glClear(GL11.GL_COLOR_BUFFER_BIT | GL11.GL_DEPTH_BUFFER_BIT);
		GL11.glMatrixMode(GL11.GL_MODELVIEW);
		GL11.glLoadIdentity();
			
		// let subsystem paint
		if (callback != null) {
			callback.frameRendering();
		}
			
		// update window contents
		Display.update();
			
		if(Display.isCloseRequested() || Keyboard.isKeyDown(Keyboard.KEY_ESCAPE)) {
			gameRunning = false;
			Display.destroy();
			callback.windowClosed();
		}
	}
}

The final addition here is to check our exit cases. If the user has closed the window (Window.isCloseRequested()) or if the escape key has been pressed (Keyboard.isKeyDown(Keyboard.KEY_SCAPE)) then we need to notify the infrastructure and destroy the game window. In LWJGL we accomplish this by calling Window.destroy().

Keyboard Handling


LWJGL provides its own keyboard handling object. This means that we don't need to use AWT events to catch key pressed we can simply poll for them using LWJGL's Keyboard class. So the implementation of check for key presses looks like this:

public boolean isKeyPressed(int keyCode) {
	// apparently, someone at decided not to use standard 
	// keycode, so we have to map them over:
	switch(keyCode) {
	case KeyEvent.VK_SPACE:
		keyCode = Keyboard.KEY_SPACE;
		break;
	case KeyEvent.VK_LEFT:
		keyCode = Keyboard.KEY_LEFT;
		break;
	case KeyEvent.VK_RIGHT:
		keyCode = Keyboard.KEY_RIGHT;
		break;
	}    
	
	return Keyboard.isKeyDown(keyCode);
}

The switch() here is a little confusing, why do we need to map VK_SPACE to KEY_SPACE and so on? LWJGL has stuck to the original key codes provided by "most" operating systems and since its a games oriented API this makes perfect sense. Java's AWT however uses its own set of key codes, which means we need a mapping between the two sets. As you can see, for the purposes of SpaceInvaders this is very simple.


LWJGL Sprite


Since LWJGL allows to access OpenGL the code for drawing a sprite on the screen is almost identical to the JOGL version (see part 3). Essentially we draw a rectangle at the right location and at the right size on the screen. We map our sprite texture across this rectangle. The code looks like this:

public void draw(int x, int y) {
	// store the current model matrix
	GL11.glPushMatrix();
		
	// bind to the appropriate texture for this sprite
	texture.bind();
    
	// translate to the right location and prepare to draw
	GL11.glTranslatef(x, y, 0);		
    	GL11.glColor3f(1,1,1);
		
	// draw a quad textured to match the sprite
    	GL11.glBegin(GL11.GL_QUADS);
	{
	      GL11.glTexCoord2f(0, 0);
	      GL11.glVertex2f(0, 0);
	      GL11.glTexCoord2f(0, texture.getHeight());
	      GL11.glVertex2f(0, height);
	      GL11.glTexCoord2f(texture.getWidth(), texture.getHeight());
	      GL11.glVertex2f(width,height);
	      GL11.glTexCoord2f(texture.getWidth(), 0);
	      GL11.glVertex2f(width,0);
	}
	GL11.glEnd();

		
	// restore the model view matrix to prevent contamination
	GL11.glPopMatrix();
}

Note that the only significant change is the use of our GL context. In LWJGL instead of have a GL class implementation, we have static access to the GL11 class which provides us our OpenGL access.

Textures


Like most of the code we've seen here, the texture loader is very similar to the JOGL version. To understand what the code is doing refer to SpaceInvaders 103. There is no significant difference between creating and manipulating textures in JOGL or LWJGL.

Plugging it Together - ResourceFactory updates


Our final step is to plug our new rendering layer into the existing SpaceInvaders infrastructure. To do this we need to make two changes in our ResourceFactory class. The first issue is that in our new rendering layer we use a different game window. Here's the update:

public GameWindow getGameWindow() {
	// if we've yet to create the game window, create the appropriate one
	// now
	if (window == null) {
		switch (renderingType) {
			case JAVA2D:
			{
				window = new Java2DGameWindow();
				break;
 			}
			case OPENGL_JOGL:
			{
				window = new JoglGameWindow();
				break;
			}
			case OPENGL_LWJGL:
			{
				window = new LWJGLGameWindow();
				break;
			}
		}
	}

	return window;
}

All we had to do was add a new leg to the switch will return the appropriate game window for LWJGL. Finally, we need to make a similar change for sprites. Here we're going to create an LWJGLSprite if we're using LWJGL to render:

public Sprite getSprite(String ref) {
	if (window == null) {
		throw new RuntimeException("Attempt to retrieve sprite before game window was created");
	}
		
	switch (renderingType) {
		case JAVA2D:
		{
			return Java2DSpriteStore.get().getSprite((Java2DGameWindow) window,ref);
		}
		case OPENGL_JOGL:
		{
			return new JoglSprite((JoglGameWindow) window,ref);
		}
		case OPENGL_LWJGL:
		{
			return new LWJGLSprite((LWJGLGameWindow) window,ref);
		}
	}
		
	throw new RuntimeException("Unknown rendering type: "+renderingType);
}

And thats it! As noted this is relatively short tutorial. This is partly because our existing infrastruture was designed specifically to support showing the changes in rendering layers. However, hopefully this tutorial has also shown has simple it is to use LWJGL to develop 2D games.

Exercises for the Reader


The following extensions of the game may help in understanding how game hangs together.


Add sound effects using LWJGL


As mentioned above, LWJGL has support for many aspects of games development. One of its strong suits is sound and music using OpenAL. Add some simple sound effects for when the player shoots and the aliens are destroyed. This should help in understanding where to look for information on LWJGL.


Add controller support using LWJGL


LWJGL also has an API for reading input from game controllers connected to your machine. If you have a game controller handy adding support for it often changes the way a game feels altogether. Again, adding this sort of functionality will help learning where to look for more information on LWJGL.


Support Fullscreen mode in LWJGL

Full screen mode is actually more normal for games development and hence for LWJGL. A simple change to the create() call should change the game into a fullscreen application. However, many systems don't support this functionality fully. Its worth experimenting with this addition with a series of different systems.

Further Reading


I'd recommend you take a look at the following material, it'll help support taking the current code to the next stage.



• The Home of LWJGL
  

Credits


Tutorial and Base Source written by Kevin Glass
LWJGL Source written by Brian Matzon
Game sprites provided by Ari Feldman

A large number of people over at the Java Gaming Forums