Chapter 3 — Bringing it to Life

Placement

Now that we have a new asteroid on the screen, let's set its point of origin. For our game, asteroids will come from the left, right, or top of the screen — it wouldn't be fair to have an asteroid sneak up from behind!

Given three possible points of origin, we need Lua to generate a random integer between 1 and 3. This is easily done using the math.random() command with a sole parameter of 3:

    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 )
end

Following this command, the local variable whereFrom will have a value of either 1, 2, or 3. Using this, we can implement a conditional if-then structure to handle each of the three cases. In Lua, the structure begins in this basic form:

    local whereFrom = math.random( 3 )

    if ( whereFrom == 1 ) then

    end
end

Let's use this first condition, whereFrom == 1, to place an asteroid slightly off the left edge of the screen. Insert three lines so that your conditional block looks like this:

    if ( whereFrom == 1 ) then
        -- From the left
        newAsteroid.x = -60
        newAsteroid.y = math.random( 500 )
    end
end

Since this asteroid will come from the left side, we set its x property to -60. This should be a sufficient amount to ensure that not even a portion of the asteroid is visible to the player when it's first created (it's entirely off screen). As for the y property, we use math.random() once again to randomly select a value between 1 and 500, effectively making the asteroid appear somewhere between the top of the content area and about half the distance down — after all, we don't want any asteroids coming from a place that makes it impossible to shoot them!

Movement

Now that we have the starting point, we need to tell the asteroid where it should move to. This time we're going to use another physics command: object:setLinearVelocity(). This command is similar to the object:applyLinearImpulse() command which we used in the previous project, but instead of applying a sudden "push" to the object, it simply sets the object moving in a steady, consistent direction.

Add the highlighted line directly following the previous lines:

    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 ) )
    end
end

This might look complicated, but object:setLinearVelocity() simply requires two numbers indicating the velocity in the x and y directions respectively. The only twist we're using here is math.random() to randomize the values so that each asteroid moves in a slightly different direction.

If we decided to call/run this function now, we might see an asteroid slowly moving across the screen from the left side, but probably not. Why? Because we haven't added conditional cases for the other two sides of the screen! Remember, Lua is randomly choosing a number between 1 and 3, but currently we're only handling the occurrence of 1, so there's just ⅓ chance that our current code will generate an asteroid.

The following two conditions will complete the three possible sides from which asteroids can originate. When adding multiple conditions into the same if-then structure, those following the first condition should begin with elseif, not with if. Observe these additions:

    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
end

With these lines, all three conditions are properly accounted for. Now, when this function is called/run, an asteroid will randomly appear in one of the three specified regions and begin moving across the screen.

Rotation

Let's wrap up the createAsteroid() function with an additional command for visual interest. To make the asteroids slowly rotate about their central point as they move through space, we can apply a random amount of torque (rotational force). Following the if-then structure (after its closing end statement), add the following highlighted command:

    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

Placement

The new laser object is now loaded, but we haven't yet positioned it correctly. In this case, we can't use a static position because the ship will eventually be moving left and right via the player's control. Fortunately, it's very easy to position the new laser at the exact same place as the ship by setting its x and y values to the ship's x and y values:

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
end

This will correctly position the laser horizontally and vertically, but there's one further issue to resolve. Because this function creates new lasers after the ship has already been loaded, and both objects are part of the mainGroup display group, lasers will appear visually above (in front of) the ship in terms of layering. Clearly this looks silly, so let's push it behind the ship with the following highlighted command:

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

Movement

As mentioned earlier, we'll move the laser up the screen using a transition. Most transitions are performed with the transition.to() command. In its most simple form, this command accepts an object reference, such as the laser, and a table of parameters to change over a specified time.

Add the following highlighted line to the fireLaser() function:

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

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

As you can see, the first parameter is the object to transition (newLaser). For the second parameter, we include a table which can contain various properties for the transition. Here, we set y=-40 which indicates the laser's vertical destination, slightly off the top edge of the screen. We also set a custom time parameter of 500. For transitions, the time (duration) should always be specified in milliseconds — remember that 1 second equals 1000 milliseconds, so this transition will occur over a duration of ½ second.

Cleanup

Great! New lasers will now correctly appear at the same location as the ship (visually behind it too) and move upward across the screen. There is just one last thing to implement, and it's very important: cleanup. In any app, it's critical that you remove objects from the game which are no longer needed. If you don't, the app will eventually slow to a crawl, run out of memory, and crash — not a good experience for the player!

There are various approaches toward cleanup and it will depend on the situation. For the lasers, we're going to use a very convenient method known as an onComplete callback. Available as an option within transition.to() and several other commands, this tells Solar2D that you want to call a function when something "completes." This is ideal for removing lasers which have completed their transition, so let's expand our transition.to() command to include an onComplete callback:

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

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

Simply stated, this addition runs a function when the transition completes. Inside the function, the only command we need is display.remove( newLaser ) which removes the laser object from the stage. Beyond that, Lua's built-in garbage collection process will automatically free up memory that was allocated to the object.

Tap Listener

We're almost done with the firing mechanics — let's finish up by assigning the ship a "tap" event listener so that the player can actually fire lasers. Immediately following the fireLaser() function (after its closing end statement), add the following command:

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

ship:addEventListener( "tap", fireLaser )

Touch Events

Touch events, distinct from tap events, have four distinct phases based on the state of the user's touch:

• "began" — indicates that a touch has started on the object (initial touch on the screen).
• "moved" — indicates that a touch position has moved on the object.
• "ended" — indicates that a touch has ended on the object (touch lifted from the screen).
• "cancelled" — indicates that the system cancelled tracking of the touch (not to be confused with "ended").

For our convenience, let's locally set the phase (event.phase) of the touch event:

local function dragShip( event )

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

With the phase locally set, we can use an if-then structure to check which phase the actual touch event is in. If it has just begun (initial touch on the ship), the "began" phase is dispatched to our function. In this conditional case, we set the touch focus on the ship — essentially, this means that the ship object will "own" the touch event throughout its duration. While focus is on the ship, no other objects in the game will detect events from this specific touch:

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 )
    end
end

Directly following this, let's store the beginning "offset" position of the touch in relation to the ship. Conceptually, as illustrated here, a touch can occur in various places within an object's bounds. In our code, event.x - ship.x gives us the horizontal offset between the exact touch point on the screen (event.x) and the ship's x position (ship.x). We set this as a property of the ship (touchOffsetX) for usage in the next 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
    end
end

For the "moved" phase (as you can guess), we move the ship! This is done by simply setting the ship's x position, but look carefully — this is where our touchOffsetX property comes into play. If we ignored this offset and simply set the ship's x position to event.x, its center axis would skip/jump to the exact touch point on the screen and, as illustrated above, the touch point within the ship bounds may not be exactly at the center. Fortunately, factoring in the offset value will produce a smooth, consistent dragging effect.

    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
    end
end

-- Store initial offset position
ship.touchOffsetX = event.x - ship.x
ship.touchOffsetY = event.y - ship.y

-- Move the ship to the new touch position
ship.x = event.x - ship.touchOffsetX
ship.y = event.y - ship.touchOffsetY

The final conditional case includes both the "ended" and "cancelled" phases. The "ended" phase indicates that the user released touch on the object, while the "cancelled" phase indicates that the system cancelled/terminated the touch event. Typically, both of these phases can be handled in the same conditional block. For this game, we simply release the touch focus on the ship:

    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
end

Let's complete the dragShip() touch listener function with one more command:

    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

As the comment indicates, this short but important command tells Solar2D that the touch event should "stop" on this object and not propagate to underlying objects. This is essential in more complex apps where you might have multiple overlapping objects with touch event detection. Adding return true at the end of touch listener functions prevents potential (and usually undesirable) touch propagation.

Touch Listener

We're almost finished with the movement mechanics — let's just assign the ship a "touch" event listener so that the player can touch/drag it left and right across the screen. Immediately following the dragShip() function (after its closing end statement), add the following command:

    return true  -- Prevents touch propagation to underlying objects
end

ship:addEventListener( "touch", dragShip )

Asteroid Cleanup

For this game, let's remove asteroids which have drifted off screen by looping through the asteroidsTable table. Remember when we declared this table as a place to store a reference for each asteroid? It may not have seemed relevant at the time, but now it's coming fully into play!

To loop through the table, we'll use a Lua for loop. Essentially, a for loop lets us use an index variable to count either up or down from a starting number to an ending number.

Add the following highlighted commands to your gameLoop() function:

local function gameLoop()

    -- Create new asteroid
    createAsteroid()

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

    end
end

In this case, we need to count down (decrement) starting from the number of asteroids in the asteroidsTable table, but there's one slight catch: the amount will constantly change as new asteroids are created and others are destroyed by the player. Fortunately, Lua has a convenient way to count the number of elements in a table, accomplished by simply prefacing the table name with #:

#asteroidsTable

As you can see, we use this method in our for loop which takes the indicated form — basically, Lua uses the index i, starts at #asteroidsTable, stops at 1, and counts by -1 (decrements).

Inside the for loop, we must include code which should be processed each time the loop iterates. If there are ten asteroids in the table, the loop will iterate ten times. If there's just one asteroid in the table, it will iterate once.

Add the following highlighted lines inside the for loop:

    -- 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

Let's examine these commands in more detail:

• For each iteration of the loop, we first declare a local reference to the asteroid which the loop is referencing on that particular iteration:

local thisAsteroid = asteroidsTable[i]

• The next block is a multi-conditional statement which checks the position of the asteroid being referenced during the loop iteration. Basically, with this statement, we check if the asteroid has drifted substantially far off any edge of the screen by checking its x and y properties:

if ( thisAsteroid.x < -100 or
    thisAsteroid.x > display.contentWidth + 100 or
    thisAsteroid.y < -100 or
    thisAsteroid.y > display.contentHeight + 100 )
then

• If any of the four conditions are met, we perform two important actions:

display.remove( thisAsteroid )

table.remove( asteroidsTable, i )

That concludes our asteroid cleanup! Basically, on each iteration of the game loop, we use the for loop to check for asteroids which have drifted substantially outside of the screen bounds. Each of those "dead" asteroids is then removed from the screen and removed from the asteroidsTable storage table, keeping the total asteroid count down and memory usage low.

Loop Timer

Although you might imagine a game loop as code/functionality which updates on every frame of the application runtime — up to 60 times per second — that's not necessarily true for every app. Because our game loop is a standard function, we have complete control over how often it runs, and when.

There are a couple different ways to run a game loop function repeatedly. In this game, we clearly don't want to generate 60 new asteroids per second, and it's not necessary to perform cleanup tasks that often either. So, we'll implement a repeating timer instead.

Immediately following the gameLoop() function (after its closing end statement), add the following command:

            display.remove( thisAsteroid )
            table.remove( asteroidsTable, i )
        end
    end
end

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

Let's dissect this line:

1. First, we state that the gameLoopTimer placeholder variable (declared earlier) will be associated with our timer. This allows us to use that variable as a reference/handle for pausing or canceling the timer later, if necessary.

2. Next, we call timer.performWithDelay(). This convenient command tells Solar2D to perform some action after a specified number of milliseconds. Timers are useful for a wide array of game functionality, so get comfortable with them!

3. Inside the parentheses, we start with the number of milliseconds to wait (delay) until the timer fires. Here we use 500 which is exactly half a second, but you can experiment with other values. A lower number like 250 will make asteroids spawn faster and increase the difficulty of the game, but don't set this value too low or asteroids will generate too quickly and crowd the screen.

4. The next parameter is the function which will be called/run when the timer fires. Obviously we specify gameLoop here.

5. Finally, we include the optional iterations parameter with a value of 0. If this parameter is omitted, timers will simply fire once and stop. If you include this parameter, the timer will repeat for that number of iterations, but don't be fooled by the 0 in this case — we are not telling the timer to "run zero times" but rather to repeat forever. Basically, passing 0 or -1 will cause the timer to repeat indefinitely (unless we tell it to pause/stop).

Restoring the Ship

Before we get into collision handling, we need a function that can be called to restore the ship following collision with an asteroid. In our game, we'll mimic classic arcade games where, as the new ship fades into view, it's temporarily invincible — after all, it wouldn't be fair to allow players to die consecutive times without being given a chance to dodge incoming asteroids!

Following the code you've already written, add the following highlighted function:

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


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

Let's examine the content of this function:

1. The first command, ship.isBodyActive = false, effectively removes the ship from the physics simulation so that it ceases to interact with other bodies. We do this (temporarily) so that, as the ship fades back into view, colliding asteroids will not trigger another collision response.

2. The next two lines simply reposition the ship at the bottom-center of the screen.

3. The final command might not make complete sense right now, but it will after we add "death" functionality further down. Essentially, this transition.to() command fades the ship back to full opacity (alpha=1) over the span of four seconds. It also includes an onComplete callback to an anonymous function. This function restores the ship as an active physical body and resets the died variable to false.

Collision Function

Next, let's write the foundation of our collision function:

        end
    } )
end


local function onCollision( event )

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

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

This is relatively simple and you should recognize some basic concepts from earlier:

1. Similar to touch events, collisions have distinct phases, in this case "began" and "ended". The "began" collision phase is by far the most common phase you'll need to handle, but there are instances where detecting the "ended" phase is important. Don't worry too much about this now — here, we simply isolate the "began" phase by wrapping our functionality in a conditional clause.

2. For simplicity throughout the function, we reference the two objects involved in the collision with the local variables obj1 and obj2. When detecting collisions with the global method, these objects are referenced by event.object1 and event.object2.

Lasers and Asteroids

Let's handle our first collision condition: lasers and asteroids. Remember how we assign a myName property to each object when we create it? This property now becomes critical as a means to detect which two object types are colliding. Here, the opening conditional clause checks the myName property of both obj1 and obj2. If these values are "laser" and "asteroid", we know which two object types collided and we can proceed with handling the outcome.

    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

        end
    end
end

Inside the conditional clause, let's begin by simply removing the two objects via display.remove(). While a fancy explosion effect would be awesome, this project merely exhibits how to handle collisions — how you expand on this later depends on your imagination!

        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 )
        end
    end
end

Next, let's remove the destroyed asteroid from the asteroidsTable table so that the game loop doesn't need to worry about it any further. For this task, we use another for loop which iterates through asteroidsTable, locates the instance of the asteroid, and removes it:

        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
        end
    end
end

Finally, to reward the player for destroying an asteroid, we'll increase the score variable by 100 and update the scoreText text object to reflect the new value:

        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
        end
    end
end

Asteroids and the Ship

Now let's handle the second collision condition: asteroids and the ship. Add the following condition to the if-then statement following the first one. Notice that we use elseif because we're adding another possible condition to the same statement:

            -- 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

        end
    end
end

Inside this conditional clause, let's begin with an additional if-then check:

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

            end
        end
    end
end

This conditional check might seem a little strange, but we need to confirm that the ship has not already been destroyed. As the game progresses, or with a faster asteroid spawning rate, it's entirely possible that the ship will be struck by two asteroids almost simultaneously. Losing two lives in that case obviously isn't fair, so we check the value of died and only proceed if it's false.

Inside this if-then clause, let's immediately set died = true because the player actually has died this time!

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

Following this, we'll subtract a life from the lives variable and update the livesText text object to reflect the new value:

        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
            end
        end
    end
end

Finally, let's include a conditional statement to check if the player is out of lives:

        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

In the opening clause of this statement, if lives is equal to 0, we simply remove the ship entirely. This is the point where you could show a "game over" message or perform some other action, but for now we'll leave the possibilities open.

In the default else clause (the player has at least one life remaining), we make the ship invisible by setting its alpha property to 0. This ties into the restoreShip() function which we wrote earlier where, when the ship fades back into view, the transition.to() command transitions the ship's alpha back to 1. Immediately following that line, we actually call the restoreShip() function after a delay of one second — this yields a slight delay before the ship begins to fade back into view.

Collision Listener

All of our collision logic is now in place, but absolutely nothing will happen unless we link it up! Since we decided to implement collisions in the global method, it only takes one command to tell Solar2D that it should listen for new collisions during every runtime frame of the app.

Immediately following the onCollision() function (after its closing end statement), add the following command:

        end
    end
end

Runtime:addEventListener( "collision", onCollision )

This command is similar to previous event listeners where we added a "tap" or "touch" listener type to a specific object. Here, we simply add a "collision" listener type to the global Runtime object.