Storyboard APIThe Storyboard API, while very powerful and flexible, can admittedly seem very confusing to new users, and especially those who are coming from a 3rd party scene management library, such as the Director Class.

Today, I’m going to walk you through the most basic storyboard usage for those who want the Storyboard API to be as simple, and work similarly to, the Director Class. While packed full of useful advanced features, not all of these features have to be used (or even understood at first). This tutorial will show you how to get up and running with the Storyboard API as quickly and easily as possible.


The Storyboard API has some differences from most other 3rd party scene management libraries, particularly in the realm of scene changes. By default, storyboard scenes are not removed or purged when a scene transition takes place. However, with most third-party scene management libraries, every scene is removed on every scene change. To replicate this behavior as much as possible, you simply need to set an option in main.lua that causes all inactive scenes to be purged every time storyboard.gotoScene() is called.


local storyboard = require "storyboard"
storyboard.purgeOnSceneChange = true

Simple as that!

Scene Modules

With the Director class, your scene modules typically have a single function, new(), that gets called whenever the scene is loaded. Optionally, scenes can include a clean() function that gets called whenever the scene is unloaded. Here’s what a scene in the Director Class looks like:

Director Class Scene

module(..., package.seeall)

-- setup function:
function new()
local localGroup = display.newGroup()

local img = display.newImage( "hello.png" )
localGroup:insert( img )

return localGroup

-- cleanup function:
function clean()
print( "Called when scene is unloaded." )

When using the Storyboard API, a similar structure and logic can be applied (given you followed the Setup section above). Using the Storyboard API this time, here’s what the Director Class scene from above would look like:

Storyboard Scene

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

-- setup function:
function scene:createScene( event )
local img = display.newImage( "image.png" )
self.view:insert( img )
scene:addEventListener( "createScene" )

-- cleanup function:
function scene:destroyScene( event )
print( "Called when scene is unloaded." )
scene:addEventListener( "destroyScene" )

return scene

See? Not much difference there. While the way you do things is slightly different, the logic is completely the same. You place all scene creation and logic in the “createScene” event listener, and place all cleanup code in the “destroyScene” event listener.

The “createScene” listener corresponds to Director’s “new” function, and the “destroyScene” listener corresponds to the “clean” function. But don’t forget to set storyboard.purgeOnSceneChange to true in your main.lua file, or the “destroyScene” event won’t automatically be dispatched every time you change scenes.

Now that you get how to setup your scenes in a similar fashion to the Director Class, you simply use storyboard.gotoScene() to switch between the different scenes.


Of course, there’s a lot more to the Storyboard API than that, but it’s not necessary to use all the features unless you need them. For most cases, and especially for those who are coming from the Director Class, using Storyboard in the way described in this tutorial should be sufficient.

  1. When you set:

    storyboard.purgeOnSceneChange = true

    if I understand correctly, only display objects will be purged, unlike Director where the whole scene is unloaded (in storyboard terms, “remove”ed) Is this the case?

    I would love to just set a flag like .purgeOnSceneChange that would cause my scenes to come in completely fresh each time.

  2. What is the best approach for use of modules within Storyboard?
    I noticed that if I have scene created as external lua file – it will be loaded and displayed w/o problems. But if I leave storyboard scene and then return back to the same scene again it will not be displayed because (correct me if I am wrong) all display objects are removed and previosuly loaded module doesn’t have display objects anymore.
    One workaround is to use your object class to create new module everytime I enter the Storyboard scene again.
    This is very interesting topic and I would be very happy to se some examples of modules within Storyboard scenes (idea for future blog post maybe?)

  3. Agree with Rob Miracle, would be handy to have storyboard.removeOnSceneChange instead of manually calling storyboard.removeAll() or storyboard.removeScence() on scene:didExitScene().

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>