composer.gotoScene()

Type Function
Library composer.*
Return value none
Revision Release 2022.3683
Keywords composer, scene switching, gotoScene

Overview

This function is used to transition to a specific scene. When called, the hide event is dispatched to the current scene (if one exists). If a self.view group does not already exist for the specified target scene, the create event will be dispatched to that scene, then the show event will be dispatched.

Syntax

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

String. The name of the scene to go to. In many cases, this is the name of the scene's Lua file (without the .lua extension).

options (optional)

Table. This table contains several transition-related options such as the effect type, custom parameters, etc. See the Scene Options for the acceptable format of this table.

Scene Options

The options table can contain various options pertaining to the target scene:

local options =
{
    effect = "fade",
    time = 400,
    params = {
        sampleVar1 = "my sample variable",
        sampleVar2 = "another sample variable"
    }
}
effect (optional)

String. Specifies the effect for the scene transition. See Transition Effects for a list of valid options. If no effect is specified, the scene transition will occur instantaneously.

time (optional)

Number. The time duration for the effect, if a valid effect has been specified. Default is 500 milliseconds.

params (optional)

Table. An optional table containing any kind of custom data that should be transferred to the scene. In the specified scene, this data can be accessed via event.params in the create event or show event.

Transition Effects

The following string values are supported for the effect key of the options table:

Examples

Going to Another Scene
local composer = require( "composer" )

local currentScore = 200

-- Later...
local options = {
    effect = "fade",
    time = 800,
    params = { level="Level 1", score=currentScore }
}
composer.gotoScene( "results", options )
Reloading the Current Scene
local composer = require( "composer" )

-- Later...
local currScene = composer.getSceneName( "current" )
composer.gotoScene( currScene )