Storyboard: Scene Purging vs. Removal

One of the most confusing aspects of Corona’s storyboard API is the purging and/or removal of scenes. What’s the difference between purging and removing? What does it mean to “purge” a scene anyway? Those are just a few of the many questions we receive often.

Today, I’m going to attempt to clear up the confusion by first giving you a high-level overview of what’s going on behind-the-scenes when purging and removal goes on, and also show you a few examples along the way.

Memory Consumption

When a Corona display object is created, it takes up both texture memory (graphics) as well as Lua memory (data, such as tables and variables). When modules are loaded, such as scene modules, it is simply a table that is stored in memory. It is often quicker to load things from memory, but having too many things in memory at once can also impede performance. Because of this constant balancing act, we decided it’s best for you to have full control of what should remain in memory, as well as when things should be unloaded/freed from memory—afterall, every app is unique in some way.

With that in mind, here’s a basic overview of what purging and removing is in regards to storyboard scenes:

Purging is removing only the display objects from the scene, to include the scene’s display group (thus freeing up texture memory). However, if the scene is represented by an external module, the module will still remain in memory, as well as any custom variables you attached to the scene object.

Removing a scene means removing everything (display objects, and Lua objects). The result is freed texture memory as well as Lua memory.

So why purge at all?

If there is a scene you can foresee the user potentially going back and forth to, but are in a scene that requires as much texture memory as possible, then it’s usually better to purge the other scene that will be soon reloaded (since the module remains in memory).

For example, let’s say you are creating an action arcade game. It uses lots of physics, and has tons of objects all moving at fast speeds—needless to say, the game scene requires as much texture memory as possible.

In the corner of the game screen is a pause button, that loads the “pausegame” scene whenever it is pressed. Since the user may be switching to this scene often, it might be a good idea to simply purge the scene (to regain as much texture memory as possible), but leave the “pausegame.lua” module in memory since the user will potentially keep coming back to the scene.

Functions for Purging

There are two storyboard functions that handle scene purging:

• storyboard.purgeScene()
• storyboard.purgeAll()

The first function takes a single argument, sceneName, that corresponds to the scene you want purged. If the scene-to-be-purged corresponds to an external module, it is the module name (minus the “.lua” extension).

Since scene purging will “destroy” the display objects that correspond to the scene, it is best to call this function once the scene is no longer being displayed on-screen. The event that corresponds to that best is “didExitScene“.

Here’s an example of a scene that purges itself when it has fully exited the screen:


-- scene1.lua
local storyboard = require "storyboard"
local scene = storyboard.newScene()

return scene


Now, let’s say you’re transitioning from a scene to menu.lua. You can get to menu.lua from several other scenes, so here’s an example of how to purge the previous scene, even if you do not know exactly where the user came from:


-- menu.lua
local storyboard = require "storyboard"
local scene = storyboard.newScene()

return scene


You can also use storyboard.purgeAll() instead to purge all scenes, except for the currently active scene. Whenever a scene is purged, a “destroyScene” event will be dispatched in case you need to do any last-minute actions, such as remove Runtime listeners you added in the scene, or anything else.

Functions for Removing

There are two storyboard functions that handle scene removal. When either of the two functions below are called, the scene will first be purged before being removed.

• storyboard.removeScene()
• storyboard.removeAll()

The first function takes a single argument, sceneName, that corresponds to the scene you want removed. If the scene-to-be-removed corresponds to an external module, it is the module name (minus the “.lua” extension).

Since each scene is purged before being completely removed, a “destroyScene” event will be dispatched on each scene that is removed.

Automatic Purging

On iOS, by default, storyboard will automatically purge the least-recently-used scene when the OS issues a “Low Memory Warning”. If you do not want this automatic behavior to occur, you can use the storyboard.disableAutoPurge property to control this behavior:


storyboard.disableAutoPurge = true


The default value is false, so if you explicitly set it to true, then you must be sure to purge scenes that you no longer need or your app’s texture memory consumption will continue to rise higher and higher as new scenes are loaded. If you are developing for Android, you’ll need to do this since the automatic purging does not occur on Android devices.

If you do not want to deal with manually purging scenes, but do not like the automatic scene purging behavior, then you can set storyboard.purgeOnSceneChange property to true, and all scenes will be purged every time you change scenes (except for the scene you are switching to).

For more information, see the storyboard.* API documentation.