ippa/jaws ippa/jaws

  • Stars
    star
    366
  • Rank 116,547 (Top 3 %)
  • Language
    JavaScript
  • License
    GNU Lesser Genera...
  • Created almost 14 years ago
  • Updated about 4 years ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
ippa/jaws
github

ippa

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Jaws - HTML5 canvas javascript 2D Game Framework

Jaws - HTML5 Javascript web game development library¶ ↑

<img src=“https://travis-ci.org/ippa/jaws.svg?branch=master” alt=“Build Status” />

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:

  • Uses 2D canvas to draw stuff on the screen

  • Does not depend on any other JavaScript library

  • Suple-simple-to-use collision detection, bounding box and circles.

  • 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)

Install¶ ↑

$ bower install jaws

Local build / test¶ ↑

npm install
npm test

Learn more¶ ↑

Tutorials¶ ↑

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? Mail me about it (my email is on my github profilepage). Or create a new issue.

Libs using Jaws¶ ↑

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 when patching jaws since you get exact file/line# of possible errors. Warning, jaws-dynamic.js loads all Jaws-files asynchronously, resulting in Jaws might not be fully loaded when the browser reaches your game.js. You can solve this by hooking into the jaws.onload callback and put your jaws.start() there.

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 constructor named Foo().

NOTE #2: jaws.js and jaws-min.js does Not include files from src/extras-dir. Examples of files that aren’t included in the mainbundle are: tile_map_pathfinding.js, pixel_map.js and audio.js (jaws <audio>-wrapper). If you want to use them, load them as usual:

<script src="/jawsjs/src/extras/tile_map_pathfinding.js"></script>

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, but rather the invidual files in the src/-directory

  • Please bundle tests with non-trivial patches, see test/-dir for inspiration

  • 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/videlais - QuadTree() and other things github.com/dmitrizagidulin - SpriteList() rewrite github.com/gregmax17 - Viewport related stuff github.com/MalphasWats - Viewport pathfinding

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.

API-deprecations leading up to ver 1.0¶ ↑

2013-09: Remove experimental, buggy DOM-sprite-support from Sprite and Text
2013-08: SpriteList is no longer included in jaws(-min).js bundle, better off using arrays and jaws.draw/jaws.update
2013-08: jaws.assets.loadAll() -  onfinish -> onload, onload -> onprogress
2013-08: jaws.assets.load(asset, options)  - options can have properties onload and onerror
2013-03: sprite.anchor() is now sprite.setAnchor()
2013-03: sprite.scale() is now sprite.scaleAll()

Example¶ ↑

<html>
<script src="jaws.js"></script>
<body>

<canvas width=500 height=300></canvas> 

<script>
  function MyGameState() {
    var player;
    var robot;

    this.setup = function() {
      player = new jaws.Sprite({image: "player.png", x: 10, y: 200});
      robot = new jaws.Sprite({x: 200, y: 200});
      robot.animation = new jaws.Animation({sprite_sheet: "images/droid_11x15.png", frame_size: [11,15], frame_duration: 120});
    }
    this.update = function() {
      if(jaws.pressed("left"))  { player.x--; }
      if(jaws.pressed("right")) { player.x++; }
      robot.setImage( robot.animation.next() );
    }
    this.draw = function() {
      player.draw();
      robot.draw();
    }
  }

  window.onload = function() {
    jaws.assets.add("images/droid_11x15.png");
    jaws.assets.add("images/player.png");
    jaws.start(MyGameState);
  }
</script>
</body>
</html>

The same example with comments¶ ↑

/*
* 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 setup, 
* 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.
    * Also setup keyboard input event listeners with jaws.setupInput().
    *
    * 2) 
    * Pre-load all assets while showing progress meter through with jaws.assets.loadAll().
    * Assets are then available with jaws.assets.get("player.png").
    *
    * 3) 
    * Create an instance of given game state constructor (in this case MyGameState) and call setup() on that instance.
    * In setup() you usually initialize the game state, create the 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>

More Repositories

1

chingu

OpenGL accelerated 2D game framework for Ruby
Ruby
306
star
2

svg_parser

Parses out info from a SVGfile
Ruby
12
star
3

rest.js

JavaScript REST client micro library for web apps
JavaScript
10
star
4

ghost

A mini Ludum Dare #14 entry made in Ruby / Gosu / Chingu
Ruby
6
star
5

a_tiny_world

Gosu/chipmunk game - Entry for RubyWeekend #3
Ruby
5
star
6

movie_maker

Automate image movements/effects and sounds over a period of time, useful for games.
Ruby
5
star
7

unite.js

unite.js - lightweight 2-way hierarchical databinding
JavaScript
5
star
8

gnorf

Gnorf (is breaking an entrence). My Ludum Dare #18 Ruby/Gosu/Chingu Entry!
Ruby
5
star
9

the_light_at_the_end_of_the_tunnel

Ludum Dare #16 entry, theme "exploration". Made in Ruby / Gosu / Chingu.
Ruby
5
star
10

whygone

A digital ode to _why on whyday 2010
Ruby
5
star
11

pixel_pang

Remake of the classic "Pang" with a twist. Made with Ruby / Gosu / Chingu.
Ruby
4
star
12

the_eternally_grey

My Ludum Dare #15 Game Compo Entry - Ruby / Gosu / Chingu
Ruby
4
star
13

acts_as_mysqlsearchable

acts_as_mysqlsearchable makes MySQL fulltext search easy available directly in your models
Ruby
4
star
14

opposite_islands

Game made with rubygame. Compoentry and winner of Rubyweekend #2.
Ruby
3
star
15

flaunt

Minimalistic slidebased presentations with one file, ruby and sinatra
JavaScript
3
star
16

triangle_wars

A topdown schmup game built with Ruby / Chingu / Gosu
Ruby
2
star
17

tiny_resource

Minimalistic abstract resource controller for rails
Ruby
2
star
18

holiday_droid

A sidescrolling 2D game made with Ruby, Chingu and Gosu.
Ruby
2
star
19

netsnake

Multiplayer snake (online) in Ruby
Ruby
2
star
20

ippa.github.com

http://ippa.github.com/
HTML
2
star