An HTML5 top-down physics-based puzzle game layed out in MVC fashion, rendered using a combination of DOM, SVG and canvas.
The game is written in CoffeeScript, bundled with Browserify and wrapped as a Cordova cross-platform app, but can also be executed and tested in the browser.
Also, the styles compile from LESS CSS and UI components are rendered using pre-compiled Handlebars templates.
The coffeescript source of the app is all contained in src/
The directory structure is layed out as follow:
- core - The web-app framework core (Template rendering, routing, UI, ...) is contained in
- views - All view controllers. GameView contains part of the base game mechanics
- game - The game engine core (World, Viewport, Entity, ...) is contained in this directory.
- behaviours - The bahaviours of all game entities that determine the game logic
- ui - UI elements and modules
- helpers - Shared utilities
Includes requirements to build the app locally and run with a the local server for browser testing and also to deploy to a cordova build
- Node.js
- Coffeescript - To build the web source and run the server -
sudo npm install -g coffee-script
- Cordova command-line interface - To build mobile source -
sudo npm install -g cordova
git clone git@github.com:tancredi/flickblaster-game.git
cd flickblaster-game
npm install
Now you just have to compile the app and run the server
Build the app using Cake
cake build
- Built the app oncecake watch
- Watch for changescake docs
- Update documentationcake manifest
- Generate HTML5 cache manifestcake downsize
- Generate resized assets for different pixel-ratios - **Needs imagemagick
- less - Compile
less/index.less
intowww/compiled.css
- handlebars - Pre-compile Handlebars templates in
templates/
intowww/js/templates.js
- coffee - Compile the CoffeeScript source in
src/
in Javascript insidelib/
- bundle - Wrap the generated JavaScript in
lib/
using Browserify into a singlewww/js/app.js
To start the server, run
npm start
You can open your browser at http://localhost:3000 and start playing
First, you may have to setup your environment to build for ios / android. For instructions on how to do that read the Apache Cordova Documentation:
Run cordova build
to build the app to all configured platforms.
You can also run cordova build [platform]
to build to a specific platform. ios
and android
are already configured in the project.
Find the generated builds in the platforms/
directory.
For more information about the Cordova Commmand-line interface read the official documentation.
A map of the core directories of the app
*
├── docs - Contains Codo documentation
├── less - Contains the LESS source
├── platforms
│ ├── android - Android app
│ └── ios - iOS Xcode project
├── plugins - Cordova plugins
├── src - App source
├── templates - Handlebards templates
└── www - Web-app root
├── game - JSON Game data
└── js - Compiled and vendor JavaScript
The web app framework taking care of views, transitions, routing, rendering of the templates, etc.. is contained in src/core/
and contains the following modules:
src/core
├── BaseView.coffee - Base view controller class
├── device.coffee - Module providing information about the used device
├── renderer.coffee - Template storage and rendering
├── viewTransitions.coffee - All available transitions between views
└── views.coffee - Manages views and routing
Most modules and classes relative to the actual game engine are contained in src/game/
, except for the GameView class contained in src/views/
.
The game directory is organised as follows:
src/game
├── World.coffee - World class - Ties together the engine
├── behaviours - Behaviour classes that apply to Entities and define the game logic
├── components - Core game classes (Loop, Viewport, Layer, physics, ...)
├── config.coffee - Configuration settings used across the game modules
├── controls - Game controls classes
├── items - GameItem Classes (Entity, Sprite, Body, ...)
└── utils - Shared utilities and modules
The game is tied together by the World, which contains Layers and a Loop, a Viewport and the Box2D physics world
The Loop updates the game at every accessible frame depending on the device performance using requestAnimationFrame
or falling back to vendor polyfills or a simple setTimeout
loop.
It provides a simple use
method to bind callbacks to every update.
The Viewport wraps the stage element and takes care of moving it around, scaling it to fit the screen size and is used by other modules to translate game coordinates into screen coordinates and vice-versa.
The Layers contain different types of game items. They take care of separating it's children and updating at every iteration of the World's Loop
Gamt items are the player, targets, lasers and everything that appears on stage. They all extend from BaseItem, and there are three main types of them:
- Body - Bodies are bi-dimensional physical objects in the stage, they are added to the Box2D World and can be of three types:
circle
,rect
andpoly
- Sprite - Sprites are visual elements, they can be animated and contain decorators, which are visual sub-elemtents used for effects
- Entity - *Entites are the main players on the scene - They contain bodies and sprites and can be associated to a Behaviour *
Behaviours are instanciated from Entities, depending on the entity behaviour
property, usually determined through the editor or by a preset.
They are passed the parent Entity and World, and they get updated at every *Loop iteration, so that they can manipulate properties and events around them freely.
Behaviours determine the base game-logic.
The documentation contained in docs/
is generated using Codo.
Generate an updated version by running cake docs
.
express
: Express 3 - Used to run the servercoffee-script
: Coffeescript - Used to compile and run the gamebrowserify
: Browserify - Used to bundle javascript modules for the browserwatch-tree-maintained
: Watch-Tree - Used to set up watch tasksasync
: Async.js - Used to ease asynchronus operationscli-color
: Cli-color - Used to easily display colors in the consoleless
: [LESS CSS](http://lesscss.org/ - Used to pre-process the CSS)handlebars
: Handlebars - Used to pre-compile templatescodo
: Codo - Used to generate the documentationretina-downsizer
: Retina Downsizer - Used to generate resized assets for different pixel-ratios
A Sublime Text project is provided in the repository (flickblaster-game.sublime-project
).
The project makes it easier to browse through the directories of the project without being disturbed by compiled output, dependencies, mobile builds, documentation and superfluous directories or files.
Thanks to Ali Tocher for designing the sound effects