Chapter 5 — Converting the Game to Composer

Physics Setup

Since this game will obviously still utilize the physics engine, there's no reason to defer that setup until later. Copy your physics setup commands from main_original.lua and paste them into the scene-accessible space of game.lua, immediately following initialization of the scene:

local composer = require( "composer" )

local scene = composer.newScene()

-- -----------------------------------------------------------------------------------
-- Code outside of the scene event functions below will only be executed ONCE unless
-- the scene is removed entirely (not recycled) via "composer.removeScene()"
-- -----------------------------------------------------------------------------------

local physics = require( "physics" )
physics.start()
physics.setGravity( 0, 0 )

Image Sheet

Next we'll need the image sheet configuration. Let's paste that just below the physics commands:

local physics = require( "physics" )
physics.start()
physics.setGravity( 0, 0 )

-- Configure image sheet
local sheetOptions =
{
    frames =
    {
        {   -- 1) asteroid 1
            x = 0,
            y = 0,
            width = 102,
            height = 85
        },
        {   -- 2) asteroid 2
            x = 0,
            y = 85,
            width = 90,
            height = 83
        },
        {   -- 3) asteroid 3
            x = 0,
            y = 168,
            width = 100,
            height = 97
        },
        {   -- 4) ship
            x = 0,
            y = 265,
            width = 98,
            height = 79
        },
        {   -- 5) laser
            x = 98,
            y = 265,
            width = 14,
            height = 40
        },
    }
}
local objectSheet = graphics.newImageSheet( "gameObjects.png", sheetOptions )

Initial Variables

Following the image sheet setup, paste in the following localized variables from main_original.lua:

local objectSheet = graphics.newImageSheet( "gameObjects.png", sheetOptions )

-- Initialize variables
local lives = 3
local score = 0
local died = false

local asteroidsTable = {}

local ship
local gameLoopTimer
local livesText
local scoreText

Display Groups

In our original version, we created three display groups for sorting and layering our game objects: backGroup, mainGroup and uiGroup. We are still going to use them, but a few small modifications will be necessary since we're using Composer.

In the last chapter, you learned how to insert scene objects into the scene's view group (sceneGroup). Now, an important concept to understand is that display groups can actually be inserted into other display groups! As such, we can maintain the three display groups from the original game and instill them into the scene's view group.

To facilitate this, we will defer the actual creation of our three groups until we create the scene. However, we still need to define the variables now using the forward declaration method that you learned about earlier. So, instead of associating each variable with a display.newGroup(), just leave them undefined for the moment:

local ship
local gameLoopTimer
local livesText
local scoreText

local backGroup
local mainGroup
local uiGroup

Game Functions

As we continue past this point in main_original.lua, we come to the local functions which power our game's core functionality. Basically, these can be copied over directly into your game.lua file, pasted directly below the variables we just defined.

First, copy over the updateText() function:

local backGroup
local mainGroup
local uiGroup


local function updateText()
    livesText.text = "Lives: " .. lives
    scoreText.text = "Score: " .. score
end

Follow this with the createAsteroid() function:

local function updateText()
    livesText.text = "Lives: " .. lives
    scoreText.text = "Score: " .. score
end


local function createAsteroid()

    local newAsteroid = display.newImageRect( mainGroup, objectSheet, 1, 102, 85 )
    table.insert( asteroidsTable, newAsteroid )
    physics.addBody( newAsteroid, "dynamic", { radius=40, bounce=0.8 } )
    newAsteroid.myName = "asteroid"

    local whereFrom = math.random( 3 )

    if ( whereFrom == 1 ) then
        -- From the left
        newAsteroid.x = -60
        newAsteroid.y = math.random( 500 )
        newAsteroid:setLinearVelocity( math.random( 40,120 ), math.random( 20,60 ) )
    elseif ( whereFrom == 2 ) then
        -- From the top
        newAsteroid.x = math.random( display.contentWidth )
        newAsteroid.y = -60
        newAsteroid:setLinearVelocity( math.random( -40,40 ), math.random( 40,120 ) )
    elseif ( whereFrom == 3 ) then
        -- From the right
        newAsteroid.x = display.contentWidth + 60
        newAsteroid.y = math.random( 500 )
        newAsteroid:setLinearVelocity( math.random( -120,-40 ), math.random( 20,60 ) )
    end

    newAsteroid:applyTorque( math.random( -6,6 ) )
end

The next function, fireLaser(), should follow:

    newAsteroid:applyTorque( math.random( -6,6 ) )
end


local function fireLaser()

    local newLaser = display.newImageRect( mainGroup, objectSheet, 5, 14, 40 )
    physics.addBody( newLaser, "dynamic", { isSensor=true } )
    newLaser.isBullet = true
    newLaser.myName = "laser"

    newLaser.x = ship.x
    newLaser.y = ship.y
    newLaser:toBack()

    transition.to( newLaser, { y=-40, time=500,
        onComplete = function() display.remove( newLaser ) end
    } )
end

ship:addEventListener( "tap", fireLaser )

ship:addEventListener( "tap", fireLaser )

ship:addEventListener( "touch", dragShip )

gameLoopTimer = timer.performWithDelay( 500, gameLoop, 0 )

Runtime:addEventListener( "collision", onCollision )

Essentially, the remainder of your scene-accessible space should be populated as follows:

local function dragShip( event )

    local ship = event.target
    local phase = event.phase

    if ( "began" == phase ) then
        -- Set touch focus on the ship
        display.currentStage:setFocus( ship )
        -- Store initial offset position
        ship.touchOffsetX = event.x - ship.x

    elseif ( "moved" == phase ) then
        -- Move the ship to the new touch position
        ship.x = event.x - ship.touchOffsetX

    elseif ( "ended" == phase or "cancelled" == phase ) then
        -- Release touch focus on the ship
        display.currentStage:setFocus( nil )
    end

    return true  -- Prevents touch propagation to underlying objects
end


local function gameLoop()

    -- Create new asteroid
    createAsteroid()

    -- Remove asteroids which have drifted off screen
    for i = #asteroidsTable, 1, -1 do
        local thisAsteroid = asteroidsTable[i]

        if ( thisAsteroid.x < -100 or
             thisAsteroid.x > display.contentWidth + 100 or
             thisAsteroid.y < -100 or
             thisAsteroid.y > display.contentHeight + 100 )
        then
            display.remove( thisAsteroid )
            table.remove( asteroidsTable, i )
        end
    end
end


local function restoreShip()

    ship.isBodyActive = false
    ship.x = display.contentCenterX
    ship.y = display.contentHeight - 100

    -- Fade in the ship
    transition.to( ship, { alpha=1, time=4000,
        onComplete = function()
            ship.isBodyActive = true
            died = false
        end
    } )
end


local function onCollision( event )

    if ( event.phase == "began" ) then

        local obj1 = event.object1
        local obj2 = event.object2

        if ( ( obj1.myName == "laser" and obj2.myName == "asteroid" ) or
             ( obj1.myName == "asteroid" and obj2.myName == "laser" ) )
        then
            -- Remove both the laser and asteroid
            display.remove( obj1 )
            display.remove( obj2 )

            for i = #asteroidsTable, 1, -1 do
                if ( asteroidsTable[i] == obj1 or asteroidsTable[i] == obj2 ) then
                    table.remove( asteroidsTable, i )
                    break
                end
            end

            -- Increase score
            score = score + 100
            scoreText.text = "Score: " .. score

        elseif ( ( obj1.myName == "ship" and obj2.myName == "asteroid" ) or
                 ( obj1.myName == "asteroid" and obj2.myName == "ship" ) )
        then
            if ( died == false ) then
                died = true

                -- Update lives
                lives = lives - 1
                livesText.text = "Lives: " .. lives

                if ( lives == 0 ) then
                    display.remove( ship )
                else
                    ship.alpha = 0
                    timer.performWithDelay( 1000, restoreShip )
                end
            end
        end
    end
end


-- -----------------------------------------------------------------------------------
-- Scene event functions
-- -----------------------------------------------------------------------------------

Great job! We now have all of the scene-accessible code copied over. In the next few sections, we'll illustrate how the Composer scene: functions tie our game together.

Transition Effects

While we didn't utilize one for the menu scene, the composer.gotoScene() command allows you to specify a transition effect such as fading in, sliding in from a screen edge, cross-fading from the previous scene, etc. Naturally, there is a time duration associated with the start and finish of scene transitions, and this is where scene phases come into play.

Scene Phases

An important factor to understand (in contrast to scene:create()) is that Composer calls the scene:show() function twice. Of course it's imperative to know when each of these calls occurs so that we can take the proper actions at the proper time. This distinction is provided via event.phase within scene:show(). Basically, scene:show() calls/phases work like this:

1. The first call occurs when the scene is ready to be shown, essentially after every command within scene:create() has been executed. In this case, event.phase is "will", effectively indicating that the scene "will show" and the transition effect is about to occur.

2. The second call occurs immediately after the scene has shown — basically, when the scene transition has completed. In this case, event.phase is "did", meaning the scene "did show" and the transition effect completed.

-- show()
function scene:show( event )

    local sceneGroup = self.view
    local phase = event.phase

    if ( phase == "will" ) then
        -- Code here runs when the scene is still off screen (but is about to come on screen)

    elseif ( phase == "did" ) then
        -- Code here runs when the scene is entirely on screen

    end
end

Now that you understand this concept, simply paste code from your main_original.lua file into the proper conditional clause. For this game, we basically want to start the game running — spawning asteroids, detecting collisions, etc. — once the scene is fully on screen (the "did" phase). So, in your game.lua file, within the scene:show() function, add the three highlighted commands:

-- show()
function scene:show( event )

    local sceneGroup = self.view
    local phase = event.phase

    if ( phase == "will" ) then
        -- Code here runs when the scene is still off screen (but is about to come on screen)

    elseif ( phase == "did" ) then
        -- Code here runs when the scene is entirely on screen
        physics.start()
        Runtime:addEventListener( "collision", onCollision )
        gameLoopTimer = timer.performWithDelay( 500, gameLoop, 0 )
    end
end

Essentially, these commands accomplish the following:

1. Re-start the physics engine with physics.start() (remember that we paused it in scene:create()).
2. Start collision detection.
3. Start the game loop with our original timer.performWithDelay() command.

Event Link-Up

Our scene:hide() function is now complete, but we need to take a few final steps to make sure it actually gets called. Logically, a scene will never be hidden unless you intentionally cause it to hide, and this occurs when you tell Composer to go to a different scene (composer.gotoScene()).

In our game, we want to return to the menu — or eventually go to the high scores scene — when the player dies and has no remaining lives. This condition has already been accounted for partially in our previous code, so all we need to add is an additional command in the same place.

In game.lua, find your onCollision function and, toward its end, locate this conditional block:

                -- Update lives
                lives = lives - 1
                livesText.text = "Lives: " .. lives
                
                if ( lives == 0 ) then
                    display.remove( ship )
                else
                    ship.alpha = 0
                    timer.performWithDelay( 1000, restoreShip )
                end
            end
        end
    end
end

Now, directly below the display.remove( ship ) command, add the following highlighted command:

                if ( lives == 0 ) then
                    display.remove( ship )
                    timer.performWithDelay( 2000, endGame )
                else
                    ship.alpha = 0
                    timer.performWithDelay( 1000, restoreShip )
                end
            end
        end
    end
end

The timer.performWithDelay() command is nothing new — this instance simply calls a function endGame() after 2000 milliseconds (2 seconds). Of course, we haven't actually written the endGame() function yet, so let's write it now. Directly above your onCollision() function, add this new function:

local function endGame()
    composer.gotoScene( "menu", { time=800, effect="crossFade" } )
end


local function onCollision( event )

    if ( event.phase == "began" ) then

For now, this function simply returns to the menu by calling composer.gotoScene().