Word Clock – Part 4

Creating a Corona Scene file

In this part we will create the clock.lua file and fill it with composer scene code.

But first let’s have a look at how a composer scene does look like and what it is good for.

Scene Management

Most of the apps does have several scenes, i.e. a main screen, a game level, a game over screen.

All these parts can be a composer scene.

The composer scene is an easy „tool“ to accomplish going from scene to another.

You may ask: why do I need a „tool“ for going from one scene to another. This is not a complicated task.

I fact you have to do a lot to change a scene:

  • all graphics of a scene have to be removed
  • but the graphics may not completely removed from memory, because you may use them again
  • the music should change
  • scores must be saved
  • maybe the game progress must be saved
  • maybe the scene should be changed with ab transition effect like fade out, fade in etc.

The composer library helps you to do the right things at the right moment when changing a scene.

The Files of a Corona SDK Project

A composer scene is always structured in the same way: first some initialization code and after that four scene events will be handled.

When using Corona’s composer library, a scene can handle four different events. These events are:

  1. Create
  2. Show
  3. Hide
  4. Destroy

Let’s examine these events.

The Create Event

The create event is used to create a game level (if you are writing a game), load graphic and sounds etc. But also to create the main screen of your app, or a settings scene etc.

The create event should do all the work you need to do to load a level once. This data is often static data, that do not change over the time of the game.

Static data in this case could be the level data. Maybe the position of a house in your game level does never change in the progress of the game. Then this would be static data.

Or the image of that house may not change. So we would load that image here too.

Of the button graphics of a settings screen can be loaded here.

Or the background music.

But for example the player’s high score does change in the progress of the game. We should not load the saved player’s high score in the create event.

Why not?

The create event is only called once: when the scenes is loaded the very first time.

After that the create event is not called again, unless the whole scene gets completely removed from memory. However we try to avoid removing a scene, to save memory and resources.

But do we load the scene more than once?

Let’s say you player has died and the game level should change back to the main screen scene. The means we need to call a composer.gotoScene(„mainscreen“) function.

Maybe the user wants to play again that level. He presses Play and you use the composer.gotoScene(„levelXY“) to load that level again.

In this case the create event of that scene is not called again! This is very important to know. Again: the create event is only called when a scene is loaded the very first time.

The Show Event

The show event would be a better place to load a player’s highscore because the show event gets called evertime a gotoScene function is called.

Furthermore the show event is fired two times: once before anything is displayed on the screen. And once after all the graphics are displayed on the screen.

So when a game level starts, loading a player’s high score would make sense before anything is displayed on screen. Otherwise the high score gets displayed on the screen with an example value of „000000“, and a short time after that the score updates to the correct value. Well, it works but it is not elegant.

The Hide Event

Only one scene can be displayed at a time. So when when you go to a different scene the current scene has to be hidden.

(This is the case if you have more than one scene. The word clock app does only have one scene.)

So now the hide event is fired. Again this event is fired two times: before the scene will be hidden and after the content of the scene has been hidden.

The Destroy Event

The destroy event is only called when the device has a low memory warning and it needs to free some memory. Or when you manually destroy the whole scene.

Here you can „undo“ things you load in the create event. For example unload some audios.

A Composer Scene Template

Here is a minimal template for a composer scene that handles all four possible scene events.

local composer = require( "composer" )
local scene = composer.newScene()
 
function scene:create( event )
end
 
function scene:show( event )
	if ( event.phase == "will" ) then 
    elseif ( event.phase == "did" ) then 
    end
end
 
 function scene:hide( event )
	if ( event.phase == "will" ) then 
	elseif ( event.phase == "did" ) then 
	end
 end
 
 function scene:destroy( event )
 end
 
 scene:addEventListener( "create", scene )
 scene:addEventListener( "show", scene )
 scene:addEventListener( "hide", scene )
 scene:addEventListener( "destroy", scene )
 
 return scene

In this template you can see how a scene object is created with composer.newScene().

After that four functions are created that should be called when the appropriate event fires.

At the end of the template the scene:addEventListener() functions connects the four functions with their event.

For example:

scene:addEventListener( "create", scene )

This line of code says: if the create event occurs on the scene object, then execute the function that does have the same name as the event – in the case create().

The Event Parameter

Every scene event function does get passed an event parameter like this:

function scene:create( event )

This event parameter does contain some informations about the current event.

For example in the scene:show() and scene:hide() function we can use the phase variable to check, if this is the first (before) or the second (after) time the function is called.

The value of phase is a string value and contains “will” on the first call and “did” on the second call.

Create the clock.lua file

Now let’s create the missing clock.lua file so that our project does not throw an error message anymore.

In Sublime open our word clock project.

Then create a new empty file with Cmd+N or use the menu File>New File to create a new empty file.

Now copy the scene template from above and paste it into the new blank file.

Then save the file into the main root folder of our project. The main root folder is the same folder where you find the main.lua file. Use Cmd+S or from the menu File>Save and call it clock.lua.

The editor and the folder structure should look like the following screenshot.

The new clock.lua file

The new clock.lua file

When you compile the project now, it should not throw any errors. The simulator should display a black window.

Conclusion

In this part you learned how a composer scene is structured and you learned about the four events a composer scene does fire.

We created a first empty scene and saved it to a new clock.lua file.

In the next part 5 we will start creating a first module that will be the base for our word clock module.