Scene Management

Most applications and games have different scenes (e.g., menu, scoreboard, game levels, inventory, end-of-game, etc). A transition from one scene to another is usually started by user input or some other event. These transitions typically consist of the following steps:

• Construct the new scene (e.g., load bitmaps, sprites, sounds)
• Hide the original scene and show the new scene, often with some kind of special effect (e.g., crossfading)
• Destroy the old scene

High level scene management functions aren’t provided directly in Gideros but the Gideros team has released a “Scene Manager” library (see: https://github.com/gideros/Scene-Manager) that can be used as is or that can be modified and extended to by the user (it’s licensed under the liberal MIT license). The library includes a demonstration Gideros project that shows many of the available built-in transitions (a demonstration video can be found on YouTube: http://www.youtube.com/watch?feature=player_embedded&v=KQMSHOMInQU)

Scene Manager Usage Overview

Create a class for each of your scenes (and preferably put them into separate .lua files):

Menu = gideros.class(Sprite)
Game = gideros.class(Sprite)
EndScene = gideros.class(Sprite)

Create a SceneManager instance passing a table with scene names as keys and your classes as values:

local sceneManager = SceneManager.new{
   ["menu"] = Menu,
   ["game"] = Game,
   ["endScene"] = EndScene,
}
stage:addChild(sceneManager)

Change between scenes with function SceneManager:changeScene(sceneName, duration, transition, ease) like so:

sceneManager:changeScene("game", 1, SceneManager.moveFromTop, easing.linear)

SceneManager dispatches events as it makes the transition from one scene to another (enterBegin, enterEnd, exitBegin, exitEnd). You can register to listen for these events to begin/end your animations, clear your timers, save the scores, etc.

Built-in Transition Effects

The scene manager library defines the following transition effects:

Move functions

• SceneManager.moveFromLeft
• SceneManager.moveFromRight
• SceneManager.moveFromBottom
• SceneManager.moveFromTop
• SceneManager.moveFromLeftWithFade
• SceneManager.moveFromRightWithFade
• SceneManager.moveFromBottomWithFade
• SceneManager.moveFromTopWithFade

Overlay functions

• SceneManager.overFromLeft
• SceneManager.overFromRight
• SceneManager.overFromBottom
• SceneManager.overFromTop
• SceneManager.overFromLeftWithFade
• SceneManager.overFromRightWithFade
• SceneManager.overFromBottomWithFade
• SceneManager.overFromTopWithFade

Fade & flip functions

• SceneManager.fade
• SceneManager.crossFade
• SceneManager.flip
• SceneManager.flipWithFade
• SceneManager.flipWithShade

Transition Events

The scene manager dispatches the following four events:

• enterBegin: Dispatched when your new scene is about to enter the stage. You can initialize your variables here.
• enterEnd: Dispatched after the transition of new scene has ended. Mostly, you add listeners and start your logic here.
• exitBegin: Dispatched when your current scene is about to leave the stage. You can remove listeners and stop timers here.
• exitEnd: Dispatched after your current scene has leaved the stage.

The following code shows an example scene (“MyScene”) and how you might use the “enterEnd” and “exitBegin” events:

MyScene = gideros.class(Sprite)

function MyScene:init()
  self:addEventListener("enterEnd", self.onEnterEnd, self)
  self:addEventListener("exitBegin", self.onExitBegin, self)
end

function MyScene:onEnterEnd()
  self:addEventListener(Event.ENTER_FRAME, self.onEnterFrame, self)
  -- create your timers
  -- also you can add your player sprite
  -- and so on...
end

function MyScene:onExitBegin()
  self:removeEventListener(Event.ENTER_FRAME, self.onEnterFrame, self)
  -- stop your timers
  -- save score
  -- and so on...
end