Jaws - HTML5 Javascript web game development library¶ ↑

Depends on JavaScript Edition 5. Works with Chrome 9+, Firefox 3.6+, Safari 5+ & IE9.

Licensed under LGPL so you’re free to use it for commercial projects.

Highlights¶ ↑

• Animation(), Sprite(), SpriteSheet(), TileMap(), Assets() and other useful constructors

• Easy and robust game state system to switch between menus, play, high score lists and settings

• JSDOC Documentation & commented examples

Jaws also:

• Does <canvas>-sprites and exprimental HTML-based sprites

• Does not depend on any other JavaScript library

• Doesn’t try to force a certain “JS class pattern” on you, just pure JavaScript as mother nature intended it

• Tries to make assets (images, music, json data) in webgames as easy as possible

• Often does object literals as arguments for readabillity (ie. new Sprite({image: “player.png”, x: 100, y: 100})

• Builds on lessons learned from years of developing github.com/ippa/chingu (Ruby game lib)

Learn more¶ ↑

• jawsjs.com/docs/index.html - Jaws documentation

• jawsjs.com/ - Official Jaws homepage. Overview and design choices.

• jawsjs.com/jawsjs/test/index.html - Jaws testsuite (QUnit)

What kind of games can you make with Jaws?¶ ↑

Jaws is well suited for “classic” side/top scrolling games (tile based or not) where you have a number of sprite-sheet-animated sprites. Jaws comes with basic rect-vs-rect/circle-vs-circle collision detection that works well in most cases. If you have tons of sprites (for example, a bullet hell schmup) you probably want to use a physicslib like Box2D or spatial hashing like quad trees to speed things up. Jaws use of canvas makes pixel perfect collisions and worms-style terrain relatively easy to develop. If your game is very GUI-heavy you might want to base your game on pure HTML-elements instead of canvas-sprites.

Simple examples demonstrating certain features¶ ↑

Check out the sourcecode for comments and explanations:

• jawsjs.com/jawsjs/examples/example0.html - get a Jaws-app working with as little code as possible

• jawsjs.com/jawsjs/examples/example1.html - basic example with manual setup of canvas

• jawsjs.com/jawsjs/examples/example2.html - jaws game states

• jawsjs.com/jawsjs/examples/example3.html - jaws.Animation

• jawsjs.com/jawsjs/examples/example4.html - jaws.Rect based collision detection

• jawsjs.com/jawsjs/examples/example5.html - the jaws.Sprite({anchor: “…”}) parameter

• jawsjs.com/jawsjs/examples/example6.html - jaws.Parallax

• jawsjs.com/jawsjs/examples/example7.html - simple DOM-based sprite

• jawsjs.com/jawsjs/examples/example8.html - jaws.TileMap

• jawsjs.com/jawsjs/examples/example9.html - jaws.Viewport (The basics for a sidescrolling platformer right here)

• jawsjs.com/jawsjs/examples/example10.html - jaws.game_states.Edit, a simple map editor

• jawsjs.com/jawsjs/examples/example11.html - jaws.gfx.retroScaleImage and Literal Notion game state

• jawsjs.com/jawsjs/examples/example12.html - jaws.viewport.drawTileMap() - optimized tile map drawing

Games using Jaws¶ ↑

• ippa.se/webgames/the_escape/index.html - “The Escape” - My Ludum Dare #21 entry. Adventure/Puzzle.

• ippa.se/webgames/unexpected_outcome/index.html - A 10-minute adventure game with pixel-perfect collisions

• ippa.se/webgames/unwaivering/index.html - A Jaws-game for www.ludumdare.com/compo/2011/01/25/minild-24/

• www.twitchtetris.com/ - A tetris game by twitchcode.blogspot.com/

• www.mcfunkypants.com/kart/magma/ - Another pixel perfect game from MC Funky Pants. Don’t touch the rising lava!

• dl.dropbox.com/u/15658925/LD22%20release/game.html - LD#22 entry by “Char” (www.ludumdare.com/compo/ludum-dare-22/?action=preview&uid=3407)

• h31p.com/save-atherton/ - A political satire mini-game from github.com/dalethatcher

• www.mcfunkypants.com/LD22/ - a Ludum Dare #22 entry by Christer Kaitila

• nibster.net/LD/ - a Ludum Dare #22 entry by github.com/Nibster

• memetika.com/iron_santa/ - a Ludum Dare #22 entry by github.com/dmitrizagidulin

• markbennett.ca/JAWS-on-a-plane/ - A minigame by github.com/MarkBennett

… missing your game here? Msg me on github!

Loading Jaws¶ ↑

• jaws.js - includes the whole framework in one easy-to-include file.

• jaws-min.js - same as jaws.js but minified with Googles closure compiler. This is probably what you want to include in your project.

• jaws-dynamic.js - dynamically loads all separate jaws files. Useful for debugging errors in Jaws. Warning, jaws-dynamic.js loads all jaws source-files asynchronously meaning Jaws might not be fully loaded before the browser

• reaches your game.js or likewise. Jaws tries to solve this issue by calling jaws.onload() when all files are loaded.

You can also link to invidual files in your HTML:

<script src="/jawsjs/src/core.js"></script>
<script src="/jawsjs/src/sprite.js"></script>

NOTE: core.js is always needed but after that you can pick and choose depending on what you need. A rule of thumb is that a file named “foo.js” will include a contructor named Foo().

Contribute¶ ↑

Jaws accepts contributions, some simple guidelines:

• Formatting: oneFunction(), OneConstrutor() and one_variable

• 2 spaces for indentation

• Don’t patch jaws.js or jaws-min.js

• Please bundle tests with non-trivial patches

• For bigger patches/feature additions, please contact me beforehand to discuss if/how it fits into Jaws and how to form the API

• Naming shouldn’t consist of abbreviations, let’s use “context”, not “ctx”

Jaws has gotten bigger contributions from: github.com/dmitrizagidulin - SpriteList() rewrite github.com/gregmax17 - Viewport related stuff

Issues and bugs¶ ↑

If you find an issue with Jaws githubs issue-tracker is the place to go. Easiest for the developers is if you put your game online. If you don’t have any hosting check out pages.github.com/. Pasting your problematic code in the issue-ticket itself will usually mean a lot of hassle with supportcode and assets to actually be able to test the code in question.

Example¶ ↑

/*
* Jaws provides powerful functions like jaws.start() to quickly get a robust gameloop running.
* It's also possible to do it more manually, fetch your own canvas context and send it to new Sprite().
* Nothing stops you from using jaws.assets or other jaws.helpers with your own game loop either.
*
* Below code shows the preferred way, letting jaws worry about most of the setut, so we can get straight to get game logic.
*/
<html>
<script src="jaws.js"></script>
<body>

<canvas width=500 height=300></canvas> <!-- don't set width/height of canvas with CSS -->

<script>
  /*
  * Jaws encourages the use of game states to separate various parts of your game.
  * We send MyGameState to jaws.start() to start with.
  * You can later switch to another game state with jaws.switchGameState(OtherGameState)
  */
  function MyGameState() {
    var player;
    var robot;

    /* Put your one-time initializing here. Will get called once each time this game state is activated. */
    this.setup = function() {
      /*
      * Make a sprite, place it at position 10/200.
      * The string "player.png" will resolve to a previously fetched resource.
      * If we wanted the sprite to be drawn to a special canvas, we could add the option {context: my_canvas_context}.
      * Otherwise jaws will just pick the most likely canvas, which works 99% of the times.
      */
      player = new jaws.Sprite({image: "player.png", x: 10, y: 200});

      /* Let's create an animated robot sprite */
      robot = new jaws.Sprite({x: 200, y: 200});

      /* Creates an animation from a classic sprite sheet */
      robot.animation = new jaws.Animation({sprite_sheet: "images/droid_11x15.png", frame_size: [11,15], frame_duration: 120});
    }

    /* update() is called each gametick with given FPS. Put your game logic here. */
    this.update = function() {
      if(jaws.pressed("left"))  { player.x--; }
      if(jaws.pressed("right")) { player.x++; }
      robot.setImage( robot.animation.next() );
    }

    /* draw() is called each gametick just after update() is done. Put your drawing/canvas stuff here. */
    this.draw = function() {
      player.draw();
      robot.draw();
    }
  }

  /* Let's start jaws after the document is fully loaded... */
  window.onload = function() {
    /*
    * Add two images to jaws internal list of assets to be loaded.
    * You can load them manually with jaws.assets.loadAll({loaded: myAssetsAreReadyCall}).
    * jaws.start() will automatically load all unloaded assets while displaying a progress meter.
    *
    * Alternative way (nice when you have a lot of assets in the same dir): 
    *   jaws.assets.path = "images/"; 
    *   jaws.assets.add(["droid_11x15.png", "player.png"]) 
    */
    jaws.assets.add("images/droid_11x15.png");
    jaws.assets.add("images/player.png");

    /*
    * jaws.start(MyGameState) is the easiest way to get something up and running. It will in this order:
    *
    * 1) 
    * Call jaws.init() that will detect <canvas> (or create one for you) and set up the 2D context.
    * It's then available in jaws.canvas and jaws.context and will be used by all new sprites.
    *
    * 2) 
    * Pre-load all assets while showing progess meter. Assets are then available with jaws.assets.get("player.png").
    *
    * 3) 
    * Create an instance of given game state (in this case MyGameState) and call setup() on that instance.
    * In setup() you usually initialize that game state, create your gameobjects, sprites and so forth.
    *
    * 4) 
    * Loop calls to update() and draw() with given FPS (default 60) until the game ends, is paused or another game state is activated.
    *
    */
    jaws.start(MyGameState);
  }
</script>
</body>
</html>