Config System

Matt Karl edited this page Sep 25, 2015 · 9 revisions

SpringRoll projects using the standard build tasks in grunt-springroll have a configuration system that is built-in which is utilized by Application and several modules. For instance, the SpringRoll modules Sound, Learning, and UI can take advantage of this system for reading externalized data and providing module initial configuration. The configuration system also provides a useful, scalable way to store Application constants, level data and other static game information. Generally, it's good practice to move magic numbers, constants, strings and other read-only information to the config system.

Setup

Enable Config Build

The springroll.json file within your project must specify a config property, which is the path to the root source folder which contains a bunch of JSON config files. (For more information about the build file see build file properties). Below is a simple build file and config system enabled.

{
	"name": "MyGame",
	"version": "1.0.0",
	"config": "src/config", // <--- config enabled with path
	"main": [
		...
	],
	"libraries": [
		...
	]
}

In the example above, src/config is a folder which only contains a bunch of JSON files. All these files will get parsed and concatenated into a single file. The default output location for this config file is deploy/assets/config/config.json.

To explicitly rebuild the config file, run the grunt tasks grunt config (config.json without whitespace) or grunt config-debug (config.json with whitespace). The grunt tasks debug, dev-main, default will also rebuild the config.json file.

Loading config.json

When you create your SpringRoll Application there's a configPath argument that must be included in the setup options.

// Autoload the config.json file
var app = new Application({
	configPath: "assets/config/config.json"
});

Usage

For more information about how JSON files get concatenated see the grunt-concat-json plugin. Here is a simple example, with two files in the config system.

Source JSON

src/config/physics.json

{
	"gravity": -10,
	"defaultFriction": 0.8
}

src/config/spaceship.json

{
	// These comments are stripped out!
	// maximum speed in pixels per second
	"maxSpeed": 100,
	"asset": "assets/images/spaceship.png"
}

Output JSON

These source files get combined into the following contents. All comments are removed and filenames are used as the config property names. Folders are also translated into as nested object properties.

deploy/assets/config/config.json

{
	"physics": {
		"gravity": -10,
		"defaultFriction": 0.8
	},
	"spaceship": {
		"maxSpeed": 100,
		"asset": "assets/images/spaceship.png"
	}
}

Application Usage

// Setup the configPath to auto-load
var app = new Application({
	configPath: "assets/config/config.json"
});

// App is ready! Config is accessible from the 
// application's config property
app.once('init', function()
{
	console.log(this.config.physics.gravity); // outputs: -10
});

Sound Config

The config system can be used by the Sound Module to automatically initialize the sounds and sound contexts that are used by your Application. There are three contexts that can be setup by default (if available): sounds.music, sounds.sfx (sound effects) and sounds.vo (voice-over).

Source JSON

Here's an example of creating the

src/config/sounds.json

{
	"music": {
		"context": "music",
		"path": "assets/sound/music/",
		"sounds": [
			"IntroMusic", // e.g., IntroMusic.ogg or IntroMusic.mp3
			"GameMusic"
		]
	},
	"sfx": {
		"context": "sfx",
		"path": "assets/sound/sfx/",
		"sounds": [
			{ "src": "Rollover", "preload": true }, // preloads audio
			"Select"
		]
	}
}

Application Usage

When the sounds config property is available the Sound Module will automatically setup the sounds and these sounds can be played as soon as your application starts.

var app = new Application({
	configPath: "assets/config/config.json"
});

// Use the sounds
app.once('init', function()
{
	this.music = "IntroMusic";
	this.sound.play("Select");
});

For more information about using sounds, see the Sound Class page.

UI Config

The config system can be used by the UI Module to create the configuration for the ScaleManager. This is used to provide some information about the designed size of the application and an understand of how to responsively handle the elements.

Source JSON

src/config/scalingSize.json

{
	"width": 900, // designed width when game is 100% scale, aka title-safe size
	"height": 480, // designed height when game is 100% scale, aka title-safe size
	"maxWidth": 1200, // optional: max width for larger aspect ratios
	"maxHeight": 600, // optional: max height for smaller aspect ratios
}

src/config/scaling.json

{
	// make sure transition is aligned
	"transition": "center"
}

Application Usage

var app = new Application({
	configPath: "assets/config/config.json"
});

// Use the sounds
app.once('init', function()
{
	this.transition = new lib.Transition(); // EaselJS movieclip
	this.display.stage.addChild(this.transition);
	// this.transition automatically is responsively scaled
	// based on the config.scaling.transition settings
	// and the config.scalingSize settings
});

Learning Config

The config system can be used by the Learning Module to automatically create the learning API methods based on the Learning Analytics specification. The if the config properties spec and specDictionary are available in the config, they will be use to automatically generate the learning event definitions.

Source JSON

src/config/spec.json

{
	"gameId": "699efb8f-f0d5-42c6-997f-0ced2b393f75",
	"version": "1.0",
	"events": {
		"9999": {
			"id": "20de47a0-8231-484c-8c50-b00f6d2258be",
			"args": [
				{
					"type": "int",
					"name": "game_time"
				},
				{
					"type": "string",
					"name": "shape"
				}
			]
		}
	}
}

src/config/specDictionary.json

{
	"9999": "shapeSelected"
}

See the full list of default event codes (no entry is needed in specDictionary for default event codes).

Application Usage

var app = new Application({
	configPath: "assets/config/config.json"
});

// Learning events have been setup
app.once('init', function()
{
	this.learning.shapeSelected("rectangle");
});

Documentation

The Application docs contain more information and events and properties which are created by the config system.