States Module

Derek Detweiler edited this page Jan 6, 2016 · 13 revisions

The States module provides a solution for managing the loading and choreography of different screens (we call them "panels") within an application. The States modules allows the asynchronous loading and unloading of assets and seamlessly transitioning between different states of the game or app.



In order to use the States module, make sure to include the module's JavaScript file within your springroll.json project file under libraries and librariesDebug.

"libraries": [
"librariesDebug": [

Application Plugin

The State module options, properties and events that are added to the Application.


options.state (String) optional The first state the manager should go to when initializing the application. This can be manually set later using app.manager.state property.

options.transition (createjs.MovieClip, springroll.easeljs.BitmapMovieClip, PIXI.Spine) optional - The reference to the transition animation. This can be set manually later using the app.transition property. (String) optional The sound alias to play during transitioning in

options.transitionSounds.out (String) optional The sound alias to play during the transitioning out.

options.transitionSounds.loading (String) optional The sound alias to play during the transitioning loading. An "onTransitionLoading" event must be available on the transition in order to play this loading sound.


manager (springroll.StateManager) The reference to main state manager.

transition (createjs.MovieClip, springroll.easeljs.BitmapMovieClip, PIXI.Spine) The reference to the transition animation (same as options.transition). The difference is that transition can be set after the application has been constructed incase any images or extra assets are needed before displaying. The transition setting needs to happen before states are set.

states (Object) setterOnly Set the states dictionary for the current application


stateAdded The event that's fired when a new state has been added to the StateManager. Two parameters: id (String) and state (springroll.State)



A transition is used to visual transition in and out of states. A transition is a createjs.MovieClip or PIXI.Spine animation that plays on-top of all of the states. The transition must have several frame labels to work with the Animator and StateManager. These are: "onTransitionIn", "onTransitionIn_stop", "onTransitionOut", "onTransitionOut_stop". Also the optional "onTransitionLoading" and "onTransitionLoading_loop" which define a region to loop while a state is preloading.


For any game which contains two or more screens, the State module creates an easy way to switch between states. Here's an example of a game we're building that contains the following states:

  • Title State - contains a background image and some UI elements
  • Intro State - contains a short animation setup
  • Game State - the actual gameplay
  • Result State - the resulting animation or pay-off screen for the game

Each state is made up of two parts: the state (which contains all the logic, event listeners, etc) and the panel (which contains all the display elements). The state should extend springroll.State and the panel should be either a createjs.Container or PIXI.DisplayObjectContainer.

var Application = include('springroll.Application');
var Transition = include('lib.Transition'); // the EaselJS movieclip
var Container = include('createjs.Container'); // to create panels

var app = new Application({
	state: 'title', // the first state to load
	transition: new Transition() // the transition animation

app.once('init', function()
	// Setup the states, the key is the alias for the state
	this.states = {
		title: new State(new Container(), {
			next: 'intro'
		intro: new State(new Container(), {
			next: 'game',
			previous: 'title'
		game: new State(new Container(), {
			next: 'intro',
			previous: 'title'
		result: new State(new Container(), {
			next: 'game',
			previous: 'game'

Extending springroll.State

The State has many convenient methods for changing state of the game and managing loading. Here's an example of how to create a custom TitleState by extending the base State class.

	// Include the parent class
	var State = include('springroll.State');
	var Container = include('createjs.Container');

	// Create a new state for the title section of the game
	var TitleState = function(panel, options)
	{, panel, options);

	// Inherit the prototype chain from State
	// the "p" var is the reference to the TitleState prototype
	var p = extend(TitleState, State);

	// These methods can be set for transition choreography
	p.enter = function(){};
	p.enterDone = function(){};
	p.exitStart = function(){};
	p.exit = function(){};

	// class will be available from the window object window.mygame.TitleState
	// or by using include('mygame.TitleState');
	namespace('mygame').TitleState = TitleState;


State Constructor Options

panel createjs.Container or PIXI.DisplayObjectContainer are used to display the visual elements of the current state.

options (optional) The object properties to use for the state

  • The String of the state alias which represents the next state to goto
  • options.previous The String of the state alias which represents the previous (or "back") state
  • options.delayLoad=0 The int number of frames to wait before loading, this can be useful to set if the construction of many display objects kills performance upon entering.

State Properties

manager The reference instance to the springroll.StateManager which controls the state.

panel The reference to the instance of the display object container for the state.

State Methods

loadingStart() This method instructs the StateManager that we're about to asynchronously load assets (like images or sounds). It will stop continuing the transition animation until loadingDone has been called.

loadingDone(delay=0) This method instructs the StateManager that we're done doing asynchronous loading of assets and will continue transitioning in the state.

  • delay (int) optional Frames to delay the load completion to allow the framerate to stabilize.

nextState() Goto the next state if the constructor is set. previousState() Goto the previous state if the constructor options.previous is set.

Overridable State Methods

enter() This method is called when the transition starts transitioning into the state. At this point the transition is completely covering the panel. This is a good place to start the preloading of assets (see loadingStart and loadingDone).

enterDone() This method is called when the transition is finished revealing the panel. This is a good place to start playback of any visual or audio events, such as voiceover, a tutorial or cutscene.

exitStart() This method is called when the transition begins transitioning out of the state. This is a good place to stop all animations, sound effects or anything else that might hinder the performance of the transition.

exit() This method is called when the transition finishes transitioning out of the state. At this point the panel is completely covered. This is a good place to remove any references, clean-up the display, remove children and unload any assets.

Dynamic Loading Assets

var state = new State();

// Create a property on the state to "hold"
// the assets that need to be loaded/unloaded
state.onDemandAssets = null;

state.on('loading', function(assets)
	// Save for later, this might change
	// dynamically depending on what needs
	// to be loaded in this round
	this.onDemandAssets = [
		{ id: "sprite1", src: "assets/images/sprite1.png" },
		{ id: "sprite2", src: "assets/images/sprite2.png" }

	// Add the assets to the assets parameter,
	// this will hook them into the preload process
		// if the assets need to be available to 
		// createjs in the window.images object,
		// add a complete callback for each asset
		// and add it to the window.images

// Unload the assets when we're done
state.on('exit', function()
	this.onDemandAssets = null;

API Documentation

See the documentation here for the StateManager.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.