API

You will find here a description of all the functions and objects offerd by gameQuery.

Functions and Objects

$.gQ.Animation

gameQuery allows you to declare animations. Animations are made of one image with a succession of frames just like in a css sprite. An animation in itself doesn’t exist until it’s associated with a sprite. Those are the attributes an animation can have:

  • imageURL: the URL of the image
  • numberOfFrame: the total number of frame in the animation (for example for a 10×10 sprite with 15 frames your image will be 10×150 or 150×10)
  • delta: the width or height (depending on the type) of one frame
  • rate: the number of milliseconds between two frame
  • type:the type of animation, it’s a binary OR of the following value:
    • $.gQ.ANIMATION_VERTICAL for vertical, the various frames are stacked verticaly
    • $.gQ.ANIMATION_HORIZONTAL for horizontal, the various frames are layed horizontaly
    • $.gQ.ANIMATION_ONCE if you don’t want the animation to loop
    • $.gQ.ANIMATION_CALLBACK a function executed at the end of each animation cycle
    • $.gQ.ANIMATION_MULTI if your image file contain more than one animation side by side
    • $.gQ.ANIMATION_PINGPONG after the last frame, instead of starting again with the first one the animation will reverse.
  • distance: the distance between two image when using multi-animations
  • offsetx: the offset along the x-axis for the position of the first frame in the image (for use with sprite-sheets)
  • offsety: the offset along the y-axis for the position of the first frame in the image (for use with sprite-sheets)

example:

var myAnimation = new $.gQ.Animation({ imageURL: “./myAnimation.png”, numberOfFrame: 10, delta: 60, rate: 90, type: $.gQ.ANIMATION_VERTICAL | $.gQ.ANIMATION_ONCE});

CSS Classes

The CSS classes and ids used by gameQuery are now namespaced with gQ_to avoid interferences with classes set by your game or other plug-ins. You can access them through a constant in the gameQuery object so that should they change for some reason you won’t have the change the code of your game. Most of the time you will use them only when you write a filter for the collision() function.

  • $.gQ.spriteCssClass the CSS class associated with every sprites (replaces sprite)
  • $.gQ.groupCssClass the CSS class associated with every groups (replaces group)
  • $.gQ.tilemapCssClass the CSS class associated with every tile-maps (replaces tileSet)
  • $.gQ.tileCssClass the CSS class associated with every tiles (sort of replaces active)
  • $.gQ.tileTypePrefix the prefix of the CSS class used to make the type of each tiles. A tile with the animation number 3 will have the class $.gameQuery.tileTypePrefix + 3 (replaces tileType_)
  • $.gQ.tileIdPrefix the prefix of the id for each tiles. A tile a the 4th line and 7th column in the tile-map array will have the id $.gameQuery.tileIdPrefix + 4 + “_” + 7 (replaces tile_)

playground(options)

This function defines the div to be used to display the game. All the objects to be added to the DOM by gameQuery will be added to this element or on of its child. If more than one element results from the expression only the first will be used.

Options may contain:

  • height: the height of the game area (320 by default)
  • width: the width of the game area (480 by default)
  • refreshRate: the refresh rate in milliseconds(30 by default)
  • keyTracker: if true enabled the key tracker
  • mouseTracker: if true enabled the mouse tracker

If the key tracker is enabled you can check at anymoment the state of every key by looking into the array $.gQ.keyTracker, the indexes of this arrays are keycodes. If the mouse tracker is enabled you can check the state of the mouse at anytime by looking into the object $.gQ.mouseTracker where x and y contain the position of the mouse and 1, 2 and 3 a boolean value where true means that the first, second or thrid button is pressed

example:

$(“#someId”).playground({refreshRate: 60});

playground()

Called without any parameters the playground function returns the current playground.

startGame(function)

This function will prepare the game to be started by pre-loading the resources and will start the main loop. If a function is given as a parameter it will be called once everything is loaded.

example:

$(“#startbutton”).click(function(){ $.playground().startGame(function(){ $(“#welcomeScreen”).remove(); }); })

pauseGame()

This function pauses the game. Animations are stopped, all elements (sprites, groups and tile-maps) are hidden and callbacks WON’T be called anymore.

resumeGame(function)

This function resumes the game. Animations stats again, all elements are made visible again and callbacks start firing again. If any new animations or sound have been added they will be loaded and once done the function callback passed as argument will be called. If a loading callback has been defined at some point it will be called during the loading of the new element. Please note that you have to call this function outside one of gameQuery’s defined callbacks since they won’t be executed during a paused game, in a event handler for example.

registerCallback(function, rate)

This function registers a function to be called at a regular interval. The rate is the number of milliseconds between two successive calls to the function given as argument.

If the function passed as an argument returns a integer it will change the interval to which to function is called. If the function returns the boolean ‘true’ then the callback will not be called anymore.

$.playground().registerCallback(function(){ /* do something here */ },30)

addSprite(name, options)

This function adds a sprite to the current selected element. This element is expected to be the playground, a group or another sprite. Any sprite created this way will automatically animate itself. The sprite will stay hidden as long as the start() function hasn’t been called.

Options may include:

  • animation: an animation
  • height: the height of the sprite (32 by default)
  • width: the width of the sprite (32 by default)
  • posx: the position on the x axis (0 by default)
  • posy: the position on the y axis(0 by default)
  • callback: a callback that will be called at the end of the animation. (Only if the animation type is $.gQ.CALLBACK)

example:

$(“#playground”).playground({height: playgroundHeight, width: playgroundWidth}) .addSprite(“sprite1″,{animation: animation1});

addGroup(name, options)

This function behaves almost in the same way as the addSprite one but it creates a transparent sprite.

Options may include:

  • overflow: visibility of elements outside of the group (visible by default)
  • height: the height of the group (32 by default)
  • width: the width of the group (32 by default)
  • posx: the position on the x axis (0 by default)
  • posy: the position on the y axis(0 by default)

example:

$(“#playground”).playground({height: playgroundHeight, width: playgroundWidth}) .addGroup(“group1″,{overflow: “visible”}) .addSprite(“sprite1″,{animation: animation1}) .addSprite(“sprite2″,{animation: animation1});

addTilemap(name, tileDescription, animationList, options)

This function creates a tilemap using the animations from animationList and arranging them according to the tileDescription. animationList can be an array of animation or a multi-animation. tileDescription can be an array of integer where the value of each point is the index of the animation in the animationList (or the multi-animaiton index) or a function taking as parameter a x and y index and returning the index of the animation for this point. Tiles created by this method are marked by the “tileType_x” class where x is the animation index (this may be useful for colision). Remark: this doesn’t work if the tilemap is transformed (rotation or scalling)

Options may include:

  • sizex: the number of column of tiles
  • sizey: the number of row of tiles
  • height: the height of a unique tile
  • width: the width of a unique tile
  • posx: the position on the x axis (0 by default)
  • posy: the position on the y axis(0 by default)
  • buffer: the size of the buffer (1 by default)

The buffer option defines the number of tiles around the visible ones that are created in advance. If you find that moving tiles around is to slow you may want to play with this value . One possible scenario is when you have a player jumping around, if you now that it will move up a little and them down the same amount most of the time you may want to make sure that the buffer is big enough so that the top most point of the jump doesn’t forces the tile-map to create new tiles. Keep in mind that the bigger the buffer the slower it is to add new tiles (because the buffer has to be re-created to)

example:

var multiAnimation = new $.gQ.Animation({imageURL: “m.png”, type: $.gQ.ANIMATION_HORIZONTAL | $.gQ.ANIMATION_MULTI, numberOfFrame: 3, delta: 10, distance: 10, rate: 300}); $.playground().addTilemap(“myTilemap”, tileDef, multiAnimation, {width: 10, height: 10, sizex: 3, sizey: 3, posx: 0});

importTilemaps(url, prefix, generatedElements)

This function imports a JSON file generated by Tiled. All the created tilemaps will be directly under the currently selected element. Their name will be made of the provided prefix followed by a number starting at 0.

Only layer of type “tilelayer” are supported for now. Only one single tileset per layer is supported.

After the call to this function the second argument will hold two new arrays:

  • tiles: an arrays of tilemaps wraped in jQuery.
  • animations: an arrays of animations

setAnimation(animation, callback)

This function allow to change the animation of the element on which it’s called. This element is expected to be a sprite. Callback is a function to call at the end of each animation cycle. It’s an optional parameter that will only be used if the animation is of type $.gQ.CALLBACK. Called whitout any parameter this function remove the animation from the selected sprite.

If the currently assigned animation is a mutli-animations the animation argument can be the index of the animation you want to choose amongst one of the multi-animations.

pauseAnimation()

Stops the animation of the selected element at the current frame. If the animation has one frame or is already paused this has not effect.

resumeAnimation()

Resume the animation of the selected element if it was paused. If the animation has not been paused this has no effect.

clearScenegraph()

Will clear all sprites, groups and tile-maps. Please make sure that after a call to this your callbacks don’t try to access to them. It is recommended to call this function when the game is paused with pauseGame().

clearAll(callbacksToo)

Will clear all sprites, groups and tile-maps but animations and sounds too. If you passe true as an argument all callbacks will be removed too. It is recommended to call this function when the game is paused with pauseGame().

xyz(x, y, z, relative)

Sets the coordinates of the sprite/group/tilemap. If relative is set to true then the arguments are increments to the current position. If called without arguments, the function will return an object {x: x-coordinate, y: y-coordinate, z: z-coordinate}.

xy(x, y, relative)

Sets the coordinates of the sprite/group/tilemap. If relative is set to true then the arguments are increments to the current position. If called without arguments, the function will return an object {x: x-coordinate, y: y-coordinate, z: z-coordinate}. The z value is present in the return object because it comes at no cost.

x(value, relative)

Sets the x-coordinates of the sprite/group/tilemap. If relative is set to true then the arguments are increments to the current position. If called without arguments, the function will return the value of the x-coordinate. (The x-coordinate corresponds to the CSS “left” property)

y(value, relative)

Sets the y-coordinates of the sprite/group/tilemap. If relative is set to true then the arguments are increments to the current position. If called without arguments, the function will return the value of the y-coordinate. (The x-coordinate corresponds to the CSS “top” property)

z(value, relative)

Sets the z-coordinates of the sprite/group/tilemap. If relative is set to true then the arguments are increments to the current position. If called without arguments, the function will return the value of the z-coordinate. (The x-coordinate corresponds to the CSS “z-index” property)

wh(w, h, relative)

Sets the width and height of the sprite/group/tilemap. If relative is set to true then the arguments are increments to the current dimensions. If called without arguments, the function will return an object {w: width, h: height}.

w(value, relative)

Sets the width of the sprite/group/tilemap. If relative is set to true then the arguments are increments to the current dimensions. If called without arguments, the function will return the width.

h(value, relative)

Sets the height of the sprite/group/tilemap. If relative is set to true then the arguments are increments to the current dimensions. If called without arguments, the function will return the height.

collision(filter, override)

This method returns the list of elements collisioning with the selected one but only those that match with the filter given as parameter. It takes two optional arguments (their order is not important). The filter is a string filtering element used to detect collision, it should contain all the elements the function should search collision into. For example if you look for collision with element of the class ‘foo’ that may be contained in a group you will use the filter ".group,.foo".

You may want watch the following video tutorial I did to explain how this all works or read the following discussion on the forum. The override is an object containing one or more of the following properties: x and y to override the element position, w and h to override the width and height.

example:

$(“#spaceship”).collision(“.missiles”).each(function(){ killspaceship(); explodemissil(this); });

loadCallback(callback)

This function sets a callback to be called with the current loading progress (in percent) as argument.

addSound(sound, add) warning You need to include a sound wrapper for this function to work

This function adds the sound to the current object. If a sound is already associated with this object it will be replaced unless the add argument is set to true. In this case both sounds will be associated with the object.

playSound() warning You need to include a sound wrapper for this function to work

This function plays the sound or sounds associated with the current object.

stopSound() warning You need to include a sound wrapper for this function to work

This function stops the sound or sounds associated with the current object.

pauseSound() warning You need to include a sound wrapper for this function to work

This function pauses the sound or sounds associated with the current object.

muteSound(mute) warning You need to include a sound wrapper for this function to work

This function mutes the sound or sounds associated with the current object or mute all sounds if no obect is selected. If you pass false to the function it unmutes instead of mutes.

roate(angle, relative) warning Supported browser: firefox > 3.5, safari > 3.1, chrome, internet explorer > 5.5

This function rotates the selected element(s) clock-wise. The first argument is an angle degree. The second argument is a flag that define if the rotation is relative or not (false by default). If sets to true the first argument is added to the current rotation.

scale(ratio, relative) warning Supported browser: firefox > 3.5, safari > 3.1, chrome, internet explorer > 5.5

This function change the scale of the selected element(s). The first argument is a ratio: 1.0 = original size, 0.5 = half the original size, 2.0 = twice the original size. The second argument is a flag that define if the scaling is relative or not (false by default). If sets to true the current scaling is multiplied by the provided value (and not added like for the other transformation).

flipv(value)

This function flips the sprite vertically if the argument is true or if no argument is specified and the sprite is currently not flipped vertically. Otherwise it will return the sprite to it’s normal state.

fliph(value)

This function flips the sprite horizontally if the argument is true or if no argument is specified and the sprite is currently not flipped horizontally. Otherwise it will return the sprite to it’s normal state.

Fork me on GitHub