14. Finishing and Deploying Your Game

What We Will Cover

Illuminations

Questions from last class?

^ top

14.1: Finishing Your Game

Objectives

At the end of the lesson the student will be able to:

  • State the most important requirement of your final game
  • Describe how you can prevent bugs in your code
  • Discuss how to detect and fix bugs in your code

^ top

14.1.1: The Last 10%

"The first 90% of a project takes 90% of the time, the last 10% takes the other 90% of the time."
-- Old Project Manager Saying

  • You will need to do lots of things to finish your game
  • These items include things such as
    • More special effects
    • Splash screens
    • Menus and configuration settings
  • As you finish up, it is important to focus on the most important requirement: your games must work well
  • Before you start to add the extras, make sure your game feels solid and does not have any quirky behavior
  • Check all the user input options to make certain that the games responds correctly
  • If the user switches to another application in the middle of a game, you should pause the game
  • When the user exits the game, the game should actually exit
  • Eliminate all the bugs and quirky behavior that you can
  • If you cannot figure out a problem, you should get help from other students or from the instructor

Adding Sound Effects

  • When polishing your game, do not forget to add plenty of sound effects
  • Sound effects are often only noticeable when they are missing
  • The sound effects you add depend on your game, of course
  • However, some of them you may need, or should think about, include:
    • When the player gets hurt (or dies)
    • When the player jumps or falls
    • When the player scores some particular point
    • When a non-player character is hit or destroyed
    • When a lever is pulled or a door opens
    • When an item is picked up
    • When something flies by the player
    • When some background environment object should make a noise, like:
      • Humming machinery
      • Bubbling brooks
      • Crackling flames
      • Rustling wind
      • Chirping birds
      • Crashing waves
      • Dripping water
    • When you want to give the player hints, like a bad guy is about to fire a weapon
    • When the user is using controls, you may want to give feedback noises like clicks for button presses
  • These are only ideas to help you come up with your own checklist of sound effects
  • Once you have your list made up, use care in placing them in your game
  • Make sure you do not add so many simultaneous sounds that they are difficult to distinguish

Adding Visual Effects

  • Visual effects can refine a game and add a "wow" factor
  • Some effects you might want to consider are:
    • Explosions
    • Flames
    • Lightning
    • Flickering lights
    • Rain, snow and other environment effects
    • Object animations such as running creatures
  • However, keep in mind that adding more effects provide a diminishing return

    • From chapter 8: Chris Crawford on Game Design, by Chris Crawford

  • The first few effects, assuming that they add to the gameplay, are very rewarding
  • However, after a while it becomes just another gimmick

^ top

14.1.2: Debugging

  • Lets return the most important requirement: a robust and well-behaved game
  • We all realize that there are three types of programming errors:
    • Syntax Errors
    • Run-time Errors
    • Logic Errors
  • Syntax errors are caught by the compiler and are the easiest to find and fix
  • However, we have to run the game to find the other types of errors
  • The hardest to find are the logic errors where we might make a mistake in the design or implementation
  • For example, our collision detection might not handle certain situations because we did not anticipate them in our design
  • Because we have to redesign part of the game, they are often the hardest to fix

^ top

14.1.3: Preventing Bugs

  • It may sound obvious, but the best way to debug is to not write bugs into your code
  • Being careful with your code and design can take less time than tracking down a strange bug or redesigning a section of your program
  • The following are some bug-prevention techniques that will help you limit the number of bugs you produce

Check Before Compiling

  • Do not “compile, run, and pray.”
  • When you write a section of code, check it over for anything you might have missed
  • Work through it by hand if you are not sure it will work
  • By preventing problems, you will spend much less time fixing bugs

Pay Attention to the API Documentation

  • Make sure you understand the specification of a method from the Java API
  • Check the parameters and make sure you pass in legal values
  • Check the values it returns and deal with them correctly
  • Check exceptions a method can throw and make sure your design can handle the exceptional situations
  • More information: Java API Specification

Write Readable Code

  • In general, you should write self-documenting code
  • Use meaningful and descriptive variable names
  • Ambiguous names are often a sign that you do not understand the code
  • Also, use constants rather than magic numbers
  • Use indentations and format your code consistently
  • When code is formatted correctly, you can more easily spot errors
  • Use Checkstyle to verify your code is well formatted
  • More information:

Test Your Code Often

  • Write unit test and run your game often
  • Unit tests are simple instructions that test your methods one at a time
  • Writing the tests often makes you think about whether the method is correct
  • When the method is correct and testable you have fewer bugs
  • When you change your method, you run the unit test to verify it still works correctly
  • More information:

^ top

14.1.4: Debugging Tips

  • While you can reduce the number of bugs you produce, you will eventually get bugs in your code
  • The following tips can help you fix them

Run from the Console

  • If you are getting exceptions, run from the console
    • Note that TextPad is set up to always run from the console
    • Most IDEs will show you the console output as well
  • Then look at the stack trace to find the exact line number of the bug
    • Most IDEs and editors will automatically jump to the line in error
    • For instance, with TextPad you just need to double-click the error message to jump to the reported problem in the code
  • Make sure you always fix the first bug in the list
  • Often the first error or warning causes all the rest of the errors and warnings
  • Reading any error or warning beyond the first may be a waste of time

Use println() Debugging

  • Using println() for debugging is a quick and easy way to narrow down the location of a bug
  • You add println() statements to the suspect area to display the values of the variables you are working with
  • By examining the values the variables contain, you can tell if there is a problem and deduce the cause of a problem

Print a Stack Trace

  • You may have noticed the following code pattern in my examples:
    • try {
    // ... code under test
}
catch (Exception e) {
    e.printStackTrace();
}
  • The reason for the e.printStackTrace() is to show how the code arrived at its current place
  • You can use the stack trace to determine what methods calls led up to the current situation
  • It lets you go backwards and check parameters and variables in the current and preceding methods
  • You can add the same line of code to your exceptions if they get thrown
  • Or you can print a stack trace without throwing or catching anything
    • new Throwable().printStackTrace();

Check for Thread Deadlock

  • One of the problems that can occur when you use threads is a deadlock
  • Deadlock is a situation where two or more threads cannot continue because each is waiting on another to do something
  • If you suspect deadlock, run the game from the console and wait for the deadlock to appear
  • Once it appears, return to the console and enter Ctrl+break on Windows (or Ctrl+\ on Mac OS X and UNIX)
  • In the console your will see the state of the threads, any locks acquired, and any deadlock detected
  • For more information, see: Deadlock from Wikipedia

Learn to Use a Debugger

  • A debugger is a tool that lets you step though your source code one line at a time
  • While you step through the code, you can examine and change variables
  • Debuggers let you set breakpoints, which stops program execution and starts the tracing when a certain point is reached
  • They also have ways to examine threads and thread state
  • Debuggers may take a few hours to learn, but can save time in the long run if you do a lot of coding
  • IDEs have a debugger built in, which is one of their big attractions
  • If you do not use an IDE, I recommend the free graphical debugger: JSwat
    • It has a help file that explains its use
  • If you prefer a command line interface, you can use the jdb debugger supplied with the JDK
  • For more information on using jdb, see:

^ top

14.1.5: Summary

  • You will need to do many things to finish your game such as
    • More special effects
    • Splash screens
    • Menus and configuration settings
  • One thing you will need in your game is plenty of sound effects
  • Oftentimes, sound effects are often only noticeable when they are missing
  • We went through some sounds effects possibility to help you determine what you need
  • In addition, you will need to add some special visual effects
  • However, keep in mind that adding more effects provide a diminishing return
  • The first few effects, assuming that they add to the gameplay, are very rewarding
  • However, after a while it becomes just another gimmick
  • As you finish your game, it is important to focus on the most important requirement: your games must work well
    • Bugs are what generally take the "other 90% of the time"
  • The best way to produce bug-free code is to avoid writing bugs in the first place
  • We looked at some techniques for avoiding bugs, including:
    • Checking before compiling
    • Paying attention to the API documentation
    • Writing readable code
    • Testing your code often
  • While you can reduce the number of bugs you produce, you will eventually get bugs in your code
  • We looked at some debugging tips and techniques including:
    • Running from the console
    • Using println() debugging
    • Printing a stack trace
    • Checking for thread deadlock
    • Learning to use a debugger

Check Yourself

  1. What is the most important requirement of your final game?
  2. How can prevent bugs in your code?
  3. What are some techniques for finding the source of bugs in your code?

^ top

Exercise 14.1

Take one minute to review the Check Yourself questions. We will review the questions after you are ready.

^ top

14.2: Deploying Your Game

Objectives

At the end of the lesson the student will be able to:

  • Discuss the options for deploying your game

^ top

14.2.1: Deployment Options

  • When you deploy your game, you want to make it as easy as possible for people to download and install
  • You want to let everyone who wants to play your game have an opportunity to do so
  • Java has a number of ways to deploy games, including many that are designed for deployment over the web
  • They include:
    • Executable JAR files
    • Application installers
    • Java applets
    • Java Web Start
  • We will look at these deployment options in the following sections

^ top

14.2.2: Executable JAR Files

  • A JAR file is the Java version of the Windows Zip file or the UNIX TAR/ZIP file
  • A JAR file lets you bundle multiple files into one single archive file
  • In addition, if Java is installed on the users machine, it will run by double-clicking under Windows
  • Thus, you can deploy your game as an executable JAR file
    • This is what you turn in to WebCT, among other things
  • One downside is that it is not obvious that the JAR file is executable
  • You can get around this problem easily by using a native-executable wrapper

Native-Executable Wrappers

  • A wrapper is a small native program that loads the JVM and then runs your program
  • You can code your own wrapper or use a third-party wrapper
  • Some free third-party wrappers (in no particular order) are:
  • Some wrappers have GUI interfaces for setup and some use only the command line
  • A wrapper usually starts by looking up the JRE
  • If the JRE is not present, some versions will install one if you included it in the wrapping
  • In addition, some wrappers will check for valid versions of the JRE

More Information

^ top

14.2.3: Application Installers

  • A step above an executable wrapper is an installer program
  • An installer can install your application, create shortcuts and manage updates
  • You can either write your own installer or use an installer-generator program
  • Installer-generator programs include commercial programs like:
  • Free alternatives include:
  • Note that jelude, listed in the executable wrappers section, is an NSIS script

Java Aware Installer Generators

  • If you want an installer that will do more than the basic functions, you should look at those that are Java aware
  • A Java-aware installer-generator program potentially adds these benefits:
    • Install-time JRE detection and download
    • Generation of native-executable launchers
    • User-editable JVM parameter files
    • Redirection of stderr and stdout for saving logs and exception stack traces
    • Registration of Java applications as Windows services and Unix daemons
  • Java-aware installer-generators include InstallShield and InstallAnywhere listed above
  • Other commercial installer-generators that are Java-aware include:
  • Free Java-aware alternatives include:

More Information

^ top

14.2.4: Java Applets

  • Java applets are an easy way for someone to play your game
  • A user need only visit your web page and they can start playing
  • However, applets do have some potential problems and restrictions
  • The biggest problem with applets is that the user may not have a recent version of Java installed on their computer
  • To get around this, you can set up your applet HTML code to download the appropriate version
    • As long as the user agrees
  • Another problem is that applets have may security restrictions including:
    • Cannot read, write or delete files on the client system
    • Cannot run programs on the client system
    • Can only access a few properties of the client system such as:
      • Java version
      • Name of operating system
      • Version of operating system
      • Characters used to separate directories, paths and lines
    • Cannot make network connections to servers
      • Other than the one the applet was loaded from
  • Thus, you may need to recode parts of your game to get around these restrictions

Running Your Game as an Applet

  • If you decide to deploy your game as an applet, you will need an applet container class
  • The following code is a container for the example game
  • If you followed the specifications and created a GameManager class, it should work for your games as well
  • In addition, you will need to create the appropriate HTML pages
  • Also, though not strictly required, you should package your game in a JAR file
  • If you are not familiar with creating applets, you should review the materials in More Information below
  • Also, here are two applet pages showing the example game:

Class RunnerApplet

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

import javax.swing.*;

public class RunnerApplet extends JApplet {
    GameManager manager;

    public void init() {
        manager = new GameManager();
        add(manager);
        manager.init();
    }

    public void start() {
        if (manager.isPaused()) {
            manager.setPaused(false);
        } else {
            manager.startGame();
        }
    }

    public void stop() {
        manager.setPaused(true);
    }

    public void destroy() {
        manager.stopGame();
    }
}

More Information

^ top

14.2.5: Java WebStart

  • Java Web Start is a deployment technology that can automatically download and install your games
  • All the users have to do is click a link on a web page, and the rest is automatic
  • If the Java Web Start engine is not present on the system, the user is prompted to download and install it
  • If you modify your game code, it downloads and installs the latest version
  • It is one of the easiest methods of game deployment

Steps for Deploying a Java WebStart Application

  1. After writing and testing the application, package it and all its resources as a JAR file.
  2. Create a public/private keypair for signing the JAR file.
  3. Sign the JAR file(s) with the private key.
  4. Create a deployment file (a JNLP file).
  5. Install the files and setup the server
  6. Test the installer on various client platforms, OSs, and browsers.
    • Some of these test clients should NOT have JWS installed

Creating a Public/Private Keypair

  • The keytool generates and manages keypairs, which are collected together in a keystore
  • Each keypair is made up of a public key and private key, and an associated public-key certificate
  • You run the keytool from the command line using a command like:
    • keytool -genkey -keystore samplekeystore -alias Nobody
  • This creates a new key for the alias Nobody stored in the file samplekeystore
  • You are then prompted to enter a password and other information about yourself, including your name, organization, city, state, and country

Signing the JAR File

  • The jarsigner tool digitally signs a JAR with a private key
  • You run the jarsigner from the command line using a command like:

    • jarsigner -keystore samplekeystore runner.jar Nobody

  • If you want to preserve your original JAR file, you use something like:

    • jarsigner -keystore samplekeystore -signedjar runner_signed.jar runner.jar Nobody

  • The name of the new JAR can be anything you choose
  • Remember that you must sign all the JAR files for your game

Creating a JNLP File

  • After you have a signed JAR file, you need to create a JNLP (Java Network Launching Protocol) file
  • A JNLP file describes your game and what security permissions and resources (JAR files) it needs
  • You can see an example JNLP file below
  • The codebase is the path and the href is the name of the JNLP file itself
    • Note that the example uses a file:// codebase so the so the installation can be tested locally
    • You change this to the correct URL when installing on the server
  • The information tag lets you specify various data including two forms of textual description:
    • A one-line message
    • A longer paragraph (confusingly labeled with the attribute value short)
  • In addition, you specify the icon and splash-screen images using files like:
  • Any icon name is allowed and the image can be in either the GIF or the JPEG format
  • Both 32x32 and 64x64 versions of the icon are displayed but Java Web Start will resize the icon as needed
  • The splash screen is displayed while the application is loading
  • The offline-allowed tag states that the application can run when JWS detects that the network is unavailable
  • Permissions are set in the security tag, which you need for full-screen mode
  • The resources tag lets you specify the resources the game needs like the JAR files and Java version
    • The + sign specifies that you can use a later version as well
  • The application-desc tag lets you specify the main-class attribute
  • Note that JWS ignores the JAR manifest and you need to specify the main class in the JNLP file

Example JNLP Deployment File (runner.jnlp)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<?xml version="1.0" encoding="utf-8"?>
<jnlp
  spec="1.0+"
  <!--
  codebase="http://www.edparrish.com/cis160/game/"
  -->
  codebase="file:///C:/courses/cis160/game/"
  href="runner.jnlp">
  <information>
    <title>Student Runner game</title>
    <vendor>Edward Parrish</vendor>
    <homepage href="."/>
    <description>Student runner game</description>
    <description kind="short">
      A demo of the Student Runner game.
    </description>
    <icon href="icon.gif"/>
    <icon kind="splash" href="splash.gif"/>
    <offline-allowed/>
  </information>
  <security>
      <!-- get all permissions so we can access
      fullscreen exclusive mode -->
      <all-permissions/>
  </security>
  <resources>
    <j2se version="1.5+" initial-heap-size="32m"/>
    <jar href="runner.jar"/>
  </resources>
  <application-desc main-class="RunnerFullScreen"/>
</jnlp>

Setting Up the Web Server

  • You end up with the following files to place on the web server:
    • JNLP file (runner.jnlp)
    • One or more digitally signed JAR files (runner.jar)
    • Icon file (icon.gif)
    • Splash screen file (splash.gif)
  • You need to make sure the codebase in the JNLP matches the URL on the server
  • In addition, you need a web page linking to the file: index.html
  • Once the files are installed, you still need to associate the JNLP files with the correct MIME type:
    • application/x-java-jnlp-file
  • This is required so that JWS can load the file instead of the web browser
  • If you are running your own web server, you probably know what to do
    • If not, you should the course CIS-164: Introduction to Managing and Securing a Web Server
  • If you have a shared hosting service, then check the documentation for adding MIME types or ask the web master to add it for you
  • If you cannot add the association in this way, then there is another solution for Apache web servers
  • You can place a file named .htaccess in the top directory of your web site that contains the line:
    • AddType application/x-java-jnlp-file .jnlp
  • It can be confusing to tell whether what you have changed is working
    • For instance, the browser usually puts the MIME response in cache
    • Thus you may need to clear the cache or restart the browser
    • An easier way is to run this program instead: GetContentType.java
  • You can enhance the Java Web Start in many other ways
  • For example, you can add JavaScript code to the web page to detect whether JWS is installed
  • Another example is to offer a one-click install of the Java runtime on Windows machines
  • How to do this is explained in the Creating the Web Page That Launches the Application which is part of the Java Web Start Guide

More Information

^ top

14.2.6: Summary

  • When you deploy your game, you want to make it as easy as possible for people to download and install it
  • Java has a number of ways to deploy games, including many that are designed for deployment over the web
  • We looked at the following techniques:
    • Java Applets
    • Executable JAR files
    • Application installers
    • Java Web Start

^ top

14.3: Open Lab

Objectives

At the end of the lesson the student will be able to:

  • Advance the state of their game project
  • At the end of the lecture, I will help students who want help on their game

^ top

Wrap Up

    Reminders

    Due Next Class: Final Project (6/2/06)

  • When class is over, please shut down your computer

^ top

Home | WebCT | Announcements | Schedule | Expectations | Course info
Help | FAQ's | HowTo's | Links

Last Updated: May 25 2006 @14:33:01