Configuration

Configuration #

bwplay-cli needs some light configuration in order to understand the structure of your project.

Assumptions #

bwplay-cli makes some assumptions about your project - if these do not hold true, this tooling may not work for you.

Your code takes care of building its own DOM. All generated HTML assumes that your JavaScript is okay with a blank HTML document (i.e. an empty <body> element). The most common situation is that the entire document is just be a single <canvas> object, created and inserted by the first JavaScript code that executes.

Configuration File #

All configuration is stored in a single file named bwplay.json. This file should be located at the root of your project. All bwplay-cli commands expect a bwplay.json to be in the current working directory (the directory from which you run bwplay-cli).

An example file may look something like this:

{
  "name": "Test Game",
  "javascriptFiles": ["src/**/*.js"],
  "audioFiles": ["assets/audio/*.wav", "test.wav"],
  "iconFile": "assets/icon.png",
  "screenOrientation": "landscape",
  "androidPackageName": "com.test.game",
  "androidVersionCode": 10003,
  "androidVersionName": "0.3"
}

Properties #

name required #

The nice, human-readable name of the project.

javascriptFiles required #

A list of glob patterns used to identify which JavaScript files should be included in the project. Files that aren’t detected by any glob pattern will not be served by the development server and will not be packed into the final game.

What about .ts files?

bwplay-cli does not try to insert itself into earlier stages of your build pipeline. TypeScript files should be rendered by your own build process, and the output files should be matched by one or more glob patterns.

audioFiles #

A list of glob patterns used to find audio files that should be included in the project. These files are used when generating audio code, running the development server, and exporting the final game. Files that aren’t detected by any glob pattern will not make their way into the game.

A large number of file types are supported. bwplay-cli does not care about the particular type of file you are trying to use - it will happily treat a PNG file as audio if the glob picks one up. If you’re targeting multiple platforms (e.g. most web browsers), consider using a popular/common audio format for your audio files.

If the tooling cannot figure out the type of one or more of your files, a warning message will be generated when attempting to generate audio code, and those unidentifiable files will not be included in the generated code.

If this setting is not specified, no audio code will be generated.

audioScriptFile #

The path to a file which will contain generated TypeScript code for the project’s audio. Note that this file is generated by bwplay-cli and can be overwritten at any time - do not make manual changes to this file.

If this setting is not specified, generated code will be written to audio.ts in the top-level directory of the project.

iconFile #

The path to an image file that will be used as the icon for the game. Usages of this file include as a favicon, a PWA icon, and an Android app icon.

This image should ideally be at least 512x512 pixels in size; the image will be automatically scaled down (or up) to different sizes to meet the requirements of favicons, app icons, etc.

screenOrientation #

One of any, portrait, or landscape. Whether the game’s viewport should be taller than wide (portrait), wider than tall (landscape), or if the size doesn’t matter (any).

Setting this to portrait or landscape will lock the viewport to this mode. “any” is only useful if your game is able to render itself regardless of screen resolution.

androidApplicationId #

The applicationId that you’d like to use when exporting to Android.

This setting is only necessary if you’ll be exporting to Android, however you cannot export to Android without it.

androidVersionCode #

An integer, designed to grow larger each time you release a new version of the Android app.

If you export to Android without setting this value, a low number will be chosen as a default.

androidVersionName #

An arbitrary human-readable string - it’s only purpose is to be shown to Android users so that they can identify the version of your app.

If you export to Android without setting this value, a low <major>.<minor>.<point> version string will be chosen as a default.

androidNetworkSecurityDomains #

A list of network domain names that your application should be allowed to communicate with. This maps to the concept of domains in the Android network security configuration. If you do not specify any domains here, your project will not be able to communicate with any websites.