Organizing display objects in layers in Corona SDK

Working with display objects and display groups in Corona SDK is fairly straightforward. Every Corona developer probably knows the basics of this and how you can organize your display objects in a hierarchy of display groups. All this is also pretty well documented by Corona Labs right here, so I'm not gonna go into details about any of this. Instead I'll show you how I've created a simple helper class called DisplayManager which I find very useful when it comes to leverage the concept of layers and to keep track of all display objects to avoid creating memory leaks by not cleaning up the display objects properly.

What I want the DisplayManager class to help me with is basically a few things, that otherwise requires quite a lot of attention when coding:

• Leverage the concept of visual layers, and encapsulate functionality concerning layers in an object-oriented way, making it easy to extend when needed.
• Make sure that all display objects are cleaned up as they should when necessary. This is very easy to get wrong if you don't have your display groups and objects neatly organized, often leading to memory leaks and very tedious bug hunts.
• Clip content to the bounds of the specified display size using a container. DisplayManager handles this for you.
• Eliminate the need to keep separate references to each display group in your code. Many times you're not interested in changing any of the objects in a particular group or layer, for example when having a background layer with static graphics. The only  need to keep a reference to a group like this is often to be able to clean it up when not needed anymore.
• Be able to have easy access to the same layers from several modules and/or scenes. With DisplayManager you can just inject the same single instance anywhere you need it. No need for global variables or passing lots of display groups as parameters between functions.
• Make sure that the class works well together with the composer module.

The DisplayManager class presented below contains only the most important functions to meet the criteria above. You start by creating a new instance with a number of predefined layers. After that you can insert display objects and display groups into any of these layers. When a layer is not needed anymore, just clean it up which will remove all objects and groups within that layer. There's also a convenience function to clean up all layers at once.

It's also possible to get a reference to a layer (which is really only a display group) to be able to inspect or change it anyway you want. This is actually not very nice from an object-oriented point of view. It would be cleaner to encapsulate the additional functionality within the DisplayManager class, but for simplicity it's often easier and much quicker to just get the layer and do whatever you need to do.

You can also get a reference to the main display container, i.e. the container that holds all the layers together and handles the content clipping. This is especially useful when working with composer scenes. Just get the display container and insert it into the scene's view and everything should work right away. This is also shown in the example code below.

If you run the example from main.lua you should see an output similar to this:

Just for demonstration purposes, the example code does the following:

• Creates a scene using composer, to show how easy it is to integrate DisplayManager with a scene
• Creates a DisplayManager with three layers: background, circles and squares
• Adds some graphics to each layer. The objects are added one at a time to each layer, just to show that they'll end up in the correct visual order anyway.
• The circles are divided into separate display groups, where the blue layer is scaled and repositioned. Again, just to demonstrate that the DisplayManager doesn't restrict your from working with display groups anyway you normally would.
• One second after the scene is shown, the big green rect is added to the background layer.
• After another second, the circle layer is cleaned up.

The DisplayManager class is not rocket science in any way. It's actually a very simple implementation, but it has saved me from a lot of headache during the making of my two Corona games. I realized the need for a class like this when creating Dragonflies. It turned out really well for me, so when I started working on Ice Trap it was a no-brainer to include it in my project. Hopefully it can now also come to good use to some of you fellow Corona SDK game programmers out there.