{"id":21090421,"url":"https://github.com/theatrejs/theatrejs.github.io","last_synced_at":"2025-03-14T06:15:23.726Z","repository":{"id":37201527,"uuid":"87357059","full_name":"theatrejs/theatrejs.github.io","owner":"theatrejs","description":"[DEPRECATED] 📓 theatre javascript game framework - documentation","archived":false,"fork":false,"pushed_at":"2023-03-02T07:45:06.000Z","size":1235,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-21T01:11:39.022Z","etag":null,"topics":["es6","framework","game","javascript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theatrejs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-05T21:13:19.000Z","updated_at":"2024-09-11T07:10:04.000Z","dependencies_parsed_at":"2024-11-20T00:30:35.289Z","dependency_job_id":"93ba7116-163b-46f4-91be-63ee2fee0aa2","html_url":"https://github.com/theatrejs/theatrejs.github.io","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theatrejs%2Ftheatrejs.github.io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theatrejs%2Ftheatrejs.github.io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theatrejs%2Ftheatrejs.github.io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theatrejs%2Ftheatrejs.github.io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theatrejs","download_url":"https://codeload.github.com/theatrejs/theatrejs.github.io/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243532556,"owners_count":20306157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["es6","framework","game","javascript"],"created_at":"2024-11-19T21:36:38.169Z","updated_at":"2025-03-14T06:15:23.687Z","avatar_url":"https://github.com/theatrejs.png","language":"JavaScript","readme":"[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n# Theatre\n\n\u003e *Theatre is a lightweight, simple and fast javascript game framework.*\n\n## Overview\n\nTheatre game framework is built in plain javascrit. It helps you create games quickly.\n\n\u003e This repository is a **demo on top of a generated Theatre game project**.\n\n\u003e 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**.\n\n## Table of contents\n\n- [Installation](#installation)\n    - [Generate the project's structure](#generate-the-projects-structure)\n    - [Install the project](#install-the-project)\n- [Usage](#usage)\n    - [Quick start](#quick-start)\n    - [Distribution](#distribution)\n    - [Electron preview](#electron-preview)\n    - [Production build](#production-build)\n- [Tree structure](#tree-structure)\n- [Asset structure](#asset-structure)\n- [Scene structure](#scene-structure)\n- [Context](#context)\n- [Lifecycle](#lifecycle)\n- [API](#api)\n\n## Installation\n\nFirst, you'll need to use our [Yeoman](http://yeoman.io/) generator (see : [`generator-theatre`](https://github.com/theatrejs/generator-theatre)) to scaffold a new Theatre project.\n\n#### Generate the project's structure\n\nStart a console then run :\n\n```\n$ npm install -g yo\n$ npm install -g generator-theatre\n```\n\nCreate the folder for your new project :\n\n```\n$ mkdir \u003cyour-game\u003e\n```\n\nThen, generate your project in this new folder :\n\n```\n$ cd \u003cyour-game\u003e\n$ yo theatre\n```\n\nOnce you've done scaffolding your project, you'll need to install the project's dependencies.\n\n#### Install the project\n\nStart a console then run :\n\n```\n$ npm install\n```\n\nA `postinstall` NPM script executes a [production build](#production-build) of your game.\n\n## Usage\n\nWe have created a `demo` scene to help you understand Theatre lifecycle.\n\n#### Quick start\n\nTo start a development server, start a console then run :\n\n```\n$ npm start\n```\n\nIt opens a new browser tab serving your game from the [`dist/`](./dist/) folder (*[`webpack-dev-server`](https://webpack.js.org/configuration/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.*).\n\n#### Distribution\n\nTo build your game in any possible way, you'll need to create a distribution of your game. Start a console then run :\n\n```\n$ npm run dist\n```\n\nIt creates a prebuild of your game in the [`dist/`](./dist/) folder which will be used by the [Electron preview](#electron-preview) and/or by the [Production build](#production-build).\n\n#### Electron preview\n\nTo see the preview of the desktop application build of your game (made with [Electron](https://electronjs.org/)), start a console then run :\n\n```\n$ npm run electron\n```\n\nIt opens a new browser tab serving your game from the [`dist/`](./dist/) folder.\n\n\u003e **WARNING** : Don't forget to create/update the [distribution](#distribution) of your game before each [Electron](https://electronjs.org/) preview.\n\n#### Production build\n\nTo build your game for production, start a console then run :\n\n```\n$ npm run build\n```\n\nIt creates the production builds (executables) of your game in the [`build/`](./build/) folder.\n\n\u003e **INFO** : Feel free to check the [`package.json`](./package.json) file if you just want to generate executables on specific platforms.\n\n\u003e **WARNING** : Don't forget to create/update the [distribution](#distribution) of your game before each production build.\n\n## Tree structure\n\nIn the root folder, you'll find this main tree structure :\n\n```\ndocs/\n|-- index.css\n|-- index.html\n'-- index.js\ndocumentation/\n'-- SGDD.md\nsources/\n|-- game/\n|   |-- assets/\n|   |-- components/\n|   |-- scenes/\n|   '-- systems/\n|-- theatre/\n|   |-- core/\n|   '-- modules/\n'-- index.js\nwebpack.\u003cconfig\u003e.js\n```\n\n#### Configuration files\n\nYou'll find there three [Webpack](https://webpack.js.org/) configuration files (files like `webpack.\u003cconfig\u003e.js`) :\n\n[`webpack.common.js`](./webpack.common.js) - Webpack configuration for both `development` and `production` environments.\n\n[`webpack.development.js`](./webpack.development.js) - Webpack configuration for `development` environment.\n\n[`webpack.production.js`](./webpack.production.js) - Webpack configuration for `production` environment.\n\n#### Sources folder\n\nThe [`sources/`](./sources/) folder contains the code base for your game :\n\n```\nsources/\n|-- game/\n|   |-- assets/\n|   |-- components/\n|   |-- scenes/\n|   '-- systems/\n|-- theatre/\n|   |-- core/\n|   '-- modules/\n'-- index.js\n```\n\n[`sources/theatre/`](./sources/theatre/) - The framework (the [`core`](./sources/theatre/core/) and useful [`modules`](./sources/theatre/modules/)).\n\n[`sources/game/`](./sources/game/) - All your source files (all [`assets`](./sources/game/assets/), [`components`](./sources/game/components/), [`scenes`](./sources/game/scenes/) and [`systems`](./sources/game/systems/)).\n\n[`sources/index.js`](./sources/index.js) - The entry point of your game with your presets.\n\n#### Dist folder\n\nThe [`dist/`](./dist/) folder contains the prebuild of your game :\n\n```\ndist/\n|-- electron.js\n|-- index.css\n|-- index.html\n|-- index.js\n|-- index.js.map\n'-- package.json\n```\n\n[`dist/electron.js`](./dist/electron.js) - The entry point for the [Electron](https://electronjs.org/) build.\n\n[`dist/index.js`](./dist/index.js) - The build ([production build](#production-build)) of your game.\n\n[`dist/index.js.map`](./dist/index.js.map) - The sourcemaps of your game.\n\n[`dist/index.html`](./dist/index.html) - The default HTML5 preview for your game.\n\n[`dist/index.css`](./dist/index.css) - The default style of the preview of your game.\n\n[`dist/package.json`](./dist/package.json) - The entry point for the [Electron](https://electronjs.org/) build.\n\n#### Docs folder\n\nThe [`docs/`](./docs/) folder contains your game preview :\n\n```\ndocs/\n|-- index.css\n|-- index.html\n|-- index.js\n'-- index.js.map\n```\n\n[`docs/index.js`](./docs/index.js) - The build ([production build](#production-build)) of your game.\n\n[`docs/index.js.map`](./docs/index.js.map) - The sourcemaps of your game.\n\n[`docs/index.html`](./docs/index.html) - The default HTML5 preview for your game.\n\n[`docs/index.css`](./docs/index.css) - The default style of the preview of your game.\n\n#### Documentation folder\n\nThe [`documentation/`](./documentation/) folder contains the documentation for your game :\n\n```\ndocumentation/\n'-- SGDD.md\n```\n\n[`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).\n\n## Asset structure\n\nFor instance, an asset is defined with the following format :\n\n```javascript\nconst asset = {\n\n    'name': 'hero',\n    'scope': 'common',\n    'source': require('./\u003cpath-to-image\u003e/hero.png'),\n    'type': 'image'\n};\n```\n\n###### Details :\n\n| key      | type                                      | description          |\n| -------- | ----------------------------------------- | -------------------- |\n| `name`   | `string`                                  | name of your asset   |\n| `scope`  | `string`                                  | scope of your asset  |\n| `source` | `mixed`                                   | source of your asset |\n| `type`   | `string of ['dataset', 'image', 'sound']` | source of your asset |\n\n###### Usage :\n\nTheatre will expose a getter function for your asset in `this.assets.\u003ctype\u003es.\u003cscope\u003e.\u003cname\u003e`.\n\nAn example for a sound :\n\n```javascript\nconst blastGetter = this.assets.sounds.common.blast;\n\n// plays simultaneously the same sound as many times as you want\nblastGetter().play();\nblastGetter().play();\n```\n\n\u003e **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.\n\n## Scene structure\n\n\u003e *Scenes are the place where you'll work most of the time.*\n\nA scene is a group of the following methods :\n\n`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).\n\n`start` *(called when the scene starts or restarts)* - Initialize there the data of the scene.\n\n`update` *(called each update tick)* - Update there the data of the scene (update the logic of your game when time passes).\n\n`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).\n\n`destroy` *(called just before the next scene boots)* - Destroy there everything created in the `setup` method to prevent spaming the next scene.\n\n## Context\n\n\u003e Theatre binds its context on each of your methods of your scenes.\n\nEverywhere 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.\n\n## Lifecycle\n\n\u003e *Theatre's lifecycle is really simple.*\n\n#### Running the first scene: `loading` scene\n\u003e All assets are loading (async) during `loading` scene's lifecycle. When all assets are loaded, Theatre sets its [`preloading`](#preloading) property to `true`.\n\n- Theatre boots `loading` scene (its `setup` then `start` methods are called).\n- Theatre's game loop starts running (async) `update` and `render` methods of  `loading` scene.\n\n```\nTHEATRE                   LOADING SCENE\n,--------------------,    ,-----------,\n| setup scene \u003c------|----|-- setup   |\n| start scene \u003c------|----|-- start   |\n| ,----------------, |    |           |\n| | update loop \u003c--|-|----|-- update  |\n| '----------------' |    |           |\n| ,----------------, |    |           |\n| | render loop \u003c--|-|----|-- render  |\n| '----------------' |    |   destroy |\n'--------------------'    '-----------'\n```\n\n#### Switch to the next scene\n\n\u003e To switch from current scene to the next you'll have to call Theatre's [`load()`](#load) method in current scene's `update` method with the next scene as parameter.\n\n- Once current scene's `update` method ends (from current update tick), current scene is destroyed (its `destroy` method is called).\n- The new scene is now defined as the current scene.\n- This new scene boots (its `setup` then `start` methods are called).\n- Theatre's game loop continue as before (but now running the new scene's `update` and `render` methods).\n\n#### Restart current scene\n\n\u003e To restart current scene you'll have to call Theatre's [`restart()`](#restart) method in current scene's `update` method.\n\n- Once current scene's `update` method ends (from current update tick), current scene is restarted (its `start` method is called).\n\n## API\n\n| method                          | description                               |\n| ------------------------------- | ----------------------------------------- |\n| [`constructor()`](#constructor) | creates an instance of the Theatre module |\n| [`load()`](#load)               | switches to another scene of your game    |\n| [`restart()`](#restart)         | restarts current scene of your game       |\n\n| property                    | description                                                                   |\n| --------------------------- | ----------------------------------------------------------------------------- |\n| [`assets`](#assets)         | gives you access to the contents of your game assets once loaded              |\n| [`container`](#container)   | gives you access to the DOM container of your game                            |\n| [`context`](#context)       | gives you access to the `canvas` context of your game                         |\n| [`delta`](#delta)           | gives you access to the elapsed time between each tick of Theatre's game loop |\n| [`element`](#element)       | gives you access to the DOM element of the `canvas`                           |\n| [`loop`](#loop)             | gives you access to the game loop                                             |\n| [`preloading`](#preloading) | lets you know when assets are preloaded                                       |\n| [`scene`](#scene)           | gives you access to current scene module                                      |\n| [`scenes`](#scenes)         | gives you access to your game scenes modules                                  |\n| [`size`](#size)             | gives you access to your game `canvas` size                                   |\n| [`state`](#state)           | gives you access to an object you can use through scenes in your game         |\n| [`version`](#version)       | gives you access to the Theatre version of your game                          |\n\n---\n\n#### `constructor()`\n\nCreates an instance of the Theatre module ([`sources/theatre/core/theatre.js`](./sources/theatre/core/theatre.js)).\n\n###### Usage :\n\n```javascript\nnew Theatre({\n\n    'assets': assets,\n    'container': document.body,\n    'expose': true,\n    'framerate': 60,\n    'scenes': scenes,\n    'sharp': true,\n    'size': {\n\n        'width': 320,\n        'height': 288\n    },\n    'speed': 1\n});\n```\n\n###### Properties :\n\n| property  | name     | type     | description                     |\n| --------- | -------- | -------- | ------------------------------- |\n| parameter | `config` | `object` | the configuration for your game |\n\n###### Details :\n\nThe `config` object allows you to set the defaults of your Theatre game. You can find below the full documentation of this `config` object.\n\n| key         | type               | mandatory | default | description                                                                      |\n| ----------- | ------------------ | --------- | ------- | -------------------------------------------------------------------------------- |\n| `assets`    | `array`            | yes       |         | definition of your game assets                                                   |\n| `container` | `DOM object`       | yes       |         | DOM container for the canvas to append                                           |\n| `expose`    | `boolean`          | no        | false   | should the Theatre context be exposed in the browser (useful when debugging)     |\n| `framerate` | `positive integer` | no        | 60      | number of updates per second of the logic of your game                           |\n| `scenes`    | `object`           | yes       |         | your game scenes                                                                 |\n| `sharp`     | `boolean`          | no        | false   | should the game have a sharp rendering (great for pixel art)                     |\n| `size`      | `object`           | yes       |         | define there the `size.width` and `size.height` (positive integers) of your game |\n| `speed`     | `positive number`  | no        | 1       | define here the speed factor of the logic of your game                           |\n\n---\n\n#### `load()`\n\nSwitches to another scene of your game.\n\n###### Usage :\n\nDuring the lifecycle of your game, in the `update` method, call Theatre's `load()` method :\n\n```javascript\nthis.load(scene);\n```\n\n\u003e Once current scene's `update` method ends (from current update tick), and not before, Theatre switches to the next scene.\n\n###### Properties :\n\n| property  | name    | type     | description          |\n| --------- | ------- | -------- | -------------------- |\n| parameter | `scene` | `string` | a scene of your game |\n\n---\n\n#### `restart()`\n\nRestarts current scene of your game.\n\n###### Usage :\n\nDuring the lifecycle of your game, in the `update` method, call Theatre's `restart()` method :\n\n```javascript\nthis.restart();\n```\n\n\u003e Once current scene's `update` method ends (from current update tick), and not before, Theatre restarts current scene.\n\n---\n\n#### `assets`\n\nGives you access to the contents of your game assets once loaded (based from their definition).\n\n###### Usage :\n\nFor instance, an asset is defined with the following format (then passed into your array of assets in the Theatre constructor in `config.assets`) :\n\n```javascript\nconst asset = {\n\n    'name': 'hero',\n    'scope': 'common',\n    'source': require('./\u003cpath-to-image\u003e/hero.png'),\n    'type': 'image'\n};\n```\n\nTheatre will expose your asset's loaded content in `this.assets.\u003ctype\u003es.\u003cscope\u003e.\u003cname\u003e` :\n\n```javascript\n// gets the hero image\nconst hero = this.assets.images.common.hero;\n```\n\n\u003e Note that an `s` is concatenated to the `type` string in `this.assets.\u003ctype\u003es.\u003cscope\u003e.\u003cname\u003e`.\n\n---\n\n#### `container`\n\nGives you access to the DOM container of your game.\n\n###### Usage :\n\n```javascript\n// gets your game DOM container\nconst container = this.container;\n```\n\n---\n\n#### `context`\n\nGives you access to the `canvas` context of your game.\n\n###### Usage :\n\n```javascript\n// gets the canvas context of your game\nconst context = this.context;\n```\n\n---\n\n#### `delta`\n\nGives you access to the elapsed time between each (render and update) tick of Theatre's game loop.\n\n###### Usage :\n\n```javascript\n// gets an object with elapsed time between each (render and update) tick\nconst delta = this.delta;\n```\n\n###### Details :\n\nThe `delta` object allows you to perform animations in your game using its values.\n\n| key      | type              | description                                                 |\n| -------- | ----------------- | ----------------------------------------------------------- |\n| `render` | `positive number` | elapsed time (ms) since the last `render` method was called |\n| `update` | `positive number` | elapsed time (ms) since the last `update` method was called |\n\n---\n\n#### `element`\n\nGives you access to the DOM element of the `canvas`.\n\n###### Usage :\n\n```javascript\n// gets the DOM element of the canvas\nconst element = this.element;\n```\n\n---\n\n#### `loop`\n\nGives you access to the game loop of your game.\n\n###### Usage :\n\n```javascript\n// speed up your game logic\nthis.loop.speed *= 2;\n\n// change your game logic framerate\nthis.loop.framerate = 30;\n```\n\n\u003e This is convenient for debugging purpose.\n\n---\n\n#### `preloading`\n\nLets you know when assets are preloaded.\n\n\u003e You'll want to use it to switch from the loading scene to a scene requiring assets.\n\n###### Usage :\n\n```javascript\n// if assets are preloaded...\nif (this.preloaded === true) {\n\n    // ...then boot to the main scene\n    this.load('main');\n}\n```\n\n---\n\n#### `scene`\n\nGives you access to current scene module.\n\n###### Usage :\n\n```javascript\n// gets current scene module\nconst scene = this.scene;\n```\n\n---\n\n#### `scenes`\n\nGives you access to your game scenes modules.\n\n###### Usage :\n\n```javascript\n// gets Theatre default scene module\nconst loading = this.scenes.loading;\n\n// gets one of your \u003ccustom\u003e scene module\nconst \u003ccustom\u003e = this.scenes.\u003ccustom\u003e;\n```\n\n---\n\n#### `size`\n\nGives you access to your game `canvas` size.\n\n###### Usage :\n\n```javascript\n// gets your game width\nconst width = this.size.width;\n\n// gets your game height\nconst height = this.size.height;\n```\n\n\u003e You'll want to use the `size` object to render your entities centered to the screen, for instance.\n\n###### Details :\n\nThe `size` object allows you to use a dynamic size.\n\n| key      | type               | description                             |\n| -------- | ------------------ | --------------------------------------- |\n| `height` | `positive integer` | the height of the `canvas` of your game |\n| `width`  | `positive integer` | the width of the `canvas` of your game  |\n\n---\n\n#### `state`\n\nGives you access to an object you can use through scenes in your game.\n\n###### Usage :\n\n```javascript\n// sets a property of your game\nthis.state.score = 0;\n```\n\n---\n\n#### `version`\n\nGives you access to the Theatre version of your game.\n\n\u003e This is convenient for debugging purpose.\n\n###### Usage :\n\n```javascript\n// gets the current Theatre version of your game (like '1.0.0')\nconst version = this.version;\n```\n\n## [Change Log](./CHANGELOG.md)\n\n## [License](./LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheatrejs%2Ftheatrejs.github.io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheatrejs%2Ftheatrejs.github.io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheatrejs%2Ftheatrejs.github.io/lists"}