Impact

iOSImpact is a set of Objective-C classes and some additional JavaScript that makes it possible to run Impact games on iOS devices without a UIWebView. It loads your JavaScript game source and executes it, but instead of rendering to a Canvas element on an HTML page, it renders to something like a Canvas element that is implemented in Objective-C with OpenGL.

The benefits, compared to running in the iPhone's browser, are better drawing performance (especially on the iPhone4 and iPad, where the larger screen size previously was a problem), perfectly working Audio and no more multitouch issues when pressing several on-screen buttons at once.

Note that only a tiny subset of the original Canvas API was implemented – and not very accurately at that. Most vector drawing functions (lineTo, curveTo etc.) are missing completely and others are implemented differently than in the spec. I'm working to improve this, but at the moment it's very much experimental.

That said, a game written for Impact that doesn't use any of the Canvas API's functions directly, but only uses Impact's classes to draw everything, should work fine.

iOSImpact is compatible with Apple's App Store guidlines. You can download the Biolab Disaster and Drop demo games made with iOSImpact from the App Store.

Please excuse the state of this documentation – it is very much incomplete. And again, please don't expect anything to work. At all. I'm in #impactjs on freenode IRC to help you, but it may very well be that some things are completely broken at the moment.

Prerequisites

To compile the iOSImpact project, you need a Mac and Xcode. I used Xcode 3.2.5 and compiled for iOS 4.2, but it should work with newer versions as well. You should be able to compile and play the iOSImpact.xcodeproj in the iOS Simulator without making any changes. If you want to test your games on real hardware, you need to have an iOS Developer Account from Apple (currently $99/Year).

You will find the complete source of iOSImpact, along with the Jump'n'Run demo game bundled with it, on your download page.

Making your Game Ready for iOSImpact

To make your game work with iOSImpact, you have to require the ios plugins from within your main.js:

ig.module(
	'game.main'
)
.requires(
	'impact.game',
	'impact.font',
	
	…
	
	'plugins.ios.ios' // <- Add this!
)
.defines(function(){

	…
	
});

Please make sure you also have the newest version of the engine itself. Either the one that comes with the iOSImpact ZIP or the one from the Git repository.

(Note that this version changes the way the screen scrolling works: You now have to call ig.game.setScreenPos( x, y ) instead of just setting ig.game.screen.x and ig.game.screen.y)

The only thing you have to change to make your game work with iOSImpact is setting up input. Instead of binding keys from the keyboard to your actions, you have to bind certain screen areas:

if( ios ) { 
	// When the 'ios' object is defined, we're running 
	// inside iOSImpact
	
	// Define an area of the screen as button. The syntax is:
	// x, y, width, height, action
	ig.input.bindTouchArea( 0, 224, 80, 96, 'left' );
	ig.input.bindTouchArea( 80, 224, 80, 96, 'right' );
}
else {
	// Normal desktop browser? Bind keyboard keys!
	ig.input.bind( ig.KEY.LEFT_ARROW, 'left' );
	ig.input.bind( ig.KEY.RIGHT_ARROW, 'right' );
}

These touch areas are invisible. If you want to show some button graphics, you have to draw them yourself. See the main.js of the Jump'n'Run demo that comes with iOSImpact for an example.

If you're using mouse input, binding MOUSE1 and getting mouse coordinates from ig.input.mouse.x and ig.input.mouse.y will still work as expected.

Make sure the screen size you defined for ig.main works on your device. The iPhone has a resolution of 480×320 px, the iPad has 1024×768 px.

By default, iOSImpact runs in landscape mode and will auto-rotate to the current device orientation (LandscapeLeft/LandscapeRight). If you want to run in portrait mode, change the Initial interface orientation setting in the iOSImpact-Info.plist to Portrait.

Performance

Having a lot of draw calls still slows the game down significantly, so you should enable background pre-rendering for all background maps. Note that iOSImpact currently does not support chunk sizes larger than the screen buffer – the default 512 wont work on the iPhone; set it to 256 instead:

// In your game class; Overwrite load level do enable 
// pre-rendering on all background maps when a level 
// was loaded

loadLevel: function( data ) {
	this.parent( data );
	
	for( var i = 0; i < this.backgroundMaps.length; i++ ) {
		this.backgroundMaps[i].chunkSize = 256;
		this.backgroundMaps[i].preRender = true;
	}
}

Sound and Music

iOSImpact loads sound files in Apple's CAFF format, instead of using MP3 or OGG. To convert your sound files to CAF, use the following commands in your terminal:

# sound effects should be in uncompressed PCM format:
afconvert -f caff -d LEI16@44100 -c 1 soundfile.wav

# music can be compressed with AAC
afconvert -f caff -d aac -c 1 music.wav

iOSImpact will play all sound files < 512kb with OpenAL. Above 512kb Apple's AVAudioPlayer is used. You can change this limit in Classes/Impact/Audio/JS_Audio.h.

To make sure Impact searches for .caf files instead of .mp3 or .ogg, include it in the list of sound formats to probe:

// Set this before you call ig.main()
ig.Sound.use = [ig.Sound.FORMAT.OGG, ig.Sound.FORMAT.MP3, ig.Sound.FORMAT.CAF];