UI Module

The Interface module provides a standard way handling the initial sizing and resize of your Application. The module allows for creating responsive and scalable game interfaces and consists of mainly one class: ScaleManager.

Dependencies

• Core Module
• EaselJS Display Module or PIXI Display Module

Installing

In order to use the UI Module, make sure to include the module's JavaScript file within the springroll.json project file. The module needs to be included after the core.

"libraries": [
	"components/springroll/dist/core.min.js",
	"components/springroll/dist/modules/easeljs-display.min.js", // or pixi-display
	"components/springroll/dist/modules/ui.min.js"
],
"librariesDebug": [
	"components/springroll/dist/core.js",
	"components/springroll/dist/modules/easeljs-display.js", // or pixi-display
	"components/springroll/dist/modules/ui.js"
]

Usage

It is recommended when designing your game to plan for the smallest aspect ratio the game will be display and to allow the interface to work at a maximum aspect ratio. This will create a title-safe area for your game. For instance, if the minimum aspect ratio is 1.333 (iPad resolution 1024x768) and the max is 2.0 (widescreen Android), then you'd want to design your backgrounds and gameplay to accommodate a max size of 1536x768.

+----------+----------------------------------------+----------*
|          |                                        |          |
|          |                                        |          |
|          |                                        |          |
|          |                                        |          |
|          |              Title-safe                |          |
|          |              1024 x 768                |          |
|          |                                        |          |
|          |                                        |          |
|          |                                        |          |
+----------+----------------------------------------+----------*
       ^---------- Non-title-safe 1536 x 768 ------------^

Here's how to setup the UIScaler to automatically resize elements to fit a range of aspect ratios between 1.333 and 2.0.

Manual Setup

// The properties of this object correspond to the names
// of properties on the class. For instance, this scaling
// will position the playButton at [10, 10] and align
// it to the top left of the screen with a minimum scale
// of 60% the original size and a maximum scale of 120%
// this configuration can also be externalized in a config.json
var scaling = {
	playButton : {
		x : 10,
		y : 10,
		align: 'top-left',
		minScale: 0.6,
		maxScale: 1.2 
	},
	closeButton : {
		x : 660,
		y : 10,
		align: 'top-right',
		titleSafe: true
	}
};

var app = new springroll.Application();

app.on('init', function()
{
	// Add the UI elements first, notice the names
	// "playButton" and "closeButton" match the same
	// names as the scaling objects properties
	this.playButton = new Button();
	this.closeButton = new Button();

	// Create the background
	this.background = new Bitmap();

	// Add the items to the stage
	this.display.stage.addChild(
		this.background, 
		this.playButton, 
		this.closeButton
	);

	// The scaling size needs to be defined
	// before adding any elements to the stage
	this.scaling.size = { 
		width: 1024,
		height: 768,
		maxWidth: 1536
	};

	// Add the scaling/position of items to this object
	this.scaling.addItems(this, scaling);

	// Add the background, will make background bitmap
	// fullscreen to cover as much of the stage as possible
	this.scaling.addBackground(this.background);
});

Automatic Setup

The scaling size and scaling properties can be externalized into the config.json. When this is loaded the scaling is applied immediately after the init event on Application.

assets/config/config.json contents:

{
	"scaling" : {
		"playButton" : {
			"x" : 10,
			"y" : 10,
			"align": "top-left",
			"minScale": 0.6,
			"maxScale": 1.2 
		},
		"closeButton" : {
			"x" : 660,
			"y" : 10,
			"align": "top-right",
			"titleSafe": true
		}
	},
	"scalingSize" : { 
		"width": 1024,
		"height": 768,
		"maxWidth": 1536
	}
}

var app = new springroll.Application({
	// Specify the configuration to load
	configPath: "assets/config/config.json"
});
app.on('init', function()
{
	// Create the UI elements
	this.playButton = new Button();
	this.closeButton = new Button();
	this.background = new Bitmap();

	// Add the items to the stage
	this.display.stage.addChild(
		this.background, 
		this.playButton, 
		this.closeButton
	);

	// Background must still be added manually
	// all other elements will be scaled right after
	// this init function
	this.scaling.addBackground(this.background);
});

Documentation

See docs for the ScaleManager.