composer.gotoScene()

Type Function

Library composer.*

Return value none

Revision Release 2024.3703

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:

"fade"
"crossFade"
"zoomOutIn"
"zoomOutInFade"
"zoomInOut"
"zoomInOutFade"
"flip"
"flipFadeOutIn"
"zoomOutInRotate"
"zoomOutInFadeRotate"
"zoomInOutRotate"
"zoomInOutFadeRotate"
"fromRight" — over current scene
"fromLeft" — over current scene
"fromTop" — over current scene
"fromBottom" — over current scene
"slideLeft" — pushes current scene off
"slideRight" — pushes current scene off
"slideDown" — pushes current scene off
"slideUp" — pushes current scene off

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 )

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