naikdij88 / fireball

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

Documentation | Community | Contributing

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 consists of:

• Editor framework for creating multi panel editor UI.
• Engine framework to enable entity-component like workflow for any JavaScript game engine.
• Package Manager for adding and managing editor extensions easily.
• Asset Database for managing game assets with native file system.

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.

Prerequisite

• Install node.js v0.12+ or io.js v2.0+
• Install gulp command line tool
• Install bower command line tool

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

• node-gyp
• Visual Studio Community 2013
• Python 2.7 - make sure you can run python --verson in your command line tool. Read this for setting up path correctly.

Install

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:

//mirror-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.

Run

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.

Update

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 [email protected]

# If you only want to update bower dependencies
bower install

Test

# 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

Feedback & Contribution

• Join our community on slack, then access with http://fireball.slack.com/
• If you have questions about a specific page of documentation, use the disqus sidebar on the left of Fireball Documentation Site.
• If you have any suggestion/feedback/problem, feel free to submit an issue.
• If you want to contribute to this project, please read Contributing Guidelines.

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: https://help.github.com/articles/error-permission-denied-publickey/#platform-linux

Fireball 0.4

We are refactoring Fireball to make it compatible with more open source HTML5 game engines. Fireball 0.5 will fully support Cocos2D-JS api, and we will add more engine support in the near future. Fireball users can use each engine with its original api.

For Fireball 0.4, we have wrapped Cocos2D-JS and Pixi.js with our own API. Please check out the following content.

Download

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 Fireball.app on Mac or fireball.exe on Windonws to launch fireball.
4. Have fun!

Get Started

Visit http://docs.fireball-x.com to learn how to use Fireball Game Engine.

Examples

• Examples - Every Fireball components and features are demonstrated in this project. Check out the example one by one and you'll get what Fireball is capable of.
• Tutorial - Step by step guide to build your first game with Fireball.
• Duang Sheep - Flappy bird clone featuring a jumping sheep!
• 1010! - 1010! clone, play tetris in a 10x10 grid.