Theatre

Theatre is a lightweight, simple and fast javascript game framework.

Overview

Theatre game framework is built in plain javascrit. It helps you create games quickly.

This repository is a demo on top of a generated Theatre game project.

You could simply clone and install this demo to take a look at the lifecycle and how things works, but we strongly recommand to generate and install your own new Theatre game project.

Table of contents

• Installation
  • Generate the project's structure
  • Install the project
• Usage
  • Quick start
  • Distribution
  • Electron preview
  • Production build
• Tree structure
• Asset structure
• Scene structure
• Context
• Lifecycle
• API

Installation

First, you'll need to use our Yeoman generator (see : generator-theatre) to scaffold a new Theatre project.

Generate the project's structure

Start a console then run :

$ npm install -g yo
$ npm install -g generator-theatre

Create the folder for your new project :

$ mkdir <your-game>

Then, generate your project in this new folder :

$ cd <your-game>
$ yo theatre

Once you've done scaffolding your project, you'll need to install the project's dependencies.

Install the project

Start a console then run :

$ npm install

A postinstall NPM script executes a production build of your game.

Usage

We have created a demo scene to help you understand Theatre lifecycle.

Quick start

To start a development server, start a console then run :

$ npm start

It opens a new browser tab serving your game from the dist/ folder (webpack-dev-server doesn't write any output files after compiling. Instead, it keeps bundle files in memory and serves them as if they were real files mounted at the server's root path.).

Distribution

To build your game in any possible way, you'll need to create a distribution of your game. Start a console then run :

$ npm run dist

It creates a prebuild of your game in the dist/ folder which will be used by the Electron preview and/or by the Production build.

Electron preview

To see the preview of the desktop application build of your game (made with Electron), start a console then run :

$ npm run electron

It opens a new browser tab serving your game from the dist/ folder.

WARNING : Don't forget to create/update the distribution of your game before each Electron preview.

Production build

To build your game for production, start a console then run :

$ npm run build

It creates the production builds (executables) of your game in the build/ folder.

INFO : Feel free to check the package.json file if you just want to generate executables on specific platforms.

WARNING : Don't forget to create/update the distribution of your game before each production build.

Tree structure

In the root folder, you'll find this main tree structure :

docs/
|-- index.css
|-- index.html
'-- index.js
documentation/
'-- SGDD.md
sources/
|-- game/
|   |-- assets/
|   |-- components/
|   |-- scenes/
|   '-- systems/
|-- theatre/
|   |-- core/
|   '-- modules/
'-- index.js
webpack.<config>.js

Configuration files

You'll find there three Webpack configuration files (files like webpack.<config>.js) :

webpack.common.js - Webpack configuration for both development and production environments.

webpack.development.js - Webpack configuration for development environment.

webpack.production.js - Webpack configuration for production environment.

Sources folder

The sources/ folder contains the code base for your game :

sources/
|-- game/
|   |-- assets/
|   |-- components/
|   |-- scenes/
|   '-- systems/
|-- theatre/
|   |-- core/
|   '-- modules/
'-- index.js

sources/theatre/ - The framework (the core and useful modules).

sources/game/ - All your source files (all assets, components, scenes and systems).

sources/index.js - The entry point of your game with your presets.

Dist folder

The dist/ folder contains the prebuild of your game :

dist/
|-- electron.js
|-- index.css
|-- index.html
|-- index.js
|-- index.js.map
'-- package.json

dist/electron.js - The entry point for the Electron build.

dist/index.js - The build (production build) of your game.

dist/index.js.map - The sourcemaps of your game.

dist/index.html - The default HTML5 preview for your game.

dist/index.css - The default style of the preview of your game.

dist/package.json - The entry point for the Electron build.

Docs folder

The docs/ folder contains your game preview :

docs/
|-- index.css
|-- index.html
|-- index.js
'-- index.js.map

docs/index.js - The build (production build) of your game.

docs/index.js.map - The sourcemaps of your game.

docs/index.html - The default HTML5 preview for your game.

docs/index.css - The default style of the preview of your game.

Documentation folder

The documentation/ folder contains the documentation for your game :

documentation/
'-- SGDD.md

documentation/SGDD.md - The template of the Short Game Design Document for your game (this is a short version of the usual Game Design Document).

Asset structure

For instance, an asset is defined with the following format :

const asset = {

    'name': 'hero',
    'scope': 'common',
    'source': require('./<path-to-image>/hero.png'),
    'type': 'image'
};

Details :

key	type	description
name	string	name of your asset
scope	string	scope of your asset
source	mixed	source of your asset
type	string of ['dataset', 'image', 'sound']	source of your asset

Usage :

Theatre will expose a getter function for your asset in this.assets.<type>s.<scope>.<name>.

An example for a sound :

const blastGetter = this.assets.sounds.common.blast;

// plays simultaneously the same sound as many times as you want
blastGetter().play();
blastGetter().play();

WARNING : It's better for a sound to be played each time from a fresh call of its getter() function because of the Web Audio API which is not able to play more than once at a time the same song.

Scene structure

Scenes are the place where you'll work most of the time.

A scene is a group of the following methods :

setup (called when the scene boots) - Put there everything (event listeners, variable declarations, states...) you'll need to access during the entire scene lifecycle (especially when the scene restarts).

start (called when the scene starts or restarts) - Initialize there the data of the scene.

update (called each update tick) - Update there the data of the scene (update the logic of your game when time passes).

render (called each render tick) - Draw and redraw there (using data created in the start method then updated in the update method) each entity you'll need to render in the scene (update the display of your game when time passes).

destroy (called just before the next scene boots) - Destroy there everything created in the setup method to prevent spaming the next scene.

Context

Theatre binds its context on each of your methods of your scenes.

Everywhere in your scenes, if you call this, you'll refer to current instance of Theatre. This is very convenient to simplify your workflow and to keep access to Theatre's data and methods at all time.

Lifecycle

Theatre's lifecycle is really simple.

Running the first scene: loading scene

All assets are loading (async) during loading scene's lifecycle. When all assets are loaded, Theatre sets its preloading property to true.

• Theatre boots loading scene (its setup then start methods are called).
• Theatre's game loop starts running (async) update and render methods of loading scene.

THEATRE                   LOADING SCENE
,--------------------,    ,-----------,
| setup scene <------|----|-- setup   |
| start scene <------|----|-- start   |
| ,----------------, |    |           |
| | update loop <--|-|----|-- update  |
| '----------------' |    |           |
| ,----------------, |    |           |
| | render loop <--|-|----|-- render  |
| '----------------' |    |   destroy |
'--------------------'    '-----------'

Switch to the next scene

To switch from current scene to the next you'll have to call Theatre's load() method in current scene's update method with the next scene as parameter.

• Once current scene's update method ends (from current update tick), current scene is destroyed (its destroy method is called).
• The new scene is now defined as the current scene.
• This new scene boots (its setup then start methods are called).
• Theatre's game loop continue as before (but now running the new scene's update and render methods).

Restart current scene

To restart current scene you'll have to call Theatre's restart() method in current scene's update method.

• Once current scene's update method ends (from current update tick), current scene is restarted (its start method is called).

API

method	description
constructor()	creates an instance of the Theatre module
load()	switches to another scene of your game
restart()	restarts current scene of your game

property	description
assets	gives you access to the contents of your game assets once loaded
container	gives you access to the DOM container of your game
context	gives you access to the canvas context of your game
delta	gives you access to the elapsed time between each tick of Theatre's game loop
element	gives you access to the DOM element of the canvas
loop	gives you access to the game loop
preloading	lets you know when assets are preloaded
scene	gives you access to current scene module
scenes	gives you access to your game scenes modules
size	gives you access to your game canvas size
state	gives you access to an object you can use through scenes in your game
version	gives you access to the Theatre version of your game

---

constructor()

Creates an instance of the Theatre module (sources/theatre/core/theatre.js).

Usage :

new Theatre({

    'assets': assets,
    'container': document.body,
    'expose': true,
    'framerate': 60,
    'scenes': scenes,
    'sharp': true,
    'size': {

        'width': 320,
        'height': 288
    },
    'speed': 1
});

Properties :

property	name	type	description
parameter	config	object	the configuration for your game

Details :

The config object allows you to set the defaults of your Theatre game. You can find below the full documentation of this config object.

key	type	mandatory	default	description
assets	array	yes		definition of your game assets
container	DOM object	yes		DOM container for the canvas to append
expose	boolean	no	false	should the Theatre context be exposed in the browser (useful when debugging)
framerate	positive integer	no	60	number of updates per second of the logic of your game
scenes	object	yes		your game scenes
sharp	boolean	no	false	should the game have a sharp rendering (great for pixel art)
size	object	yes		define there the size.width and size.height (positive integers) of your game
speed	positive number	no	1	define here the speed factor of the logic of your game

---

load()

Switches to another scene of your game.

Usage :

During the lifecycle of your game, in the update method, call Theatre's load() method :

this.load(scene);

Once current scene's update method ends (from current update tick), and not before, Theatre switches to the next scene.

Properties :

property	name	type	description
parameter	scene	string	a scene of your game

---

restart()

Restarts current scene of your game.

Usage :

During the lifecycle of your game, in the update method, call Theatre's restart() method :

this.restart();

Once current scene's update method ends (from current update tick), and not before, Theatre restarts current scene.

---

assets

Gives you access to the contents of your game assets once loaded (based from their definition).

Usage :

For instance, an asset is defined with the following format (then passed into your array of assets in the Theatre constructor in config.assets) :

const asset = {

    'name': 'hero',
    'scope': 'common',
    'source': require('./<path-to-image>/hero.png'),
    'type': 'image'
};

Theatre will expose your asset's loaded content in this.assets.<type>s.<scope>.<name> :

// gets the hero image
const hero = this.assets.images.common.hero;

Note that an s is concatenated to the type string in this.assets.<type>s.<scope>.<name>.

---

container

Gives you access to the DOM container of your game.

Usage :

// gets your game DOM container
const container = this.container;

---

context

Gives you access to the canvas context of your game.

Usage :

// gets the canvas context of your game
const context = this.context;

---

delta

Gives you access to the elapsed time between each (render and update) tick of Theatre's game loop.

Usage :

// gets an object with elapsed time between each (render and update) tick
const delta = this.delta;

Details :

The delta object allows you to perform animations in your game using its values.

key	type	description
render	positive number	elapsed time (ms) since the last render method was called
update	positive number	elapsed time (ms) since the last update method was called

---

element

Gives you access to the DOM element of the canvas.

Usage :

// gets the DOM element of the canvas
const element = this.element;

---

loop

Gives you access to the game loop of your game.

Usage :

// speed up your game logic
this.loop.speed *= 2;

// change your game logic framerate
this.loop.framerate = 30;

This is convenient for debugging purpose.

---

preloading

Lets you know when assets are preloaded.

You'll want to use it to switch from the loading scene to a scene requiring assets.

Usage :

// if assets are preloaded...
if (this.preloaded === true) {

    // ...then boot to the main scene
    this.load('main');
}

---

scene

Gives you access to current scene module.

Usage :

// gets current scene module
const scene = this.scene;

---

scenes

Gives you access to your game scenes modules.

Usage :

// gets Theatre default scene module
const loading = this.scenes.loading;

// gets one of your <custom> scene module
const <custom> = this.scenes.<custom>;

---

size

Gives you access to your game canvas size.

Usage :

// gets your game width
const width = this.size.width;

// gets your game height
const height = this.size.height;

You'll want to use the size object to render your entities centered to the screen, for instance.

Details :

The size object allows you to use a dynamic size.

key	type	description
height	positive integer	the height of the canvas of your game
width	positive integer	the width of the canvas of your game

---

state

Gives you access to an object you can use through scenes in your game.

Usage :

// sets a property of your game
this.state.score = 0;

---

version

Gives you access to the Theatre version of your game.

This is convenient for debugging purpose.

Usage :

// gets the current Theatre version of your game (like '1.0.0')
const version = this.version;

Change Log

License