Cross-engine hackable game editor for mobile and HTML5 games.

License: BSD-3-Clause

Language: JavaScript

Documentation | Community | Contributing | Examples

Fireball Game Engine

release badge Dependency Status devDependency Status experimental

Fireball is a hackable game editor for creating mobile and HTML5 games, providing powerful scene editor and other integrated tools for open source game engines such as Cocos2D-JS, Pixi.js. We will be supporting more engines in the future.

fireball-0 5

Fireball consists of:

Fireball is a cross-platform software powered by Electron and Polymer. Currently we test our distribution on Mac and Windows 7/8.1. Issues and PR on other platform are welcome!

Learn what's going on from Fireball Beta Roadmap.



For Windows user, you need the following environment set up to be able to build nodejs native modules:


In cloned project folder, run the following command to setup dev environment:

# Initialize gulp task dependencies
# npm is a builtin CLI when you install Node.js
npm install

This is all you have to do to set Fireball development environment.

Run Tasks Manually

Behind the scene, npm install script will run a series of gulp tasks. If anything goes wrong during the bootstrap process, you can manually run these commands to get back on track:

# Initialize git submodules
git submodule update --init

# Install builtin packages
gulp install-builtin

# Install runtime packages
gulp install-runtime

# Install fireshell(electron)
gulp update-electron

# rebuild npm native modules for Electron
gulp npm-rebuild

# Install bower packages
bower install

Choose Electron Download Mirror

Download Electron can take time, especially when you're on the wrong side of wall. We use electron-prebuilt for Electron binary download. You can choose if you want to use the china mirror during gulp update-electron task.

The first time you run this task (this task is included in npm install process), you'll be asked if you want to use China mirror for Electron downloading. A json file mirror-setting.json will be created to record your choice, like this:

// local-setting.json
    "mirror": "china" // this value can be 'china' or 'global'
                      // depending on your answer

You can change this file anytime to choose mirror for Electron downloading again.


Here are ways to run fireball development version:

# Run fireball's dashboard
gulp run

# Open Fireball Package Studio
gulp package-studio

# Open a Fireball project
gulp fireball --path path/to/project

You can run package studio with path parameter like this:

# Open Fireball Package Studio with default builtin packages
gulp package-studio

# Open Fireball Package Studio with all packages in editor-framework/demo loaded
gulp package-studio --path editor-framework/demo

# Open Fireball Package Studio with a single package editor-framework/demo/grid loaded
gulp package-studio --path editor-framework/demo/grid

Package Studio will detect the path argument you sent to it, if there is a package.json under the path, it will treat your path as a single package, and load it after builtin package loaded.

Otherwise, Package Studio will register your path as a package loading path through Editor.registerPackagePath function, and load any packages under it. This also trigger the watch for the path, so any packages you add to this path after Studio opened, will be loaded automatically.


To get the latest fireball build:

# Update fireball from github repo,
# also update builtin packages and electron binary
# this command will also check dependencies
# and report outdated or missing dependencies
gulp update

# If you want to update all dependencies
# this command will bootstrap and update the whole project and takes long
npm install

# or if you just want to quickly install a missing package:
# please use the semver reported at the end of `gulp update` dependency check
npm install some-npm-package@x.x.x

# If you only want to update bower dependencies
bower install


# Run all tests
npm test

# Run a single test
npm run test -- <testfile...>

# Run test in submodule
npm run test -- editor-framework/test/<testfile...>

# Run All test of a submodule
npm run test -- editor-framework

All test files are located in test folder or submodule's test/ folder.

API Docs

# Generate and preview API docs
npm run gendoc

Use Fireball

Release Version

  1. Download distribute version from release page.
  2. Extract the zip file to a folder of its own. This folder can locate anywhere on your disk.
  3. Click on Mac or fireball.exe on Windonws to launch fireball.
  4. Have fun!

Get Started

Visit to learn how to use Fireball Game Engine.


Checkout Cocos2d-js examples.

Feedback & Contribution

Trouble Shooting

[Windows] error MSB4025: Could not load project file. Invalid character in coding provided.

This error is due to non-ascii character in your home path, please check this guide to rename user profile.

Error: Permission denied (publickey)

Usually this is due to incorrect setup of ssh key. Please troubleshoot with this guide:

npm ERR! version not found: module_name@x.x.x

If you choose to use China Mirror for npm installing during the bootstrap process, you will get all your npm packages from . Sometimes there're lag in syncing package between and, if that's the case, just go to and manually trigger a synchronization. Then you should be good to go.

If you can't even find the package version on , please contact us or report an issue.

Project Statistics

Sourcerank 7
Repository Size 4.91 MB
Stars 372
Forks 42
Watchers 49
Open issues 52
Dependencies 79
Contributors 8
Tags 25
Last updated
Last pushed

Top Contributors See all

Johnny Wu Wang Nan Jare Guo yinkaile adamsay KamiSama Qin Tao Yazhong Liu

Recent Tags See all

0.5.1 September 12, 2015
0.5.0-beta August 28, 2015
0.5.0-alpha.5 August 17, 2015
0.5.0-alpha.4 August 07, 2015
0.5.0-alpha.2 July 17, 2015
0.5.0-alpha-2 July 17, 2015
0.5.0-alpha June 23, 2015
v0.4.0 May 29, 2015
0.4.0 May 29, 2015
v0.3.0 April 30, 2015
0.3.0 April 30, 2015
v0.2.2 April 23, 2015
0.2.2 April 23, 2015
v0.2.1 April 19, 2015
0.2.1 April 19, 2015

Something wrong with this page? Make a suggestion

Last synced: 2017-11-24 18:39:53 UTC

Login to resync this repository