Scene Management

The Director API is used to create and manage scenes (or levels) in Gemini. Scenes are collections of layers and their associated objects in addition to the code that defines their behavior. Scenes are loaded via the Director API and this API allows for dynamic transitions between scenes.

Each scene is defined by a lua module based on the following template:

----------------------------------------------------------------------------------
--
-- scene_template.lua
--
----------------------------------------------------------------------------------

local director = require("director")
local scene = director.newScene()


---------------------------------------------------------------------------------
-- Scene event handlers
---------------------------------------------------------------------------------

-- Called when the scene is first created
function scene:createScene(event)

	-----------------------------------------------------------------------------
	--	CREATE display objects here (layers, groups, sprites, etc.)
	-----------------------------------------------------------------------------

end

-- Called immediately after scene has moved onscreen
function scene:enterScene(event)

	-----------------------------------------------------------------------------
	--	Start timers, set up event listeners, etc.  
	-----------------------------------------------------------------------------

end


-- Called when scene is about to move offscreen
function scene:exitScene(event)

	-----------------------------------------------------------------------------
	--	Stop timers, remove event listeners, etc.
	-----------------------------------------------------------------------------

end


-- Called when the scene is about to be deallocated
function scene:destroyScene(event)

	-----------------------------------------------------------------------------
	--	Cleanup scene elements here
	-----------------------------------------------------------------------------

end

---------------------------------------------------------------------------------
-- End of event handers
---------------------------------------------------------------------------------

scene:addEventListener("createScene", scene)

scene:addEventListener("enterScene", scene)

scene:addEventListener("exitScene", scene)

scene:addEventListener("destroyScene", scene)

return scene

Essentially this template defines a set of event handlers to respond to the various events that a scene receives during its lifetime. These are

• createScene - Received when the scene is first loaded. This is where most of the objects in the scene will be created.
• enterScene - Received when the director has transitioned into this scene. This is where most functionality for the scene will be enabled.
• exitScene - Received when the director transitions away from a scene. This is where scene functionality is suspended.
• destroyScene - Received when a scene is unloaded. This is provided to allow a scene to perform cleanup on itself.