Composer 库

理解场景

Composer 生命周期始于 main.lua。但是，main.lua 本身**不是** Composer 场景 — 它仅用于初始化代码，然后通过 composer.gotoScene() 启动第一个场景。在此调用中，指定要加载的场景（文件）的名称，不带 .lua 扩展名。

local composer = require( "composer" )

-- Code to initialize your app

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

场景基本上只是 Lua 文件，作为单独的 .lua 文件存在于您的项目中。但是，您必须遵循一些额外的结构设置，以便 Composer 可以将它们视为场景。这包括两行初始化场景的代码、四个用于处理 Composer 生成的事件的侦听器函数、四行初始化这些侦听器函数的代码，以及一个基本的 return 语句将场景与 Composer 关联起来。请参阅下面的示例 场景模板。

场景对象本身是通过调用 composer.newScene() 创建的。此对象保存 Composer 必须访问的场景的重要数据。对于开发者来说，最重要的方面是场景的 self.view 显示组 — 这是应将所有场景的可视内容添加到其中的显示组。

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

场景流程/事件

四个不同的生命周期函数处理 Composer 生成的事件：

调用 composer.gotoScene() 后，场景的生命周期开始，并遵循以下基本流程：

1. 加载场景的 .lua 文件，并通过 composer.newScene() 创建 Composer 场景对象。此时，尚未初始化场景的视图 (self.view)。

2. 初始化场景的视图，如果该视图**不存在**，则会将 create 事件分派到场景的 scene:create() 函数。此时，场景仍然位于“屏幕外”，因此这是创建场景所需的用户界面对象和其他显示对象的绝佳时机，包括按钮、文本、图形以及其他应在场景出现在屏幕上时显示的对象。

3. 在场景过渡到“屏幕上”之前，会将 show 事件分派到场景的 scene:show() 函数，其中 phase 参数等于 "will"。这是重置变量值或重新定位自上次显示场景以来可能已从其预期起始位置移动的对象（如重新启动游戏关卡）的绝佳机会。

4. 场景完全显示在屏幕上后，另一个 show 事件将分派到 scene:show() 函数，其中 phase 参数等于 "did"，并且此场景现在被视为活动场景。这是启动过渡/计时器、播放特定于场景的在 scene:create() 中加载的音乐，以及如果您正在使用 Corona 的 physics 引擎，则启动物理模拟的好地方。

5. 例如，如果通过转到另一个场景来退出此活动场景，则会将 hide 事件分派到场景的 scene:hide() 函数，其中 phase 参数等于 "will"。这是暂停或停止物理、取消计时器和过渡，以及停止特定于场景的在 scene:show() 中播放的音频的绝佳机会。

6. 场景完全从屏幕上消失后，另一个 hide 事件将分派到 scene:hide() 函数，其中 phase 参数等于 "did"。此时，场景的视图保持初始化状态，因为默认情况下，Composer 会将隐藏/非活动场景保留在内存中，因为它假设它们可能会重新显示定期。

7. 从这时起，如果场景被销毁，无论是通过 命令 还是由于 自动回收，都会将 destroy 事件分派到场景的 scene:destroy() 函数。这是 Composer 清理场景的显示对象（您插入到场景的 self.view 组或其子组中的任何显示对象）的时候。这也是“撤消”您在 scene:create() 中执行的操作（这些操作与场景的显示对象无关）的好时机，例如，dispose特定于场景的音频。

场景模板

以下模板可用于创建新的场景文件。请注意，此模板包含场景中所有潜在事件的侦听器函数，但您只需要包含要处理的事件的侦听器。

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

第一行本地化场景的 Composer 库，下一行创建场景的视图。在此之后，您应该包含任何场景范围的函数和前向声明将在场景中使用的局部变量。由于 Lua 文件只加载一次，因此除非您采取显式步骤卸载该文件，否则您在此处设置的变量将**不会**在您重新访问场景时重置。

之后是四个用于处理为场景生成的事件的函数。然后，声明事件侦听器以处理场景事件，最后，将 scene 对象返回给 Composer。

请注意，在侦听器函数中，self.view 被分配给局部变量 sceneGroup 以便于引用。如果您需要在这些函数之外引用场景的视图，只需使用 scene.view。

跳转到场景

创建场景 .lua 文件后，您需要一种方法来访问它们。在 Composer 中，这是通过 composer.gotoScene() 完成的。

composer.gotoScene( sceneName )

sceneName 参数对应于 Lua 文件的名称，不带 .lua 扩展名。例如，如果您有一个名为 menu.lua 的场景文件，请使用以下命令访问该场景：

composer.gotoScene( "menu" )

此外，您可以选择将几个参数传递给 composer.gotoScene() 以控制过渡并向场景提供数据。您可以执行以下操作：

• 设置过渡效果（请参阅下面的 过渡效果）。
• 设置过渡时间。
• 将参数/数据表传递给场景。

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

在本例中，menu.lua 场景将使用“淡入”效果在 500 毫秒内过渡到屏幕上。还传入了一个可选的参数表。要从 menu.lua 场景访问此数据，请在目标场景的 scene:create() 或 scene:show() 函数中访问 event.params 表。

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

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

场景管理

Composer 的一个主要特性是，在大多数情况下，它会自动管理显示对象，前提是您将它们插入到场景的视图组中。

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

在此场景被回收或移除后，Composer 将处理 menuBack 对象以及插入到场景的视图组或其子组中的其他对象的正确处置。应用于这些对象的触摸、点击和碰撞侦听器也将被移除。

composer.recycleOnSceneChange = true

composer.recycleOnSceneChange = false

composer.removeScene( "menu" )

composer.removeScene( "menu", true )

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

叠加场景

Composer 允许您拥有一个**叠加**场景。这是一个加载在活动场景（父场景）顶部的场景。叠加场景的构造方式与任何其他 Composer 场景一样。

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

其他方法/属性

Composer 提供了一些便捷的方法和属性来帮助您进行场景管理。

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" )