storyboard.gotoScene()

Type Function
Library storyboard.*
Return value none
Revision Current Public Release (2014.2393)
Keywords scenes, switching, transitions, gotoScene, storyboard

Overview

Used to transition to a specific scene. Scenes must be explicitly purged/removed by the user. However, if the storyboard.disableAutoPurge flag is not set to true, the least recently used scene will be automatically purged whenever the OS issues a low memory warning.

When a scene is purged, its scene.view display group is removed to preserve texture memory, but the scene's module is kept in memory (in case the module needs to be used again). Scene removal is purging plus the unloading of the scene's module.

When storyboard.gotoScene() is called, the "exitScene" event is dispatched for the currently loaded scene (if one exists), followed by the "createScene" event (for the specified scene, if no scene.view exists on the scene), which is followed by a "willEnterScene" event and then finally an "enterScene" event once the transition is complete.

Syntax

storyboard.gotoScene( sceneName [, options] )
sceneName (required)

String. This is the name of the scene you want to "go" to (the next scene). This will most-often be the name of the scene's module (without the ".lua" extension), or if you created a non-module-based scene, it will be the name you specified when calling storyboard.newScene().

options (optional)

Table. Contains several scene transition-related options (such as effect, custom parameters, etc). See the next section for how you should format this table.

Format for options

This table takes a number of different options. All of which are optional, but some depend on other options to be set.

local options =
{
    effect = "fade",
    time = 400,
    params =
    {
        sample_var = "anything",
        custom = "you want",
        data = "here"
    }
}
effect (optional)

String. Represents the effect you would like to use for the scene transition. See the next section for a list of supported effects. If no effect is specified, the scene transition will happen instantaneously.

time (optional)

Number. The duration of time the effect should last. This is only taken to account if the effect is also set. Default: 500 (milliseconds)

params (optional)

Table. You may optionally pass any kind of custom data that you want transferred to the next scene via event listeners. This data can be accessed via event.params in the "createScene", "willEnterScene", and "enterScene" events of the next scene.

Scene Effects

The following is a list of supported strings for the effect key of the options table:

Examples

local storyboard = require "storyboard"

local options =
{
    effect = "slideLeft",
    time = 800,
    params = { var1 = "custom", myVar = "another" }
}

storyboard.gotoScene( "scene1", options )