Download: CocoonJSAudioPlugin

How to use: Just put the CocoonPlugin as the first entry to register and you can use everything else of the SoundJS-library just as is in CocoonJS now.

createjs.Sound.registerPlugins([createjs.CocoonJSAudioPlugin]);

//this will allow me to play 3 parallel instances of jump.ogg
  createjs.Sound.registerSound('jump.ogg','jump', 3);

direct link: http://labs.indiegamr.com/olines/index.html

For bluring I used this filter: Link – but still: For those kind of operations HTML/JS is unfortunately still way behind flash in terms of performance.

Audio != Audio

While most browsers and devices already do support audio in general, that doesn’t mean you can just play any audio file in any modern browser. The following table briefly lists the support for Audio-codecs.

As you can see there is no single codec and format that is supported by all browsers and devices. In addition to this not every device does support the WebAudio-API and some devices only allow audio-playback upon a user-interaction or only allow playing one sound at a time. So what should you do? Setup an audio file for any codec and then check the browser’s support before loading and playing the file? While this would be currently the only way to do it right, this not only sounds like a lot of work, but also is. What about browsers that don’t support the audio-element at all? – Implementing a flash fallback is no easy task as well.

SoundJS

One possible solution is SoundJS – SoundJS is a JavaScript framework that will take care of all the compatibility issues with audio on different devices and even adds the ability of a flash-fallback should the browser support no audio. You would still have to provide different files for each sound to ensure that a soundfile is available for each device depending on the codec support but besides this, playing a sound with SoundJS can be done with 2 lines of JavaScript:

var src = ‘mySound.m4a|mySound.ogg’;
createjs.Sound.registerSound(src);
//…after the sound was loaded, it can be played by:
createjs.Sound.play(src);

What I also like about SoundJS is that it features a plugin-system, so you can write your custom playback-plugin for individual needs, for example I used it to write a CocoonJS-plugin for it.

howler.js

Another solution is howler.js, it is also released under the MIT license, so you can use it free in any of you projects it works very similar to SoundJS. One advantage over SoundJS is that it is very lightweight with only 9kb and offers pretty much the same functionality as SoundJS – with one exception though: howler.js features no flash-fallback, but if you are targeting mobile platforms, this should be no problem.

var sound = new Howl({
  urls: ['mySound.m4a','mySound.ogg']
}).play();

Another thing I like about howler is the support of sound-sprites:

var sound = new Howl({
  urls: ['sounds.mp3', 'sounds.ogg'],
  sprite: {
    blast: [0, 1000],
    laser: [2000, 3000],
    winner: [4000, 7500]
  }
});

// shoot the laser!
sound.play('laser');

SoundManager 2
A third option is SoundManager 2, (github), just like SoundJS it features a flash fallback if HTML5 audio is not supported. SoundManager2 is used by popular site like SoundCloud, last.fm or the Nyan Cat site. The focus of SoundManager2 is more on implementing audio-players on web-sites as it also features UIs for audio playback. Sounds are played like this:

// create "mySound"...
soundManager.createSound({
  id: 'mySound',
  url: '/path/to/an.mp3'
});

// ...and play it
soundManager.play('mySound');

Comparison

As you can see, all three frameworks have their pros and cons, you should check out their sites and see what features you need for your project. The following table is just a very brief overview on the differences:

*this doesn’t mean that you cannot use it for other cases, it’s just my personal evaluation

A last word: Beware of MP3!

What a lot of people probably don’t know: MP3 is not free!
Implementing mp3 into your app/game is no problem, but what you should know is that if your game is ‘distributed’ (technically that includes 1 user playing the game in his browser) more than 5000 times, you have to pay an mp3 codec royalty of $2500. But not only because of the licensing I would suggest you to use Ogg Vorbis(.ogg) or AAC(.m4a, MP4), OGG and AAC do have a better sound-quality while encoded with a smaller file-size than their MP3-counterpart.

If you want to learn more about the workflow of implementing audio into your html5- (mobile-) app/game and additional information on creating and publishing an HTML5 game, you should checkout my book at: http://indiegamr.com/zerotoappstore/

Download: easeljs_cocoonjs_touchfix.js

(updated version to work with EaselJS 0.7+, thx to Jonny)
How to use: Download JS-fix and implement it through a script-tag somewhere after the EaselJS-script-tag and your done!

Hope this helps someone, comment for any issues,cheers!

If you use an older version of EaselJS: easeljs_cocoonjs_touchfix_pre_0.7.js (for pre-EaselJS 0.7)

Here is an example (play around with the alpha threshold and toggle the detection mode):

// Rect Collision
var intersection = ndgmr.checkRectCollision(bitmap1,bitmap2);
// intersection is null if no collision, otherwise a {x,y,width,height}-Object is returned

// Pixel Perfect Collision
var collision = ndgmr.checkPixelCollision(bitmap1,bitmap2,alphaThreshold);
// true or false
// alphaThreshold default is 0, set to higher value to ignore collisions with semi transparent pixels

1. Not all CSS Properties trigger hardware acceleration any more

Previously there were quite a few properties that triggered a hardware acceleration, for example:

• -webik-transform: translate3d(x,y,z);
• -webkit-transform: preserve-3d;
• …

As Apple states in its Developer Changelog for iOS6: ‘WebKit no longer always creates hardware-accelerated layers for elements with the -webkit-transform: preserve-3d option.[…]‘ There is a need for new CSS properties to trigger the acceleration, unfortunately I’m not aware of any official document by Apple listing those properties.

How to fix it:
Here are three properties that have been proven to work (at least in combination, I have not yet tested them solo, but they should):

• -webkit-transform: translateZ(0);
• -webkit-perspective: 1000;
• -webkit-backface-visibility: hidden;
  

As this is going to trigger hardware acceleration for the specified elements this might still not completely fix all the issues, therefore please continue reading Nr.2.

2. Overlapping with other Elements

Since I cannot downgrade to iOS5 I cannot say for sure if this “issue” already persisted, however it heavily persists with iOS6:

If you have an element(Element A) that is hardware accelerated and animated, it will/might cause performance and visual issues when overlapping with other elements(Element B) that are not hardware accelerated, as Element A will trigger Element B to be re-rendered with every change of Element A(at the end of a CSS-transition or when updating CSS properties through JS), which will cause:

• flickering of Element B, since it renders a lot slower
• heavy slowdown of the animation, since it needs more CPU time to render leaving less time for JS execution

One thing I noticed: If Element A OVERlaps another element it is not slowing down the animation as heavy as if Element A was UNDERlapping another element. Also it does not really matter if the parent-container of Element A has ‘overflow: hidden;’ or ‘overflow: visible;’ – it still slows doen the execution if the overlapping occures outside the bounds of the parent container.

How to fix it:
 a) This can be simply fixed by giving ALL overlapping elements the CSS properties that trigger hardware accerleration. (see 1.)
(My first approach to fix this was by alternating the DOM-order to only have OVERlapping elements, however fix a) is way easier and works way better – for me.)

I have visualized this here:

edit1: 16-10-2012

3. Avoid changes between ‘display: none;’ and ‘display: something;’

Changing the display-state on iOS is like adding or removing an element to and from the DOM and is therefor a very heady calculation depending on how many items you have in your DOM that can easyly cause the UI to freeze for a second or more.

How to fix it:
Instead of using the display-property, use the tranform-property instead, if you want to hide an item you can use something like this: transform:

translate(100000px,100000px);

and if you want to show the element, just set the values to 0:

translate(0px,0px);

You have to set the ‘position: absolute;’ though. This method needs a little bit more work than using ‘display’, however the performance of your webapp will thank you greatly for that.

I hope this helps someone as I was struggeling with this issue for quite a while, thoughts or additions on this article are very welcome!

The algorithm

// the initial seed
Math.seed = 6;

// in order to work 'Math.seed' must NOT be undefined,
// so in any case, you HAVE to provide a Math.seed
Math.seededRandom = function(max, min) {
    max = max || 1;
    min = min || 0;

    Math.seed = (Math.seed * 9301 + 49297) % 233280;
    var rnd = Math.seed / 233280;

    return min + rnd * (max - min);
}

You may ask: Why ‘(seed * 9301 + 49297) % 233280‘ ?!
The answer is both simple&complicated: The combination of 9301, 49297 and 233280 provide a very even distributed set of “random” numbers. Please don’t ask WHY – that’s the complicated part, some very smart people figured out those numbers quite some time ago, and I also cannot tell you how they did it. But as allways: Google is your friend

Benchmark

See it in ‘action’

The result:

Background Parallax

self.createBgGrid = function(numX, numY) {
	var grid = new Container();
	grid.snapToPixel = true;
	// calculating the distance between
	// the grid-lines
	var gw = w/numX;
	var gh = h/numY;
	// drawing the vertical line
	var verticalLine = new Graphics();
	verticalLine.beginFill(Graphics.getRGB(101, 60, 176));
	verticalLine.drawRect(0,0,gw * 0.02,gh*(numY+2));
	var vs;
	// placing the vertical lines:
	// we're placing 1 more than requested
	// to have seamless scrolling later
	for ( var c = -1; c < numX+1; c++) {
		vs = new Shape(verticalLine);
		vs.snapToPixel = true;
		vs.x = c * gw;
		vs.y = -gh;
		grid.addChild(vs);
	}
	// drawing a horizontal line
	var horizontalLine = new Graphics();
	horizontalLine.beginFill(Graphics.getRGB(101, 60, 176));
	horizontalLine.drawRect(0,0,gw*(numX+1),gh * 0.02);
	var hs;
	// placing the horizontal lines:
	// we're placing 1 more than requested
	// to have seamless scrolling later
	for ( c = -1; c < numY+1; c++ ) {
		hs = new Shape(horizontalLine);
		hs.snapToPixel = true;
		hs.x = 0;
		hs.y = c * gh;
		grid.addChild(hs);
	}

	// return the grid-object
	return grid;
}

And when the game is initialized, don’t forget to add the grid to the stage:

// setting up 'constants' for the number of vertical
// and horizontag background lines - play around with those values
var	GRID_HORIZONTAL = 8,
	GRID_VERTICAL = 4;

// and the following will be added to 'self.initializeGame'
background = self.createBgGrid(GRID_HORIZONTAL,GRID_VERTICAL);
stage.addChild(background);

To emphasize movement we will make the background move with about 50% of the world-movement creating a parallax-effect. We accomplish that by adding the following to the ‘self.tick’-method:

// the background 'moves' about 45% of the speed of the world-object
// and it's position snaps back to zero once it's reached a limit 
background.x = (world.x * .45) % (w/GRID_HORIZONTAL); // horizontal
background.y = (world.y * .45) % (h/GRID_VERTICAL);   // vertical

Note: This is pretty much the most simple way to make a background move seamlessly as the world moves, however if you have a more complex background you will probably have to use either a greater modulo(%) or handle you background-movement individually.

The changes above should already result in something similar to this:

Pretty simple – right?

More Background Parallax

self.createPixelLine = function(width) {
	// adjusting the width to the games scale
	// but not smaller than 1px and round it
	// to only have full pixels to render or
	// anti-aliasing will slow everything down
	width = Math.max(Math.round(width * scale),1);

	// drawing the line
	vl = new Graphics();
	vl.beginFill(Graphics.getRGB(255,255,255));
	vl.drawRect(0,0,width,h);

	lineShape = new Shape(vl);
	lineShape.snapToPixel = true;
	// the thinner the line, the less alpha
	// to make it look like it's further away
	lineShape.alpha = width * .25;
	// if it's further away, make it move slower
	lineShape.speedFactor = 0.3 + lineShape.alpha * 0.3 + Math.random() * 0.2;
	// the range defines when the line will be
	// moved back to the end of the screen
	lineShape.range = w + Math.random() * w * .3;
	// every line needs an offset, so they
	// don't start off at the same position
	lineShape.offsetX = Math.random() * w;
	
	return lineShape;
}

And when we initialize the game, we will just create 4(or how many we want) of those lines:

// create and add another background-
// /parallax-layer
background_2 = new Container();
stage.addChild(background_2);
for ( var c = 0; c < 4; c++) {
	// create a line/ distant waterfall
	var line = self.createPixelLine((Math.random()*3+1)|0);
	// add it to the scene
	background_2.addChild(line);
	// and push it to the parallaxObjects
	// don't forget to initialize that array
	parallaxObjects.push(line);
}

And now we will make those lines move, just we like we made the grid move (it’s a little more complex this time, but the basic idea behind it, is the same):

l = parallaxObjects.length;
for ( c = 0; c < l; c++ ) {
	p = parallaxObjects[c];
	// just change the x-coordinate
	// a change in the y-coordinate would not have any
	// result, since it's just a white line
	p.x = ((world.x * p.speedFactor - p.offsetX) % p.range) + p.range;
}

And voila – now we got a pretty decent looking parallax-background already, of course with this way, it’s pretty simple to use just any graphic instead of white line, just add some vertcal-movement as well, and it should be good to go. The current result after adding all parallax elements looks like this:

Animations

The basic way for creating a SpriteSheet-Animation in EaselJS looks like this:

// defining the spriteSheetData
// this whole object can also be
// stored in a JSON-file, however
// by resizing my assets with my
// custom algorithm this would make
// things more complicated
var waterFallSpriteSheetData = {
	images: [assets[WATERFALL_IMAGE]],
	frames: {
		// dimensions of the animation
		height: 256 * scale,
		width: 8 * scale,
		// number of frames
		count: 3
	},
	animations: {
		// we call this animation 'default'
		default: {
			// it contains all 3 frames
			frames:[0, 1, 2],
			// and it runs with a decent speed
			frequency: 5
		}
	}
}
// ...

// and now we can initialize an animation at any time
var spriteSheet = new SpriteSheet(waterFallSpriteSheetData);
var waterfall = new BitmapAnimation(spriteSheet);
waterfall.snapToPixel = true;
waterfall.gotoAndPlay('default');

CAUTION: EaselJS version 0.4.2 does NOT support Canvas-Elements in SpriteSheets, however our scaling-algorithm creates a Canvas-Element, meaning that we have to UPDATE our version of EaselJS – you can download the “NEXT-Version” on github.com/CreateJS/EaselJS – However, be aware, that this version uses namespacing, the simplest fix to get our game running with the “NEXT-Version” is to add the following into our index.html BEFORE loading EaselJS:

<script>
	var createjs = window;
</script>
<!-- now your can load the rest -->
<script src="js/easeljs-NEXT.min.js"></script>
<script src="js/utils.js"></script>
<script src="js/hero.js"></script>
<script src="js/jumpy.js"></script>

Note: The SpriteSheet-Data CAN also be stored and loaded from a JSON – but in this case the SpriteSheet-Data contans dynamic values, like the size and the image, that’s why I prefer to just initialize the whole thing within a JS method. For a more detailed view on all the possible attributes of a SpriteSheet, please refer to: http://createjs.com/Docs/EaselJS/SpriteSheet.html.

As my next step I created a new layer in the front to add the waterfalls to and added a method that would add a waterfall to every platform with a probability of 35%. Since this is just placing and moving objects, I’m not going into detail about what lines of code I added where – for details please download and view the sourcecode.

As a final step I then added a fly to fly around our hero, it’s based on a simple 2-frame animation, and its movement is the following:

// the movement of the fly
// calculate an offset to create a "swirling-like" behaviour
fly.offsetX = ( Math.cos(ticks/10) * 10) * scale;
fly.offsetY = ( Math.sin(ticks/ 7) *  5) * scale;
// smoothly follow the hero by 10% of the distance every frame
fly.x = fly.x + (hero.x - fly.x) * .1 + fly.offsetX;
fly.y = fly.y + (hero.y - fly.y) * .1 + fly.offsetY;

• Part 1: User-Input (Keystrokes, MouseClick, Touch)  & Movement
• Part 2: Collisions between objects
• Part 3: Movement&More Collision
• Part 4: Adjustments for mobile devices
• Part 5: Polishing up the game with animations & eye candy

Open this http://demos.indiegamr.com/jumpy/part4/index_nearestNeighbor.html in a new browser-window and see how it adjusts to your window-size as you reload the page after resizing the window.

As allways: There are many ways to do this, all will pros and cons, I’m going to explain two (fairly simple) ways to do this.

Method I – Linear Scaling: Easy&straight forward

1. Calculate the minimum-scale from the width&height based on a default-width & default hight
2. Multiply every (scale-relevant) value of the game with that scale(e.g: dimensions of objects, velocities, ect..)

Calculating the scale is just one line: Okay in my case it’s 3, because I added variables for the default-dimensions:

/* defined globally */
var BASE_WIDTH = 800,
    BASE_HEIGHT = 400;
// this was new to me here: i tried using 'const' for those values, instead
// of 'var' which was working fine until i tried it with ...guess what: IE!

/* when initializing the _game() */
var w = getWidth(),
    h = getHeight(),
    scale = Math.min(w/BASE_WIDTH,h/BASE_HEIGHT);

// to make the scale accessbile from the 'outsite' through
// Game.scale, we assign it to the Game-object
self.scale = scale;

So now that we have our scale-value: We are going to multiply every value, relevant to the scale, with it. As this involves quite a few parts of the code, instead of posting the whole updated source-code I’m going to list a few examples, and you can download the full source as always at the end of the page.

// e.g: when setting up the objects or position them
hero.x = 50 * scale;
hero.y = h/2 + 50 * scale;
hero.scaleX = hero.scaleY = scale;

// or when resetting attributes like velocity
Hero.prototype.reset = function() {
    this.velocity = {x:10*Game.scale,y:25*Game.scale};
    this.onGround = false;
    this.doubleJump = false;
};

// or when updating values
this.velocity.y += 1 * Game.scale;

Adjustments

function getBounds(obj,rounded) {
  /* 
     I left out the calculation of the bounds, this is
     described in Part2
  */
  // and now round everything to get integer values
  if ( rounded ) {
    bounds.x = (bounds.x + (bounds.x > 0 ? .5 : -.5)) | 0;
    bounds.y = (bounds.y + (bounds.y > 0 ? .5 : -.5)) | 0;
    bounds.width = (bounds.width + (bounds.width > 0 ? .5 : -.5)) | 0;
    bounds.height = (bounds.height + (bounds.height > 0 ? .5 : -.5)) | 0;
  }
  return bounds;
}

You don’t have to fully understand bitwise operations, but as a basic fact you should know, that with any bitwise operation all decimals will be erased. However, for optimizing code it is allways helpfull to know how bitwise works!

So all values from the returned bounds-rectangle will be integer values, to prevent the method from not detecting a collision, but then moving the object for example 0.5px too far, thus creating a collision-situation.
Rounding values like the position or the velocity of an object is in 90% of the cases a good thing to do, as it is basically impossible to spot a difference between rounded- and non-rounded pixel-values while it is (on most platforms) way faster for the canvas to render on pixel instead of subpixel values. So: use integer-values or for EaselJS-Objects: myObject.snapToPixel = true; – it is faster and in most cases you won’t see the difference.

That’s it with Method I of adjusting a canvas-app to the screen-size, you might think: ‘Looks good to me, why should I use anything else?!’ – here’s the reason: The following image shows two scaled versions of Method I and Method II – and since we are building a retro-/pixel-style game, guess which method we are going to use

Method II – Nearest Neighbor Scaling: keep hard pixel-edges

function nearestNeighborScale(img, scale)
{
  // to have a good looking scaling
  // we will snap all values to 0.5-steps
  // so 1.4 e.g. becomes 1.5 - you can also
  // set the snapping to 1.0 e.g.
  // however I would recommend to use only 
  // a multiple of 0.5 - but play around
  // with it and see the results
  scale = snapValue(scale,.5);
  if ( scale <= 0 ) scale = 0.5;

  // the size of the "pixels" in the new images
  // will be rounden to integer values, as drawing
  // a rect with 1.5x1.5 would result in half-transparent
  // areas
  var pixelSize = (scale+0.99) | 0;

  // getting the data-array containing all the pixel-data
  // from our source-image
  var src_canvas = document.createElement('canvas');
  src_canvas.width = img.width;
  src_canvas.height = img.height;
  var src_ctx = src_canvas.getContext('2d');
  src_ctx.drawImage(img, 0, 0);
  var src_data = src_ctx.getImageData(0, 0, img.width, img.height).data;
  
  // setting up the new, scaled image
  var dst_canvas = document.createElement('canvas');
  // just to be sure, that no pixel gets lost, when
  // we scale the image down, we add 1 and floor the
  // result
  dst_canvas.width = (img.width * scale+1) | 0;
  dst_canvas.height = (img.height * scale+1) | 0;
  var dst_ctx = dst_canvas.getContext('2d');

  // reading each pixel-data from the source
  // and drawing a scaled version of that pixel
  // to the new canvas
  var offset = 0;
  for (var y = 0; y < img.height; ++y) {
      for (var x = 0; x < img.width; ++x) {
          var r = src_data[offset++];
          var g = src_data[offset++];
          var b = src_data[offset++];
          var a = src_data[offset++] / 255; // the alpha value needs to be divided
          dst_ctx.fillStyle = 'rgba(' + r + ',' + g + ',' + b + ',' + a + ')';
          dst_ctx.fillRect(x * scale, y * scale, pixelSize, pixelSize);
      }
  }

  return dst_canvas;
}

function snapValue(value,snap)
{
  var roundedSnap = (value/snap + (value > 0 ? .5 : -.5)) | 0;
  return roundedSnap * snap;
}

So when the game gets initialized, we scale any bitmap loaded:

self.initializeGame = function() {
  assets[HERO_IMAGE] = nearestNeighborScale(assets[HERO_IMAGE], scale);
  assets[PLATFORM_IMAGE] = nearestNeighborScale(assets[PLATFORM_IMAGE], scale);
  // ...
  // see source for the rest of initializing part(no changes there)

And then again, like with ‘Method I’ we have to adjust every scale-relevant value, like velocities, positions EXCEPT for any scaleX or scaleY values, because our nearsetNeighborScale-method did that already. Also, just to be on the save side, we also do the collision-detection adjustments here (see bounds-rounding further up in the article).

Compare both methods side by side

Download the sources: here.

Agenda

• Part 1: User-Input (Keystrokes, MouseClick, Touch)  & Movement
• Part 2: Collisions between objects
• Part 3: Movement&More Collision
• Part 4: Adjustments for mobile devices
• Part 5: Polishing up the game with animations & eye candy