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

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/

Long story short: This is probably the most senseless piece of code I have ever written and most likely will ever have written:

onComplete = function(e) {
  //...doing some other stuff

  // at this point everything is
  // loaded and ready to go
  // ...but ... you know ... the client ...
  setTimeout(
    function() {
      $('#loadingCover').hide();
    }, 3000
  );
}

I personally love the  ‘-webkit-overflow-scrolling: touch’-feature as it allows you to implement a scroll pane for mobile devices with just writing two lines of css and no need of hasseling around with JS to make some content scroll smooth ect., however this approach also comes with a drawback: hardware acceleration will cause performance-issues on iOS (maybe other mobile devices, though it was only tested on an iPad2 running iOS6)

In my last post I was writing about forcing html5 hardware acceleration on iOS6, turns out you do NOT want to do that on every element as this can also cause the performance to drop, pointed out by the following example:

The scenario is the following: The base is a big scrollpane using ‘-webkit-overflow-scrolling: touch‘ that contains many images that are scaled from 100px width to 50px width.
When combining this with forced hardware acceleration it will cause a massive drop in fps while scrolling.

Try it yourself by pointing your mobile browser to the following urls:
Images Example Version 1: http://goo.gl/XIn9e – NOT hardware accelerated, very good framerate
Images Example Version 2: http://goo.gl/DKC1u  - hardware accelerated, low framerate while scrolling, however seems not to affect the execution of JS as the displayed fps does not drop

The only difference between Version 1 and Version 2 is:

img {
 -webkit-transform: translateZ(0);
 -webkit-perspective: 1000;
 -webkit-backface-visibility: hidden;
}

The examples with HTMLImages shows a very huge drop in performance, however this effect is not solely limited to images but also <div> and other elements, even though it takes a larger number of divs to bring down the performance this way, it is possible:

Divs Example Version 1: http://goo.gl/1iF71 – NOT accelerated, fluid, high fps
Divs Example Version 2: http://goo.gl/qkdwm – accelerated, less frames on scrolling, seems to affect the execution speed of JS code

So bottom line: Forced hardware acceleration and ‘-webkit-overflow-scrolling: touch;’ do not work together very well!

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!

Let’s face it: “There is an app for everything!” – However looking at the two major App Stores, iTunes and Play, there are serveral types of apps.
Now the division of those apps are not backed by any statistics and are only based on my perception of the appstores and my experience browsing through the stores:

Now, what I want to take from this:
Making an A-App as an indie dev is very unlikely. D-Apps are not worth looking into, since they are all bad and/or copied. What I want to look at is B and C. I used to browse through the App Store looking at Apps and sometimes found a neat, innovatice App or cool idea – however I always say to myself things like ‘Too bad it already exists, I could have made an app like that‘ or ‘Well someone tried it, but looks like noone’s downloading it, so noone wants an app like that‘ – Well, while this might apply to some apps, it won’t apply to the majority of those apps. In my opinion the majority of those C-Apps have no success because of their UI and their usability. Think about it: Would you really use an app with a badly designed UI that’s not fun to use at all, even if it could be of use for you? Probably Not.
And that’s why C-Apps are interesting for any indie dev! They are innovative and usually of good use for their customers, however their execution is bad. So the key of succeeding could be an idea of an existing app but without its flaws and with an awesome, kickass UI. I personally, truly believe that there is potential in those apps. There doesn’t allways have to be something completely new to succeed, it can just as well be an old idea picked up and executed well.

“Taking an idea” does not equal “rip off”

I’m not saying that you should go ahead and rip off other indie developers by copying an app 1to1, it is more like taking an idea and shaping a new, better product out of it and maybe even form new ideas during that process. In my eyes this is where innovation comes from.

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

Types of Collision Detection

There are several types of collision detection methods, I’m going to explain two of the most commong ways to detect a collision – if you want more/detailed information on the subject I would encourage you to google for it or try this article as an introduction to the topic.

1) Distance Based- or Circle-Collision

This is probably the simplest type of collision detection. What you basically have to do is to set a collision-radius for each object, then calculate the distance between the objects and see if the distrance is lower than the radii combined. However the following image shows, that this kind of detection won’t be suitable for our platform game:

As you can see, with this method, a collision is detected way before an actual collision occures. This is due to the fact, that the platform has a very different hight and width. However a circle-collision-detection would be perfect for any Pool-game for example.

2) Bounding-Box-Collision

This type of  detection is (is many cases, not all) more accurate than the circle-based detection and it basically works by defining a rectangle of the boundaries for each object and then check if those two rectangles intersect in any way.

There are two(or probably more, but i’m only going to point out two of them) ways to collect a collision this way.

The first method is actually not checking for a collision, but for non-collisions. This simply requires four if clauses:

• a) is the space between rect1.left and rect2.right ?
• b) is there space between rect1.right and rect2.left ?
• c) is there space between rect1.top and rect2.bottom ?
• d) is there space between rect1.bottom and rect2.top ?

If any (1 or more) of the statements above are true, then there is no intersection between the rectangles, however if all of the statements are false, there must be an intersection.

And here is the according piece of code:

function checkRectIntersection(rect1,rect2) {
  if ( rect1.x >= rect2.x + rect2.width    // a)
    || rect1.x + rect1.width <= rect2.x    // b)
    || rect1.y >= rect2.y + rect2.height   // c)
    || rect1.y + rect1.height <= rect2.y ) // d)
      return false;

  return true;
};

Even though this method looks super-simple – we are unfortunately NOT going to use this method. Instead we will use a method that checks for an intersection AND returns the size of the intersecting area.

To explain this a little better i drew up a graphic for this:

So what we are going to do, is calculate the X- and the Y-overlapping value, if both values are greater than 0, there is an intersecting area.

dx = |cx1 - cx2| - (hw1 + hw2)
dy = |cy1 - cy2| - (hh1 + hh2)

=> if  d_x < 0 and d_y < 0 then there is a collision, in this case we can return -d_x and -d_y as overlapping values

And the method in JS looks like this – I also added two parameters x and y, to calculate where the rect1 wants to move to:

function calculateIntersection(rect1, rect2, x, y) {
  // prevent x|y from being null||undefined
  x = x || 0; y = y || 0;

  // first we have to calculate the
  // center of each rectangle and half of
  // width and height
  var dx, dy, r1={}, r2={};
  r1.cx = rect1.x+x+(r1.hw = (rect1.width /2));
  r1.cy = rect1.y+y+(r1.hh = (rect1.height/2));
  r2.cx = rect2.x + (r2.hw = (rect2.width /2));
  r2.cy = rect2.y + (r2.hh = (rect2.height/2));

  dx = Math.abs(r1.cx-r2.cx) - (r1.hw + r2.hw);
  dy = Math.abs(r1.cy-r2.cy) - (r1.hh + r2.hh);

  if (dx < 0 && dy < 0) {
    return {width:-dx,height:-dy};
  } else {
    return null;
  }
}

This is also the method we are going to use in the game. There are plenty of other methods that are probably more accurate(a mix of Circle/BoundBox-collision, Pixel-perfect collision ect.), but usually take longer for their calculation. And for the sake of keeping everything simple our current method will do a pretty good job and you won’t really notice any flaws of the collisions in the game. I could spend a lot more time on figuring out a pixel-perfect collision algorithm ect., just to get rid of the last “free spaces” – however it won’t look that much more realistic to be worth the effort. This is actually a good tipp for new game-developers:

Go with simple!:
In 90% of the cases a simple version works just (almost) as good as a ‘perfect’ version, that would have taken much much longer to develop. The same with making a method as universial as possible because you say “I might need it later for something else” – there’s a very good chance, that you will not need it- and if you do: Do it when you need it, you won’t loose any time.

So now we’ve got our collision-method – how do we use it in the game?

Implementation

Before we can acutally use the detection-method in the game, we need the bounding rectangle of our EaselJS DisplayObject – however since EaselJS is not providing such a function(yet?), we will use the method from here and put it into our utils.js(included in the zip-file from Part 1) as well as the “calculateIntersection()” method.

We then will update the tick-method of our Hero-class with the following:

Hero.prototype.tick = function () {
    this.velocity.y += 1;

    // preparing the variables
    var c = 0,
        cc = 0,
        addY = this.velocity.y,
        bounds = getBounds(this),
        cbounds,
        collision = null,
        collideables = Game.getCollideables();

    cc=0;
    // for each collideable object we will calculate the
    // bounding-rectangle and then check for an intersection
    // of the hero's future position's bounding-rectangle
    while ( !collision && cc < collideables.length ) {
			cbounds = getBounds(collideables[cc]);
			if ( collideables[cc].isVisible ) {
				collision = calculateIntersection(bounds, cbounds, 0, addY);
			}

			if ( !collision && collideables[cc].isVisible ) {
				// if there was NO collision detected, but somehow
				// the hero got onto the "other side" of an object (high velocity e.g.),
				// then we will detect this here, and adjust the velocity according to
				// it to prevent the Hero from "ghosting" through objects
				// try messing with the 'this.velocity = {x:0,y:25};'
				// -> it should still collide even with very high values
				if ( ( bounds.y < cbounds.y && bounds.y + addY > cbounds.y )
				  || ( bounds.y > cbounds.y && bounds.y + addY < cbounds.y ) ) {
					addY = cbounds.y - bounds.y;
				} else {
					cc++;
				}
			}
		}

    // if no collision was to be found, just
    // move the hero to it's new position
    if ( !collision ) {
        this.y += addY;
        if ( this.onGround ) {
            this.onGround = false;
            this.doubleJump = true;
        }
    // else move the hero as far as possible
    // and then make it stop and tell the
    // game, that the hero is now "an the ground"
    } else {
        this.y += addY - collision.height;
        if ( addY > 0 ) {
            this.onGround = true;
            this.doubleJump = false;
        }
        this.velocity.y = 0;
    }
}

now we have to add a platform for the hero to collide with, I therefor create a method called “addPlatform”, that should mostly explain itself:

this.addPlatform = function(x,y) {
    x = Math.round(x);
    y = Math.round(y);

    var platform = new Bitmap(assets[PLATFORM_IMAGE]);
    platform.x = x;
    platform.y = y;
    platform.snapToPixel = true;

    world.addChild(platform);
    collideables.push(platform);
}

also I did update the javascript-file holding the main methods and the game loop ect. quite a bit(to make the post not too big, I left out a few parts – download the ZIP-file to get the full source):

var  HERO_IMAGE = 'assets/hero.png',
     PLATFORM_IMAGE = 'assets/platform.png';

function _game()
{
    window.Game = this;
    var self = this, ticks = 0, canvas, stage, world, hero,
        w = getWidth(), h = getHeight(), assets = [], keyDown = false;

    // holds all collideable objects
    var collideables = [];
    this.getCollideables = function() { return collideables; };

    // starts to load all the assets
    this.preloadResources = function() {
        self.loadImage(HERO_IMAGE);
        self.loadImage(PLATFORM_IMAGE);
    }

    var requestedAssets = 0, loadedAssets = 0;
    // loads the assets and keeps track 
    // of how many assets where there to
    // be loaded
    this.loadImage = function(e) {
        var img = new Image();
        img.onload = self.onLoadedAsset;
        img.src = e;

        assets[e] = img;

        ++requestedAssets;
    }
    // each time an asset is loaded
    // check if all assets are complete
    // and initialize the game, if so
    this.onLoadedAsset = function(e) {
        ++loadedAssets;
        if ( loadedAssets == requestedAssets ) {
            self.initializeGame();
        }
    }

    this.initializeGame = function() {
        /* setting up stage&listeners - download ZIP */

        // creating the Hero, and assign an image
        // also position the hero in the middle of the screen
        hero = new Hero(assets[HERO_IMAGE]);
        hero.x = w/2
        hero.y = h/2;
        world.addChild(hero);

        // add a platform for the hero to collide with
        self.addPlatform(w/2 - assets[PLATFORM_IMAGE].width/2, h/1.25);
    }

    this.tick = function(e)
    {
        ticks++;
        hero.tick();
        stage.update();
    }

    // this method adds a platform at the
    // given x- and y-coordinates and adds
    // it to the collideables-array
    this.addPlatform = function(x,y) {
        x = Math.round(x);
        y = Math.round(y);

        var platform = new Bitmap(assets[PLATFORM_IMAGE]);
        platform.x = x;
        platform.y = y;
        platform.snapToPixel = true;

        world.addChild(platform);
        collideables.push(platform);
    }

    /* input-listeners - download ZIP */

    self.preloadResources();
};

new _game();

When you try this out – it should look similar to this:

Some of you might noticed that, the hero is also able to jump twice now: I removed the reset()-method from Hero.js and replaced it with a similar jump()-method:

Hero.prototype.jump = function() {
    // if the hero is "on the ground"
    // let him jump, physically correct!
    if ( this.onGround ) {
        this.velocity.y = -17;
        this.onGround = false;
        this.doubleJump = true;
    // we want the hero to be able to
    // jump once more when he is in the
    // air - after that, he has to wait
    // to lang somewhere on the ground
    } else if ( this.doubleJump ) {
        this.velocity.y = -17;
        this.doubleJump = false;
    }
}

And that’s pretty much all there is to get a basic collision detection working – Again: There are PLENTY of other methods, some of them maybe better in performance and/or accuracy, however I find this approach to be both fairly simple, effective and easy to follow – but suggestions for different approaches are allways welcome, just leave a comment!

The sources for this part can be found right here: Download Part2.zip

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

Here I’m starting a series of 4 articles on how to create a small game with EaselJS that “can” run on your mobile device (unfortunately it won’t run on all mobile devices) – however I also plan on a future posting on how to use technologies like cocoonJS to create a WELL-PERFORMING native app from this.

The FINAL result

The result is going to look similar to this (but with better code!) – In case you take a look at the source-code: This is NOT a good example on how to code cleanly – I did this as a quick mashup to try out a few things. – You can also do another jump, while in the air:

To test this on your mobile device, point your mobile browser to: http://demos.indiegamr.com/jumpy

The result of Part 1&Part 2

Let’s get started with the basics – Setting up the Stage

Working with EaselJS is pretty simple, especially when you worked with ActionScript3 before, as a lot of the methods and classes are based on ActionScript3-equivalents. So basically the first thing you have to do in order to see a result, is to create a canvas-element and set up the “Stage” here is how this can be done:

// creating the canvas-element
canvas = document.createElement('canvas');
canvas.width = 500;
canvas.height = 250;
document.body.appendChild(canvas);

// initializing the stage
stage = new Stage(canvas);

However, if you tried this out, it wouldn’t bring you that much of a result, because in order to actually see something the Stage has to be ‘updated’ (stage.update();) by EaselJS, also this is something, that has to be done every frame – so to do that, we can setup an event, that will update the Stage every frame.

Ticker.setFPS(30);
Ticker.addListener(tick);
function tick(e) {
	stage.update();
}

Great! Now we have a stage, that is updated with 30 frames/second.

More basics – Adding something to the stage

Now that we’ve setup the Stage, we can obviously still see nothing, because there is no object/image there to display.

The basic flow of doing this is to: 1) Preload an Image then 2) Create an DisplayObject with that image and finally 3) add this DisplayObject to the Stage(or another Container)

var img = new Image();
img.onload = onImageLoaded;
img.src = 'asset/myImage.png';

function onImageLoaded(e) {
	var myBitmap = new Bitmap(img);
	stage.addChild(myBitmap);
}

Preloading:
Some might ask here, why I’m not introducing PreloadJS to preload all the assets (or in this case: one asset) – well PreloadJS is a very nice way to do so – and I also recommend using it for some projects, but I tried running the app with the cocoonJS-launcher and receiveed a big load of Errors from cocoon(due to cocoon’s limited JS-parsing). Now this is NOT the fault of PreloadJS, however since preloading assets is nothing super-complicated, that requires super-extensive knowlege(basically one function), I chose to use an own 5-line implementation to achieve this.

Great! – So how do I make a game from this?

Well, a typical game usually needs the following things:

• Part 1: User-Input (Keystrokes, MouseClick, Touch)  & Movement
• Part 2: Collisions between objects
• Part 3: Animations

User Input

To listen to userinput-events we first have to distinguish if the device is a touch-device or has a regular screen and add the according event listeners.

//check for a touch-option
if ('ontouchstart' in document.documentElement) {
	canvas.addEventListener('touchstart', function(e) {
		handleKeyDown();
	}, false);

	canvas.addEventListener('touchend', function(e) {
		handleKeyUp();
	}, false);
} else {
	document.onkeydown = handleKeyDown;
	document.onkeyup = handleKeyUp;
	document.onmousedown = handleKeyDown;
	document.onmouseup = handleKeyUp;
}

function handleKeyDown(e)
{
	// execute things on KeyDown
	// e.g.
	hero.jump();
}

function handleKeyUp(e)
{
	// execute things on KeyUp
}

This is pretty straight forward and should widely explain itself.

Movement

To create movement, the simples thing to do is e.g. to alter the position of an object a little bit every frame, just like this:

function tick(e) {
	//this will move the object down by 1 pixel
	myBitmap.y += 1;
	//this will update the stage
	stage.update();
}

However in order to get the whole thing not too messy, once there are more objects involved in the scene, we should setup an own class for each object, or at least each object that is moving, as an example I put together the following:

(function (window) {
	function Hero(image) {
		this.initialize(image);
	}
 	Hero.prototype = new Bitmap();

 	// save the original initialize-method so it won't be gone after
 	// overwriting it
 	Hero.prototype.Bitmap_initialize = Hero.prototype.initialize;

 	// initialize the object
 	Hero.prototype.initialize = function (image) {
 		this.Bitmap_initialize(image);
 		this.name = 'Hero';
 		this.snapToPixel = true;
 	}

 	// we will call this function every frame to 
	Hero.prototype.tick = function () {
		this.y += 1;
 	}

 	// this will reset the position of the hero
 	// we can call this e.g. whenever a key is pressed
 	Hero.prototype.reset = function() {
 		this.y = 0;
 	}

 	window.Hero = Hero;
} (window));

With the Hero-class implemented, we can now create a hero object and apply some interaction, all together it would look like this:

if ('ontouchstart' in document.documentElement) {
	canvas.addEventListener('touchstart', function(e) {
	handleKeyDown();
	}, false);
} else {
	document.onkeydown = handleKeyDown;
	document.onmousedown = handleKeyDown;
}

var	stage,
	canvas,
	hero,
	img = new Image();

function init() {
	canvas = document.createElement('canvas');
	canvas.width = getWidth();
	canvas.height = getHeight();
	document.body.appendChild(canvas);

	stage = new Stage(canvas);

	img.onload = onImageLoaded;
	img.src = 'assets/hero.png';
}

function onImageLoaded(e) {
	hero = new Hero(img);
	stage.addChild(hero);
	hero.reset();

	Ticker.setFPS(30);
	Ticker.addListener(tick);
}

// move the hero down by 1px
// and update/render the stage
function tick() {
	hero.tick();
	stage.update();
}

// whenever a key is pressed then hero's
// position will set to y=0;
function handleKeyDown(e)
{
	hero.reset();
}

init();

here’s how it should look like(depending on the background-color, that you chose for your html-body):

Of course this is very basic, and the movement is absolutely not realistic, since there is no acceleration in the movement, but we can fix this by adding a velocity-object to the hero, just add the following:

//add this to the "initialize"-method
this.velocity = {x:0,y:12};

//now we update the "tick"-method with:
this.velocity.y += 1;
this.y += this.velocity.y;

//and this goes into the "reset"-method:
//getHeight() is a utility-function, but can also be
//replaced with a hardcoded-number
this.y = getHeight() / 1.25;
this.velocity.y = -15;

and this is how it should look like by now:

Awesome, now we have a basic “game”, with a character falling down, that will be reset on any user-input. The next parts are going to cover collisions and animations.

You can download the source-files here: download

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