Director does what is called an “un-require” to completely unload the module and when it reloads it, everything starts over. This can be simulated by calling:
storyboard.removeScene(“scenename”)
prior to doing:
storyboard.gotoScene(“scenename”)
There are really three considerations for making the most out of storyboard:
- The scene’s main chunk
- Creating the view
- Entering/exiting the scene
The scene’s main chunk (code outside of createScene(), enterScene(), exitScene() and destoryScene() only gets executed once ever until the scene is un-required and required again. Storyboard scenes are just Lua modules that Storyboard requires as necessary.
If you have variables defined in the main chunk, or code that runs (not just defined functions sitting there, but code to actually run the functions) out of the main chunk. You get it once and only once. So lets say you have a value you want to start the level out at like say resetting the score to 0, if you do:
local score = 0
in the scene’s main chunk, and later on during play of that round score changes to 100, then the next time you goto that scene, score will be 100. It will not reset to 0. To get that code to re-execute, you have to un-require the scene, which as I said above that’s what storyboard.removeScene does.
Now, for createScene(). This only gets called if the scene’s “view” (the main display.newGroup() for the whole scene) has been deleted and nil’ed out (or it has never been created the first time). The storyboard.purgeScene() and auto purge settings removes the view so that createScene() will be executed on every re-entry. If purgeScene() or removeScene() is called, then and only then will destroyScene() get called.
It’s important to know that for transitions to work, your scene’s visuals need created in the createScene() function, then they are transitioned onto the screen. For speed and efficiency, you should plan the code for createScene() to work in a way that you don’t need to purge it. That way we can keep it around and not have to re-create it.
Since the scene’s main chunk doesn’t re-execute and you shouldn’t be re-creating the view every time, how do you deal with it?
That’s where scene:willEnterScene() and scene:enterScene() come into play. If you need to reset any visuals (move them back to where they started, hide or unhide them, etc.) and you want that to happen before the scene transitions back on to the screen, then you need to put that code in the "willEnterScene() function (and setup it’s event handler at the bottom like enterScene()). The willEnterScene() will get called every time like enterScene if you’ve set it up. It has a partner function: didExitScene() that runs after the scene is transitioned off the screen. The exitScene() happens before the scene transitions off.
Finally once the scene is on the screen, then enterScene() can be used to reset any other variables or objects that it’s okay to reset after being on the screen. Here you would start up any transitions and timers needed (of course stopping them in exitScene().
So there, short answer: if you want to use brute force, just call removeScene(). If you want to plan your code a bit better, implement willEnterScene() and reset/recreate things as necessary.
