API Docs for: 0.2.0
Show:

Quintus Class

Defined in: lib/quintus.js:28
Module: Quintus

Top-level Quintus engine factory wrapper, creates new instances of the engine by calling:

 var Q = Quintus({  ...  });

Any initial setup methods also all return the Q object, allowing any initial setup calls to be chained together.

 var Q = Quintus()
         .include("Input, Sprites, Scenes")
         .setup('quintus', { maximize: true })
         .controls();

Q is used internally as the object name, and is used in most of the examples, but multiple instances of the engine on the same page can have different names.

var Game1 = Quintus(), Game2 = Quintus();

Methods

_removeExtension

(
  • filename
)
String

Defined in lib/quintus.js:1718

Helper method to return a name without an extension

Parameters:

  • filename String

Returns:

String:

filename without an extension

asset

(
  • name
)

Defined in lib/quintus.js:1733

Getter method to return an asset by its name.

Asset names default to their filenames, but can be overridden by passing a hash to load to set different names.

Parameters:

  • name String
    • name of asset to lookup

Q

()

Defined in lib/quintus.js:51

A la jQuery - the returned Q object is actually a method that calls Q.select. Q.select doesn't do anything initially, but can be overridden by a module to allow selection of game objects. The Scenes module adds in the select method which selects from the default stage.

var Q = Quintus().include("Sprites, Scenes");
... Game Code ...
// Set the angry property on all Enemy1 class objects to true
Q("Enemy1").p({ angry: true });

Q._clone

(
  • obj
)
Object

Defined in lib/quintus.js:154

Return a shallow copy of an object. Sub-objects (and sub-arrays) are not cloned. (uses extend internally)

Parameters:

  • obj Object
    • object to clone

Returns:

Object:

cloned object

Q._defaults

(
  • dest
  • source
)
Object

Defined in lib/quintus.js:166

Method that adds default properties onto an object only if the key on dest is undefined

Parameters:

  • dest Object
    • destination object
  • source Object
    • source object

Returns:

Object:

returns the dest object

Q._defaults

(
  • object
  • key
)
Boolean

Defined in lib/quintus.js:185

Shortcut for hasOwnProperty

Parameters:

  • object Object
    • destination object
  • key String
    • key to check for

Returns:

Boolean:

Q._detect

(
  • obj
  • iterator
  • context
)
Array

Defined in lib/quintus.js:364

Returns a new Array with entries set to the return value of the iterator.

Parameters:

  • obj Array or Object
  • iterator Function
  • context Object

Returns:

Array:

Q._detect

(
  • obj
  • iterator
  • context
  • [arg1]
  • [arg2]
)
Var

Defined in lib/quintus.js:333

Basic detection method, returns the first instance where the iterator returns truthy.

Parameters:

  • obj Array or Object
  • iterator Function
  • context Object
  • [arg1] Var optional
  • [arg2] Var optional

Returns:

Var:

first truthy value

Q._each

(
  • obj
  • {Function
)

Defined in lib/quintus.js:287

Basic iteration method. This can often be a performance handicap when the callback iterator is created inline, as this leads to lots of functions that need to be GC'd. Better is to define the iterator as a private method so. Uses the built in forEach method

Parameters:

  • obj Array or Object
  • {Function Object

    iterator function, this is used for each object

Q._extend

(
  • dest
  • source
)
Object

Defined in lib/quintus.js:137

Extends a destination object with a source object (modifies destination object)

Parameters:

  • dest Object
    • destination object
  • source Object
    • source object

Returns:

Object:

returns the dest object

Q._fileExtension

(
  • filename
)
String

Defined in lib/quintus.js:1503

Return the file extension of a filename

Parameters:

  • filename String

Returns:

String:

lowercased extension

Q._invoke

(
  • arr
  • property
  • [arg1]
  • [arg2]
)

Defined in lib/quintus.js:314

Invoke the named property on each element of the array

Parameters:

  • arr Array
  • property String
    • property to invoke
  • [arg1] Var optional
  • [arg2] Var optional

Q._isArray

(
  • obj
)
Boolean

Defined in lib/quintus.js:248

Check if something is an Array

Parameters:

  • obj Var
    • object to check

Returns:

Boolean:

Q._isFunction

(
  • obj
)
Boolean

Defined in lib/quintus.js:224

Check if something is a function

Parameters:

  • obj Var
    • object to check

Returns:

Boolean:

Q._isNumber

(
  • obj
)
Boolean

Defined in lib/quintus.js:212

Check if something is a number

Parameters:

  • obj Var
    • object to check

Returns:

Boolean:

Q._isObject

(
  • obj
)
Boolean

Defined in lib/quintus.js:236

Check if something is an Object

Parameters:

  • obj Var
    • object to check

Returns:

Boolean:

Q._isString

(
  • obj
)
Boolean

Defined in lib/quintus.js:198

Check if something is a string

NOTE: this fails for non-primitives

Parameters:

  • obj Var
    • object to check

Returns:

Boolean:

Q._isUndefined

(
  • obj
)
Boolean

Defined in lib/quintus.js:260

Check if something is undefined

Parameters:

  • obj Var
    • object to check

Returns:

Boolean:

Q._keys

(
  • obj
)
Array

Defined in lib/quintus.js:427

Return an object's keys as a new Array

Parameters:

  • obj Object

Returns:

Array:

Q._normalizeArg

(
  • arg
)
Array

Defined in lib/quintus.js:101

An internal utility method (utility methods are prefixed with underscores) It's used to take a string of comma separated names and turn it into an Array of names. If an array of names is passed in, it's left as is. Example usage:

Q._normalizeArg("Sprites, Scenes, Physics   ");
// returns [ "Sprites", "Scenes", "Physics" ]

Used by Q.include and Q.Sprite.add to add modules and components, respectively.

Most of these utility methods are a subset of Underscore.js, Most are pulled directly from underscore and some are occasionally optimized for speed and memory usage in lieu of flexibility.

Underscore.js is (c) 2009-2012 Jeremy Ashkenas, DocumentCloud Inc.

Underscore is freely distributable under the MIT license.

http://underscorejs.org

Parameters:

  • arg String or Array
    • Either a comma separated string or an array

Returns:

Array:

array of normalized names

Q._popProperty

(
  • obj
  • property
)
Var

Defined in lib/quintus.js:272

Removes a property from an object and returns it if it exists

Parameters:

  • obj Object
  • property String
    • property to pop off the object

Returns:

Var:

popped property

Q._range

(
  • start
  • stop
  • [step]
)
Array

Defined in lib/quintus.js:443

Return an array in the range from start to stop

Parameters:

  • start Integer
  • stop Integer
  • [step] Integer optional

Returns:

Array:

Q._shuffle

(
  • arr
)
Array

Defined in lib/quintus.js:408

Returns a new array with the same entries as the source but in a random order.

Parameters:

  • arr Array

Returns:

Array:

copy or arr in shuffled order

Q._uniq

(
  • arr
)
Array

Defined in lib/quintus.js:385

Returns a sorted copy of unique array elements with null removed

Parameters:

  • arr Array

Returns:

Array:

uniq'd sorted copy of array

Q._uniqueId

() Integer

Defined in lib/quintus.js:470

Return a new unique identifier

Returns:

Integer:

Q.assetType

(
  • asset
)

Defined in lib/quintus.js:1517

Determine the type of asset based on the Q.assetTypes lookup table

Parameters:

  • asset String

Q.assetUrl

(
  • base
  • url
)
String

Defined in lib/quintus.js:1539

Either return an absolute URL, or add a base to a relative URL

Parameters:

  • base String
    • base for relative paths
  • url String
    • url to resolve to asset url

Returns:

String:

resolved url

Q.clear

()

Defined in lib/quintus.js:1410

Clear the canvas completely.

If you want it cleared to a specific color - set Q.clearColor to that color

Q.component

(
  • name
  • metehods
)

Defined in lib/quintus.js:1127

Registers a component with the engine, making it available to Q.GameObject's This creates a new descendent class of Q.Component with new methods added in.

Parameters:

  • name String
    • component name
  • metehods Object
    • hash of methods for the component

Q.gameLoop

(
  • callback
)

Defined in lib/quintus.js:526

Game Loop support

By default the engine doesn't start a game loop until you actually tell it to. Usually the loop is started the first time you call Q.stageScene, but if you aren't using the Scenes module you can explicitly start the game loop yourself and control exactly what the engine does each cycle. For example:

var Q = Quintus().setup();

var ball = new Q.Sprite({ .. });

Q.gameLoop(function(dt) {
  Q.clear(); 
  ball.step(dt);
  ball.draw(Q.ctx);
});

The callback will be called with fraction of a second that has elapsed since the last call to the loop method.

Parameters:

  • callback Function

Q.imageData

(
  • img
)

Defined in lib/quintus.js:1435

Return canvas image data given an Image object.

Parameters:

  • img Image
    • image to get image datda for

Q.include

(
  • mod
)
Quintus

Defined in lib/quintus.js:78

Default no-op select method. Replaced with the Quintus.Scene class

Syntax for including other modules into quintus, can accept a comma-separated list of strings, an array of strings, or an array of actual objects. Example:

Q.include("Input, Sprites, Scenes")

Parameters:

  • mod String
    • A comma separated list of module names

Returns:

Quintus:

returns Quintus instance for chaining.

Q.load

(
  • assets
  • callback
  • options
)

Defined in lib/quintus.js:1747

Load assets, and call our callback when done.

Also optionally takes a progressCallback which will be called with the number of assets loaded and the total number of assets to allow showing of a progress.

Assets can be passed in as an array of file names, and Quintus will use the file names as the name for reference, or as a hash of { name: filename }.

Example usage: Q.load(['sprites.png','sprites.,json'],function() { Q.stageScene("level1"); // or something to start the game. });

Parameters:

  • assets String, Array or Array
    • comma separated string, array or Object hash of assets to load
  • callback Function
    • called when done loading
  • options Object

Q.loadAssetAudio

(
  • key
  • src
  • callback
  • errorCallback
)

Defined in lib/quintus.js:1603

Loader for Audio assets. By default chops off the extension and will automatically determine which of the supported types is playable by the browser and load that type.

Which types are available are determined by the file extensions listed in the Quintus options.audioSupported

Parameters:

  • key String
  • src String
  • callback Function
  • errorCallback Function

Q.loadAssetImage

(
  • key
  • src
  • callback
  • errorCallback
)

Defined in lib/quintus.js:1560

Loader for Images, creates a new Image object and uses the load callback to determine the image has been loaded

Parameters:

  • key String
  • src String
  • callback Function
  • errorCallback Function

Q.loadAssetOther

(
  • key
  • src
  • callback
  • errorCallback
)

Defined in lib/quintus.js:1682

Loader for other file types, just stores the data returned from an Ajax call.

Just makes a Ajax request for all other file types

Parameters:

  • key String
  • src String
  • callback Function
  • errorCallback Function

Q.loadAssetWebAudio

(
  • key
  • src
  • callback
  • errorCallback
)

Defined in lib/quintus.js:1652

Asset loader for Audio files if using the WebAudio API engine

Parameters:

  • key String
  • src String
  • callback Function
  • errorCallback Function

Q.pauseGame

()

Defined in lib/quintus.js:593

Unpause the game by restarting the requestAnimationFrame-based loop. Pause the entire game by canceling the requestAnimationFrame call. If you use setTimeout or setInterval in your game, those will, of course, keep on rolling...

Q.pauseGame

()

Defined in lib/quintus.js:579

Pause the entire game by canceling the requestAnimationFrame call. If you use setTimeout or setInterval in your game, those will, of course, keep on rolling...

Q.preload

(
  • arg
  • [options]
)

Defined in lib/quintus.js:1864

Let us gather assets to load at a later time, and then preload them all at the same time with a single callback. Options are passed through to the Q.load method if used.

Example usage: Q.preload("sprites.png"); ... Q.preload("sprites.json"); ...

 Q.preload(function() {
    Q.stageScene("level1"); // or something to start the game
 });

Parameters:

  • arg String or Function
    • comma separated string of assets to load, or callback
  • [options] Object optional
    • options to pass to load

Q.reset

()

Defined in lib/quintus.js:1256

Reset the global game state

Q.select

()

Defined in lib/quintus.js:70

Default no-op select method. Replaced with the Quintus.Scene class

Q.setup

(
  • [id="quintus"]
  • [options]
)

Defined in lib/quintus.js:1269

Canvas Methods

The setup and clear method are the only two canvas-specific methods in the core of Quintus. imageData also uses canvas but it can be used in any type of game.

Setup will either create a new canvas element and append it to the body of the document or use an existing one. It will then pull out the width and height of the canvas for engine use. It also adds a wrapper container around the element. If the maximize is set to true, the canvas element is maximized on the page and the scroll trick is used to try to get the address bar away. The engine will also resample the game to CSS dimensions at twice pixel dimensions if the resampleWidth or resampleHeight options are set. TODO: add support for auto-resize w/ engine event notifications

Available options:

   {
    width: 320,  // width of created canvas
    height: 420, // height of created canvas
    maximize: false // set to true to maximize to screen, "touch" to maximize on touch devices
   }

Parameters:

  • [id="quintus"] String optional
    • id of the canvas element to trigger quintus on
  • [options] Object optional
    • options hash

Properties

Q.assetTypes

Object

Defined in lib/quintus.js:1455

Asset Loading Support

The engine supports loading assets of different types using load or preload. Assets are stored by their name so the same asset won't be loaded twice if it already exists.

Augmentable list of asset types, loads a specific asset type if the file type matches, otherwise defaults to a Ajax load of the data.

You can new types of assets based on file extension by adding to assetTypes and adding a method called loadAssetTYPENAME where TYPENAME is the name of the type you added in.

Default bindings are:

  • png, jpg, gif, jpeg -> Image
  • ogg, wav, m4a, mp3 -> Audio
  • Everything else -> Data

To add a new file extension in to an existing type you can just add it to asset types:

Q.assetTypes['bmp'] = "Image";

To add in a new loader, you'll need to define a method for that type and add to the Q.assetTypes object, e.g.:

Q.loadAssetVideo = function(key,src,callback,errorCallback) {
   var vid = new Video();
   vid.addEventListener("canplaythrough",function() {  callback(key,vid); });
   vid.onerror = errorCallback;
   vid.src = Q.assetUrl(Q.options.imagePath,src);
};

Q.assetTypes['mp4'] = 'Video'

Q.components

Object

Defined in lib/quintus.js:933

The master list of registered components, indexed in an object by name.

Q.options

Object

Defined in lib/quintus.js:483

Options

Default engine options defining the paths where images, audio and other data files should be found relative to the base HTML file. As well as a couple of other options.

These can be overriden by passing in options to the Quintus() factory method, for example:

// Override the imagePath to default to /assets/images/
var Q = Quintus({ imagePath: "/assets/images/" });

If you follow the default convention from the examples, however, you should be able to call Quintus() without any options.

Default Options

{
 imagePath: "images/",
 audioPath: "audio/",
 dataPath:  "data/",
 audioSupported: [ 'mp3','ogg' ],
 sound: true,
 frameTimeLimit: 100
}

Q.state

Q.GameState

Defined in lib/quintus.js:1247

Top-level Q.GameState instance, generally used for global state in the game