Composer Library

Understanding Scenes

The Composer lifecycle starts within main.lua. However, main.lua itself is not a Composer scene — it is merely used for initialization code, then it launches the first scene via composer.gotoScene(). In this call, specify the name of the scene (file) to be loaded, minus the .lua extension:

local composer = require( "composer" )

-- Code to initialize your app

-- Assumes that "scene1.lua" exists and is configured as a Composer scene
composer.gotoScene( "scene1" )

Scenes are basically just Lua files, existing as separate .lua files in your project. There is, however, some additional structural setup that you must obey so that Composer can treat them as scenes. This includes two lines to initialize the scene, four listener functions to handle the events that Composer generates, four lines of code to initialize these listener functions, and a basic return to associate the scene with Composer. Please see the sample scene template below.

The scene object itself is created by calling composer.newScene(). This object holds important data for the scene that Composer must access. For the developer, the most important aspect is the scene's self.view display group — this is the display group to which all of the scene's visual content should be added.

function scene:create( event )

    -- Assign "self.view" to local variable "sceneGroup" for easy reference
    local sceneGroup = self.view

    local rect = display.newRect( 160, 240, 200, 200 )
    -- Insert rectangle into "sceneGroup"
    sceneGroup:insert( rect )
end

Scene Flow/Events

Four different life cycle functions handle Composer-generated events:

Once composer.gotoScene() is called, the scene's life cycle begins and it follows this basic flow:

1. The scene's .lua file is loaded and a Composer scene object is created via composer.newScene(). At this point, the scene's view (self.view) is not initialized.

2. The scene's view is initialized and, if the view does not already exist, a create event is dispatched to the scene's scene:create() function. At this point, the scene still resides "off screen," so this is an opportune time to create user interface objects and other display objects needed for the scene, including buttons, text, graphics, and other objects that should show when the scene comes on screen.

3. Immediately before the scene transitions "on screen," a show event is dispatched to the scene's scene:show() function with a phase parameter equal to "will". This is a great opportunity to reset variable values or reposition objects that may have moved from their intended starting position since the scene was last shown (like restarting a game level).

4. Once the scene is fully on screen, another show event is dispatched to the scene:show() function with a phase parameter equal to "did" and this scene is now considered the active scene. This is a good place to start transitions/timers, play scene-specific music that was loaded in scene:create(), and start the physics simulation if you're using Corona's physics engine.

5. If this active scene is exited by going to another scene, for instance, a hide event is dispatched to the scene's scene:hide() function with a phase parameter equal to "will". This is a great opportunity to pause or stop physics, cancel timers and transitions, and stop scene-specific audio that was played in scene:show().

6. Once the scene is fully off screen, another hide event is dispatched to the scene:hide() function with a phase parameter equal to "did". At this point, the scene's view remains initialized since, by default, Composer keeps hidden/inactive scenes in memory on the assumption that they may be re-shown periodically.

7. From this point, if the scene is ever destroyed, either by command or as a result of auto-recycling, a destroy event is dispatched to the scene's scene:destroy() function. This is when Composer cleans up the scene's display objects (any display objects that you inserted into the scene's self.view group or a child group of it). This is also a good time to "undo" things that you did in scene:create() which are not related to the scene's display objects, for example, dispose of scene-specific audio.

Scene Template

The following template can be used to create new scene files. Note that this template includes listener functions for all potential events in the scene, but you only need to include listeners for the events that you want to handle.

local composer = require( "composer" )

local scene = composer.newScene()

-- -----------------------------------------------------------------------------------
-- Code outside of the scene event functions below will only be executed ONCE unless
-- the scene is removed entirely (not recycled) via "composer.removeScene()"
-- -----------------------------------------------------------------------------------




-- -----------------------------------------------------------------------------------
-- Scene event functions
-- -----------------------------------------------------------------------------------

-- create()
function scene:create( event )

    local sceneGroup = self.view
    -- Code here runs when the scene is first created but has not yet appeared on screen

end


-- show()
function scene:show( event )

    local sceneGroup = self.view
    local phase = event.phase

    if ( phase == "will" ) then
        -- Code here runs when the scene is still off screen (but is about to come on screen)

    elseif ( phase == "did" ) then
        -- Code here runs when the scene is entirely on screen

    end
end


-- hide()
function scene:hide( event )

    local sceneGroup = self.view
    local phase = event.phase

    if ( phase == "will" ) then
        -- Code here runs when the scene is on screen (but is about to go off screen)

    elseif ( phase == "did" ) then
        -- Code here runs immediately after the scene goes entirely off screen

    end
end


-- destroy()
function scene:destroy( event )

    local sceneGroup = self.view
    -- Code here runs prior to the removal of scene's view

end


-- -----------------------------------------------------------------------------------
-- Scene event function listeners
-- -----------------------------------------------------------------------------------
scene:addEventListener( "create", scene )
scene:addEventListener( "show", scene )
scene:addEventListener( "hide", scene )
scene:addEventListener( "destroy", scene )
-- -----------------------------------------------------------------------------------

return scene

The first line localizes the Composer library for the scene and the next line creates the scene's view. After this, you should include any scene-wide functions and forward-declare local variables that will be used in the scene. Because Lua files are only loaded once, variables that you set here will not be reset when you revisit the scene unless you take explicit steps to unload the file.

After this are the four functions to handle events generated for the scene. Then, event listeners are declared to handle scene events and, finally, the scene object is returned to Composer.

Note that within the listener functions, self.view is assigned to the local variable sceneGroup for easy reference. If you need to reference the scene's view outside of these functions, just use scene.view.

Going to Scenes

Once you create scene .lua files, you need a method to access them. In Composer, this is accomplished via composer.gotoScene():

composer.gotoScene( sceneName )

The sceneName parameter corresponds to the name of the Lua file, without the .lua extension. For example, if you have a scene file named menu.lua, access that scene with:

composer.gotoScene( "menu" )

In addition, there are several parameters which you can optionally pass to composer.gotoScene() to control the transition as well as provide data to the scene. You can do the following:

• Set the transition effect (see transition effects below).
• Set the transition time.
• Pass a table of parameters/data to the scene.

local options = {
    effect = "fade",
    time = 500,
    params = {
        someKey = "someValue",
        someOtherKey = 10
    }
}
composer.gotoScene( "menu", options )

In this example, the menu.lua scene will transition on screen using a "fade" effect over the span of 500 milliseconds. An optional table of parameters is also passed in. To access this data from the menu.lua scene, access the event.params table in the target scene's scene:create() or scene:show() function:

function scene:create( event )
    local sceneGroup = self.view
    local params = event.params

    print( params.someKey )
    print( params.someOtherKey )
end

Scene Management

One key feature of Composer is that, for the most part, it manages display objects automatically, assuming you insert them into the scene's view group:

function scene:create( event )

    -- Assign "self.view" to local variable "sceneGroup" for easy reference
    local sceneGroup = self.view

    local menuBack = display.newRect( display.contentCenterX, display.contentCenterY, 280, 360 )
    -- Insert object into "sceneGroup"
    sceneGroup:insert( menuBack )
end

Upon this scene being recycled or removed, Composer will handle the proper disposal of the menuBack object, along with other objects that were inserted into the scene's view group or a child group of it. Touch, tap, and collision listeners applied to these objects will also be removed.

composer.recycleOnSceneChange = true

composer.recycleOnSceneChange = false

composer.removeScene( "menu" )

composer.removeScene( "menu", true )

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

Overlay Scenes

Composer allows you to have one overlay scene. This is a scene that gets loaded on top of the active scene (the parent scene). An overlay scene is constructed like any other Composer scene.

local options = {
    effect = "fade",
    time = 500,
    isModal = true
}
composer.showOverlay( "inventory", options )

composer.hideOverlay( "fromBottom", 400 )

------------------------------------------------------------------------------
-- In "scene1.lua" (parent scene)
------------------------------------------------------------------------------
local composer = require( "composer" )

local scene = composer.newScene()

-- Custom function for resuming the game (from pause state)
function scene:resumeGame()
    --code to resume game
end

-- Options table for the overlay scene "pause.lua"
local options = {
    isModal = true,
    effect = "fade",
    time = 400,
    params = {
        sampleVar = "my sample variable"
    }
}

-- By some method (a pause button, for example), show the overlay
composer.showOverlay( "pause", options )

return scene

------------------------------------------------------------------------------
-- In "pause.lua"
------------------------------------------------------------------------------
local composer = require( "composer" )

local scene = composer.newScene()

function scene:hide( event )
    local sceneGroup = self.view
    local phase = event.phase
    local parent = event.parent  --reference to the parent scene object

    if ( phase == "will" ) then
        -- Call the "resumeGame()" function in the parent scene
        parent:resumeGame()
    end
end

-- By some method (a "resume" button, for example), hide the overlay
composer.hideOverlay( "fade", 400 )

scene:addEventListener( "hide", scene )
return scene

Other Methods/Properties

Composer features a few convenience methods and properties to assist with your scene management.

composer.setVariable( "gameLevel", 1 )
composer.setVariable( "playerName", "Zorron" )

local playerName = composer.getVariable( "playerName" )

local currScene = composer.getSceneName( "current" )
local prevScene = composer.getSceneName( "previous" )
local overlayScene = composer.getSceneName( "overlay" )