Posted on by
NOTE: This tutorial is outdated and has been replaced by resources in Corona University. Please refer to these guides and tutorials for current information and usage examples.

Posted by . Thanks for reading...

68 Responses to “Introducing the Storyboard API”

  1. Nicholas G

    Wow, I just started learning director – now I think I may want to drop that…maybe.

    I hope Corona puts this as a “template” project (like there is comic, game, etc – at least on the MAC there is, windows isn’t there yet).

    I would love to have that kind of integration instead of relying on 3rd party authors. That isn’t a knock on director – I mean Ricardo busted his ass on that thing, and released it for free! I just think it’s time for some “native” tools to make corona a more complete package.

    And John Beebe is epic.

    The end.

    Reply
  2. Naveen

    When I call storyboard.removeScene(“nameOfScene”) is it automatically removing all displayObjects from that scene and freeing their memory? I have a master displayGroup for each of my “scenes” and I just want to make sure that this master displayGroup is properly being removed.

    Reply
  3. Jonathan Beebe

    @Naveen: Yes, storyboard.removeScene() will first call storyboard.purgeScene() — which removes the ‘view’ group from that scene, and then it also proceeds to removing the loaded module from memory as well. That last bit is where removeScene differs from purgeScene.

    As long as your displayGroup is inserted into the ‘view’ group of your scene, then that will get removed also. Or, you can just place your masterGroup:removeSelf() code in your “destroyScene” event listener. That will also do it (because “destroyScene” is always dispatched before a scene is purged).

    Reply
  4. Naveen

    Also, when I do removeScene and then go back to the scene that I removed, it doesn’t call createScene. Is this supposed to happen? I want to fully destroy the scene when I leave it, and the remake it from scratch when I return.

    Reply
  5. Naveen

    @Jonathan Thanks, I set my masterGroup to self.view and it seems to be working correctly, except for createScene not getting called after the scene has been destroyed (see my previous comment).

    Reply
  6. Jonathan Beebe

    @Naveen: When you call storyboard.removeScene(), the scene will be loaded from complete scratch the next time you call storyboard.gotoScene() on it (everything inside and outside of the listeners will be executed).

    When you use storyboard.purgeScene(), only the ‘scene.view’ display group is removed (to free up texture memory). When you call gotoScene() a “createScene” event is dispatched, but the module is already loaded so it doesn’t need to be reloaded again (in other words, code outside of your listener functions won’t be executed).

    So yes, if you want to completely remove the scene so the module loads from scratch next time, use storyboard.removeScene().

    Reply
  7. Naveen

    @Jonathan I think it’s a bug then. I do call removeScene but it will not call createScene when I return to it. The first few times that I switch between the 2 scenes it does work and it re-creates the scene, but after 3-4 times, it stops calling createScene. It seems like it’s still being saved in memory somehow (I checked memory usage as I did this). Weird….

    Reply
  8. Jonathan Beebe

    @Naveen: I recommend you post your code in a forum thread, and then post a link to the thread here. From my testing, storyboard.removeScene() seems to be behaving correctly. To test, you can look at the Storyboard SampleCode, and in the “enterScene” listener on each scene, change the call to ‘purgeScene’ to ‘removeScene’ instead, and when you cycle through the screens again, you’ll see that the “createScene” event is definitely getting called.

    If you’re still having problems, once again, please post your code in the forums and post your link and I’ll try to help you out from there. If you’re having confusion/problems, its likely other users are as well.

    Reply
  9. Naveen

    @Johnathan Wow, I feel so stupid. I missed out on 1 letter when typing out one of the lines for the storyboard api. It was removing the wrong scene by accident. Sorry about that! It’s actually pretty painless switching from director > storyboard (though I wish you could pick the fade colour). Thanks for the help! :)

    Reply
  10. Jonathan Beebe

    @Naveen: No worries, glad you got it straightened out :-)

    Will make note of the fade color suggestion—thanks!

    Reply
  11. Ricardo Rauber Pereira

    Nobody will like me anymore… lol

    This is great, I did a lot of stuff on Director because I am a developer and aleays wanted something like this right from the box. Storyboard is a great step, I hope it could answer all the questions that Director could not did.

    That was a great time since Director 1.0, thanks Ansca and Corona community for everything!

    Reply
    • Hitendra

      hi Ricardo,

      I was a big fan of director class and I used it for my app your efforts were very much appreciated and I know you

      Reply
  12. Jonathan Beebe

    @Ricardo: No worries, I’m sure everyone will still like you, lol.

    I’m pretty sure there will still be a lot of folks using Director, particularly those who need a more open-source approach due to specialized needs, etc. (such as the comment someone made about a colored-fade effect and probably a plethora of other things that Director has that’s out of the scope of storyboard).

    Thank you so much for your contributions, and for helping out the community in such a big way until we were able to provide an official solution. In fact, I personally used the Director class in my games/apps that I had released previously, it was a huge time-saver :-)

    Looking forward to your future contributions, apps, Director updates, etc.

    Thanks again Ricardo.

    Reply
  13. nick

    After some messing around, I figured out I am not ready for this. I just started getting used to director, and I am so far along that I will have to implement this into the next project, or when I do updates to my game.

    I was hoping to change fade color, then realized I wasn’t able to and got a sad face. That’s ok though, I’ll let this mature a bit and come back to it as it looks sweet!

    ng

    Reply
  14. MrMells

    Disclaimer : I don’t know Ricardo personally.

    Knowing that the Director Class has been helping a lot of newcomers to Corona Sdk until now and a great helper for user adoption, I was thinking that it would be a nice move from Ansca to reward Ricardo in some way (money, or anything else that suits Ansca).

    There is no doubt that Ricardo didn’t do it for the money, but that would be a perfect example of how “sharing the love” can be rewarded for being a loyal “Partner” of Corona Sdk. Just my 2 cents :)

    What do you think about this Ansca, does this sound reasonable?

    Reply
  15. Fotis

    What’s the best way to pass variables between scenes using storyboard?

    @Ricardo We do like you and looking forward for updates :)

    Reply
  16. MichaelS

    @Ricardo: You know, never change a running system, so I will stay on Director because I know how to use it and how it’s working. So don’t worry, your class will be alive….

    Reply
  17. Tim Masterson

    Way to go corona. @Ricardo for me your director class is what made my experience with Corona so great.

    Corona team I am continually impressed with the speed and quality you all are building out this excellent toolset with.

    Corona has seriously helped me do more with my limited, time, staff and money. Thanks Guys.

    Reply
  18. iNSERT.CODE

    Another great (and somewhat unexpected) step for Corona.

    I’d like to thank and applaud Ricardo though for his efforts with Director – a first class and selfless act on his part for the community.

    Reply
  19. PiotrT

    That is really nice.
    Jonathan I understand that we can use purgeScene in for example tabView app when you can fast go back to previous screen but I guess in a game when we have mainMenu.lua, level1.lua , level2.lua etc we will be using removeScene… Am I wrong ?

    Reply
  20. ojnab

    Great thanks.
    Wondering about this though:

    Is there a way to tell what the previous scene was.
    In the example we remove scene1 from scene2 with this:

    storyboard.removeScene( “scene1″ )

    but what if we don’t know what the previous scene was. Then we can’t hardcode the removeScene like this.
    We don’t always come from scene1 when we enter scene2….

    Reply
  21. Alex

    Jonathan and everybody else,

    Regarding Storyboard and Director, are you planning a quick how to on how to migrate projects from Director to Storyboard? Also, will Storyboard come with transitions like the one offered by Director? Lastly, will the page curl transition finally arrives with Corona (maybe the secret feature mentioned in the daily builds)?

    Reply
  22. Antheor

    Ricardo, you’re the one that made me switch from flash to corona 1 year ago : easing scene management and your “always willing to answer” state were unvaluable.

    I will probably try to test the right from the box solution, but don’t know if I will drop director.

    BTW : was scenemanager a beta for storyboard ?

    Reply
  23. carlos m. icaza

    The point that @jonathan brings is exactly the reason we want Director to still be around. Ricardo has been a great contributor to the Corona community and we (Ansca) will certainly want him to be around and continue further development of Director and also contribute in other ways.

    Ricardo is a Certified Corona Developer and his contributions are essential to the success of Rauber Labs and for us here as well at Ansca.

    Carlos.

    Reply
  24. Nick

    This sounds pretty cool as I’ve been playing around with Director whilst toying with code for a Hangman game app I thought I’d try out. Started off as a bit of code tinkering, having not used Corona for a while, but I may tweak it some more, up the graphics and submit it to the various app stores. However, I got into a few issues with clearing Runtime events which I subsequently fixed, but thinking now I’l try and incorporate the Storyboard API solution instead, to move between word categories and winning and losing scenes etc. You guys just keep bringing out more and more solutions. Keep up the great work!

    Reply
  25. Jonathan Beebe

    @ojnab: Great point! In the next update we’ll be sure to provide a way to know what the previous scene was :-)

    @PiotrT: We recommend using purgeScene if you plan on going back to that scene at some point in the near future and just want to free up texture memory (the module will still be loaded, but its display group will be removed). We recommend using removeScene if you don’t plan on going back to that scene, or if you need to retain as much memory as possible (the display group as well as the module will be released from memory with removeScene).

    Reply
  26. Jonathan Beebe

    @Fotis: The easiest way to do this is to assign variables to the ‘storyboard’ object itself, for example:


    storyboard.testVar = "Hello World"

    The storyboard.testVar variable would be accessible by all of your scenes. However, what I would recommend is making ‘testVar’ (or whatever) a table instead, and add your variables to that so you don’t accidentally conflict with storyboard’s internal properties.

    Reply
  27. Ojnab

    @jonathan thanks. Looking forward to use Storyboard in my next project… it looks really promising.

    @Ricardo. I also wan’t to express my grattitude for your work and sharing of director.
    Please don’t stop developing on it. I can easily imagine projects where I will choose Director over Storyboard, because it is open source and I can modify it any way I want to.

    Reply
  28. Jonathan Beebe

    Also, for those commenting on fade color. Remember, the black you’re seeing isn’t the “fade color”, it’s the default background of an empty canvas. So in all actuality, you can change the fade color by using:


    display.setDefault( "background", r, g, b )

    In effect, the above will change the fade color to whatever you set it (assuming you don’t have something else set as a static background for your whole app).

    Reply
  29. lKinx

    Do I only need the require storyboard statement at the top and the storyboard.goToScene() method to switch my lua files? I really hope so, because I hate adding my images to the director group right now.

    Reply
    • Jonathan Beebe

      @IKinx: I’m not exactly sure what you’re asking, but that sounds about right. You require “storyboard” at the top, and then use storyboard.gotoScene() to switch to the new scene (note that the T in “goto” is lowercase as well). I recommend you download the SampleCode and read through the API to become more familiar with it. The Sample is really small and should be pretty easy to digest.

      Reply
  30. Mario

    What the?!! I JUST saw this!! Man, Ansca you guys just don’t STOP!!! Excellent addition to the repertoire!!!!! Thank you so much!

    Reply
  31. iNSERT.CODE

    Hey @Jonathan, I have a mainMenu.lua and a settings.lua, and I want to transition from settings back to the mainMenu using a button (the logic is in enterScene). I want to use removeScene() to clear memory completely so where exactly should I put the line storyboard.removeScene( “settingsScreen” )? Would it go in exitScene or destroyScene or in the button logic after the call to storyboard.gotoScene( “mainMenu”, “fade”, 800 )?

    Also, when using Director I had a function called cleanUp() that I ran before exiting that scene – it removed listeners, timers, transitions etc – where should I put this logic with the above in mind – exitScene or destroyScene?

    Sorry for the long post

    Reply
  32. PiotrT

    @insert.code I guess removeScene() should go to scene:enterScene in a scene that you are changing to. It will be in mainMenu.lua. but you will remove settings (there is nothing to remove yet ) also when you call mainMenu.lua for the first time so I’am not sure.

    I have very similar problems… for example I’am creating 20 objects in ” for ” loop. Each object I am adding to the group and adding collisions to each one , so I have to make two loops.. One for creating objects in scene:createScene and another loop in scene:enterScene to adding collision ? Logic for this collisions goes to enterScene also right ? In example it’s look like very easy but when I started to change my project the problem is what exactly should go where…

    Reply
  33. david

    Great feature!
    Cannot find a way to add a “enterFrame” listener local to the scene (I got runtime error).
    For now, I create an external Listener function, with a “Runtime:addEventListener( “enterFrame”, myListener )”.
    I tried to create a scene:enterFrame then call scene:addEventListener( “enterFrame”, scene ), but nothing occurs. Any help?

    Reply
  34. ckausik

    I was super excited to see this new development. But then I read:

    “For those of you using the widget library in your apps, currently, there may be some unexpected behavior with some widgets being inserted into scene groups. ”

    What exactly could go wrong when using storyboard with widgets? Should I stay off this for now until issues are settled?

    Reply
  35. Jonathan Beebe

    @iNSERT.CODE: I would recommend placing removeScene() in the “enterScene” event of the scene you will be transitioning to. Or, you can even place it in the “exitScene” event of the scene you want removed. I recommend taking a look at the SampleCode (with the terminal) because it shows you exactly when all events are dispatched, and it also provides a good sandbox to experiment with things like that (and see how it affects things). The director-equivalent to your cleanUp() function would be either the “exitScene” or the “destroyScene” event. Remember, “destroyScene” is only dispatched before a scene is about to be purged (scenes are also purged when you call removeScene as well). “exitScene” is dispatched whenever a scene is being transitioned-out.

    @PiotrT: If removeScene is called and the scene doesn’t exist, nothing will happen. This is also shown in the samplecode. In the “enterScene” event of scene1, it calls purgeScene on scene4. When the app first starts, scene4 was never loaded. No errors are thrown though, nothing bad happens if you call removeScene or purgeScene on a scene that doesn’t exist. Also, you could create objects and add collisions to them in the same for loop within the enterScene, because “createScene” will only be called if the objects are removed. If objects aren’t removed (e.g. purgeScene or removeScene wasn’t called), then objects should retain their collision listeners (and not need to be added during the ‘enterFrame’ event).

    @ckausik: If your widgets worked fine with Director, they should be fine here. The reason that statement was placed there was because things hadn’t been thoroughly tested with widgets yet, and we wanted you to know to be cautious. Widgets such as the ‘button’ and things like that should be fine. Just give it a shot and see if things are still transitioning properly for you (and also, don’t forget to manually remove widgets in your scene in the “destroyScene” event).

    Reply
  36. Jonathan Beebe

    @david: Because “enterFrame” events are runtime-only events, the only thing you can add that to is the ‘Runtime’ object. If you tried doing object:addEventListener( “enterFrame”, object), it wouldn’t work either, so this isn’t an issue with scenes. By design, you can only add an enterFrame listener to the Runtime object, even if the listener function is a table within another object.

    Examples:

    — valid:
    Runtime:addEventListener( “enterFrame”, myObject )
    Runtime:addEventListener( “enterFrame”, myListener )

    — not valid:
    myObject:addEventListener( “enterFrame”, myObject )

    — valid (touch listener):
    myObject:addEventListener( “touch”, myObject )

    Hope that clears some things up for you!

    Reply
  37. leafcutter

    I found in build 685 that the animated effects did not work – they just stopped on the first frame. If i use gotoScene(“scene1″) that is fine but if i use gotoScene(“scene1″, “flip”, 500) all I can see is my scene compressed into a very thin vertical line in the middle of the scene (i.e. the start of the flip transition)

    Reply
  38. Jonathan Beebe

    @leafcutter: In the latest build’s release notes (though not available for download at the moment), the “effect on first scene” issue has been fixed. Currently, there are no more known issues in the next build that becomes available for download

    Reply
  39. Mike M

    Very nice addition to the API, and expediently implemented. I’m really appreciate that step.

    Just one request. Please force the compatibility to the tableview widget. The slide transition for tableview is such an important feature.

    Thanks!

    Reply
  40. finefin

    Just started a new project with the scene template and it works great!
    And once again I was able to prototype a new idea in less than 3 hours.
    happy happy happy! thank you!

    Reply
  41. Kang

    Hey Ricardo, I already think of you as beyond “Pro”, more of “Demi-god” level. Perhaps a label can be created for you by Ansca. That will be recognition enough I suppose.

    Reply
  42. satheesh

    @Ricardo Don’t Worry! We are not going to forget you any time soon! I ,for one ,am never changing from director..
    Storyboard is good but surplus to requirements.
    Cheers :)

    Reply
  43. russell

    It would only make sense that this is offered to ‘test drivers’. The reason why is it will allow beginners a much easier and simpler path to a completed game which in turn will turn into much higher subscription rates and overall higher revenue stream!

    Reply
    • Jonathan Beebe

      @russel: Test drivers have access to Storyboard API since the latest public release. Anyone who downloads Corona from now on has access to the Storyboard API.

      @andrew: We needed an official solution that didn’t require users to place extra files in their project directory. There are great open-source options available, such as the Director Class, for special cases where users have specific needs (which would require modifying the source code).

      Reply
  44. andrew

    I think this is a bad thing. You should have an module to do this, so that devs can look at the manager themselves.

    Reply
  45. russell

    @jonathan I’m having trouble running your code from github. I unzipped it and ran the main.lua file. It says main.lua:10: module ‘storyboard’ not found : resource (storyboard.lu) does not exist in archive
    No field package. preload ['storyboard']
    what am i doing wrong?
    tnx

    Reply
  46. troy nall

    johnathan, you stared explaining the, “exitScene” at the beginning of your article…
    “When storyboard.gotoScene() is called, an “exitScene” event will be dispatched to the currently shown scene before the transition occurs. Cleanup duties, such as removing event listeners, stopping timers, etc. should be placed in the listener function for this event.”

    when you say “transition occurs” (regarding exitScene), you mean the “exit” transition. which is totally different from the “starting” transition, correct ?

    Reply
  47. JORIS

    How can I force removal of scenes?

    Your advise to call storyboard.removeScene(“level1″) in function scene:exitScene( event ) results in an error:

    Runtime error
    ?:0: attempt to index field ‘?’ (a nil value)
    stack traceback:
    [C]: ?
    ?: in function ‘?’
    ?: in function ‘gotoScene’

    Reply
  48. Armin

    I’m using the API and have found an issue. Assume that I have 2 scenes (master/detail). I choose in the master scene an object which should be shown in details as soon I tap on it in the master scene. The first time details scene enters createScene is called. If I go back and reenter the details scene with another object tapped the old object id visible during the transition and then replaced by the new one. So wouldn’t we need for all events pre and post’s? In the pre I would check if the object changed…if not fine if yes i load the new one. then the transition starts and then then listeners etc. are registered. Actually in most SDK’s there are always pre and post events.
    Or am I wrong? How deal others with that? Getting the detail scene before calling gotoScene and fixing everything before?

    Reply
  49. mmedia

    how can i get access to the storyboard source code, there seems to be something wrong with the scenes, when you enter a new scene it calls the exit scene code aswell ….
    i suspect its whats causing joris’s error aswell a good work around for now is

    function scene:enterScene( event )
    local group = self.view
    poup=false
    — do nothing

    end

    — Called when scene is about to move offscreen:
    function scene:exitScene( event )
    local group = self.view
    print(debug.traceback())
    if popup==true then
    native.cancelWebPopup()
    storyboard.removeScene(“contact”)
    popup=false
    else
    popup=true
    end
    end

    Reply
    • Brent

      Hi @mmedia,
      Accessing the core code of Storyboard isn’t possible. For your scenario, do you wish to -not- call the exitScene code at all? Can you describe in more detail what you wish to do during each phase of Storyboard as you change scenes, i.e. what should happen to the current scene -and- the new scene in memory + visually?

      Reply

Leave a Reply

  • (Will Not Be Published)