gamelab / kiwi.js

Kiwi.js is a blazingly fast mobile & desktop browser based HTML5 game framework. It uses CocoonJS for publishing to the AppStore.

Kiwi.js 1.4.0

Kiwi.js is the world's easiest to use Open Source HTML5 game framework for making both mobile and desktop HTML5 browser games.

Our focus is blazingly fast WebGL rendering and complementary tools to make professional quality serious games. We use CocoonJS for publishing games and App creation.

Version: 1.4.0 "Cole"

• Visit the Official Website
• Follow us on Twitter
• Explore examples for Kiwi.js
• Read our API Documentation
• Browse our Plugin Repository
• Contact us for more information

##Welcome to Kiwi!

Born out of a desire to democratize HTML5 game development and to make something that we love available to the masses, we bring you Kiwi.js.

We don't mean to brag (too much), but Kiwi.js is fast. With hardware accelerated WebGL rendering, you can expect your games to be easily deployed across mobile and desktop browsers. But wait, they can also be deployed to mobile devices as native apps, using the CocoonJS framework.

Our mission is to follow the best open source community practices. We're backing that up by providing professional support when its needed, so everyone — commercial developers as well as indies — feel the love.

And we do think you're going to feel the love. What couldn't you love about a game engine that is named after a fluffy adorable bird and one of the world's greatest game inventors?

##How to Guides

Have you ever been trying to figure out how to do something on a website and the help pages resemble a Goosebumps choose your own adventure book? So have we, which is why we have spent literally hundreds of hours writing good help documents for Kiwi.js developers.

Our Official Documentation Codex is here if you do get stuck.

Release Notes for this Version

Number tags refer to GitHub issues.

v1.4.0 "Cole"

New Features

• Much faster rendering! Render pipeline caches the results of matrix concatenation, overcoming a significant bottleneck. Also uses cached data objects during rendering, rather than recreating assets on the fly. Depending on scene composition, this may yield a 10-50% performance improvement. Hint: Objects that don't transform are more performant.
• Geom.Transform.ignoreChild property added. Defaults false. If set to true on a Group or State, its children will not inherit transforms. They will be positioned from (0, 0). This can save a matrix concatenation operation for every object in a group that doesn't move, resulting in significant performance gains. It's also faster to implement than Geom.Transform.ignoreParent from v1.3.0 if you have several children.
• Added Geom.Intersect.rayToCircle() intersection check. This completes the geometry intersections. (#170)
• Geom.Ray now inherits from Geom.Line. This gives it a more robust feature set. (#170)
• Kiwi.Geom.Matrix.equals() method added.
• Add state property to Component.
• Kiwi.Plugins is now a TypeScript module, allowing TypeScript developers to make plugins natively. (#208)
• File param timeout added; file timeouts now default to null. This allows the user to set loading tolerances. By default, files will attempt to load forever. This can prevent crashes on slow connections.
• State.destroy now explicitly destroys members; destruction of tracking list is more robust. This overcomes some issues which might occur when switching states.
• File load checks status code and response for greater robustness.
• Optimised GameObjects.Tilemap.getOverlappingTiles().
• Nicer layout in preloader template.
• Check out http://examples.kiwijs.org/ for examples covering every facet of KiwiJS development.

Deprecations

• glMatrix library removed. This was used for a single call during WebGL rendering. Our own matrix code seems to perform just as well. In addition, glMatrix will load itself into a different namespace if certain other frameworks are in use, which results in a crash. Rather than fork or work around glMatrix, we decided to remove it entirely, reducing the size of KiwiJS. If you need glMatrix functionality, you may obtain the stand-alone library from http://glmatrix.net/. Thanks to the team at Cerebral Fix for bringing this to our attention! (#136)

Bug Fixes

• Stage.rgbColor now correctly interprets all values in range 0-255. (#198)
• Audio now loops and stops correctly. Previously, it might loop indefinitely without making sound after the first loop, which is neither a proper loop nor a proper stop. (#199, #207)
• Console error will be reported when a texture atlas JSON could not be loaded (#200)
• Camera.transformPoint, Camera.transformPointToScreen, Box._rotateRect, and Box._rotateHitbox now copy concatenated matrices, rather than operating directly on the matrix. (#201)
• Sound.AudioManager._unlockedSource now passes a required parameter under iOS Safari. (#203)
• Eliminated flickering at high frame rates on some devices in CocoonJS. (#204)
• Prevent renderer crash when creating a shader after at least one frame has been rendered. (#210)
• Touch events fixed in Internet Explorer 11. Thanks to @benliddicott for the fix! (#212, #213)
• Geom.Transform.anchorPointY now updates correctly. (#216)
• Stage visibility changes are more robust.
• Kiwi.Files.File now supports proper parsing of Data files.
• Data files now succeed properly when dealing with null variables.
• Remove version property from bower.json (contributed by Kevin Kirsche).
• Correct documentation of Kiwi.Input.Keyboard _keyPressed and _keyReleased methods
• FileStore.removeFile now destroys properly
• @radarhere fixed typos in the documentation.
• You can now stop the RAF from executing. (#211)

More details can be found on the Kiwi.JS repo under the 1.4.0 milestone

Previous Changes

View the changelog for a list of changes from previous versions.

##Features

####Powerful Rendering Kiwi uses a custom built WebGL rendering system for targeting modern mobile and desktop browsers as well as mobile apps through CocoonJS.

Not only is Kiwi lightning quick but it is also extendible, meaning that fellow contributors can easily write their own powerful rendering Plugins and Add-ons using WebGL Shaders. For instance our WebGL Particle Plugin creates stunning special FX using this system.

Of course, you can render to canvas too, which means older browsers, and mobile browsers, don't miss out.

####Mobile Publishing Kiwi.js is closely aligned with Ludei's CocoonJS. You can use Cocoon to wrap up your game and play it on iOS or Android devices.

####State Management A state management system lets you easily move between and manage game states. Each state has an optional preloader phase, a create phase, an update loop, and a destroy phase. Each of the phases are highly configurable.

####Flexible Asset Loading and Management It's easy to load in images, sound and data. You can decide when you want it to load (e.g. in a single payload at the beginning, or on a per state basis). When your assets are loaded they're super easy to access from data libraries.

####Gameobjects - Sprites, Images, Textfields Gameobjects are objects that get rendered in your game. Whether they're frame-based sprites, webGL particles, static images or text fields, they all can be moved in the game world and placed in the scene graph.

####Entity/Component system Each gameobject is an "Entity" and can have "components" attached to it. Components are small pieces of code that do something useful. For instance the arcade physics system is implemented as a component. If you want your game object to use physics, simply attach a physics component to it. Some of the standard gameobjects have components such as animation already attached. You can also write your own components.

####Scene Graph (Grouping objects) The scene graph represents all of the gameobjects that visible in your gameworld. You can group objects, and place groups within groups. You can animate and move your objects and groups and they'll behave in a consistent manner depending on how they are nested.

####Animation Sprites have an animation component that enables frame by animation from spritesheets and texture atlases. You can easily define frame sequences and frame lengths, play, pause, loop and reverse animations. There is also a built in tweening system.

####Input (Including Touch) Kiwi.js supports input for mouse, keyboard and of course touch. Mouse and touch events are easily handled by Kiwi.js pointer objects, so in most cases you don't have to worry about where the input is coming from.

####Camera Your game world is viewed through a controllable camera, which you can move and spin.

####Tilemaps Kiwi.js has support for tilemaps, including multiple tile layers. The Tiled map data format is supported, including isometric tiles. You can programatically generate tile maps, and once a tile map is created you can easily manipulate the data to change the tilemap dynamically.

####Audio Kiwi.js supports the WebAudio api, and falls back to using <audio> tag when it is not available. Audio sprites are also supported, unless of course your device happens to be some weird futuristic ghetto blaster.

####Monetization As fellow game developers we know what it is like to be hungry, shivering on the corner holding a can of change in one hand and a damp "will code for cash" cardboard sign in the other.

Because of this, creating an In-App Purchasing Plugin to allow you to monetize your games was a top priority and is available now.

CocoonJS users can easily add a virtual currency to consumable goods via the AppStore.

####Plugin System As part of our dedication to open source principles, the plugin system lets developers extend many aspects of Kiwi.js. The rules around creating them are unobtrusive, making plugins easy to create and attach. Plugins will soon be able to be sold in the upcoming Kiwi.js marketplace.

####Integration with powerful tools Kiwi.js is part of a larger ecosystem of products which will enable you to create games and game content using specialised tools such as the Gamefroot cloud based game building solution. Because you can never get enough power

##Getting Started

There are several ways to get started, starting from scratch is the generally accepted way to go about this, but if you want to get up and running even faster, Kiwi.js "Blueprint" games will help get your game building experience off to a flying start.

Choose from any of the following:

• HTML5 match-three game
• HTML5 hidden object
• HTML5 dressup game
• HTML5 breakout game
• HTML5 roguelike game
• HTML5 distance flyer game

There will be an ever increasing library of free and premium blueprints to get you started.

##Starting from scratch

The easiest way to start with a blank game is to take a copy of the /gameTemplate folder. This contains a recommended folder structure and all default files already in place.

You will need to use a web server to open the index file. We suggest XAMPP, WAMP or MAMP.

A more advanced, but still simple, way to create a blank game is to use the Kiwi.js Yeoman Generator. This will create build files and other goodies for you as well.

###Viewing the examples

We have a throng of examples. So many, in fact, that one kiwi got tired carrying them all. As generous souls, we put them in their own repo. Check out the examples repo and look in tutorials/core.

Also, don't forget to check out the examples site where we demo all the library features and the cool plugins available to you.

###What's in this repo?

Note: If you just want to use the framework, the kiwi.js and kiwi.min.js files are located in the /build folder, and the docs in the /docs folder, and there is a template game in the /templateGame folder. You probably don't need to worry about the rest of the repo!

###Folders

• build - The kiwi.js and kiwi.min.js files
• src - The kiwi.js framework source code
• docs - API documentation on the Kiwi.JS framework.
• docstyles - Used to store assets for building docs.
• templateGame - An example TemplateGame to help you on your way to developing a Kiwi.JS game.

###Files

• .gitignore - mask files from git
• bower.json - see below about bower installation
• gruntfile.js - used for building the framework
• license.txt - The MIT license
• package.json - the npm package used for installing dev dependencies
• README.md - this file!
• tslint.json - the tslint configuration file

##Getting and building the library

###Bower If you use the Bower package manager you can install kiwi.js with

bower install kiwijs

###Yeoman If you use the Yeoman scaffolding system you can install a blank kiwi.js game with

yo kiwigame

It's best to look at our Yeoman Game Generator repo for full details.

###Using Grunt

This requires installing node.js, and the grunt CLI package. There are a few thing you can do with grunt, including linting and compiling the typescript, uglifying the result and compiling the docs.

To build, lint and uglify use the default

grunt

To do all of the above plus compile the docs

grunt full

To just build the docs

grunt docs

The csproj and grunt compilation methods both output a single kiwi.js file in /build Grunt will also create a min.js version and also output a kiwi.d.ts definition file in /build as well

###Using Visual Studio

• Requires Microsoft Visual Studio 2013 or later.
• Install the TypeScript plugin.

There are csproj files for the main project.

We advise that you build using Grunt, as this will correctly concatenate certain additional files.

##Extending Kiwi.js

You want Plugins? We got Plugins!.

The concept of Plugins, and how they might apply to game creation, is something we're very interested in. Years of working in the open source space and hacking open source tools has provided us with the qualifications necessary to create a system that works for you.

We built Kiwi.js from the ground up as a plugable system. You can add multiple plugins to your game, or write plugins yourself. Soon, you'll even be able to sell your own plugins in the Kiwi.js marketplace.

Kiwi.js is built in such a way that your plugins can do very simple or very powerful things. For example:

• A utility plugin, such as an inventory for keeping track of items a player has collected.
• A gameobject plugin, that creates programmable tower defense unit.
• A component plugin, such as a specialised physics system that can be applied to any gameobject.
• A rendering plugin, that creates new renderers and WebGL shaders that give your game an entirely different look.
• A service plugin, such as an ad-network or in-app purchasing system.
• Stop your bathtub from automatically draining whenever you try to take a bath.

To learn about building Plugins view the tutorials on kiwijs.org. You can also get started with Plugins using the Kiwi.js Yeoman Plugin Generator.

##Tools

Visual Game Maker

Gamefroot is the worlds most powerful and easy to use browser-based game editor.

We've partnered with Gamefroot and we're pleased to let you know that Kiwi.js integration is in development and coming your way soon.

Stay tuned for more updates and more tools!

##Roadmap

Here are some of the features planned for future releases.

• Productivity tools!
• Multiple cameras with filters
• A whole new world!

##Contributing

We'd love for you to get involved and help make Kiwi.js the best damn game framework in the world! If you'd like to contribute please get in touch, fork/clone the repo and have a dig around.

• If you find a bug then please report it on GitHub issues
• If you have feature request, or have written a game or demo that shows Kiwi in use then please get in touch. We'd love to hear from you! Please email: [email protected]
• If you have a pull request for Kiwi, please only do so against the dev branch and not against the master branch.
• Before submitting a Pull Request please run your code through JSHint to check for stylistic or formatting errors.

##Bugs?

If you discover a bug and find yourself wanting to jump in and help make the world of HTML5 gaming a better, less buggy, place, please add said bug to our issues tracker with as much information as possible, especially source code demonstrating the issue.

https://github.com/gamelab/kiwi.js/issues/new

##Community

A massive shoutout to our contributors on Github!

• Ross Kettle @rosskettle
• Ben Harding @BenjaminHarding
• Phil Wickliffe @stupidlikeafox
• Zach Frieberg @zacharyf1991
• Locky Reid @lockyreid
• Ido Yehieli @tametick
• Ellison Leão @ellisonleao
• Kevin Johnson @cavemanpi
• Dan Milward @danmilward
• Julien Castelain @julien
• Benjamin D. Richards @BenjaminDRichards
• @ic5y
• Hector Zarco Garcia @zzarcon
• John Wu @tjwudi
• Ryan Loader @RaniSputnik
• @rydairegames
• @benliddicott
• Kevin Kirsche
• Andrew Murray @radarhere

Kiwi.js also uses code from a number of open source projects. Effort has been made to clearly identify authors in the code comments. If you notice and missing or incorrect attribution please let us know.

##License

• MIT (see license.txt for details)

kiwi.js's Issues

Replace all matrix operations with gl-matrix.

Cocoon/WebGL intermitant flashing on some Android devices

TextureAtlas base class doesn have 'name' property set correctly

currently sets to 'AtlasName'.
this is not the case for the derived class 'SingleImage', haven't checked spritesheet class
name appear correctly in textureatlas library on the state
probably set wrongly by the preloader

WebGL - TextureAtlases not updating upon dirty being toggled

Original Issue: #37

Found out that TextureAtlases are no longer updating when their 'dirty' property is being set to 'true'. Mean that TextFields are no longer rendering in WebGL.

Preloader images render weirdly with WebGL

I'm guessing this is because the shader hasn't loaded yet.

reorder kiwi.ts file so that js outfile is in logical rather than alphabetical order (easier to read)

WebGL Renderer Blend Mode Manager required

Current implementation of WebGL particles plugin sets the following blendfunc:

gl.blendEquationSeparate(gl.FUNC_ADD,gl.FUNC_ADD)
if (this._config.additive )
    gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ONE,gl.ONE);
else
    gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE,gl.ONE);

After drawing, it resets blend modes:

//return to standard blendfunc
gl.blendFunc( gl.SRC_ALPHA,gl.ONE_MINUS_SRC_ALPHA);

This is undesirable behaviour, particularly if the standard blendfunc isn't actually as specified in the particle plugin.

A more robust solution would be as follows:

The render manager should take care of setting blendfuncs, and record an internal state of the last set blendfunc. Individual renderer objects can then request a blendfunc from the manager when they begin rendering every frame. If the manager identifies that the blendfunc has not changed since it was last set, it can skip setting the blendfunc and avert unnecessary GL API calls. The manager should also initialise a default blendfunc on launch.

This will require modifications to the WebGL Particle Plugin, the KiwiPreloader object, and any other plugin or object that manually sets blend modes under WebGL.

rotPoint x and y need an alias - transformPoint

The rotPoint properties on the transform would be better called transformPoint - due to use in scaling as well as rotation. Make a non breaking change by introducing an alias getter/setter for rotPoint called transformPoint.

Audit console.log messages

gl-matrix should be included as a part of the Kiwi.js distribution rather than as a dependency

Setting the Stage Size When Creating Game Object

I think it would be useful to be able to set the game size when creating a game object. This could be done with an optional parameter.

Support for bower.js

It would be great to have support for BowerJS (http://bower.io/).

Investigate and implement dirty property of Box Component.

Modification of stage background colour via numeric values.

Change or add the ability to modify the background colour via RGB colour streams. This would allow developers to 'tween' and change the background colour more easily.

"idtkscale:ScaleAspectFit" css function doesnt work with webgl rendering

this.game.stage.canvas.style.cssText = "idtkscale:ScaleAspectFit";

the code above works in canvas, but not webgl.

List of things to investigate around States

• State Config Object.
  • Investigate use of 'hasPreloader'.
  • 'isPersistent'.
• setType method. Currently is unused.
• Different types of 'states' when adding to the StateManager.

Refactor and simplify Attributes detection for GL Renderer

Autodetect WebGL

On boot - detect webgl and default to webgl rather than canvas
config options

• nothing = default to webgl - fallback to canvas
• RENDERER_WEBGL - force webgl
• RENDERER_CANVAS - force canvas

update the device detection script for webgl detection

TileMap objects: missing layers property

I am creating a tilemap step by step referencing this post. And my code is

var K = Kiwi,
  game = new K.Game(),
  state = new K.State('state');
game.states.addState(state);

state.preload = function() {
  K.State.prototype.preload.call(this);
  this.addJSON('tilemap', 'tilemap.json');
  this.addSpriteSheet('tiles', 'tileset.png', 48, 48);
}

state.create = function() {
  K.State.prototype.create.call(this);
  this.tilemap = new K.GameObjects.Tilemap.TileMap(this, 'tilemap', this.textures.tiles);

  this.addChild(this.tilemap.layers[0]);
}

game.states.switchState('state');

Then I got Uncaught TypeError: Cannot read property '0' of undefined. With the help of inspector, it seems like the layers property is missing from this.tilemap. I am using the latest version of Kiwi. When I switch to the Kiwi provided by the post, everything turns out to be just fine.
So there must be something wrong with TileMap class in the latest version of Kiwi.

Cheers!

restarting states cause error in update()

after calling this.game.states.switchState("myState"); to restart a state with an update() function, the following error happens:

Uncaught TypeError: Cannot read property 'exists' of undefined kiwi.js:4268

line 4268 in kiwi.js is "if (this.members[i].exists === false) {", so it seems it is in the middle of an update after destroy() was called, which removed all members.

Current work around is to wrap Kiwi.State.prototype.update.call(this); with try{...}catch{...}

Scaled image's x, y positions do not update.

When scaling an image down to half it's size, the position is not updated and "top left" becomes "old top left even though the scales changed and the sprite is now elsewhere"

Game running slow with Arcade Physics on Windows safari

EDIT:

Games just runs slowly on that version of Safari. I really doubt many, if any, people use safari for windows.

---

USING SAFARI 5.1.7 for WINDOWS (Not mac) (Latest version as of 30/05/2014)

Game on this webpage is running extremely slow:

http://www.kiwijs.org/documentation/tutorials/using-arcade-physics-in-kiwi-js/

Have tested other games with same version of Safari on PC and have not had problems.

Run smoothly with:
MAC:
Safari (tested on two different macs)
PC:
Chrome
IE
Firefox

Debug Canvas Bugs

• Multiple calls of 'createDebugCanvas' creates multiple debug canvases.
• The debug canvas doesn't appear above the regular canvas.

Rationalise use of children/members on groups

Kiwi.Input.Keyboard API needs updating

The descriptions of onKeyUp and onKeyDown do not specify what they parameters are returned to callbacks applied.

(keyCode, key);

TextField GameObjects Not Rendering in WebGL

The TextField GameObjects aren't rendering in WebGL.
Does not produce game crashing bugs, they just do not appear.

Internet Explorer Input events not firing

Signals added directly to the Input Manager Internet Explorer that Signals do not fire on Internet Explorer when on desktop and the Mouse is being used.

Does work if you add callbacks directly to the Mouse Manager instead but we do want parity with how is intended to be used.

Look into what happens when you flag an entire Kiwi Game for garbage collection

Look into what happens when you flag an entire Kiwi Game for garbage collection and then fix/make changes accordingly.

Box Component: Cell Hitboxes

Allowing the Hitbox of a BoxComponent to have it's dimensions based upon the current cell of the GameObject it is applied to hitbox.

Add helper functions for creating timers

Javascript Kiwi exceptions console information is too vague.

In debug mode need to have a way of receiving useful information when Kiwi crashes, especially when testing on devices.

WEBGL Canvas not clearing from previous state when it has nothing to render

When Switching from the loading state to play state that has nothing visible to render.

In CANVASit runs as expected (eg. blank state that has nothing on it)

In WEBGL the state does not clear the canvas and therefore show what was last seen from the previous state

Investigate you of dirty property on camera - where is it being used

Cameras transform/matrix not correctly taken into account in WebGL.

The games camera won't move in WebGL.

game.input.isDown does not work in cocoon

Tried to use the touchbutton plugin with cocoon, but the touch button could not register any presses.

Optimise Uniform updates in GL Renderer

Fix bug where setting the visibility of a Group does nothing.

Fix a bug where when you set the groups visibility to false, the entire group should not appear.

Just needs implementation on the renders.

Box draw method

The draw method on the box component doesn't take a Camera into account whilst rendering.

HUD Icons not appearing when using Textures which are Canvas's

The HUD Icon Widget doesn't apply a valid background image when Texture used on the Icon use's a Canvas element instead of an Image.

Group Alpha

Allow alpha to be applied to a group.

• Default alpha of a group is 1.
• If a groups alpha is a 0.5 and a member of that group is also at 0.5, then the members will visually look like it has an alpha value of 0.25 (0.5 * 0.5).

Collision detection on irregular objects

Is there any support for collision detection on irregular objects?

Textures not rendering correctly immediately proceeding RebuildLibraries call - WebGL Rendering Issue

In a special case when creating a custom preloader and using RebuildLibraries, the WebGL rendering can go a little bit crazy with Alpha values.
Making whole sprites either go between black/white (as a sprite fades in/out) or make in-between opacities whiter than they appear.

Console message pertaining to DOM element the game is to be inserted to doesn't return correct value.

Move examples to a new repo

Move the examples to a new repo where people can contribute there own examples more easily. This will require removing php and replacing with node.

Window currently in focus plus events

Investigate having some events for when a window that a kiwi game resides on goes out of focus/comes into focus. Then can look at pausing the update loop/game timer/e.t.c.

Getting started typo

In the getting started page:
"Since Kiwi is a JavaScript game engine, all you need to use it is a modern web browser and a text editor. There are many good Text Editors out there ***too choose from so we will let you decide on that, but a good browser that we recommend is chrome since it supports majority of the latest HTML 5 API’s."

should be TO not TOO . I know it's not important but I thought I'd point it out anyway

Download link in docs for "Basic Kiwi.js game" is wrong

http://www.kiwijs.org/documentation/tutorials/creating-a-basic-kiwi-js-game/

The source download points tot the SwitchStates tutorial, and not the basic game.

Input component does not take camera movement and position into account

created a platformer with an on screen directional pad, which had the pad move with the scrolling stage improperly. the input remained on the correct position incorrectly.

Improve the tslint configuration file

Hi guys, i was just talking to @danmilward and i suggested him to add on the gruntfile a tslint task feature. I've implemented this on #4 but i'm getting a lot of warnings caused by the tslinter and the initial configuration file that i've added as well.

I think we can work on this configuration file to see what's important and what isn't, for us to create good and clean code.

Hope to hear from you guys!

Transformations of an entire state.

Fix a bug where when you apply scale/rotation on a state, positioning coordinates of its members will not longer be correct.