Simple Game Engine Documentation

Overview

The simpleGame.js library adds game programming features to HTML5-compliant browsers. The library is designed primarily for 2D Sprite-based games, but it can be used for other game types as well. The library is designed to be easy enough for beginning game developers to use.

The library is object-oriented, and features two primary objects, the sprite and the scene. Each game is based on a scene, and all of the moving objects in the game are sprites. A scene can contain as many sprites as you wish. Each sprite is based on a standard image, so any image file you create can become a sprite for your game.

Primary features

Canvas-based The canvas tag is supported in all modern browsers, and can even be used in IE with an add-on.
Mobile-ready Games written with this library will be suitable for use on mobile devices as virtually all such devices come with HTML-5 compliant browsers.
Fast While the speed of the engine is dependent on many other factors, it is reasonably speedy with most modern machines and browsers.
Straightforward The library was designed from the beginning to be easy to teach and learn. It was designed for beginning programmers and beginning game programmers. The syntax is straightforward and consistent, and not overly complex
Feature-rich All the main components of a 2D game engine are available including collision-detection, speed and direction control, arbitrary rotation, and a basic audio system.

The basic game

A game written with the SimpleGame library is essentially a web page. You should be familiar with basic HTML and JavaScript syntax. Examine the following simple code (simpleCar.html). It provides the skeleton for all simpleGame games.

<!DOCTYPE HTML>
<html lang="en-US">
<head>
	<meta charset="UTF-8">
	<title>simpleCar.html</title>
	<script type = "text/javascript"
		src = "simpleGame.js"></script>
	<script type = "text/javascript">

	var scene;
	var car;
	
	function init(){
		scene = new Scene();
		
		car = new Sprite(scene, "car.gif", 50, 30);
		car.setSpeed(3);
		car.setAngle(0);
		car.setPosition(20, 25);

		scene.start();
	} // end init
	
	function update(){
		scene.clear();
		car.update();
	} // end update
	
	</script>
</head>
<body onload = "init()">
	<h1>Simple Car</h1>
</body>
</html>

Template code explanation

While this example is not very long, there is quite a bit happening. Here's the details:

Begin with an HTML5 page Game Engine uses HTML5 features, so begin by building an HTML5 page. Fortunately, HTML5 is quite a bit simpler than XHTML Strict, so this should not be a problem.
Include the simpleGame.js library The library is simply a text file you can download and incorporate into your pages as an external js file. For best performance, include the simplegame.js file in the same directory as your game.
Create a new script area for game code Most of your development will be done in JavaScript, so you'll need a script area to contain your coding.
Create variables for your main elements Most games will have at least two main variables: a scene (which is the game's background), and one or more sprites (the things that move around.) This example will have a single scene called "scene" and a single sprite called "car"
Create an init() function To start the game, use the standard HTML body onload mechanism to call a function called init(). This function will begin your game.
Build a Scene object The scene object is the data representation of your game and its background on the page. The game engine will automatically create a canvas element for you.
Build a sprite Sprites are the elements that move around and bonk into each other. A sprite requires four parameters: the scene, an image, width and height. You can base a sprite on any image, but by default that image should be pointing to the right.
Set the car's speed Sprites are complex objects, but they are easy to use. Each sprite has a number of things it can do, called methods. The setSpeed() method allows you to set the initial speed of the car.
Set the car's angle Like the speed, the angle of any sprite can be set easily with a method. A sprite can be pointing in a different direction than it is moving (to skid, for example) but we'll go with a simple form of motion for this example.
Start the scene Once you've set up the initial values for your sprites, you can tell the scene to begin its work. The scene (like the sprite) has methods to manage all the jobs it can do. Invoke the scene's start() method to start the game.
Add an update() function. In addition to init(), each game should have an update() function. This function will be automatically called on every frame. (typically 20 times per second.)
Clear the scene The scene has a clear() method, which erases the background. If you do not do this, the sprite will leave a trail on the screen.
Update the sprite(s) The final job of the update function is to tell each sprite to update itself. Typically you'll call the update function of every sprite.

Baby you can drive my car

So far this is a good animation, but it's not much of a game. To make a game, you need some sort of user interaction. With a few changes, it's not hard to let the user drive the car with the keyboard. Take a look at drive.html to see how it works.

Here's the code. Most of it's the same, but the update() function has been improved.

<!DOCTYPE HTML>
<html lang="en-US">
<head>
    <meta charset="UTF-8">
    <title>Drive.html</title>
    <script type = "text/javascript"
            src = "simpleGame.js"></script>
    <script type = "text/javascript">
      var scene;
      var car;
      function init(){
        scene = new Scene();
        car = new Sprite(scene, "car.gif", 50, 30);
        
        car.setSpeed(3);
        car.setAngle(0);
        scene.start();
      } // end init
      
      function update(){
        scene.clear();
        if (keysDown[K_LEFT]){
          car.changeAngleBy(-5);
        }
        if (keysDown[K_RIGHT]){
          car.changeAngleBy(5);
        }
        if (keysDown[K_UP]){
          car.changeSpeedBy(1);
        }
        if (keysDown[K_DOWN]){
          car.changeSpeedBy(-1);
        }
        car.update();
      } // end update
    </script>
</head>

<body onload = "init()">
  <title>Drive.html</title>
  <h1>A basic car you can drive</h1>
</body>
</html>

The new code isn't terribly shocking. In the update() function, you simply check to see if any keys have been pressed. SimpleGame has a large array which shows the current status of any key. You can use special constants (K_UP, K_DOWN, K_SPACE, K_A, and so on) to simplify checking for a particular key press.

If the player presses the up key, accellerate the car by using the sprite's changeSpeedBy() method. The down key works the same way, but change the car's speed by a negative value. The left and right keys are the steering control. You can change the car's direction with the changeAngleBy() method.