Preparing Your Pi

Believe it or not, one of the strengths of the Raspberry Pi is that it is low power. If you develop on a low-powered computer, then you broaden your audience because not everyone has the latest and greatest gaming rig or mobile device. Indeed, developing on a Pi is perfect for targeting the mobile market, because the Pi shares a lot with the internal hardware of mobile phones.

In the same spirit of inclusiveness, you don’t actually have to have a Raspberry Pi to follow along with this book. You can buy any System-on-a-Chip (SoC) device; common ones include the BeagleBone, Banana Pi, Odroid, and the Pine64.

This book is general enough to cover whatever SoC device you use and any Linux or UNIX operating system. Technically, you can even use a spare computer instead, although you’ll need to install Linux on it first or boot from a Linux USB drive. The important thing is to get through this section and end up with some computing device loaded with a UNIX or Linux operating system.

The advantage of a genuine Raspberry Pi is that it is thoroughly documented. There are lots of tutorials on raspberrypi.org to help you through anything you don’t understand, and there’s little to no variation in what you see on a Pi compared to what you see in this book.

Depending on where you buy your Raspberry Pi, you might find that the OS (called either Raspbian or NOOBS) is included in the box. That’s fine for normal use, but when programming, it’s best to have access to the latest development libraries. Raspbian isn’t known for providing the most recent software tools, so this book uses a Linux OS called Fedberry, derived from the popular Fedora distribution of Linux. You can either purchase a spare microSD card to use with this book, or use the microSD card that came with your Pi, as long as you accept that the contents of your card will be replaced with a different OS.

If you purchased a Raspberry Pi that didn’t include the OS on an SD card, or if you purchased a different SoC device that doesn’t come already set up, then you have a computer that doesn’t know what to do when you turn it on. It needs an operating system, and it’s a great learning experience for you to install one.

Installing Linux onto Your Pi with Etcher

To install an operating system on your Pi or SoC device, you need a microSD card and an OS image file. OS images are available from fedberry.org/#download. Use the Fedberry “minimal” image file.

Caution

This process erases the card, so don’t use one containing photos, videos, or other data that you care about.

There are many ways to get a disk image onto a microSD card. The following is the easy method, and it’s the same whether you run Linux, macOS, or Windows on your personal computer.

1. 1.

   If you have not already done so, download the Fedberry LXQT image from https://github.com/fedberry/fedberry/releases . This image provides a basic OS with a few extra applications. You will manually install a full development environment later.

    
2. 2.

   On your personal computer, download and install the Etcher application from www.balena.io/etcher/ . For both Etcher and Fedberry, you need a tool to unzip archives. If you run Linux on your personal computer, then you already have one; otherwise, download and install 7zip from www.7-zip.org for Windows or Keka from www.keka.io for macOS.

    
3. 3.

   Put the microSD card into your computer. If your computer doesn’t have an SD card slot, you must purchase a microSD card reader.

    
4. 4.

   Once the OS image has downloaded and Etcher has been installed, launch the Etcher application.

    
5. 5.

   In the Etcher window, select the Fedberry image file from where it is saved on your hard drive, probably in your Downloads directory (see Figure 1-1).

    

1. 6.

   Select the SD card as the destination.

    
2. 7.

   And finally, click the Flash button.

    

You can now skip to the “Writing Your First Lua Script” section.

First Boot

Assuming that you have your Pi plugged into a monitor, keyboard, mouse, and Ethernet, you can finally boot into your fresh, new Linux operating system. The first time you boot, you are asked to configure your system.

1. 1.

   Configure your network to connect wirelessly to the Internet. If you are connected to the Internet over an Ethernet cable, then you can skip this category.

    
2. 2.

   Set your time zone. To have your Pi get the correct time and day from the Internet, enable NTP in the upper-right corner of the time zone screen.

    
3. 3.

   Set the administrative password.

    
4. 4.

   Create a user and set a user password. Set the user as an administrator (see Figure 1-2). Take note of your username and password. You will need them often!

    

1. 5.

   Click the Finish Configuration button in the bottom right of the main screen to continue booting.

    

Note

From this point on, the term Pi is meant to encompass whatever device you are using to follow along with this book.

When Fedberry has booted, you are left at the login screen. You’ll log in to the desktop soon, but you got this book so that you could learn to code, so it’s worth looking behind the scenes. Press Ctrl+Alt+F3 to switch to a text login screen instead.

Establishing a Development Environment

Having a development environment means having all the tools you need to develop software, and having a place where you can do that development without affecting the rest of your system or letting the rest of your system affect your work.

Navigating the Desktop

Log in to your Pi using the same username and password as before. If you’ve never used a Linux desktop before, you’ll find that it’s similar to any other computer (see Figure 2-1).

An application menu is located in the bottom left corner, but the three most common applications are pinned to the panel along the bottom. The first icon is for a terminal, which is software that emulates the text console you used in the first chapter. The second icon is a file manager. With it, you can create new folders, move and copy files, move old files to the trash, browse and launch applications, and so on. The third icon is a web browser (see Figure 2-2).

There are also some unique features developed by Linux that are slowly making their way to other platforms. For instance, in the lower-left corner, there are two boxes labeled 1 and 2. These represent virtual desktops. You can open a few applications while on desktop 1, and then switch to desktop 2 to open another application to avoid clutter. It can be useful to leave a Bash shell open on one desktop so you can run commands or test out Lua functions while your code editor is open on another desktop.

Installing Development Applications

You won’t be programming complex games in the Lua prompt, as you did for your simple dice game, so you need all the usual programming tools that software developers use on a daily basis. There are lots of tools that a programmer might use, depending on what a project demands, but there are some things that are expected no matter what. These include the following.

• Text editor. A person who codes needs an application to write code in. Most programmers use a special kind of text editor called an integrated development environment (IDE), which not only edits text but also knows enough about the language being used to add convenience features, such as word completion, syntax highlighting, and file management. Popular IDEs include Eclipse, Qt Creator, and NetBeans. This book uses Geany, a lightweight IDE.

• Terminal. It’s helpful to have direct access to the platform you’re programming. A terminal gives you a shell prompt as an application inside your desktop. No more switching back to a text console with Ctrl+Alt+F3! There are many terminal emulators for Linux; this book uses QTerminal.

• Git. Programming is all about iteration. You try something, test it, improve it, and then try it again. With so many iterations, it’s helpful to have a historical record of each attempt you make at solving a problem. Git is the basis for popular sites like GitLab and GitHub, so it’s a good version control system to learn. There are many interfaces to Git. This book uses a plain old terminal as well as git-cola.

• Web browser. If you are going to refer to the Lua reference manual, you need a way to access the Internet. Fedberry provides the Chromium browser, the open source basis for Google’s Chrome.

• Software catalog. To make it easy to find software, Fedberry provides the dnfdragora repository browser.

That’s not all you’ll need to complete this book, but it’s a good start for now.

There’s a lot of great software out there for Linux, so you could search for packages by description and then try each one out until you find the one you like best. You are encouraged to do that sometime when you have a free month or two, but for the sake of efficiency, install these fine applications:

      $ sudo dnf install geany vte291 git-cola

If you prefer to work in graphical applications, click the application menu in the bottom left of the screen and select Administration ➤ dnfdragora.

In the dnfdragora window, set the search scope to All, All, and in names. The first time dnfdragora launches, it syncs with the application servers, so give it some time to pull an updated application list from the Internet. When it’s finished, the main panel is populated with a list of applications.

Once the applications are listed, search for each of these installer packages: geany, vte291, and git-cola. Mark each one for installation (see Figure 2-3) and then click the Apply button in the lower-left corner of the dnfdragora window.

Creating a Graphical Game

The dice game you experimented with in the previous chapter demonstrated some of the very basic principles of code, but now it’s time to program a game with graphics, and that someone else can play without having to type the code first. To keep things simple, the next exercise is a revised, graphical version (see Figure 2-4) of the dice game.

You may as well start off with proper organization, so create a folder (or directory in UNIX terminology) for your first Lua project.

You can do this two different ways. Maybe the most obvious way is just as you would on any computer you’re used to: click the file manager icon in the lower-left corner of the desktop panel to open a window to your home directory, and then right-click in the empty space of the window and choose Create New ➤ Folder. Name your new directory dice.

Remember that the $ is your shell prompt, so don’t type that. The tilde (~) character is shorthand meaning your home directory, and the slash (/) serves as a path delimiter between one directory (your home in this case) and another (in this case, dice).

Whatever way you choose, the end result is a new directory in your home, called dice. This is where the data files for this, your first game, must be stored.

The Geany IDE is highly configurable, with many themes and plugins. You can spend time customizing it, but at the very least click the Tools menu and select Plugin Manager. In the Plugin Manager window, activate the File Browser extension to add a display of your files in the left panel.

Additionally, go to the Edit menu and select Plugin Preferences. In the Plugin Preferences window, enable the file browser to follow the path of the current file (see Figure 2-5).

Finally, select Preferences from the Edit menu and enable the same feature for Geany’s built-in terminal (see Figure 2-6).

With these features activated, both the file browser and the terminal synchronize their displays with whatever file you are editing at any moment. It won’t make much of a difference now, but once you’re working on complex projects, this makes it easy for you to run test commands in the correct location.

Game and GUI Logic

When you were running your dice game from the Lua shell, everything was instantaneous. Applications with graphical user interfaces, by nature, tend to sit idly until the user tells it to do something. Currently, your GUI dice game launches, rolls the dice, and announces a winner. You need to slow it down so that it waits for the user before taking action.

Common conventions for making a GUI application do something are buttons and menus. Both of these are usually triggered by a mouse click. Why not make the dice game wait to roll die until the user clicks the mouse? The act of clicking the game screen helps the user feel that they have more involvement with the game, and also makes the game something that can be played several times without having to be closed and the reopened.

You already know that the main loop of a LÖVE game is the love.draw function , so that’s the part of your code that you need to control. The first task is to force love.draw to wait for input before displaying any change. A common trick for such control is to create a variable and then force the main loop to wait for that variable to change before taking action.

For this game, use a variable called start, set to true, to indicate that a new game has been launched, but that the main loop is waiting for input from the user. Create the variable in love.load so that the game begins in the start mode.

      start = true

Erase whatever you have in the love.draw function, replacing it with a conditional statement that checks whether start is true or not. If it is not true, then the game commences. If true, it draws the neutral die graphic.

There’s quite a bit of math involved in positioning the graphics. You originally set the game window sizes in the global variables cw (canvas width) and ch (canvas height), so you know the area you have to work with.

In most computer graphic applications, LÖVE included, the upper-left corner of the canvas is 0, and the X and Y axes increase to the right and down screen (see Figure 2-7).

Technically, you could start the first dice display at 0, but so that it’s not crowded against the left window edge, the example code indents it by 33 pixels. The same holds true for the distance from the top edge, which is indented by 30 pixels. The offset of the dice are set to 0, and the scale is set to 0.2, because the source graphics are larger than the screen.

The dice display on the right of the screen is slightly different. To determine its position along the X axis, the width of the canvas is divided in half (or multiplied by 0.5, as the case may be). You could do that math yourself, and then put in the number manually (777*0.5=388), but if you ever changed the canvas size, you’d have to go through your code and find all the wrong numbers and recalculate. Well, that’s exactly what computers are for, so it’s much smarter to take the time to figure out the correct equation rather than doing the math yourself.

function love.draw()

   love.graphics.setColor(1,1,1)

   if start == false then

   -- do something here

   end

   love.graphics.draw(human.img,33,30,0,0.2,0.2)

   love.graphics.draw(computer.img,cw*0.5,30,0,

   0.2,0.2)

   end

Save and then launch the game. At the very least, it shows you the neutral positions of the die. Not terribly exciting, but it’s a good start.

Packaging

You now have a fully functional dice-rolling game. It’s simple, but it’s only about 50 lines of code and demonstrates many important principles of game logic, UI design, and programming fundamentals.

It’s programmed in LÖVE, so any of your friends or family can play it as long as they install LÖVE on their platform. However, if you send them a folder of code, images, and fonts, they won’t know what to do with it. It’s time to package your game for distribution.

Open a desktop window to your dice folder and double-click dice.love. Your game launches just like any normal application would. You can send this file to anyone you want to, and as long as they install LÖVE, they can play your game.

Homework

The love.mousereleased function accepts three parameters from your operating system: the X and Y coordinates on which the mouse was clicked and the button that was released.

Project Directory

There is no rule for how you organize your code, but there is a general convention, especially within the open source software world. You can get a feel for this convention if you browse a few open source projects online, and you’ve already implemented some principles as you created your dice game.

That takes care of the obvious folders, but there are also a few files that most people expect to find in a software source directory: README and LICENSE.

The LICENSE file tells anyone looking at your source how they may use your code. There are several varieties of open source licenses, listed in detail at gnu.org/licenses/license-list.html.

As the author of the code, I license the program that you are about to copy and learn from under the GNU Public License version 3 (GPLv3). This grants you permission to redistribute, or even sell, and modify it as you wish, as long as you give everyone else permission to do the same. As open source licenses go, this is a common and sensible agreement: you get to do whatever you want to do with the code as long as you let the next person in line do whatever they want.

That takes care of all the bureaucracy and preparation. Now you need to build a virtual card deck.

Classes and Objects

In the dice game, you had two dice “objects” to code. An object in code is a little bit like a mold in real life: the code defines the basic properties of an object, and usually allows customization, as needed. Object-oriented programming (OOP) is the prevailing means of developing software today, so learning to structure your code into objects is important, and by the end of this book, it’s something you’ll do naturally.

For the dice game, you coded each object separately because there were only two die. This time, you are writing a game involving 52 playing cards, so it doesn’t make sense to code each card separately, just as programmers in major game studios don’t manually code every single enemy you have to fight.

When a program requires lots of different objects with basically the same properties, you can use a class. A class is a snippet of code—usually stored in its own unique file—that your main program uses as a template when building an object in your game. This template not only generates an object for your program, it creates a whole infrastructure with variables and other properties unique to that one instance of the object.

Open Geany and create a new, empty file called card.lua . Technically, Lua doesn’t have classes, but it has tables that can be treated like classes. You’ve already created a table for the dice game, so some of this process may seem familiar to you.

Next, create a function called Card.init (the word init is a common programming term meaning initialize or create). For the dice game, you used functions, such as math.random()and love.load() , included in Lua. This time, you are creating your own function.

In this Card.init function , you establish a local variable called self, which uses a special Lua extension called a metatable, as a kind of container for all the properties about that individual instance of a card. A card’s self variable ensures that each card can keep track of whatever makes it unique.

Since each card created gets unique memory out of your computer’s RAM, each one can track properties such as its suit and value. At the end of the creation process, the Card class alerts your main program of its self data, which you can use in your game.

Save the card.lua file and create a new one called main.lua .

This prompts Lua to search the current directory for a library called card.

To create a card using your function, create a new variable and invoke your function, along with two arguments: one for the suit you want your new card to belong to and one for the face value.

Your class produces, upon request, a card “object.” It’s not a physical object, but it’s a virtual playing card with unique properties from the next. Each “object” is produced by filling a variable with a table containing preset variables that you have defined as an inherent attribute of the object. This is an important principle in modern programming because it lets you make templates for constructs in your program that you want to use over and over again.

Randomized Cards

Now that you have a card-producing Lua library, you must use it in a way that is useful in a game of Blackjack.

Blackjack is a simple game of chance and calculated risk. Each player draws a card and adds it to their hand until they are as close to 21 as possible. When both players are satisfied, they compare their hands. The player closest to 21 wins. If a player goes over 21, they lose.

It’s important for Blackjack to be random. Your dice game also used random numbers, so you know that when producing a random number, you constrain Lua with a minimum and a maximum value. But Lua has no knowledge of playing cards, so you can’t just tell it to randomly pick a suit or a face card. However, you can create a table listing each suit and a table listing each possible face value and then tell the computer to pick from those numbered lists.

This sets up a LÖVE window, an empty table to represent the player and their computer opponent, and a basic skeleton for your code.

Since you already know how to get a random value from Lua, you can use your card generator library to produce a card object with a random suit and value.

This function creates a temporary variable called c and gives it a random number between 1 and 4. Then it creates another temporary variable called s and uses c to select one item from the suits table. It does basically the same thing with the values table for a variable called v, and then it calls your card generator library to create a new card with whatever random results are in the s and v variables.

At the end of the function, there is a return statement. This means that after the function runs, it outputs information, which can be assigned to a variable.

Like your dice game, user interaction is a simple mouse click. The mousereleased function of LÖVE sends a variety of information, including where on the screen the mouse was released, and which physical button on the mouse was released. You don’t have to use the information, but it lets you be precise about what input you want your game to respond to.

In this code, the left mouse button triggers the creation of a new card object by creating a variable called var, which is assigned the output of your card generator function. Your card generator function, of course, calls your card library so that var contains a table detailing the suit and value of a card.

Once the card has been created, the var variable containing the card is copied into the player’s hand. When you add an item to a table, you must add it to the end of the list; so to specify where in the table the new card goes, you use the #hand shorthand to get the current length of the table plus 1.

After the card has been added to the player’s hand, tally up the current total score for the player. The value of each card is contained in the card’s table. The current card is still going by the name var, so you add whatever is contained in total to var.value.

There are still no graphics being drawn, so add some text to help you see that your application is working up to this point. You can use whatever font you want, but this sample code uses Ostrich from TheLeagueofMoveableType.com.

The problem lies in how the cards are scored. Some cards are listed as numbers, but others are face cards. Lua can’t very well add “Jack” to the total score, so it crashes.

The obvious solution to this problem is to change the King, Queen, and Jack values to 10, and the Ace value to 1. However, if the King and Queen and Jack are all changed to 10, there’s no way to tell them apart when randomly choosing which to display.

Launch your game again. You can keep drawing cards endlessly. No bugs!

Graphics

A game of cards using names and numbers is effective, but not pretty. To make this a real people-pleasing game, you need graphics. Then again, 52 cards are a lot of graphics to come up with. Luckily, a few people on OpenClipArt.org have already done the work for you, posting them as free assets with no recompense required. Download the cards from this book’s code repository, or make your own.

Place the .png files in the img folder of your code directory. They must be named in the Value-of-suit.png format; for example, 2-of-hearts.png.

Now whenever a new card is created, the card object is assigned a graphic with a filename corresponding to its randomly selected suit and name.

Since your game will draw multiple cards on the screen, it’s helpful to have a variable representing the size of a virtual card. In the preceding code, the slot variable is assigned to the results of the getWidth function performed on the playback card multiplied by the current scale. This allows you to use slot to represent any space occupied by a card. In the real world, you would use inches or centimeters, but those don’t mean much on screens, so for this game, you use slot instead.

In addition to creating the deck and a variable for one unit of card measure, this code sample sets the background of the game window to green.

Launch your project. The deck should appear in the upper-right corner; the instructions are on the right. If you click the green tabletop, nothing happens, but if you click the card deck, you are dealt a new card. This happens until the cards flow right off the screen.

Competition

Blackjack can be a solitaire game in real life, but people playing competitive computer games usually expect a definitive win and lose condition. That means you need to program an opponent.

According to the Internet, the prevailing opinion on Blackjack is to hold at around 17. This being the only real “strategy” (such as it is), programming an AI is a simple conditional: if the computer’s hand is 17 or higher, then the computer must hold. To make the game a little more exciting, you can make the computer more reckless than popular strategy dictates by setting its hold tolerance to 16 or 15.

Notice that the computer takes its turn before the player. This means that whether or not the player is drawing a card or holding, the computer still has the opportunity to take a turn.

Just because the computer chooses to hold doesn’t necessarily mean that the player is going to hold, so a hold flag can only be set by the player, which is currently the else statement in the player’s mousereleased action.

Once a player chooses to hold, the game is over. At that point, you could program a pop-up box to ask if the player wants to play another hand. However, when designing an interface, it’s better to default to success as often as possible. A player knows how to exit the game, so there’s no reason to bother them with prompts. That means if the player has decided to hold, the game should just start over. For that to happen, you need a reset function.

A reset is called when two things are true: the player has decided to hold, but the player has clicked somewhere on the screen. However, since clicking the table is also a sign to hold, some safeguards need to be introduced to prevent clicking the table from both starting a new game and signaling the end of that new game. A simple way to prevent a premature endgame signal is to ensure that the player has at least one card on the table before flagging a hold or a reset.

Launch the game to verify that it’s working and to see what’s missing.

Winning

All that’s left now is to detect and declare a winner. Sometimes, it’s easier to detect failure than success, so the first thing you can do is add a watcher function to check whether or not the player has exceeded 21. If ever a player’s hand exceeds 21, then there’s no way for the player to win, so the hold flag can be set immediately to bring the game to an end.

The Lua tonumber method is a safeguard to ensure that the content of total is definitely treated as a number and not a string. It’s not very likely that LÖVE would get confused about that, or that total would contain a string, but since it’s a math operation, it doesn’t hurt to ensure that both sides of the equation are numbers.

There can be no win condition unless a hold has either been chosen or imposed, so it’s safe to only call the winner function if hold is true. You can check this in the love.draw() section of your code, using this as an opportunity to display on screen a running total of each hand until a winner is announced.

The game is complete. Launch it to try it out.

Open a desktop window to your blackjack folder and double-click blackjack.love. Your game launches just like any normal application. You can send this file to anyone you want to, and as long as they install LÖVE, they can play your game.

Homework

Game Theory

What is a game? Most of us play games in some form, but few of us stop to consider what makes a game feel like a game. You have now programmed at least two games, and if you think about what you have learned, you will likely detect a few common elements not only in what you have made but also in other games you may have played.

You might think, at first, that a game requires competition. While some games do require players to compete against one another, other games require them to work together to defeat a common threat. In some games, a player is just trying to beat his or her own best score. So in broad terms, a game requires a win condition .

Once a win condition is declared, it’s natural to add obstacles that block players from making the win condition true. In some games, the obstacles are other players or a computer playing the part of other players. In other games, the obstacles are forces of nature, physics, or time itself.

Since most games are intended to be played more than once, the obstacles also must change from play to play. Games that don’t change are predictable and eventually cease to challenge the player, which is usually considered the thing that makes games fun.

In fact, if you think about the most enduring games, there are ones that are never the same, like chess, poker, and Dungeons & Dragons, and those that have had their challenges completely redefined, as speed runners have done for Super Mario Bros. and other relatively stagnate games.

You already learned about randomness in the previous two games you made, so creating obstacles that change with each play-through is familiar to you.

The next game that you program in this book is a fantasy card game inspired by games like Magic: The Gathering, Hearthstone, Pathfinder Adventure Card Game, and other trading card games. It will teach you the concepts necessary for all kinds of games, including collision detection, saved game states, graphics, and more. But first, the game must be designed—keeping the game theory principles that you just learned in mind.

Experimental Design

Step away from your Raspberry Pi for this section. If you have a deck of playing cards, you can use that during this exercise; otherwise, find some blank index cards or a few sheets of paper cut down to approximate playing-card size.

You’re going to invent a new game that modernizes the game that you just programmed, Blackjack. Although the initial design uses a standard deck of cards as a tool, ultimately, you will style the game as a battle scenario, so the game’s name is Battlejack.

There will be several iterations of this new game, and while this book proscribes much of the game to you, you are encouraged to add your own variations along the way. There are no right or wrong answers here. Any idea is worth trying. And if something breaks the game, then you can adapt it or throw it out as needed.

Pseudo Code for Battlejack

Once you’re happy with a game concept, it’s time to write what’s called pseudo code. Pseudo code is an informal but structured method of planning out a program without worrying about syntax and other details. It’s purely an exercise in logic and planning. Pseudo code doesn’t have to be right, it can be changed later, but it serves as a good guide for you when you sit down at a blank screen to start writing code.

At just 20 lines , this is obviously a very simplified picture of what the game requires, but it’s a good “big picture” view of what is needed. Having it as a guide will help you stay focused when it comes time to write the actual code.

Documentation

It’s just as useful for you as a programmer, and even more useful for your players, if you document your game before you even begin writing code. In big companies, this step is typically done by the UX (user experience) team. They literally draw out what a program is intended to look like, where buttons and menus appear, and what each button or widget does. This is helpful to you while coding because you know where to put your interface elements, and it’s good for your users because you can usually repurpose the design specs as user-facing documentation explaining how to play the game.

Figure 4-1 shows a sample spec for Battlejack.

When the game launches, the player is greeted with a menu screen that allows the user to resume a saved game or start a new game, adjust settings for full-screen or windowed display, and determine whether or not tutorial tips are displayed during play.

During game play, the user clicks their own deck to draw a card. During their turn, the player clicks and drags cards to either the dealer’s stash to cancel out a card in play, or to their own score box to add their card to their own stash. Onscreen prompts alert the player of their choices.

If a player attempts to cancel a dealer card out with a less powerful card (trying to cancel a five-strength card with a three-strength card, for example), nothing happens. The player may add powerups or additional cards to complete the action, or click and drag the card back into their hand to continue.

There are no undo functions. Once a move has been made, the move is not retractable.

A spec document doesn’t necessarily have to be followed to the letter, but it serves as a guide and a target while coding. Some adjustments might have to be made. Some features might have to be dropped, others added, and still others changed. If you were hired to program to a specification, changes would have to be negotiated to ensure that you’re not cheating your client out of something you assured them you could do. In this case, however, you are your own client, and so this spec document is just a gentle guide and a helpful map of what needs to get coded and what needs to be produced for the game.

In the next chapter, you’ll learn about code libraries, data storage, and deck definition files, which are essential for a feature-rich video game.

Homework

Even high-tech video games can be reduced down to tabletop mechanics. Learning why games are fun to play is an important part of designing good games.

Try to come up with a card game version of your favorite game. It doesn’t have to be an exact match, but see how close you can get. Incorporate dice as needed.

Installing New Libraries

In most games, the kind of data needing storage is not very complex, so usually a simple configuration text file is sufficient. For Lua to know what to do with a text file, the text must have a predictable structure. Highly structured text storage forms a non-relational database that Lua loads into memory and uses just like any other variable you might create in Lua.

There are many popular formats for these kinds of files, including YAML, JSON, and INI. These formats allow you to store data in a consistent structure, which enables its parent application to accurately parse it.

One library (sometimes also called a module) that enables plain text configuration files is inifile . As its name suggests, it interacts with INI configuration files (if you don’t know what that is, you’ll write one soon, so don’t worry).

The best place to find libraries for Lua is luarocks.org, a website dedicated to tracking and distributing Lua libraries. The site is useful for a new Lua programmer because it has several methods for you to search for libraries that you may not even know exist. As you become more familiar with programming, you’ll get a feel for what to expect from any language. The luarocks command will prove far more efficient.

Once luarocks is installed, type it into a terminal to see a helpful message.

The --tree option tells luarocks to create a new folder, called local in this example, for all the files that would normally get installed. With this simple trick, you install all the dependency code you want to use in your project into the project directory itself. Your user doesn’t have to worry about installing anything extra, because it’s all contained in your project.

Now you know why you might want to add a library to a project and how to do it.

Now it’s time to try some libraries to help with configuration files.

Configuration Files

To see how to interact with a text-based configuration file, open Geany and create a new file and enter the following sample data in INI format.

Save the file as sample.ini into your home directory, not the config directory. After all, saving the configuration file into your LÖVE project directory is exactly what you’re trying to avoid, because you want the configuration file to be separate from your application.

Imagine that this file is a save file for a game, with the progress of each player in each configuration block. Were this a real game, you would save a configuration file in a hidden folder named ~/., but for now, you can keep this sample unhidden.

This simple application detects the user’s home directory, detects how the operating system finds its way to the home directory, parses the INI file, and then increments the level entry for player1 by 1.

This tells you that Lua attempted to use the inifile library, but couldn’t locate it because the library isn’t installed on your system; it’s installed in your project directory.

Deck Building

Having completed the exercise in this chapter, you not only know how to store data on your user’s computer, but you also know how to define data structures in a file to have it imported by your application. That means you don’t have to define a deck of complex battle cards in the main code of your application, which means a smaller file for your executable code and a lot less clutter in your main script.

For the Blackjack game, the card deck was a simple 52-card poker deck. Your current project, Battlejack, can use a standard card deck, but part of the fun of programming digitally is that you can generate game assets without the costly manufacturing bills involved in creating a new deck of cards in the physical world. It doesn’t make sense to limit the game to a standard poker deck when you can invent any theme you want for your game.

Regardless of your artistic skill or access to artwork, 52 cards is a lot of cards to make. It’s not impossible (there are more than 10,000 Magic: The Gathering cards, and 2,000 in Magic Online), but for an independent game developer, it’s a tall order. When determining the assets for a game, it’s important to look critically at what is necessary and what is just nice to have.

For this project, even though the design assets were 52 cards, there were actually only 10 unique values: 1 through 10. For every iteration of cards 1 to 10, there were three cards worth 10 (Jack, King, and Queen). Furthermore, although the dev deck had four suits, the suits actually had no effect on the game, so those can be thrown out.

To create player identities, the alpha version of the game used red and black, and since that’s easy and classic, the digital version can keep that. For accessibility, the digital version will also use a symbol along with the opposing colors, since not everyone can see the color red.

To make the game a little more exciting, the digital version of Battlejack will enable players to “level up” as they continue to play. Levels in any game are a mix of rewards and, essentially, penalties; the players level up and become more powerful, but only to face new challenges. That means the digital deck will have a small subset of extra cards that are shuffled into the game, throwing off the predictability of how often certain values are drawn, and a second subset of cards that serve as “power ups” granting the player a free bonus (anywhere from a +1 to +3) to their hand.

There isn’t much to this dataset, but it should be expressed separately from the user data because it is not data that is meant to change. It defines the virtual deck of cards, and that’s all. Tracking which cards have been drawn during a game must be done by the application itself, because it gets reset every time a new game is started. Any permanent rewards, penalties, or level data is written to the user data file.

Take a moment to think about what kind of deck you want to use for your Battlejack implementation, or download and use the deck provided with this book. (The art is licensed under a Creative Commons license, so you may use the artwork for any purpose). Once you have decided on a theme, create a project folder called battlejack. Create font and img directories within your project folder, as usual.

That’s just 25 cards to generate; although in a pinch it can be done with just three (one for all face cards, one for all earned cards, and one for all powerup cards). That’s manageable, so now all that’s left to do is make them. And that’s just what you’ll do in the next chapter.

Homework

Installing and learning new libraries is an important part of programming. Nobody codes everything from scratch unless absolutely necessary, because there are so many great libraries out there with much of your work already done for you.

Install lua-yaml or a similar library for parsing YAML and try to parse some sample data.

For an example of a working script, download the code files for this chapter from this book’s code repository.

Design by Genre

The word genre is an art term meaning a category or style. It’s a term meant to be broad and nonspecific. If you’re fortunate enough to be able to hire an artist to do artwork for your game, then a genre is useful to convey to the artist what they should be aiming for. When it’s entirely up to you to design the game’s graphics, a genre gives you a target to aim for when gathering and creating all the different artistic elements that you need.

Before you sit down to create your game art, stop and think of a genre to serve as your central design theme. Your theme can be anything, just think about what appeals to you or to your intended audience. Think in terms of a broad genre. The more general your initial concept, the easier it is to hit your mark in the end. Much of the frustration that non-artists experience when they attempt to make art is because they see clearly in their mind what they want, but lack the artistic skills to make it happen. Protect yourself by avoiding specifics.

It can also be fun to mash up two different genres. Instead of settling for just a fantasy game, why not make rock-a-billy fantasy? Or cyberpunk in the Old West? Or a cartoon horror game? Mix it up. Force yourself to invent a rationale for an unlikely combination, and see what happens.

Let the Fonts Do the Talking

Once you have thought of a genre (or two) for your game, go on a font hunt. Fonts are a great way to convey a theme quickly, and since there are so many open source fonts out there, it’s one of the lowest investments of effort on your part (see Figure 6-1). There’s a font out there for every genre, so go find one and bring it into your project to kick-start your thematic vision.

Note

Fonts are just like everything else you find online or on most computers. They’re licensed for use, meaning that if you find a font you like on a Windows or Mac computer, it’s only licensed for you to use on that one computer. You’re not allowed to redistribute it with your game. So when looking for fonts, make sure its license permits it to be redistributed.

Some of the best open or redistributable font websites include

• FontLibrary.​org

• slackermedia.​info/​sprints

• FontSquirrel.​com

• TheLeagueofMovea​bleType.​com

• DaFont.​com (use the site’s filters to view only free and open source fonts)

If you choose a highly stylized font, then you might need two fonts: one for big titles consisting of only a few words at a time, and one simpler font that’s easier to read for text that users need to read often or quickly.

The important thing is that the font or fonts you choose speak to your theme. It’s alright if your fonts are a little cliché as long as they enforce your genre. If you’re not sure of what type of font to use, go look at some movie posters or book covers to get an idea of how fonts are used to convey the genre of the story being told.

Before continuing, download a font or two to your Downloads folder. This example uses the Arkham font from DaFont.​com ( www.dafont.com/arkham.font ), a free font with no restrictions on redistribution.

To install a font, do the following.

1. 1.

   Open a file manager window and navigate to your Downloads directory. Most font downloads are zipped, so you must unarchive them to install them.

    
2. 2.

   If you prefer to work with GUI tools, install xarchiver in dnfdragora.

    
3. 3.

   If you prefer to work in a terminal, install p7zip-full with apt .

    

  $ sudo dnf install p7zip-full

1. 4.

   Next, create a local font folder located at ~/.local/share/fonts.

    

  $ mkdir -p ~/.local/share/fonts

1. 5.

   To do this in the GUI, open a file manager by double-clicking the Home icon on your desktop. Right-click in any blank space in the file manager window. Select Options ➤ Show Hidden Files, and then navigate to .local/share. In the share directory, right-click any blank area and select New ➤ Directory. Name the new directory fonts.

    
2. 6.

   Create a subdirectory in ~/.local/share/fonts for the first letter of each font you are installing, and then copy the TTF or OTF files to the appropriate place.

    
3. 7.
   To copy the files, you must unarchive your font downloads. Most font archives can be unarchived with p7zip, but you can also use other unarchiver tools as needed.

       $ cd Downloads

       $ 7z x arkhamfonts.zip

       $ tar xvf nouveau.tar.bz2
    
4. 8.
   Once unarchived, you can copy the files to their destination.

       $ mkdir -p ~/.local/share/fonts/a

       $ cp ~/Downloads/arkhamfonts/ark*ttf ~/.local/share/fonts/a
    

In the GUI, right-click a font archive and select Open with ➤ xarchiver. Drag and drop font files from the xarchiver window to the directory matching the first letter of the font name.

Color Scheme

The last thematic element you must decide upon is a color scheme. While some genres have specific colors associated with them, there’s a lot of freedom in this aspect of design. While the Old West is often associated with browns and yellows, and a technical future world often is painted in black and neon green, you can use your own color palette in any genre as long as your colors are consistent and somehow relate to one another in a pleasing way.

The problem for non-artists is finding colors that match.

To solve this problem, all you have to do is generate a color palette from an existing image. Search the Internet or your own hard drive for an image that you like. It doesn’t have to be a free-licensed photo and it doesn’t have to match the genre for your game, because the image is only going to be used to generate colors. Just pick an image that you enjoy looking at.

To generate a color scheme from a photograph, do the following.

1. 1.

   Install Image Magick.

    

      $ sudo dnf install imagemagick

1. 2.

   Download the image to your Pi.

    
2. 3.

   Run the following Image Magick command, adjusting ~/path/to/image.png to match whatever photo you have downloaded.

    

      $ convert ~/path/to/image.png -geometry 16x16 -colors 8 \

      -unique-colors -scale 4000% ~/scheme.png

1. 4.

   Take a look at the resulting color scheme.

    

      $ display ~/scheme.png

The colors you get back as scheme.png are more or less an average of dominant colors (it’s not mathematically sound, but it’s a rough approximation). Use these colors to guide your design (see Figure 6-2).

Card Design with GIMP

GIMP (GNU Image Manipulation Program) is an all-purpose graphics creation application. You can use it to modify photographs, textures, and existing graphics, and combine them all together to provide you with your game assets, or you can create graphics from nothing but your own ideas.

The barrier to getting started with GIMP isn’t artistic skill so much as comprehending and learning the many tools that GIMP has to offer. Entire books have been written about it, there are tutorial websites dedicated to it, and it has thorough documentation, so this section steps you through the process of using the tools that apply to the current goal: creating playing cards for Battlejack. Stepping through this won’t teach you everything about GIMP, but it demonstrates the general process and some of the common tools.

Install

There are a few different ways to install GIMP. The easiest way gets you an old version of GIMP, and while there’s nothing wrong with that under normal circumstances, you’re a software developer now so there’s no reason to settle for second best. Instead of installing using the Synaptic application installer or the dnf command in a terminal, you can install the latest version, as described at www.gimp.org/downloads/ .

The latest build of GIMP is delivered using Flatpak, a software installer method similar in spirit to dnf. To use Flatpak, it must be installed.

$ sudo dnf install flatpak

Once Flatpak has been installed, use it to install GIMP.

$ sudo flatpak install \

https://flathub.org/repo/appstream/org.gimp.GIMP.flatpakref

Once GIMP and all of its dependencies have been installed, you must log out of the Enlightenment desktop, and then log back in so that it recognizes updates from Flatpak. If you don’t want to do that just now, you can launch GIMP manually, as described in the gimp.​org download instructions.

$ flatpak run org.gimp.GIMP//stable

In the future (after a reboot), you can find GIMP in your application menu.

The GIMP interface consists of three main regions: the toolbox is full of all the tools that you use to compose graphics, the main window contains any graphics that you are working on, and the contextual docks provide extra options based on what you’re doing.

In the first part of this chapter, you defined a theme or a combination of themes, and collected suitable assets, such as fonts and clip art. GIMP allows you to composite them together.

New Document

To create a new document in GIMP, do the following.

1. 1.

   In the GIMP window, click File ➤ New.

    
2. 2.

   In the Create a New Image dialog box that appears, set the unit of measure to mm. Set the image width to 63.5mm and the height to 88.9mm. These measurements are those of a standard US poker playing card.

    
3. 3.

   Since screen size and printed size are different, click the Advanced Options link at the bottom of the window and set the resolution of your image to 100 DPI. Any lower, and your image may look too small or pixelated on standard displays. Any higher, and your image will be too large to fit on the screen.

    

Note

For serious design work, it’s not uncommon to design at a higher resolution, just in case you want to also print the designs you create for onscreen display or to account for the eventual increase in graphic resolution. For instance, as of this writing, it’s common for gamers to own 100 DPI monitors sized 1920×1080, but in a few years, 4K monitors and greater will be the default. If you design in higher resolutions, you safeguard against increasing resolution, but if you do that during this chapter, you have to scale the image down in LÖVE.

Color Scheme

So that you have it handy, open the scheme.png color scheme file you created earlier. If you didn’t create a color scheme file, that’s alright, just keep your color scheme in mind.

Color selection in a graphics application is a lot like variables in programming. It’s something you end up doing a lot more often than you think you should have to, although GIMP makes it easy. GIMP is smart enough to map a color scheme to a palette.

1. 1.

   To see your GIMP palettes, go to the Window menu ➤ Dockable Dialogs ➤ Palettes. This embeds a new panel displaying color palettes, including one called Colormap of Image, which is your color scheme imported as a palette (Figure 6-3).

    

1. 2.

   Right-click your palette and select Duplicate Palette to create an editable copy.

    
2. 3.

   Double-click the duplicate and give it a name, such as cardscheme . A named palette becomes permanent.

    
3. 4.

   You may now close the color scheme file so that only your blank card appears in your workspace.

    
4. 5.

   Your named color scheme remains. Right-click it and select Edit Palette to open the Palette Editor tab. This displays your color scheme so that you can use it as a reference when choosing the colors in your design.

    
5. 6.

   GIMP uses a tabbed interface to manage open files, so to get back to your card design, click the appropriate tab at the top of the window.

    

Text Elements

Eventually, you must create cards for each card listed in the deck.ini file, but this example creates a wizard card with a value of 10 to ensure that the initial design accounts for a long title and a double-digit value.

1. 1.

   Select the Text tool from the Tool Options panel, or press T on your keyboard.

    
2. 2.

   Click near the top-left corner of your card, but don’t start typing anything yet. When you click, a contextual tool-based panel appears below your toolbox. Since the text tool is active, you see options for text. Pick a font within your theme, and set the size to 60 or so.

    
3. 3.

   To set the color of your text, click the box labelled Color. A color picker window appears. Its default view is the GIMP color picker, but there are tabs along the top of window Figure 6-4.

    

1. 4.

   Click the right-most tab to view your custom palette and choose a color for your text.

    
2. 5.

   Click the OK button.

    
3. 6.

   Now that you have your tool configured, type the title of the card: Wizard. Don’ worry if you positioned your text too far to the right such that the whole word won’t fit; you can fix that later.

    
4. 7.

   Press the Esc key to exit text mode.

    

Time to Save

It’s never too early to start saving your work. To save your document, go to the File menu and select Save. You can save the document anywhere you please, but it’s best to keep project work together, so saving it into your battlejack directory is best.

However, GIMP files are a special .xcf format intended as an uncompressed master copy, not as a file for everyday use, so in the end you’ll export to .png or .jpg. Intermediate files that are necessary to create assets but that do not ship with a game are generically called source files. It’s not uncommon to place them in a directory all their own, and then exclude that directory from your final .love package.

1. 1.

   Using the GIMP save dialog, create a new directory, called src, in your battlejack project.

    
2. 2.

   In src, create another directory called img, and save your file into it with the name red-10-wizard.xcf.

    

Moving Layers

When you typed text onto your card, you created a new layer. If you don’t see a Layers docker in your GIMP window, go to the Window ➤ Dockable Dialogs menu and select Layers to open it or bring it to the top of a docking panel.

Layers are like sheets of cellophane placed on top of a canvas. They’re transparent until you “paint” something on them, and even then you can always move or remove the layer entirely because you haven’t painted on your canvas, but on a transparent layer above it.

As long as the text layer is selected (and it is, by default, because it was the most recent one you created), its bounding box is a yellow and black dotted-line. By default, a layer uses up only as much space as it needs, but if you need to make a layer bigger, go to the Layer menu and select Layer to Image Size.

1. 1.

   To move a layer, select the Move tool in the Tool Options panel, or press M. As always, the Tool Options panel displays configuration choices for that tool. Select the “Move the active layer” option.

    
2. 2.

   Click your card and drag your mouse to move the active layer. Position your text where you think the title of each card looks best.

    

Backdrops

To help the player focus on what’s important, it often helps to add backdrops. A backdrop separates important information, especially text, from the background image.

1. 1.

   To add a layer between the background and a foreground layer, right-click the background layer and select New Layer.

    
2. 2.

   In the New Layer window, name the layer backdrop and set the “Fill with” field to Transparency so that the layer is filled with a transparent alpha channel.

    
3. 3.

   Select the Rectangle Select tool from the Tool Options panel, or press R on your keyboard. Using this selection tool, select an area around the title. It might be hard to tell, but you’re not selecting the title text or the white background behind it. You’re selecting a portion of the invisible layer between them.

    
4. 4.

   Click the top color swatch under the toolbox. In the color picker that appears, select the Palette tab and select a color within your color scheme.

    
5. 5.

   Click the Edit menu at the top of the GIMP window, and select Fill with FG Color (FG stands for foreground).

    
6. 6.

   To exit selection mode, press the Esc key on your keyboard.

    

Color Code and Value

The card still needs a value. According to deck.ini, its value is 10. Repeat the previous process to create a value indicator.

Since Battlejack’s opposing sides are differentiated by color (red against black), use red as the backdrop color. If you don’t have red in your color scheme, you must adapt. You can still use your color scheme as a guide, though. RGB colors are defined by three numbers ranging from 0 to 255: the first number is for red, the second for green, and the third for blue. These values are visible in the right column of the GIMP color picker window. Look at a color in your palette and shift its numbers such that the highest number is in the color you want to create within the same scheme.

For instance, assume you have a green defined in your palette with these values: Red 11, Green 14, Blue 8. To produce a red similar in “feel”, shift each number one position to the left so that the number in the Blue slot now goes to Green, the number in the Green slot goes to Red, and the number in Red wraps around to Blue: Red 14, Green 8, Blue 11.

The resulting red shade may not be exactly what you want, but this trick produces something in the same mood as the rest of your color scheme, and you can adjust it manually with one of the color wheels in the color picker tabs.

Background Image

The card design is basically finished. It has the requisite information on it, so all it needs now is an image. Find an image that you feel might represent a wizard. Think abstractly. It’s easier to find an image that suggests wizardry than to find a free image of exactly what you see in your mind’s eye when you think of a wizard.

For example, you might be able to find a series of icons for fantasy roles consisting of wands, swords, battle axes, and so on. Even if you only find five or six icons, you could reuse those depending on the broad category of each card (a wand for each magic user, a sword for generic fighters, an axe for particularly powerful fighters, and so on.

Alternatively, you can borrow from Magic: the Gathering, which bases all player abilities on five different types of land. Backgrounds for video games or even landscape photography are easy to find. Add some “flavor text” on the card to explain how the land depicted has influenced the wizard that the card represents.

The possibilities are endless, so use your imagination. If you can’t find suitable images for this project, you can use images provided along with the source code for this book. The images are from the tabletop game Petition, designed by the author, and illustrated by Nikolai Mamashev in Krita on Linux. All assets are provided under the Creative Commons Attribution-ShareAlike license.

1. 1.

   To bring in an image, click the layer named Background. This layer is the base layer of your GIMP document.

    
2. 2.

   Click the File menu and select Open as layers.

    
3. 3.

   The image you choose from the file chooser is imported into your document above the Background layer but below your backdrops and text. The image may be too large, but you can fix that with the Scale tool.

    
4. 4.

   As needed, select the Scale tool from the toolbox, or press Shift+S on your keyboard.

    
5. 5.

   Click the image that you want to resize and use the selection bounding box or the dialog box to scale the image to better fit into your card design.

    
6. 6.

   Press the Return key or click the Scale button to accept the change.

    

Other tools you can use to fit an image into your design include the Rotate and Flip tools . Try them out and see what looks best.

Integration

To bring elements of the card design together, and as an excuse to learn more GIMP tricks, the final step is to make the card look more like an intentional design and less like something cobbled together from disparate sources. You can try one or none of these techniques, depending on what you like in card design.

The first technique is to add a subtle drop shadow to the backdrop to suggest that the “meta” game information is not part of the wizard. In other words, you’re acknowledging that in real life, people don’t walk around with banners and titles and a number value assigned to them.

1. 1.

   To add a drop shadow, select a backdrop layer and then click Filters ➤ Light and Shadow.

    
2. 2.

   There are currently two different drop shadow filters: one is permanent and the other (“legacy”) creates a new layer just for the drop shadow. Use either one, but remember: less is more. A subtle shadow says more than a big, bold shadow that draws attention to itself.

    
3. 3.

   Another integration technique is to merge the meta information of the card with the “flavor” (graphic). You can do that by blending text into the image. First, right-click the 10 layer in the Layers docker and select Text to Path.

    
4. 4.

   Locate the Paths docker by clicking the Windows menu and selecting Dockable Dialogs ➤ Paths.

    
5. 5.

   In the Paths palette, there is now an outline of the text element 10. The outline is a vector path— a mathematical formula that GIMP doesn’t see as a graphic but as a guide for graphical manipulation. Right-click the path and select Path to Selection. The text on the card is now selected.

    
6. 6.

   Navigate back to the Layers docker. Click the eye icon to the left of the 10 layer to hide the text, and then select the red backdrop layer.

    
7. 7.

   With the shape of the 10 still selected, press the Delete key on your keyboard, or go to the Edit menu and select Clear. This erases red from your backdrop in the shape of the number 10. You can see right through the backdrop to the image beneath.

    
8. 8.

   To remove the active selection, go to Select and choose None, or press Shift+Ctrl+A on your keyboard.

    

There’s a lot more you can do in GIMP, so try out some subtle effects, brushes, and composite modes. Work in layers, so that anything you do can’t be undone later if necessary. GIMP is a powerful tool, so investing in a good tutorial book or spending time on some tutorial sites is effort well spent.

Of course, you don’t have to use this example as a blueprint for your design. Come up with your own ideas, tap into what appeals to you, and create it Figure 6-6.

Exporting from GIMP

The native format of GIMP files is a multilayered and uncompressed .xcf file. It’s intended as a project file for use within GIMP. It wouldn’t make sense to use it anywhere else, especially not in a LÖVE game. After completing each card, you must export it to a common graphic format like PNG or JPEG.

To export an image from GIMP, go to the File menu and select Export as.

In the file chooser that appears, navigate to your battlejack project directory, name the file in a standard format, such as red-10-wizard.png, and then export the image to the img directory.

Homework

Getting to know GIMP is important if you plan on doing graphics work, whether you anticipate creating promotional web banners or all the graphics in your game. Spend some time getting to understand how GIMP works, and enjoy the freedom of doing complex graphical work without having to pay a “rental” fee each month the way that designers tied down to big-name competitors do.

There are several other excellent graphic applications on Linux. GIMP is good at collage (professionally known as compositing), and can be used for digital painting if you download a good set of brushes.

Main Framework

Launch Geany and navigate to your battlejack project directory.

Create three new files: main.lua, menu.lua, and game.lua. Since LÖVE always launches a file called main.lua, you must use that as a kind of control center for the different parts of your game. The main.lua file serves as the engine keeping the game open; it invokes the menu and game states.

Your application can only be in one state at a time. A player cannot be in the menu while playing the game. So whenever a game state is activated, it creates a token to designate that it is the current active state.

Your game won’t launch yet, because you’re referencing two empty files, and you call functions that don’t yet exist and use variables that never get set. You fix that in the next section.

Switching Modes

A menu screen needs, at the very least, a few menu selections. It also needs to set the STATE token so that the main loop knows the current game state.

In previous exercises, you have treated all variables equally, but in fact, there are broadly two different kinds of variables: local variables and global variables. A local variable only needs to be used within one Lua file (in other languages, a class), but a global variable can be used across files.

In context of this project, the STATE variable must be a global variable because it is set by either the menu or game, and then is sent back to main for use. Something local to only the menu can be a local variable because no other file in this project ever draws a menu.

Pragmatically, all variables can be global; however, it’s better to differentiate when possible so that your application can manage its memory more effectively.

This code includes a few vital elements: it sets the STATE global variable so that main.lua knows the game state, and it creates the .activate function as a gateway into the menu from the main loop. It also sets up the menu entries.

In this code, you use a for loop to cycle through the number of entries in the menu. For each iteration of the loop, LÖVE prints the corresponding menu entry as defined at the top of the file.

Since the menu is the first and only thing invoked by main.lua, you can now launch your application now to see what you have so far.

The first problem you are likely to notice is that there’s no way to select any of the menu entries. One of the many benefits of LÖVE is its keypressed function , which is perfect for game and menu navigation (this is discussed in the next section).

First, you may as well put in some basic code for the game screen, so that once the menu is operational, you can tell the difference between the menu screen and the game world.

You can’t get there yet, but at least it exists, and with a background color set, you’ll know it when you see it.

Menu Selection

For the player, a visual cue is useful. There are several ways to implement a selection marker for a text menu, but for now, just draw a simple character next to the active entry by checking the value of the selection variable. Of course, at this point, the selection variable can only be 1 because nothing has changed yet in your code; but that won’t be true for much longer.

Update your menu.draw() function so it matches this:

You can launch the game to see the > marker on the first selection.

When a user presses a key on the keyboard, the computer receives a keycode signal. This is known as an input event. Depending on your language and keyboard layout, your operating system translates keycodes to specific letters, numbers, or characters. That’s built into any operating system, and it’s why you can interact with your computer.

The only reason a specific application reacts to a number or character or symbol, however, is because it is programmed to do something when a keypress event is received. LÖVE features the keypressed() function , which listens for keypress events and lets you define what should happen with each keypress event.

For menu navigation, you must define what the menu must do when it receives an Up arrow or a Down arrow event. These events both toggle the active selection, which is currently set to 1 by default. Since the selection variable is set to 1 when the application starts, the active selection is the first in the list. To make the active selection second on the list, the selection variable must be incremented when the Down arrow is pressed, and decremented when the Up arrow is pressed. If you’re good with math, you might detect an exception to this rule already; if not, you’ll discover it soon.

In addition to moving the selection designator around, the menu should respond when the Return key is pressed.

It’s a common convention in games to use the Esc key to call and dismiss a menu screen, so pressing the Esc key goes back to the game screen.

To differentiate when a user is starting a new game and resuming a saved game, the preceding code sample invents some nonexistent functions, such as game.new() and game.load(). It’s alright that these don’t work yet, because you’ll create them later.

If you test the application, you will probably notice that the application crashes if you try to move up from the top selection or down from the bottom selection. If you’re not new to programming, you probably predicted this issue, but if you’re new to all of this, then it’s useful to witness the crash and then to follow the logic and math that causes it.

The selection starts out as 1. Pressing the Down arrow increments selection to 2, then 3, 4, and 5. All of these numbers correspond to the existing five menu entries. If selection gets incremented once more to 6, however, LÖVE doesn’t know what to do because there is no sixth menu entry next to which it can draw the > selection symbol.

To solve this bug, you must catch when selection would normally become either 0 or 6 and impose an existing number. A user would expect a menu selection to wrap: when you scroll past the bottom of a list, the active selection becomes the top of the list.

To do the math to fix a selection that goes out of bounds, create a new function called wrap that requires one argument: the value of selection plus or minus 1, depending on which key was pressed. If that value would result in something less than 1 or higher than menmax, then reset selection to the lowest or highest value, as appropriate, and hand it back to the process that called the function. To save lazy programmers from too much typing, selection is renamed sel for use within this function.

Try your application once more. Scroll through the menu, start a new game, return to the menu, and then quit. The first milestone has been reached: you have the framework that you need for a game and a menu system.

Git

As you have seen by now, there are times during development when an application just can’t be launched, even for testing. Sometimes your code is incomplete, or sometimes you make some choices that render your project unusable. These are all important stages of development, and since it’s through experimentation that most of the really good stuff gets done, it’s not something you ever want to discourage in yourself. And yet, there’s something significant about reaching an important milestone like the one you have just reached. Your project is in a pretty good state right now. Even though there’s really not much to it, your current codebase serves as a solid foundation upon which the rest of the project can be built.

Furthermore, your project is divided into three files at the moment. If you had an assistant, you could save a lot of time by working on the game part and letting your assistant programmer work on the menu part. You’d probably both need access to main.lua, though, so eventually you’d have to come together and figure out what you each added or changed in each file, and then merge your combined work.

In the world of professional software development, this is known as version control, and the most popular version control system right now is Git.

Git was developed when Linus Torvalds and his fellow Linux kernel developers were ejected from a proprietary version control system, and suddenly found that they needed a way to manage lots of changes to hundreds of files between hundreds of developers. The lesson was clear: open source gives the users control of their own data and their own destiny. So, Torvalds developed his own system for managing code. Since then, Git is synonymous with software development. It’s used by Linux, a huge portion of open source projects, Microsoft, Apple, and movie studios (i.e., Weta Digital, Sony, and Industrial Light & Magic), and it’s the backbone of popular coding sites like GitLab and GitHub.

Git has no effect on your application; it’s purely a tracking tool that enables you to maintain fluid backups and different development paths in one place. With Git, you get a running history of your project, with snapshots (called commits in Git terminology) of important moments in each file’s life. This gives you the ability to (figuratively) go back in time and reverse mistakes you made along the way.

Learning Git is more a journey than a destination, but the sooner you start, the better. You already installed Git back when you installed Geany and several other tools, so it’s ready to use.

Adding Files

Git tracking is enabled for your project now, but Git only tracks what you tell it to track. You can see which files are (or are not) being tracked.

$ git status

On branch master

Initial commit

Untracked files:

  (use "git add <file>..." to include in what will be committed)

        deck.ini

        font/

        game.lua

        img/

        main.lua

        menu.lua

nothing added to commit but untracked files present (use "git add" to track)

In git-cola, untracked files are listed in the Status pane.

All files in the directory are currently untracked Figure 7-2. Since they’re all in a healthy state (your game launches and you have code that you want to keep), add them all to Git using the wildcard character * as shorthand for everything here.

$ git add *

$ git status

On branch master

Initial commit

Changes to be committed:

  (use "git rm --cached <file>..." to unstage)

        new file:   deck.ini

        new file:   font/arkham.ttf

        new file:   game.lua

        new file:   img/red-10-wizard.png

        new file:   main.lua

        new file:   menu.lua

Now the files have been added to a special staging area. They’ve been marked for tracking, but you have yet to actually commit them. You can think of a Git commit as a sort of snapshot of the current state of a file. Commit everything in your staging area now.

$ git commit --message "game can switch between menu and game screens"

[master (root-commit) 99dd051] game launches and switches betwe[...]

 6 files changed, 46 insertions(+)

 create mode 100644 deck.ini

 create mode 100644 font/arkham.ttf

 create mode 100644 game.lua

 create mode 100644 img/red-10-wizard.png

 [...]

If you prefer to work within git-cola, add files by selecting them in the Status pane, and then right-click and select Stage Selected. This stages those files to be committed.

To commit all staged files, enter a commit message in the Commit pane, and then click the Commit button Figure 7-3.

With your files committed, you can continue to develop with a peace of mind, knowing that if you ever get too far off track, you can always return to this point in your project’s history.

Card Table

In your Blackjack game, each card was its own Lua table, with a unique self.suit, self.value, and self.img all its own, which you were able to call from your main script when you needed to calculate the total score or when you needed to tell LÖVE which image to draw on the screen.

This is a slightly more complex version of your Blackjack card table. Of course, none of these values mean anything yet. They’re just empty fields that need to be populated by data you feed into the table when generating a new card.

There are still a few more fields needed. First of all, each card needs an image. This would be identical to your Blackjack game were in not for the addition of the Joker to this deck. In fact, you could render the Joker and back images basically the same as all the other cards by naming their image files as you named the face cards (0-joker.png, 0-back.png) but then you need a copy of each in the red and black directories, which is redundant data. There’s nothing wrong, necessarily, with that approach, but it wouldn’t scale were this a much larger game with really big assets, while allowing for deviations in the code is cheap, and worthwhile.

And finally, it’s always important to be able to ascertain an object’s size. A game object’s size is vital for collision detection: it’s how you tell where to draw the next object without drawing on top of the previous one, and it’s how you detect whether the player has clicked one object or another.

Lua has functions specifically for the task of determining image size, but your program is going to scale your graphics down (as in the Blackjack game) so that the screen size can be changed. Technically, you could use Lua’s size detection and multiply the result by your scale. Or, you can enter the size value as part of each card. Both do the same thing, but since the size of objects is used frequently, it’s “cheaper” to do the calculation once and enter the value as a variable than to do the math every time a user interacts with the screen.

The value of the scale variable has yet to be created, but as long as it is defined before card.lua is actually used, there won’t be a problem.

Game State

Currently, entering the game state of your application sets the active STATE to game, which in turn causes the main loop to invoke your custom game.draw() function, which renders a colored background. This all happens in the game.lua file, so open that in Geany so you can make some changes.

The game.lua file is the logical place to define important game-related variables, because it’s within this file that the mechanics and game data tracking happens.

Based on both the card.lua file and your previous experience with your Blackjack game, you can anticipate a few important variables that can be defined whether or not your code has a need for them yet.

Start by defining some environment variables. Eventually, LÖVE needs to know who is running the game so that it can store save files. Lua provides the os.getenv('HOME') function to discover a user’s home directory. In Linux, this is a folder in a directory literally called home, whereas on the Mac, it is a folder within the Users directory, and on Windows it is a location usually on the C drive. The point is, you don’t have to worry about where a user keeps their personal data files, because Lua finds that out for you.

Another thing that changes from system to system is the separator character used to delimit directories from one another. For instance, on the Raspberry Pi, as on any Linux or Mac system, the separator character is a forward slash. The location to any file or folder on the system can be predictably written out in plain text; for example, /home/pi/battlejack/img/joker.png. On Windows, however, the separator character is traditionally a backslash: C:\\My Documents\example\img\joker.png. Lua can detect this for you, too, with its package.config function.

Next, your game needs several tables to serve as decks of cards in various states of play. Create tables called hand and horde to serve as the player and AI active hands, tables called deck and ai to serve as shuffled draw decks for player and AI, a table called back containing the backside of the player and AI decks to serve as the clickable item when a player wants to draw a new card, and a grab table to serve as a staging area for cards a player is about to send into battle.

Finally, create a winner variable to mark whether or not a winner has been found. By default, set it to nil. Pull card data from your configuration file into a variable called set using the inifile function.

The first logical place to call this function is any time a new game begins. The function takes the width of the screen, which is a global variable established in main.lua, and the native size of a card graphic. If you’ve made your own graphics for this game, then you must determine the size of your graphic yourself (you can find it in GIMP, if you’re not sure). The example graphics included with the source code of this book are 790 pixels wide.

The game.scaler() function assumes that approximately six cards should fit horizontally across the screen (WIDE/6). This calculation renders the width of each card in pixels, which itself is important enough to keep in a global variable called slot, which keeps cards from overlapping when being drawn. The slot value divided by the unscaled size of a card provides a decimal number by which all cards may be scaled to fit six across the screen.

With these functions and variables in place, you can at least draw the most rudimentary of cards screen.

The first card you generate is the “top” of the draw deck for the player. Since it’s the back of a card, it has no color or value, so you pass in the "c" and "v" dummy values, which the card library ignores once it sees that the card being generated is of the back type. The card’s X position is set at the left plus the value of pad, a variable set in main.lua to provide padding around the edges of the screen. The card’s Y position is calculated from the height of the screen.

The card generated is added to the back table. Then the same variable is used to generate a second card to represent the AI’s draw deck, using new X and Y values so that the card’s placement is in the top right (across the virtual table) instead of the bottom left. This second card is also added to the back table.

Finally, a proper tabletop is defined. Currently, the game mode only renders a flat color in the background, but Battlejack deserves something more exciting. Rendering an array based on a texture or pattern is pretty common for a game engine, and LÖVE provides the love.graphics.newQuad function to map tiles across a given space. Specifically, this code defines a quad of the width and height of the screen, with tiles sized 150×150 pixels (which happens to be the size of the tile pattern included with the source code of this book). The tile is defined using the d variable to ensure compatibility with whatever system the game is running on, and the tile mode is set to wrap seamlessly across all available space.

Of course, nothing is actually drawn unless it appears in the love.draw() function, which in this program is aliased to the draw() function of whatever STATE the user is in. For game play, the user is in the game state, so you must add your draw commands to game.draw().

After setting the color to white to ensure that everything is drawn at 100% opacity, the tiles are drawn to create the tabletop. Order is important here, so the tabletop must be drawn before cards are drawn, or else the cards will be drawn “under” the table.

To draw the two card decks, you populate a temporary card variable with one object from the back table and use that data to draw the graphic. Since the back table contains relatively little data, manually pulling out an entry is simple (the contents of the other tables that you have created are far more dynamic and require for loops).

Launch your game to verify that all of your code is correct so far. Correct any errors and make adjustments as needed, and then it’s time to set up the deck creation functions.

Deck Building

Like any card game, a key element of Battlejack is the random nature of the game elements. Functionally, that means your program needs a reliable set of methods that you can use repeatedly to create freshly randomized decks of cards based on the card definitions you have set forth in your card definition INI file.

To create decks for Battlejack, you must fill two distinct tables with card definitions: one filled with red cards and the other with black cards. However, it’s part of the game design that there are six black “mole” cards inserted into the player deck, so six cards must be stolen from one deck and inserted into the other. Additionally, a Joker must be placed in each deck but not accidentally stolen when the black “mole” cards are inserted into the player deck. And finally, each deck must be shuffled to ensure unpredictability.

In your game.lua file, create four new functions: game.setsplit(), game.mole(), game.joker(), and game.shuffle().

This code uses a for loop to repeat the same action for as many times (n) as you proscribe when calling the function. The action that it takes is another for loop that iterates over the set variable, which contains the contents of the card section of your INI file, assigns a color to the card definition, and then places the card definition into whatever table you have told it to build into.

Next, you need to steal six cards from the black deck. If you do that immediately after building the decks, however, the same black cards are stolen every time because no randomness has been introduced into the decks. For this reason, you need to develop the shuffle method first.

Launch the game and look at the terminal to see a text list of the cards in each deck.

The next step is to transform all of this setup work into a playable game.

Playable Cards

Playing Battlejack is a three-step process: the user must draw a card, the user must select cards to use in an attack, and then the user must choose a target for an attack. That means your code needs functions to visually produce a card into the player’s hand, to mark cards as selected, and finally, to resolve a battle.

Create a new function called game.cardgen() that accepts a deck as an argument. This function’s job is to parse the next available card definition from a deck to use your card library to create a card object with all the necessary attributes (image, width, height, position, and so on), and to add it to the table representing the player’s hand or the AI horde.

As cards are drawn from a deck, they must be removed from that deck or else the same card would be drawn for eternity. For that reason, the deck table becomes populated with nil entries as the game progresses, so your function must be programmed to skip over empty entries.

Notice that this function is a little different than any of the functions you’ve written so far; it returns either true or false, depending on the results of its calculation. This is a convenience that lets you use the result of a call to the function as a sort of switch; if it returns false, then you know that there’s no reason to continue analyzing a click.

Launch the game and draw some cards.

Battle

Sending cards into battle is also all about click detection. Since the user can select more than one card to combat an enemy card, you must mark selected cards as selected until an enemy target is clicked. You already have a table called grab, and so it serves as a kind of extension of the player’s hand, containing any cards that have been clicked in preparation for battle. Of course, clicking an already grabbed card causes it to be deselected.

Now that you have the ability to detect whether a card has been grabbed yet, you can process mouse clicks. For the action of grabbing a card and adding it to the grab table, you can use a the LÖVE mousepressed function, simply to avoid overloading the mousereleased function with too many checks.

Launch the game and try selecting some cards from your hand.

Visual Effects

Selecting cards for battle should be an exciting prospect in the game. After all, it’s the central mechanic; without this, the game is basically Blackjack. While elevating the card on the table is pragmatically effective, it’s not very flashy.

One way to “sweeten” the act of selecting cards for battle is to add a simple visual effect. You can imagine, for instance, that in a fantasy battle, warriors chosen to go out onto the front line might glow with a magical aura. In video game design terms, that translates to a particle effect.

Particle effects are relatively expensive, so you don’t want to over-use them, especially on a relatively weak platform like the Pi. But as an indicator that something is “hot” and ready for battle, it’s justified.

To set up a particle effect, you must point LÖVE to a graphic that is to be used as the actual particles. This particle serves as the raw material for the effect, and there are a few important attributes to set to keep the effect from devouring your processor and spreading particles all over the screen.

Since the particle graphic itself is quite small, this code uses a while loop to place a particle seed along the top edge of any card in the grab table.

Launch your game again and select some cards for battle to see the effect Figure 8-1.

Resolving Conflict

To settle the outcome of a card battle, you must compare the player’s cards selected for battle against the AI card being targeted. This happens only if 1 or more cards is present in the grab table, and only when a card in the AI horde has been clicked.

There’s also one important exception to any attack: if the card is a Joker, then all cards in the horde are wiped out.

If you launch your game and draw a few cards, and then press Esc to bring up the menu, and then start a new game, you find that a new game is now, finally, truly a new game.

Resolving battle is still incomplete. Aside from the blast function, it mostly happens within the mousereleased function.

Order is important now. Currently, your mousereleased function checks whether the mouse button is button 1 and then takes action. But the button is always button 1, so new qualifiers are required. For instance, if the mouse button is 1 and there are cards currently grabbed, then check to see if it was a card in the horde table that was clicked. If so, then it’s time to battle. If not, then check that the click was button 1 and that a card in the back table was clicked, and draw a card.

In addition to removing the attacked horde cards, the player’s resources require adjustment. The cards used in the attack are also removed from the player hand. However, this must only happen if the attack is successful, since a player could attempt to attack without enough power to actually remove cards from the field. You must decide through play testing whether a successful attack must be greater than a black card, or if a card that is equal to or greater than a black card is victorious. The sample code here allows for cards both equal in value and greater in value to defeat the opponent.

Launch your game and take out the opposition. There’s no win or lose condition yet, and there may be a few crashes, but the basic mechanic and game play is complete. Your game is now firmly in alpha.

Git Commit

A lot of progress has been made up to this point, so it makes sense to commit the changes to Git, just in case changes you make later render the game unplayable by mistake.

Open git-cola and look in the Status pane to see which files you have changed but not yet committed. A Git commit is like a snapshot, so even though you have committed an earlier version of a file, you must take a new snapshot of any changes since the original commit.

In git-cola, right-click the updated files in the Status pane and select “Stage selected”.

In the future, you should commit code whenever you make a significant change that has not broken your codebase. It’s a good habit to get into, and in case of disaster, it can save you hours of work.

Leveling Up

That balances the game, and catching it early prevents you from having to write the code associated with the AI playing a Joker card. If you decide to add it back later because you want the extra challenge, you can use the game.blast function when the player draws a Joker card, and you can write the necessary code.

Balancing a game isn’t just crippling the opposition, but also bolstering the player. The human player in Battlejack is up against a relentless march of cards that are drawn but never spent. Tipping the scales in the player’s favor has two important effects: it makes the player feel more powerful as they achieve victories, and it assures the player that all their hard work is paying off.

The level can be printed on screen using the usual love.graphics.printf function, which you’ve already used in both Blackjack and Battlejack. However, the player doesn’t really need a constant reminder of what level they’re on, so it’s a good idea to create some marker variable to signal the level text to disappear. You could use the Lua os.clock function to measure the passage of time, but in a turn-based game like Battlejack, time is more or less relative compared to when the player clicks, so it’s more meaningful to use clicks as a measure of “time” than actual time.

Each mouse release, check to see whether a winner has been declared and either increment the level or start a new round. This check must be performed before anything else so that as soon as there’s a valid winner, game play stops.

This code refers to a new function that doesn’t exist yet: game.sleep. This function causes the game to “sleep” to ensure that the player isn’t missing important information. Without a brief pause, the game would go from “You win” to “Level 1” messages in the blink of an eye.

You can play the game now to see the latest improvements. Remember to commit your changes with Git, as long as everything works as expected.

Powerup

The game increases the player’s levels but so far doesn’t actually reward them with anything substantial. Now that the level mechanism is in place, you can use it to add new cards into the player’s deck any time they gain a level. This gives the player the feeling of growing power, and a sense of accomplishment.

First, you need some way to alert the player of their accomplishment. You could print a message on the game screen, but for something as significant as an hard-earned powerup, a special message screen seems more important and means less clutter in the game play area.

On the message screen, you can display the new cards added to the deck after each victory. It can do double duty as an alert message when the player draws a black card from their own deck, underscoring that their luck has changed for the worst.

You need a few new tables and variables for this mechanism. Since there are sets of cards involved, you need new tables, earn for earned bonuses and up for powerups. Since the winner variable is set back to nil with each new game, you need a new persistent variable called lastwon to represent whether the player won the last round or not.

You also need to create a new file called msg.lua to serve as your message screen.

This introduces two new variables: an earncard and an upcard. These variables don’t exist yet, but you will create them before calling the new msg screen. They will contain the card or cards that have been generated from either a victory or an unfortunate hand.

You also need a method for inserting new cards into the player’s deck. You have already created a method to insert a Joker card into a deck, and while it seemed like a sensible function at the time, you can see now that it could be expanded into a generic method for inserting any card type into a deck. An additional argument is required so that the function can differentiate between a normal card and a bonus or powerup card, and the function name should change to better reflect its new generic purpose.

And then add the bonus and powerup cards to the deck. These cards are only added after level 0 has been won, and the player is only alerted to new additions that have been won from the previous victory. Once the cards have been earned, they are silently added to the deck. This means that a message screen is only shown when lastwon is set to 1. It also means that which cards are added can be controlled according to the current value of the level variable. That is, starting at level 1, all cards in the earn and up tables, from 1 to 1, are added. At level 2, all cards from 1 to 2 are added. At level 3, all cards from 1 to 3 are added, and so on. When you have no further cards to add, the limit is capped to the highest number of cards defined in the earn and up sets of deck.ini.

The other purpose for the message screen is to alert the player when a traitor has been discovered among their ranks, or in mechanical terms, they have drawn a black card from their own red deck.

This requires an if statement in the game.mousereleased function , when a new card is drawn from the player deck. When a card is generated, you assign it to the card variable, and since card generation uses your own card.lua code, you know that you can look at its color by looking at card.color. If the color is black, then you can trigger a few actions. First, a message should be given to the player, telling them of the bad news. Then, the card must be placed into the AI hand and removed from its default destination of the player’s hand.

Try playing a few rounds to see how the new bonus and powerup cards perform.

Powerup Double Draw

Now that the game is more complex and more complete, play testing is a little difficult. You have to play longer, and press more keys or click more things to find the bugs. Don’t let that deter you, though; there are bugs to fix yet.

One notably missing feature is the way powerup cards are treated. First of all, they’re counting toward the total of the player’s hand, but they’re meant to be powerups, not just another card. Contrariwise, the powerup cards count as one card draw, meaning that in a sense they penalize the player because the game’s most urgent mechanic is the need for more cards. If a “powerup” card takes up a turn but adds nothing to the player’s points stash, then the player is arguably better off without the powerup.

The way to make a powerup feel like a powerup is to give the player a second card any time a powerup card is drawn. That way, a powerup card adds temporary ammunition to the player’s hand but doesn’t cost them any points toward their score.

The logic here is fairly simple, but for the one exception when a player draws a bonus card and then a black card. The code first checks for a bonus card. If the card is a bonus card, then a new card is immediately drawn. If that card is a black card, then that card is silently moved into the AI’s hand and removed from the player’s hand. This is done without a message to avoid too many alerts. You can change this, if you prefer verbosity, but during play testing pay close attention to how often the game is interrupted so that you don’t annoy your players.

Font and UI Consistency

There’s another bug hidden in the code that you might not have discovered yet. Because the game uses two different fonts and font sizes, going back to the menu screen after a game has started results in unreadable menu options. The fix for this is to monitor font settings closely. Specifically, you can enforce the “default” font for each game state in the activate functions.

This resolves any inconsistencies in the user interface.

Garbage Collection

The final bug to squash is a rather serious crash that you only see after several rounds. The crash renders an out of memory error, which is caused by the vast amounts of data being moved in and out of this game. This is a niche problem caused by this type of game; usually, Lua is fully capable of managing memory, but with all the cards and graphics that Battlejack cycles through, it’s difficult for Lua to know what information we expect to have access to.

Part of memory management is called garbage collection. Most modern programming languages have it built in, although some low-level languages like C and C++ do not. Although built upon C, Lua has automated garbage collection but allows for manual memory management when needed.

Garbage collection, as its name suggests, is a signal you can send to Lua to assure it that it’s safe to cycle through old variables and clear them from memory. There are a few places that you can expect this to be safe: at the beginning of a new game, there’s certainly no reason to keep information from previous rounds, and when the player uses the Joker card, which only happens once per round, it can be safely assumed that very old data is no longer required. This is mostly guess work, of course; you have no way of monitoring exactly what Lua is keeping track of in the recesses of its memory allotment, but the Lua collectgarbage() function is a trigger for Lua to run a garbage collection cycle sooner than its default schedule. You’re still leaving it up to Lua to decide what to remove from memory, and Lua is smart enough to know that, for instance, the lastwon variable is still important and must not be erased, while the structure of the previous decks are safe to discard.

For most Lua programs, you won’t run into memory management problems. However, if you do, you now know how to prompt Lua to review its resources and clear out unused data.

Homework

Fullscreen

In its current state, your Battlejack code requires some changes to account for a sudden change in game window size. If you’re not a fan of math, many of the changes will seem a little mysterious, but the most important concept is the use of relative measurements. You must base the size of game elements on the width and height of the user’s current window size, but in order to do that you must ask the user’s system what that size is. In practice, this often means that you have to adjust the location of elements to account for a potential change in empty (or “negative”) space.

Forces the window to update its mode settings.

With these functions, you can always determine whether your game screen is fullscreen or windowed, and extract the dimensions of the space you have available.

The fullscreen toggle selection in menu.lua is option 3 (it’s the third selection in the menu entries array). Currently, there’s a placeholder there: it returns true, which in this context is Lua shorthand for not an error.

At the end of this code, a new variable called fsupdated is created and set to 1. This variable serves as a flag signaling that the window mode has been changed, which in turn lets you write code in game.lua that only runs when a window mode change is made.

For the game to resize, several adjustments are required. Some game elements in Battlejack have been purposefully misconfigured in earlier chapters so that you can see the difference between a reasonable first attempt and, ultimately, the correct code. The important thing to understand is that when scaling a game, you must think about many different factors, and these factors may be unique to your game, depending on the assets you use. The examples in this section are specific to Battlejack, but the principles of using variables for calculations, detecting changes in screen settings, and knowing what can and cannot scale, are broadly applicable no matter what your game is like.

Open game.lua for editing. The various states of the game are defined by the variable STATE. Any time a user enters game mode, it is by triggering the game.activate function , whether by selecting New game or pressing Esc. That means that any time a user is in the menu screen, the game.activate function is the entry point to the game, and the ideal place to detect whether the screen size has changed.

If the fsupdated variable is 1, this function now your game.scaler function to recalculate a new scale for each card relative to the size of the screen.

Additionally, the function cycles through each of the hand, horde, back, and grab decks and applies the new size to the cards in play.

Finally, it sets the fsupdated to 0 so that no further size updates are triggered until the user changes the screen settings again.

Launch the game and change the screen setting now. Take note of what scales properly and what does not. Spend some time thinking about the problems you see, and try to predict what function contains the problem code.

Usability

One point of confusion you might detect after testing is that there’s no explicit way to return to the game from the menu screen. On one hand, it’s reasonable to expect that since the user had to press Esc to get to the menu screen in the first place, the user can probably guess that pressing Esc again returns to the game. On the other hand, making the user think too hard about an interface can be frustrating, so there’s no reason to leave it up to chance.

Add a menu option to return to a game already in progress. Phrases like “Exit menu” and “Resume game” can be taken many different ways: exiting the menu could also mean exiting the application, and resuming a game could mean loading a previously saved game. A good interface uses the clearest possible language, which in this case is simply “Return to game”.

Scaling Adjustments

Generally, measurements that need to change dynamically are more predictable when they are based on a single point of authority. All the scaling problems you are witnessing in your test are bugs in the game.draw function, where there is heavy reliance on card.x and card.y values. Since there are several arrays defining cards, the values stored in various card values are unpredictable. There is also some dependence on the pad value, which defines a margin around the edges of the screen, but it changes depending on the screen size. And finally, while the slot variable provides the width of the cards, there’s no value at all for the height of cards in relation to the screen size.

In summary, the layout of a dynamically resizable game must be based on the size of its parent window.

Notice that the new method of placing the glow and the deck relies exclusively on values derived from the screen size, and not at all on card-specific variables. As usual in programming, there are actually several different ways to arrive at the same solution, but this is the most efficient; an alternative is to leave the code unchanged, and use screen size calculations to update the important card variables, but that requires updating values in several places, whereas the screen size calculations are made once and then can be used many times. Any time you have the opportunity to require the computer to do less work, you are optimizing your code, and that’s always a good thing.

The 72 in each line is the font size of the onscreen text. By now, you’re hopefully suspicious of any hard coded value, so you’re probably wondering whether even this value ought to become relative. In fact, you could make the font size more dynamic by either using some calculation to determine the optimal size depending on screen size, or you could create an array of font sizes for specific ranges of screen sizes. As screen sizes vary wildly in sizes, from mobile phones to 4k monitors, this is a worthwhile exercise, but one left for you to manage on your own.

All of these changes have affected the grab code. When a player selects a card, it’s added to the grab array, but it’s also moved up the screen and given a particle effect, very precisely placed just under its top border.

Notice that the particle effect line uses 32/2 instead of the old pad/3 calculation to position the particle image below the card’s top border. This is dependent on the particle image, so if you have changed or plan on changing the particle seed image, you must adjust the value 32 to match the height of your custom image. To make this kind of change even easier, you could create a variable at the top of the file to define the height of the particle image, and then use that variable in this code. That way, all the values you need to change are easily found at the very top of your file, saving you from having to search through your code for all the hard coded values requiring updates. Again, this exercise is left to you to do on your own time.

Try playing the game again to experience dynamic switching of screen sizes. Make adjustments and changes as required, and remember to commit your changes to Git once satisfied.

Save States

Save states for games are a nice convenience for users, and generally expected in modern gaming. Luckily, there’s a wide range in what users accept for save states. Some games save every last detail of a game so that when you resume a saved game, it’s as if you had only paused the game. Others save less information, placing you back at a waypoint or checkpoint. Still others only save your level and nothing else.

Considering that Battlejack falls within the puzzle or card game genre, saving just the player’s level would probably be acceptable by most users. However, Lua’s heavy use of tables makes saving and restoring complex data easy, so Battlejack can have full save state support.

There are two bundles of information that need to be saved: there’s the player information and the game state. Player information is anything that remains true regardless of a game round, such as whether or not the game is in fullscreen mode, and what level the player has reached. Game information is anything specific to the current round, such as the contents of the draw decks and the player’s hands.

You will use two different methods of saving this information, and the information is saved to two separate locations on the user’s drive. Player information is generally referred to as the user configuration and the game information is game data or just data.

One of the most common errors when saving and loading data in an application’s code are missing files or directories. For instance, if you write Lua code to save a the file bar.conf in a directory called foo, if Lua can’t find the foo directory, then Lua crashes.

Lua has no way of knowing whether a file or a directory exists, so you must write a function for this. This is a low level operation that is usually the domain of the operating system, and as such Lua’s os function has some tools that can help solve this puzzle. Lua functions are documented on the Lua website ( www.lua.org/manual ) and also in the book Programming in Lua by Roberto Ierusalimschy (Lua.​org, 2016), the official Lua guide from the language creators.

While there is no function to determine whether a file or directory exists, the os.rename function requires that a file or directory exists in order to successfully rename it. It’s a little bit of a hack, but by invoking os.rename on a file path, you can parse its output to determine whether it was able to find a file or not.

User Configuration

This default location is not arbitrary. In the computer world, everyone benefits from standards. Standards are conventions that programmers mutually agree to follow in order to ensure compatibility. Most modern low-level computing standards are defined by the open source POSIX specification, while user-level specifications for Linux are defined by freedesktop.​org. Operating systems that are not open source often follow a combination of open standards and their own standards. You have the option of following one or the other, but since the open standards are available to all, this book follows those.

Freedesktop.​org defines two hidden directories in a user’s home for configuration and application data. The .config directory contains configuration data and .local/share contains application-specific data files.

The if statement that invokes saver.exists is a subroutine that ensures the destination for the save file exists. If it does not exist, the os.execute function runs the mkdir command on the operating system to create the directory. The mkdir command works on Linux, MacOS, BSD, and Windows.

The last line of the code block uses the inifile library to save the conf table to a file. It uses the io Lua module to create the file.

Game Data

Saving the game data is theoretically a simple matter of taking all the tables that contain game information and dumping their contents into a file. That’s a lot of code to write, and also potentially prone to error if a table is very complex. It’s also a common task, however, so a user on the lua-users.​org website created a handy script to save and load tables. This is the sort of script you might usually find with Luarocks, but it just happens that this script has never been entered into the Luarocks repository, so it just exists on the Internet.

Download the script from lua-users.org/wiki/SaveTableToFile or from the code included with this book. However you obtain it, save it in your project directory, in the local/share/lua/5.3/ folder, as table_save.lua.

Of course, if you only provide a filename, Lua would do exactly as it is told and save the files into your current directory , so you must interpret filename broadly to mean the path to the file you want to create.

Launch the game and start a round. Once you have drawn one or two cards, go to the menu screen. Save the game and then quit.

Loading a Save File

The inverse of saving a game is loading a game. This is a little more complex than the save process, because there is so much setup when starting a new game, which is “clobbered” by loading in existing data. Because loading a game replaces the game.new and game.setup functions when invoked, the loading process happens in the game.lua file.

First of all, you want to ensure that you’re facing a clean workspace when loading a saved game. Currently, the slate is cleaned by game.new, but if you move the cleanup code to its own function, then you can use it again in your loading code.

The next logical step would seem to be loading the game data, but first there’s another bit of code that usually only happens in game.new: generating a background.

Once the load process is finished, it calls game.activate to put the user back in the game.

Launch the game and load your saved game. Try this process a few times, and play through a few games. Take note of any errors or glitches you encounter.

Homework

The next chapter makes no further changes to the game code aside from adding sounds to the experience. That means the game is basically feature-complete, so any glitches or unoptimized code you find are permanent unless you change it.

Remember to commit your changes to Git to preserve snapshots of your progress.

Finding Audio

As with any game asset, the first problem with adding sound effects to your game is that you need sound effects. Of course, open culture on the Internet has a few potential solutions, and so does your Raspberry Pi, if you’re up for some manual labor.

The website freesound.​org is a treasure trove of sound effects. Search for terms like level up, power up, ambient music, game, and so on, to rummage through thousands of professional sound effects that are free to use. The licensing of each sound can differ, so look at the requirements set by the creator; some require attribution, some forbid using their work in commercial products, and others require nothing.

There are other websites loaded with sounds, but you don't have to limit yourself to reusing other people’s work. You can create your own high-quality sounds on your Raspberry Pi with Linux Multimedia Studio, better known as LMMS.

LMMS

LMMS is a music production suite available for free on your Raspberry Pi. Whether or not you call yourself a musician, LMMS makes it easy to lay down a beat, synthesize new sounds, sample, loop, distort, enhance, and mix. LMMS comes with ready-to-use instruments, presets, and samples, making it one of the easiest music applications on any platform to get started on.

It takes a while for the full package to install, since there are so many synths and effects bundled with it, so be patient. Once installed, launch LMMS from the application menu.

Whatever you make in LMMS ends up in the Song Editor window. This is where you sequence, or schedule, sounds. If you are using LMMS to create sound effects, then everything you sequence should happen immediately in the left-most block. If you are using LMMS to make background music for your game, then the sounds happen gradually, over several blocks from left to right.

By default, the Song editor (see Figure 11-1) has four channels (triple oscillator, sample track, beat/bassline, automation) already populated, but these are only example tracks. As you create sounds, you add your own.

On the far left of the LMMS window are vertical tabs. When clicked, each tab opens a panel. Click the star icon tab for a Presets panel (see Figure 11-2) containing sounds and synthesizers that you can use to create your sound effects and music bed. More can be found in the musical note tab.

Click and hold some of the sounds to get a feel for what’s available.

Building a Sound Effect

Once you find a sound that you like, drag the sound into the left panel of the Song editor. This creates a new track in the Song editor, which is the one that you work in to create your sound effect.

This example uses Presets ➤ ZynAddSubFX ➤ Fantasy ➤ 0037-ImpossibleDream5.xlz.

In the Song editor, double-click the first black square in the ImpossibleDream5 track. This opens the Piano Roll editor (see Figure 11-3). As the name implies, this is the digital equivalent to the rolls used in old-fashioned player pianos. Notes are entered into the matrix of the roll so that they are triggered automatically as your song plays.

Since you’re only designing a sound effect, keep your “song” (such as it is) under 2 or 3 seconds. This example creates a sound effect for messages announcing that new cards have been added to the player’s deck, so the mood is happy and empowering.

The important buttons in the Piano Roll editor are the pencil and the eraser. The pencil enters new notes into the matrix, while the eraser removes them. You can hear (but not enter) notes by pressing the keys of the keyboard along the left side of the window.

If you’re unfamiliar with making music, don’t be afraid to experiment. Discover the wonders of a well-constructed arpeggio, or the raw thrill of a power chord. There’s no wrong way to design sound effects. If something sounds good to you, then use it.

When you’re happy with your first sound effect, go to the File menu and select Export.

In the Export window (see Figure 11-4), navigate to the snd folder in your project directory. At the bottom of the Export window, set Files of type to Compressed OGG-File (*.ogg). This format is common in the game industry because it is an open source format that renders a very small file size, meaning your sound files don’t result in an impossibly large game package once you’re ready to distribute. Name the file powerup.ogg and click Save.

In the Export project window that appears, keep the default settings and click the Start button.

Repeat this process for each sound effect that you want to create. So that you only have one LMMS file per project, you can use the same Song editor for each sound effect. Just mute the tracks that you’re finished with as you go. The Mute button for each track is the green light on the left end of the Song Editor track label, as in shown in Figure 11-5.

As you work, be sure to save your LMMS project. By default, you are prompted to save into a lmms folder in your home directory. This is acceptable, since you won’t be distributing the LMMS project along with your game. The sound effect exports, however, must always be saved into the snd folder in your Battlejack project directory.

Listening to Your Effects

To hear your sound effects as they will play in your game, navigate to your snd directory on your desktop and click the .ogg file that you want to hear. The default music player, called Sayonara (see Figure 11-6), opens with that file as the sole item in a playlist in the left panel.

Adjusting Export Length

Depending on your aesthetic, some sounds that you use may have a long “tail,” meaning that they echo for a few seconds after the notes themselves have ended. The synth preset ImpossibleDream5 is an example of such an effect, and if you listen to the file in Sayonara, you can hear that the file ends before the sounds fade.

To fix this, return to LMMS. Mute any of the tracks that you don’t need, and unmute the one that you do. Play the track and watch the timer in the top left of the LMMS window while listening for the sound to fade. It doesn’t need to fade out completely, especially if you intend to play background music during the game. When the sound is mostly faded, take a mental note of how many seconds have elapsed.

Stop playback and move the playhead in the Song editor to the position, in seconds, when the sound faded. With a sound clip using ImpossibleDream5 notes that last about 2.5 seconds, you might position the playhead at 10 seconds.

Finally, click the black grid boxes between the sound clip and the playhead (see Figure 11-7). This marks those squares as occupied with sound, even though there are no notes being played.

Export the track again and play it in Sayonara for quality assurance.

Creating Music

Making music for your game is basically the same process as making sound effects, only longer. There’s plenty of Creative Commons and royalty-free music online, so you don’t have to compose your own game music. However, creating your own music for your game can be fun and rewarding.

Since Battlejack is just a battle card game, the music doesn’t need to be much more than a background soundscape, without too much activity or complexity to distract the player from the actual game. In fact, regardless of what kind of game you are composing for, the music you use must be capable of looping, since you can never predict just how long it will be needed.

Unlike most simple sound effects, music composition will probably require more than one track in your Song editor. The sample code included with this book includes two LMMS project files so that you can see how tracks and sound clips in a song fit together.

When you’re ready to export your music, use the same settings as you did for your sound effects, with one exception. In the Export project window (see Figure 11-8), select “Export as loop (remove end silence)” so that your music can be looped in LÖVE.

LMMS can’t guarantee that your music will loop seamlessly; designing seamless loop points is an art all its own, but you can experiment with ways to disguise loops that don’t work, or you can just incorporate a fade-out and fade-in so that the loop, while noticeable, is at least innocuous.

Sound Code

To add sounds to your game, you must create a variable for each sound file that you want to play, classifying it as either a static file for sound effects or a stream for background music. You use this variable to trigger the sound as needed.

The if statement establishes whether the message screen is displayed to announce a powerup or because a black card was drawn. If a black card was drawn, nothing is done for now, but if a powerup has been earned, then the powerup sound effect plays. Of course, if you have a sound effect for a traitor card, then you can trigger that sound in the else clause.

Background music is established in main.lua. It’s up to you whether you create separate music for the menu screen and the game, but in this example, the same music plays behind the music and the game.

For sound files greater than a few seconds, set the file type to stream so that the entire file isn’t loaded into memory.

Since the background music is meant to loop, the variable is also set to loop with the :setLooping(true) LÖVE function.

Go through the code of your game and add background music and sound effects for important events.

If you try to play your game, you may notice that all of your audio is badly distorted. This is a known issue and is easy to fix. You will fix it in the next section.

Fixing the Raspberry Pi Sound Settings

LÖVE uses a technology called OpenAL to play sound. OpenAL is a powerful audio driver providing head-related transfer function (HRTF), more commonly known as 3D audio. For this reason, it’s very popular for gaming. As you know, the Raspberry Pi is a low-powered computer, and not exactly known as a “gaming rig.” So when you attempt to play high-powered, specialized OpenAL audio through a mini-computer designed for everyday computer tasks, you experience distortion.

Save the file and close Geany.

Try playing the game now and you will find that all of your audio problems are solved.

This is good practice, since you can’t possibly predict what platform any given user will use to play your game.

Homework

What’s Roguelike?

The exact definition of roguelike is the topic of much debate within gamer culture, but generally it’s characterized as an exploration game, often set in a top-down dungeon or tomb in a fantasy setting. It emphasizes tactics, with combat being the central mechanic. There’s no story, and randomly generated levels and monster encounters are usually revealed little by little as the player progresses through the map. Furthermore, death is permanent, a frustrating tradition mitigated by the fact that there’s no win condition, and the next game will be completely different anyway.

The classic roguelike is Nethack, a very old game that uses ASCII characters to represent the hero, monsters, items, and the map itself (see Figure 12-1). More recent examples include Pokemon Mystery Dungeon, Pixel Dungeon, Diablo, Darkest Dungeon, and Runestone Keeper.

The roguelike genre is useful because it demonstrates how to translate the same mechanics from dice and card games into a character-driven video game. This chapter emphasizes how to translate what you have learned so far into a game that, on the surface, bears no resemblance to the example games you have created up to this point. There are fewer explanations of the Lua syntax than examples of how all the code you already know is capable of being used in ways that are new to you.

It Looks Good on Paper

As with Battlejack, the smartest thing you can do before writing any code at all is to interpret the game you want to make into a tangible system you can test. As it happens, dynamically generated dungeons for tabletop games have existed for years in the form of random tables. If you’ve never seen or used a random table, it’s worth looking at any Dungeons & Dragons (D&) Dungeon Master Guide as a study of game design. In the context of randomness, Dungeon Master Guides provide tables of various attributes for items that a player might find in an imaginary dungeon while playing this popular tabletop RPG. If a player finds an item, the Dungeon Master may roll dice and then refer to the table to mutually discover, along with the adventurer, what exactly it was that they found. For instance, a die roll of 11 on Table 98 means that the player has found a pair of Bracers of Defense, while a roll of 16 means the player has found Gauntlets of Ogre Power.

The same principle can be applied to the layout of the dungeon itself. For a paper-based example, visit. The system is simple: roll a 12-sided die (d12) for the subjective size of a room, then a d12 again for the general shape of the room, and then a d4 to discover the number of exits that exist in the room.

It’s easy to translate this into a digital Lua-based system, and it is easily extended to include all aspects of the game world; the number of monsters in a room, the amount of treasure, the presence of discarded weapons or shields or other gear, and so on.

Most elements of this game can be abstracted out of main.lua into their own tables. Start with the most basic element of a dungeon crawl: the rooms.

Assets

The source code for this example game includes the Underworld tile set by Poikilos and Redshrike on OpenGameArt.​org, a 32×32–pixel tile set laid out in spritesheets. You can use this set or you can make your own, but this example assumes that your sprites are in spritesheets rather than individual image files, because spritesheets are very common and you should know how to use them.

As you can tell from the requires list, you will create a custom library for each major element of your dungeon. This code also creates a table to store similar elements together, defines the tile size as specified by the spritesheet artist, and starts a random seed.

In the love.load function , two new variables are created. The sheet variable contains the main spritesheet, and skull contains the object that will serve as a projectile weapon (yes, the hero of this game throws magical flaming skulls at monsters).

So far, this is the same process you used to create the table texture in Battlejack.

Treasure

Images are each defined with the newQuad function . Each one extracts some portion of the sheet image. The syntax specifies the X and Y position of the image you want to “cut out” from the spritesheet. Since the spritesheet is laid out in columns and rows, all you have to do is count, starting at 0, and then multiply the result by the tile size. Since this is programming, you’re better off letting the computer do the multiplication for you, so the X and Y positions are defined with small equations, such as 6*t and 2*t.

The size of each image is always the same, so t,t is used to set the width and height of the sprite. Finally, sheet:getDimensions() is called to set the source and size of the image that the quad is using as its source.

Traps

This library generates a trap object located somewhere within a room of a given size (specified by the w and h arguments). There are two different traps, each with two states: there’s a crack in the floor that opens into a pit, and pinholes from which spikes spring. For ease of selection, the image for the first type of trap is stored in self.state[1] and the second in self.state[3]. This way, the virtual die only has to choose between two numbers, which can be directly applied to which image is used for its un-sprung state.

Monsters

Setting images for the monsters is similar to setting images for traps, except that there are many more states for each monster. On this spritesheet, there are at least three images of each monster walking east, and at least three more of each monster walking west. This is significant, because in the animation cycles for the monster, the grouping of images for each monster matters: starting at self.face[1] has the monster facing one way, and starting at self.face[3] has the monster face the opposite direction.

Hero

This code is lazy, in a good way. There are a total of 12 states for the hero’s image: a three-frame walk cycle for each cardinal direction. Instead of typing out all 12 quad definitions, a for loop is used for each direction. Additionally, a variable called self.face is set to make it easy to find out which direction the hero is facing. This is an important variable to determine whether the hero is passing by a doorway or actually passing through a door, and also for determining which way a magic missile (or a flaming skull, as the case may be) is fired.

The self.speed variable defines how quickly the hero moves each turn. The self.xp variable grants the hero 10 points of XP. Other variables, such as self.x and self.y, are created as placeholders, since they will be overwritten almost immediately, when the hero is placed in the room.

Bolt

This library creates a table for the bolt’s images from the spritesheet skull. It sets an initial origin point of self.x and self.y, both of which are defined by the x and y arguments when the bolt is created. Since the bolt is meant to originate from the hero’s magical hands, the origin point will always be the same as the hero’s current position.

Floor Tiles

Room

All decisions about the room and its contents are made with the digital equivalent of rolling a die. The room size is based on the assumption that this game works on a tiled setup, so the room width, for instance, will never be less than 4 tiles nor larger than 24 tiles.

This code plays a little with probability. Instead of having the computer decide between 0 and 1 for whether or not a door is in a wall, it “rolls” a 20-sided die (d20) and then divides the result by 2, returning the modulo (the “remainder”). The result is the same: either a 0 or a 1, but the probability is a little better distributed.

To transform the 0 and 1 result to a Lua-friendly Boolean value, a custom function is used. The bool function returns false unless a value is 1.

Doors

The location of each door is determined from a random range from tile 1 (not 0, since a door in a corner would be inaccessible) to the maximum length of a wall (minus 1 tile, to avoid a door in the corner). The door is marked active with the self.go variable, and a field called self.face is created to track which direction the door is facing.

Rogue Code

The code for main.lua is only about 400 lines of code. Most of it is code similar to what you have already done for the previous games in this book, but there are a few new tricks specific to character-driven games for you to learn.

You can probably understand this code, even though you’ve never done anything like this for your other games. The global hot table is analyzed. If the hot['name'] field is found to be nil, then a value is randomly generated from the contents of the card (as in cardinal directions) table. A corresponding X and Y value is assigned to hot table, the hero is placed at whatever door has been designated as the hot door, and then functions are called to place treasure, monsters, and traps.

Obviously each convention is useful for different reasons. Since the doors table contains other tables (each one called door), you can access information inside each table using the standard dot notation, as in doors['n'].x or doors['e'].y. It’s a lot of data to manage, and it can get overwhelming to try to keep track of which table contains data and which table contains more tables, and what data those tables contain. When in doubt, iterate through a table and print the values. If you see more tables, then you know that you either need to iterate through another level of tables, or else call table fields directly. There are more examples of both later in this game, so look at them with this in mind.

This function looks at the room table to discover whether a door at a certain position is meant to exist. If it is, then a door is generated with your door.lua class , and placed into the doors table with a key identifying its position as n, e, s, or w.

You might remember the blast function from Battlejack. It clears out the old data from tables. It’s used here because rooms are disposable; once a player leaves a room, they can never return to it. This is a design decision made exclusively to keep the code simple (and it’s why there is a hist table tracking each room as they are created, but never actually used for any mechanic).

Draw Function

The draw function is, of course, the place where all the graphics really happen. You already know the basics of this function, so read the code once for comprehension, and then add it to your main.lua file.

The rest of the love.draw function is pretty routine. Draw the traps, treasures, monsters, update the player about their score or death, draw any bolts that have been fired, and then draw the player.

Keypressed

Permadungeon is a turn-based game, meaning that the hero moves and then the monsters move. For that reason, player movement happens on each key press, and monster movement happens on each key release.

Another counter is the progress variable. This is a convenience counter that ensures a player is a few steps from the door through which they entered before the game starts looking for doorway collisions; otherwise, the player might accidentally step back through a door as soon as they enter a room. The progress counter is reset each time a room is created.

Monster Movement

In the love.keyreleased function , two important things happen: the monsters move, and any bolts that the hero fires are generated. Placing the fire power trigger in the keyreleased function rather than the keypressed function is a good way to reinforce that your player can’t just hold down a button and spray bolts out at their enemy. While LÖVE distinguishes between a key press and a key repeat, not all game engines do, so it’s good practice to put fire power where you really mean for it to happen.

Bolts and Updates

The final function to write for the game is the love.update function . This is a standard LÖVE function. You’ve used it before to check for win conditions and to update particle effects. In this game, the update function is needed for out-of-turn motion, specifically for the bolts fired by the hero. While it might be a valid mechanical choice to make weapon fire move within the structure of game turns, it’s more common that fire power moves in real time.

Since the bolt animation happens to have four states on its spritesheet rather than three, a dedicated frame counter that goes all the way up to four is used. Bolt movement is basically the same as hero and monster movement, except that when it reaches the limits of a room, it is removed from the bolts table. If it hits a monster, it deals damage to the monster and is removed from the table.

That’s all the code there is for a basic dungeon crawler. Launch it, fix any bugs you find, and make your own improvements.

Homework