SimpleGame.js Documentation

Overview of SimpleGame

The simpleGame.js library was designed with a few key features in mind:

The Scene Object

The central object of the simpleGame library is the Scene. When you create a Scene object, two primary things happen: The Scene creates a canvas tag to hold all the visual aspects of the game, and it begins a timing loop that causes a function called update() to run twenty times per second.

You should create the Scene object variable as a global variable so it is available to all functions. You'll normally initialize Scene as the first line of your init() function. The Scene constructor requires no parameters. The Scene object is first described in chapter 5, with more features described throughout the book.

Primary properties of the Scene object

The Scene object has a number of interesting properties you can read directly:

Important methods of the Scene class

Like most objects, the Scene object is controlled with methods, which are used to manage the scene and change its behavior and appearance.

The Sprite Class

Scenes provide the background of a game, but the other key element in simpleGame is the Sprite class. Nearly every game element is based on the sprite, so understanding what the sprite can do is the key to writing games in simpleGame. The Sprite class is first introduced in chapter 5, and it is further described throughout the book.

The sprite class is quite large, so the various properties and methods are broken into several different categories.

The sprite constructor has a number of important parameters:

mySprite = new Sprite(scene, imageFile, width, height)

Each sprite should be created as a global variable, and the sprites should all be initialized in the init() method. You must indicate all the required parameters when creating a sprite:

Main properties of the Sprite

The sprite has a number of properties. You can read values from these properties, but it's best not to change them directly. Instead, use the appropriate method to change the behavior or appearance of a sprite. Basic sprite methods are described in chapter 5, but you'll see more advanced techniques used throughout the book, especially in chapter 8.

Appearance methods of the Sprite

Use these methods to change the appearance of the Sprite element

Movement Methods of the Sprite

One of the most important jobs of the sprite object is to move around the screen in interesting ways. At its very essence, position is stored as an (x, y) coordinate pair. You can directly set the position of the sprite, but there are many convenience methods which give you better control of sprite motion. The basic motion format is a motion vector (dx, dy.) You can set these values directly with appropriate methods, but sprites also have speed and angle attributes which can give much more interesting behavior. In fact, a sprite has two different angle measurements, the imageAngle, and the moveAngle. The imageAngle determines which direction the sprite is facing, and the moveAngle determines the direction of motion. If you simply change the angle, you are changing both the image and movement angles at once. All angles in simpleGame are measured in degrees using normal navigation formatting, with 0 degrees pointing up and 90 degrees pointing to the right.

Boundary methods of the sprite

With all this movement, it isn't surprising that sprites sometimes leave the confines of the game canvas. Most boundary-handling behavior is automatic, but you can either change the default boundary-checking mechanism, or you can add your own. Note that each sprite has a different boundary-checking behavior, so you can have more than one boundary mechanism in the same game. (bullets frequently die when they leave a screen, while spacecraft may wrap around, for example.)

Collision methods of the Sprite

The sprite has two main ways to check collisions. There is a standard collidesWith() method which checks for bounding-rectangle collisions. In addition, you can use the distanceTo() and angleTo() methods to get a better sense of the proximity of two sprites. Chapter 6 describes collision-detection in some detail.

Animation methods of the Sprite

The simpleGame library has limited support for spritesheet animations. See chapter 8 for a description of this technique. The following methods assist with Animations:

Utility Classes

In addition to the main two classes, the simpleGame library includes a number of helpful utility classes. Use these classes to add features to your game, from sound effects to mobile device interface schemes.

The Sound Object

The sound class encapsulates the HTML5 audio object, and makes it very easy to build sound effects. When you build a sound object, you'll actually be creating an HTML5 audio object which is not displayed, but can be played with JavaScript code. Note that the sound object has the same limitations as HTML5 sound elements. Most importantly, there is no single audio format guaranteed to play on every browser. For best results, create each sound effect twice (once in .mp3 and once in .ogg format) and create a Sound object for each. Use of the Sound object is described in chapter 6.

Note that the iPhone / iPad operating systems have a well-known problem playing back sound effects from JavaScript. IOS (the iPhone / iPad / iPod operating system) refuses to preload a sound, and will only load the sound effect after direct user feedback. In practice, this means you cannot load a sound in the background. However, there is a loophole. Use the sound object's showControls() method to make the HTML5 audio control panel appear for each sound. The user can then manually load each sound by playing it once. Once the sound is in memory, it will play within the game with no problems. Each time the page is reloaded, you will need to reload the sounds.

See Chapter 6 for complete details on how to use the sound object.

The Timer Object

The timer is a simple object designed to give you an easy way to work with elapsed time. It only has two methods, and they are both quite straightforward:

If you look at the source code, you'll find another method getCurrentTime() but this is only used internally, and is not likely to be useful as it is. (It returns the current time in a format that's useful for calculations, but not human-readable)

The timer is explained in chapter 6.

The Virtual Joystick

One of the most interesting features of the simplegame library is its support for mobile devices. Since these devices often do not have keyboards, they rely on alternative input methods. The virtual joystick object is used to manage touchscreen input.

The virtual Accelerometer

In addition to touch input, mobile devices also include support for motion-detection with a built-in accelerometer. The accelerometer measures rotation around all three axes, but x and y turn out to be most useful.

See chapter 9 for more information on how to use the accelerometer for motion-sensing.

The Game Button

The game button provides a convenient button which can be used in both desktop and mobile games. It is essentially a standard HTML button, but it is optimized for game programming, especially on mobile devices as an alternative to keyboard input.

Note that the label can be any valid HTML text, including plain text or an image (using the standard <img> tag. You can also use CSS to style your labels (use the standard button style) to make them semi-transparent if you prefer. You can find complete discussion of the GameButton class in chapter 9.

Keyboard array

The keyboard is a primary input mechanism for the simpleGame engine, so it's designed to be easy to use. As soon as the Scene is initialized, a special array called keysDown is created. There is an entry in this array for each of the main keys on the keyboard. Check the status of a key by using the keyboard constant as the index. The keyboard constants all begin with a capital K, followed by an underscore and the letter name. EG the A key is K_A, and B is K_B. In addition to the letter and number keys, the following keyboard constants are defined:

Note that these keys are defined for a standard US keyboard, and some behavior may be different on different keyboards.

This system (unlike standard JavaScript keyboard techniques) allows for multiple keys to be pressed at one time.

Chapter 5 describes how to read the keyboard.