Introducing the Composer API

Corona Labs logo
Share on Facebook0Share on Google+8Tweet about this on TwitterShare on LinkedIn2

We are excited to introduce the Composer library, our new scene manager!

For those of you new to scene management, it allows you to create Lua files that represent a scene in your app. When you navigate to different scenes using API calls, Composer handles the transitions and helps you easily clean up. It’s a very useful tool and can make creating and managing your games and apps much easier.

Introduction to scene events

In Composer, there are four scene events which reflect “when they occur” more so than “what they do.” These four scene events are create, show, hide, and destroy, and each will be discussed in further detail below. One of the primary design goals for Composer was to minimize these events into a manageable set without losing the ability to detect multiple events.

Diving into the scene template

In most cases, you should use the following scenetemplate.lua file to construct scenes. This basic template has the core features needed to implement a Composer scene:

The top portion of the scene loads the Composer library and then creates this scene’s scene object using composer.newScene().

Next, you should include any scene-wide functions and forward-declare local variables that will be used in the scene. Because Lua files are only loaded once, variables that you set here will not be reset when you revisit the scene unless you take explicit steps to unload the file.

Following this are the four functions which handle scene events generated for the scene:


This function is primarily used to create the display objects for a scene — basically, anything to display in the scene. This is also a good point to load (but not play) scene-specific audio files.

For Composer to “manage” your scene and the display objects within, all of these objects must be inserted into the scene’s view display group or a child display group of it. This group is referenced by the critical line at the top of each listener function:

Essentially, all display objects for the scene should be inserted into this group, for example:

Note that the scene:create() function is only called if the scene’s view does not exist — that is, it will be called the first time the scene is loaded. However, Composer tries to keep the scene in memory assuming that you’ll revisit it later, so if the scene remains in memory, scene:create() will not be called again.


In Composer, scene:show() will be called twice when a scene shows: once for each of these phases:

  • “will” — called when the scene is still off screen (but is about to come on screen).
  • “did” — called when the scene is fully on screen.

These new string values are specified in the event.phase table entry. The "will" phase is a great opportunity to reposition objects that may have moved from their intended starting position since the scene was last shown (like restarting a game level).

The remainder of the action will happen in the "did" phase of scene:show(). This phase is a good place to start transitions/timers, play scene-specific music, and start the physics simulation if you’re using Corona’s physics engine.

This is also the proper place to create native objects like text input fields, maps, etc. if you are showing the scene using one of the built-in “fade” effects. This is because native objects cannot automatically “fade in” along with the scene’s view, so it will look better if you show these objects after the scene is fully transitioned on screen.


In Composer, scene:hide() will be called twice when a scene is hidden: once for each of these phases:

  • “will” — called when the scene is on screen (but is about to go off screen).
  • “did” — called immediately after scene goes off screen.

Note that the scene:show() and scene:hide() events are tied together — for each "show" event, there’s a corresponding "hide" event. Therefore, during the "will" phase of scene:hide(), you may need to:

  • pause or stop physics
  • cancel timers and transitions
  • remove native objects
  • stop scene-specific audio

Generally, there isn’t much to handle in the "did" phase of scene:hide(), although you could remove the scene permanently if you desire.


The scene:destroy() function is where Composer cleans up the scene’s display objects (any non-native display object that you inserted into the scene’s view group or a child group of it). scene:destroy() is called just prior to this clean up. Here you can “undo” things that you did in scene:create() which are not related to the scene’s display objects, for example, dispose of scene-specific audio.

Because Composer tries to keep scenes in memory for performance reasons, this function is only called in these circumstances:

  1. If an explicit call is made to composer.removeScene().
  2. If Composer is set to automatically remove the scene’s view upon scene change.
  3. If the app receives a low memory warning from the OS.

Removing scenes

In Composer, composer.removeScene() allows you to explicitly remove a scene, and it also accepts a boolean true/false parameter (shouldRecycle) which controls how “deep” the operation goes:

composer.removeScene( "sceneName", shouldRecycle )

  • If the shouldRecycle boolean is set to true, only the scene’s view is destroyed. Consider this as if you placed a file in the trash/recycle bin of your OS — it’s out of sight, but the file still exists. If/when you come back to the scene, its scene:create() event will execute again, but any code outside of the listener functions will not be re-executed since the scene object resides in Lua’s memory.
  • If the shouldRecycle boolean is false or nil, Composer will destroy the scene’s view and unload the scene from Lua’s memory. Consider this as if you placed a file in the trash/recycle bin of your OS and then emptied the trash/bin — the scene is effectively removed and must be re-created if/when returning to it. In this case, its scene:create() event will execute again and code outside of the listener functions will be re-executed because Composer once again regards it as a new scene.

Going to scenes

Once you create scene files, you need a method to access them. In Composer, this is accomplished via composer.gotoScene(). It requires a sceneName parameter which corresponds to the name of the Lua file, minus the .lua extension. For example, if you have a scene file named gamecredits.lua, access that scene with:

In addition, an optional table of parameters controls how the scene transitions on screen:

This tells the scene to transition in with a “fade” effect over the span of 500 milliseconds. For a list of valid transitions, see the composer.gotoScene() documentation.

If you want to pass data to a scene, composer.gotoScene() allows this as well — simply include a table of data named params in the options table…

…and then access this data from the event.params table in the target scene’s scene:create() or scene:show() function:


In addition to normal scenes, Composer allows you to have one overlay scene. This is a scene that gets loaded over the active scene (the parent scene) without affecting that parent scene. This makes it ideal for displaying things like a pause menu, an inventory display, or similar.

At the core, an overlay scene is constructed just like any other Composer scene, and it receives the same core events outlined above. However, there are some differences to be aware of.

Modal interaction

Because an overlay scene might not cover the entire screen, users may potentially interact with the parent scene underneath. To prevent this, set the isModal parameter to true in the options table of composer.showOverlay(). This prevents touch/tap events from passing through the overlay scene to the parent scene.

To dismiss (hide) the overlay, call composer.hideOverlay(). For example:

Parent scene access

An overlay scene can access the parent’s scene object via event.parent. This allows you to access functions/methods in the parent scene and communicate with the parent when the overlay scene is shown or hidden. For example:

Final notes

The Composer API is our new scene manager because it is built upon a more stable, future-proof base and it offers a simplified collection of functions and events. This allows us to expand and improve the library moving forward, providing Corona developers with a solid solution for scene management.

Share on Facebook0Share on Google+8Tweet about this on TwitterShare on LinkedIn2
Rob Miracle

Rob Miracle creates mobile apps for his own enjoyment and the amusement of others. He serves the Corona Community in the forums, on the blog, and at local events.

This entry has 73 replies

  1. Stephen says:

    Looks good. Cleaner to use than Storyboard, though I don’t see much functional difference from the old ways. Can you give a hint what future “better and more interesting things” Composer will enable?

    • Rob Miracle says:

      I’m not privy to any specific plans at this time, and if I were to speculate or postulate any thing, someone would try to hold us to a promise.

      • Joe says:

        What kind of possible feature? I don’t see much difference either. Please give me some clues. Thanks.

  2. I could be missing something, but where do we download the new release? Is this only for paid users with access to daily builds?

    • Rob Miracle says:

      Until we release a new public build, this will be for Pro and Enterprise subscribers only through daily builds.

  3. Matt says:

    Stephen, I’m guessing internal code improvements is a key driver.

    Rob, any reason “will” and “did” are used instead of “began” and “ended”?

    • Rob Miracle says:

      I can only speculate on why. Began and Ended have some semantic differences that could be confused with “did my scene begin or end” and “did my scene show or hide”. Will and did are clearer and are a bit of a throwback to the old events that we removed “willEnterScene” and “didExitScene”.

  4. Peter Dwyer says:

    Good work but, surely this section is wrong

    “Because an overlay scene may not cover the entire screen, users may potentially interact with the parent scene underneath. To prevent this, set the isModal parameter to true in the options table of composer.gotoScene(). This prevents touch/tap events from passing through the overlay scene to the parent scene.”

    surely you pass the isModal parameter to the composer.showOverlay call otherwise what you describe here will actually just load a new scene instead of an overlay onto the existing scene.

    • Rob Miracle says:

      If you have played Candy Crush Saga (I’m playing it at the moment, so it’s fresh in my mind), when you start a level, it shows a scene, then it pops up a small dialog in the middle. You can of course interact with that dialog which does not cover the whole screen or you can interact with objects in the underlying parent scene.

      Many apps would want this feature. However, some apps will want you to only interact with the overlay until it’s dismissed. This is it’s Modal model. If you want the modal behavior, you set the flag. If you want to interact with both, don’t set it.

      If your overlay is full screen, there isn’t much of a need to set the isModal flag since they can’t interact with the underlying area. The other reason you would want an overlay over just going to a scene is your app may still have timers, transitions, physics interactions going on while the overlay is shown. If you goto a new scene, because of the risk of it being removed, you have to stop all of that first.

      • Peter Dwyer says:

        Um hu?

        I’m not saying you shouldn’t have ismodal I’m saying your description is wrong as it’s telling people to call gotoScene, which transitions to a new scene and DOES NOT launch an overlay!

        • Rob Miracle says:

          got it!

  5. RichieLoco says:

    Looks like a migration from storyboard to composer shouldn’t be too messy. Wouldn’t mind knowing what the actual functional improvements are to this new API though, as I can’t really see any…


  6. Supertapp says:

    It would be really nice to see you implementing some form of the swipe-back type navigation that iOS7 now supports, where the whole scene moves with the touch rather than just looking for a change in movement and calling a scene change. As a storyboard devotee I’m in agreement with the above comments, this doesn’t look that much different.

  7. Lerg says:

    I like the new API, but I feel like you could just keep it named storyboard. Storyboard 2.0 or something. And I think something like “scenery”, “paysage”, “decor” or “stageset” could be a more logical name.
    Anyway, good job!

    Regarding composer.getScene(‘previous’) – does it keep track of all previous scenes? Can I use it to go back to the very beginning?

    Heh, you added setVariable() and getVariable(), a bit clumsy to use it instead of just composer.myVar, which most users do. But still it’s good to have it!

    • Rob Miracle says:

      Right now we don’t keep a stack of scenes. So getScene(“previous”) would just toggle between two scenes. I know a lot of people would like a full history/stack system. We gave it a new name because it minimizes the impact on existing projects.

  8. brocoli says:

    If the base code and interface are changing, why not allow stacked overlays, and multiple overlays per scene?

    These may sound not very useful at first, but consider the following cases:

    1) You want to pop up a confirmation screen on top of an overlay. If you try to do this the obvious way (with a modal showOverlay() on top of the overlay scene) what will happen is that the original overlay will disappear.

    2) You have an overlay scene, and you want to transition to another overlay scene. This means that the parent scene will have two overlays during the transition.

    It’s easy to picture situations where these cases arise.

    Finally, I can’t see much reason for the limitation to one single overlay. The overlay scenes themselves should create a natural stack structure, and if multiple overlays in a scene are allowed, a natural tree structure should arise instead.

  9. Rob Miracle says:

    Several people asked basically the same question “what new features”. As I said at the top in my first reply, I don’t want to speculate and have you read that as a promise. As of now, I’m not aware of any enhancements, but I’m also not in engineering conversations about what direction the future holds. I know there were numerous bugs that were fixed and we addressed clearing up the interface (a frequently complained about issue).

    But since a couple of you have mentioned a stack based system and multiple overlays, it will be more practical to consider those now than it was with the old code base. Are there plans for these now? Not that I’m aware of. Would they be cool? You bet.

  10. AndyCWatson says:

    Sounds good and not too different to storyboard to work with. I guess that we can pass persistent variables between scenes similarly; whereas before we ran with “”, do we now just call “”, as they’ll all share that common object.

  11. When you delivered Storyboard, you announced it as the perfect API, now you trash it and announce a replacement…

    Sprites, Graphics, Storyboard… Since I work with Corona I encountered many changes impacting compatibility on, most of the time for us, commercial products. I has a cost for us.

    While like the idea to see a product evolve, you have to keep in mind that Corona SDK is a mature product, and you’re targeting not only independent small game developers but professional companies, with customers and commercial/legal responsibilities on the delivered products (my case…).

    • David says:

      David, thanks for the feedback. Just a couple of points:
      – I don’t think we really trashed Storyboard. We are just saying that we now think Composer is better
      – We completely understand that change can sometimes be disruptive. But unfortunately we all live in that world. You know as well as us that Apple and Google often change/add/deprecate things to their platforms and we have to deal with that or fall behind. In the same vein (and at a smaller scale 🙂 we also have to make sure we keep up with the times and move forward.

      The good news here is that if you love Storyboard and want to keep on using it, you will be able to do so forever. It will be in the core for a while and is also available as a separate library you will always be able to build in.

      • Thanks David for the reply. I understand, but it’s not a reason to accept everything without complaining 🙂

        And regarding “Apple and Google often change/add/deprecate things to their platforms”, yes, and it’s hard to face sometime, so we should try to not to to others what we don’t like to suffer from.

        Great to know that Storyboard will be supported for a while.

  12. Andreas says:


    this is great, I wrote my own lightweight scene handler about 2 years ago because Storyboard was a bit unstable then, and I never switched back because Storyboard seemed just a bit overcomplicated.

    But Composer looks good, will use it when I need to handle scenes the next time.


    I see that for the Overlay feature the following Transition Effects are supported:

    “fromRight” — over current scene
    “fromLeft” — over current scene
    “fromTop” — over current scene
    “fromBottom” — over current scene

    But how to remove an Overlay the same way that it appeared?

    Imagine a kind of settings page that I slide over the actual scene “fromLeft”.
    After I did the settings I want to remove it the same way again, so I would need “toLeft” (the Overlay disappears again on the left side, the actual scene below is revealed.

    So I guess the following Transition Effects would be needed to make this happen:

    “toRight” — reveals current scene
    “toLeft” — reveals current scene
    “toTop” — reveals current scene
    “toBottom” — reveals current scene

    Now I remember, this was one of the reasons why I wrote my own scene manager, because I needed Overlays that behaved like this a while back…


    • Kerem says:

      Andreas, this is a very logical suggestion. I too would like my overlays to behave in this manner. Thanks!

    • Rob Miracle says:

      If you do a “fromRight” to transition on, do a “fromLeft” to transition off. Even if an overlay only covers part of the screen, if it only moved on screen by 200 px, it will move off the screen by 200 px. So having something slide up from the bottom works great. I realize that “fromTop” doesn’t sound right but it works.

      • Andreas says:

        Ah, great, good to know – maybe you can put this into the Transition Effects documentation.

        Thanks & best,

  13. Lerg says:

    By the way, here are a few helper functions I added to storyboard some time ago:

    storyboard.goBack() – goes to the previous scene with the same params it was called.
    storyboard.getCurrentScene() – just a shortcut

    • Renato says:

      Hi Lerg.

      Since you are already capturing the gotoScene, you can easy add the functionality that you asked before (about tracking all previous scenes) using a stack. I just did that here to manage the “back button” between scenes. If you need help, just reach me out.

  14. Renato says:

    I write here to be one more asking why do I need a new storyboard while there are so many other new features and bugs that are more important than that?

    A new storyboard is not even a request registered in the Corona Feedback system ( that supposedly would manage all new features requests. On the other side, we have several new features request with more than 1 year that are still there, including the super important Text Widget (from 22 Jan 13 and ranked 2nd) and several other functionalities for monetization and retention.

    This is not attack Corona, a tool and a team that I like a lot. But, the effort prioritization that is being showed just appear to be focused on the wrong direction.

    • Kerem says:

      Well said.

      No need to look any further. The forum and open bug reporting system has all the insight needed :

      While we have been reduced to literally beg for fixes to real problems we were given

      Graphics 2.0
      Corona Editor
      Corona Code Exchange Upgrade

      Thank you very much! I am sure all of the above are beneficial but none of them rate higher than the existing bugs and/or the bugs these new features keep adding to the growing list.

      Makes no sense at all. Corona Labs leadership, please establish a no change window of 3 to 6 months and just keep fixing bugs. Enough already.

      • Richard says:

        Looks like potential for yet more bugs ! I agree totally with Kerem, please can you put some focus on sorting the current issues rather than bringing in new stuff.

  15. Renato says:

    Great addition Kerem.

    Corona Editor is also a great example of something that we didn’t need. And the problem is not only the effort to develop the tool, but now they have to maintain it, so it is more effort being deflected from more important tasks.

    PS: That Corona Bug System is not reliable at all. I have several bugs still open that are not there.

    • Kerem says:

      “Corona Bug System is not reliable at all.”

      Ah the irony…

      • David says:

        Hey guys – thanks to you as well for your feedback.

        I have a couple of points to say about this, of course with the best intentions and in the spirit of open discussion:

        1) While you may think feature X is more important than feature Y (for any combination of X and Y), there are actually lots of opinions on that across the community. We have to look across all those opinions and balance that out and try to make the best decisions. Inevitably, someone will find that any given decision was not to their liking. But others do. As an example, I can assure you that many people do like Corona Editor and have used it to great effect – but I also understand if you couldn’t care less.

        2) As for bugs, well, there will always be bugs 🙂 Not much we can do about that, and it applies to all software and platforms. Just like we do with features, we prioritize bug fixing and do our best. While some of your bugs may still be waiting, there are many others that have been addressed and that were important for others.

        In any case, thanks again for the feedback. I really mean that. It keeps us honest and makes sure that we are paying attention.


        • Richard says:

          Feature X may be better than Feature Y for one person or the other way round for another person.
          Thats irrelevant really.

          Feature A,B,C,D,E that we already have and are full of bugs are more important to everybody.

          As for there always being bugs, yes there will and as a professional software developer with 25 years experience, I appreciate that fully. However, normally, you would focus more on removing bugs with existing stuff more than adding new features once in a while.

        • Joe says:

          We are not talking about which bugs are more important than others.

          However, Corona should allocate more resources on bug fixing & make some plan (a special project for concentrating on bug fixing).

          A lot of features recently added (such as Corona Cards, editor, composer) are not really useful for the developers to enhance existing apps. Sometimes pushing an app to the extreme will make the most of the money for our developers, not by quantity or speed.

          There are many bugs that should be heeded immediately but they have been there for months. If I am working inside Corona, I feel very painful to see those bugs sitting there. I don’t understand why you could keep them for so long with an ease of mind.

      • JONL says:

        I stopped using Corona two years ago due to bugs and a lack of support for native features.
        Since then I have concentrated on developing natively in objC and the new Sptite Kit API which even in its infancy knocks is very impressive. I understand Corona fits a demand for an easy to use development tool aimed at designers, but I definitely recommend you try out sprite Kit in ios

        Just my 2cents

  16. Kerem says:


    Thank you very much for your comments here. Most appreciated. As you say, its all in the spirit of open dialogue and with the best of intentions.

    Please don’t get me wrong. I am supportive of all innovation and progress. I realize that as a business you must try and remain competitive in an ever-evolving marketplace to keep attracting paying customers and investors. I also realize how it is a tough balancing act between features vs. maintenance.

    Bugs will always exist as you say. No doubt about that and indeed many bugs are being fixed on a regular basis as evidenced in the Daily Build logs. The question is whether we are gaining or losing ground in this challenge against bugs while a lot of Corona Labs resources are allocated in new features discussed above. As I look at some of the bugs that affect my area of focus, namely Business Apps, I can’t help but feel the challenge is already lost.

    Today there are numerous bugs that are open, affecting the widgets, native objects and other UI elements. Some of these bugs are more than six months old with many news ones added post G2 release. All these are making it very hard for us to deliver consistent results with little loss of time due to SDK problems. This is not a speculative post but rather one based on facts. I can present number of bugs and aging data if required but then again I shouldn’t have to as you have complete access to the bug reporting system and can see for yourself.

    We are fast approaching the one year anniversary of the release of Widgets 2.0 which is a key building block for Business Apps. I have made repeated attempts at getting a response from Corona Labs leadership for a simple question “How much longer will we have to wait for fixes to the remaining bugs in this key framework?”. You can see this question and perhaps respond at :

    Thank you very much for attention and kind support. I will remain hopeful that these issues can be addressed on a more timely basis than they have been in the past.


  17. The current installation for this release is corrupt for windows

  18. Rob Miracle says:

    Which build #?

  19. Craig says:

    Hi there,

    Seems good so far.. I like the ability to reload scenes (works well).

    However I am wondering if show() is working correctly? It appears that display objects added in show() are not correctly disposed of, I know display objects should be added in Create, but there are times when show() is needed (more dynamic content). If I add text in show() and then transition to another scene and back again it layers up. Is this the way it is supposed to work? Should I manually remove these objects in hide()?


    • Rob Miracle says:

      If you add them to the sceneGroup (self.view) then they will be managed correctly. If you don’t do a:


      you will see this behavior.

      • Craig says:

        I am and it still occurs.

        The object, in this case text, is getting put into the sceneGroup (self.view) and transitions off the screen perfectly (so it must be in the group) – however when I transition back the text gets bolder and bolder as it layers up. Should I submit a bug?

        I have also tried it with a tableview and deleted rows – the row deletes as it should but there is kind of a ghost left behind that can be seen when the transitions off the screen (the deleted row lingers behind the tableview widget).



  20. JCH says:

    I’ve moved to composer and it seems better integrated with graphics 2.0 than storyBoard. Naming it composer is a really good idea, there’s no confusion when you read code (it is the case with different versions of widget for instance).

    But… When calling “showOverlay” I don’t understand why the “show” listener attached to the “parent” is invoked. Why don’t just invoke listener for the parent when parent shows ?

    • Rob Miracle says:

      You should not be getting a show event in the parent. What version of Corona SDK are you using? This should have been fixed in 2148 or so.


      • JCH says:

        Correct, the problem has been fixed, thank you. I was using DB 2152 but initial code was written with 2140 when I “discovered” composer in the doc.

  21. Dennis says:

    There really isn’t a whole lot semantically different here, but it seems one of the main changes to the API is the reduction of 8 events down to 4. Ignoring the overlay events (which could just be deprecated and then eventually removed from the current API, but whatever), I don’t understand how removing two of the events is simplifying the API.

    Correct me if I’m wrong, but it seems the lifecycle of a scene hasn’t changed at all. This means the change that is supposedly a simplification is actually somewhat obnoxious.

    Previously, if you wanted to do something when the scene starts, you’d put it into “enterScene” and be done.

    Now, if you use the new “show”, it will be called twice unless you put it in an if statement that checks the phase. I’m not sure about other people, but we rarely use “willEnterScene”, so this is going to be 2 extra lines of code over and over.

    And for those who say “well, it’s just two extra lines of code, it’s not that bad”, I would say…compare the use case where you want to do the exact same thing on both “willEnterScene” and “enterScene” (or “exitScene” and “didExitScene”). If this doesn’t exist or is super rare, it means that the new “show” will have a guaranteed switch in it all the time, whereas in the previous API you could just opt out of using one of the events without writing anything extra.

    To me, simpler is an API that lets me hook into what I want and to not write code that’s essentially busy work. This is not an improvement in that direction.

    • JCH says:

      +1 for Dennis point of vue. People developing Corona should have in mind “how to make it simpler for developers to migrate”.

      • Dennis says:

        It’s not so much migration as…what makes an API good. It seems that sometimes changes are made ostensibly to make things better, but in reality just to make things different. Making more boilerplate necessary is not typically better.

        Combine this with Nicholas Golden’s comment below (about show being called twice) and you have something that’s vaguely confusing to people who don’t read the documentation closely and completely unnecessary because there’s not much reason you’d want to combine enterScene and willEnterScene.

        Having more event hooks is not complex when each of those correlates directly to something with semantic meaning (in this case an event in the lifecycle of a scene).

        • develephant says:

          “Having more event hooks is not complex when each of those correlates directly to something with semantic meaning (in this case an event in the lifecycle of a scene).”

          Well said, couldn’t agree more.

  22. What’s up with scene:show entering twice? I put print statements on the different scene changes and always, I get twice for scene:show. First I thought I had extra print statements, but no it’s always called twice unless I did some if statement to check the phase. That’s weird!

    My overall view of it, nice but not sure If I’m on board with it. Maybe I’ll just stick to storyboard for now, until people get this figured out.

    • Craig says:

      As far as I can tell it is getting fired once for each phase – will and did – put your code inside the if statements and you should only get it once depending on where it is…

    • Rob Miracle says:

      show and hide get called twice. Once is the old willEnterScene event and the other is the enterScene event. And on the hide side, it is the old exitScene and didExitScene. You have to monitor for the different phases in the event.phase attribute. You will get a “will” and a “did” phase for each of them to indicate if the scene is on screen yet or not

  23. JB says:

    If it ain’t broke, don’t fix it

    Without a lot of extra features
    this seems like a waste of time
    i have 30+ apps and it will be a total waste of time to update them

  24. Jeff Leigh says:

    I agree with Dennis – I think the separate functions willEnterScene and didEnterScene was better (code in the functions was more to the point and compartmentalized). Combining into one function and handling phases with if’s seems like a step backward to me.

  25. Martin says:

    Why you doing this always? First i used director then switch to scenemanager then to storyboard and now to Composer come on… really… you still breaking my code;)

    • Rob Miracle says:

      If you’re happy with Storyboard you can continue to use it. Director is a 3rd party solution and you are dependent on it’s producer for support. I’m not all that familiar with scenemanager.


      • Martin says:

        But why then we should switch to Composer? When storyboard etc can be use. Stop reinventing the wheel.

        What should storyboard source code help when its not anymore official supported ? Should we as a community then fix stuff I really dont get it;)

        • Rob Miracle says:

          Martin, let me try and explain this. Storyboard from the users perspective is a really good thing. Many of you are using it to great success. But like other things, it had bugs reported against it and people request new features be added and people complained about the the complexity. When looking at the code we have to work with and trying to address outstanding bugs and feature requests, we realized that we needed to refactor the code to make the required changes and meet the requirements. This refactoring required breaking changes. Instead of dropping Storyboard 2.0 on you and forcing you to have to adapt, we chose to release it as a new library and let you change when you’re ready.

          Since we open sourced the Storyboard 1.0 code, you just have to drop storyboard.lua in your main folder to keep using after we finally remove the library to keep going. But any fixes and new features will happen in Composer. At some point it’s in your best long term interest to start using Composer. But since the current Storyboard library is reasonably stable, the pressure to migrate isn’t as great.

          This to me seems to be the best of worth worlds.

  26. Dave Haynes says:

    I don’t really have any problems with bugs with the parts of the Corona SDK that I use. I don’t use any of the widgets in anything I’m doing currently, and that seems to be where most of the complaints are.

    That said, as a professional developer, I am a bit perturbed with the way these new APIs are introduced and the old ones phased out so quickly with Corona.

    My development experience is in a mostly Microsoft world, and with .NET, when they release new APIs, there’s a new version of .NET, but you are still able to target the older version if you want.

    I’m a full-time .net developer during the day, and only get to work on my corona projects at night and on the weekends, so here’s my experience with Corona.
    1. Start using some third party scene manager as recommended by the Corona staff and community.
    2. Very soon after that, switch to the new hotness — the Storyboard.
    3. Get about 1/4 way finished with my game, and Graphics 2.0 is released.
    4. Spend a little bit of time going through the whole game, modifying everything to use Graphics 2.0.
    5. Get about 1/2 way finished with my game, and now the Composer API is released.
    6. Now I’ll have to spend some time going through and modifying everything to use the Composer API…

    It’s just slowing down the development of the game trying to keep up with the breaking API changes. I kinda wish you’d follow a more Microsoft-like model and introduce new API features that completely replace old ones (like Graphics 2.0 and the Composer API) in an entirely new major version of Corona. So maybe if we were using Corona SDK 1.0, it would have Storyboard and Graphics 1.0. Corona SDK 2.0 would have Graphics 2.0 and the Composer API and be better supported by Corona Editor.

    Obviously, this is just a comment, and it would need a lot more time to think it through, but these are just some ideas I had. I still really love Corona and appreciate the hard work that’s gone into making it easy.

    One other thing, though, I don’t find the new Composer API to be that straightforward to use. It seemed better when there were completely separate events for “will” and “did” — having the if condition to check for phases seems a bit weird.

  27. Lerg says:

    Ugh, people stop complaining that you have to rewrite everything to use composer now. Storyboard is not a goner, even more – now that it’s open sourced you can fix ALL the bugs you are having with it. Lua code for storyboard is not a rocket science, it’s pretty clean (much much much cleaner than Director [not as clean as my Director Slim, but I digress]).

    You can even build your own perfect scene manager based on that code.

    And don’t compare Graphics 2.0 transition with storyboard. Graphics is the core of corona, which was hugely updated, while storyboard is just an accompanying library.

    It is only when widgets 2.0 came out you were forced to update. Even G2.0 has compatibility mode!
    And I am sure it didn’t take much time to create it, so if they spent this time fixing bugs on storyboard – nothing would be really different.

    So, seriously, stop it, folks. You’ve got a new toy to play with, be grateful.

    • Renato says:

      Lerg, I think users have their right to complain, after all, they are paying for a expensive service that should make their lives easier and not otherwise.

      I think that the list of complain that users are registering here just show how the Corona users are engaged with the platform and really like to use it, otherwise, they would just ignore everything. Corona should be grateful to have these users and receive their input.

      My opinion, and appears to be the same of the big majority, it is not simply against a new API, but the effort that was spent with a new API while we already had something that was working fine while other things with Corona are still really stone age. Have you tried to create a business app using the textFields/textBox with Corona? It is horrible (and if you are Windows users, it is the hell) and the users are requesting a text widget for more than 1 year. So when we see Corona releasing Corona Editor, Composer, … it is more than justified to us to be frustrated.

  28. David says:

    Will the composer correctly remove objects within a display group if you insert that display group into the sceneGroup? Or do you have to manually remove them yourself?

    What I’m trying to figure out is the best way to, let’s say, have a bunch of enemies on the screen and be able to easily remove them from memory.


    • Rob Miracle says:

      It should remove them correctly.


  29. I don’t intend to complain (much), as I do appreciate any new engineering effort going into storyboard/composer. And as I have a Storyboard-based project nearing completion, I’ll probably be going through the conversion before its release, to save any upgrade pain later. But I will add a +1 for those like Dennis above who wonder about the wisdom of “simplifying” the event model. Fewer discrete events, but with more phases = overall no reduction. So, depending on one’s usage, it may be the case that the event model has been complicated rather than simplified. As previously commented by others, in the old storyboard you’d only implement and listen for events of interest. With Composer, you’re essentially always required to “implement” both will/did by at least checking phase, even if don’t actually use both phases, otherwise you’d get “duplicate” events. So we’ve got fewer events, but more code to implement them properly. I do prefer the *names* of the events better in Storyboard – just not sure the event consolidation will be advantageous. $0.02

  30. Radim says:

    I’m having issues with Composer. I have 1st scene I call Menu and then 2nd scene Levels where I select a level I want to play. I use print command to check in Output window what is happening and this is my problem

    Menu:show will
    Menu:show did
    Menu:hide will
    Levels: create
    Levels: hide will
    Levels: hide did
    Levels: show will
    Levels: show did
    Levels: show will
    Levels: show did

    Levels enter first “Hide” and then “Show” and then “Show” again. If I run Levels straight from Main scene then the output is correct:

    Levels: create
    Levels: show will
    Levels: show did

    this behaviour is causing a lot of issues with Runtine listeners and functions. Problem is that if scene enters first to “hide” where I’m removing Runtime listener instead of entering “show” where I’m adding Runtime listener my functions don’t work.

    I’m using Composer scenetemplate with just a very little code so I have no idea why it does not work. This is link to my Dropbox–wfjFa/Composer

    • Rob Miracle says:

      Can I ask you to post this in the forums please? It will be easier to help you there.


  31. Joe C says:

    I was just getting the hang of Storyboard…..And now its going to be replaced…. *pulls out hair* 🙁

  32. Joe C says:

    Also wanted to add, I replaced all the storyboard commands in my app with the composer commands and now I get an error where as before everything worked…. 🙁

  33. Nick says:

    For those who are still using storyboard, I went and took a look at the lua file. If you are really bent out of shape about composer, you could just go and study the open sourced storyboard. Everything you need is in there, and you can even just slim it down. It’s all lua so if you really want something specific you could add it in yourself. Hell, you could make a “director slim” type of thing that lerg did 🙂

    I am using composer and find lots of quirks with it but got around it. For example, you toss display objects on create scene, but then reload then it only goes to scene show. If those objects have physics and you have collisions etc etc, then you need to instantiate the physics on the scene show did (otherwise bla bla physics nil value bla bla can’t find this bla bla bla bla type thing). Same goes for event listeners, runtimes etc. Once I got around that portion, composer was fine.

    I highly suggest if you are going to learn how to use it, put print statements for every scene and figure out what’s going on ” like menu – scene show “did” , level1 – scene create etc. For example, if you put a reload.lua and want to reload level1, you’ll see on first time you get scene create, then you get scene show from then on. Once you know that, then you can code accordingly.

    You’ll start to see patterns in how it works. You just have to put the time in. It’s quirky, things getting called twice is odd yes but once you figure out how to manage it all it’s fine.

  34. Robert Craig says:

    Started using composer as I am brand new to corona sdk and also LUA. Have to say I am loving it 🙂 Only wish the SDK docs went a little further with examples. Maybe a full app for composer for instance. Showing someone like me where exactly things go.

    I am relying heavily on my understanding of OOP to work things out. But that aside great API guys!

    Almost got battleships coded on it after two days 🙂

    Thanks for providing a tool that allows multi platform app building. Would love to see the API extended to use Android and IOS native UI components 🙂

    Cheers ☺

  35. charles says:

    since.. corona doesnt have storyboard… i cant make a game anymore……….
    dont understand about composer… i put a same code… but it doesnt work… helppp

    • Rob Miracle says:

      First, you should read up on Composer and give it a chance. It’s Storyboard’s newer better brother. It’s not a direct replacement, we did make breaking changes that have to be adapted for. But just to keep old code working, you can go to and look for the legacy storyboard project. It will have a “storyboard.lua” file. You simply download that and drop it into the folder with your main.lua and you’re all set.