Welcome to the wonderful world of game and entertainment application development in Java! The Gamelet Toolkit was written to make it easy enough for beginner programmers to look like professionals yet make it powerful for expert programmers to reduce development time.

If you are new to game development, have no fear. Developing fast action games and entertaiment applications is easy. You won't have to spend hours reading a game programming book just to figure out how sprite animation or collision detection works. Read through this document and look through the example source code provided. And don't be afraid to borrow source code from the examples to get you started.

For those seasoned pros, you'll see the advantage of using a Java toolkit. Many months have been spent on architecting, developing, and optimizing the Gamelet Toolkit. Source code is also included for your browsing pleasure.

The main thing that you'll realize is that developing with the Gamelet Toolkit is simple and will reduce the amount of time it takes to develop cool Java games and entertainment applications. Once you get the hang of it, you can write simple games in a weekend. There are many companies on the internet today that deploy moderate sized games in a week!




The Gamelet Toolkit treats all animating objects such as ships, bullets, obstacles, etc. as Actor objects. Actors are simple objects that are responsible for displaying themselves and managing their own state.

Actors have attributes that aid them in animating themselves. Animation attributes include position, velocity, and frame rate. Other imaging attributes include the current display layer the Actor is in and whether the Actor should wrap when it goes offscreen.

Support also exists for automatically timed destruction of Actors, whether or not the Actor can collide with multiple Actors on a single tick cycle, and AnimationPaths the Actor follows.




When Actors are created, they should be assigned to an ActorManager which is responsible for maintaining a list of all Actors for a given Scene. The ActorManager sends a tick to each Actor for each Gamelet run-time cycle. It also performs collision detection and notifies Actors when they have collided.

All the frames for a given animation are stored within a single image. This was chosen to reduce the overhead of loading each image across the network individually while at the same time gives the developer a convenient means to display and handle the frames during development.

Frames can be stored in any array of size nXm. Frames are numbered starting from the upper left hand corner, to coincide with Java's origin.

Default behaviour is to cycle through the animation frames beginning at frame zero continuing to the maximum number of frames and looping back to zero. This behaviour can be modified by overriding the calculateCurrentFrame method and controlling the instance variable currentFrame.

Actors can have specific frame rates that they cycle through. This can be set via the secondsPerFrame instance variable, or through the setFramesPerSecond(double) convenience method. This should be considered as a cap if you are trying to slow down the frame rate of a particular Actor. If no frame rate is specified, animation will attempt to cycle through as quickly as possible.

Actors can also be told to follow a predefined path by setting the AnimationPath for a given Actor. The AnimationPath defines a set of end points for linear movement, or Bezier control points for a curved path. Once the Actor reaches the end of its AnimationPath, it can either loop back to the starting point on the AnimationPath, reverse its direction, stop, or expire.

The Gamelet Toolkit was designed to incorporate highly optimized display management; this is necessary for quick action arcade style games. DisplayManager handles this with selective double buffering.

Two offscreen caches are used, one is a read only representation of a `clean' background, the other is the working copy used to build the current frame. Actors are drawn on this working copy and then copied to the display. The extra step of copying to a working copy allows the DisplayManager to coalesce images when they are close so as to reduce the number of copy actions to the screen. It also solves the problem of cleaning up the last frame displayed.

ScoreManager maintains the current score and provides access methods for objects to access and update the score. It also allows objects to register for notification when a specific point level has been reached. This is useful for rewarding the player with a bonus.

A scene may be used to segment a game into parts where the functionality of a game changes significantly enough to warrant a new set of Actors and a new ActorManager. This is useful for arcade games that have an intermission animation sequence, or separate game levels.

Scenes are also useful for displaying multiple views at the same time. This can be used with games where different perspectives are visible at the same time, as in a tank game with left, front, and right views. Or where the actors within the Scenes are independent of the other Scene's actors.

All gamelets operate within the context of a Scene. Even simple gamelets like those which don't require multiple views or stages contain a main Scene (see the Boink example). When gamelets require more complexity, Scenes allow for the developer to segment the game into independent sections.