Scene Management

From GiderosMobile

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: 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:

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 ={
   ["menu"] = Menu,
   ["game"] = Game,
   ["endScene"] = EndScene,

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)

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

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