Get Started

Understand the Capabilities

The dim-boilerplate project provides the following features out-of-the-box:

  1. Declarative JSON markup for defining game world scenes, items, and events.
  2. Exploration of the game world via arrow key or gesture-driven menus.
  3. Game world interactions including examining, moving, taking, and using.
  4. Game world puzzles involving sequencing and timed reactions.
  5. Visual backgrounds and text descriptions.
  6. Aural text-to-speech synthesis, voice actor narration, sound effects, music, and ambiance.

Keep in mind that the project is a template for writing adventure games, not a strict framework or engine. You should drop, replace, extend, or otherwise hack any of the included components to suit your needs.

Clone the Boilerplate

The boilerplate project is available on GitHub. Clone it with the following command:

git clone git://

Understand the Contents

The boilerplate project has the following general layout (not all files are shown):

├── docs/                        # source for this documentation
├── dev/                         # development and deployment scripts
└── webapp/
    ├── css/                     # game visual stylesheets
    ├── data/                    # game world assets
    │   └── world.json           # game world definition
    ├── favicon.ico              # game browser bar icon
    ├── img/                     # game iOS startup and touch icons
    ├── index.html
    ├── js/                      # game engine
    │   ├── dim/
    │   │   ├── aural/
    │   │   ├── controllers/     # game interaction controllers
    │   │   ├── events.js
    │   │   ├── input.js
    │   │   ├── main.js
    │   │   ├── pump.js
    │   │   ├── topic.js
    │   │   ├── visual.js
    │   │   └── world.js
    │   └── vendor/              # dependencies
    └── robots.txt

Setup for Development

Push the boilerplate into a new git repository where you will build your game. Alternatively, copy at least the dev and webapp folders to a new directory in the version control system of your choice.

The boilerplate has no web server-side requirements. You can simply put the webapp folder in a web accessible directory (e.g., ~/Sites on OS X, ~/public_html on Linux) and visit the index.html page in a browser. As you make build-out your game, you can simply refresh your browser to immediately see the impact of your changes.

Currently, the boilerplate supports the following browsers:

  1. Chrome on any platform
  2. OS X Safari 6.x


Ultimately, the boilerplate should be compatible with any browser that supports the HTML5 Web Audio API.

Build Your Game

Draft the storyline of your adventure game. Then try to answer these questions.

  1. What is the goal of the game?
  2. What locations will the player visit?
  3. What other people and things exist in the world?
  4. What interactions will the player have?
  5. What challenges will the player face?

Now modify the boilerplate to implement your game ideas. Work through the following levels of modification in the order given, only continuing to higher levels if you cannot accomplish what you need in a lower level.

  • Level 1 - Define your game scenes, items, and events in the game world JSON file using text, sounds, speech, and images.
  • Level 2 - Create new JavaScript controllers to enable new user actions within the game world.
  • Level 3 - Modify the input capture, aural rendering, and visual rendering JavaScript code to support new means of interaction with the user.