/jaws

Jaws - HTML5 canvas javascript 2D Game Framework

Primary LanguageJavaScriptGNU Lesser General Public License v3.0LGPL-3.0

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 ↑

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:

Games using Jaws ↑

… 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>