javascript games made easy
Content
Description
gameQuery is a jQuery plug-in to help make javascript games easier to develop by adding some simple mechanism and commodity. It's still in a very early stage of development may change a lot in the versions to come. The project has now also a Google Code page where the svn repository of the project is hosted and a twitter page where you can follow the progress made on the development on a daily basis.
From version 0.2.0 the API should be mostly forward-compatible, i.e.: a game written for this version should run on any newer version. This means that you can start coding your games without to many risks! If you've done a game and want to show it around I will gladly host it on this page, send me a mail!
Why javascript games matter?
Javascript games are still in their infancy but but there is many reason why they are more than a curiosity: First because you can! Modern borwser provide very good javascript engine and impovement keeps comming. Then to develope javascript games you don't need an expensive proprietray IDE, widly available, free, open source software are there wating for you! Sometimes Flash is not available in some platform, even very recent ones (Wii, iPhone ...).
Why DOM instead of canvas?
Canvas is a very powerfull and efficient way to maniputale images in the browser and is thus probalby the best solution for nice looking games, however I choose DOM manipulation for gameQuery... why is that? First I think that for most practical solution ouside of games DOM is still the way to go. Since one of my goal was to learn usefull javascript using DOM made sens to me. Benchmark for pure javascript are available but aving a way to test the DOM engine is more tricky... games are a good way to test this side of the javascript performances. Finally I hope that gameQuery can be used by beginers to learn game programming and with this in mind I think it's easier to debug you games when all your object are visible with a simple DOM explorer.
Remark
I'm no javascript wizard and this is my first jQuery plugin so there may well be bad practice, bugs or worst. If you have any comments, bug to report or suggestion you're welcome to send a mail to: gamequery(at)onaluf(dot)org. You can also leave a comment the gameQuery entry of my blog.
News
1 jully 2009:
Release of version 0.3! Rotation and zoom included. A demo using all this is comming once the collision detection will be updated to work well with scaled or rotated elements.
17 february 2009:
The first tutorial is out! Read-it while it's hot :) and as allways comments are welcomed!
10 February 2009:
gameQuery 0.2.7 released.
3 February 2009:
A small teaser for the tutorial is published today, it's the game that the tutorial will help you build. Have fun here and look at the source code if you want to!
30 January 2009:
I just opened a twitter account where you will be able to follow a more day-to-day update of what's going on with the development of gameQuery.
13 Novembre 2008:
Ok, I know, I still haven't published the tutorial. But I moved to a new place and it took much more of my spare time that I would have tougth. Will do soon, I promise.
And now for something completly different: polls result. To my great suprise, at this date, 26% of you would like to see some sound support in gameQuery. So I've been looking into it. Rafael pointed me to his implementation of a sound management he used for his tetris and this gave me a great lot of clues as what I could do to make sound work in my plugin. One thing I'm still working on is a way to detect that the sound is completly loaded. So far, most plugins seam to offer this possibility but one of the remaining problem is to detect if a plugin is loading and will eventualy be ready to answer to the javascript or not. But still, some improvement in this domain should come shortly after the tutorial is published.
23 September 2008:
Many things happend since the las update. Ajaxian did an entry on gameQuery which led to a total of more than 10,000 view. To celebrate I just posted the version 0.2.5 with support for collision detection. Look at the doc and the new demo for more details on how it works. The tutorial I spoke about in the last news is on it's way, stay tuned!
You may want to take a second to answer this simple poll so that I'll know what feature you want to see in gameQuery next:
7 August 2008:
Since the 26th of June There have been more than 2,000 unique visitor for the demo! So what's to come in the next week or so? First I'll try my best to add a collision detection mechanisme as soon as possible. Then I will write a tutorial on a complete making of a small shoot'em up. I there is any features you want to see included in the next release don't hesitate to contacte me!
Download
- Download gameQuery 0.3.0 (25ko Uncompressed)
Previous versions
- Download gameQuery 0.2.7 (21ko Uncompressed)
- Download gameQuery 0.2.6 (18.4ko Uncompressed)
- Download gameQuery 0.2.5 (16.7ko Uncompressed)
- Download gameQuery 0.2.0 (Uncompressed)
- Download gameQuery 0.1.2 (Uncompressed)
- Download gameQuery 0.1.1 (Uncompressed)
- Download gameQuery 0.1 (Uncompressed)
Release notes
- 0.3.0: transformations and multi-texture added:
- feature: multi-animations, an image can now contain more than one animation side by side. You can pass from on to another by passing an integer to the setAnimation function. (see setAnimation documentation for usage)
- feature: preliminary support for zoom and rotation using css transform. This should work with firefox 3.5, safari 3.1, chrome. A fall back using filter for IE is there. Keep in mind that for now the collision detection won't work properly with transformed element. (see rotate() and scale() documentation for usage)
- 0.2.7: Maintenance release:
- bugfix: setAnimation can now be called without an animation to remove any animation from the sprite
- feature: better sound support (still W.i.P.)
- fix: some doc improvement
- fix: the collision() function now plays nice with the end() function
- 0.2.6: Maintenance release:
- bugfix: animation images were loading as soon as the sprite was added to the playground
- bugfix: the jQuery css() function hijacking done for collision detection remove the return of any value causing for example MAJOR issues in demo1.
- change: The position css attribute of the playground may be set to 'relative' by adding 'position: relative' to the options. By default it's still absolute
- bugfix: Some code cleanup to make packing working again.
- change: Removed the playground black border that was left from some old debug code. The sprites don't need to have an animation anymore.
- new feature: Added a simple way to probe the state of the keyboard: when setting the playground specify 'keyTracker: true' and then you can access the state of a key by reading jQuery.gameQuery.keyTracker[keyCode] from anywhere at anytime
- 0.2.5: Added collision detection
- 0.2.0: API changes:
- Added an Animation object
- Removed the removeSprite() and addAnimationToPreload() methodes
- Now the callback function can return a number instead of a boolean. In this case this number redefine the rate at which the functions is called (in milliseconds)
- 0.1.2: bugfix & cleanup:
- setTimeout() replaced by setInterval(), no more function in the global scope
- Fixed a big bug where there was no easy way to remove a sprite from the sprite list. This lead to a sort of memory leak where unused sprite where polluting the sprite list. Now the corrected way to remove a sprite is to use the removeSprite() function instead of remove().
- 0.1.1: fixed a small bug for ie7
- 0.1.0: initial release
Demos
Mechalchemist
This game is a money idol exchanger clone. To play use the 'a' to move the probe left, 'd' to move the probe right, the 's' arrow to take a stone and the 'w' arrow to drop it. Your goal is to make the stone disappear. Use the conversion table at the right. The probe can store any number of stone but all from the same kind.
The graphics still lacks some polish but I've already spend WAY to much time on those for a simple proof of concept. I will likely spend the time I have improving the library and documentation so don't expect a new version of this demo to soon!
Collision Demo
This is a simple demo for the collision detection, it's not a game! Whenever a red square hits the blue one it explodes. You can move the blue square with the a,s,d,w keys.
First tutorial Demo
This is the result of the first tutorial so keep in mind that it's a very simple example, not a full game. It's a shoot'em up. Use the keys 'a', 'w', 'd' and 's' to make the spaceship move and 'k' to shoot. To have a playable frame rate you better use a recent browser, Safari, Chrome or Firefox whith Tracemonkey enabled.
Demo from other people
DerFichtl published a pong clone made with gameQuery here.
raist is working on a port of his side-shooter HoneyBlaster.
Red line is racing game made by the guys at Vertigo Project.
Yann Michalski has published a memory game using jQuery for the animations.
Manual
Animations
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 10x10 sprite with 15 frames your image will be 10x150 or 150x10)
- delta: the width of 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:
- Animation.VERTICAL for vertical, the various frames are stacked verticaly
- Animation.HORIZONTAL for horizontal, the various frames are layed horizontaly
- Animation.ONCE if you don't want the animation to loop
- Animation.CALLBACK a function executed at the end of each animation cycle
- Animation.MULTI if your image file contain more than one animation side by side
- distance: the distance between two image when using multi-animations
example:
playground(expression, 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)
example:
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:
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. This function will be called as long as the return value is false.
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 Animation.CALLBACK)
example:
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:
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 Animation.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.
collision(filter)
This method returns the list of elements collisioning with the selected one but only those that match with the filter given as parameter.
example:
addSound(name, url) experimental!
This function allows adding a sound to the game. The sound will not be played but will be added to the preload.
playSound() experimental!
This function plays the sound on which it's called.
setLoadBar(id, width)
This function sets the div to use as a loading bar. This div will see its width increase progressively from 0 to width as the items on the preload list are loaded.
roate(angle) supported browser: firefox > 3.5, safari > 3.1, chrome, internet explorer > 5.5
This function rotates the selected element(s) clock-wise. The argument is a degree. The usage of this funciton breaks the collison detection for now !
scale(ratio) supported browser: firefox > 3.5, safari > 3.1, chrome, internet explorer > 5.5
This function change the scale of the selected element(s). The passed argument is a ratio: 1.0 = original size, 0.5 = half the original size, 2.0 = twice the original size. The usage of this funciton breaks the collison detection for now !
Tutorials
First tutorial
The first tutorial is an introduction to game programming with gameQuery by the example of a simple side scrolling shooter.
License
This library is under the an MIT license.