Chapter 2 — Upward & Onward

Project Setup

With these basic design goals in mind, start a new project just like you did in the previous chapter:

1. From the Simulator, select New Project… from the File menu.

2. For the project/application name, type StarExplorer and ensure that the Blank template option is selected.

3. This time, under the section where you can select a screen size, choose Tablet Preset. Notice that the width and height values change to 768 and 1024 respectively.

4. Leave the other settings at default and click OK / Next.

5. Locate and open the project folder.

Build Settings

The build.settings file provides real devices (phones, tablets, etc.) with details they need regarding your app. This includes the supported orientations for the app, names of icon files, plugins to include, special information required by devices, and more.

Using your text editor, locate and open the build.settings file within your project folder. It will contain a lot of information, but let’s focus on the highlighted block of code:

settings =
{
    orientation =
    {
        -- Supported values for orientation:
        -- portrait, portraitUpsideDown, landscapeLeft, landscapeRight

        default = "portrait",
        supported = { "portrait", },
    },

Our StarExplorer app will only be available to play in portrait mode, so we set this on the following two lines:

• default = "portrait", — This line specifies that the game should begin in portrait orientation when the user first loads the app.

• supported = { "portrait", }, — This line specifies that the only supported orientation is also portrait. That means that even if the user turns (orients) the physical device around in their hands, your app will remain locked in portrait orientation.

There are several additional things which can be included inside the build.settings file, but in the interest of keeping this guide as straightforward as possible, let’s move on.

Configuration Options

The config.lua file contains app configuration settings. This is where we specify what content resolution the app will run at, the content scale mode, how high-resolution devices should be handled, etc.

Using your text editor, locate and open the config.lua file within your project folder and inspect the following highlighted lines:

application =
{
    content =
    {
        width = 768,
        height = 1024, 
        scale = "letterbox",

Notice that this content table contains a series of configuration settings, including:

• width and height — These values specify the content area size for the app. Your base content area can be whatever you wish, but often it’s based around a common screen width/height aspect ratio like 3:4, set here by 768 and 1024.

• scale — This important setting specifies how to handle the content area for screens which do not match the aspect ratio defined by the width and height settings, for example 3:4 in this case. The two most common options are "letterbox" and "zoomEven".

letterbox	zoomEven

application =
{
    content =
    {
        width = 768,
        height = 1024, 
        scale = "zoomEven",

Physics Setup

Like the BalloonTap project, this game will use the physics engine, so let’s configure it right from the beginning. If you’re using physics, it’s often best to include your basic physics setup code early in the program.

Using your chosen text editor, open the main.lua file within your project folder and type these commands:

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

As you can see, after loading and starting the physics engine, we set gravity values. By default, the physics engine simulates standard Earth gravity which causes objects to fall toward the bottom of the screen. To change this, we use the physics.setGravity() command which can simulate gravity in both the horizontal (x) or vertical (y) directions. Since this game takes place in outer space, we are going to assume that gravity does not apply. Thus, we set both values to 0.

Random Seed

Our game will randomly spawn asteroids outside of the screen edges, so we’ll be implementing random number generation further along in this project. First, though, we need to set the “seed” for the pseudo-random number generator. On some operating systems, this generator begins with the same initial value which causes random numbers to repeat in a predictable pattern. The following addition to our code ensures that the generator always starts with a different seed.

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

-- Seed the random number generator
math.randomseed( os.time() )

Including Images

Initially we’ll need just two visual assets for this project. As before, they should be placed within your StarExplorer project folder.

Loading Image Sheets

If you’ve used another game development platform, you may be familiar with the term “sprite sheet” or “texture atlas.” In Solar2D, it is called an image sheet and it allows you to load multiple images/frames from a single larger image file. Image sheets are also used for animated sprites, where frames for the sprite are pulled from the sheet and assembled into an animated sequence.

Following your existing code, create a sheetOptions table as shown below. Note that it should contain a child table, frames, which will contain an array of Lua tables defining each frame in the sheet.

-- Seed the random number generator
math.randomseed( os.time() )

-- Configure image sheet
local sheetOptions =
{
    frames =
    {

    },
}

When configuring an image sheet, you must specify where the images are located within the sheet. For this game, every image is different in size, so we must provide four specific properties which define the theoretical “bounding box” for the portion of the image sheet to utilize:

1. x — the upper-left corner point of the image in x coordinates, relative to the overall sheet width.
2. y — the upper-left corner point of the image in y coordinates, relative to the overall sheet height.
3. width — the total width of the image.
4. height — the total height of the image.

With this concept in mind, add five Lua tables inside the frames table to declare the position and size of each image within the sheet:

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

With this table of information, we can now load the image sheet into memory with the graphics.newImageSheet() command. This accepts the name of the image file for the image sheet (gameObjects.png) and a reference to the sheetOptions table which we just created:

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

Initializing Variables

In larger programs, it’s a good idea to declare all of the variables that are used throughout the file near the beginning. This helps us stay organized and provides a quick reference if we forget what the name of a variable was and/or if the variable had an initial value.

Following the image sheet options and setup, add these lines:

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

local asteroidsTable = {}

local ship
local gameLoopTimer
local livesText
local scoreText

Let’s examine each set of additions in detail:

• First we declare variables to keep track of the number of lives remaining (initial value of 3), the current score (initial value of 0), and whether the player has died (initially false).

• Next we declare the variable asteroidsTable which will be used for a very specific purpose throughout the game. As you recall from the previous chapter, the curly brackets ({}) indicate a Lua table (array). Among other things, tables are used to keep track of similar types of information. Since there will be many asteroids on the screen in this game, it’s impractical to declare each as a unique variable such as asteroid1, asteroid2, asteroid15, etc. We need a more efficient method and that’s where tables can help — essentially, tables can contain a large amount of object references and other data, growing and shrinking as needed throughout the game’s life.

• On the next few lines, we declare a variable placeholder for the ship object (ship), a placeholder for a timer we’ll implement later, and two variables for the text objects which will display the player’s remaining lives and score.

Great! With our initial variables set, we can begin loading objects onto the screen.

Using Display Groups

In the previous chapter, we simply placed objects on the stage — this is essentially the core layer/group in which all display objects exist. In this game, we’ll insert objects into distinct display groups for more controlled layering and organization. Basically, a display group is a special kind of display object which can contain other display objects and even other display groups. Imagine it as a blank sheet of paper on which you “draw” images, text, shapes, and animated sprites.

With this in mind, let’s create three initial display groups. Following the lines you’ve already entered, add these commands:

-- Set up display groups
local backGroup = display.newGroup()  -- Display group for the background image
local mainGroup = display.newGroup()  -- Display group for the ship, asteroids, lasers, etc.
local uiGroup = display.newGroup()    -- Display group for UI objects like the score

Loading the Background

As in the previous project, we’ll load the background image first:

-- Load the background
local background = display.newImageRect( backGroup, "background.png", 800, 1400 )
background.x = display.contentCenterX
background.y = display.contentCenterY

Loading the Ship

As mentioned earlier, image sheets can be used as a source for an animated sequence of images (sprite) or they can be used to organize a collection of static images that will be used within your app. For this project, we’ll use the second method.

Loading an individual image from an image sheet is similar to loading it from a file. Instead of supplying an image name, however, we specify a reference to the image sheet along with a frame number. Add the following highlighted line to your project code:

local background = display.newImageRect( backGroup, "background.png", 800, 1400 )
background.x = display.contentCenterX
background.y = display.contentCenterY

ship = display.newImageRect( mainGroup, objectSheet, 4, 98, 79 )

Let’s inspect this command in more detail:

• The first parameter specifies the display group that the object will be placed (mainGroup). (not simply on the stage).

• The second parameter is the reference to the image sheet we loaded earlier (objectSheet).

• Since the ship is the 4th frame in our image sheet configuration, we specify 4 as the frame number (third parameter).

• Finally, as usual, we set the width and height to 98 and 79, matching the frame’s width and height values in the image sheet configuration.

local ship
local gameLoopTimer
local livesText

Let’s continue configuring the ship with the following highlighted commands:

ship = display.newImageRect( mainGroup, objectSheet, 4, 98, 79 )
ship.x = display.contentCenterX
ship.y = display.contentHeight - 100
physics.addBody( ship, { radius=30, isSensor=true } )
ship.myName = "ship"

With the first two commands, we position the ship at the bottom-center of the screen. You’ll recognize display.contentCenterX from the previous chapter, but this time we utilize a new command, display.contentHeight. This convenient property indicates the maximum y coordinate of the content area (bottom edge of the screen). Since the ship should be positioned slightly above this point, however, we subtract 100 from this value.

Next, we add the ship to the physics engine with a radius property of 30. In addition, we specify an important property: isSensor=true. This specifies that the object should be a sensor object. Essentially, sensor objects detect collisions with other physical objects but they do not produce a physical response. For example, if a normal body collides with a sensor body, the two bodies will not bounce off each other or cause any other physical reaction. This is ideal for our ship object, because we only want it to detect collisions with asteroids, not bounce off them.

Lastly, we give the ship object a myName property of "ship". This property will be used later to help determine what types of collisions are happening in the game.

Lives and Score

Now let’s place UI labels for the player’s lives and score on the screen:

-- Display lives and score
livesText = display.newText( uiGroup, "Lives: " .. lives, 200, 80, native.systemFont, 36 )
scoreText = display.newText( uiGroup, "Score: " .. score, 400, 80, native.systemFont, 36 )

To keep things simple, we use a special Lua method with the labels to show our lives and score. Placing two periods together in Lua (..) is called concatenation. Concatenation joins two strings into one. Thus, in the livesText = display.newText() command above, we are joining the string Lives: and the variable lives for a result of Lives: 3 being displayed on the screen (remember that we set the initial value of lives to 3 earlier). Similarly, for scoreText, we join the string Score: and the variable score for a result of Score: 0.

-- Hide the status bar
display.setStatusBar( display.HiddenStatusBar )

Finally, let’s write a function to update the text property of both livesText and scoreText. This will be similar to the function we wrote in the previous chapter. As you recall, any time you create a new label or object with display.newText(), the text’s label/value is stored in the text property of the object, so we update that property with the concatenated string value of the label and its associated variable.

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

Now that we have the basic visual objects in place, can load images from the image sheet, and update the UI labels for both lives and score, we’re ready to get started on the game logic and events!