composer.loadScene()

Type Function
Library composer.*
Return value none
Revision Release 2024.3703
Keywords composer, scene, load, loadScene
See also composer.gotoScene()
composer.showOverlay()

Overview

Loads the specified scene, hidden behind the current scene, without initiating a scene transition. This function is similar to composer.gotoScene(), but it does not change the currently active scene. Only the create event will be dispatched on the scene, assuming its self.view does not already exist.

In addition, you can set an optional doNotLoadView flag when calling this function. Doing so will load only the scene's object, not its self.view display group.

This function is commonly used to "pre-load" a scene before initiating a transition on it, which would happen explicitly at a later time.

Syntax

composer.loadScene( sceneName [, doNotLoadView] [, params] )
sceneName (required)

String. The name of the scene to load, hidden behind the current scene.

doNotLoadView (optional)

Boolean. Set to true to load only the scene's object, not its self.view display group. Only the create event will be dispatched on the scene, assuming its self.view does not already exist.

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, unless doNotLoadView is set to true).

Example

local composer = require( "composer" )

local currentScore = 200

-- Pre-load the scene, hidden behind the current scene
local options = { level="Level 1", score=currentScore }
local results = composer.loadScene( "results", false, options )

-- Later, transition to the hidden scene (no loading necessary)
composer.gotoScene( "results", "fade", 800 )