Namespace gbox
Gamebox module allows multiple grouped objects to move simultaneously, it helps with collisions, rendering and moving objects. It also provides monospaced pixel-font rendering, keyboard handling, audio, double buffering and eventually FSEs. Gamebox can also store and load data from cookies!
Defined in: gbox.js.
Method Summary
addAudio(id, filename, def)
addBundle(call)
addImage(id, filename)
Adds an image file to the loader, assigning it to an ID. If adding an image to an existing ID, it checks to see if the file you're adding is different than the one currently assigned to the ID.
addObject(data)
Creates a new game object. Generally speaking you pass a fully-defined object as the parameter (including a group, id, tileset, and so on).
addScript(call)
blit(tox, image, data)
blitImageToScreen(image)
Draws an image directly to the screen's current canvas context. Used internally in gbox.go().
canLog()
changeAudioVolume(a, vol)
changeChannelVolume(ch, a)
collides(o1, o2, t)
Calculates a box collision between two collision boxes within a given tolerance. A higher tolerance means less precise collision.
dataLoad(k, a)
Loads data from a browser cookie. Send it a key and it returns a value (if available).
dataSave(k, v, d)
Saves data to a browser cookie as a key-value pair, which can be restored later using gbox.dataLoad.
debugGetstats()
Displays basic audio, object, and performance statistics in the status bar. Automatically called each frame if the status bar is enabled.
deleteAudio(id)
deleteImage(id)
Deletes an image currently in use. Does not delete the image file, but removes it from Akihabara's image list.
getAudioMute(a)
getAudioVolume(a, vol)
getCanvasContext(id)
Gets the two-dimensional canvas context of a given canvas. The object it returns contains all the drawing functions for the canvas.
getChannelVolume(ch)
getObject(group, id)
Given a group and an id for a particular object instance, this returns the instance requested. NOTE: this does not return a copy of the object you've requested! Any modifications you make to the object returned are directly modifying the object you requested.
go()
This function is called once per frame. This is where the basic rendering and processing of groups occurs.
hitAudio(a, data)
initScreen(w, h)
Initializes the screen to a certain width and height, applies zoom attributes, populates the body of the HTML document including the canvas element, sets an initial camera, creates a '_buffer' canvas, sets keyboard event listeners, and many other initialization functions.
keyIsHold(id)
Returns true if a given key in this._keymap has been held down for at least one frame.
loadAll(cb)
Loads the initial splash screen and debugging font, then calls gbox._waitforloaded which adds to the game all the previously defined resources.
log()
objectIsTrash(o)
Returns whether an object is due to be trashed. Useful in cases you want to check if an object is marked as trash before it is actually deleted.
objectIsVisible(obj)
Determines whether an object is visible by seeing if it collides with the camera's viewport.
pixelcollides(o1, o2, t)
Calculates a point-box collision between a point and a collision box within a given tolerance. A higher tolerance means less precise collision.
playAudio(a, data)
playGroups(gid)
readBundleData(pack, call)
resetChannel(ch)
setAudioMute(a)
setAudioPosition(a, p)
setAudioTeam(a)
setAudioVolume(a, vol)
setAutoskip(f)
setCanAudio(a)
setCanLog(c)
setChannelVolume(ch, a)
setFrameskip(f)
setZindex(th, z)
stopAudio(a, permissive)
stopChannel(ch)
stopGroups(gid)
toggleGroups(gid)
Method Detail
gbox.addFont(data)
Creates a font.
gbox.addImage('font', 'font.png');
gbox.addFont({ id: 'small', image: 'font', firstletter: ' ', tileh: 8, tilew: 8, tilerow: 255, gapx: 0, gapy: 0 });
Parameters:
| {Object} | data |
An object containing:
|
gbox.addImage(id, filename)
Adds an image file to the loader, assigning it to an ID. If adding an image to an existing ID, it checks to see if the file you're
adding is different than the one currently assigned to the ID. If it's different, it overwrites the old image. If it's the same, then
no action is taken.
Parameters:
| {String} | id | The identifier of the image. |
| {String} | filename | The file name of the image. |
gbox.addObject(data)
: Object
Creates a new game object. Generally speaking you pass a fully-defined object as the parameter (including a group, id, tileset, and so on).
A group must be specified, or the program will crash. If no id is specified, then it will automatically provide
an id of 'obj-XXXX' where 'XXXX' is an automatically incrementing integer. This is where the initialize, first, and blit
functions are defined, as well.
data = {
group: 'player',
id: 'player_id',
tileset: 'player_tiles',
x: 0,
y: 0,
initialize: function() {
this.x = 10;
this.y = 10;
},
};
gbox.addObject(data);
Parameters:
| {Object} | data | The object you wish to create. |
Returns:
| {Object} | The object you created. |
gbox.addTiles(t)
Creates a new Akihabara tileset, adding it to the engine.
Parameters:
| {Object} | t |
An object containing:
|
gbox.blitAll(tox, image, data)
Draws an image to a canvas context
// draw an image at (100,100)
gbox.blitAll(gbox.getBufferContext(),gbox.getImage("image_id"),{dx:100,dy:100});
Parameters:
| {Object} | tox | The canvas context to be drawn on. |
| {Object} | image | The image to draw. Must be a DOM Image element, typicallly accessed via gbox.getImage |
| {Object} | data |
An object containing data about the tile to be drawn, including:
|
gbox.blitClear(image, data)
Clears a rectangular area of a canvas context.
Parameters:
| {Object} | image | The canvas context to be drawn on. |
| {Object} | data |
An object containing a set of data, including:
|
gbox.blitFade(tox, data)
Draws a filled rectangle over an entire canvas context.
Parameters:
| {Object} | tox | The canvas context to be filled. |
| {Object} | data |
An object containing a set of data, including:
|
gbox.blitImageToScreen(image)
Draws an image directly to the screen's current canvas context. Used internally in gbox.go(). Probably shouldn't be used otherwise.
Parameters:
| image |
gbox.blitRect(tox, data)
Draws a filled rectangle to a canvas context.
Parameters:
| {Object} | tox | The canvas context to be drawn on. |
| {Object} | data |
An object containing a set of data, including:
|
gbox.blitText(tox, data)
Draws text to a canvas context
Parameters:
| {Object} | tox | The canvas context to be drawn on. |
| {Object} | data |
An object containing a set of data, including:
|
gbox.blitTile(tox, data)
Draws a tile to a canvas context
// from capman, draws an current object's tile, called from inside its blit function
gbox.blitTile(gbox.getBufferContext(),{tileset:this.tileset,tile:this.frame,dx:this.x,dy:this.y,fliph:this.fliph,flipv:this.flipv,camera:this.camera,alpha:1});
Parameters:
| {Object} | tox | The canvas context to be drawn on. |
| {Object} | data |
An object containing data about the tile to be drawn, including:
|
gbox.blitTilemap(tox, data)
Draws a tilemap to a canvas context
Parameters:
| {Object} | tox | The canvas context to be drawn on. |
| {Object} | data |
An object containing a set of tilemap data, including:
|
gbox.centerCamera(data, viewdata)
Centers the camera.
// Center the camera on the player object
gbox.centerCamera(gbox.getObject('player', 'player_id'), {w: map.w, h: map.h});
Parameters:
| {Object} | data | An object containing x and y parameters -- typically the object you wish to center the camera on. |
| {Object} | viewdata | An object containing parameters h and w, which are a bounding box that the camera is not supposed to leave. For example, to use your map as a bounding area for the camera, pass along {w: map.w, h: map.h}. |
gbox.clearGroup(gid)
Destroys all objects in a given group.
Parameters:
| {String} | gid | The id of the group. |
gbox.collides(o1, o2, t)
Calculates a box collision between two collision boxes within a given tolerance. A higher tolerance means less precise collision.
Parameters:
| {Object} | o1 |
A collision box you're testing for collision. Must contain:
|
| {Object} | o2 |
A collision box you're testing for collision. Must contain:
|
| {Integer} | t | The tolerance for the collision, in pixels. A value of 0 means pixel-perfect box collision. A value of 2 would mean that the boxes could overlap by up to 2 pixels without being considered a collision. |
Returns:
| True if the two collision boxes are colliding within the given tolerance. |
gbox.createCanvas(id, data)
Creates a new canvas. By default, the width and height is the current gbox._screenw and gbox._screenh,
but it can also be set by passing in a data object with the appropriate parameters.
gbox.createCanvas('newCanvas', {w: 640, h: 480});
Parameters:
| {String} | id | The id of the new canvas. |
| {Object} | data | (Optional) The height and width of the new canvas, contained in data.h and data.w parameters. |
gbox.dataClear(k)
Clears a value stored in a key-value pair in a browser cookie. Sets value to "". Only works if user has cookies enabled.
Parameters:
| {String} | k | The key which identifies the value you are clearing. |
gbox.dataLoad(k, a)
: Object
Loads data from a browser cookie. Send it a key and it returns a value (if available). Only works if user has cookies enabled.
hiscore = gbox.dataLoad("hiscore");
Parameters:
| {String} | k | The key which identifies the value you are loading. |
| {String} | a | A switch to determine whether a string or a number is returned. By default a string is returned. |
Returns:
| {Object} | A string or a number loaded from the cookie. |
gbox.dataSave(k, v, d)
Saves data to a browser cookie as a key-value pair, which can be restored later using gbox.dataLoad. Only
works if user has cookies enabled.
// (from Capman)
gbox.dataSave("capman-hiscore",maingame.hud.getNumberValue("score","value"));
Parameters:
| {String} | k | The key which identifies the value you are storing. |
| {String} | v | The value you wish to store. Needs to be a string! |
| {String} | d | A date offset, to be added to the current date. Defines the cookie's expiration date. By default this is set to 10 years. |
gbox.debugGetstats()
Displays basic audio, object, and performance statistics in the status bar. Automatically called each frame if the status bar is enabled.
gbox.deleteCanvas(id)
Deletes a given canvas.
Parameters:
| {String} | id | The id of the canvas to be deleted. |
gbox.deleteImage(id)
Deletes an image currently in use. Does not delete the image file, but removes it from Akihabara's image list.
Parameters:
| {String} | id | The identifier of the image. |
gbox.getBuffer()
: Object
Gets the buffer canvas (automatically created by gbox.initScreen).
Returns:
| {Object} | A DOM Canvas element, including the width and height of the canvas. |
gbox.getBufferContext()
: Object
Gets the buffer canvas context.
Returns:
| {Object} | A DOM Canvas context object. |
gbox.getCanvas(id)
: Object
Gets a given canvas.
Parameters:
| {Object} | id | The identifier of the canvas. |
Returns:
| {Object} | A DOM Canvas element, including the width and height of the canvas. |
gbox.getCanvasContext(id)
: Object
Gets the two-dimensional canvas context of a given canvas. The object it returns contains all the drawing functions for the canvas.
See W3C and
Mozilla Developer Center for details.
Parameters:
| {Object} | id | The identifier of the canvas. |
Returns:
| {Object} | A DOM Canvas context object. |
gbox.getFlag(f)
Returns a gbox flag at index f.
Parameters:
| {Object} | f | The index of the flag you want returned. |
gbox.getFont(id)
Returns a font object containing data about the font.
Parameters:
| {String} | id | The id of the font, as set in gbox.addFont. |
gbox.getFps()
: Integer
Get the frames per second rate (default is 25).
Returns:
| {Integer} | Returns the frames per second. |
gbox.getGroups()
: Array
Get an array containing the names of each group in the game, in order of rendering.
grouplist = gbox.getGroups(); grouplist; // => ["background", "player", "enemy", "game"]
Returns:
| {Array} | An array of group names. |
gbox.getImage(id)
: Object
Gets information about a loaded image.
image = gbox.getImage('logo');
image; // => ![](?"logo.png?_brc=5-7-2010-15-48-42")
?
Parameters:
| {String} | id | The id of the image. |
Returns:
| {Object} | A DOM Image element, including the URL and last modified date of the image, its ID, and whether it was loaded successfully. |
gbox.getObject(group, id)
: Object
Given a group and an id for a particular object instance, this returns the instance requested.
NOTE: this does not return a copy of the object you've requested! Any modifications you make
to the object returned are directly modifying the object you requested.
// Find the player and reduce health by half.
playertemp = gbox.getObject('player','player_id');
player.health = player.health/2;
Parameters:
| {String} | group | The id of the group that contains the object. |
| {String} | id | The id of the instance of the object. |
Returns:
| {Object} | The object requested. |
gbox.getScreenHH()
: Integer
Get the screen half-height.
Returns:
| {Integer} | Screen half-height in pixels. |
gbox.getScreenHW()
: Integer
Get the screen half-width.
Returns:
| {Integer} | Screen half-width in pixels. |
gbox.getTiles(t)
Gets an Akihabara tileset, adding it to the engine.
Parameters:
| {String} | t | The ID of a tileset. |
Returns:
An object containing:
|
gbox.go()
This function is called once per frame. This is where the basic rendering and processing of groups occurs.
gbox.groupIsEmpty(gid)
: Boolean
Returns whether a given group contains no objets.
Parameters:
| {String} | gid | The group you're checking. |
Returns:
| {Boolean} | True if the group contains no objects. |
gbox.imageIsLoaded(id)
: Boolean
Checks to see if an image was successfully loaded.
Parameters:
| {String} | id | The id of the image. |
Returns:
| {Boolean} | True if the image has been loaded. |
gbox.initScreen(w, h)
Initializes the screen to a certain width and height, applies zoom attributes, populates the
body of the HTML document including the canvas element, sets an initial camera, creates a '_buffer'
canvas, sets keyboard event listeners, and many other initialization functions.
Parameters:
| {Integer} | w | The width of the main canvas. |
| {Integer} | h | The height of the main canvas. |
gbox.keyIsHit(id)
: Boolean
Returns true if a given key in this._keymap is pressed. Only returns true on the transition from unpressed to pressed.
Parameters:
| {String} | id | A key in the keymap. By default, one of: "up" "down" "left" "right" "a" "b" "c" |
Returns:
| {Boolean} | True if the given key is transitioning from unpressed to pressed in this frame. |
gbox.keyIsHold(id)
: Boolean
Returns true if a given key in this._keymap has been held down for at least one frame. Will not return true if a key
is quickly tapped, only once it has been held down for a frame.
Parameters:
| {String} | id | A key in the keymap. By default, one of: "up" "down" "left" "right" "a" "b" "c" |
Returns:
| {Boolean} | True if the given key has been held down for at least one frame. |
gbox.keyIsPressed(id)
: Boolean
Returns true if a given key in this._keymap is being held down. Returns true as long as the key is held down.
Parameters:
| {String} | id | A key in the keymap. By default, one of: "up" "down" "left" "right" "a" "b" "c" |
Returns:
| {Boolean} | True if the given key is held down. |
gbox.keyIsReleased(id)
: Boolean
Returns true if a given key in this._keymap is released. Only returns true on the transition from pressed to unpressed.
Parameters:
| {String} | id | A key in the keymap. By default, one of: "up" "down" "left" "right" "a" "b" "c" |
Returns:
| {Boolean} | True if the given key is transitioning from pressed to unpressed in this frame. |
gbox.loadAll(cb)
Loads the initial splash screen and debugging font, then calls gbox._waitforloaded which adds to the game all the previously
defined resources. Once gbox._waitforloaded is done, it calls the callback function cb.
Parameters:
| cb |
gbox.objectIsTrash(o)
: Boolean
Returns whether an object is due to be trashed. Useful in cases you want to check if
an object is marked as trash before it is actually deleted.
Parameters:
| {Object} | o | The object you're checking. |
Returns:
| {Boolean} | True if the object is marked as trash. |
gbox.objectIsVisible(obj)
Determines whether an object is visible by seeing if it collides with the camera's viewport.
Parameters:
| {Object} | obj |
The object you're testing to see if it's visible. Must contain:
|
Returns:
| True if the object's collision box is within the camera's viewport. |
gbox.pixelcollides(o1, o2, t)
Calculates a point-box collision between a point and a collision box within a given tolerance. A higher tolerance means less precise collision.
Parameters:
| {Object} | o1 |
A point you're testing for collision. Must contain:
|
| {Object} | o2 |
A collision box you're testing for collision. Must contain:
|
| {Integer} | t | The tolerance for the collision, in pixels. A value of 0 means pixel-perfect collision. A value of 2 would mean that the point could exist within the outermost 2 pixels of the box without being considered a collision. |
Returns:
| True if the point is colliding with the box within the given tolerance. |
gbox.playGroup(gid)
If a group is disabled, this will enable the group.
Parameters:
| {String} | gid | The id of the group. |
gbox.purgeGarbage(obj)
Clears the record held in gbox._garbage of what has been deleted.
Parameters:
| {Object} | obj | The object you wish to delete. |
gbox.setCallback(cb)
Deprecated: gbox._cb is now set by passing it directly into gbox.loadAll(). Left in for backwards compatibility.
Parameters:
| {String} | cb | The name of the function to be called once gbox.loadAll is completed. |
gbox.setCameraX(x, viewdata)
Sets the x value of the current camera object.
Parameters:
| {Integer} | x | The camera object's new x value. |
| {Object} | viewdata | An object containing parameters h and w, which are a bounding box that the camera is not supposed to leave. For example, to use your map as a bounding area for the camera, pass along {w: map.w, h: map.h}. |
gbox.setCameraY(y, viewdata)
Sets the y value of the current camera object.
Parameters:
| {Integer} | y | The camera object's new y value. |
| {Object} | viewdata | An object containing parameters h and w, which are a bounding box that the camera is not supposed to leave. For example, to use your map as a bounding area for the camera, pass along {w: map.w, h: map.h}. |
gbox.setDoubleBuffering(db)
Sets the gbox._db property. Turns on an off double buffering.
Parameters:
| {Boolean} | db | The value to write to gbox._db. True enables double buffering, false disables. |
gbox.setForcedIdle(f)
Sets the gbox._forcedidle property.
Parameters:
| {Boolean} | f | The value to write to gbox._forcedidle. |
gbox.setFps(f)
Set the frames per second rate.
Parameters:
| {Integer} | f | Total frames per second for the game to run at. |
gbox.setGroups(g)
Defines the names of each group in the game along with their rendering order.
Parameters:
| {Array} | g | An array of strings of group names, in the order in which the groups should be rendered. So g[0] will contain the first group to render, g[1] the second group to render, etc. |
gbox.setRenderOrder(g)
A method of setting the render order of groups independently of gbox.setGroups. Sets gbox._renderorder,
which by default is equivalent to gbox._groups. However, gbox._renderorder is what ultimately determines
the rendering order of groups. If you need to change your rendering order on the fly, use this function
by passing it a reordered array of group names.
Parameters:
| {Array} | g | An array of strings of group names, in the order in which the groups should be rendered. So g[0] will contain the first group to render, g[1] the second group to render, etc. |
gbox.setStatBar(txt)
Writes text to the status bar, but only if the status bar is enabled.
Parameters:
| {String} | txt | The text to write to the status bar. |
gbox.setStatusBar(f)
Sets the gbox._statbar property. Only useful if called before gbox.initScreen. Debugging funtionality.
Much easier to access if you add '?statusbar=1' to your URL.
Parameters:
| {Boolean} | f | The value to write to gbox._statbar. |
gbox.setZoom(z)
Sets the gbox._zoom parameter, only works before gbox.initScreen is called.
Parameters:
| {Integer} | z | Zoom factor. |
gbox.soloGroup(gid)
Turns off all groups except for the one specified.
Parameters:
| {String} | gid | The id of the group. |
gbox.stopGroup(gid)
If a group is enabled, this will disable the group.
Parameters:
| {String} | gid | The id of the group. |
gbox.toggleGroup(gid)
Toggles a group between enabled and disabled status.
Parameters:
| {String} | gid | The id of the group. |