Tutorial: Building a Level Selection Scene

12 August 2014

Tutorial: Building a Level Selection Scene

Today’s tutorial illustrates how to build a level select scene for a game. Level select screens are common in games which are divided into levels from which the player can resume play or choose to replay for maximum score.

Setup

This tutorial module is built atop the Corona Composer API. It assumes that we have a scene module game.lua which is loaded when a particular level is selected, along with a scene named menu.lua which will be shown if the player decides not to play a level.

We also need a common “data” table which can be accessed in multiple scenes. The following code loads a mydata.lua file which mimics the simple data module outlined in the Goodbye Globals! tutorial:

This looks more complex than it actually is. The bottom half just pre-populates the table for purposes of this tutorial — this will allow us to see the results without building a functioning game around it. The key table members are at the top:

• .maxLevels — The maximum number of levels for the game (to be included in the level select screen).
• .settings — Data table that will hold various player data and otherwise.
• .settings.currentLevel — Level that the player is currently playing.
• .settings.unlockedLevels — Highest level attained (completed) by the player.
• .settings.soundOn / .settings.musicOn — Booleans for player audio preferences.
• .settings.levels — Table that tracks the player’s per-level progress. For this tutorial, only .stars is important, but we could also track the player’s per-level score.

This entire table can be easily saved using the loadsave module saveTable() call:

Scene Setup

Now that the basic data module is configured, let’s look at the core scene:

Looking in Depth

All of this is based on the standard Composer scene. Although the code is commented, let’s examine each part and its functionality:

1. To keep this tutorial simple, there are no required graphical assets. Instead, we use the display.newPolygon() API to generate vector stars. This API requires an array of vertices, so we define it in the scene’s main chunk in case there’s a need to use it elsewhere.
2. The next two functions handle button events. Since our buttons use the onEvent handler, we need to test for the phase to ensure that the code is only executed once. In each handler function, we simply use composer.gotoScene() to go to the appropriate scene.
3. Inside the handleLevelSelect() function, we set the currentLevel value within the myData.settings table so that it’s easy to access from the game.lua scene. We also call composer.removeScene() to make sure that the game scene loads fresh each time.
4. The rest of the magic happens in the scene:create() event handler. First, we create a background, set its fill to white, and center it on screen. Then we create a widget.newScrollView() to hold the buttons in case we have more than one full screen of them. As designed, we can fit around 20 buttons on the screen without needing to scroll.
5. Next, we initialize some variables that are used to compute each button’s location on the screen (within the scroll view). These include the x and y of the button (xOffset and yOffset) and a count of the current number of buttons in the row (cellCount). The cellCount variable starts at 1, and this tutorial will place 5 buttons in each row.
6. For the max number of levels in the game (myData.maxLevels), we perform a loop and generate a widget.newButton() for each button. This tutorial uses the vector-based method of generating the button shape — in this case, a rounded rectangle.
7. In the loop, we also set the button’s text label as the index of the array, thus numbering them in sequential order. We use this same value to set the button’s id value which is used when the player selects the level.
8. The next block of code tests whether the number of unlocked levels has been passed in. Unlocked levels will be shown in full color with the button’s touch handler enabled, whereas locked levels will be faded out and disabled.
9. If we want to show the number of stars earned per level, we can generate them now. In an actual produced game, we would likely use an image instead of a star-shaped polygon. Either way, we read the number of earned stars from the saved data (myData.settings.level.stars) and generate one star for each. Each star is positioned relative to the button’s x and y values.
10. Next, we increment xOffset to position the next button further to the right. We also increment the number of buttons in the row and, if that value exceeds the number of buttons for each row, we reset xOffset to the first position in the row, increment the cellCount variable, and add the number of pixels at which to draw the next row (yOffset).
11. Once the loop finishes, we insert the entire scroll view into the scene’s view group and center it on the screen.

Conclusion

While some of this module may seem complex, most of the process is straightforward. Of course, for an actual produced game, certain adjustments to variables and data structures would be necessary. In the meantime, if you want to experiment with the code base in this tutorial, please download it here.