Before You Begin

This book teaches you to program. It assumes you have never written a line of code in your life, and it does not assume you want to become a programmer — only that you want to make a game.

Every lesson ends with something you can run and play with. Nothing is saved for later: there are no chapters of theory before the first picture appears on screen. You will write your first working program in about ten minutes, and it will be five lines long.

Singe is a game engine. You can make anything with it that you can make with any other engine, in two dimensions or three, and most of this book is about doing exactly that. What sets it apart is that it can also play full motion video as the world the game happens in, which is how the laserdisc games of the arcades worked and which almost nothing else does well. That is a capability, not an obligation: a game only plays video if it asks to, and nothing you write for the first thirteen lessons will go near it.

The language is Lua, which Singe uses for everything. Lua was chosen by people who had to teach it to artists and designers, and it shows. There are no semicolons to forget, no types to declare, and no compiler to fight. When you make a mistake, Singe tells you the file, the line, and what it did not understand.

What You Need

  • Singe. One file. Put it in a folder somewhere you can find again.

  • A text editor. Notepad, TextEdit in plain text mode, Notepad++, VS Code, or anything else that saves plain text. A word processor will not do: it saves formatting you cannot see, and Singe cannot read it.

  • Nothing else. You do not need a laserdisc, a video file, a drawing program, or any artwork. The whole of part one draws everything itself, and from part two onward the pictures, the sounds, the video, and the models you need all come with the book or with the engine. What you need is listed below.

How to Read This Book

Type the code in. Do not copy and paste it. Typing it is slower, and that is the point: you will make small mistakes, and fixing them is how you learn to read what the computer tells you. Every lesson has a Try it section with changes to make, and those matter as much as the lesson.

If a lesson goes wrong and you cannot see why, the finished script for every lesson is in the learn folder that comes with this book, named for its lesson: 01-hello.singe, and so on. Read it only after you have tried.

How Your Folders Are Laid Out

Lesson one sets this up and every later lesson assumes it, so it is worth seeing once now.

You keep one work folder with your copy of Singe in it. Each lesson makes a new folder inside that, named after the script inside it.

singe/                 <- your work folder, with Singe in it
    Singe/             <- the engine puts its own files here
    data/              <- and anything your games save
    hello/
        hello.singe
    rocks/
        rocks.singe
        art/

You run a lesson from the work folder by naming its folder, so Singe rocks runs rocks/rocks.singe. That short form works because the folder and the script share a name. This is the same shape a real installed game has, which is why the book uses it from the first lesson rather than tidying up later.

What Comes with This Book

From part two onward the lessons use pictures and sounds. They are in the art folder that comes with the book, and you copy that folder into whichever lesson folder you are working in, keeping the name. There is a ship, a rock, a shot, a star, four frames of somebody walking, and two noises. art/README.txt lists them with their sizes.

Singe itself provides the rest. The first time you run anything, the engine unpacks a folder called Singe into your work folder, and in it are a video, a font, two 3D models, and a click. The lessons that need those use the ones already on your disk, so there is nothing to find and nothing to buy. None of it is pretty. All of it is real, and swapping in something better is usually one changed file name.

This Is Not the Forge Book

Forge, a separate tool with a book of its own, makes a game by describing it instead of programming it. That is a different road to a different place, for someone who does not want to write code at all. If you came here to learn to program, you are in the right place. You do not need Forge or its book, and this one does not build on it.

The Singe Reference is the reference: every function, every argument, every return value, and the programming model behind them. It is not a tutorial and does not try to be one. You will start reaching for it around lesson six, and by the end of this book you will use it more than you use this book. It comes in the same download as this one.

The Series

Thirty-one lessons in four parts. Each one needs the one before it and nothing else.

Part One: The Ideas. No artwork, no video, nothing to install. You draw with the shapes and the text the engine already has, and you learn what a program is made of.

  1. Hello — a script, a function, a string, and something on screen.

  2. Numbers That Change — variables, arithmetic, and making it move.

  3. Making Decisions — if, comparison, and reading the controls.

  4. Doing It Again — for and while, and drawing a hundred of something.

  5. Your Own Functions — arguments, return values, and why you would bother.

  6. Lists of Things — tables, ipairs, adding and removing.

  7. A Game — everything so far, playable, in about a hundred and twenty lines.

  8. When It Goes Wrong — reading errors, debugPrint, and reloading with F5.

Part Two: A Real Game. Artwork, sound, and the shape a finished game takes.

  1. Pictures — sprites, loading, drawing, and frames.

  2. Sound — effects, music, and when to load which.

  3. Hitting Things — collision, the game kit, and hit boxes.

  4. Score, Lives, and Game Over — state, saving, and starting again.

  5. A Game Folder — games.dat, artwork for the menu, and running from it.

Part Three: Video. Playing film as the world of the game, and the arcade conventions that grew up around it. Skip this part if your game does not want video; nothing after it depends on this part.

  1. Playing Video — the disc, frames, seeking, and waiting.

  2. The Other Way to Write It — the threaded model, and why it suits video.

  3. Branching — choices, paths, and the shape of a branching video game.

  4. Light Guns — aiming, firing, and the calibration a cabinet needs.

  5. Quick-Time Events — prompts, windows, and scoring the player’s timing.

Part Four: Everything Else. Each lesson stands alone; take them in any order.

  1. Text That Looks Good — fonts, quality, and measuring.

  2. Menus and Screens — the GUI, documents, and styling.

  3. Subtitles — and why they are their own system.

  4. Into 3D — scenes, cameras, and coordinates.

  5. Models and Light — glTF, materials, and animation.

  6. Physics — bodies, forces, joints, and when not to use them.

  7. Particles — emitters, and making an explosion.

  8. Characters That Move Themselves — navigation and pathfinding.

  9. Music and MIDI — tracks, soundfonts, and instruments.

  10. Online — accounts, high score tables, and the catalogue.

  11. Keeping Data — databases, tables, and the questions you ask of them.

  12. Shipping It — packing, patching, licenses, and the release.

  13. In a Cabinet — controls, service menus, bezels, and the things that only matter on real hardware.

Lesson 1: Hello

The finished lesson

That is what you will have at the end of this lesson. It is not much to look at. It is also a program you wrote, running on a real game engine, and everything else in this book is built on the five lines that made it.

Set Up Your Work Folder

Make one folder to keep everything in, called singe or whatever you like, and put your copy of Singe in it. This is your work folder, and every lesson in this book puts a new folder inside it. You will make it once and never think about it again.

Inside the work folder, make a folder called hello, and inside that a file called hello.singe.

singe/                 <- your work folder, with Singe in it
    hello/
        hello.singe

That nesting is not fussiness. Singe treats the folder you run it from as the place where games live, one folder per game, and it keeps its own files there too. Your game goes in its own folder, one level down. From lesson two onward each lesson is another folder beside hello.

Two things about the names. The part after the dot, .singe, is how Singe knows this is a script. And on most computers that are not Windows, capital letters count: Hello.singe and hello.singe are two different files. Get into the habit now of typing names exactly.

Giving the folder and the script the same name matters as well, and you will see why in a moment.

Open hello.singe in your text editor. It is empty. That is correct.

Type This In

function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    return OVERLAY_UPDATED
end

Save it.

Do not worry yet about what any of it means. Two things are worth noticing before you run it, because they will be true of every program you ever write.

The first is that the spaces at the start of the middle three lines are there on purpose. They do nothing at all to the program — Singe would run it exactly the same without them — but they show you at a glance that those three lines belong inside the thing that starts with function and ends with end. Every programmer does this. Do it from the first day and you will never have to learn it later.

The second is the order of the lines. They happen top to bottom, one after another, like the steps of a recipe. That is the single most important thing about a program, and almost everything that confuses a beginner comes from forgetting it.

Run It

Open a terminal, go to your work folder — not the hello folder inside it — and name the folder you want to run:

Singe hello

On Windows that is Singe.exe hello. If your copy of Singe lives somewhere else, type the path to it, such as ../Singe hello.

That is why the folder and the script share a name. Given a folder, Singe looks inside it for a script called the same thing. Name them differently and you get Error: Unable to locate the game., which is the engine saying it looked and found nothing it recognized. You can always be explicit instead and write Singe hello/hello.singe, which does the same job.

A black window opens with the word Hello! near the top left corner. Press Escape or Q to quit.

Two things will have happened that you did not ask for, and both are normal. Folders called Singe and data appeared in your work folder, beside hello: the first is the engine unpacking the files it needs, the second is where anything your games save will go. Leave both alone. And the window is mostly black, because you have not drawn anything except six characters.

What Just Happened

Now the five lines, one at a time.

function onOverlayUpdate()

function starts a group of instructions and gives it a name. Everything from here down to the matching end belongs to it. This one is called onOverlayUpdate, and the empty parentheses after the name will make sense in lesson five.

That name is not yours to choose. Singe looks for a function with exactly that name and calls it about sixty times a second, forever, so that you have a chance to draw. If you spell it onoverlayupdate or onOverlayUpdated, Singe will not find it, your window will stay black, and nothing will tell you you made a mistake. That is the first real lesson: the computer does what you wrote, not what you meant.

A function that you write and the engine calls is a callback. You do not call it yourself, and you cannot say when it runs; you write it, and Singe calls you back when there is something to do. Every name in this book that begins with on is a callback, and there is one for nearly everything that can happen: a button pressed, a key typed, a sound finishing, the disc reaching a frame. onOverlayUpdate is the one for drawing, and it is the only place drawing is allowed.

    overlayClear()

This is a function too, but not one you have to write: Singe provides it, along with several hundred others, and you are calling it. Calling a function means saying its name followed by parentheses. This one wipes the screen clean.

It comes first because drawing does not replace what was there before, it draws on top of it. Clear, then draw, every time.

    overlayPrint(2, 2, "Hello!")

Another call, and this one needs to be told three things, which go inside the parentheses separated by commas. Things you hand to a function like this are called arguments.

The first two are numbers: how far across and how far down. The third is the text to print, and it is in double quotes because that is how you tell the computer that Hello! is a piece of text rather than the name of something. Text in quotes is called a string, and you will use strings constantly.

Sooner or later you will want a double quote inside a string, and the obvious way does not work: the second quote ends the string early, and you get the same unfinished string error you will meet at the end of this lesson. There are two ways round it, and both are worth knowing.

    overlayPrint(2, 2, "She said \"hello\" to me.")
    overlayPrint(2, 4, 'She said "hello" to me.')

The first puts a backslash in front of each quote that belongs to the text. The backslash says "the next character is part of the string, not the end of it", and the pair together is called an escape. The second uses single quotes to mark the ends of the string, which leaves double quotes free to be ordinary text. Lua accepts either kind of quote, as long as the string ends with the same kind it started with.

Both of those lines print exactly the same thing. Use whichever is easier to read, which is usually the single quotes when the text is full of double ones.

The two numbers are not pixels. overlayPrint is the engine’s own plain text, and it counts in character cells: (0, 0) is the very top left corner, (1, 0) is one letter to the right, and (0, 1) is one line down. So (2, 2) is two letters in and two lines down. Other ways of drawing text do count in pixels, and you will meet them in lesson nineteen.

    return OVERLAY_UPDATED

return hands an answer back to whoever called the function. Singe asks your onOverlayUpdate one question every time it calls it: did you change anything? OVERLAY_UPDATED means yes, so put it on screen.

OVERLAY_UPDATED has no quotes around it because it is not text. It is a name that Singe has already given to a value, so that you can write something you can read instead of a number you would have to remember.

end

The matching end of the function. Every function has exactly one, and forgetting it is the single most common mistake there is.

Try It

Change one thing at a time, save, and run it again. That loop — change, run, look — is the whole job.

  1. Move the text. Change overlayPrint(2, 2, "Hello!") to overlayPrint(10, 5, "Hello!"). Then try (0, 0). Then try (200, 2), and work out why it vanished.

  2. Say something else. Put your own name in the quotes.

  3. Say two things. Add a second overlayPrint line under the first one, with a different row number and different text. Nothing stops you having as many as you like.

  4. Take the clear out. Delete the overlayClear() line and run it. Nothing changes, because nothing on your screen moves yet. Put it back anyway. In lesson two it will matter enormously, and this is a good time to see that some mistakes wait before they bite.

Break It on Purpose

Beginners spend more time reading error messages than reading books about programming, so let us get the first one over with now.

Delete the closing quote after Hello!, so the line reads overlayPrint(2, 2, "Hello!), and run it. Singe refuses to start and says:

Error running script:  hello/hello.singe:3: unfinished string near '"Hello!)'

Read it from the left. hello/hello.singe is which file: the folder, then the script inside it. 3 is which line. The rest is what went wrong, in this case a piece of text that was opened and never closed. Go to line three, put the quote back, and it runs.

Almost every error you will ever see has that shape: a file, a line, and a complaint. The complaint is sometimes written for someone who already knows Lua, but the file and the line are always right, and nine times in ten the line is enough.

Stop Restarting It

You have now started Singe by hand five or six times. Stop doing that. Run it like this instead:

Singe -R hello

-R tells Singe to watch your script. Save a change in your editor, and the game restarts itself a moment later with your change in it, without closing the window. If you save a mistake, the error is printed and the window sits empty until you save a fix.

Use -R for the rest of this book.

What You Learned

  • A program is a file of instructions that happen in order, top to bottom.

  • A function groups instructions under a name and stops at its end.

  • onOverlayUpdate is a name Singe looks for and calls many times a second, and it is where all your drawing goes.

  • Calling a function means writing its name and parentheses. Anything inside the parentheses is an argument.

  • A function the engine calls for you, rather than one you call yourself, is a callback. onOverlayUpdate is one.

  • Text in double quotes is a string.

  • Clear the screen before you draw on it.

  • An error tells you the file and the line. Start there.

Next Time

Your Hello! sits where you put it and never moves. To make it move, you need somewhere to keep a number that changes — a variable — and that is the whole of lesson two.

Lesson 2: Numbers That Change

The finished lesson

In lesson one you put a word on the screen and it sat there. By the end of this lesson the same word will be sliding around the window, turning round when it reaches an edge, and it will be doing it because of four numbers that the program changes sixty times a second.

Along the way you will meet the single idea that trips up more beginners than any other: where you put something decides how long it lives.

Start a New Folder

Make a folder called numbers next to your hello folder, and inside it a file called numbers.singe. Type the lesson one program into it, or copy hello.singe over and rename it — either is fine, and typing it again is not wasted.

function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    return OVERLAY_UPDATED
end

Run it with Singe -R numbers and leave it running. The -R from the end of lesson one means you will not have to start it again for the rest of this lesson; save the file and the window catches up on its own.

Count the Frames

Lesson one said that Singe calls onOverlayUpdate about sixty times a second. That is easy to say and hard to believe, so count them.

function onOverlayUpdate()
    frames = 0
    frames = frames + 1
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Save it. In the top left corner you get frame 1, and it stays at frame 1 forever.

That is disappointing, and it is also the most useful thing in this lesson, so do not fix it yet. Look at what you wrote and think about the order of the lines, which lesson one said was the most important thing about a program.

Singe calls onOverlayUpdate. The first line sets frames to zero. The second adds one to it, making one. You print it, you return, and the function is over. Then Singe calls it again, and the first thing that happens is that frames is set back to zero.

You are not counting frames. You are counting to one, sixty times a second.

Move the Line Out

Take the frames = 0 line out of the function and put it above, on its own, before the word function.

frames = 0


function onOverlayUpdate()
    frames = frames + 1
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Save it. The number climbs, fast, and does not stop.

Nothing else changed. The only difference is where the line is, and that is the whole of the idea. Lines inside a function happen every single time the function is called. Lines outside every function happen once, when Singe reads your file, before the game starts.

frames = 0 needed to happen once. It was happening sixty times a second, and it was wiping out the work of the line under it.

Every moving thing you ever write has this shape. Set the number up outside, change it inside.

What Just Happened

Three new pieces of code are in there. Here they are on their own.

frames = 0

This makes up a name, frames, and puts the number zero behind it. A name with a value behind it is a variable, and it is called that because the value is allowed to vary — to change while the program runs.

The = is not the equals sign from school. It does not say that frames is equal to zero; it says put zero into frames, and it always works in that direction, right into left. Programmers call it assignment, and it is worth saying the line out loud that way as you write it: "frames gets zero".

You choose the name. It can be almost anything that starts with a letter and has no spaces in it, and it should say what the thing is. frames is a good name. f is a bad one, and you will not thank yourself for it in a week.

    frames = frames + 1

This is the line that makes people stop and stare, because as a statement about arithmetic it is nonsense: nothing is equal to itself plus one.

It is not a statement about arithmetic. Remember that = puts the right-hand side into the left-hand name, and read it in that order, right first. Work out frames + 1 using whatever is in frames right now. Then put the answer back into frames. If frames held six, the right-hand side works out to seven, and seven goes into frames.

Adding one to a variable like this is something you will write thousands of times.

The + is what you expect, and so are the other three: - subtracts, * multiplies, and / divides. There is no x key for multiply, which is why the star does that job.

    overlayPrint(0, 0, "frame " .. frames)

overlayPrint wants text, and frames is a number, not text. The two dots join the two together and hand the result over as one string: the five characters frame, a space, and then however many digits the number needs.

Those two dots are the joining operator, and it is worth knowing its real name because the error messages use it: joining strings is called concatenation.

Note the space inside the quotes, before the closing one. Without it you get frame6. Lua joins exactly what you give it and adds nothing of its own.

Lua will turn a number into text for you when you join it to a string this way, which is why you did not have to do anything special. It will not do that for everything. If you ever try to join something that is neither text nor a number, Lua stops with an error, and the way round it is tostring, which turns anything at all into text:

    overlayPrint(0, 0, "frame " .. tostring(frames))

That line does exactly the same as the one before it. You do not need tostring for numbers. You will need it in lesson three.

Make It Move

You now have everything you need to move the word. The word is drawn wherever you say, you have a way to keep a number between frames, and you have a way to change it.

Give the column its own variable outside the function, and add to it inside.

frames = 0
wordX  = 0


function onOverlayUpdate()
    frames = frames + 1
    wordX = wordX + 1
    overlayClear()
    overlayPrint(wordX, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Save it. The word shoots off the right-hand side and never comes back.

It moved one column every frame, sixty times a second, so it crossed the whole window in about a second. Slow it down by adding less than a whole column:

    wordX = wordX + 0.25

Now it takes four frames to move one column, and the word creeps. wordX is mostly a number like 12.75, which is not a column at all, and Singe deals with that by throwing away everything after the dot when it draws: 12.75 draws in column twelve. Keeping the fraction in the variable is exactly what lets you move slower than one column a frame. The number is finer than the screen is.

Where Is the Edge?

The word still leaves. To turn it round you have to know where the right-hand edge is, and you could find that out by counting: a game with no video gets a world 720 by 480 by default, the overlay you draw on is half that, 360 by 240, and the built-in console font’s letters are six pixels wide, so there are sixty columns.

Do not do that. Ask the engine.

lastColumn = overlayGetWidth() // CELL_WIDTH - string.len(word)

overlayGetWidth and overlayGetHeight are two more functions Singe provides, like overlayPrint. They take nothing and hand back a number: how wide and how tall the drawing surface is. You saw return hand a value back in lesson one, and this is the other end of it — a function you call can give you something, and here you are doing arithmetic with what it gave you.

The numbers they give you are in pixels, and overlayPrint counts in character cells, so you have to divide. overlayGetFontWidth tells you how many pixels wide one cell is, and overlayGetFontHeight how tall, so you never have to know the answer yourself. The two slashes mean divide and throw the fraction away, because a third of a character cell is not a place you can print. The ordinary single slash would give you a fraction, and a fraction of a cell is not a place either.

string.len counts the characters in a string, and it is there so that the word turns round when its last letter reaches the edge rather than its first. Try it without and you will see six characters slide off into nothing.

The capitals in CELL_WIDTH, which holds what overlayGetFontWidth gives you, are a habit rather than a rule. Lua does not care, but a name in capitals is how programmers say "this is a number I set once at the top and never touch again", and it beats having a bare 6 halfway down a file that nobody can explain a month later.

Turn It Round

Moving the other way is no work at all: instead of adding 0.25 every frame, add -0.25. So keep the amount in a variable of its own and flip its sign when the word arrives at an edge.

    if wordX > lastColumn then
        wordX = lastColumn
        speedX = -speedX
    end

That is a decision, and decisions are the whole of lesson three, so take it on trust for one lesson. Read it out: if wordX has got past lastColumn, then do the two indented lines; otherwise skip them. The end closes it, the same way end closes a function.

The first line pins the word exactly on the edge, so that a fast word cannot sail past it. The second is the flip. -speedX is minus whatever speedX holds, so if it held 0.25 it now holds -0.25, and adding -0.25 every frame walks the word back the way it came. When it reaches the left edge, the matching if flips it again, and it flips back to 0.25.

Two more of those for the top and bottom edges and the word bounces around the whole window.

The Whole Thing

CELL_WIDTH  = overlayGetFontWidth()
CELL_HEIGHT = overlayGetFontHeight()
TOP_ROW     = 2

word   = "Hello!"
wordX  = 0
wordY  = TOP_ROW
speedX = 0.25
speedY = 0.125
frames = 0

lastColumn = overlayGetWidth() // CELL_WIDTH - string.len(word)
lastRow    = overlayGetHeight() // CELL_HEIGHT - 1


function onOverlayUpdate()
    frames = frames + 1
    wordX = wordX + speedX
    wordY = wordY + speedY

    if wordX < 0 then
        wordX = 0
        speedX = -speedX
    end

    if wordX > lastColumn then
        wordX = lastColumn
        speedX = -speedX
    end

    if wordY < TOP_ROW then
        wordY = TOP_ROW
        speedY = -speedY
    end

    if wordY > lastRow then
        wordY = lastRow
        speedY = -speedY
    end

    overlayClear()
    overlayPrint(0, 0, "frame " .. frames)
    overlayPrint(wordX, wordY, word)
    return OVERLAY_UPDATED
end

TOP_ROW keeps the word out of the top two lines so that it never scribbles over the frame counter. lastRow has a - 1 in it rather than a string.len, because a word is many characters wide but only ever one line tall.

Notice that the whole top half of the file runs once and the whole bottom half runs sixty times a second, and that you can tell which is which by looking at the indentation. That is what the spaces were for.

Try It

  1. Change the speeds. Try speedX = 1 and speedY = 1. Then try 0.05 for both. Then make one much bigger than the other.

  2. Change the word. Put a much longer word in the quotes — long enough to fill a third of the window — and watch the right-hand bounce still happen in the right place. That is string.len doing its job.

  3. Take the clear out. Delete the overlayClear() line. Lesson one promised this would matter one day, and this is the day: the word smears a trail across the window and never rubs any of it out, because drawing has always drawn on top of what was there. Put it back.

  4. Stop it going sideways. Set speedX = 0 and run it. Work out why the word now never leaves column zero, and why the if for the left edge never fires.

  5. Break the frame counter on purpose. Move the frames = 0 line back inside the function, above frames = frames + 1. Watch the counter stick at one while the word keeps moving perfectly. Then work out why the word is unaffected.

Break It on Purpose

Change the two dots on the frame counter line to a plus sign, so that it reads:

    overlayPrint(0, 0, "frame " + frames)

Save it. The window closes, Singe stops, and the terminal says:

Error executing function 'onOverlayUpdate':  numbers/numbers.singe:42: attempt to add a 'string' with a 'number'

followed by several lines starting with stack traceback:, which you can ignore for now.

Read it the way lesson one taught you: the file, the line, then the complaint. Line 42 is the line you changed. The complaint says Lua was asked to add a string to a number, and adding is for numbers. + and .. look similar on the page and do entirely different jobs: plus is arithmetic, .. is glue.

This one is worth meeting because of where it appeared. Lesson one’s error stopped Singe before your game ever started, because Lua could not read the file at all. This one is a perfectly readable line that only goes wrong when it runs, so the window opened, the game ran, and it died on the first frame. Both kinds tell you the file and the line. Start there either way.

What You Learned

  • A variable is a name with a value behind it, and the value can change.

  • = means "put the right-hand side into the name on the left", not "is equal to".

  • frames = frames + 1 works out the right-hand side first, then stores it.

  • +, -, *, and / do the arithmetic you expect; // divides and throws the fraction away.

  • .. joins text together, and turns a number into text on the way.

  • A line inside onOverlayUpdate runs every frame. A line outside every function runs once, before the game starts.

  • Anything that has to remember something between frames has to live outside.

  • overlayGetWidth and overlayGetHeight tell you the size of the drawing surface, so you never have to guess it.

  • overlayClear matters the moment anything moves.

Next Time

The word moves, but it moves on its own and nothing you do makes any difference to it. In lesson three you take the four if blocks you used on trust, learn what they really say, and point them at the arrow keys instead of the edges of the screen. The box you steer around the window at the end of it is the player of the game you build in lesson seven.

Lesson 3: Making Decisions

The finished lesson

Everything you have written so far does the same thing every frame. The word in lesson two moved whether you wanted it to or not, and the only reason it ever turned round was four blocks of code you were told to take on trust.

This lesson is those four blocks, properly. By the end of it your program will ask questions, act on the answers, and — because the most interesting question a game can ask is "what is the player doing?" — you will be steering a box around the window with the arrow keys. Keep that box. It is the player of the game you build in lesson seven.

Start a New Folder

A folder called decisions, a file in it called decisions.singe, and Singe -R decisions running in a terminal. Same as last time.

What an if Really Says

Here is the block from lesson two on its own.

if wordX > lastColumn then
    wordX = lastColumn
end

Four parts. The word if. A question. The word then. And a body of lines that run only when the answer to the question is yes, closed off by end.

The question is wordX > lastColumn, and the > is doing the real work. It compares the two numbers either side of it and produces an answer that is either true or false. Those two words are not text and are not numbers; they are values in their own right, called booleans, and a boolean is the only thing an if is interested in.

The indentation is the same idea as in lesson one: the lines inside are indented so you can see at a glance what belongs to the if, and the end lines up with the if that opened it. Lua would run it without the spaces. You would not be able to read it.

There are six of these comparisons and you will use all of them.

a < b

a is less than b

a > b

a is greater than b

a ⇐ b

a is less than or equal to b

a >= b

a is greater than or equal to b

a == b

a is the same as b

a ~= b

a is not the same as b

The last two are the ones to be careful with, for different reasons.

~= means "is not equal to". Most languages write that !=, and if you have seen a program before, your fingers will type != and Lua will refuse it. The squiggle is on your keyboard next to the 1 or under the #, depending on where you live.

== is two equals signs, and it is not a typo for one. This is one of the most common mistakes in programming, and it is worth stopping on for a moment.

In lesson two you learned that one equals sign means put the right-hand side into the name on the left. That is a thing you do. It changes something.

Two equals signs mean are these the same? That is a question you ask. It changes nothing, and it hands back true or false.

lives = 3
if lives == 3 then

The first line sets lives to three. The second asks whether it is three. Different jobs, different symbols, one character apart. Lua will catch you if you get it the wrong way round, and you will meet the error it uses at the end of this lesson.

When the Answer Is No

An if on its own does nothing at all when the answer is false. Very often you want the other thing to happen instead, and that is else.

if lives > 0 then
    message = "Ready"
else
    message = "Game Over"
end

Exactly one of those two bodies runs, never both, never neither, so message always ends up holding one of the two strings and never nothing.

When there are more than two possibilities, elseif chains them.

if score >= 10000 then
    rank = "ace"
elseif score >= 5000 then
    rank = "pilot"
elseif score >= 1000 then
    rank = "rookie"
else
    rank = "passenger"
end

Lua tries the questions from the top and stops at the first one that is true. A score of 6000 is not greater than 10000, so it tries the next, which is true, so rank becomes pilot and the other two questions are never asked. That last point matters: the elseif for 1000 is also true for a score of 6000, and it is never reached, which is why the order is from biggest to smallest.

The whole chain needs exactly one end, no matter how many elseif parts are in it. It is one decision, not four.

True, False, and Nothing at All

You do not have to compare two things to get a boolean. You can keep one.

paused = false

That is a variable like any other, and the value in it is the boolean false itself, written without quotes because it is not the word "false", it is the idea. The same goes for true. A variable holding one of them can go straight into an if with no comparison at all:

if paused then

Read it as "if paused". That is better English than if paused == true, which does the same thing the long way round, and experienced programmers will look at you oddly for writing it.

Three words join and flip these answers.

if alive and not shielded then
if coins > 0 or freePlay then

and is true when both sides are. or is true when either side is, or both. not turns true into false and false into true. They read like English and, unusually for programming, they mean what English means.

There is one more value to know about, and it is the one that produces the most confusing errors of your first year.

overlayPrint(0, 0, "lives " .. tostring(lives))

If you have never put anything into lives, that prints lives nil. Lua does not complain about a name it has never seen; it hands you nil, which is its word for nothing here. It is not zero and it is not an empty string. Zero is a number you meant to store. nil is the absence of a value.

You have met nil twice already without being told. frames = frames + 1 without the frames = 0 line above it fails because you asked Lua to add one to nothing. And a callback you spell wrong is nil too, which is why a misspelled onOverlayUpdate gives you a black window and no error at all: Singe looks for the name, finds nothing there, and quietly gets on with its day.

tostring is in that line because .. will not join a boolean or a nil to anything. Numbers it converts for you; these it will not. That was the promise at the end of lesson two, and now you have a use for it.

Finally, the rule that ties the whole section together, because if will accept anything you give it, not only true and false:

Everything in Lua is true except false and nil.

Zero is true. An empty string is true. Only those two are not, and once you know it, if movingLeft then reads perfectly whether movingLeft holds true, false, or has never been set at all.

Reading the Controls

Time to ask the player something. That takes a new callback.

function onInputPressed(what)
    if what == SWITCH_RIGHT then
        boxX = boxX + 10
    end
end

onInputPressed is the second callback you have written, and it works exactly the way lesson one described: you write it, Singe calls it. onOverlayUpdate is called on a timer. This one is called when something happens — when the player presses anything the engine recognizes.

The difference from onOverlayUpdate is the word inside the parentheses. Singe has to tell you which control was pressed, so it hands the function a value, and what is the name you have chosen to receive it under. Lesson one called the things you pass into a function arguments; from the inside, the name that catches one is a parameter. The name is yours: call it what, call it button, call it k. Singe fills it in either way.

SWITCH_RIGHT is a name the engine has already given to a value, like OVERLAY_UPDATED in lesson one. You do not have to load anything to use it; Singe defines all of them before your script runs. There is one for everything a cabinet has: SWITCH_LEFT, SWITCH_RIGHT, SWITCH_UP, SWITCH_DOWN, SWITCH_BUTTON1 through SWITCH_BUTTON4, SWITCH_START1, SWITCH_COIN1, and more. The reference’s Engine Constants table covers the family, which runs from SWITCH_UP to SWITCH_RECORD. They are deliberately not called "the right arrow key", because the same SWITCH_RIGHT arrives whether the player pushed an arrow key, a joystick, or a control pad’s thumbstick. You write the game once and it works on all three.

Add that callback, give boxX a starting value outside the functions, and draw something at boxX. Press the right arrow. The box jumps ten pixels each time you press it.

It Happened, and It Is Happening

Hold the arrow key down. Nothing more happens.

onInputPressed is called once, on the way down, and not again until you let go and press it again. There is no key repeat. That is exactly right for some things — firing a shot, inserting a coin, choosing a menu item — and exactly wrong for walking, which needs to keep happening for as long as the key is held.

The two are genuinely different questions. It happened is an event, and you hear about it once. It is happening is a state, and it lasts. Singe tells you about events, and the way you turn events into state is to remember them yourself.

Two callbacks, a variable between them.

movingRight = false


function onInputPressed(what)
    if what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_RIGHT then
        movingRight = false
    end
end

onInputReleased is the third callback, and it is the mirror of the second: Singe calls it on the way back up, with the same SWITCH_ value. Between them they keep movingRight telling the truth about what the player’s finger is doing right now.

Nothing has moved yet, and that is the point. The pressing and the moving are now two separate jobs. The moving goes where all the per-frame work goes.

function onOverlayUpdate()
    if movingRight then
        boxX = boxX + BOX_SPEED
    end
    ...

The box now slides smoothly for as long as the key is down, at a speed you control, and the arithmetic is back in the one function that runs sixty times a second where it belongs. This shape — events set flags, the frame acts on flags — is how nearly every game handles its controls, and you will use it again in every lesson that has a player in it.

Drawing a Box

overlayBox takes two corners: the left and top of the rectangle, then the right and bottom.

colorForeground(255, 220, 0)
overlayBox(boxX, boxY, boxX + BOX_SIZE, boxY + BOX_SIZE)

It draws an outline, four lines one pixel thick, and not a filled rectangle. There is no filled rectangle in the overlay drawing calls at all. When you want a solid block later there are ways to get one, and lesson nine has the usual one.

Its numbers are pixels, not character cells. This catches people out, because overlayPrint in lesson two counted in cells of six pixels by thirteen and everything else in Singe counts in pixels. overlayPrint is the odd one; the rest of the drawing calls — overlayBox, overlayLine, overlayCircle, overlayEllipse, and overlayPlot — all work in the same pixels that overlayGetWidth reports.

colorForeground sets the color, as three numbers from 0 to 255: how much red, how much green, how much blue. All three at 255 is white, all at 0 is black, and (255, 220, 0) is a warm yellow. Notice that it is not an argument to overlayBox. It is a setting: you change it, and everything you draw after that comes out in the new color until you change it again. overlayPrint is the exception once more — the console font arrives with its own colors baked in and ignores you.

The Whole Thing

BOX_SIZE  = 20
BOX_SPEED = 2

width  = overlayGetWidth()
height = overlayGetHeight()
maxX   = width - BOX_SIZE - 1
maxY   = height - BOX_SIZE - 1

boxX = width // 2
boxY = height // 2

movingLeft  = false
movingRight = false
movingUp    = false
movingDown  = false


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    elseif what == SWITCH_UP then
        movingUp = true
    elseif what == SWITCH_DOWN then
        movingDown = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    elseif what == SWITCH_UP then
        movingUp = false
    elseif what == SWITCH_DOWN then
        movingDown = false
    end
end


function onOverlayUpdate()
    if movingLeft and not movingRight then
        boxX = boxX - BOX_SPEED
    elseif movingRight and not movingLeft then
        boxX = boxX + BOX_SPEED
    end

    if movingUp and not movingDown then
        boxY = boxY - BOX_SPEED
    elseif movingDown and not movingUp then
        boxY = boxY + BOX_SPEED
    end

    if boxX < 0 then
        boxX = 0
    elseif boxX > maxX then
        boxX = maxX
    end

    if boxY < 0 then
        boxY = 0
    elseif boxY > maxY then
        boxY = maxY
    end

    overlayClear()

    if movingLeft or movingRight or movingUp or movingDown then
        colorForeground(255, 220, 0)
    else
        colorForeground(80, 160, 255)
    end

    overlayBox(boxX, boxY, boxX + BOX_SIZE, boxY + BOX_SIZE)
    overlayPrint(0, 0, "x " .. boxX .. "  y " .. boxY)
    return OVERLAY_UPDATED
end

Four things in there are worth a second look.

movingLeft and not movingRight is there because a player can hold both arrows at once. Without the not, the two would fight and the box would jitter or drift; with it, holding both means neither wins and the box stands still, which is what a player expects.

maxX is worked out once at the top, using overlayGetWidth the way lesson two did, and the - 1 is because the surface’s last pixel is one less than its width. Take the - 1 out and the box’s right-hand edge falls off the surface and vanishes, because Singe throws away anything you draw outside the overlay without complaining.

The clamping blocks use elseif rather than two separate if blocks. The box cannot be off the left edge and off the right edge at the same time, so asking the second question when the first was true is wasted work.

And the color decision is an if whose only job is to pick a value. Yellow while the player is doing something, blue while they are not, which is a free way of seeing that your input handling actually works.

Try It

  1. Change the speed. BOX_SPEED = 1 and BOX_SPEED = 8. At eight, watch what the clamping does when you shove the box into a corner.

  2. Show your flags. Add a line to onOverlayUpdate: overlayPrint(0, 1, "left " .. tostring(movingLeft)). Hold and release the left arrow and watch it flip. Then take the tostring off and read the error Lua gives you.

  3. Make it faster when a button is down. Add a running flag driven by SWITCH_BUTTON1 in the two input callbacks, and use an if in onOverlayUpdate to move by twice BOX_SPEED while it is true.

  4. Mark the middle. Draw a second, small box in the center of the window that changes color when the player’s box overlaps it. You will need and to join four comparisons, and it is harder than it sounds. Getting it slightly wrong is normal; lesson eleven does it properly.

  5. Take the releases out. Delete the whole onInputReleased function and run it. The box takes one step and then never stops. Work out which line is now never reached.

Break It on Purpose

Find the clamping block and change the < in its first comparison to a single equals sign, so it reads:

    if boxX = 0 then

Save it. The window sits there empty and the terminal says:

Error running script:  decisions/decisions.singe:57: 'then' expected near '='

This is the mistake the whole == section was warning about, and the message is a good example of an error that is completely accurate and completely unhelpful if you take it literally. Lua is not asking you to add the word then. Lua got as far as if boxX, expected a comparison or a then next, and found =, which cannot be either.

Whenever you see 'then' expected after an if, look for a single = that should be a double one. It is nearly always that.

Note where this one appeared: the game never started, the same as lesson one’s unfinished string, because Lua could not read the file. The frame counter error in lesson two happened while running. Errors in the shape of your code stop you before the game starts. Errors in what your code does wait until it runs.

What You Learned

  • if question then …​ end runs a body only when the answer is true.

  • else gives the other case, and elseif chains more; the first true question wins and the rest are never asked.

  • The comparisons are <, >, ⇐, >=, ==, and ~=.

  • = puts a value into a name. == asks whether two things are the same.

  • true and false are values, and you can keep them in variables.

  • and, or, and not join and flip those answers.

  • nil is what you get from a name you never set, and it is not zero.

  • Everything is true except false and nil.

  • onInputPressed and onInputReleased are callbacks Singe calls with a SWITCH_ value when the player presses or lets go of a control.

  • A press is an event and happens once; hold the state in a variable and act on it every frame.

  • overlayBox draws an outline in pixels, and colorForeground is a setting, not an argument.

Next Time

One box is easy. A hundred stars are not, at least not the way you have written things so far, because typing a hundred overlayPlot lines is nobody’s idea of a good evening. Lesson four is the loop: telling the computer to do the same thing many times, with something different each time round, which is what makes a screen full of anything possible.

Lesson 4: Doing It Again

The finished lesson

You have drawn one word and one box. A game needs a hundred things: stars, bricks, bullets, the rows of a menu. Typing a hundred lines is not the answer, and if it were, you would have to type another hundred the moment you wanted a hundred and one.

This lesson is the answer. By the end of it a field of stars will be drifting down your window, every one of them drawn by the same five lines of code.

Start a New Folder

A folder called repeating, a file in it called repeating.singe, and Singe -R repeating running in a terminal.

Forty Dots

Type this in and run it.

function onOverlayUpdate()
    overlayClear()
    colorForeground(255, 255, 255)

    for star = 1, 40 do
        overlayPlot(star * 8, 100)
    end

    return OVERLAY_UPDATED
end

A row of forty white dots across the middle of the window.

overlayPlot is the simplest drawing call there is: it sets one pixel to the current foreground color, and it is exactly what a star wants. Everything interesting here is the three lines around it.

    for star = 1, 40 do

That says: do what follows forty times, and each time round, star holds a different number — one the first time, two the second, forty the last. Both ends are included, so 1, 40 really is forty times round and not thirty-nine. This shape is a loop, and this particular one is a numeric for loop.

star is a name you invent, the same way you invented frames in lesson two, and the loop fills it in for you. You do not set it, and you should not change it inside the loop. It exists only between the for and its end; ask for it afterwards and you get nil.

The do is required and is easy to forget. Leave it out and Lua says 'do' expected near, followed by whatever it found instead, which will be the first thing on the next line.

        overlayPlot(star * 8, 100)

The body. This is what runs forty times, and it is the same line every time — what changes is star, so the first dot lands at x of 8, the second at 16, and the last at 320. A loop is only useful when the body does something with the loop’s number, and the first thing you will reach for every time is arithmetic on it.

The body is indented one step further than the for, for the same reason everything else has been indented so far.

    end

Closes the loop. You have now met three things that need an end: function, if, and for. They all work the same way, they nest inside each other, and the indentation is how you keep track of which end belongs to what.

Counting by More Than One

The loop counts up by one unless you tell it otherwise. Add a third number and it counts by that instead.

    for x = 0, overlayGetWidth() - 1, 10 do
        overlayPlot(x, 100)
    end

Read it as from, to, by. This one goes 0, 10, 20, and so on, stopping at or before the last pixel of the surface, which draws a dotted line all the way across whatever size the window happens to be. It is the same row of dots as before, described in terms of where they go rather than how many there are.

The step can be negative, which counts down.

    for countdown = 10, 1, -1 do

Ten, nine, eight, down to one. With a negative step the second number is the floor rather than the ceiling, which is what you would expect, and getting the sign wrong is a loop that never runs at all: for i = 10, 1 do with no step counts up from ten towards one, is already past the end before it starts, and does nothing. No error, no output. If a loop of yours never seems to run, check the direction first.

The step can be a fraction too, though you will want that less often than you think.

One Loop Inside Another

The body of a loop is ordinary code, and ordinary code can contain a loop.

    for row = 0, overlayGetHeight() - 1, 20 do
        for column = 0, overlayGetWidth() - 1, 20 do
            overlayPlot(column, row)
        end
    end

That draws a grid of dots over the whole window. Put it in your onOverlayUpdate in place of the row and look at it, because the way it runs is worth getting straight in your head now rather than in lesson eleven when something depends on it.

The outer loop runs once for row of 0. Inside that, the whole inner loop runs from beginning to end — eighteen columns, eighteen dots, one row of the grid. Only when the inner loop has finished does the outer loop move on to row of 20 and run the entire inner loop again.

The inner loop’s body therefore runs eighteen times twelve, which is two hundred and sixteen times, for twelve trips round the outer one. That multiplication is why nested loops are how you fill a rectangle with anything, and also why you should glance at the numbers before you nest three of them.

Notice that each dot’s position needs both loop variables: column for the across and row for the down. That is the pattern. If the inner body only uses the inner variable, the inner loop is drawing the same thing over and over in the same place, and you have written a slow way of doing it once.

When You Do Not Know How Many

A for loop needs to know how many times before it starts. Sometimes you do not, and then you want the other kind.

    x = 0
    while x < overlayGetWidth() do
        overlayPlot(x, 100)
        x = x + 10
    end

A while loop checks a question before every trip round, exactly the question an if would ask, and keeps going for as long as the answer is true. When the answer is false it stops and carries on with the line after the end. If the answer is false the very first time, the body never runs at all.

That example draws the same dotted line as the for with a step of ten, and it takes three lines to do what for did in one, so use for for that. Here is the difference that decides it:

  • Use for when the number of trips is known before you start. Forty stars. Every tenth pixel across. Every row of a grid.

  • Use while when you are waiting for something to become true and cannot say in advance how long it takes. Deal cards until the deck runs out. Keep asking until the player types something valid. Step through a list until you find what you were looking for.

A while has three parts and you have to write all three yourself: set the variable up before the loop, test it in the while, and change it inside the body. The for loop does all three for you, which is why it is the one to reach for when it fits. Forget the third part in a while and the question never stops being true, which you will do on purpose at the end of this lesson.

A Star Made Out of Its Own Number

Now the star field, and a problem that shapes the rest of part one.

Each star needs an x and a y of its own, and you have no way to keep a hundred separate variables — writing star1X, star2X and so on up to a hundred is worse than typing the hundred lines you were avoiding. So do not store them. Work each one out from the only thing that makes a star different from its neighbors: its number.

        starX = (star * 37) % width

The % is the last of the arithmetic operators and it is the remainder: what is left over after dividing. Fifteen divided by four is three with three left over, so 15 % 4 is 3. Its useful property is that the answer can never be as large as the number on the right, so a remainder by width is always a position somewhere on the screen no matter how big the left-hand side gets.

Star 1 goes to 37, star 5 to 185, star 10 to 10 — 370 wrapped round past 360 and came back at the left. Thirty-seven is chosen because it shares no factor with 360, which is what stops the stars landing in neat stripes; try 36 instead and you will see the problem immediately.

The downward drift is the same trick with a number that grows over time.

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    ...
        starY = (star * 61 + math.floor(drift * layer * 0.5)) % height

drift lives outside the function and climbs every frame, exactly like frames in lesson two. Adding it to every star’s y moves the whole field down together, and the % brings a star that falls off the bottom back on at the top, forever, for free.

math.floor throws away the fraction of a number and hands back the whole part below it: math.floor(7.9) is 7. Lesson two pointed out that Singe does that for you when it draws, and it does, but doing it yourself means the number you are working with is the number that appears on screen. That will matter in lesson seven, when two things have to agree about whether they are touching.

Note that layer in there is a second loop variable. The stars are drawn by a loop inside a loop, and the outer one is not a row of a grid but a distance: three layers of stars, each drifting at its own speed and its own brightness, which is what makes a flat field of dots look like it has depth.

Chance

Stars twinkle. Twinkling means a brightness that is a bit different every frame, and "a bit different" is math.random.

        shade = math.random(60, 90) + layer * 55
        colorForeground(shade, shade, shade)

math.random(60, 90) hands back a whole number from 60 to 90, both included, chosen afresh every time you call it. Call it with no arguments at all and you get a fraction between 0 and 1 instead, which is the form to use when you want something to happen one time in five. You do not have to set the generator up; Lua does that when Singe starts.

Adding layer * 55 lifts the near layers out of the dim range, so the far stars stay faint and the near ones are almost white. Equal red, green, and blue, as lesson three explained, is a shade of gray.

Because shade is picked again on every frame for every star, each star flickers on its own, which at sixty frames a second reads as a twinkle rather than as a fault.

The Whole Thing

LAYERS          = 3
STARS_PER_LAYER = 40
ACROSS_STEP     = 37
DOWN_STEP       = 61
LAYER_SHIFT     = 13
LAYER_SPEED     = 0.5
LAYER_BRIGHT    = 55

width  = overlayGetWidth()
height = overlayGetHeight()

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()

    for layer = 1, LAYERS do
        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            colorForeground(shade, shade, shade)
            overlayPlot(starX, starY)
        end
    end

    return OVERLAY_UPDATED
end

A hundred and twenty stars, drawn by five lines, and the file is shorter than the one in lesson three.

It is also as far as this approach goes, and it is worth being honest about why while you are looking at it. Every star in there is a formula. Nothing about a star is remembered: you cannot make one brighter than its neighbor and have it stay that way, you cannot knock one out of the sky, and you cannot have the player collect one, because there is nowhere to write down that anything happened to it. Star seventeen is not a thing. It is a number that briefly passes through a variable called star.

The moment you want a hundred things that each remember something of their own, you need somewhere to put a hundred sets of facts. That is lesson six, and the star field is why it exists.

Try It

  1. More and fewer. Try STARS_PER_LAYER = 200, then 4. Then LAYERS = 8 and watch what layer * LAYER_BRIGHT does to shade when the layer number gets big. The numbers colorForeground takes stop at 255.

  2. Change the spacing. Set ACROSS_STEP to 36 and run it. The stars fall into stripes, because 36 divides into 360 exactly ten times. Put it back to 37 and try 71 and 90.

  3. Stop the twinkle. Replace the math.random line with a plain shade = layer * 70 and compare. Decide which you prefer; there is no right answer, and noticing that you have a preference is part of the job.

  4. Make them fall upward. One character.

  5. Draw the grid as well. Put the nested grid loop from earlier back in, after the stars, in a dim color. Two nested loops in one function, drawing two different things, and the second one does not disturb the first.

Break It on Purpose

Every error so far has been a message. This one is not, and that is exactly why you should meet it while you are expecting it.

Put this in your onOverlayUpdate, just under overlayClear(), run it, and read the next paragraph before you do anything else.

    x = 0
    while x < width do
        overlayPlot(x, 100)
    end

The line that moves x along is missing, so x stays at zero, so x < width never stops being true. The loop goes round forever, plotting the same pixel, and it is inside onOverlayUpdate, so onOverlayUpdate never returns. Singe is waiting for your function. It cannot draw, it cannot read the keyboard, and it cannot quit.

What you see is a window that stops moving. Escape does nothing. Q does nothing. Nothing is printed, either.

Go to the terminal you started Singe in and press Ctrl and C together. Singe stops your loop and tells you where it was:

Stopped:  the script did not return, and Singe was asked to quit.
stack traceback:
	repeating/repeating.singe:20: in function 'onOverlayUpdate'

It may say it twice, a few seconds apart, before it quits. Once is plenty. Line 20 is the end of your while, which is where the loop was going round when you stopped it. Take the loop out, save, and start Singe again.

That is a report, not an error. Nothing complained until you asked, because nothing went wrong, as far as the computer is concerned. You asked for a loop that runs while x is less than the width, and that is precisely what you got. This is the one kind of mistake the error messages cannot help you with, and the cure is a habit: every time you write a while, write the line that changes the variable before you write anything else in the body.

What You Learned

  • for name = first, last do …​ end runs its body once for each number from first to last, both included.

  • A third number is the step, and it may be negative to count down.

  • The loop variable exists only inside the loop, and the body should use it.

  • for needs a do, and every loop needs an end.

  • A loop inside a loop runs the whole inner loop for each trip round the outer one, which is how you fill a rectangle.

  • while question do …​ end repeats for as long as the question is true, and you have to change something in the body yourself.

  • Use for when you know how many times, and while when you are waiting for something to become true.

  • % is the remainder, and it keeps a growing number inside a range.

  • math.random(a, b) gives a whole number from a to b; math.floor throws away the fraction.

  • A loop that never ends freezes the whole game with no error message, and Ctrl and C in the terminal is how you get out.

Next Time

Look at that onOverlayUpdate again. It draws stars, it works out positions, it picks colors, and it is starting to be a function that does four jobs instead of one. In lesson five you write functions of your own, give them arguments the way Singe’s functions take them, and get answers back out of them — and the star field becomes one line that says drawStars().

Lesson 5: Your Own Functions

The finished lesson

Lesson four ended with a warning about your own program: onOverlayUpdate works out where a hundred and twenty stars go, decides how bright each one is, draws them, and counts the drift, and it is one function doing four jobs. It is about to be asked to do a fifth, because a star field with nothing in front of it is not a game.

In this lesson you take it apart. You will write functions of your own — functions Singe has never heard of and will never call — and hand the work to them. By the end, the whole star field is one line that says drawStars(), there is a ship back on the bottom of the screen, and the program is easier to read than it was when it did less.

Start a New Folder

A folder called functions, a file in it called functions.singe, and Singe -R functions running in a terminal.

Copy lesson four’s finished program into it. This is it, unchanged, and it is worth running once before you touch anything:

LAYERS          = 3
STARS_PER_LAYER = 40
ACROSS_STEP     = 37
DOWN_STEP       = 61
LAYER_SHIFT     = 13
LAYER_SPEED     = 0.5
LAYER_BRIGHT    = 55

width  = overlayGetWidth()
height = overlayGetHeight()

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()

    for layer = 1, LAYERS do
        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            colorForeground(shade, shade, shade)
            overlayPlot(starX, starY)
        end
    end

    return OVERLAY_UPDATED
end

Three layers of stars drifting down the window at three speeds. Nothing in the first half of this lesson changes what you see. Everything in it changes how the program reads.

One Job, One Name

Start with the two lines that put a star on the screen. Above onOverlayUpdate, add this:

function drawStar(x, y, shade)
    colorForeground(shade, shade, shade)
    overlayPlot(x, y)
end

Then, in the inner loop, delete those two lines and call it instead:

        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            drawStar(starX, starY, shade)
        end

Save. The picture is the same.

You have written functions before — onOverlayUpdate is one, and so are onInputPressed and onInputReleased from lesson three — but those are callbacks. You write them and Singe calls them. drawStar is different. Singe has never heard of it. It runs because you wrote its name and parentheses, the same way you call overlayPlot, and nothing in the world will run it unless you do.

That is the whole trick. From here on, when you find yourself thinking "and now draw a star", you can write "draw a star" and mean it.

A Parameter Is a Name, Not a Thing

Look at the first line of drawStar again.

function drawStar(x, y, shade)

The three names in the parentheses are parameters. A parameter is a name the function uses for whatever the caller handed it. When you write drawStar(starX, starY, shade), Lua sets x to whatever is in starX, y to whatever is in starY, shade to whatever is in shade, and then runs the function.

The names have nothing to do with each other. The caller’s number is called starX out there and x in here, and it would work exactly the same if you called it across or banana. Inside the function, only the names in the parentheses exist, and they hold copies of what came in.

This is where the empty parentheses from lesson one finally make sense.

function onOverlayUpdate()

Nothing in the parentheses means no parameters: the engine has nothing to tell this function, so there is nothing to name. Compare it with the callback you wrote in lesson three.

function onInputPressed(what)

One parameter, called what. The engine has something to tell this one — which control was pressed — so there is a name to catch it in. You have been using a parameter since lesson three.

A parameter really is the function’s own copy, and it is worth proving that to yourself once. Type this in, call it from onOverlayUpdate, and take it out again afterwards:

function half(number)
    number = number // 2
    return number
end

Call it as half(drift). The function halves its number and hands the answer back, and drift out in onOverlayUpdate carries on counting as though nothing had happened. A function cannot reach out and change the caller’s variables through a parameter. It gets a copy, and what it does to the copy is its own business.

Handing an Answer Back

half did something the functions you have written so far did not: it gave an answer. That is the last line.

    return number

return hands a value back to whoever called the function, and the call turns into that value. Write smaller = half(drift) and Lua runs half, takes what half returned, and puts it in smaller. You met return in lesson one, where onOverlayUpdate returns OVERLAY_UPDATED to answer Singe’s question about whether anything changed. This is the same word doing the same job, except that now you are the one asking the question.

The brightness line is begging to be a function with an answer. Add this one:

function shadeFor(layer)
    return math.random(60, 90) + layer * LAYER_BRIGHT
end

The whole body is a return, which is normal for a small function. Now the inner loop can hand the answer straight to drawStar without a name in the middle:

            drawStar(starX, starY, shadeFor(layer))

A call inside a call. Lua works the inside one out first, gets a number back from shadeFor, and passes that number to drawStar as its third argument. You have written something like it before without noticing: the math.floor(drift * layer * LAYER_SPEED) in lesson four is a call whose answer is used on the spot, in the middle of a bigger sum.

Two Answers at Once

The two position lines are harder, because they are two numbers worked out together and you would have to pick one to hand back. In most languages a function can return one value and getting two out of it is a nuisance. Lua lets you return as many as you like.

function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end

You catch the answers by putting two names on the left, separated by a comma:

            local x, y = starAt(star, layer)

First value into the first name, second into the second. If you ask for fewer names than the function returns, the extra values are thrown away: local x = starAt(star, layer) gives you the across number and loses the down one, with no complaint. If you ask for more names than there are values, the extras are nil.

Ignore the word local in those two blocks for one more minute. It has a section of its own coming, and it is the important one.

The Star Field in One Line

The inner loop is now three short lines, all of them about one layer of stars. That is a job with a name.

function drawLayer(layer)
    for star = 1, STARS_PER_LAYER do
        local x, y = starAt(star, layer)
        drawStar(x, y, shadeFor(layer))
    end
end

And the outer loop is a job with a name too:

function drawStars()
    for layer = 1, LAYERS do
        drawLayer(layer)
    end
end

Functions calling functions calling functions, three deep, and each one is three or four lines you can hold in your head at once. onOverlayUpdate can now say what a frame is:

function onOverlayUpdate()
    drift = drift + 1
    overlayClear()
    drawStars()
    return OVERLAY_UPDATED
end

That is the promise lesson four made at the end, kept.

Put the Ship Back

Now the fifth job, the one that would have made a mess of the old onOverlayUpdate. Bring back the box you steered in lesson three, this time as a ship sitting near the bottom of the screen that only moves left and right.

It needs some values of its own, up at the top with the others, and lesson three’s two input callbacks with the up and down branches taken out:

PLAYER_WIDTH  = 20
PLAYER_HEIGHT = 6
PLAYER_SPEED  = 3
PLAYER_MARGIN = 6

playerX     = width // 2
playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
movingLeft  = false
movingRight = false
function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end

Drawing it is two lines, so it is a function:

function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end

Moving it is where the lesson pays off. In lesson three, keeping the box on the screen took four lines of if and elseif for each direction. That idea — hold a number between a bottom and a top — has a name, and the name is clamp:

function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end

Three returns, and at most one of them ever happens, because return does not only hand back an answer: it stops the function dead. Nothing after it runs. If the value is under the bottom, hand back the bottom and stop. If it is over the top, hand back the top and stop. Otherwise hand back what came in.

function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end

A function that ends without a return hands back nothing, which is nil. That is right for drawPlayer and movePlayer, which are called to do something rather than to answer something. It is a bug in a function like clamp: leave off that last return value and every position in the middle of the range comes back as nil.

Where Names Live

Every name you have made since lesson two has been a global. A global belongs to the whole program: drift, playerX, and LAYERS can be read and written by any function in the file, at any moment, and they stay there for as long as the game runs.

That sounds convenient, and for six names it is. The trouble starts at sixty. Every global is a name the whole program has agreed to reserve, so when some other function wants somewhere to keep a position across the screen and calls it starX as well, the two of them are the same box, and each writes over the other’s number. When a global holds something wrong, anything in the file could have put it there, and finding out which means reading all of it.

A local is the cure. Put the word local in front of a name the first time you use it, and the name exists only inside the function, the loop, or the if it was written in.

function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end

x and y here are nobody else’s business. Another function can have its own x and the two never meet. When the x in starAt is wrong, the three lines above are the only three lines that could have done it. Without the word local, those two lines would be quietly creating two more globals, which is exactly what starX and starY have been all along.

Now the part that surprises everyone. Type this function in, and put a line in onOverlayUpdate that shows you what it hands back:

function countUp()
    local counted = 0
    counted = counted + 1
    return counted
end
    overlayPrint(0, 0, "Count: " .. countUp())

Count: 1, and it stays Count: 1 while the game runs, though that function is called sixty times a second and adds one every time. A local is made fresh when the function starts and is gone when the function ends, so counted is born as 0, becomes 1, and dies, sixty times a second, forever. A local does not remember. Take the two of them out again when you have looked at it.

That is not a flaw, it is the point: a local cannot be poisoned by the last call, because there is nothing left of the last call. When you do need to remember something between calls — drift and playerX have to remember — the name must live outside every function. Put it at the top of the file with local in front of it:

local drift   = 0
local playerX = width // 2

A local written at the top of the file, outside all the functions, lives as long as the script does and can be seen by every function below it. That last word matters: below. A local exists from its own line downwards, so a function written above the line that creates it cannot see it. The same is true of the functions themselves once you mark them local, which is why the finished script is in the order it is in: the values first, then your own functions, then the callbacks, last.

Go through the whole file now and put local in front of every name you made — the constants in capitals, width and height, drift, the player’s four values, and every one of your own functions. Three names do not get it: onInputPressed, onInputReleased, and onOverlayUpdate have to stay global, because Singe finds them by name and a local name is invisible from outside the file.

Be honest about what locals do not fix. If you mistype a name you are assigning to — movinLeft = true instead of movingLeft = true — Lua does not complain. It makes a brand new global with your typo for a name, sets it, and leaves the real one alone. Nothing moves, nothing errors, and you stare at it for ten minutes. Locals will not save you from that one. Reading the name twice will.

The Whole Thing

Here is the finished program, with every piece of the lesson in it.

local LAYERS          = 3
local STARS_PER_LAYER = 40
local ACROSS_STEP     = 37
local DOWN_STEP       = 61
local LAYER_SHIFT     = 13
local LAYER_SPEED     = 0.5
local LAYER_BRIGHT    = 55

local PLAYER_WIDTH  = 20
local PLAYER_HEIGHT = 6
local PLAYER_SPEED  = 3
local PLAYER_MARGIN = 6

local width  = overlayGetWidth()
local height = overlayGetHeight()

local drift       = 0
local playerX     = width // 2
local playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
local movingLeft  = false
local movingRight = false


local function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end


local function shadeFor(layer)
    return math.random(60, 90) + layer * LAYER_BRIGHT
end


local function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end


local function drawStar(x, y, shade)
    colorForeground(shade, shade, shade)
    overlayPlot(x, y)
end


local function drawLayer(layer)
    for star = 1, STARS_PER_LAYER do
        local x, y = starAt(star, layer)
        drawStar(x, y, shadeFor(layer))
    end
end


local function drawStars()
    for layer = 1, LAYERS do
        drawLayer(layer)
    end
end


local function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end


local function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()
    movePlayer()
    drawStars()
    drawPlayer()
    return OVERLAY_UPDATED
end

Two things are worth pointing at before you move on.

local function drawStar(x, y, shade) marks the function itself as local. Your own functions are names like any other, and they belong to this file alone. The three callbacks stay global so that Singe can find them.

And onOverlayUpdate is now six lines that say what a frame is: count the drift, clear the screen, move the player, draw the sky, draw the player, done. It does five jobs by naming five things that do one job each, which is the shape of every game loop you will ever write.

A Function Is a Name for an Idea

clamp is called once. Pulling it out saved no typing at all — four lines came out, one went in, and a nine line function appeared elsewhere. It was still worth doing.

A function is not only a way to avoid repeating yourself. It is a way to give a name to an idea, so that the code using the idea can say the name and move on. "Keep the player between the left edge and the right edge" is a thought you had once. clamp(playerX, 0, width - PLAYER_WIDTH - 1) is that thought, written down. Four if statements are the same thought taken apart into pieces you have to put back together in your head every time you read them.

When you are deciding whether something deserves to be a function, do not ask how many times you will call it. Ask whether it has a name.

Try It

  1. Rename a parameter. In drawStar, change x and y to across and down, everywhere inside the function. Do not touch anything outside it. Run it. Work out why nothing broke.

  2. Draw them the other way round. Swap drawStars() and drawPlayer() in onOverlayUpdate and look at the ship. Then put them back. Each of those five lines is one job, and their order on the screen is their order in the function.

  3. Use clamp on a shade. Change shadeFor to return clamp(math.random(60, 90) + layer * 90, 0, 200) and look at the three layers. Then take the clamp out and look again: colorForeground was quietly holding the numbers down for you all along, and now you can see where.

  4. Call drawStar with two arguments. Write drawStar(100, 100) somewhere in drawLayer and run it. The error names the exact thing that went missing. Read it before you put the third argument back.

  5. Move a local. Take the line local drift = 0 and move it to the bottom of the file, below everything. Run it, read the error, and think about the word "below" in the section above.

Break It on Purpose

The order of a file with locals in it matters, and the error you get when you break that order is not the one you expect.

Take the whole drawStar function and move it to the bottom of the script, below onOverlayUpdate. Everything is still there, spelled the same. Run it:

Error executing function 'onOverlayUpdate':  functions/functions.singe:50: attempt to call a nil value (global 'drawStar')
stack traceback:
	functions/functions.singe:50: in upvalue 'drawLayer'
	functions/functions.singe:57: in upvalue 'drawStars'
	functions/functions.singe:101: in function 'onOverlayUpdate'

This looks different from the error in lesson one because it is a different kind of error. Lesson one’s mistake was caught before the script ran. This one was caught while it was running, which is why Singe names the function it was in the middle of, and why there is a traceback underneath: the list of who called whom, newest first. Line 50 is inside drawLayer, which was called from line 57 inside drawStars, which was called from line 101 inside onOverlayUpdate. Your line numbers will differ if your file does not match the one above exactly, and the engine may add a line or two of its own below these. The word upvalue is Lua’s name for a local that a function borrowed from the file around it; read past it for now.

The complaint itself is worth learning by heart. "Attempt to call a nil value" means you put parentheses after a name that held nothing. The word global in front of drawStar is the part that gives the game away: you marked drawStar as local, so when Lua read drawLayer and found no local of that name anywhere above it, the only thing left to try was a global — and there is no global called drawStar either. Put the function back above the code that calls it and the error goes with it.

What You Learned

  • You can write functions of your own, and nothing runs them but your own calls.

  • The names inside a function’s parentheses are parameters, and they are the function’s own copies of what the caller passed.

  • return hands a value back and stops the function where it stands, and a function that ends without one hands back nil.

  • A call can be an argument to another call, and the inside one happens first.

  • Lua can return more than one value, and you catch them with several names separated by commas.

  • local makes a name that exists only where it was written.

  • A local inside a function is made fresh on every call and remembers nothing from the last one.

  • A local can only be seen below the line that creates it, so values and your own functions go above the callbacks that use them.

  • Callbacks stay global, because Singe finds them by name.

  • A function is worth writing when the thing it does has a name, even if you call it once.

Next Time

Your hundred and twenty stars are still a hundred and twenty copies of three ideas. Nothing in the program is a star: there is a number, and some arithmetic that turns the number into a position. You cannot say "this one is nearer, so it falls faster and shines brighter", because there is no "this one" to say it about, and you cannot let a star fall off the bottom and be replaced by a new one, because there is nothing there to remove.

Lesson six gives you the thing that holds a star, and then a way to hold a hundred and twenty of them and add a hundred and twenty-first while the game is running. It is the most useful lesson in this part of the book.

Lesson 6: Lists of Things

The finished lesson

You have a hundred and twenty stars and not one of them exists. There is no star anywhere in your program: there is a loop that runs a hundred and twenty times, and each time round it works out two numbers from the star’s number and its layer, plots a pixel, and forgets everything. The three layers are there to fake the one thing that arrangement cannot do, which is let a star be different from its neighbor.

This lesson gives you the missing thing. You will learn how to keep a list of items, how to make one item that holds several named values at once, and then how to put the two together into a list of items that each remember their own position, speed, and brightness. It is the longest lesson in this part of the book and the one everything afterwards leans on. Take your time with it.

Start a New Folder

A folder called tables, a file in it called tables.singe, and Singe -R tables running in a terminal. Copy lesson five’s finished program into it: the star field, the ship, and all.

A List

Add this line at the top of tables.singe, under the other values, and the three overlayPrint calls to onOverlayUpdate above the return.

local names = { "Ada", "Grace", "Alan" }
    overlayPrint(2, 2, names[1])
    overlayPrint(2, 3, names[3])
    overlayPrint(2, 4, "There are " .. #names .. " names.")

Run it. Ada on one line, Alan on the next, and There are 3 names. under them.

The braces on the first line make a table. A table is the one container Lua has, and everything you will ever store more than one of goes in one. Here it is holding three strings in a row, which is the shape people call a list.

The brackets on the next lines take an item out. names[1] is the first item, names[3] is the third, and the number in the brackets is called the index.

That number is where Lua parts company with almost every other language you will meet. Lua counts from one. C, Java, Python, JavaScript, and most of the rest count from zero, so their first item is item zero and their third item is index two. Lua’s first item is item one, and this is the single thing that trips up programmers arriving from somewhere else. You are arriving from nowhere, so you have the easier job: the first one is number one.

names[0] is not an error, by the way. It is nil — the nothing value from lesson three — because there is nothing stored there. Reading an index that was never filled always gives nil, which is a kindness right up until you try to use it.

The # in front of a table’s name is the last new punctuation for a while. It hands you how many items are in the list, so #names is 3. Because the count and the last index are the same number, names[#names] is always the last item, however long the list gets.

Adding and Taking Away

A list you have to write out in full is not much use to a game. These two calls are how a list changes while the program runs.

    table.insert(names, "Katherine")

That puts Katherine on the end, and #names is now 4. table.insert is a function like any other, and the dot in the middle of its name means it lives inside a table called table that Lua provides — a table of functions for working on tables. You do not have to make it or load it. It is there.

Give table.insert three arguments and the middle one is where to put the new item.

    table.insert(names, 1, "Edsger")

Edsger goes in at the front, and everything that was already there shuffles along to make room: Ada was item one and is now item two. Nothing is overwritten and nothing is lost.

Taking an item out is the mirror image.

    table.remove(names, 2)

Item two goes, and everything after it shuffles back down to close the gap, so the list never has a hole in the middle. table.remove also hands back the item it took out, so local gone = table.remove(names, 2) gets rid of it and tells you what it was in one line. Leave the number off altogether — table.remove(names) — and it takes the last item, which is the quickest way to use a list as a pile.

Put those three calls in your script, one at a time, run it after each, and watch the count on the third line change.

Walking a List

You know one way to visit every item, because you have been using it since lesson four:

    for i = 1, #names do
        overlayPrint(2, i + 1, names[i])
    end

That works. Start at one, stop at the count, use the counter as the index. There is a better way, and it is the way you will write from now on:

    for i, name in ipairs(names) do
        overlayPrint(2, i + 1, name)
    end

ipairs walks a list from item one until it runs out, and hands your loop two things each time round: the index and the item itself. That second one is the point. With the numeric for you get a number and have to go back to the table with names[i] to find out what it is; with ipairs the item is already in your hand, under whatever name you put second.

It is also harder to get wrong. for i = 1, #names is a place to make an off-by-one mistake — start at nought and you print a nil, stop at #names - 1 and you lose the last one — and ipairs has no numbers in it at all to get wrong.

Most of the time you do not want the index, only the item. Write the index as a single underscore and be done with it:

    for _, name in ipairs(names) do

_ is a perfectly ordinary name, and nothing in Lua treats it specially. It is a habit programmers share for saying "something arrives here and I am not going to use it". Anybody reading your loop knows at a glance that the index does not matter in it.

Delete the names experiments now, and the overlayPrint lines with them. You know what a list is. Time to put something better than a string in one.

A Table Can Also Be a Record

A star needs to remember four things: where it is across, where it is down, how fast it falls, and how bright it is. Four separate lists, all kept in step by hand, would be miserable. Instead, make a table and put names inside it.

    local star = {}
    star.x = 40
    star.y = 0
    star.speed = 2
    star.shade = 180

The empty braces make an empty table. The four lines after it put values into it under names instead of numbers, and the dot is how you say which name you mean. star.x is read as the x of star, and it behaves exactly like any other variable: read it, assign to it, add to it.

    star.y = star.y + star.speed

A table used this way — a fixed set of named values describing one thing — is a record, and the names inside it are its fields. It is the same kind of table as the list above. The only difference is that a list’s items are found by number and a record’s fields are found by name, and one table can do both at once if you ever want it to.

The dot is a shorthand. star.x and star["x"] mean exactly the same thing, which is worth seeing once: the brackets take a name as happily as they take a number, so a list and a record really are one idea wearing two hats. Use the dot. It reads better.

A field you never set is nil, the same as an index you never filled. There is no list of allowed field names anywhere, and nothing checks your spelling, so star.sped is not an error — it is nil, and you will meet what happens next at the end of this lesson.

Writing four lines to fill in four fields gets old. You can put the fields inside the braces when you make the table:

    local star = {
        x     = 40,
        y     = 0,
        speed = 2,
        shade = 180
    }

Same table, one statement. The commas separate the fields, the last one needs no comma after it, and the lines are spread out only to be read easily.

A List of Records

Here is the whole idea of this lesson in two lines:

    local stars = {}
    table.insert(stars, star)

A list can hold anything, and that includes a table. So a list of records is a list of things, each of which remembers everything about itself. stars[1] is a whole star, and stars[1].y is that star’s distance down the screen. Nearly every game you will ever write is a handful of lists like this one: the enemies, the bullets, the pickups, and the falling blocks.

There is one thing about tables you must know before you write the code, and it catches everybody once. Handing a table to a function does not copy it. A number gets copied — that is why half could chop up its number in lesson five without disturbing drift — but a table is shared. Both names refer to the same table, and a change made through one is visible through the other.

    local star = stars[3]
    star.y = star.y + 1

That moves the third star in the list. Not a copy of it: it. This is exactly what you want here, and it is what makes the next section work, but remember it when a function you wrote changes something you did not expect it to.

Rebuild the Star Field

Out goes the arithmetic. A star is about to become a thing.

Delete starAt, shadeFor, drawLayer, and the old drawStar, and with them the constants they used: LAYERS, STARS_PER_LAYER, ACROSS_STEP, DOWN_STEP, LAYER_SHIFT, and LAYER_SPEED. The variable drift goes too, and so does the drift line at the top of onOverlayUpdate. LAYER_BRIGHT stays, under a name that no longer mentions layers, and two values join it:

local STAR_COUNT  = 120
local STAR_SHADE  = 55
local BURST_COUNT = 10
local stars = {}

A hundred and twenty is what you had: three layers of forty. The list starts empty, and this is what fills it:

local function newStar(y)
    local speed = math.random(1, 3)
    local star  = {
        x     = math.random(0, width - 1),
        y     = y,
        speed = speed,
        shade = math.random(60, 90) + speed * STAR_SHADE
    }
    return star
end

newStar makes one star and hands it back. Look at the last field and compare it with shadeFor in lesson five: the same sum, with the star’s own speed where the layer number used to be. The layers have not gone away so much as dissolved. Every star now picks its own speed, one, two, or three pixels a frame, and a star that falls faster is brighter, which is the whole of the illusion of depth and costs one line.

The starting y is a parameter because the two callers want different things. The stars made when the game starts should be scattered all over the screen; the ones made later come in at the top.

local function makeStars()
    for number = 1, STAR_COUNT do
        table.insert(stars, newStar(math.random(0, height - 1)))
    end
end

Nothing calls makeStars yet. Add one line at the very bottom of the file, after everything else and inside no function at all:

makeStars()

There is more to say about that line, and it waits until the end of the lesson. Now the drawing, which gets shorter every time you touch it:

local function drawStar(star)
    colorForeground(star.shade, star.shade, star.shade)
    overlayPlot(star.x, star.y)
end


local function drawStars()
    for _, star in ipairs(stars) do
        drawStar(star)
    end
end

drawStar took three numbers in lesson five and takes one star now. Everything it needs to know is inside the star, which is the reason to have records at all: one thing to pass around instead of four, and no chance of handing them over in the wrong order. And drawStars has lost its loop over layers, along with any interest in how many stars there are or where they came from.

Stars That Come and Go

Now the part the old star field could not do at all. Stars fall at their own speeds, leave at the bottom, and are replaced at the top.

local function moveStars()
    for i = #stars, 1, -1 do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end
    while #stars < STAR_COUNT do
        table.insert(stars, newStar(0))
    end
end

Call it from onOverlayUpdate, on the line where drift = drift + 1 used to be.

Each star moves down by its own speed, which is the line lesson five could not write. The while at the bottom is the refill: while there are fewer than a hundred and twenty stars, make another one at the top of the screen. It runs as many times as it needs to and then stops, which is the right tool when you do not know how many are missing.

The for line at the top counts down, using the step you met in lesson four. for i = #stars, 1, -1 visits the last item first and works back to item one. That is not a flourish. It is the only safe way to do what this loop does, and the next section is why.

Never Remove Going Forwards

Write the same loop forwards and it is broken:

    for i = 1, #stars do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end

Follow it by hand with four stars, and suppose stars two and three have both reached the bottom.

  • i is 1. Star one is fine.

  • i is 2. Star two is off the bottom, so out it goes. Everything shuffles down: the star that was three is now two, and the star that was four is now three.

  • i is 3. That is the star that used to be four. Star three was never looked at. Removing item two moved it down into slot two, and the loop had already been to slot two and gone.

  • i is 4. There is no item four any more. stars[4] is nil.

Two separate faults from one small mistake. Items get skipped, so a star that had reached the bottom is not even looked at this time round. A star surviving one extra frame does no harm, and the same loop over a list of enemies, where being looked at is what kills them, is a bug you would chase for an hour. The second fault is louder. The list is now shorter than the count the loop started with, because #stars was worked out once, before any removal, so the last turns of the loop reach past the end of the list:

Error executing function 'onOverlayUpdate':  tables/tables.singe:60: attempt to index a nil value (local 'star')
stack traceback:
	tables/tables.singe:60: in upvalue 'moveStars'
	tables/tables.singe:124: in function 'onOverlayUpdate'

"Attempt to index a nil value" means you put a dot after something that held nothing. The (local 'star') on the end names it: star was nil, so star.y had nowhere to look.

Going backwards fixes both faults at once, and it is worth seeing why rather than taking it on trust. When you remove item i, everything after i moves down a slot — and going backwards, everything after i is everything you have already visited. What is still to come, items i - 1 down to 1, has not moved at all. The list shrinking behind you cannot hurt you either, because you are walking towards item one and item one is always there.

The rule, which you will use for the rest of your life: when a loop might remove items from the list it is walking, walk it backwards.

ipairs is not an exception to this. Removing items in the middle of an ipairs loop goes wrong in the same way. ipairs is for looking, and the backwards for is for changing.

Add Some Yourself

One more branch in onInputPressed and you can watch the list grow while the game runs. This goes with the other two:

    elseif what == SWITCH_BUTTON1 then
        addBurst()
local function addBurst()
    for number = 1, BURST_COUNT do
        table.insert(stars, newStar(0))
    end
end

addBurst goes above the callbacks with your other functions. And so that you can see the list’s length change, put the count on screen in onOverlayUpdate:

    overlayPrint(0, 0, "Stars: " .. #stars)

Press the button — the space bar, unless you have changed what SWITCH_BUTTON1 comes from — a dozen times. The count goes up by ten each press and the sky thickens, and there is no repeat while you hold it down: onInputPressed is told once, when the button goes down. Then watch the count come back to a hundred and twenty on its own as the extra stars reach the bottom and are removed, because the refill only ever tops the list up to STAR_COUNT and never trims it.

Nothing in the drawing, the moving, or the removing had to be told that the number of stars had changed. They all work from the list.

The Whole Thing

local STAR_COUNT  = 120
local STAR_SHADE  = 55
local BURST_COUNT = 10

local PLAYER_WIDTH  = 20
local PLAYER_HEIGHT = 6
local PLAYER_SPEED  = 3
local PLAYER_MARGIN = 6

local width  = overlayGetWidth()
local height = overlayGetHeight()

local stars       = {}
local playerX     = width // 2
local playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
local movingLeft  = false
local movingRight = false


local function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end


local function newStar(y)
    local speed = math.random(1, 3)
    local star  = {
        x     = math.random(0, width - 1),
        y     = y,
        speed = speed,
        shade = math.random(60, 90) + speed * STAR_SHADE
    }
    return star
end


local function makeStars()
    for number = 1, STAR_COUNT do
        table.insert(stars, newStar(math.random(0, height - 1)))
    end
end


local function addBurst()
    for number = 1, BURST_COUNT do
        table.insert(stars, newStar(0))
    end
end


local function moveStars()
    for i = #stars, 1, -1 do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end
    while #stars < STAR_COUNT do
        table.insert(stars, newStar(0))
    end
end


local function drawStar(star)
    colorForeground(star.shade, star.shade, star.shade)
    overlayPlot(star.x, star.y)
end


local function drawStars()
    for _, star in ipairs(stars) do
        drawStar(star)
    end
end


local function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end


local function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    elseif what == SWITCH_BUTTON1 then
        addBurst()
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    overlayClear()
    movePlayer()
    moveStars()
    drawStars()
    drawPlayer()
    overlayPrint(0, 0, "Stars: " .. #stars)
    return OVERLAY_UPDATED
end


makeStars()

What Just Happened

The program is shorter than lesson five’s and it does something lesson five could not begin to do. Three pieces are worth a second look.

makeStars()

That single line at the very bottom of the file is not inside any function, and it is easy to miss. Lua reads your file from top to bottom when Singe loads it, and a line at the outer level of the file runs there and then, once, before the engine has called anything. Everything above it is definitions — here is a value, here is a function — and this is the one instruction that happens at load time. It has to be at the bottom, because makeStars does not exist until the line that creates it has been read.

        local star = stars[i]
        star.y = star.y + star.speed

star is a local made fresh on every turn of the loop, and it holds the same table that is sitting in the list — not a copy of it. Changing star.y moves the star that is in the list. If tables were copied, this loop would move a hundred and twenty copies a frame and nothing on screen would ever change.

    for _, star in ipairs(stars) do
        drawStar(star)
    end

Compare that with lesson four: two nested loops, two pieces of arithmetic per star, a remainder to keep each one on the screen, and three layers to fake the variety you now get for nothing. The drawing no longer knows or cares how the stars got where they are, how many there are, or what happens to them next. Each part of the program does one job, and the list is what they all agree about.

Try It

  1. Make it deeper. Change math.random(1, 3) to math.random(1, 6) and STAR_SHADE to 25. More speeds, more shades, a deeper sky.

  2. Fewer stars, bigger burst. Set STAR_COUNT to 10 and BURST_COUNT to 100, then press the button three or four times. Watch the count on screen climb, and time how long it takes to drain.

  3. Give a star another field. Add age = 0 to newStar, add one to star.age in moveStars, and put stars[1].age on screen next to the count. Nothing else in the program needs changing to carry a new fact about every star.

  4. Stop removing them. Delete the three lines of the if star.y >= height block from moveStars and run it. Wait ten seconds, then read the count on screen and look at the sky. Work out how both of those can be true at once.

  5. Do it forwards. Change for i = #stars, 1, -1 to for i = 1, #stars and run it until it falls over. Then read the section above again with the real error in front of you.

Break It on Purpose

Misspell a field name. In moveStars, change star.speed to star.sped:

        star.y = star.y + star.sped

Run it:

Error executing function 'onOverlayUpdate':  tables/tables.singe:60: attempt to perform arithmetic on a nil value (field 'sped')
stack traceback:
	tables/tables.singe:60: in upvalue 'moveStars'
	tables/tables.singe:124: in function 'onOverlayUpdate'

Your line numbers will not be exactly these unless your file matches the one above line for line. The name of the file, the number after it, and the complaint are what you read.

Read the end of the first line first. field 'sped' is Lua telling you which name came up empty, and it is telling you it was a field — something after a dot — rather than a variable of your own. "Attempt to perform arithmetic on a nil value" is what it was doing when it found out: adding nil to a number, which cannot be done.

There was no complaint when the table was made without a sped field, and none at the moment you asked for it. A table hands out nil for any name it does not have, without comment. The error comes later, at the first line that tries to use the nothing you were given, which may be a long way from the typo. When you see nil value (field 'something'), look for the place that name was spelled differently.

What You Learned

  • Braces make a table, the one container Lua has. A table used as a list holds items in a row, and brackets with an index take one out.

  • Lua counts from one. Most other languages count from zero.

  • #list is how many items are in it, and list[#list] is the last one.

  • table.insert adds an item, on the end or at a position you name; table.remove takes one out and closes the gap.

  • An index or a field that was never filled is nil, and nothing warns you until you use it.

  • ipairs walks a list and hands you the index and the item; _ is the habit for an index you do not want.

  • A table used as a record holds named fields, reached with a dot.

  • A list of records is how a game holds its enemies, its bullets, and everything else there is more than one of.

  • Tables are shared, not copied, when you pass them around.

  • When a loop may remove items from the list it is walking, walk it backwards.

Next Time

You have every piece of a game now: things that move, a ship that answers the controls, decisions, loops, functions, and a list that things can join and leave while the game is running.

Lesson seven puts them together into a game you can lose. You steer along the bottom of the screen, blocks fall from the top, and you stay out of their way — and the falling blocks are a list of records, made, moved, and removed exactly as your stars are.

Lesson 7: A Game

The finished lesson

Six lessons ago you put one word on a black screen. Since then you have learned every idea a small game is made of: variables, decisions, loops, functions of your own, and lists of things. This lesson does not teach a new idea. It spends the ones you have.

You are going to build a game called Dodge. Blocks fall out of the sky, you slide a bar along the bottom to get out of their way, and every block that misses you is a point. Hit three of them and it is over. You will build it in six stages, and every one of them runs: you never have to type a hundred lines and hope.

Make the Folder

Make a folder called dodge, and in it a file called dodge.singe. Run it the way you have been running everything since lesson one:

Singe -R dodge

Leave that running in a terminal for the whole lesson. Every time you save, the game restarts with your change in it.

Stage One: Something You Can Steer

Type this in, save, and steer it with the left and right arrow keys.

dofile("Singe/Framework.singe")

local PLAYER_WIDTH  = 40
local PLAYER_HEIGHT = 8
local PLAYER_SPEED  = 4
local PLAYER_MARGIN = 4

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local playerY      = screenHeight - PLAYER_HEIGHT - PLAYER_MARGIN

local playerX    = (screenWidth - PLAYER_WIDTH) / 2
local goingLeft  = false
local goingRight = false


function onInputPressed(what)
    if what == SWITCH_LEFT then
        goingLeft = true
    elseif what == SWITCH_RIGHT then
        goingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goingLeft = false
    elseif what == SWITCH_RIGHT then
        goingRight = false
    end
end


function onOverlayUpdate()
    if goingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if goingRight then
        playerX = playerX + PLAYER_SPEED
    end
    if playerX < 0 then
        playerX = 0
    elseif playerX > screenWidth - PLAYER_WIDTH then
        playerX = screenWidth - PLAYER_WIDTH
    end

    overlayClear()
    colorForeground(80, 255, 160)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH - 1, playerY + PLAYER_HEIGHT - 1)
    return OVERLAY_UPDATED
end

Fifty lines, and almost none of it is new. Two things in it are, so take the first line first.

dofile("Singe/Framework.singe")

dofile belongs to Lua rather than to Singe, and it means "go and run that file, then carry on here". The file it runs is Singe/Framework.singe, one of the files the engine unpacked into your work folder the first time you ran anything, back in lesson one. Open it in your text editor and look: it is ordinary Lua, no different in kind from what you have been writing since lesson two, and there is nothing magic in it.

Running it hands your script a set of names it can then use. The ones this book reaches for are these:

  • DIR, which holds the folder your own script is sitting in. Lesson nine needs it the moment a game loads a picture, and it is the real reason this line is here.

  • SCANCODE and MODIFIER, names for every key on a keyboard, for a game that reads typing rather than a joystick.

  • GAMEPAD_0 to GAMEPAD_3 and MOUSE_0 to MOUSE_3, for a cabinet with more than one of something plugged into it.

  • A few helpers whose names begin with util, and the six calls that post a score to a leaderboard, which is lesson twenty-eight.

  • The second way of writing a game altogether, which is lesson fifteen.

One thing it does not give you, because it is the natural thing to assume. SWITCH_LEFT, and every other name beginning with SWITCH_, comes from the engine itself, before any script runs at all. That is why lessons three to six could read the arrow keys without loading anything. The framework adds to what is already there; it does not provide it.

This particular game uses nothing from the framework. The line is here because every game from lesson nine to the end of the book does need it, and because it is how nearly every real Singe game starts. It is read once, at startup, and then forgotten about.

The second new thing is the way the arrow keys are handled, because it is the first thing beginners get wrong.

onInputPressed does not move the player. It sets goingLeft to true, and onInputReleased sets it back to false. The moving happens in onOverlayUpdate, which asks "is the player holding left?" sixty times a second. If you moved the player inside onInputPressed instead, you would get one step per press: Singe sends a press exactly once when the key goes down and never repeats it, which the reference’s entry for onInputPressed says plainly. Holding the key would do nothing at all.

So the press handler records what is true about the world, and the update decides what to do about it. Keep that split and your input code will stay five lines long forever.

The four names in capitals are ordinary variables. Writing PLAYER_SPEED in capitals is a message to yourself and to anyone reading: this one is set once at the top and never changes. Nothing in Lua enforces it. It matters because in a minute there will be ten of them, and when the game is too hard you want one obvious place to go and turn a number down.

screenWidth and screenHeight come from the engine rather than being typed in, so the game lays itself out to whatever size the overlay happens to be. playerY is worked out once from the height: the bar sits PLAYER_MARGIN pixels off the bottom and never moves up or down, so there is no reason to compute it again every frame.

The - 1 in the overlayBox line is not a typo. overlayBox draws through both corners you give it, so a box from playerX to playerX + 40 is forty-one pixels wide. Subtracting one makes the bar you see exactly forty wide, which will matter in stage four when something has to decide whether it touched you.

Stage Two: Something to Dodge

One block, falling. Add two constants to the list at the top:

local BLOCK_SIZE    = 12
local BLOCK_SPEED   = 1.5

Two more variables under goingRight:

local blockX     = math.random(0, screenWidth - BLOCK_SIZE)
local blockY     = -BLOCK_SIZE

In onOverlayUpdate, just above the overlayClear() line, make it fall:

    blockY = blockY + BLOCK_SPEED
    if blockY > screenHeight then
        blockX = math.random(0, screenWidth - BLOCK_SIZE)
        blockY = -BLOCK_SIZE
    end

And under the line that draws the player, draw it:

    colorForeground(255, 90, 90)
    overlayBox(blockX, blockY, blockX + BLOCK_SIZE - 1, blockY + BLOCK_SIZE - 1)

Save. A red square falls, reaches the bottom, and reappears at the top in a new place.

It starts at -BLOCK_SIZE, which is above the top edge of the screen. There is nothing wrong with a negative position: the engine draws the part of the box that is on the overlay and quietly throws away the part that is not. The block slides into view instead of popping into existence.

BLOCK_SPEED is 1.5, not a whole number, so blockY spends most of its life being something like 83.5. That is fine too. Drawing chops the fraction off, and keeping it in the variable is what lets the block move slower than one pixel a frame.

Stage Three: A Sky Full of Them

One block is not a game. In lesson six you learned to keep many of something in a list, and this is what it was for.

Delete blockX and blockY, and put these in their place:

local blocks     = {}
local spawnTimer = 0

Add one more constant at the top:

local SPAWN_FRAMES  = 40

Now a function that makes one block and puts it in the list. Put it above onInputPressed:

function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    block.y = -BLOCK_SIZE
    table.insert(blocks, block)
end

Replace the falling code from stage two with this:

    spawnTimer = spawnTimer - 1
    if spawnTimer <= 0 then
        spawnBlock()
        spawnTimer = SPAWN_FRAMES
    end

    for i = #blocks, 1, -1 do
        local block = blocks[i]
        block.y = block.y + BLOCK_SPEED
        if block.y > screenHeight then
            table.remove(blocks, i)
        end
    end

And replace the one line that drew the block with a loop over all of them:

    for i, block in ipairs(blocks) do
        overlayBox(block.x, block.y, block.x + BLOCK_SIZE - 1, block.y + BLOCK_SIZE - 1)
    end

Save. Blocks rain down.

A block is a record: one little table with an x and a y in it, which is how you keep two numbers that belong together from drifting apart. blocks is a list of those records, which is the shape almost every game’s world has.

spawnTimer counts down one per frame, and when it reaches zero a block is born and the timer is wound back up. Forty frames is about two thirds of a second. There is no clock in this game and there does not need to be one: onOverlayUpdate is the heartbeat, and counting heartbeats is a perfectly good way to measure time.

The falling loop runs backwards — from #blocks down to 1, a step at a time — because it removes things as it goes. That is the rule from lesson six, and this is the first time you have had a real reason to obey it. Remove item three while walking forwards and everything shuffles down one, so the block that was item four is now item three and the loop never looks at it. Walking backwards, everything that moves has already been dealt with.

The drawing loop uses ipairs instead, because it removes nothing and only wants each block in turn.

Stage Four: Getting Hit

The blocks fall straight through you. Time to notice.

The engine has a function for exactly this question. Change the test inside the falling loop from this:

        if block.y > screenHeight then
            table.remove(blocks, i)
        end

to this:

        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) or block.y > screenHeight then
            table.remove(blocks, i)
        end

Save, and drive the bar into a falling block. It vanishes.

collideRects takes two rectangles and answers true if they overlap. Each rectangle is four numbers: a corner, then a width and a height — not two corners, which is the other reasonable way to describe a rectangle and the way overlayBox does it. The reference’s entry for collideRects gives the order, and it is worth looking at now, because getting the eight arguments in the wrong order is the kind of mistake that produces no error at all, just a game where nothing ever hits anything.

You could write this yourself. It is four comparisons, and it is genuinely not hard. Use the engine’s anyway, for three reasons. It is right, including the awkward cases: a rectangle with no width, two rectangles that only touch along an edge. It says what it means, so the line reads as "did these two overlap" instead of four comparisons joined by and that you have to decode every time you come back to it. And when you reach lesson eleven, where things hit each other constantly, you will already know the family: collidePointRect for a mouse click, collideCircles for two round things, and collideSegments for a shot against a wall. The reference lists them together.

The one thing the engine cannot do for you is decide what a rectangle means. The block’s rectangle here is the whole block. In a real game you often want the hit rectangle to be a little smaller than the picture, so a near miss feels like a near miss. That is a design decision, and lesson eleven is where you make it.

Stage Five: Score and Lives

Getting hit should cost something, and surviving should be worth something.

Two more constants at the top:

local BLOCK_FASTER  = 0.05
local START_LIVES   = 3

Three more variables, next to spawnTimer:

local blockSpeed = BLOCK_SPEED
local score      = 0
local lives      = START_LIVES

BLOCK_SPEED is now the speed the game starts at, and blockSpeed is the speed it is going at right now. Change the falling line to use the variable:

        block.y = block.y + blockSpeed

Then split the two cases apart, because they now do different things:

        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) then
            table.remove(blocks, i)
            lives = lives - 1
        elseif block.y > screenHeight then
            table.remove(blocks, i)
            score      = score + 1
            blockSpeed = blockSpeed + BLOCK_FASTER
        end

And show the numbers. Put this just before the return:

    overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)

Save, and play it for a minute. It gets harder, which is the whole trick: every block you dodge makes the next ones fall a twentieth of a pixel per frame faster. Twenty points in and they are noticeably quicker. You did not have to write a single word about difficulty levels.

You will also watch LIVES go to -4, because nothing stops the game yet. That is the next stage, and it is the one that matters most.

Stage Six: Game Over, and Going Again

Here is the trap. The obvious way to add a game over screen is a variable called gameOver, set to true when the lives run out. Then you want a title screen before the first game, so you add started. Then you want a pause key, so you add paused. Now you have three true-or-false variables, eight combinations between them, and five of those combinations are nonsense that your code has to be careful never to produce. Every beginner writes this game at least once, and it is where small games go to die.

Do this instead. One variable holds what the game is doing, as a word:

local state      = "waiting"

It is "waiting" before the first game, "playing" during one, and "over" when the lives are gone. Three states, one variable, and no such thing as an impossible combination. There is nothing magic about the strings; they are words you chose, and you must spell them the same way every time.

Now the function that begins a game. Every variable a game owns goes back to its starting value here, in one place:

function startGame()
    playerX    = (screenWidth - PLAYER_WIDTH) / 2
    blocks     = {}
    blockSpeed = BLOCK_SPEED
    spawnTimer = 0
    score      = 0
    lives      = START_LIVES
    state      = "playing"
end

Losing the last life ends it. Inside the collision branch, under lives = lives - 1:

            if lives == 0 then
                state = "over"
            end

The space bar starts a game, but only when one is not already running. Add an arm to onInputPressed:

    elseif what == SWITCH_BUTTON1 and state ~= "playing" then
        startGame()

~= is "is not equal to". state ~= "playing" is true while waiting and true while over, which are exactly the two moments when space should start a game. SWITCH_BUTTON1 is the space bar by default, and also the A button on a controller.

Two small functions put the words on screen. printCentered does the arithmetic once so that the title and game over screens do not each do it badly:

function drawOverText()
    printCentered(7, "GAME OVER")
    printCentered(9, "PRESS SPACE TO PLAY AGAIN")
end


function drawWaitingText()
    printCentered(6, "DODGE THE BLOCKS")
    printCentered(8, "ARROW KEYS TO MOVE")
    printCentered(10, "PRESS SPACE TO START")
end


function printCentered(row, text)
    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)
end

with one more constant at the top:

local TEXT_COLUMNS  = overlayGetWidth() // overlayGetFontWidth()

Finally, the important part. Move everything that draws out of onOverlayUpdate into a function called drawGame, move everything that moves into a function called updatePlaying — both of them are in the full listing below — and leave onOverlayUpdate looking like this:

function onOverlayUpdate()
    if state == "playing" then
        updatePlaying()
    end

    overlayClear()
    drawGame()
    if state == "waiting" then
        drawWaitingText()
    elseif state == "over" then
        drawOverText()
    end

    return OVERLAY_UPDATED
end

Save. You have a game: a title screen, a game, a game over, and a way back round.

Read those thirteen lines again, because they are the shape of every game you will ever write. The world only moves while the state is "playing", so the game over screen freezes with the last blocks hanging exactly where they were. The world is drawn every frame whatever the state, because the picture is the same in all three; the state decides only what words go on top of it. And there is precisely one place that makes that decision.

That is what you bought with the state variable. When you add a pause, you add one arm to that if and one line to onInputPressed, and nothing else in the game needs to know a thing about it.

The Whole Thing

Here it is, finished. If yours does not match, the difference is worth finding.

dofile("Singe/Framework.singe")

local PLAYER_WIDTH  = 40
local PLAYER_HEIGHT = 8
local PLAYER_SPEED  = 4
local PLAYER_MARGIN = 4
local BLOCK_SIZE    = 12
local BLOCK_SPEED   = 1.5
local BLOCK_FASTER  = 0.05
local SPAWN_FRAMES  = 40
local START_LIVES   = 3
local TEXT_COLUMNS  = overlayGetWidth() // overlayGetFontWidth()

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local playerY      = screenHeight - PLAYER_HEIGHT - PLAYER_MARGIN

local playerX    = (screenWidth - PLAYER_WIDTH) / 2
local goingLeft  = false
local goingRight = false
local blocks     = {}
local blockSpeed = BLOCK_SPEED
local spawnTimer = 0
local score      = 0
local lives      = START_LIVES
local state      = "waiting"


function drawGame()
    colorForeground(80, 255, 160)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH - 1, playerY + PLAYER_HEIGHT - 1)
    colorForeground(255, 90, 90)
    for i, block in ipairs(blocks) do
        overlayBox(block.x, block.y, block.x + BLOCK_SIZE - 1, block.y + BLOCK_SIZE - 1)
    end
    overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)
end


function drawOverText()
    printCentered(7, "GAME OVER")
    printCentered(9, "PRESS SPACE TO PLAY AGAIN")
end


function drawWaitingText()
    printCentered(6, "DODGE THE BLOCKS")
    printCentered(8, "ARROW KEYS TO MOVE")
    printCentered(10, "PRESS SPACE TO START")
end


function printCentered(row, text)
    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)
end


function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    block.y = -BLOCK_SIZE
    table.insert(blocks, block)
end


function startGame()
    playerX    = (screenWidth - PLAYER_WIDTH) / 2
    blocks     = {}
    blockSpeed = BLOCK_SPEED
    spawnTimer = 0
    score      = 0
    lives      = START_LIVES
    state      = "playing"
end


function updatePlaying()
    if goingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if goingRight then
        playerX = playerX + PLAYER_SPEED
    end
    if playerX < 0 then
        playerX = 0
    elseif playerX > screenWidth - PLAYER_WIDTH then
        playerX = screenWidth - PLAYER_WIDTH
    end

    spawnTimer = spawnTimer - 1
    if spawnTimer <= 0 then
        spawnBlock()
        spawnTimer = SPAWN_FRAMES
    end

    for i = #blocks, 1, -1 do
        local block = blocks[i]
        block.y = block.y + blockSpeed
        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) then
            table.remove(blocks, i)
            lives = lives - 1
            if lives == 0 then
                state = "over"
            end
        elseif block.y > screenHeight then
            table.remove(blocks, i)
            score      = score + 1
            blockSpeed = blockSpeed + BLOCK_FASTER
        end
    end
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        goingLeft = true
    elseif what == SWITCH_RIGHT then
        goingRight = true
    elseif what == SWITCH_BUTTON1 and state ~= "playing" then
        startGame()
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goingLeft = false
    elseif what == SWITCH_RIGHT then
        goingRight = false
    end
end


function onOverlayUpdate()
    if state == "playing" then
        updatePlaying()
    end

    overlayClear()
    drawGame()
    if state == "waiting" then
        drawWaitingText()
    elseif state == "over" then
        drawOverText()
    end

    return OVERLAY_UPDATED
end

About a hundred and twenty lines of code, and you wrote all of them a handful at a time.

What Just Happened

A few pieces deserve a second look.

local blocks     = {}
local score      = 0


function startGame()
    score = 0
end

The data is local and the functions are not. Those are two deliberate and opposite choices.

The data is local so that it belongs to this file and nothing outside can reach in and change it. The functions are global so that they can call each other in any order: drawOverText is defined before printCentered and calls it anyway, because a global name is looked up at the moment of the call, by which time the whole file has been read. Make those functions local and the file has to be sorted so that nothing is used before it appears, which is a rule you would spend the rest of the book tripping over. Three of the names here have no choice at all: onOverlayUpdate and the two input callbacks must be global, because that is how Singe finds them.

Inside the file, the order is alphabetical, with the three callbacks last. That is not a rule of Lua. It is so that in six months you can find spawnBlock without reading anything.

    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)

#text is the length of a string, in characters. You met # in lesson six counting the items in a list, and it does the same job here. "GAME OVER" is nine characters, so on a sixty column screen it starts at column twenty-five, which leaves twenty-five cells of space on its left and twenty-six on its right. math.floor throws away the fraction, because there is no such thing as column twenty-five and a half.

TEXT_COLUMNS works out how many character cells fit across the screen. overlayPrint counts in cells while everything else counts in pixels, so the width of the overlay is divided by the width of one cell, and overlayGetFontWidth is what tells you that. Two slashes rather than one, because a fraction of a column is not a place to print. Work it out this way and the centering stays right at any overlay size, which is the fourth thing in Try it.

    colorForeground(255, 90, 90)

colorForeground sets a color that stays set. It is not an argument to overlayBox; it is a switch you flip, and everything drawn afterwards comes out in that color until you flip it again. That is why drawGame sets green, draws the player, sets red, and then draws all the blocks without mentioning color again.

It does not affect overlayPrint. The console font is copied onto the overlay exactly as it is, in its own colors, which the reference’s entry for overlayPrint says in as many words. Colored text needs a loaded font, and that is lesson nineteen.

Try It

  1. Make it easier, then unfair. Change PLAYER_WIDTH to 80 and play a round. Then change it to 12, the same size as a block. Notice that you did not have to touch the drawing or the collision to do either one.

  2. Speed up faster. Change BLOCK_FASTER from 0.05 to 0.5 and see how many points you can get. Then try 0, and ask yourself whether the game is still worth playing.

  3. An extra life. Give the player a life back every ten points. Everything you need is already in updatePlaying, in the branch that adds to the score.

  4. Play it bigger. Run it with Singe -R --canvas=1280x720 dodge. The game lays itself out correctly, centered text and all, because it asked the engine how big the screen was. TEXT_COLUMNS asked too.

  5. Pause it. Add a fourth state, "paused". SWITCH_BUTTON2 should swap between "playing" and "paused", and nothing should move while paused. Done right, this is three lines and you do not have to touch updatePlaying at all.

Break It on Purpose

Go into spawnBlock and delete the line that sets block.y, so that it reads:

function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    table.insert(blocks, block)
end

Save, press space, and Singe stops with this:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:97: attempt to perform arithmetic on a nil value (field 'y')
stack traceback:
	dodge/dodge.singe:97: in function 'updatePlaying'
	dodge/dodge.singe:135: in function 'onOverlayUpdate'

Line 97 is block.y = block.y + blockSpeed. The complaint is that something in that sum is not a number, and the part in parentheses tells you which one: field 'y', meaning the y inside a table. It has no value, because you never gave it one, and a thing with no value in Lua is nil.

Notice where the error is and where the mistake is. The error is in updatePlaying, forty lines away from spawnBlock, where nothing is wrong at all. updatePlaying is only the first piece of code unlucky enough to touch the damage. This is the normal case, not the exception, and following that trail backwards is a skill.

Put the line back. Then turn the page, because the next lesson is about nothing else.

What You Learned

  • A game is a world that changes, a world that gets drawn, and a decision about which of those to do — and those are three separate pieces of code.

  • Input handlers should record what is held down; the update should decide what that means.

  • A list of records is the shape of almost every game world.

  • Remove things from a list by walking it backwards.

  • collideRects answers whether two rectangles overlap, and the engine’s version is better than yours because it is right, it reads well, and it has a family you will meet again.

  • One state variable holding a word beats three true-or-false flags, and keeps beating them as the game grows.

  • Start a game from one function that resets everything, so that the second game is exactly like the first.

  • Numbers you might want to tune belong in named constants at the top of the file.

  • Build a game in stages that each run. A program that has never worked is much harder to fix than one that worked five minutes ago.

Next Time

You have now written enough code to make interesting mistakes. The next lesson is the one no beginner’s book bothers with: what Singe’s error messages actually say, how to find out what a variable really holds instead of guessing, and how to cut a problem in half until there is nowhere left for it to hide.

Lesson 8: When It Goes Wrong

The finished lesson

You have written a game. From here on you will spend more of your time fixing programs than writing them, and that is not a sign that anything is wrong with you. It is the job. The difference between someone who enjoys programming and someone who gives it up is almost never talent; it is whether they learned to read what the computer is telling them.

So this lesson has nothing new in it to build. It is the five messages you will see most often for the rest of your life, what each one actually means, and four ways of hunting down the mistake behind it. Keep dodge.singe from lesson seven open, because you are going to break it on purpose several times.

Two Kinds of Stop

Singe stops for two different reasons, and it says so in two different ways.

When the script will not even start, you get this shape:

Error running script:  dodge/dodge.singe:92: 'then' expected near 'spawnBlock'

Lua reads your whole file before running a word of it, and this means it could not make sense of what it read. Nothing ran at all.

When the script started fine but something went wrong later, you get this shape instead:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:98: attempt to perform arithmetic on a nil value (global 'blockSped')
stack traceback:
	dodge/dodge.singe:98: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

The game was running. Singe called your onOverlayUpdate, as it does sixty times a second, and this time the call did not come back.

Both shapes contain the same three things, and they are the three things you want: a file, a line, and a complaint. Read them in that order, every time.

The line numbers in this lesson are from lesson seven’s finished listing. If yours are a line or two out, so is your file, and nothing about reading an error depends on the number matching.

The Ones That Stop It Before It Starts

These are the easy ones, and they are also the ones that feel worst, because the screen stays black and there is nothing to look at.

Go into updatePlaying and delete the word then from the line if spawnTimer ⇐ 0 then. Save:

Error running script:  dodge/dodge.singe:92: 'then' expected near 'spawnBlock'

Lua got to the end of the if line, wanted the word then, and found the start of the next line instead — which is spawnBlock(), and that is the near 'spawnBlock' part. "Near" means "this is where I noticed", and it is usually the first thing after what you left out.

Now a nastier one. Put then back, and instead delete the end on the last line of spawnBlock. Save:

Error running script:  dodge/dodge.singe:148: 'end' expected (to close 'function' at line 58) near <eof>

Line 148 is the end of the file, just past its last line. There is nothing wrong with line 148. Lua read to the very end — <eof> is what it calls the end of a file — still waiting for an end that never came, and by then it had swallowed every function after spawnBlock as if it were part of it.

The useful half of that message is (to close 'function' at line 58), which is where spawnBlock begins. When a message points at the end of the file, believe what it says in the parentheses, not the line number. This is also why the indenting matters so much: a missing end is almost invisible in a list of lines, and obvious the moment everything below it is indented one step too far.

Two more worth recognizing, because you will meet both this week:

Error running script:  dodge/dodge.singe:41: unfinished string near '"GAME OVER)'

A quote you opened and never closed, which you met in lesson one.

Error running script:  dodge/dodge.singe:135: 'then' expected near '='

That one is if state = "playing" then. One = sets a variable, two == ask a question, and Lua will not let you set one inside an if. It looks like a strange complaint, and it always means the same thing.

Attempt to Index a Nil Value

This is the one you will see most, by a wide margin.

Go into spawnBlock and misspell block on the first line that uses it, so it reads blocl.x = math.random(0, screenWidth - BLOCK_SIZE). Save, press space:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:60: attempt to index a nil value (global 'blocl')
stack traceback:
	dodge/dodge.singe:60: in function 'spawnBlock'
	dodge/dodge.singe:92: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Indexing is what the dot does. blocl.x means "go into the thing called blocl and find the x in it". You can only do that to a table.

Nil is what Lua calls a name with nothing behind it. You have not seen much of it because you have been careful to give everything a value, but every name you have never used is nil already, and typing a name wrong invents a brand new one.

So the whole message says: you used a dot on something that does not exist.

The part in parentheses is the gift. global 'blocl' is the exact name of the thing that was empty. Search your file for it. If it appears exactly once, it is a spelling mistake, and you have found it in ten seconds.

The word before the name tells you where Lua looked for it:

  • global — a name with no local in front of it anywhere.

  • local — a name you declared with local in the function you are in.

  • field — a name after a dot, like the y in block.y.

  • upvalue — a local from further out that this function can see, which is what all the variables in dodge.singe are, since they are declared at the top of the file and used inside functions.

field is the other common cause, and it is not a spelling mistake at all. If you wrote block.hit.when and never set block.hit, you get attempt to index a nil value (field 'hit'). The dot that fails is the second one. Lua tells you which by naming it.

Attempt to Call a Nil Value

Put blocl back. Now misspell an engine function: in drawGame, change overlayPrint to overlayPirnt. Save:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:36: attempt to call a nil value (global 'overlayPirnt')
stack traceback:
	dodge/dodge.singe:36: in function 'drawGame'
	dodge/dodge.singe:140: in function 'onOverlayUpdate'

Same nil, different crime. Calling is what the parentheses do, and you can only do that to a function. There is no function called overlayPirnt, so overlayPirnt is nil, so the parentheses have nothing to call.

This happens for four reasons, in order of how often:

  1. You misspelled one of your own functions.

  2. You misspelled one of Singe’s. Nothing in the engine checks your spelling when the file loads, so a misspelled engine name is just another name that happens to be empty, and it costs you nothing until the line runs.

  3. The function does not exist in Singe at all — it was a reasonable guess, and reasonable guesses are wrong about half the time. The reference’s function list is the only way to be sure.

  4. You made it local and called it from somewhere above where it is declared. This is exactly why the functions in dodge.singe are global.

There is a much worse version of this mistake, and you met it in lesson one without knowing: spell a callback wrong and you get no message at all. onOverlayUpdated is not an error. It is a perfectly good function that Singe has never heard of and will never call, so the screen stays black and nothing complains. When a whole feature does nothing whatsoever, suspect the name.

Attempt to Perform Arithmetic on a Nil Value

Put overlayPrint back. In updatePlaying, misspell blockSpeed in the falling line, so it reads block.y = block.y + blockSped:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:98: attempt to perform arithmetic on a nil value (global 'blockSped')
stack traceback:
	dodge/dodge.singe:98: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Arithmetic is +, -, *, and /. You cannot add nothing to a number. Again the parentheses name the empty thing, and again the commonest cause is a typo — but this one has a second cause that is worth knowing, because it is harder to see.

A variable you never gave a number to is nil, not zero. If you add a high score to the game and write local hiScore at the top without = 0, it holds nil until something sets it, and the first hiScore + score stops the game. Lua does not start numbers at zero for you. You start them at zero.

Two close relatives, with the same cause and the same cure:

dodge/dodge.singe:37: attempt to concatenate a nil value (upvalue 'hiScore')

.. joining a string to something that is not there. You will see this one whenever you print a score you forgot to set — here, hiScore added to the score line in drawGame, which is line 37 now that local hiScore sits above it.

dodge/dodge.singe:105: attempt to compare nil with number

That is if score > hiScore then, put under state = "over" to keep the best score when a game ends, with nothing in hiScore. Note that this message does not name anything in parentheses. When Lua cannot tell you which side was empty, the section after next is how you find out.

An Argument of the Wrong Kind

Every message so far came from Lua. This one comes from Singe, and it looks completely different, so it is worth meeting on purpose.

Suppose you want to see what is in blocks, and you try to print it. Add this line to drawGame, under the score:

    overlayPrint(1, 3, blocks)
37:overlayPrint:  Argument 3 must be a string.

No file name, no traceback, no attempt to anything. An engine complaint starts with the line number, then the name of the function that refused, then what it wanted. Here overlayPrint was handed a table where it needs text, and it stopped rather than draw something meaningless.

The sibling message counts rather than checks:

34:overlayBox:  Expected 4 argument(s), got 3.

That is an overlayBox with a corner missing. The odd-looking argument(s) is the engine’s, not a typo of yours.

When you get one of these, the reference’s entry for that function is the answer, and it will take you a minute. Every entry lists the arguments in order with what each one has to be. Singe checks them because the alternative is a game that runs for ten minutes and then draws garbage.

Finding Out What Is Really in There

Half of debugging is not reading errors at all. It is the case where nothing crashes and nothing works: blocks that never appear, a player who will not move, a score stuck at zero. For that you need to see inside the running game, and there are two ways.

The first is debugPrint, which writes a line to the terminal you started Singe from. Take the line you cannot make sense of and put one above it:

    debugPrint("blocks " .. #blocks .. ", timer " .. spawnTimer)

Now you are looking at what is actually there instead of what you are sure is there, and that gap is where bugs live. Print playerX the same way and you will see the truth about it, too: it prints as 160.0, not 160, because dividing with / in Lua always gives a number with a fractional part, even when the fraction is zero.

Two things will bite you. The first is that debugPrint insists on text or a number; hand it anything else and it stops the game the way overlayPrint did. debugPrint(blocks) will not show you a list, and debugPrint("left " .. goingLeft) at the top of updatePlaying will not show you a true or a false either:

dodge/dodge.singe:78: attempt to concatenate a boolean value (upvalue 'goingLeft')

tostring is the fix. It takes anything at all and gives you text for it, so tostring(goingLeft) is "true" or "false" and the line works.

The second is that onOverlayUpdate runs sixty times a second, so a debugPrint inside it prints sixty lines a second and you cannot read any of them. The reference says as much in its entry: the call is cheap, but nothing throttles it.

Before anything else, put one switch in front of every debug line you add, so that you can turn the noise off without hunting them down again:

local DEBUG = true


function debugLog(text)
    if DEBUG then
        debugPrint(text)
    end
end

Every debugLog in the game obeys that one true. Change it to false and the game goes quiet; change it back and everything returns.

Then print when something happens rather than every frame:

            debugLog("hit at y " .. math.floor(block.y) .. ", lives now " .. lives)

Or print on a timer, counted down exactly the way blocks are spawned:

    reportTimer = reportTimer - 1
    if reportTimer <= 0 then
        debugReport()
        reportTimer = REPORT_FRAMES
    end

The learn folder has the whole thing as 08-when-it-goes-wrong.singe: it is lesson seven’s game with a report about every two seconds, a line when you get hit, and a line when the game ends.

The second way to see inside is to put it on screen, which is better for anything that changes every frame, because sixty lines a second in a terminal is useless but a number that ticks in the corner is easy to watch:

    if DEBUG then
        overlayPrint(1, 3, "BLOCKS " .. #blocks .. "   PLAYER " .. playerX)
    end

Cutting the Problem in Half

When you cannot see which of twenty lines is wrong, stop looking and start removing.

Put two dashes at the start of a line and Lua ignores the rest of it. That is a comment, and the usual use is to leave notes for yourself, but the better use is this one:

    -- overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)

Comment out half of drawGame and run it. If the problem is still there, it is in the half you kept. If it went away, it is in the half you removed. Put that half back and cut it in half. Twenty lines takes five rounds of this, and each round is one save and one look.

It works on more than lines. Comment out the body of updatePlaying and the blocks stop moving, which tells you whether the thing you are chasing is in the moving or in the drawing. Comment out the collideRects branch and see whether the game stops crashing. You are not trying to fix anything while you do this. You are trying to find out where it is not.

Going Round Faster

All of this depends on being able to try something in a couple of seconds, and that is what -R is for. You have been using it since lesson one; here is what it is actually doing, and it is worth knowing now that you are going to lean on it.

Singe watches every script file your game loaded. When you save one, the game starts again from the beginning: everything the script made is thrown away and your file is run afresh, in the time it takes to read the file rather than the time it takes to start the engine. F5 does the same on demand, without saving anything.

A key you are holding through a reload is ignored until you let go, so the player will not run off on his own after a reload.

The two kinds of stop behave differently here, and it is useful to know which you are looking at without reading the message. A script that will not compile is printed and survived: the window stays open and empty, the file stays watched, and saving the fix brings the game back. A crash inside a callback — all the attempt to messages, and the engine’s argument complaints — takes Singe down, and you start it again by hand.

Reading a Traceback

The lines under stack traceback: are the list of functions that were in progress when everything stopped, innermost first. Here is the one from blocl again:

	dodge/dodge.singe:60: in function 'spawnBlock'
	dodge/dodge.singe:92: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Read it from the bottom up and it is a sentence. Singe called onOverlayUpdate. At line 136, onOverlayUpdate called updatePlaying. At line 92, updatePlaying called spawnBlock. At line 60, spawnBlock gave up.

The top line is where it broke. The lines under it are how it got there, and they are what you need when the top line looks innocent. A function that adds a number to block.y is not wrong; a function that put a block in the list without a y is. Only the trail joins the two, and the trail is printed for you every single time.

The Habit

Everything above is technique. This is the habit, and it matters more:

Change one thing. Run it. Look at what happened.

When something will not work, the temptation is to change four things at once, because one of them is bound to be it. Do that and it stops working in a new way, and now you do not know which of the four did it, or whether two of them are canceling out. You have made the problem bigger and hidden it better.

One change. Run. Look. It feels slower. It is the fastest thing there is, and every experienced programmer you will ever meet does it, for exactly the reason you are about to find out.

Try It

  1. Meet them all. Make each of the five mistakes in this lesson in dodge.singe on purpose, one at a time, and read the message before you fix it. You will never be afraid of them again.

  2. Watch the spawner. Put a debugPrint inside spawnBlock that prints the new block’s x. Play for thirty seconds, then look at the numbers. Are they spread across the screen, or do they favor one end?

  3. Turn it off. Change DEBUG to false in the lesson script, and satisfy yourself that nothing prints and the game is unchanged.

  4. A bug with no error. In updatePlaying, change if spawnTimer ⇐ 0 then to if spawnTimer == 0 then, which looks as if it means the same thing. Run it and start a game. There is no error, nothing crashes, and not one block ever falls, so you cannot even lose. Put a debugLog inside spawnBlock, add spawnTimer to the first line debugReport prints, and play again. Work out from what they say, and from what one of them never says, why == was the wrong question to ask.

  5. Break a callback’s name. Rename onInputPressed to onInputPress and run it. No error is printed, nothing crashes, the player will not move, and space will not start a game. Then explain to yourself why that is the most dangerous mistake in this lesson.

What You Learned

  • Errors have a file, a line, and a complaint. Read them in that order.

  • Error running script means nothing ran; the shape with a traceback means it was running and stopped.

  • nil is a name with nothing behind it, and it is behind most error messages you will ever see.

  • The word in parentheses names the empty thing, and says whether it was a global, a local, a field, or an upvalue.

  • A missing end is reported at the end of the file, and the parentheses tell you where the mistake really is.

  • Engine complaints look different: a line number, a function name, and what it wanted instead.

  • debugPrint shows you what a variable really holds. tostring makes anything printable, and a switch like DEBUG turns the noise off.

  • Comment a half out with -- to find out which half the problem is in.

  • A misspelled callback produces no error at all, which makes it worse than one that does.

  • Change one thing, run it, look.

Next Time

That is the end of part one. You can write a game, and now you can fix one, which means everything from here is addition rather than foundation. Part two starts by replacing those colored boxes with actual pictures, and from there the game you have been building begins to look like a game somebody else would want to play.

Lesson 9: Pictures

The finished lesson

Everything you have drawn so far, you drew with boxes and lines and the engine’s own plain text. That was on purpose: eight lessons with no artwork meant eight lessons where nothing could go wrong except your program. Now the boxes become a ship and some rocks.

A picture the engine draws onto the overlay is called a sprite. This lesson loads them, draws them, measures them, puts them in the right order, and steps through a picture that holds several frames of an animation. By the end, the game from lesson seven looks like a game.

The Art Kit

You do not have to draw anything. This book ships a small folder of artwork, and everything in this lesson and the next uses it.

Find the art folder that came with the book and copy the whole folder into this lesson’s folder, beside your script. You should end up with this:

singe/                 <- your work folder
    Singe/
    data/
    rocks/
        rocks.singe
        art/
            spaceship.png
            asteroid.png
            bullet.png
            star.png
            walk.png
            shoot.wav
            boom.wav

Your artwork goes inside your game’s own folder, and the engine’s Singe folder stays where it is, out in the work folder. That matters in a moment, because it decides how you name a file when you load it.

The Singe folder is the one the engine unpacked for you on your very first run, back in lesson one. It is worth knowing what is in it, because those files are yours to use too and every reader of this book has them:

  • Singe/click.wav — a short click, which the engine’s own menu uses for its sound test.

  • Singe/FreeSansBold.ttf — a TrueType font, for lesson nineteen.

  • Singe/menuIntro.flac — the music the engine’s menu plays. You will use it in lesson ten.

  • Singe/menuBackground.mkv — a video, for lesson fourteen.

  • Singe/DragonModel.glb and Singe/SingeText.glb — two 3D models, for lesson twenty-three.

  • Singe/missing.png — the picture the engine draws when a game asks for one it cannot find.

The kit’s pictures are small on purpose. The ship is 32 pixels across and 24 down, a rock is 24 by 24, a shot is 4 by 10, and a star is 8 by 8. That sounds tiny until you remember how big the screen actually is, which is the next thing to sort out.

How Big the Screen Is

Without a video to play, Singe gives your game a canvas 720 pixels across and 480 down, and the surface you draw on — the overlay — is half that in each direction: 360 by 240. Singe stretches it to fill the window for you, so a 32 pixel ship is about a tenth of the width of the screen, which is roughly what a ship in an arcade game looks like.

Never type 360 and 240 into your program. Ask:

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()

Those two report the size of the overlay, and a game that asks is a game that still works when somebody runs it at a different size.

There is one thing that does not count in those pixels: overlayPrint, from lesson one, counts in character cells. Each cell is 6 pixels across and 13 down, so a 360 by 240 overlay is 60 columns by 18 rows of text. Sprites are in pixels, overlayPrint is in cells, and mixing the two up is worth one confused afternoon if you let it be.

One Picture on Screen

Start a new file next to your art folder and type this in.

dofile("Singe/Framework.singe")

local ship = spriteLoad(DIR .. "art/spaceship.png")


function onOverlayUpdate()
    overlayClear()
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(ship)
end

Run it. A small blue ship sits near the middle of a black screen, pointing up.

What Just Happened

Four new things, one at a time.

local ship = spriteLoad(DIR .. "art/spaceship.png")

spriteLoad reads an image file off the disk, decodes it, and keeps the picture in memory. What it hands back is not the picture. It is a handle: a plain number, an entry ticket, the engine’s way of saying "that one". You give that number back to the engine every time you want to do something with the picture, and you never need to know or care what the number is.

Print it if you like — debugPrint(ship) from lesson eight will show you a small number — but the number itself is not yours to reason about, and nothing in your program should ever depend on what it turns out to be. The only rule is that you keep it somewhere you can get at it again, which is exactly what a variable is for.

DIR is new too, and it solves a problem the layout you have been using since lesson one creates. Singe looks for files relative to the folder you were standing in when you started it, not relative to your script. You start it from your work folder, so a plain art/spaceship.png sends the engine looking for singe/art/spaceship.png, out beside the Singe folder. Your artwork is not there. It is one level down, in rocks/art/spaceship.png, with your script.

DIR closes that gap. It is a piece of text holding the folder your script is in, with the slash already on the end, so DIR .. "art/spaceship.png" — joining two pieces of text with .., which you have been doing since part one — names the picture correctly however the game was started, and keeps naming it correctly when you move the whole folder somewhere else.

DIR is one of the names that Singe/Framework.singe defines, which is what the dofile line at the top of your script is for. You met that line and what is in it in lesson seven, and this is the moment it earns its place: without it there is no DIR, and without DIR the engine cannot find your ship.

Use DIR on every file your game loads, from here to the end of the book.

    spriteDraw(ship, 160, 100)

Draw the sprite with that handle, at that position. Like every drawing call, it only works inside onOverlayUpdate.

The position is the top left corner of the picture, not its middle. Ask for (160, 100) and the topmost, leftmost pixel of the ship lands there and the rest of it hangs down and to the right. That trips up everybody once, usually when they try to center something and it comes out low and to the right by half its own size.

If you would rather give the middle, say so:

    spriteDraw(ship, 160, 100, true)

A fourth argument of true means "treat that point as the center". Both forms are in the reference’s entry for spriteDraw, along with two more that stretch the picture into a rectangle.

function onShutdown()
    spriteUnload(ship)
end

onShutdown is a callback, like onOverlayUpdate and the two input callbacks from lesson three. The engine calls it once, when your game is ending. It is where you give back what you took: spriteUnload frees the picture and throws the handle away.

Strictly, you could leave it out. The engine frees everything your script loaded when the game ends, so a missed spriteUnload is not a leak. Write it anyway. It costs one line, it says what your program owns, and in a minute you will see the case where forgetting to unload really does matter.

One warning about that handle: once you have unloaded a sprite, the number is dead. Drawing with it does not draw nothing, it ends your game with an error.

Transparency, and Why It Is a PNG

The ship is a triangle with two fins. The file it lives in is a rectangle, 32 by 24, because every image file is a rectangle. So what happened to the corners?

They are transparent. A PNG can say, for every single pixel, how solid it is, and the kit’s pictures say "not there at all" for every pixel outside the shape. Singe honors that, so the black background shows through the corners and the ship has an outline instead of a box around it.

This is the reason the kit is PNG and not JPEG. A JPEG cannot store transparency at all — it would give you the ship in a gray box — and it also smudges hard edges, which is the last thing small artwork needs. For game artwork, PNG. For a photograph that fills the whole screen and has no transparent parts, JPEG is fine and much smaller. The reference’s entry for spriteLoad lists every format Singe will read, and there are a lot of them.

Try it yourself: change the black to something else by drawing a box behind the ship before you draw the ship. The corners will show whatever is behind them, which is the whole point.

Do Not Load While You Draw

Here is the mistake this section exists to stop. It looks completely reasonable:

function onOverlayUpdate()
    overlayClear()
    local ship = spriteLoad(DIR .. "art/spaceship.png")
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end

Run that and it works. It draws the ship. Nothing complains. You would have no reason to think anything was wrong.

onOverlayUpdate runs about sixty times a second. That is sixty fresh copies of the ship loaded into memory every second, three thousand six hundred a minute, and not one of them ever unloaded. The game runs beautifully for two minutes, gets slower, and then the machine runs out of memory and it dies. Worse, it dies during the demo and not while you were testing.

The rule: load once, draw many times. Loading is slow and it takes memory. Drawing is fast and takes none. So spriteLoad goes at the top of your file, outside every function, where it runs one time as the script starts.

This is not only about sprites. Every somethingLoad in the engine works this way — sounds in lesson ten, fonts in lesson nineteen, models in lesson twenty-three. If you find yourself typing Load inside a function that runs every frame, stop and move it out.

How Big Is It?

You know the ship is 32 by 24 because this book told you. Your program does not, and it should not have to. Ask:

local shipWidth  = spriteGetWidth(ship)
local shipHeight = spriteGetHeight(ship)

Now you can keep the ship on the screen, because the rightmost position it may sit at is screenWidth - shipWidth, and put it in the middle, because the middle is (screenWidth - shipWidth) / 2. Neither line has a number in it that would have to change if somebody redrew the ship a bit bigger.

Both of these report the size as the sprite would be drawn right now. If you ever scale or rotate a sprite, with spriteScale or spriteRotate, the answer changes to match. That is usually what you want, and it will surprise you exactly once.

Drawing Order

Sprites do not merge. Later covers earlier, pixel for pixel, exactly like sticking paper cutouts on a wall. So the order of your spriteDraw calls is the order from back to front:

    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()

Stars are furthest back, so they go down first. The ship is in front of everything in the playfield. The score sits on top of all of it. Get this backwards and your carefully drawn ship spends the game hiding behind the star field, and there is no error to tell you so — only a ship you cannot see.

overlayClear still comes first, before all of it. Drawing never replaces, it only covers, so the frame starts empty every time.

Frames

Open art/walk.png in any image viewer. It is not a picture of a person. It is a picture of four people, side by side: the same figure at four points of a walk, each one 24 pixels across in a strip 96 wide.

One picture holding several frames of an animation is a sprite sheet, and it is how nearly all 2D animation is stored. One file, one load, one handle, and the game picks which slice to draw.

Make a second file, walk.singe, beside the first one:

dofile("Singe/Framework.singe")

local walk      = spriteLoadFrames(4, DIR .. "art/walk.png")
local walkFrame = 1
local walkTick  = 0
local walkX     = 0


function onOverlayUpdate()
    overlayClear()
    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end
    walkX = walkX + 1
    if walkX > overlayGetWidth() then
        walkX = -spriteFrameWidth(walk)
    end
    spriteDrawFrame(walk, walkX, 100, walkFrame)
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(walk)
end

Run it with Singe rocks/walk.singe. A small figure walks steadily across the screen, disappears off the right edge, and comes back on from the left.

spriteLoadFrames is spriteLoad with one extra thing to say: how many frames are in the strip. The count comes first, before the file name, which is the opposite of what most people guess. It divides the width of the image by the count and remembers the slices. Four frames in a 96 pixel strip means four frames 24 pixels wide. Get the count wrong — say 3 — and you get three 32 pixel slices, each showing bits of two figures, which is a memorably silly way to find out you typed the wrong number.

spriteDrawFrame draws one slice. It takes the handle, where to put it, and which frame, in that order, and frames are numbered from 1: frame 1 is the leftmost figure and frame 4 the rightmost.

Watch out for that 1. Elsewhere in the sprite family — spriteSetFrame and spriteGetFrame — frames are numbered from 0. That is an accident of history, both are in the reference, and this book uses spriteDrawFrame and counts from 1.

spriteFrameWidth reports the width of one frame, 24 here, rather than the 96 of the whole strip. spriteFrameHeight is its partner. When you want to know how wide a slice of a sheet is, those are the two to ask, and not spriteGetWidth.

The frame number is a number in a variable like any other, so the walking is arithmetic:

    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end

Count the frames going by. Every eighth one, step to the next picture, and after the fourth picture go back to the first. Sixty frames a second divided by eight is between seven and eight steps a second, which for a four frame cycle is a brisk but believable walk. Change the 8 and you change the speed: bigger is slower.

You may wonder why you are counting at all, when the engine has spritePlay to run an animation for you. It does, and for an animated GIF it is the right answer, because a GIF carries the timing for each of its frames inside the file. A plain strip like walk.png carries no timing, so the engine runs it as fast as it is allowed to — a hundred frames a second, twenty-five complete walk cycles every second, a blur. When the frames come from a strip, do the counting yourself.

The Game Gets Its Artwork

Now put it together. The game from lesson seven steered a box along the bottom of the screen and dropped other boxes on it. Every box becomes a picture, and while you are in there the ship gets something to shoot with.

The changes are all of a piece, so here is the whole script. It is longer than anything you have written, and there is nothing in it you have not met.

dofile("Singe/Framework.singe")

local SHIP_SPEED  = 3
local SHOT_SPEED  = 6
local ROCK_COUNT  = 6
local STAR_COUNT  = 40
local START_LIVES = 3
local HIT_SCORE   = 10

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")
local rockSprite = spriteLoad(DIR .. "art/asteroid.png")
local shotSprite = spriteLoad(DIR .. "art/bullet.png")
local starSprite = spriteLoad(DIR .. "art/star.png")

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local shipWidth    = spriteGetWidth(shipSprite)
local shipHeight   = spriteGetHeight(shipSprite)
local rockWidth    = spriteGetWidth(rockSprite)
local rockHeight   = spriteGetHeight(rockSprite)
local shotWidth    = spriteGetWidth(shotSprite)
local shotHeight   = spriteGetHeight(shotSprite)

local shipX   = (screenWidth - shipWidth) / 2
local shipY   = screenHeight - shipHeight - 4
local goLeft  = false
local goRight = false
local rocks   = {}
local shots   = {}
local stars   = {}
local score   = 0
local lives   = START_LIVES
local over    = false


function drawHud()
    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(50, 1, "LIVES " .. lives)
    if over then
        overlayPrint(25, 8, "GAME OVER")
        overlayPrint(17, 10, "PRESS 1 TO PLAY AGAIN")
    end
end


function drawRocks()
    for _, rock in ipairs(rocks) do
        spriteDraw(rockSprite, rock.x, rock.y)
    end
end


function drawShots()
    for _, shot in ipairs(shots) do
        spriteDraw(shotSprite, shot.x, shot.y)
    end
end


function drawStars()
    for _, star in ipairs(stars) do
        spriteDraw(starSprite, star.x, star.y)
    end
end


function newRock(rock)
    rock.x     = math.random(0, screenWidth - rockWidth)
    rock.y     = -rockHeight - math.random(0, 160)
    rock.speed = math.random(8, 20) / 10
end


function onInputPressed(what)
    if over then
        if what == SWITCH_START1 then
            startGame()
        end
        return
    end
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goLeft = false
    elseif what == SWITCH_RIGHT then
        goRight = false
    end
end


function onOverlayUpdate()
    overlayClear()
    updateStars()
    if not over then
        updateShip()
        updateShots()
        updateRocks()
    end
    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
end


function overlapping(ax, ay, aw, ah, bx, by, bw, bh)
    if ax + aw <= bx then
        return false
    end
    if bx + bw <= ax then
        return false
    end
    if ay + ah <= by then
        return false
    end
    if by + bh <= ay then
        return false
    end
    return true
end


function startGame()
    shipX = (screenWidth - shipWidth) / 2
    score = 0
    lives = START_LIVES
    over  = false
    shots = {}
    for i = 1, ROCK_COUNT do
        rocks[i] = {}
        newRock(rocks[i])
    end
end


function updateRocks()
    for _, rock in ipairs(rocks) do
        rock.y = rock.y + rock.speed
        if rock.y > screenHeight then
            newRock(rock)
        end
        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                over = true
            end
        end
    end
end


function updateShip()
    if goLeft then
        shipX = shipX - SHIP_SPEED
    end
    if goRight then
        shipX = shipX + SHIP_SPEED
    end
    if shipX < 0 then
        shipX = 0
    end
    if shipX > screenWidth - shipWidth then
        shipX = screenWidth - shipWidth
    end
end


function updateShots()
    for i = #shots, 1, -1 do
        local shot = shots[i]
        local gone = false

        shot.y = shot.y - SHOT_SPEED
        if shot.y + shotHeight < 0 then
            gone = true
        end
        for _, rock in ipairs(rocks) do
            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then
                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
            end
        end
        if gone then
            table.remove(shots, i)
        end
    end
end


function updateStars()
    for _, star in ipairs(stars) do
        star.y = star.y + star.speed
        if star.y > screenHeight then
            star.y = 0
            star.x = math.random(0, screenWidth - 1)
        end
    end
end


for i = 1, STAR_COUNT do
    stars[i] = { x = math.random(0, screenWidth - 1), y = math.random(0, screenHeight - 1), speed = math.random(1, 3) / 4 }
end

startGame()

Left and right arrows steer. Space fires. When the rocks have taken your last life, 1 starts a new game.

A few things in there are worth pointing at.

The four spriteLoad calls and the eight measurements are at the top, outside every function, so they happen once. Everything after them is written in terms of screenWidth, shipWidth, and their friends, and there is not one raw pixel count in the whole of the playing code.

The functions are in alphabetical order, which is a habit worth picking up now. It does not matter to Lua in the slightest — it is for you, six months from now, looking for updateShots in a file with forty functions in it.

The last two things in the file are not functions at all. They are plain instructions at the bottom of the script: build the star field, then call startGame to set up the rocks and zero the score. They run once, in order, as the script loads, and they have to come after the functions they use.

overlapping is the four comparisons lesson seven said you could write yourself instead of calling collideRects, written out as a function with the same eight arguments. Two rectangles miss each other if either one is entirely left of, right of, above, or below the other; if none of those four is true, they overlap. Lesson eleven replaces it with something the engine provides, and explains why the rectangle is the wrong shape for a ship.

One last note for when you read other people’s Singe code. Every sprite call in this book takes the handle first. Singe 2.10 put it last, and a game can ask the engine to keep doing that, so code you find online may read spriteDraw(x, y, ship). Do not copy it. Handle first is the current order and the one the reference documents.

Try It

  1. Center the ship on its position. Add true as a fourth argument to the ship’s spriteDraw. Watch where the ship jumps to, and work out from the distance it moved what the fourth argument actually did.

  2. More rocks. Change ROCK_COUNT to 20. Then to 200. Somewhere between those two the game stops being playable, and somewhere well past it the game starts to slow down. Find both.

  3. Grow the ship. Add spriteScale(shipSprite, 2) at the very bottom of the file, on the line above startGame(). Run it and steer into the right-hand edge: the ship is twice the size but it still stops where the small one stopped, and it hangs off the right edge and off the bottom. Work out why, then move that one line up above the spriteGetWidth calls and watch it come right. The reference’s entry for spriteScale explains what scaling does to the measurements.

  4. Put the walker in. Load walk.png in the game, and draw the walking figure across the top of the screen as scenery. You will need the frame counting from the walk script, and you will have to decide where in onOverlayUpdate the draw goes — in front of the stars, behind the rocks.

  5. Unload something you are still using. Add spriteUnload(starSprite) at the bottom of the file, after startGame(), and run it. Read what you get.

Break It on Purpose

Capital letters matter, and artwork is where that bites hardest. Change the ship’s load to use a capital S:

local shipSprite = spriteLoad(DIR .. "art/Spaceship.png")

The game refuses to start:

10:spriteLoad:  Couldn't open rocks/art/Spaceship.png: No such file or directory

Read it the same way as the error in lesson one, but note that the shape is a little different. 10 is the line. spriteLoad is the engine function that gave up, rather than a file name — when the complaint comes from Singe rather than from Lua, this is what you get. Then the reason, which here is your operating system’s own wording and will differ slightly from machine to machine.

No such file or directory is the computer being precise rather than unkind. There genuinely is no file called Spaceship.png; there is one called spaceship.png, and to a Linux machine those are two different names. On Windows, and on most Macs, it would have worked, which is worse, because it means the bug travels to somebody else’s machine and appears there for the first time.

The other half of this error you will meet is the folder. If you put the art kit in the wrong place, or started Singe from the wrong directory, the message is exactly the same and the fix is not. The path in the message helps: it is the whole name Singe tried, counted from the folder you started it in, and the rocks/ on the front is the part DIR added. Check three things, in this order: is the file named exactly what you typed, is it in the art folder, and is that art folder beside your script.

What You Learned

  • A picture drawn onto the overlay is a sprite, loaded with spriteLoad.

  • spriteLoad hands back a handle: a number that means "that picture" to the engine, which you keep in a variable.

  • DIR is the folder your script is in, and every file your game loads should be named with it.

  • spriteDraw(handle, x, y) draws it, from its top left corner, and only inside onOverlayUpdate. A fourth argument of true means the center instead.

  • Load once, at the top of the file. Loading inside onOverlayUpdate eats memory until the game dies.

  • spriteUnload gives a picture back, usually from onShutdown, and the handle is dead afterwards.

  • PNG carries transparency, which is why the corners of the ship are not black boxes.

  • spriteGetWidth and spriteGetHeight measure a sprite as it would be drawn now, so you never have to type its size into your program.

  • Sprites cover each other. The order you draw in is back to front.

  • spriteLoadFrames(count, file) slices a strip into frames, and spriteDrawFrame(handle, x, y, frame) draws one of them, counting from 1.

Next Time

The game looks right and sounds like nothing at all. In lesson ten the shots get a noise, the rocks get an explosion, and something plays underneath the whole thing — and you meet your fifth callback, the one the engine uses to tell you a sound has finished.

Lesson 10: Sound

The finished lesson

A game with no sound feels broken in a way that is hard to put a finger on. The shots go out and nothing happens. The rocks break and nothing happens. Put a half second noise on each of those and the same game suddenly feels like it is made of something.

This lesson gives your game a shot, an explosion, and music underneath. On the way it introduces your fifth callback: the one the engine uses to tell you that a sound has finished playing.

One Noise

The art kit you copied in lesson nine has two sounds in it, shoot.wav and boom.wav, and the explosion is the easier of the two to hear. Make a new file beside your art folder and type this in.

dofile("Singe/Framework.singe")

local boom = soundLoad(DIR .. "art/boom.wav")


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(boom)
    end
end


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Press space.")
    return OVERLAY_UPDATED
end


function onShutdown()
    soundUnload(boom)
end

Run it and tap the space bar three or four times quickly. The bangs pile up on top of each other instead of cutting each other off.

Holding the space bar down gives you exactly one bang, not a stream of them. That is the same behavior you met in lesson three: a held key is one press, reported once, and the engine throws away the repeats your keyboard sends. It is why steering needs onInputReleased and a variable rather than counting presses.

What Just Happened

The shape is the same as lesson nine’s: load once at the top, use the handle, give it back at the end.

local boom = soundLoad(DIR .. "art/boom.wav")

soundLoad reads an audio file and keeps it in memory, and hands back a handle — the same idea as a sprite handle, a number that means "that clip" to the engine. DIR is there for the same reason it was there in lesson nine: the sound lives in your game’s folder, and the game has to be able to find it from wherever Singe was started.

Everything lesson nine said about loading applies here word for word. Load at the top of the file, once. A soundLoad inside onOverlayUpdate loads the clip sixty times a second and never gives one back, and the game dies of it some minutes later.

        soundPlay(boom)

Play it. That is the whole of playing a sound effect, and the engine takes care of the rest: the clip starts, it finishes, and it never gets in the way of your program.

But soundPlay hands something back too, and it is not the same number you gave it. Change the line and look:

        local channel = soundPlay(boom)
        debugPrint("clip " .. boom .. " on channel " .. channel)

Tap the space bar quickly half a dozen times and watch the two numbers. The clip number never changes. The channel number climbs — 0, then 1, then 2 — and once the earlier bangs have finished it drops back and starts reusing the low numbers again.

This is the single thing about sound that catches everybody, so it is worth saying slowly. Two different kinds of number are in play.

The clip handle from soundLoad is the recording. There is one of it. It does not change, it is not playing or not playing, it is the sound sitting in memory waiting to be used.

The channel from soundPlay is one performance of that recording. Singe has sixteen of them, numbered 0 to 15, and every sound that is currently audible is using one. That is why the bangs overlap: the second press did not interrupt the first, it started a second performance on the next free channel.

Everything that acts on a sound you can hear takes a channel: soundStop, soundIsPlaying, soundPause, soundResume. Everything that acts on the recording takes the handle: soundPlay and soundUnload. Hand one where the other belongs and you will not always get an error, because 3 is a valid channel number and also a perfectly good clip handle — you will get silence, or the wrong sound stopping, which is far harder to find.

Sixteen is a lot, but it is not endless. When every channel is busy, nothing plays and soundPlay hands back -1 instead of a channel number. A game that fires a great many sounds at once should expect that, and you will write one in a minute.

Volume

There are three volumes, and they multiply together.

The master effects volume covers everything. soundGetVolume reads it and soundSetVolume sets it, on a scale of 0 to 63.

    soundSetVolume(40)

Resist. That number is the player’s, not yours: it starts at whatever they asked for when they launched the game, and a game that overwrites it is a game that is too loud in somebody’s quiet room. Change the master volume only when the player asks you to, from an options screen. soundGetVolume is there so that an options screen can show what it currently is instead of guessing.

What you should reach for is the channel volume, which sits under the master. Give soundPlay a third argument and this one performance is quieter:

    soundPlay(shootClip, 0, 35)

The 0 in the middle is how many times to repeat, which you have to give because the volume comes after it. 0 means play it once. -1 means loop until something stops it, which is how you would do an engine drone or wind. The reference’s entry for soundPlay lists all three arguments.

The third volume is distance, for sounds placed in a 3D world. That is for part four, when the game moves into three dimensions.

Music has a volume of its own, and it is on a different scale. More on that in a moment.

Stopping, and Not Stopping

soundStop takes a channel and cuts it off where it is:

    soundStop(engineChannel)
    engineChannel = -1

Note the second line. As soon as a channel stops, the engine is free to hand that same number to the next soundPlay, so a channel number you are still holding may now belong to a completely different sound. Throw it away the moment you stop it. -1 is the useful thing to put there, because it is the same value soundPlay gives you when it could not play at all, so one test covers both: if channel >= 0 then.

soundStop is for a sound that is wrong now — the engine noise when the engine dies, the alarm when the alarm is answered. It is the wrong tool for a short effect. A half second explosion chopped off after a tenth of a second sounds like a mistake, because it is one.

So most of the time, do nothing at all. Let it finish. A sound effect that you start and never think about again ends by itself and frees its channel by itself, which is exactly what you want.

This holds even at the end. soundUnload does not cut off a clip that is still playing: the engine keeps the audio alive until the last channel using it has stopped. You can unload in onShutdown without worrying that you have silenced something.

soundIsPlaying(channel) answers whether a channel is making noise right now. Its main use is not curiosity but restraint: an alarm that should sound once, and not restart every time the game notices the danger is still there.

function raiseAlarm()
    if alarmChannel < 0 or not soundIsPlaying(alarmChannel) then
        alarmChannel = soundPlay(alarmClip)
    end
end

Read the condition aloud: play the alarm if there is no alarm channel, or if the one you have has stopped. Otherwise leave it alone.

The Sound That Stutters

Here is the mistake. Everybody writes it, usually within a week of discovering sound.

Suppose you wanted the ship to keep firing while the button is held down, rather than once per press. You would do it the way you steer: a firing variable set to true in onInputPressed and back to false in onInputReleased, and the shot created in onOverlayUpdate while it is true. That is a perfectly sensible thing to want, and the noise looks like it belongs right there with the shot:

function onOverlayUpdate()
    if firing then
        shots[#shots + 1] = { x = shipX, y = shipY }
        soundPlay(shootClip)
    end
    ...

What comes out is not a shot. It is a buzzing rattle, or a hard flat tone, or a sound like a small machine breaking.

onOverlayUpdate runs about sixty times a second. Hold the button for one second and you have asked for sixty performances of a clip that lasts about a fifth of a second, each one starting on top of the last. About eleven of them are playing at any moment, each a frame behind the one before, and what you hear is sixty copies of the same attack piled on each other.

The fix is not a cleverer sound. It is playing the sound where the event happens rather than where the state is true:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(shootClip, 0, 35)
    end
end

onInputPressed happens once, when the button goes down. One press, one shot, one noise.

If you really do want held fire, the answer is the same one in a different shape: make the firing itself an event. Count frames, exactly as the walk cycle counted them in lesson nine, and create a shot only every eighth frame. The noise goes with the shot, so it plays seven or eight times a second instead of sixty, and that is a machine gun rather than a rattle.

That is the rule, and it is worth carrying out of this lesson: sounds belong with events, not with conditions. A press, a hit, a death, a pickup — each of those happens once and deserves one sound. "The button is down" and "the ship is moving" are not events; they are true for hundreds of frames in a row, and anything you play from them plays hundreds of times.

When a sound really does belong to a state that lasts — an engine, wind, a siren — start it once with -1 for the loop count, keep the channel, and stop it when the state ends.

The Fifth Callback

Sometimes you do need to know when a sound has finished. Write this function and the engine will call it:

function onSoundCompleted(channel)
end

That is your fifth callback, after onOverlayUpdate in lesson one, the two input callbacks in lesson three, and onShutdown in lesson nine, and it works the same way as all of them: you write it, you never call it, the engine calls you. The channel it hands you is the channel that has just gone quiet — the number soundPlay gave you when you started it.

It fires when a clip runs out, when the last repeat of a loop finishes, and when you stop a channel yourself with soundStop. That last one surprises people who use the callback to chain one sound into the next: stopping a channel on purpose still reports it as completed, and if you are not careful the next sound in the chain starts anyway.

The game is about to use it for something worth doing. When the last life goes, the ship’s explosion plays, and the game holds still — no GAME OVER, no music fading — until that explosion has actually finished. Then everything stops at once. It takes a handful of lines and it is the difference between an ending and a cut.

Music Is Not a Sound Effect

You could load a three minute tune with soundLoad and play it with soundPlay. Do not. Music gets its own family of calls, for reasons that matter:

  • Music has its own volume, separate from the effects, so a player can turn the music down and still hear the shots.

  • There is no sixteen channel limit and no channel number. One handle is one piece of music, and you stop it, pause it, and resume it by that handle.

  • musicStop can fade a piece out over a second or two instead of cutting it.

The calls mirror the ones you already know:

local theme = musicLoad("Singe/menuIntro.flac")

musicSetVolume(50)
musicPlay(theme, -1)

musicLoad gives a handle. musicPlay starts it, with the same loop count as soundPlay: -1 for forever. musicStop(theme) ends it, and musicStop(theme, 1500) takes a second and a half to fade it away. musicUnload gives it back.

Now the trap. Music volume runs from 0 to 128, not 0 to 63. Sound effects use one scale and music uses another, twice as long, for historical reasons that are no comfort at all when your music comes out at half the volume you meant. When you are working with music, double the number you had in mind for an effect.

The piece being loaded there is the engine’s own menu music, out of the Singe folder the engine unpacked into your work folder on your first run. It is ten seconds long and it was written to fade out at the end, so looping it sounds exactly like a ten second loop that keeps fading out. That is fine for learning the calls and no good at all for a finished game, which ships a longer piece of its own. Any of the usual formats will do: the reference’s Music section lists them, and Ogg Vorbis or MP3 are the sensible choices, because a few minutes of music as a WAV is an enormous file.

The Game Gets a Soundtrack

Open the game from lesson nine. Everything here is an addition to it; nothing comes out.

Four things to load, at the top, with the sprites:

local shootClip = soundLoad(DIR .. "art/shoot.wav")
local boomClip  = soundLoad(DIR .. "art/boom.wav")
local clickClip = soundLoad("Singe/click.wav")
local theme     = musicLoad("Singe/menuIntro.flac")

The first two have DIR on them and the last two do not, and that is on purpose. DIR means your game’s folder. A name that begins with Singe/ means the engine’s own folder instead, wherever that is — which is why dofile("Singe/Framework.singe") has worked since lesson seven without a DIR either. Your own files need DIR; the engine’s never do.

Two new variables, beside the others:

local dying        = false
local deathChannel = -1

dying is the moment between the last life going and the game being over: the explosion is still sounding, and nothing on screen is moving.

The shot gets its noise in onInputPressed, right where the shot itself is created, and the restart gets a click so that pressing 1 feels like it did something:

function onInputPressed(what)
    if over then
        if what == SWITCH_START1 then
            soundPlay(clickClip)
            startGame()
        end
        return
    end
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
        soundPlay(shootClip, 0, 35)
    end
end

A rock that is shot bangs, and so does a rock that hits you. In updateShots, beside the score:

                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)

And in updateRocks, where the life is lost, the interesting part:

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            local channel = soundPlay(boomClip)

            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                dying        = true
                deathChannel = channel
                if channel < 0 then
                    endGame()
                end
            end
        end

When the last life goes, the explosion plays and its channel is remembered. The game is now dying, which stops everything moving but does not yet say GAME OVER.

The if channel < 0 is the sixteen channel limit, handled. If every channel happened to be busy at that exact moment, there is no explosion and no channel to wait for, and without those two lines the game would sit in dying forever, waiting for a sound that never played. Waiting for something that cannot arrive is one of the easiest ways to hang a program, and the guard is always cheaper than the bug.

Now the new callback, and the little function it shares with that guard:

function endGame()
    dying        = false
    deathChannel = -1
    over         = true
    musicStop(theme, 1500)
end


function onSoundCompleted(channel)
    if channel == deathChannel then
        endGame()
    end
end

The engine calls onSoundCompleted for every channel that stops, so the first thing it does is check whether this one is the channel it cares about. Everything else — every shot, every rock — passes through and is ignored.

onOverlayUpdate needs to hold still while the explosion runs, which is one word:

    if not over and not dying then
        updateShip()
        updateShots()
        updateRocks()
    end

startGame clears the two new variables and starts the music over:

    dying        = false
    deathChannel = -1
    musicSetVolume(50)
    musicPlay(theme, -1)

And onShutdown gives back what was loaded:

function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
    soundUnload(shootClip)
    soundUnload(boomClip)
    soundUnload(clickClip)
    musicUnload(theme)
end

Run it. Fire at the rocks, let one hit you three times, and listen to the end: the last bang plays out in full, and only when it is gone does the music start to fade and the words come up.

The finished script is in the learn folder as 10-sound.singe if you want to compare.

Try It

  1. Make the shot quieter still. Change the 35 in the shot’s soundPlay to 10, then to 63. Find the number where it sits under the explosions instead of on top of them.

  2. Turn the music down without touching the effects. Change musicSetVolume(50) to musicSetVolume(15). Confirm that the bangs are exactly as loud as they were, which is the whole reason music is its own system.

  3. Cut the ending off. In endGame, change musicStop(theme, 1500) to musicStop(theme). Listen to both endings twice. The difference is a number in one argument and it is not a small difference.

  4. Give the ship an engine. Start soundPlay(clickClip, -1, 12) in startGame, keep the channel it gives you in a variable of its own, and stop it in endGame. The click lasts a fiftieth of a second, so looping it is a buzz, which is as close to an engine as this kit gets. Then take the soundStop out again, play three games in a row, and listen to what you have built.

  5. Count the channels. Print the channel number every time a rock explodes. Then raise ROCK_COUNT until several explode at once, and keep raising it until you see a -1 go by.

Break It on Purpose

You have two volume scales in your head now, and sooner or later the wrong one comes out of your fingers. Add this line on its own, just below the four soundLoad and musicLoad lines:

soundSetVolume(100)

The game refuses to start:

20:soundSetVolume:  Invalid sound volume value:  100

The line number you get is the line you actually typed it on, so yours may not be 20. Then the function that objected, and the value it objected to. The message does not tell you what the range is — that is what the reference’s entry for soundSetVolume is for — but it does tell you the number it would not take, and once you know that effects stop at 63 the fix is one number.

100 is a suspicious number to find in a volume, and it is worth knowing why you typed it. Almost certainly you thought of volume as a percentage, because every volume slider you have ever used goes to 100. Singe’s does not. Effects are 0 to 63 and music is 0 to 128, and neither is a percentage of anything.

This is the general shape of an engine error, as opposed to the Lua errors in lesson one: a line number, the name of the engine function you called, and a complaint about the values you handed it. When you see one, the reference’s entry for that function is the next thing to read.

What You Learned

  • soundLoad reads a clip and returns a handle. Load once, at the top of the file.

  • soundPlay starts a clip and returns a channel, which is a different kind of number from the handle.

  • Singe mixes sixteen channels. When they are all busy, soundPlay returns -1 and nothing plays.

  • Channel numbers are reused. Forget one as soon as you have stopped it.

  • Short effects should be left alone to finish; soundStop is for sounds that have become wrong.

  • soundUnload does not cut off a clip that is still playing.

  • Play a sound where the event happens, not where a condition is true, or it plays sixty times a second.

  • onSoundCompleted(channel) is a callback the engine calls each time a channel goes quiet, for any reason.

  • Music is a separate system with its own handles, its own volume, and no channel limit.

  • Effects volume is 0 to 63. Music volume is 0 to 128. They are not percentages.

Next Time

Your rocks are hit when their rectangles overlap, which is why a shot that passes through a corner of the sky still counts. In lesson eleven you get the engine’s own collision tests, learn what a hit box is, and find out why the rectangle around a round rock is the wrong shape.

Lesson 11: Hitting Things

The finished lesson

Your game from lesson ten works. Shots break rocks, rocks cost lives, and the explosions land in the right places. Watch it closely, though, and it cheats, in both directions. A rock that slides past the tip of a wing takes a life. A shot that goes through the empty sky beside a rock breaks it anyway.

Two things in a game touch when the numbers say they do. Nobody looks at the pictures. This lesson makes the numbers agree with what the player sees: it swaps your hand-written test for the engine’s own, shrinks the boxes being tested so they fit the things inside them, and gives you a switch that shows you those boxes. The picture above is the game with that switch on.

Where You Are

The game asks "do these two touch?" in exactly two places, and both use overlapping, the function you typed in lesson nine. One is in updateRocks, where a rock meets the ship:

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then

The other is in updateShots, where a shot meets a rock:

            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Everything in this lesson changes those two lines and adds a few small functions to feed them. Nothing else in the game moves. The whole finished script is in learn/11-hitting-things.singe if you lose your way.

Read It Once More

Lesson nine already did this part: overlapping is rectangle collision written out by hand. Read it once more before you throw it away, because it is the whole of the idea:

function overlapping(ax, ay, aw, ah, bx, by, bw, bh)
    if ax + aw <= bx then
        return false
    end
    if bx + bw <= ax then
        return false
    end
    if ay + ah <= by then
        return false
    end
    if by + bh <= ay then
        return false
    end
    return true
end

The question "are these two touching?" is hard to answer directly and easy to answer backwards. Two rectangles are not touching when one of them is entirely to the left of the other, or entirely to the right, or entirely above, or entirely below. There is no fifth way to miss. If none of those four is true, they are touching.

Each if is one of the four ways to miss. ax + aw is the right-hand edge of the first rectangle, so ax + aw ⇐ bx reads "the first one ends before the second one starts", which is what "entirely to the left" means in numbers. The same shape three times more, for right, above, and below, with y and the heights in place of x and the widths, and the only thing left is true.

Those are the eight numbers any collision test needs: a corner and a size for each of two things. Keep the shape in your head, because you are about to delete it.

The Engine Already Has It

You met collideRects in lesson seven, where it caught the falling blocks in Dodge. Lesson nine wrote the same test out by hand so you could see inside it. You have seen inside it. Delete overlapping, and change the two lines from Where You Are to call the engine instead:

        if collideRects(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            if not gone and collideRects(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Same eight numbers, in the same order: the first rectangle’s corner and size, then the second one’s. Run it, and the game plays exactly as it did, which is the point. The only difference is at the very edge. Your ⇐ said that two rectangles meeting along an edge are not touching. collideRects says they are, and a rectangle with no width or height touches nothing at all. Those awkward cases are where hand-written versions go quietly wrong, and they are one reason to use the engine’s.

collideRects is one of a family of collision tests, and the family is one part of what this book calls the game kit: a handful of plain functions for the things nearly every game used to write for itself. Testing whether two things touch is one. Saving a number for next time is another, and it is lesson twelve. Waiting a while, sliding a number smoothly from one value to another, and showing how long each frame took are the rest. The reference gives each part a section of its own: Collide, Save, Timer, Tween, and Stats.

The collision tests are the plainest of the lot: plain questions, with no handles to keep and nothing to set up or free. And none of them move anything. collideRects tells you that the ship and the rock are in the same place; what to do about it is yours to decide, and everything interesting in a game happens in that decision.

The Picture Is Not the Hit Box

Lesson ten promised to explain why the rectangle around a round rock is the wrong shape. The rectangle around the ship is wrong too, and for the same reason.

Draw the ship’s 32 by 24 rectangle on paper and shade in the ship. It is a triangle with two fins, so there is empty sky in both top corners and between the fins. The rock is round, so there is empty sky in all four corners of its square. A rock that clips the top corner of the ship’s rectangle has not hit the ship. It has flown past the wing, and a player who loses a life for it will say the game cheated — and be right.

So the box you test is not the picture you draw. It is smaller, and it sits inside the picture. Add three numbers to the constants at the top of your file:

local SHIP_PAD_X  = 6
local SHIP_PAD_Y  = 5
local ROCK_PAD    = 4

The pad is how far in from each edge the real thing starts. Six pixels off each side of the ship and five off the top and bottom leaves a box 20 by 14 in the middle of a 32 by 24 picture, which is about where the hull is. Four off every side of the rock leaves 16 by 16, and that is nearly all rock.

Both boxes are a little smaller than the things they stand for, and that is on purpose. A box slightly too small gives the player near misses that feel like skill. A box slightly too big gives them hits that feel like cheating. Players forgive the first and never the second.

Rather than write the arithmetic out at every test, write it once for each kind of thing:

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end


function shipBox()
    return shipX + SHIP_PAD_X, shipY + SHIP_PAD_Y, shipWidth - SHIP_PAD_X * 2, shipHeight - SHIP_PAD_Y * 2
end

The sizes come from rockWidth and shipWidth and their friends, the measurements lesson nine took from the pictures, so there is still not one raw pixel size in the playing code. Redraw the ship bigger and the box grows with it.

Each of those functions hands back four numbers at once, separated by commas. A function may return as many values as it likes, and the way to catch them is a list of names on the left of the =:

function shipHitsRock(rock)
    local sx, sy, sw, sh = shipBox()
    local rx, ry, rw, rh = rockBox(rock)

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)
end

Now the test in updateRocks reads like the question it is asking:

        if shipHitsRock(rock) then

The padding arithmetic is in exactly two places, and the numbers it uses are at the top of the file, so you can tune how fair the game feels by changing one number rather than by hunting through your tests.

Put the new functions in their places in the alphabet, as lesson nine asked: rockBox after onSoundCompleted, then shipBox and shipHitsRock.

Firing Back

That is the ship’s side done. The other collision in the game is the one you fire back with: every shot against every rock, in updateShots. It has the same problem the ship had, in a smaller size. A shot is a 4 by 10 rectangle tested against the rock’s whole 24 by 24 square, so a shot that only passes through the empty corner beside a rock still breaks it.

You could give the shot a padded box of its own. Look at the numbers first, though. Pad a shot four pixels wide and there is almost nothing left, and testing a whole rectangle to find out whether a sliver of light touched something is more machinery than the question deserves.

A Shot Is Almost a Point

Test the tip instead. collidePointRect asks whether one point falls inside one rectangle — two numbers for the point, then the rectangle’s corner and size:

function shotHitsRock(shot, rock)
    local rx, ry, rw, rh = rockBox(rock)

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)
end

shot.y is the top of the shot and shot.x + shotWidth / 2 is halfway across it, so the point being tested is the middle of the shot’s nose. That is where a player thinks a shot is. The rock’s side of the question uses the same rockBox the ship does, so a rock is the same size whatever hits it.

It goes after shipHitsRock, and the test in updateShots becomes:

            if not gone and shotHitsRock(shot, rock) then

Deciding What Happened

None of the collision tests do anything. They answer, and your code decides. Here are the two places that decide, with their new questions in them. First updateRocks:

        if shipHitsRock(rock) then
            local channel = soundPlay(boomClip)

            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                dying        = true
                deathChannel = channel
                if channel < 0 then
                    endGame()
                end
            end
        end

And the loop inside updateShots:

        for _, rock in ipairs(rocks) do
            if not gone and shotHitsRock(shot, rock) then
                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)
            end
        end

Everything under the questions is exactly what lesson ten left there. A rock that hits the ship bangs, goes back to the top, and costs a life. A rock that is shot bangs, goes back to the top, and scores. The shot goes too, and the not gone stops one shot from breaking two rocks. Change any of that and you change the game, without touching a single collision test, which is the reason the questions and the answers are kept apart.

Run it. Fly close past a rock and let it brush a fin: you keep the life. Shoot just beside a rock and the shot sails past. Shoot into the middle of one and it breaks, the same as ever.

Seeing the Boxes

The hit boxes are invisible, which makes a mistake in them invisible too. Draw them while you are working. One more constant at the top:

local SHOW_BOXES  = false

Two more functions, which go at the very top of the alphabet:

function drawBox(x, y, width, height)
    overlayBox(x, y, x + width - 1, y + height - 1)
end


function drawBoxes()
    colorForeground(0, 255, 0)
    drawBox(shipBox())
    for _, rock in ipairs(rocks) do
        drawBox(rockBox(rock))
    end
end

And in onOverlayUpdate, after the ship is drawn and before the score goes on top:

    spriteDraw(shipSprite, shipX, shipY)
    if SHOW_BOXES then
        drawBoxes()
    end
    drawHud()

Change SHOW_BOXES to true and green outlines appear over the artwork, as in the picture at the top of this lesson. Change it back when you are done. A switch like this, one word at the top of a file that turns on a picture of what the program believes, is worth more than any amount of staring.

What Just Happened

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end

Four values from one return, separated by commas. Lua is happy to hand back as many as you want, and the caller decides how many to keep. When a call like this is the last thing inside another call’s parentheses, all four are passed along, which is why drawBox(rockBox(rock)) works and gives drawBox its four arguments. Anywhere else in an argument list, only the first value survives. That rule bites exactly once, and it bites at the end of this lesson.

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)

collideRects wants eight numbers: corner and size, corner and size. It gives back true or false and changes nothing. Because the answer comes straight back out of the function with return, shipHitsRock(rock) reads like a question wherever it is used.

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)

collidePointRect wants six: a point, then a rectangle. The edge counts as inside, so a shot exactly on the boundary hits. Use it whenever one side of the question is small enough that its size does not matter.

    colorForeground(0, 255, 0)
    overlayBox(x, y, x + width - 1, y + height - 1)

Both of these are from lesson seven. overlayBox takes two corners, not a corner and a size — the one place in this lesson where the numbers change shape — and the - 1 is because both corners are included. colorForeground is a switch that stays flipped, so everything drawBoxes draws comes out green. Sprites and overlayPrint ignore it, so the rest of the game looks the same.

The Rest of the Family

collideRects and collidePointRect will carry most 2D games. The others are there for the shapes rectangles describe badly, and each is the same kind of plain question:

  • collideCircles and collidePointCircle, for anything round. A circle is a center and a radius.

  • collideRectCircle, for a round thing against a square one.

  • collidePointPolygon, for a shape with corners of its own — a dragon, a continent, an odd-shaped button. You give it a flat list of x, y, x, y numbers.

  • collideSegments, for two line segments crossing.

If you are honest, your rock is round, and the circle tests fit it better than any box. Padding is the cheap answer and it is good enough for most games, which is why it comes first. The exact answer is one of the things to try below.

collideSegments matters more than it sounds. Your shot moves six pixels a frame and the rocks are sixteen pixels of hit box, so a shot cannot get past one without being tested inside it. Make the shot fast enough — forty pixels a frame — and it jumps from below a rock to above it, never once being in the same place as the rock, and it never hits anything. Drawing the line from where the shot was to where it is now, and asking collideSegments whether that line crosses an edge, is the cure. Slow things do not need it.

There is one collision callback in Singe, onCollision, and it is not for this. It belongs to the 3D physics engine: bodies with mass, falling and bouncing off one another in three dimensions, telling you where they touched and how hard. You will meet it in lesson twenty-four. Nothing on the overlay reports itself, and nothing needs to. Your rocks are in a list, you know how many there are, and asking is cheap.

And when you want to know not just whether two things met but where the moving one should end up — sliding along a wall instead of stopping dead inside it — the collide calls deliberately do not answer that. A library called bump is bundled with Singe for exactly that job, and the reference’s Included Libraries section says how to reach it.

Try It

  1. Take the padding out. Set ROCK_PAD to 0 and play for a minute. Then set it to 8 and play again. One of them feels like the game is lying to you.

  2. Look at what you are testing. Set SHOW_BOXES to true and watch the green outlines while a rock passes the ship. Now set SHIP_PAD_X to 16, play, and notice that nothing can hit you any more. Work out why from the arithmetic in shipBox.

  3. Make the shot too fast. Set SHOT_SPEED to 40. Count how many rocks you hit out of ten. Work out from the numbers why that happens before you change it back.

  4. Use the whole shot. Rewrite shotHitsRock to use collideRects with the shot’s full rectangle instead of collidePointRect with its nose. Play both and decide which one you prefer; there is no right answer, which is worth knowing.

  5. Make the rock round. Give the rock a circle instead of a box: its center is rock.x + rockWidth / 2 across and rock.y + rockHeight / 2 down, and a radius of 10 is about right. Use collideRectCircle for the ship and collidePointCircle for the shot, and draw the circle in drawBoxes with overlayCircle, which takes a center and a radius.

Break It on Purpose

The two boxes are already four values each, so it is tempting to feed them straight in and skip the eight local names:

function shipHitsRock(rock)
    return collideRects(shipBox(), rockBox(rock))
end

That looks right and it is wrong. Run it and the game stops before it draws a thing:

186:collideRects:  Expected 8 argument(s), got 5.

The line is the one you just typed, so yours may not be 186. Five, though. rockBox(rock) is the last thing in the parentheses, so all four of its values went in. shipBox() is not, so it was cut down to one. One plus four is five, and collideRects will not guess at the other three.

This error comes from the engine rather than from Lua, so it is shaped like the ones in lessons nine and ten: the number at the front is the line, then the name of the function that refused, then the complaint. Put the eight local names back.

What You Learned

  • Collision is arithmetic on rectangles, and you can write it yourself.

  • Two rectangles miss in exactly four ways; if none of them is true, they hit.

  • collideRects takes a corner and a size for each of two rectangles and answers true or false. It counts edges that only touch as touching.

  • The collision tests are part of the game kit, plain functions with nothing to set up. Save, Timer, Tween, and Stats are the rest of it.

  • collidePointRect asks whether a point is inside a rectangle, which is the right question for anything small.

  • The box you test is smaller than the picture you draw, or the game feels unfair.

  • A function can return several values, and only the last call in an argument list passes all of them on.

  • The collision tests only answer. What happens next is your code, and keeping the two apart lets you change either one alone.

  • Drawing your hit boxes on screen turns an invisible bug into a visible one.

  • onCollision is for 3D physics bodies, not for sprites on the overlay.

Next Time

The game counts your score and takes your lives, and the moment you quit, the best score anybody ever got is gone. It starts in the middle of the action the instant it loads. And it keeps track of what it is doing with two true-or-false variables, over and dying, which is exactly the trap lesson seven warned you about. Lesson twelve gives it a title screen, one variable in place of those two, and a high score that is still there tomorrow.

Lesson 12: Score, Lives, and Game Over

The finished lesson

Your game keeps score, takes lives, and says GAME OVER. It is nearly a game. Three things are still missing. It has no front door: it is in the middle of the action the instant it loads. It forgets: quit, and the best score anybody ever got goes with it. And it keeps track of what it is doing with two true-or-false variables, over and dying, which is the trap lesson seven warned you about.

This lesson fixes all three. One variable for what the game is doing, a title screen to start from, a high score that is still there tomorrow, and a second game that starts exactly like the first.

A Game Is Always in Exactly One State

Watch any arcade machine for two minutes. It shows a title and waits for somebody. Somebody presses start and it plays. The player runs out of lives and it says so, then waits again. The machine is always doing exactly one of those things.

Dodge, in lesson seven, kept that in one variable holding a word: "waiting", "playing", or "over". Lesson nine’s game went back to a true-or-false over, and lesson ten added dying beside it. Count what two of those can say. Each is true or false, so together they make four combinations. Three mean something: playing, dying, and over. The fourth, both at once, is nonsense, and your code has to be careful never to produce it. It is careful: look at endGame, which sets dying back to false before it sets over to true. Now add a title screen. That is a third flag, eight combinations, and four of them nonsense. That is lesson seven’s trap exactly, and it is where small games go to die.

So do what Dodge did. Four states, one variable. Put the names of the states under your other constants:

local TITLE   = "title"
local PLAYING = "playing"
local DYING   = "dying"
local OVER    = "over"

Then take over and dying out of your variables, and put one line in their place:

local state        = TITLE

Dodge used the words themselves. Names in capitals are not cleverer, and they do not catch a spelling mistake: Lua treats a misspelled name as nil and a misspelled word as a word that matches nothing, and either one gives you a game that quietly stops responding. What the names buy is a list. Every state the game can be in is written down once, at the top of the file, where you can see all four at a glance.

Everywhere the game used to set a flag, it now sets the state. In updateRocks, where the last life goes:

            if lives <= 0 then
                state        = DYING
                deathChannel = channel

In endGame, two lines become one, and the nonsense combination is gone because there is nothing left to combine:

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
end

And in startGame, the two lines that cleared both flags become state = PLAYING.

One Place That Decides

Every frame, onOverlayUpdate makes the two decisions that matter: what moves, and what words go on top. What moves is one test:

    if state == PLAYING then
        updateShip()
        updateShots()
        updateRocks()
    end

That replaces if not over and not dying then, and it says what it means. On the title, while the last explosion plays, and after the game is over, nothing moves. You get that by not calling the functions that move things. Stopping a game is not a special feature; it is leaving things out.

The world is still drawn every frame, whatever the state, exactly as Dodge drew it. Only the words change. Replace the drawHud() line with this:

    if state == TITLE then
        drawTitle()
    else
        drawHud()
    end

drawTitle is new, and it goes after drawStars:

function drawTitle()
    overlayPrint(25, 6, "R O C K S")
    overlayPrint(25, 9, "BEST " .. best)
    overlayPrint(22, 12, "PRESS 1 TO PLAY")
end

best is the best score so far, and it arrives in the next section; the game will not run until it does. Before the first game the list of rocks is empty, so what the title shows is the stars drifting past and the ship waiting at the bottom, which is all a title screen needs.

One line has to go, or you will never see the title at all. Delete the startGame() at the very bottom of the file. The game begins on its title now, and Starting Again says why that line matters.

drawHud asks one question of its own. Change its if over then to:

    if state == OVER then

The input callback needs the same kind of thinking. Here it is whole:

function onInputPressed(what)
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 and state == PLAYING then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
        soundPlay(shootClip, 0, 35)
    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then
        soundPlay(clickClip)
        startGame()
    end
end

Read it from the top. The arrow keys are recorded whatever the state, because they only say which keys are down, and nothing moves the ship unless the state is PLAYING. Fire means something only while playing. And 1 starts a game from the title or from the game over screen, and not while the last explosion is still sounding: the game is not over until it says so. The parentheses work the way they do in arithmetic. The or inside them is worked out first, and then the and joins it to the key.

Score and Lives

You have had both since lesson nine, and they hardly change. What is new is the best score, which starts life as an ordinary variable. Put it with the others, below lives:

local best         = 0

Show it in the line across the top, between the other two. In drawHud:

    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(25, 1, "BEST " .. best)
    overlayPrint(50, 1, "LIVES " .. lives)

And give endGame the job of noticing a record:

    if score > best then
        best = score
    end

Run it. The title says BEST 0. Press 1, shoot something, lose, and the game over screen shows your score as the best. Press 1 again and the best stays while the score starts over. Now quit, run it again, and look at the title: BEST 0. The record lived exactly as long as the program did. That is the second half of this lesson.

While you are looking at lives, notice that lesson nine wrote the test as lives ⇐ 0, not lives == 0, and keep it that way. Today nothing can take two lives at once, so the two can only ever agree. The day you add a rock that costs two, == 0 steps straight over zero and the player keeps playing on minus one life, while ⇐ 0 keeps working. Ask for what you mean.

Starting Again

You have already deleted the startGame() from the bottom of the file. In lesson ten the first game was started by that line and every later one by pressing 1, which is two ways in. Now there is one. Every game, the first included, starts when somebody presses 1 and startGame runs, so the first game and the fifth start exactly the same way.

startGame has to put back everything a game changes:

function startGame()
    shipX        = (screenWidth - shipWidth) / 2
    score        = 0
    lives        = START_LIVES
    state        = PLAYING
    deathChannel = -1
    shots        = {}
    for i = 1, ROCK_COUNT do
        rocks[i] = {}
        newRock(rocks[i])
    end
    musicSetVolume(50)
    musicPlay(theme, -1)
end

It is just as important to know what it leaves alone, and why. best outlives every game; that is its whole job. The stars are scenery. And goLeft and goRight are not the game’s at all. They are the keyboard, and only the keyboard should change them.

That last one is a bug you have just fixed without noticing. Lesson ten’s input callback started with if over then, and while the game was over it threw every key away except 1. Press the right arrow while GAME OVER is showing, keep holding it, and press 1. The new ship sits still: the press of the right arrow was thrown away, the release has not happened yet, and so goRight is false while the key is plainly down. The ship stays put until you let go and press again. The new callback records the arrow keys in every state, so the held key is still held when the game begins.

Bugs in starting again are the most common bugs in any game, and they all feel the same to play: the second game is subtly wrong and the first one was fine. When that happens, read startGame and ask two questions. What did the last game change that this one does not put back? And what is this one putting back that was never the game’s to touch?

A Number That Outlives the Program

Everything your game has held so far — score, lives, the list of rocks — lives in memory, and memory is gone the instant the program stops.

Singe gives every game a save of its own: a set of names with values under them, written to disk for you. It is another part of the game kit from lesson eleven, so it is the same kind of thing as collideRects: plain calls, nothing to load or free.

saveSet("highScore", 4200)

saveSet takes a name — the key — and a value. The key is yours to choose and never changes; the value is whatever you want to remember. Numbers, strings, true and false, and whole tables of those all go in. Things that only make sense while the program is running do not. A sprite handle is only a number, so it saves, and tomorrow it is a number that means nothing. A function cannot be written down at all, and trying to save one stops the game with an error rather than letting you find out next week.

Reading it back is the other half. Change the line you added for best:

local best         = saveGet("highScore", 0)

It runs once, when the game starts. The second argument is the default: what to answer when nothing has ever been saved under that key. More about that in a moment, because it is the whole of this lesson’s error.

And make endGame write the record down when it falls:

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
    if score > best then
        best = score
        saveSet("highScore", best)
        saveFlush()
    end
end

You do not have to ask Singe to write the file. It writes once at the end of any frame in which something changed, however many keys you set, and again when the game shuts down. saveFlush writes it immediately instead: a new high score is worth a file write of its own, because an arcade cabinet gets switched off at the wall and a frame is a long time.

Run it, set a score, quit, and run it again. The title remembers.

The reference’s Save section lists the rest of the family. saveDelete forgets one key, saveClear forgets everything — that is the "reset high scores" in a service menu — and saveGetAll hands you a copy of the lot, which is useful when you want to print the whole save while you are hunting something.

Where the File Actually Goes

It does not go beside your script, and this is not an accident.

A finished game may live on a disc, on a network share, or inside a single packed file (lesson thirty), and none of those can be written to. A game that saves next to its own script works perfectly on the machine you wrote it on and fails on half the machines it is installed on. Singe 2 did it that way and it was wrong.

So everything Singe writes for a game — the save, screenshots, its log — goes in one place, and singeGetDataPath will tell you where:

debugPrint(singeGetDataPath())

Put that just below the dofile line for a moment and run it. It says data/rocks/: the data folder that appeared in your work folder the first time you ran anything, in lesson one, and inside it a folder named after your game’s folder. In there you will find save.json. Open it in your text editor: it is plain text, and your high score is in there under the name you gave it.

That is the answer whenever you need a file of your own as well. Build the name from singeGetDataPath() and it lands somewhere writable; write to a name of your own invention and sooner or later it does not.

The First Time, There Is Nothing

The very first time anybody runs your game, no high score has ever been saved. saveGet has nothing to hand back, so it hands back the default you gave it:

local best         = saveGet("highScore", 0)

Nothing saved, so best is 0, the title screen says BEST 0, and the first game anybody plays sets a record. That is exactly what you want, and it costs one extra argument.

Leave the 0 out and saveGet has no default to fall back on, so it answers nil — the value Lua uses for "there is nothing here", which you met in lesson three. nil is not zero. You cannot add to it, you cannot compare it with a number, and you cannot glue it onto a string. It goes wrong on the first frame, every time, on every machine where the game has not been played — which includes every machine your players are about to install it on, and not the one you are testing on.

Give every saveGet a default. It is the cheapest habit in this book.

What Just Happened

local TITLE   = "title"

A constant: a name you set once and never change, in capitals so that you can see at a glance that it is one, as in lesson seven. Lua does not enforce it — nothing stops you assigning to TITLE — so the capitals are a message to the next person reading, who is you in a fortnight.

    if state == PLAYING then

The question that decides whether the world moves. When you add a fifth state later — a pause, or a bonus round — the first thing to ask is whether the world moves in it, and this is where the answer goes.

    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then

Without the parentheses, Lua would join the and first and read this as "the key is 1 and the state is the title, or the state is over". Then any key the branches above did not catch would start a game from the game over screen, fire included, and a player still hammering the fire button when the last rock hits would be dropped into a new game the moment GAME OVER appeared. The parentheses make the or happen first. When you mix and and or, add the parentheses even if you think you know the order. The next person to read it will not have to know.

        saveSet("highScore", best)
        saveFlush()

saveSet puts the number in the save; saveFlush puts the save on the disk now rather than at the end of the frame. Both are inside the if, so the file is only written when the record is actually broken, which is a few times a session rather than sixty times a second.

local best         = saveGet("highScore", 0)

Read once, at startup, into an ordinary variable. The rest of the game reads best rather than calling saveGet again, because the save is a file and a variable is a variable. Write to both when the record falls.

Try It

  1. Go back to the title. An arcade machine does not sit on GAME OVER forever. Look up timerAfter in the reference’s Timer section, another part of the game kit, and use it in endGame to put the state back to TITLE five seconds after the game ends. Then press 1 quickly after a game ends and make sure the timer does not throw your new game back to the title three seconds in.

  2. Show the lives as ships. Draw shipSprite once per life in the top right corner with spriteDraw instead of printing the number. A for loop from lesson four, and shipWidth tells you how far apart to put them.

  3. Save more than a number. Add saveSet("gamesPlayed", saveGet("gamesPlayed", 0) + 1) to startGame, and print it on the title screen. Quit, run again, and watch it remember.

  4. Find the file and break it. Open data/rocks/save.json in your editor, change the high score to something absurd, and run the game. Then delete the file entirely and run it again. Both of those will happen to your players.

  5. Reset it from inside the game. Make a key you would never press by accident call saveClear(), and check the title screen afterwards. Careful: best is still in memory, and saveClear does not touch it. Work out what else has to happen.

Break It on Purpose

Take the default out, so the line reads:

local best         = saveGet("highScore")

If you have already set a high score, nothing happens at all, which is the trap: the save has the key, so saveGet hands it back. Delete data/rocks/save.json first, then run it. The title screen never appears, and you get this:

Error executing function 'onOverlayUpdate':  rocks/rocks.singe:101: attempt to concatenate a nil value (upvalue 'best')
stack traceback:
	rocks/rocks.singe:101: in function 'drawTitle'
	rocks/rocks.singe:165: in function 'onOverlayUpdate'

Read it the way lesson eight taught you. The file and the line take you to overlayPrint(25, 9, "BEST " .. best) in drawTitle, and the complaint says something that was nil was glued onto a string. .. joins two strings, and nil is not one. If your lines are laid out differently, your numbers will be too.

The line it names is not where the mistake is. Line 101 is where the game finally tripped over it; the mistake was made near the top of the file, where best was asked for and nothing was there. That gap between where a bad value is made and where it is noticed is the hardest thing about nil, and the reason a default costs one argument and saves an evening.

Put the 0 back.

What You Learned

  • A game is in exactly one state at a time, and true-or-false flags that try to say which one breed combinations that mean nothing.

  • Keep the state in one variable, with its possible values named once at the top of the file.

  • onOverlayUpdate decides what moves and what is said, by asking the state.

  • Stopping a game is a matter of not calling the things that move it.

  • Start every game, the first one included, through one function, and make that function put back everything a game changes — and nothing else.

  • Keys belong to the keyboard. Record them in every state.

  • saveSet stores a value under a key, and saveGet reads it back on a later run.

  • saveFlush writes the file now, for the things you would hate to lose.

  • The save goes in the game’s own data folder, which singeGetDataPath names. Never write beside your script.

  • saveGet with no default answers nil when nothing was saved, and nil breaks the first frame on a machine that has never run your game.

  • When you mix and and or, use parentheses.

Next Time

Your game is a game now, and it is a folder that only you know how to start. Lesson thirteen gives it a games.dat, so the engine’s own menu lists it with a title and a picture, and a player who has never heard of you can start it without typing anything.

Lesson 13: A Game Folder

The finished lesson

Your game is a script in a folder you remember the name of, started by typing its name at a terminal. That is fine for you and useless for anybody else. A player should be able to copy a folder next to Singe, start the menu, see your game listed with its title and its artwork, and press a button. The picture above is that menu, with your game in it.

That takes one new file, about six lines long, and two pictures you can take with one key. Your script does not change at all.

Give the Game a Name

A game has two names, one for the computer and one for people.

The one for the computer is the folder, and you chose it in lesson nine: rocks, with rocks.singe inside it. The folder and the script share a name, the way every lesson has since lesson one, which is why Singe rocks finds the script from the folder alone. Keep that name plain. No spaces, which a terminal reads as the gap between two names. And the same capitals everywhere you type it: on most computers that are not Windows, rocks and Rocks are two different folders, and a game that only runs on your machine is not a game anybody else can have.

The name for people can be anything you like, capitals, spaces, and all, and it does not live in the folder name. It lives in the file this lesson is about, so that renaming the game on the menu never means renaming a folder.

What Goes in the Folder

Everything your game needs, and nothing else. By the end of this lesson it looks like this:

rocks/
    games.dat       What the menu reads
    rocks.singe     The game
    art/            The art kit from lesson nine
        spaceship.png
        asteroid.png
        bullet.png
        star.png
        shoot.wav
        boom.wav
        ...
    cabinet.png     A picture the menu shows beside the list
    marquee.png     A picture the menu shows above it

Anything else that ended up in there while you were learning — walk.singe from lesson nine, the little sound test from lesson ten — is not part of the game. Move them into a folder of their own beside rocks. The art kit also has a few files this game never loads, and they do no harm for now. Lesson thirty is where you go through a game folder and take out everything that is not the game.

The rule behind that layout is that a game never reaches outside its own folder. Not for artwork, not for a sound, and not for a library you also use in another game — if you share code between two games, each one keeps its own copy. There is exactly one place outside the folder a game may load from, and you are already loading from it: the engine’s own Singe folder, where Singe/Framework.singe lives, and since lesson ten the click and the music.

The game folder sits in your work folder, beside the engine:

singe/                 Your work folder
    Singe-v3.00-...    The engine itself, whatever yours is called
    Menu.sh            Starts the menu.  Menu.bat on Windows
    Singe/             Support files.  Not yours; leave them alone
    data/              Everything anything writes, your save among it
    rocks/             Your game

That is the shape a player’s machine has too. The engine wrote Singe, data, and Menu.sh (Menu.bat on Windows) the first time you ran anything, back in lesson one. Lesson one mentioned the first two. The third is new to you, and this lesson puts it to work.

Paths Count from Where Singe Started

You have been doing this since lesson nine, so this is a reminder, not a change.

Every name your game loads — art/spaceship.png, art/boom.wav — is looked for starting at the folder Singe was started in, not the folder your script is in. You start Singe in your work folder, so a bare art/spaceship.png would be looked for in singe/art, which does not exist. DIR is your script’s own folder with the slash already on the end, so a name joined to it points at your file from wherever Singe was started:

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

The menu starts Singe in the folder Menu.sh sits in, which is your work folder again, so DIR does there exactly what it does for you. It keeps doing it when the game is packed into a single file in lesson thirty, when somebody else’s work folder is called something else entirely, and on a machine you will never see. A name that begins Singe/ is the engine’s folder and never needs DIR; every name that is yours does.

games.dat

games.dat is how a game introduces itself. The menu reads the games.dat of every game folder beside it and lists what it finds. No games.dat, no listing: your folder is invisible, however good the game inside it is.

Make a new file called games.dat in your rocks folder. This is the smallest one that works:

GAMES = {
    {
        TITLE  = "Rocks",
        SCRIPT = "rocks/rocks.singe"
    }
}

That is Lua, and it is a table of the kind you met in lesson six: GAMES is a list, and each thing in the list is a record describing one game. One folder can hold several games — that is why it is a list — but yours holds one.

SCRIPT is the field the engine needs to run the game, and TITLE the one the menu needs to list it. The script’s path is counted from the folder above the games.dat, not from the folder the games.dat is in. So a games.dat inside rocks names its own script as rocks/rocks.singe. That looks like it says rocks twice and it is correct. Every other path in the file works the same way. Get it wrong and nothing complains when you type the name: the entry simply never matches the script you ran.

TITLE is the name for people from the start of this lesson. It is what the menu shows, and games are listed in title order, so a title is also where your game sits in the list.

Telling the Menu More

The menu has a whole panel to fill beside the list, and it fills it from the rest of the entry:

GAMES = {
    {
        TITLE       = "Rocks",
        SCRIPT      = "rocks/rocks.singe",
        CANVAS_X    = 720,
        CANVAS_Y    = 480,
        YEAR        = 2026,
        GENRE       = "Shooter",
        DEVELOPER   = "Your Name Here",
        PUBLISHER   = "Your Name Here",
        DESCRIPTION = "Shoot the rocks before they reach your ship.",
        CABINET     = "rocks/cabinet.png",
        MARQUEE     = "rocks/marquee.png"
    }
}

CABINET and MARQUEE are ordinary image files in your game folder, in any format Singe can read. The cabinet art is the big picture beside the list and the marquee is the strip above it. Make them whatever size you like; the menu fits them into their panels.

You do not need a drawing program to make them, because your game can take its own picture. Run it, and when the screen looks the way you want the world to see it, press F12 (or F11, because some desktops keep F12 for themselves). Singe saves a picture of the window into your game’s data folder, data/rocks, named singe000.png, then singe001.png, and so on. Take one of the title screen and one in the middle of a fight. Copy them into your rocks folder and rename them: the fight is cabinet.png, the title is marquee.png.

A real marquee is a wide strip with the game’s name in big letters, and a whole screen squeezed into it looks like a postage stamp. It will do until you have something better. Leave MARQUEE out and the menu puts the engine’s own missing picture there instead, a pink checkerboard that says MISSING, which is worse.

YEAR, GENRE, DEVELOPER, PUBLISHER, and DESCRIPTION are the text underneath, and the engine never looks at them. They are for the person reading the menu, which is the point.

CANVAS_X and CANVAS_Y are the size of your game’s world, and 720 by 480 is the default — the same world you have been drawing in since lesson one. Set them only if your game wants a different shape. A game with no VIDEO field is a game with no video, which is what yours is; lesson fourteen is where that field starts to matter.

The reference’s games.dat section lists every field there is, including several for hardware you do not have yet. A few more are worth knowing the names of now.

REQUIRES says what a game needs from the machine beyond plain 2D: "GUI" for the menus and pages of lesson twenty, "SCENE" for the 3D that starts in lesson twenty-two, and a few more. The menu reads it so that it can tell a player "this machine cannot run that" instead of letting the game fail halfway in. Rocks is plain 2D, and leaving REQUIRES out means exactly that, so leave it out. You will rarely have to work out the list yourself, because Singe notices what a game uses as it runs and says so when the entry does not list it. From lesson twenty on you will see lines like this one, whether or not the game has a games.dat at all:

Warning:  this game uses GUI, which its games.dat does not list in REQUIRES.

It is advice, not an error; the game runs either way. The cure is one line in the entry, REQUIRES = { "GUI" },, and packing a game in lesson thirty writes the list for you if the entry has none. Its partner TIER, a number from 0 to 3, says how much machine a game wants, and can wait until you write a game heavy enough to care.

GAME_ID is a unique identity for your game, which the online high score tables in lesson twenty-eight need and nothing else does. And RESOLUTION_X and RESOLUTION_Y ask for a particular window size. Ignore the rest until something sends you looking.

Running It from the Menu

Run Menu.sh — Menu.bat on Windows — from your work folder. It finds the newest Singe beside it and starts the menu.

Your game is in the list, with its artwork beside it and its description underneath. It is the only thing in the list, because rocks is the only folder you have given a games.dat; hello, dodge, and the rest are not games as far as the menu can tell. Up and down move one game, left and right move a page, and start or a fire button plays the one that is selected. Quit the game with Escape and you are back at the menu, on the same game, ready to go again. The menu remembers which game you were on between runs, too.

That is the whole of shipping a game, as far as the engine is concerned. A player copies your folder next to Singe and it appears.

Typing the name still works, and works the same way:

Singe rocks

When you launch a script by hand like that, Singe looks for a games.dat beside it — and in up to three folders above it — and if an entry names the script you launched, that entry’s settings apply to it. So a game plays the same from a terminal as from the menu, which means you can go on working the way you have been, with -R and a text editor, and still trust what a player will get. It writes to the same place, too: started either way, your game’s save is the one in data/rocks.

Later: One File

A folder is easy to work in and slightly awkward to give away: a dozen files, a folder inside a folder, and a player who unzips it into the wrong place. A finished Singe game can be packed into a single .game file that the engine runs directly, artwork and sounds and all, which a player copies next to Singe and is done.

Nothing in your game has to change for that. It is lesson thirty, and it is worth waiting for: pack a game that is not finished and you will pack it again tomorrow.

What Just Happened

GAMES = {
    {

Two braces, because it is a list of records. The outer one is the list. The inner one is the first thing in the list, which is the record for one game. Getting one of them wrong is the usual mistake, and Lua will tell you the line.

        SCRIPT      = "rocks/rocks.singe",

Counted from the folder above the games.dat, which is your work folder. It is the same name you would type after Singe to run the script by hand, and that is the easiest way to remember it.

The comma at the end of the line separates one field from the next, exactly as in lesson six. The last field in a record has no comma after it — Lua does not mind if it does, but leave it off and your file will look like everybody else’s. A comma that is missing in the middle is another matter, and it is this lesson’s error.

        CABINET     = "rocks/cabinet.png",

A picture the menu loads, not your game, so it is named the way SCRIPT is, from the folder above, and not with DIR. DIR belongs to your script while it runs, and the menu and the engine read games.dat before your script has started.

Try It

  1. Make better artwork. If you have a drawing program, make a proper marquee.png: a wide strip with ROCKS across it in big letters. Put it in place of the screenshot and look at the menu again.

  2. Give Dodge a games.dat. Write a games.dat in your dodge folder from lesson seven and start the menu. Two games now, in title order. Then change the TITLE of Rocks to Asteroid Field and watch it move above Dodge: the list is sorted by title, not by folder.

  3. Break games.dat for the menu. Delete one of the closing braces in the games.dat in rocks and start the menu. Your game is gone from the list, and the terminal says why. Put it back.

  4. Get SCRIPT wrong. Set CANVAS_X to 1280 and CANVAS_Y to 720, and run Singe rocks. The field is wider. Now change SCRIPT to rocks.singe and run it again. The game is back to its old size, and nothing told you: the entry no longer names the script you ran, so it does not apply. Put both back.

  5. Find your save. Start the game from the menu, set a high score, quit back to the menu, and quit the menu. Run Singe rocks and look at the title. Then look in data/rocks for the file that remembered it.

Break It on Purpose

Take the comma off the end of the TITLE line, so the top of the file reads:

GAMES = {
    {
        TITLE       = "Rocks"
        SCRIPT      = "rocks/rocks.singe",

Run Singe rocks. The game starts, and the terminal says this:

Note:  rocks/games.dat ignored:  [string "rocks/games.dat"]:4: '}' expected (to close '{' at line 2) near 'SCRIPT'

Your game still runs, because a game started by name does not need its entry. It just runs without it. Start the menu, though, and your game is gone. If it was the only one there, the list says No games yet, and the terminal says the same thing a different way:

rocks/games.dat:  rocks/games.dat:4: '}' expected (to close '{' at line 2) near 'SCRIPT'  Skipped.

Read it like any other Lua error. The file is rocks/games.dat and the line is 4. But line 4 is the SCRIPT line, and there is nothing wrong with it. The mistake is at the end of line 3. After TITLE = "Rocks", Lua expected either a comma and another field, or the } that closes the record that began on line 2. It found SCRIPT instead, so line 4 is where it noticed. Its guess at the fix — a } — is wrong; its line is out by one. When an error points at the start of a line, look at the end of the line before it.

Put the comma back, and start the menu again.

What You Learned

  • A game is a folder: the script, its artwork, and a games.dat, and nothing from outside it except the engine’s own Singe folder.

  • The folder’s name is for the computer, so keep it plain. The name for people is TITLE.

  • Names your script loads are counted from where Singe was started, which is why every one of them is built from DIR.

  • games.dat is a Lua file holding a GAMES list, and each entry is one game.

  • An entry needs TITLE and SCRIPT and nothing else; paths in it count from the folder above the games.dat.

  • CABINET, MARQUEE, YEAR, GENRE, DEVELOPER, PUBLISHER, and DESCRIPTION are what the menu shows the player, and F12 takes a picture you can use for the first two.

  • REQUIRES tells the menu what a game needs beyond 2D, and Singe warns you when a game uses something its entry does not list.

  • Menu.sh or Menu.bat starts the bundled menu, which lists every game folder beside it, sorted by title.

  • A game launched by name gets its games.dat entry too, so it behaves the same either way, and a games.dat that will not load is reported and ignored.

  • A finished game can be packed into one file later, in lesson thirty.

Next Time

That is part two finished: you have a game, with art, sound, collision, score, and a way for somebody else to run it. Part three is about the thing almost no other engine does — playing film as the world the game happens in — and lesson fourteen starts with the disc, the frame, and the wait.

Lesson 14: Playing Video

The finished lesson

Singe can play a film and run your game inside it. The picture becomes the world, and the overlay you have been drawing on since lesson one is laid over the top of it. In this lesson you will start a video, find out which frame is showing, stop it, and jump to any moment you like.

Before any of that, one thing needs saying plainly, because it decides whether you should read this part of the book at all.

A Game Plays Video Only If It Asks To

Singe is a game engine. Everything you built in parts one and two — the sprites, the sound, the collisions, the score, the game folder — is the whole of Singe, and none of it involves video. What part three adds is an extra: a game may ask for a film to be playing behind it, and then the film is the world instead of a black canvas.

Nothing else changes. onOverlayUpdate is still called sixty times a second. overlayPrint still counts in character cells. Your sprites draw where they drew before. A game with video and a game without it are written the same way, with the same functions, and share the same book.

So if the game you want to make has no video in it, you may close this part now and go to part four. Nothing in part four depends on anything in part three, and the only lessons that need this one are the four that follow it.

Still here? Good.

You Already Have a Video

You do not need to find one, buy one, or make one. The first time you ran Singe in lesson one, a folder called Singe appeared in your work folder. Open it and look: among the files the engine unpacked there is menuBackground.mkv. It is the backdrop the engine’s own menu uses, it is 720 by 480 pixels, and it is 420 frames long — about fourteen seconds.

That is the video for this lesson and the two after it.

Make a folder called movie in your work folder, beside the folders from the other lessons, and a file inside it called movie.singe. That is all the setting up there is. You run Singe from the work folder, as you have since lesson one, so the Singe folder, video and all, is right there beside your game, and Singe/menuBackground.mkv is the name you will hand the engine in a moment. Nothing needs copying.

Type This In

dofile("Singe/Framework.singe")


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    return OVERLAY_UPDATED
end


discPlay()

Save it.

Run It

The video is not part of your script, so you do not load it in your script. You hand it to the engine on the command line, with -v:

Singe -R -v Singe/menuBackground.mkv movie

-v is short for --framefile, and it names the video the game is to play. The name of your script comes last, as it always has. -R is the same -R you have been using since lesson one, and it still restarts the game when you save.

Asking is the whole point of -v. If you drop a video file next to your script and say nothing, the engine notices it, says so on the console, and runs your game without it. A game is a video game only when somebody says it is.

A window opens. A ball of orange fire fills it, a dragon forms out of the fire, the word SINGE appears under it, and then a magenta grid rolls away under an orange sun. In the top left corner, over all of it, is a number counting up.

Watch it to the end. Then watch what happens at the end.

What Just Happened

discPlay()

Singe calls the video the disc, and every function that drives it begins with disc. The name is historical: the engine began life playing games that kept their film on a laserdisc, and the name stuck to the idea. It is a video file on your hard drive and nothing more.

A game has at most one disc, so none of the disc functions takes an argument saying which one. There is only the one.

This line is not inside any function. It sits at the bottom of the file, on its own, and it runs once when Singe loads your script — before the first onOverlayUpdate, before anything else. Singe has no onStartup callback because it does not need one: a Lua script is a list of instructions, and anything you write outside a function happens as the file is read. Startup code goes at the bottom, below the functions, by convention.

You need discPlay() because the disc does not start itself. When the game begins, the engine parks the disc on frame one and pauses it there. Nothing moves until you ask.

    overlayPrint(2, 2, "Frame " .. discGetFrame())

discGetFrame answers one question: which frame is showing right now? It takes no arguments and hands back a number.

Notice where that number is drawn. Column 2, row 2 — exactly where Hello! went in lesson one, and it lands in the same place on screen. The overlay you draw on is half the size of the video on each side, which for a 720 by 480 video is 360 by 240, which is exactly the size you have been drawing on for thirteen lessons. Your coordinates did not move. If you ever play a video of some other size, the overlay changes size with it, and overlaySetResolution sets it to whatever you want; the reference’s entry has the details.

This is the whole idea of the overlay. The video is underneath. Your drawing is on top, and wherever you have not drawn, the film shows through. That is why overlayClear matters even more now than it did: clear the overlay and you are looking at the film.

A Frame Is an Address

The number discGetFrame returns is a frame number. A frame is one still picture. This video holds 420 of them and shows about thirty every second, so it lasts about fourteen seconds.

Frames are counted from zero, so this video has frames 0 to 419. The count and the last number are not the same, which catches everybody once. discGetFrameCount tells you the count — 420 — and the highest frame you can ask for is one less than that.

The important thing about a frame number is that it never changes and never drifts. Frame 110 is the moment the dragon breathes fire, in this copy of the file, on this machine, today and next year. Seconds drift, because a video does not always play at exactly the rate you think. A frame number is the address of a moment, and addresses are what a video game is built out of: you write down the frame where the dragon appears, and from then on you can send the film there whenever you like.

Finding those numbers is a job you do once per video, and the script you wrote is the tool for it: run the film, watch the counter, write down the frames where things happen. Everything in lesson sixteen is built on a list of numbers found exactly that way.

What Happened at the End

The counter reached 419, and then it was 0 again and the fire was back.

When the disc runs off the end, the engine starts it again from frame zero. It does not stop, and it does not tell you. A real game never lets it get there: it watches the frame number and sends the disc somewhere else before the end arrives. Forgetting to do that is why a half finished video game suddenly plays its own title sequence in the middle of a fight.

Stopping, Jumping, and Asking

Add this function above onOverlayUpdate:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        if discGetState() == DISC_PLAYING then
            discPause()
        else
            discPlay()
        end
    elseif what == SWITCH_LEFT then
        discSearch(0)
    elseif what == SWITCH_RIGHT then
        discSkipForward(30)
    elseif what == SWITCH_START1 then
        discStop()
    end
end

Save, and try each one. Space plays and pauses. Left goes back to the start. Right jumps on about a second. The 1 key stops the disc altogether, and what you get is a blue screen — the color a laserdisc player showed when it had stopped, kept because a great many games drew their score table on it.

Five new calls there, and they divide into two kinds.

Asking. discGetState hands back one of four names the engine has already defined for you: DISC_PLAYING, DISC_PAUSED, DISC_STOPPED, and DISC_EJECTED. They are like OVERLAY_UPDATED — no quotes, because they are names for values rather than text. Compare with == as you compared numbers in lesson three.

Telling. discPlay starts or resumes. discPause freezes on the frame that is showing and leaves it on screen. discStop is the heavier one: the picture is replaced by the blue screen, discGetFrame answers 0 until the disc runs again, and discPause and the skip calls are ignored while it is stopped. Any of discPlay, discSearch, or discSkipToFrame un-stops it.

Two calls send the disc to a frame, and the difference between them is the only thing in this lesson worth memorising:

  • discSearch(frame) goes there and pauses on it.

  • discSkipToFrame(frame) goes there and plays from it.

Search when you want to park on a picture and wait. Skip when you want a scene to start. discSkipForward(30) and discSkipBackward(30) are the same idea measured from where you are rather than from the beginning, and they leave the disc playing if it was playing and paused if it was paused.

There is also discPauseAtFrame, which does exactly what discSearch does under an older name. The reference marks it as a legacy alias. You will see it in other people’s scripts; write discSearch in your own.

Waiting Is Harder Than It Sounds

Here is the sentence every video game is made of:

Play from frame 0 to frame 120, then ask the player a question.

Try to write it. You cannot write "play, then wait, then ask", because you do not have anywhere to write it. You have onOverlayUpdate, which Singe calls sixty times a second and which must return immediately every single time. A function that sat and waited would stop the engine dead: no drawing, no input, no video.

So you cannot say "then". You have to turn "then" into a variable that remembers where you have got to, and check it on every one of those sixty calls:

local asking = false


function onOverlayUpdate()
    overlayClear()
    if not asking and discGetFrame() >= 120 then
        discPause()
        asking = true
    end
    if asking then
        overlayPrint(2, 4, "Left or right?")
    end
    return OVERLAY_UPDATED
end

That works. Read it and you can see it works. But notice what it cost: one variable, whose only job is to remember which part of the sentence you are in, and two if statements to keep it honest.

Now add the rest of the scene. The player answers, so one of two things plays next. Each of those ends somewhere and asks another question. A modest branching game has forty of these moments, and every one of them wants its own variable and its own if. You end up with a script where the story is not written down anywhere — it is spread across a dozen flags, and to find out what happens after the dragon you have to read all of them.

Hold that thought. Lesson fifteen is nothing but the fix for it.

When There Is No Video

Run your script the plain way again, with no -v:

Singe -R movie

Nothing crashes. You get a black window with Frame 0 in the corner.

This is worth understanding, because it is the reassuring half of the promise at the top of this lesson. A game without a disc still runs every disc call you make; they do nothing useful. The engine documents exactly what they answer, and it never changes: discGetFrame and discGetFrameCount return 0, discGetState returns DISC_EJECTED, discGetWidth and discGetHeight return the size of the canvas, and discPlay, discPause, discSearch, and the rest are recorded in the log and otherwise ignored.

You cannot break a script by calling a disc function when there is no disc.

When a script needs to know, it asks SINGE_DISC. That is another name the engine defines before your script runs, and it is true when the game has a video and false when the world is a plain canvas. It is the right way to write a game that can run both ways:

    if not SINGE_DISC then
        overlayPrint(2, 2, "This game has no video.")
        overlayPrint(2, 4, "Run it again with -v Singe/menuBackground.mkv")
        return OVERLAY_UPDATED
    end

not flips a true or false value over, as it did in lesson three.

The Whole Thing

Put together, with a small function that turns the state into words and a frame to hold at, this is the finished script. It is a frame finder: the tool you will use every time you meet a new video.

dofile("Singe/Framework.singe")

local stopAt = 400
local held   = false


local function stateName()
    local state = discGetState()

    if state == DISC_PLAYING then
        return "playing"
    elseif state == DISC_PAUSED then
        return "paused"
    elseif state == DISC_STOPPED then
        return "stopped"
    end
    return "not there"
end


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        if discGetState() == DISC_PLAYING then
            discPause()
        else
            discPlay()
        end
    elseif what == SWITCH_LEFT then
        discSearch(0)
        held = false
    elseif what == SWITCH_RIGHT then
        discSkipForward(30)
    elseif what == SWITCH_START1 then
        discStop()
        held = false
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    overlayClear()
    if not SINGE_DISC then
        overlayPrint(2, 2, "This game has no video.")
        overlayPrint(2, 4, "Run it again with -v Singe/menuBackground.mkv")
        return OVERLAY_UPDATED
    end

    if not held and frame >= stopAt then
        discPause()
        held = true
    end

    overlayPrint(2, 2, "Frame " .. frame .. " of " .. discGetFrameCount())
    overlayPrint(2, 4, "The disc is " .. stateName() .. ".")
    overlayPrint(2, 6, "Space plays and pauses.  Left rewinds.")
    overlayPrint(2, 7, "Right jumps on a second.  1 stops the disc.")
    if held then
        overlayPrint(2, 9, "Holding at frame " .. stopAt .. ".")
    end

    return OVERLAY_UPDATED
end


discPlay()

held is the same kind of variable as asking above, and it is here for a reason you can test: take it out, leave if frame >= stopAt then discPause() end, and then try to press space to carry on past frame 400. You cannot. The disc resumes for a sixtieth of a second and the next onOverlayUpdate pauses it again, forever. held is how you say "I have already done this once".

Try It

  1. Find the dragon. Run it, watch the counter, and write down the frame where the dragon first appears, the frame where it breathes fire, and the frame where the grid takes over the screen. You will want these three numbers in lesson sixteen.

  2. Step through it. Change discSkipForward(30) to discSkipForward(1) and hold the right arrow down. Now change stopAt to a frame in the middle of the dragon and use discSearch and the arrow key to land on it exactly.

  3. Make it loop. Change the hold so that instead of pausing at frame 400 it calls discSkipToFrame(0). You have built an attract mode: a scene that plays forever until somebody presses a button.

  4. Ask for a frame that is not there. Change the SWITCH_RIGHT line to discSkipToFrame(100000). It does not crash. Read the reference’s entry for discSkipToFrame and find the sentence that says why.

  5. Play it without the video. Run Singe -R movie and then press every key. Nothing you press can break it.

Break It on Purpose

The mistake that costs the most time here is not a Lua mistake. Run this:

Singe -R -v menuBackground.mkv movie

The path is wrong — it is counted from the work folder, and the video is in the Singe folder there, not lying loose — and Singe will not start. What it does instead is print its entire list of command line options, which is alarming the first time, and then this as the very last line:

Error:  Unable to locate video.

A wall of options like that always means the same thing: the engine never got as far as your game. Ignore the wall and read the last line.

That one is easy. The unhelpful version of it is running with no -v at all and forgetting you did. There is no error, because a game without a video is a perfectly good game. You get a black screen and a counter stuck on 0, and you go looking for the bug in your script for twenty minutes.

That is what the SINGE_DISC block in the finished script is for. Three lines of it, and the game tells you what is wrong instead of sulking. Put a check like that in every script you write that needs a video.

What You Learned

  • A game plays video only when it asks to, and everything else in Singe works the same either way.

  • Singe calls the video the disc. A game has one, and the disc functions take no handle because there is nothing to choose between.

  • The video goes on the command line with -v, not in the script.

  • The overlay is drawn over the picture, and the film shows through wherever you have not drawn.

  • A frame is one still picture, counted from zero, and a frame number is the address of a moment.

  • discGetFrame asks where the disc is; discGetFrameCount says how many frames there are; discGetState says what the disc is doing.

  • discPlay, discPause, and discStop drive it. discSearch goes to a frame and pauses; discSkipToFrame goes to a frame and plays.

  • A disc that runs off the end starts again at frame zero without telling you.

  • Without a disc every disc call is harmless, and SINGE_DISC is how a script tells which kind of game it is in.

  • You cannot wait inside onOverlayUpdate, so "then" has to be spelled out as a variable.

Next Time

That last point is the sore one. A video game is a list of steps — play this, ask that, play the other — and you have just seen that the callback model cannot say "then" without a flag and an if for every step. Lesson fifteen shows you the other way Singe lets you write a script, in which "then" is a new line.

Lesson 15: The Other Way to Write It

The finished lesson

Every lesson so far has been written the same way. You write functions whose names begin with on, Singe calls them when it feels like it, and you never say what order anything happens in. That is the event driven model, and it is how most game engines work.

Singe has a second model. In it you write your game as a list of steps, from the first line to the last, and you are allowed to wait. In this lesson you will write the same short video sequence both ways and see the difference with your own eyes.

The Sequence

Here is what the game does, in English:

  1. Start the film at the beginning and play it up to frame 120.

  2. Stop there and ask the player to press the space bar.

  3. When they press it, play on to frame 300.

  4. Stop there, say "The end.", wait four seconds, and quit.

Four steps. Read them again and notice that every one of them contains the word "then", spoken or not.

The Way You Know

Make a file called events.singe in the movie folder from lesson fourteen, and type this:

dofile("Singe/Framework.singe")

local step    = 1
local endedAt = 0


function onInputPressed(what)
    if what == SWITCH_BUTTON1 and step == 2 then
        step = 3
        discPlay()
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    overlayClear()
    overlayPrint(2, 2, "Frame " .. frame)

    if step == 1 then
        if frame >= 120 then
            discPause()
            step = 2
        end
    elseif step == 2 then
        overlayPrint(2, 4, "Press the space bar to go on.")
    elseif step == 3 then
        if frame >= 300 then
            discPause()
            endedAt = singeGetTicks()
            step = 4
        end
    elseif step == 4 then
        overlayPrint(2, 4, "The end.")
        if singeGetTicks() - endedAt > 4000 then
            singeQuit()
        end
    end

    return OVERLAY_UPDATED
end


discSearch(0)
discPlay()

Run it. Naming the folder would run movie.singe, so name the script instead, the way lesson one showed you:

Singe -R -v Singe/menuBackground.mkv movie/events.singe

It works. It does exactly the four steps. singeGetTicks is new — it hands back the number of milliseconds since the engine started, which is the ordinary way to measure a stretch of time — and singeQuit ends the game, which is what the engine does for you when you press Escape.

Now read the script and try to find the four steps in it. They are there, but they are inside out. The order of the story is written in the values of step, not in the order of the lines, and step is set in one function and read in another. To answer "what happens after the player presses space?" you have to hold the whole thing in your head at once.

And this is the easy version. There are two decisions in it.

The Other Way

Start a new file, steps.singe, and type this:

local message = ""
local pressed = false


local function drawFrame()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    overlayPrint(2, 4, message)
end


local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end


local function waitForButton()
    pressed = false
    while not pressed do
        drawFrame()
        singeYield()
    end
end


local function waitSeconds(seconds)
    local stopTime = singeGetTicks() + seconds * 1000

    while singeGetTicks() < stopTime do
        drawFrame()
        singeYield()
    end
end


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        pressed = true
    end
end


function singeMain()
    discSearch(0)
    discPlay()
    playTo(120)
    discPause()

    message = "Press the space bar to go on."
    waitForButton()

    message = ""
    discPlay()
    playTo(300)
    discPause()

    message = "The end."
    waitSeconds(4)
end


dofile("Singe/Framework.singe")

Run it the same way, ending in movie/steps.singe. It does the same four things.

Now read singeMain. The four steps are the four paragraphs, in order, top to bottom, and there is no step variable anywhere because the position in the story is the position in the function. That is the whole point of this lesson.

What Just Happened

function singeMain()

singeMain is a name Singe looks for, like onOverlayUpdate. If your script defines it, the framework runs your game from it: it is called once, at the start, and your game lasts as long as it lasts. When it returns, the game quits.

        singeYield()

This is the call that makes it possible, and it means "let a frame happen".

Singe is not doing two things at once — nothing here is running in parallel, whatever the word threaded suggests. What happens is that singeYield stops your function where it stands, hands control back to the engine, and remembers the exact spot. The engine draws the frame, reads the input, moves the video on, and then starts your function again from the line after the singeYield, with every variable exactly as you left it.

So a while loop with a singeYield in it is a way of waiting. It is the only way of waiting, and you must put one in every loop that is waiting for something. This is a deal you are making with the engine: you may sit and wait, as long as you give the frame back sixty times a second.

local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end

Singe has no "wait until the video reaches frame 120" function. It does not need one, because you can write it in four lines, and you just did. Keep going while the disc is short of the frame you want; give a frame back each time round.

waitForButton is the same shape with a different question, and waitSeconds is the same shape again with a clock. Three small functions, written once, and singeMain reads like the English sentences at the top of the lesson because of them. This is exactly what lesson five said your own functions were for.

        drawFrame()
        singeYield()

Every wait loop draws before it yields, and this is the part that surprises people. In the threaded model there is no onOverlayUpdate of your own, so nothing draws unless you draw it. Whatever you draw before a singeYield is what appears on that frame. Stop drawing and the overlay stops changing.

That is why message exists. singeMain sets it, and drawFrame prints it, and the three wait loops all call drawFrame. It is a small price for getting the story back in order.

dofile("Singe/Framework.singe")

At the bottom. This matters more than anything else in the lesson, so it is worth knowing why.

dofile runs another script inside yours, and one of the things the framework does as it runs is look for a function called singeMain. If it finds one it wraps your game around it and writes an onOverlayUpdate of its own, whose entire job is to start your singeMain again once per frame. If it does not find one, it does nothing of the sort, and your game is an ordinary event driven game.

So the framework has to be loaded after singeMain exists. Load it at the top, the way you have every lesson since the seventh, and at the moment it looks there is no singeMain yet, and you get a game with no game in it.

The Rules

There are four, and between them they cover every mistake you can make here.

The framework goes last. For the reason above.

Do not write your own onOverlayUpdate. The framework has written one, and there can only be one: whichever of the two is written last wins, and the other is thrown away without a word. Above the dofile, yours goes and your drawing never appears. Below it, the framework’s goes and your singeMain never runs again. Draw from inside singeMain instead.

Every waiting loop needs a singeYield. A loop without one never gives the frame back. The window stops redrawing, stops responding, and the game is gone; you close the terminal to get out of it. There is no error message, because from the engine’s point of view your function has not finished yet.

Returning from singeMain quits the game. Which is tidy when you mean it and a surprise when you do not. A game that should keep going forever ends with a loop that never exits:

    while true do
        drawFrame()
        singeYield()
    end

Input Still Arrives

Look again at where pressed is set:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        pressed = true
    end
end

That is a callback, in a script that is written as a list of steps. Both models are running at once, and they are meant to be.

When singeMain exists, only onOverlayUpdate is taken away from you. Everything else — onInputPressed, onInputReleased, onKeyPressed, onSoundCompleted, onShutdown, all of them — fires exactly as it always did, in the gaps between your yields. So the usual way to write a game in this model is the way you just did: the story in singeMain, and a small callback that catches an event and leaves a note for the story to find.

waitForButton sets pressed to false before it starts waiting, which throws away anything the player mashed earlier. Leave that line out and a button pressed during the video counts as the answer to a question that has not been asked yet.

Which One to Use

Neither model is the better one. They suit different jobs, and a real game uses whichever fits.

The threaded model suits anything that is a sequence. Play this, then ask, then play that. An opening. A cut scene. A tutorial. A boss fight with three phases. Anything you would naturally describe as a numbered list is a singeMain waiting to be written, and video is the most sequential thing there is, which is why part three arrives at it here.

The event driven model suits anything that is a situation. Ten enemies and a player, all moving, all colliding, none of them in any order. The game you wrote in lesson seven has no sequence in it at all: every frame is the same question asked again, which is exactly the shape of onOverlayUpdate. Write that as a list of steps and you gain nothing and lose the clarity.

When a game is both — and most are — it is written as both. singeMain walks through the levels in order, and inside each level a loop does the lesson seven work sixty times a second until the level ends.

Try It

  1. Add a step. After waitForButton, make the film jump backwards instead: discSkipToFrame(0), then playTo(60), then carry on as before. Two new lines in one place, and nothing else in the script has to know.

  2. Add the same step to the other one. Now do it to events.singe. Count how many places you had to touch.

  3. Write waitFrames. A fourth helper, next to the other three, that waits for a given number of frames of video rather than a given number of seconds. Use discGetFrame and remember where you started.

  4. Take a yield out. Delete the singeYield() inside playTo and run it. Be ready to close the terminal, because nothing else stops it. Now put it back and delete drawFrame() instead, and work out from what you see why the frame counter stops but the film does not.

  5. Make it a loop. Put the whole of singeMain inside while true do …​ end so the sequence starts over instead of quitting. Escape still gets you out, because that has never been your job.

Break It on Purpose

Move the dofile("Singe/Framework.singe") line from the bottom of steps.singe to the top, and run it.

There is no error. Nothing is printed. The window opens, the first frame of the film sits there, and that is all that ever happens.

This is the worst kind of bug and the reason it is worth meeting on purpose. Nothing has gone wrong, in the engine’s view: your script loaded, the framework loaded, and neither of them defined an onOverlayUpdate, so the engine has nothing to call. The disc is parked on frame one, paused, exactly as the engine left it, because the discPlay that would have started it is inside a singeMain that nobody ever runs.

When a threaded game does nothing at all, look at the last line of the file first. It is almost always that.

What You Learned

  • Singe has two ways to write a script, and you choose by defining singeMain or not.

  • In the threaded model your game is a list of steps and runs from top to bottom.

  • singeYield() gives one frame back to the engine and carries on from the next line.

  • Waiting is a while loop with a singeYield in it. You write the waiting function you need; the engine does not provide one.

  • Nothing draws unless you draw it, before a yield, on every frame.

  • dofile("Singe/Framework.singe") goes at the end of a threaded script.

  • Do not write your own onOverlayUpdate when singeMain exists.

  • Every other callback still fires, so events and steps mix freely.

  • Returning from singeMain ends the game.

  • Sequences want the threaded model; situations want the event driven one.

Next Time

You can now write "play this, then ask, then play that" as three lines. A branching video game is nothing but that sentence, a few hundred times, with the answers deciding which line comes next. Lesson sixteen builds one, and the interesting part turns out not to be the video at all. It is keeping the map of what leads where in a form you can still read when the game has forty scenes in it.

Lesson 16: Branching

The finished lesson

A branching video game is a film with forks in it. A scene plays, the player chooses, and a different scene plays next. Do that twenty or thirty times and you have a game people will replay for years trying to find the ending they have not seen.

In this lesson you will build one. It has four scenes, two choices, a timer on each choice, a death, and three lives. The code that plays it is about thirty lines, and it would still be about thirty lines if the game had two hundred scenes — because the game itself will not be written in code at all.

Imagine It Is a Dragon

The video everybody has is Singe/menuBackground.mkv, the same 420 frames you have been driving since lesson fourteen. It is a ball of fire, a dragon made of paper, the word SINGE, and then a magenta grid rolling away under an orange sun forever.

It is not a drama. There is nobody in it to be in peril, and the sunset does not care what you decide.

Play along anyway. The dragon is real enough for two minutes, and everything you are about to write works exactly the same when the footage is a stunt performer falling off a cliff. Here is the map, and the frame numbers are the ones you found for yourself in lesson fourteen:

Scene Frames What happens

arrive

0 to 119

Fire, and the dragon lands. Left or Right?

sunset

120 to 259

It breathes fire. Duck Left or run Right?

pit

260 to 339

You are eaten. You lose a life.

escape

340 to 410

The grid rolls away and you got out.

Left is always right, so to speak: left from arrive goes to sunset, left from sunset gets you to escape. Right goes to the pit both times, and so does taking too long.

The Map Is Data, Not Code

Here is the whole game, and it is a table.

local scenes = {
    arrive = {
        first  = 0,
        last   = 119,
        ask    = 30,
        prompt = "The dragon lands.  Left or Right?",
        left   = "sunset",
        right  = "pit",
        goesTo = "pit"
    },
    sunset = {
        first  = 120,
        last   = 259,
        ask    = 170,
        prompt = "It breathes fire.  Duck Left or run Right?",
        left   = "escape",
        right  = "pit",
        goesTo = "pit"
    },
    pit = {
        first  = 260,
        last   = 339,
        death  = true,
        goesTo = "arrive"
    },
    escape = {
        first  = 340,
        last   = 410
    }
}

A table with names down the left instead of numbers, exactly as in lesson six, and every value in it is another table. Each of those inner tables is a record: one scene, described field by field.

scenes.arrive is the first scene. scenes.arrive.first is 0. scenes.arrive.left is the string "sunset", which is the name of another scene in the same table — which is how the forks are written down. A scene does not contain the scene after it. It contains the name of the scene after it, and the name is looked up when the time comes.

The fields mean this:

first and last

The frames the scene runs between.

ask

The frame the question appears on. The player has from ask to last to answer, which is the timer.

prompt

What the question says.

left and right

The scene each answer leads to.

goesTo

Where the scene goes when nobody chose — because the player ran out of time, or because there was no question in the first place. For pit, which is a death, it is where the retry goes back to.

death

Present, and true, only on a scene that costs a life.

Three things are worth noticing about that table.

The first is that it is the design document. You can hand it to somebody who has never written a line of Lua and they can read the game out of it. When you want the dragon to fork three ways, you add a field. When you want another scene, you add another record. You do not go looking for the code that plays scenes, because you do not change it.

The second is that the records are not all the same shape. pit has no ask, no prompt, and no left — there is nothing to choose in it. escape has no goesTo, because it is the end and goes nowhere. A field that is not in a table reads as nil, which is the word you met in lesson three for "nothing is there", and asking for scenes.escape.goesTo is not an error. It is nil, and nil is an answer. Code that reads these records has to be ready for that, and in a minute you will see the one line that is.

The third is what the table does not contain: nothing in it draws, plays, or waits. It is a description. That separation is the entire trick of this lesson.

One Function That Plays Any Scene

This is the code half, and there is only one function of any size. Written in the threaded model from lesson fifteen, because a branching game is the most sequential thing there is.

local function playScene(name)
    local scene = scenes[name]

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do
        local frame  = discGetFrame()
        local asking = scene.ask ~= nil and frame >= scene.ask

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end
        drawScene(scene, frame, asking)
        singeYield()
    end
    discPause()

    if scene.death then
        lives = lives - 1
        if lives == 0 then
            ending = "The dragon wins.  Game over."
            return nil
        end
        waitForGo("Press the space bar to try again.")
    end

    return scene.goesTo
end

It takes the name of a scene, plays it, and returns the name of the scene that comes next. That is its whole contract, and the game is then three lines:

function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end

Start at arrive. Play whatever scene you are holding, and hold whatever it hands back. When it hands back nil there is no next scene, the loop ends, and the game is over.

The Whole Thing

Make dragon.singe in your movie folder and type this in. It is the longest script in the book so far, and every piece of it has been explained except the two small helpers, which come after.

local FPS = 30

local scenes = {
    arrive = {
        first  = 0,
        last   = 119,
        ask    = 30,
        prompt = "The dragon lands.  Left or Right?",
        left   = "sunset",
        right  = "pit",
        goesTo = "pit"
    },
    sunset = {
        first  = 120,
        last   = 259,
        ask    = 170,
        prompt = "It breathes fire.  Duck Left or run Right?",
        left   = "escape",
        right  = "pit",
        goesTo = "pit"
    },
    pit = {
        first  = 260,
        last   = 339,
        death  = true,
        goesTo = "arrive"
    },
    escape = {
        first  = 340,
        last   = 410
    }
}

local answer = nil
local ending = "You got out alive."
local lives  = 3


local function drawScene(scene, frame, asking)
    overlayClear()
    overlayPrint(2, 2, "Lives: " .. lives)
    if scene.death then
        overlayPrint(2, 4, "That did not go well.")
    elseif asking then
        overlayPrint(2, 4, scene.prompt)
        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")
    end
end


local function waitForGo(text)
    answer = nil
    while answer ~= "go" do
        overlayClear()
        overlayPrint(2, 2, "Lives: " .. lives)
        overlayPrint(2, 4, text)
        singeYield()
    end
end


local function playScene(name)
    local scene = scenes[name]

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do
        local frame  = discGetFrame()
        local asking = scene.ask ~= nil and frame >= scene.ask

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end
        drawScene(scene, frame, asking)
        singeYield()
    end
    discPause()

    if scene.death then
        lives = lives - 1
        if lives == 0 then
            ending = "The dragon wins.  Game over."
            return nil
        end
        waitForGo("Press the space bar to try again.")
    end

    return scene.goesTo
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        answer = "left"
    elseif what == SWITCH_RIGHT then
        answer = "right"
    elseif what == SWITCH_BUTTON1 then
        answer = "go"
    end
end


function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end


dofile("Singe/Framework.singe")

Run it:

Singe -R -v Singe/menuBackground.mkv movie/dragon.singe

Play it four or five times. Go left twice and get out. Go right and get eaten. Sit on your hands and get eaten anyway. Lose all three lives.

What Just Happened

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do

A scene is a jump followed by a wait, which is the pattern from lesson fifteen with the numbers coming out of the record instead of being typed in. discSkipToFrame goes to a frame and plays from it, which is what a scene change is.

The frame number is right the instant the call returns, so the while never thinks it is still in the scene you just left.

        local asking = scene.ask ~= nil and frame >= scene.ask

The one line that is ready for a missing field, and the reason the death scene can leave ask out.

and means both halves have to be true, as it did in lesson three, and Lua checks the left half first. If scene.ask is nil the left half is false, Lua stops there, and the comparison on the right never happens. Which is just as well, because comparing nil to a number is an error and you will meet it at the end of this lesson.

asking is the answer to "is the question on screen right now?", worked out once a frame and used three times.

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end

While the question is not up, anything the player presses is thrown away. It has to be, or a player leaning on the left arrow during the film answers a question they have not read.

Once the question is up, an answer ends the scene at once. return scene[answer] is worth a second look: answer holds the string "left" or "right", and scene["left"] is the same thing as scene.left. Putting the name in brackets instead of after a dot lets you look up a field whose name you are holding in a variable. Two lines of code for both answers, and for five answers it would still be two lines.

The elseif also explains why only "left" and "right" are allowed through. The space bar sets answer to "go", and scene["go"] is nil, so a stray space bar during a question would end the game in silence. Say what you accept.

    discPause()

Right after the loop, and easy to forget. The scene has reached its last frame but the disc has no idea the scene is over — it plays straight on into whatever footage happens to sit next in the file, which in a real game is the middle of a scene from somewhere else entirely. Stop it the moment you stop wanting it.

    if scene.death then
        lives = lives - 1

scene.death is nil for every scene except pit, and nil counts as false in an if, so this reads as "if this scene was a death". You do not have to write death = false in the other three records, and you should not: the absence of the field says it just as well, and there is then only one place that decides which scenes are deadly.

The retry is the two lines under it. Take a life, and if there are any left, hold on the frame and wait for the space bar. Then return scene.goesTo sends the player back to arrive, and the record is what knows that. Change goesTo to "sunset" and the retry becomes a checkpoint instead of a restart — one word, and the game’s difficulty changes.

        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")

The timer. scene.last - frame is how many frames are left, and dividing by the frames in a second turns that into seconds. math.ceil rounds a number up to the next whole one, so the countdown reads 3, 2, 1 and never 0.4 or 2.966666.

FPS is 30 because this video runs at a little over thirty frames a second. It is the one number in the script that is a guess, and it is a named guess at the top of the file rather than a 30 buried in the middle of a line, so that when you change videos there is exactly one thing to change.

Notice what the timer is measured against: the film. The player is racing the video, not a clock, so the question can never outstay the shot it belongs to. That is the reason branching games count in frames.

Why Not Write It Out by Hand

You could write this game as one long function. Play frames 0 to 119; if left, play 120 to 259; if left again, play 340 to 410; else play 260 to 339, take a life, go back to the top. For four scenes it would be shorter than what you have.

For forty scenes it would be a disaster, and it is worth being precise about why.

The frame numbers would be scattered through the code, each written once and never named, so changing where a scene starts means finding every place it is mentioned. The shape of the story would be buried in the shape of the if statements, so nobody could see the game without reading all of it. And adding a scene would mean editing the playing code, which is the code that already works — every new scene another chance to break an old one.

The version you wrote has one piece of code that plays scenes and one piece of data that says what the scenes are. Adding a scene touches only the data. That is worth the extra half hour it took, and it is the same idea underneath the games.dat file from lesson thirteen: describe the thing, then write one piece of code that reads the description.

Try It

  1. Add an ending. Give escape a question and a second ending scene that reuses frames from somewhere in the film. Only the table changes.

  2. Make it fair. Lower ask in both scenes so the player has five seconds instead of three, then raise it so they have one. Find the number you would actually ship.

  3. Move the checkpoint. Change the goesTo of pit to "sunset" and play it. Then think about what happens if a player dies in arrive — and whether the death scene should know where it came from rather than being told.

  4. Count what the player has seen. Add a table beside scenes that records which scene names have been played, and show the count in the corner. Now you have a game that can say "you have found three of the five endings".

  5. Break the map. Change the left of arrive to "cave", a scene that does not exist. Run it, go left, and read what Lua says. That error is the most common one a data-driven game has, and knowing its shape saves an hour.

Break It on Purpose

Take the guard off the asking line, so it reads:

        local asking = frame >= scene.ask

Run it and go right. The arrive scene plays fine, because arrive has an ask. Then the pit scene starts, which does not, and the game stops with this:

Error executing function 'onOverlayUpdate':  movie/dragon.singe:68: attempt to compare nil with number
stack traceback:
	[C]: in function 'error'
	Singe/Framework.singe:603: in function 'onOverlayUpdate'

Read it the way lesson one taught. The file and the line come first, and they are exactly right: line 68 is the line you just changed. The complaint is the rest: you asked Lua whether a number was greater than nil, and Lua has no idea. scene.ask is nil because the pit record has no ask field, and a field that is not there is nil.

One part of that message deserves an explanation, because it is a lie of omission. The function named is onOverlayUpdate, which you did not write. That is the framework’s own, the one lesson fifteen said was installed to drive your singeMain. The error came out through it, so that is the name the engine had to hand, and the traceback under it — the list of functions that were running, innermost first — can only show the framework passing your error on. Ignore both. The file and the line at the top are yours, and they are the ones that are true.

What You Learned

  • A branching game is a set of scenes, each of which names the scenes that come after it.

  • Keep the scenes as data — a table of records — and the code that plays them stays one function however big the game gets.

  • A record holds the name of the next scene, not the scene, and the name is looked up when it is needed.

  • A field that is not in a record is nil, which is not an error, and code that reads records must expect it.

  • scene[answer] looks up the field whose name is in a variable; scene.left and scene["left"] are the same field.

  • Put the timer on the video: a choice lasts from one frame to another, so it can never outlast its own shot.

  • Throw away anything the player pressed before the question appeared.

  • Pause the disc the moment a scene ends, or it plays on into the next scene’s footage.

  • A missing field standing for false — death on three records out of four — keeps the description short and honest.

  • Comparing nil with a number is an error, and and is how you avoid it.

Next Time

Your game asks left or right. The arcade machines this kind of game grew up in asked something harder: point at the thing on screen and shoot it. Lesson seventeen is about light guns — where the player is aiming, what the game does with that, and the calibration a real cabinet cannot do without.

Lesson 17: Light Guns

The finished lesson

You are going to make a shooting gallery. Targets appear over the video at frames you choose, you aim at the screen and pull a trigger, and the ones you hit score.

You do not need a light gun to write this. You need a mouse, because to Singe a light gun is a mouse: it reports a position in the same coordinates, through the same calls, and its trigger arrives as the same switch as a mouse button. Write the game for the mouse on your desk and it works on a cabinet with a gun bolted to it, which is the only sane way round to do it. A gun is not a different kind of input. It is a mouse that somebody aimed.

What You Are Pointing At

Start the same way as lesson fourteen, with the video the engine unpacked for you:

Singe -R -v Singe/menuBackground.mkv gallery

That footage is a purple grid and a sunset. It is not a bank robbery. Every frame number in this lesson refers to it so that the code runs the day you type it, and the whole clip is 720 by 480 and about 420 frames long, which at roughly thirty frames a second is fourteen seconds. Imagine better footage. The code does not care what is in the picture.

Match the Overlay to the Video

Put this at the top of gallery.singe, under the dofile line:

overlaySetResolution(discGetWidth(), discGetHeight())

Without that call the overlay is half the video in each direction — 360 by 240 here — and every coordinate you draw with, and every mouse position you are handed, is in that smaller space. Nothing is wrong with the small overlay, but it is one more conversion to keep in your head while you are working out where a shot landed. Matching the video means a target at x = 80 is eighty pixels across the picture, and so is a shot at x = 80. The reference’s entry for overlaySetResolution explains what it costs.

Where the Gun Is Pointing

One call answers that:

local x, y = mouseGetPosition(0)

mouseGetPosition hands back two numbers, which is something you have not seen a function do before and which Lua is perfectly happy about: a function may return as many values as it likes, and you catch them by listing that many names on the left of the =. The 0 is which pointing device you are asking about, counting from zero. With one mouse, or one gun, the answer is always device 0.

The numbers are in overlay coordinates, not desktop pixels, which is why the call above was worth making. The position is the last one the device reported, so you can ask for it whenever you like, as often as you like. Ask for it in onOverlayUpdate and draw with the answer.

There is another way to get the same numbers. onMouseMoved is a callback, like onOverlayUpdate, and the engine calls it every time a pointer moves, handing it the new position. It is the right choice when you want to react to movement. For drawing a crosshair you do not: you want to know where the thing is right now, and mouseGetPosition tells you that without your having to keep a copy.

Drawing a Crosshair

The engine will not draw one for you. A crosshair is four lines and a circle:

local function drawCrosshair(x, y)
    colorForeground(255, 255, 255, 255)
    overlayCircle(x, y, 10)
    overlayLine(x - 18, y, x - 4, y)
    overlayLine(x + 4, y, x + 18, y)
    overlayLine(x, y - 18, x, y - 4)
    overlayLine(x, y + 4, x, y + 18)
end

The gaps matter more than the lines. Leaving the four spokes short of the circle gives you a hole in the middle to see the target through, which is the whole point of a crosshair and the first thing beginners draw over.

One thing you should ask before drawing it:

local drawAim = singeWantsCrosshairs()

That returns false when the player started Singe with --nocrosshair. Some light guns put a spot of their own on the screen, and two crosshairs a few pixels apart are worse than none. The answer cannot change while the game runs, so read it once at the top and keep it in a variable.

You do not have to hide the system pointer, because Singe already has. It grabs the mouse at startup, which confines it to the window and hides the desktop arrow. If you ever want it back — for a level editor, say — mouseSetCaptured(false) releases it, and the key mapped to INPUT_GRAB, which is G in the shipped controls, toggles the same thing while you play.

The Trigger

A trigger is a button, and buttons arrive at onInputPressed, which you first met in lesson three:

function onInputPressed(what, device)
    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    -- ...
end

SWITCH_BUTTON3 is the left mouse button, and on a gun it is the trigger. The shipped controls.cfg maps the left button to SWITCH_BUTTON3, the right to SWITCH_BUTTON1, and the middle to SWITCH_BUTTON2. Those numbers look shuffled because they are: the switches are the arcade panel’s buttons, and which physical control is wired to which is a cabinet’s business, not the game’s. Left Shift is mapped to SWITCH_BUTTON3 too, so you can fire without a mouse while you are testing.

The second argument is the new part. When the switch came from a mouse or a light gun, device is that device’s index — 0 for the first, 1 for the second, and so on. When it came from a key or a gamepad it is nil, because no pointing device was involved. That is why the call above says device or 0: if device is nil, use 0 instead. You will use or like that constantly, and it reads exactly as it sounds — "device, or nothing, in which case zero".

That one extra argument is what makes a two gun cabinet possible. Player one’s gun is device 0 and player two’s is device 1, and the same onInputPressed tells them apart without your guessing.

Did It Hit Anything

You already know how to answer this. It is lesson eleven:

if collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then

A shot is a point. A target is a rectangle. collidePointRect asks whether the point is inside the rectangle, and the edge counts as inside. There is nothing special about shooting. A gun game’s hit test is the same hit test a platform game uses to find out whether you landed on a block, and the reference’s collide family has the rest of the shapes.

Targets That Come and Go

The only thing video changes is when a target exists. In lesson eleven a rock was there until you shot it. Here a target is on screen while the film is showing the part of the scene it belongs to, and then it is gone whether you shot it or not.

That is two more fields on the record, and lesson six built you the tool:

local targets = {
    { first =  40, last = 110, x =  80, y = 110 },
    { first = 120, last = 190, x = 470, y = 140 },
    { first = 200, last = 270, x = 290, y = 250 },
    { first = 280, last = 360, x = 150, y = 300 },
}

Four records, each with the frame the target appears on, the frame it leaves on, and where it sits. Adding a fifth target is adding a line. That is the shape to reach for every time you find yourself about to write the same four lines of code with different numbers in them.

Whether a target counts is then a small function of its own:

local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end

The drawing asks it, and so does the shooting, which is the point of putting it in one place: a target you can see and a target you can hit can never disagree.

The Whole Thing

-- Learn to Program with Singe -- Lesson 17: Light Guns

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local FIRST_FRAME = 20
local LAST_FRAME  = 400
local TARGET_SIZE = 96
local HIT_SCORE   = 100
local FLASH_TIME  = 12

local targets = {
    { first =  40, last = 110, x =  80, y = 110 },
    { first = 120, last = 190, x = 470, y = 140 },
    { first = 200, last = 270, x = 290, y = 250 },
    { first = 280, last = 360, x = 150, y = 300 },
}

local aimX    = overlayGetWidth() / 2
local aimY    = overlayGetHeight() / 2
local score   = 0
local shots   = 0
local hits    = 0
local flash   = 0
local flashX  = 0
local flashY  = 0
local drawAim = singeWantsCrosshairs()


local function drawCrosshair(x, y)
    colorForeground(255, 255, 255, 255)
    overlayCircle(x, y, 10)
    overlayLine(x - 18, y, x - 4, y)
    overlayLine(x + 4, y, x + 18, y)
    overlayLine(x, y - 18, x, y - 4)
    overlayLine(x, y + 4, x, y + 18)
end


local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end


local function startRound()
    score = 0
    shots = 0
    hits  = 0
    flash = 0
    for _, target in ipairs(targets) do
        target.hit = false
    end
    discSkipToFrame(FIRST_FRAME)
end


function onInputPressed(what, device)
    if what == SWITCH_START1 then
        startRound()
        return
    end

    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    local frame = discGetFrame()

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then
            target.hit = true
            hits       = hits + 1
            score      = score + HIT_SCORE
            flash      = FLASH_TIME
            flashX     = x
            flashY     = y
            return
        end
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    if frame >= LAST_FRAME then
        startRound()
        frame = FIRST_FRAME
    end

    aimX, aimY = mouseGetPosition(0)

    overlayClear()

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) then
            colorForeground(255, 200, 0, 255)
            overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)
            overlayCircle(target.x + TARGET_SIZE / 2, target.y + TARGET_SIZE / 2, TARGET_SIZE / 3)
        end
    end

    if flash > 0 then
        colorForeground(255, 255, 255, 255)
        overlayCircle(flashX, flashY, 30 - flash * 2)
        flash = flash - 1
    end

    overlayPrint(2, 1, "SCORE " .. score .. "   HITS " .. hits .. "/" .. shots .. "   FRAME " .. frame)

    if drawAim then
        drawCrosshair(aimX, aimY)
    end

    return OVERLAY_UPDATED
end


startRound()

Aim at a yellow box and click. The counter in the corner goes up, a white ring opens where you hit, and the box disappears. Miss and the shot count goes up on its own, which is the cheapest scoreboard there is and tells a player more about how they are doing than the score does. The round restarts by itself when the film runs out, and 1 restarts it whenever you like.

What Just Happened

local frame = discGetFrame()

if frame >= LAST_FRAME then
    startRound()
    frame = FIRST_FRAME
end

The video is the clock, as it was in lesson fourteen, and discGetFrame is how you read it. Everything else in the frame is decided from that one number. When the film runs off the end of the last target, the round starts over: startRound clears the score, marks every target unshot, and sends the disc back to the beginning with discSkipToFrame. The line under it sets the local copy of frame as well, because it was read before the jump and still holds the old number. Without it the drawing below would spend one frame working from a number that is no longer true.

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(...) then

Count the shot before you look for a hit, so that a miss counts too. Then walk the list. return inside the loop stops at the first target hit, which means one bullet cannot take two overlapping targets — a rule you have to decide one way or the other, and this is the line that decides it.

overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)

overlayBox wants two opposite corners, not a corner and a size, so the far corner is the near one plus the size. The - 1 is because both corners are included: a box from 80 to 175 is ninety six pixels wide. collidePointRect wants a corner and a size instead, which is why TARGET_SIZE goes in on its own there and added to the corner here. Mixing those two up is a genuinely common bug, and it shows as targets you can hit slightly outside where they are drawn.

if flash > 0 then
    colorForeground(255, 255, 255, 255)
    overlayCircle(flashX, flashY, 30 - flash * 2)
    flash = flash - 1
end

flash is a countdown in frames, set to twelve when a shot lands and reduced by one every time the screen is drawn. Because the radius is worked out from the countdown, the ring grows as the number shrinks. Twelve frames is under half a second. Feedback that lasts longer than that stops feeling like a consequence of the trigger and starts feeling like weather.

Two Guns

You are two changes away from a two player cabinet, and neither is in the game loop.

The first is mouseSetMode(MOUSE_MANY), which tells Singe to read each device separately instead of pooling them into one cursor. mouseHowMany() says how many it found at startup, so a game normally asks before it commits:

if mouseHowMany() >= 2 then
    mouseSetMode(MOUSE_MANY)
end

After that, mouseGetPosition(1) is the second gun, and the device argument of onInputPressed says which gun fired. Keep two crosshairs, two scores, and one list of targets, and you have a co-operative game.

The second change is not in your script at all. The shipped controls.cfg binds only the first mouse’s buttons, so the second gun’s trigger reaches nothing. A cabinet with two guns needs its own line in that file naming both:

INPUT_ACTION_3 = { SCANCODE.LSHIFT, GAMEPAD_0.BUTTON_X, MOUSE_0.BUTTON_LEFT, MOUSE_1.BUTTON_LEFT }

Say so in your instructions. A player whose second gun does nothing will blame your game, and they will be half right.

The Other Way to Test a Hit

There is a second way to answer "did that shot hit something", and it is worth knowing about even though you are not going to use it today. vldpGetPixel(x, y) reads the color of one pixel of the video frame currently on screen. Games have used it since the very first version of Singe: paint every target in the footage a color that appears nowhere else, and on a trigger pull ask what color is under the crosshair.

It buys you hit shapes that follow the action exactly, for free, with no rectangles to author. It costs you footage you have to prepare that way, and a hit test you cannot see or debug. The reference’s entry for vldpGetPixel has the details. Rectangles are the right default; keep this in your pocket.

What Only a Cabinet Cares About

Everything above works on your desk. Several things do not exist on your desk at all, and this is a good moment to name them so that they are not a surprise later.

Calibration. A real light gun has to be told where the screen is, because it is a camera looking at a monitor from wherever the player is standing. Singe’s service tools have a Light Gun screen that puts targets in the middle and at each corner and marks where the gun actually pointed, so you can see which way it is out. Your game does not do the calibrating and should not try.

The Sinden border. One popular family of guns finds the screen by looking for a bright frame drawn around the picture. --sindengun draws that frame, and the engine maps positions back into the smaller picture inside it, so your game keeps getting coordinates that mean what they used to mean.

Screens that are not the shape of the film. ratioGetX() and ratioGetY() hand you the numbers a player gave on the command line for a display whose proportions do not match the footage. Singe does not apply them; a game that wants them does the arithmetic itself.

Guns going away. SWITCH_MOUSE_DISCONNECT arrives at onInputPressed when a gun is unplugged. No button produces it; the engine raises it. A game that watches for it can put "PLAYER 2 GUN DISCONNECTED" on screen instead of appearing to have died.

No mouse at all. A cabinet with a joystick and no pointing device can drive the cursor from the stick, which joyMouseEnable turns on.

None of that changes the game you wrote. All of it is lesson thirty-one.

Try It

  1. Move a target. Change the third target’s x to 680 and run it. Most of it now hangs off the right edge, because the overlay is 720 wide and the target is 96. You can still shoot the sliver that is left. Decide what you want to happen at the edges.

  2. Make the targets easier. Change TARGET_SIZE to 140. Notice that the drawing and the hit test both change, and that you only edited one number. That is what a named constant is for.

  3. Keep score for accuracy. Add a line that prints hits as a percentage of shots. Guard against dividing by zero before the first shot, and find out what Lua prints if you do not.

  4. Make a target punish you. Add a penalty = true field to one record and subtract points when it is hit. Notice you are adding a field to one record, not to all four, and that the ones without it have nil there.

  5. Take the return out of the loop in onInputPressed, then overlap two targets by giving them the same frames and nearly the same position. One shot now takes both. Decide which behavior your game wants.

Break It on Purpose

Change the fire test to use SWITCH_BUTTON1 instead of SWITCH_BUTTON3 and run it. Nothing breaks. No error appears. The left button stops doing anything, and the right button now fires.

This is the worst kind of bug and the most common one in input code: the program is not wrong, it is just wired to the wrong thing. There is no error message to read, because you asked a sensible question about a switch that exists and it answered honestly.

Two things find it. The first is debugPrint, from lesson eight:

function onInputPressed(what, device)
    debugPrint("switch " .. what .. " from device " .. tostring(device))

Now every press prints a line, and you can see what the trigger actually sends. Note tostring(device): device is nil for a key press, and joining nil onto a string with .. is an error. tostring turns it into the word nil and the line prints.

The second is the engine’s own Input Test, in the service tools, which shows every device it can see and the last switch the game would have received. When a button does nothing, that screen tells you which half of the problem you have: either the switch is arriving and your game is ignoring it, or it is not arriving at all.

What You Learned

  • A light gun reports as a mouse, so a game written for the mouse works with a gun.

  • mouseGetPosition(device) returns two values, the pointer’s position in overlay coordinates.

  • A function in Lua can return more than one value, and you catch them by listing that many names.

  • singeWantsCrosshairs() says whether to draw your own reticle. Read it once.

  • Singe grabs and hides the system pointer at startup; you do not have to.

  • onInputPressed takes a second argument naming which mouse or gun fired, and nil when it was a key or a pad.

  • A hit test against a rectangle is collidePointRect, the same collision you learned in lesson eleven.

  • A target’s frame window is just two more fields on its record.

  • a or b gives you b when a is nil.

  • Calibration, the Sinden border, and two gun wiring live outside your script.

Next Time

Your gallery asks for one thing: hit that, there. The other arcade convention video games are built on asks for something harder — press this, now, and you have half a second. Lesson eighteen builds a quick-time event, with a prompt, a window measured in frames, and three different endings depending on whether you were right, wrong, or too slow.

Lesson 18: Quick-Time Events

The finished lesson

A prompt appears. You have half a second. Press the right thing and the story goes on; press the wrong thing, or nothing at all, and it goes somewhere else.

That is the whole idea, and a surprising number of video games are made of almost nothing else. You already have every piece: lesson fourteen gave you frames, lesson six gave you a list of records, lesson three gave you input, and lesson sixteen gave you branching. This lesson puts them together and adds one thing that is genuinely new — a window of time, and what happens when it closes.

The Clock Is the Film

Everything here is measured in frames, not in seconds, and that is worth stopping on because it is the single decision that makes this work.

Lesson fourteen said a frame is the address of a moment in the film. The prompt has to appear when the actor starts to swing, and the window has to close when the fist arrives. Those are not times, they are places in the footage, and you found them by stepping through it. If you write the window in seconds you have to start a stopwatch when the prompt appears, and then the two clocks — yours and the film’s — can drift apart. If the video stutters on a slow machine, your stopwatch keeps running and the player is punished for their hardware.

Frames cannot drift, because there is only one clock. discGetFrame() is the time, always. A window is two frame numbers, and "how long is left" is subtraction.

Run with the same video as before:

Singe -R -v Singe/menuBackground.mkv moves

Still the purple grid and the sunset. Picture a fight.

A Move Is a Record

Here is the table the whole lesson hangs on:

local moves = {
    { first =  60, last = 105, switch = SWITCH_LEFT,  name = "LEFT"  },
    { first = 140, last = 185, switch = SWITCH_UP,    name = "UP"    },
    { first = 220, last = 265, switch = SWITCH_RIGHT, name = "RIGHT" },
    { first = 300, last = 345, switch = SWITCH_DOWN,  name = "DOWN"  },
}

Four moves. Each one says when the window opens, when it closes, which switch answers it, and what to put on screen. Forty five frames is about a second and a half at this video’s rate, which is generous; real games often give you less than half that.

Everything that makes a move a move is in that table. There is no code anywhere below that knows there are four moves, or that the second one is up, or that the first window opens at frame sixty. Adding a fifth move is adding a line. Retiming every move is editing numbers. Nobody has to read a function to change the fight.

That is not a trick for this lesson. It is the difference between a game you can tune and a game you cannot, and it costs nothing to do from the start. When you find yourself about to write if frame == 60 then a fourth time, stop and make a table instead.

What Happens When

Three things can happen to a move, and they are three different outcomes, not two:

  • The player presses the right switch inside the window. Score it and play on.

  • The player presses a wrong switch inside the window. They tried and failed.

  • The window closes with no answer at all. They froze.

Lazy code treats the last two the same. Games almost never do, because they feel completely different to play: guessing wrong is a mistake, and freezing is a different mistake, and the film usually goes somewhere different for each. Here the wrong answer sends the disc to frame 362 and no answer sends it to frame 388, which on this footage means two slightly different amounts of sunset. On real footage they would be two different shots of you losing.

So each record grows a fifth field while the run is going — answer — which is nil until something happens to the move, and then one of three strings:

move.answer = "right"
move.answer = "wrong"
move.answer = "late"

nil is the value Lua gives you for a field nobody has set. You met it in lesson three. Here it earns its keep: "no answer yet" is genuinely a different state from any of the three answers, and nil says so without your inventing a word for it.

Finding the Move That Is Being Asked

Everything else needs to know one thing: which move, if any, is open right now?

local function moveAt(frame)
    for _, move in ipairs(moves) do
        if move.answer == nil and frame >= move.first and frame <= move.last then
            return move
        end
    end
    return nil
end

Walk the list, and answer with the first move whose window covers this frame and which has not been answered. If nothing matches, answer nil.

Returning nil on purpose is worth noticing. A function that sometimes has no answer should say so, and "no move is open" is a perfectly good answer. The caller then writes if move ~= nil then, and the code that draws the prompt never runs when there is nothing to prompt for.

The move.answer == nil test is what stops a move being asked twice. The moment the player gets it right, the prompt vanishes even though the window is still open — which is exactly what it should do, because they have answered.

Reading the Answer

function onInputPressed(what)
    if not isDirection(what) then
        return
    end

    local move = moveAt(discGetFrame())
    if move == nil then
        return
    end

    if what == move.switch then
        move.answer = "right"
        score       = score + RIGHT_SCORE
    else
        move.answer = "wrong"
        endRun("WRONG WAY", WRONG_FRAME)
    end
end

Read it top to bottom. If the switch is not one of the four directions, it is none of our business — leave. If no move is open, a direction press means nothing — leave. Otherwise there is exactly one move to compare against, and one comparison to make.

Both of those early return lines are guards: they throw out the cases you do not care about so that the code underneath only ever runs in the one situation it was written for. Writing it the other way round, with the real work nested three levels deep inside three if blocks, says the same thing and is much harder to read.

isDirection is a tiny function that does nothing but keep that first line short:

local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end

Notice that it returns the comparison itself rather than saying if …​ then return true else return false end. A comparison is already true or false. Testing whether something is true so that you can say it is true is a habit worth losing early.

The Window Closing

Nobody presses anything, and the frames keep going by. Something has to notice. That something is onOverlayUpdate, because it runs every frame whether or not the player does anything:

if not runOver then
    for _, move in ipairs(moves) do
        if move.answer == nil and frame > move.last then
            move.answer = "late"
            endRun("TOO SLOW", LATE_FRAME)
            break
        end
    end
end

A move that is unanswered and whose last frame has gone past was missed. break leaves the loop immediately, because once the run is over there is no point looking at the rest.

endRun is the branch, and it is the same branch you wrote in lesson sixteen:

local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end

Three lines. Remember what to say, remember that the run is finished, and send the film somewhere else. A missed quick-time event is not a special mechanism. It is a choice the player made by not making one, and the film branches on it exactly as it branches on a door they picked.

A Gauge That Drains

The player cannot see frame numbers. They need to see time running out, and they need to see it without looking away from the action, which means a shape that changes rather than a number that counts.

Two numbers give you everything:

local left = move.last - frame
local span = move.last - move.first

span is how long the window is. left is how much of it remains. The bar is left out of span of the full width:

fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)

// is division that throws away the fraction, which you want here because a bar a hundred and thirty-three and a third pixels wide is not a thing. Multiply before you divide — GAUGE_W * left // span and not GAUGE_W * (left // span) — or the fraction is thrown away while it is still the only information you have, and the bar jumps between full and empty with nothing in between.

There is no filled rectangle in the overlay. overlayBox draws an outline, which is what you want for the frame around the gauge, and the fill is your own:

local function fillBar(x, y, width, height)
    if width < 1 then
        return
    end
    for row = 0, height - 1 do
        overlayLine(x, y + row, x + width - 1, y + row)
    end
end

Eighteen horizontal lines stacked on top of each other. The guard at the top matters: at the very last frame of the window left is zero, the width is zero, and without it x + width - 1 is one pixel to the left of x and you draw a short backwards line instead of nothing.

The last touch is a color change when it gets desperate:

if left * 3 < span then
    colorForeground(255, 60, 60, 255)
else
    colorForeground(255, 200, 0, 255)
end

The bar turns red in its last third. Written that way — multiplying the time left rather than dividing the span — it stays whole numbers and works for a window of any length.

The Whole Thing

-- Learn to Program with Singe -- Lesson 18: Quick-Time Events

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local FIRST_FRAME = 20
local WRONG_FRAME = 362
local LATE_FRAME  = 388
local LAST_FRAME  = 415

local PROMPT_COL  = 54
local PROMPT_ROW  = 22
local GAUGE_X     = 210
local GAUGE_Y     = 330
local GAUGE_W     = 300
local GAUGE_H     = 18

local RIGHT_SCORE = 100

local moves = {
    { first =  60, last = 105, switch = SWITCH_LEFT,  name = "LEFT"  },
    { first = 140, last = 185, switch = SWITCH_UP,    name = "UP"    },
    { first = 220, last = 265, switch = SWITCH_RIGHT, name = "RIGHT" },
    { first = 300, last = 345, switch = SWITCH_DOWN,  name = "DOWN"  },
}

local score   = 0
local runOver = false
local verdict = ""


local function fillBar(x, y, width, height)
    if width < 1 then
        return
    end
    for row = 0, height - 1 do
        overlayLine(x, y + row, x + width - 1, y + row)
    end
end


local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end


local function moveAt(frame)
    for _, move in ipairs(moves) do
        if move.answer == nil and frame >= move.first and frame <= move.last then
            return move
        end
    end
    return nil
end


local function startRun()
    score   = 0
    runOver = false
    verdict = ""
    for _, move in ipairs(moves) do
        move.answer = nil
    end
    discSkipToFrame(FIRST_FRAME)
end


local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end


function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

    if not isDirection(what) then
        return
    end

    local move = moveAt(discGetFrame())
    if move == nil then
        return
    end

    if what == move.switch then
        move.answer = "right"
        score       = score + RIGHT_SCORE
    else
        move.answer = "wrong"
        endRun("WRONG WAY", WRONG_FRAME)
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    if not runOver then
        for _, move in ipairs(moves) do
            if move.answer == nil and frame > move.last then
                move.answer = "late"
                endRun("TOO SLOW", LATE_FRAME)
                break
            end
        end
    end

    if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then
        if not runOver then
            verdict = "CLEAR"
            runOver = true
        end
        discSearch(LAST_FRAME)
    end

    overlayClear()

    local move = nil
    if not runOver then
        move = moveAt(frame)
    end

    if move ~= nil then
        local left = move.last - frame
        local span = move.last - move.first

        overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

        colorForeground(255, 255, 255, 255)
        overlayBox(GAUGE_X - 2, GAUGE_Y - 2, GAUGE_X + GAUGE_W + 1, GAUGE_Y + GAUGE_H + 1)

        if left * 3 < span then
            colorForeground(255, 60, 60, 255)
        else
            colorForeground(255, 200, 0, 255)
        end
        fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)
    end

    overlayPrint(2, 1, "SCORE " .. score .. "   FRAME " .. frame)

    if runOver then
        overlayPrint(2, 3, verdict)
        overlayPrint(2, 4, "PRESS 1 TO RUN IT AGAIN")
    end

    return OVERLAY_UPDATED
end


startRun()

Arrow keys answer the prompts. Get all four and the film runs to the end and holds there on CLEAR. Get one wrong, or sit on your hands, and it cuts to a different frame with a different word on screen. 1 runs it again.

What Just Happened

Most of it you have already read. Four pieces are worth a second look.

if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then

The end of the film has to be caught, or it runs off the end and there is nothing to see. discSearch goes to a frame and pauses there, which is exactly what a final shot wants. The discGetState() half stops that happening again on every one of the following frames: once the disc is paused it is no longer DISC_PLAYING, so the condition is false and the seek is not repeated sixty times a second. discGetState and the DISC_* constants are in the reference under discGetState.

local move = nil
if not runOver then
    move = moveAt(frame)
end

onOverlayUpdate asks for the open move again, rather than being told by onInputPressed. That is deliberate. There is exactly one function that knows which move is open, and everybody asks it. If the prompt came from a variable that the input code kept up to date, then two pieces of code would be remembering the same fact, and sooner or later one of them would be wrong. When you are choosing between asking and remembering, ask.

overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

overlayPrint counts in character cells, as it has since lesson one, so the prompt is positioned by eye: column fifty four is near enough the middle for words of this length. It is near enough, not right, and "PRESS RIGHT" ends three characters further right than "PRESS UP". Lesson nineteen loads a real font, and with it the ability to measure a string in pixels and center it properly.

function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

One callback, two completely different jobs, chosen by runOver. While the run is going the directions mean moves; once it is over the only key that means anything is start. A variable that decides which rules apply is a state, which lesson twelve called by that name, and a game is mostly a small number of them.

Try It

  1. Make it harder. Change the first move’s last from 105 to 75. Fifteen frames is half a second. Play it and find out whether you can.

  2. Add a move. Put a fifth line in the table with a window between frames 370 and 400, and push LAST_FRAME up to 418. You should not have to touch any other line. If you do, something in the code knows too much about the table.

  3. Score the speed. Award more points for answering early. In onInputPressed, where the right answer is scored, work out left and span from move and discGetFrame() the same way the gauge does, and add RIGHT_SCORE * left // span instead of RIGHT_SCORE. Decide whether that makes the game better or only busier.

  4. Give a wrong answer its own consequence. Instead of ending the run, let a wrong press cost fifty points and leave the window open to try again. You will need to stop setting move.answer, and you will meet the reason it was set in the first place.

  5. Two prompts at once. Overlap two moves' windows and see what happens. moveAt returns the first match, so only one is ever asked. Decide what you would want, and what it would take.

Break It on Purpose

Delete the break from the loop that finds missed moves, and miss the first one on purpose. The run ends, the disc jumps, and everything looks right.

Now put debugPrint(move.name .. " missed") next to move.answer = "late" and do it again. The console shows one line, as you would expect.

Then take out the if not runOver then around the loop as well, and miss the first move again:

LEFT missed
UP missed
RIGHT missed
DOWN missed

The first line arrives when the window closes, as before. The other three arrive together on the very next frame, the instant the disc lands at 388: every remaining window is now in the past, so every unanswered move is missed at once, and each one calls endRun and seeks all over again. The game still more or less works, which is what makes it dangerous. Three extra seeks in a single frame, three overwrites of the verdict, and nothing on screen says so.

There is no error message here either. The lesson is that break and that guard are not tidiness. They are the two lines that say "this has already been decided", and code that keeps deciding something it has already decided is one of the most reliable sources of bugs you will ever write.

What You Learned

  • A quick-time event is a prompt, a window, and a consequence.

  • Measure the window in frames, because the film is the clock and there must only ever be one clock.

  • Keep the moves in a table of records, so that adding a move is adding a line.

  • Right, wrong, and no answer are three outcomes, and they usually lead three different places.

  • nil in a record field is a real state: nobody has answered yet.

  • One function answers "which move is open", and everybody asks it rather than keeping a copy.

  • Guard clauses — early return for the cases you do not care about — keep the real work unnested.

  • // divides and throws away the fraction; multiply before you divide.

  • overlayBox draws an outline, so a filled bar is a stack of overlayLine calls.

  • A missed move is a branch, and discSkipToFrame takes it, exactly as in lesson sixteen.

Next Time

Part three is done. You can play film, wait on it, branch on it, aim at it, and time the player against it. What you have been writing on top of it all is the engine’s console font, which is six pixels wide and meant for diagnostics. Lesson nineteen loads a real typeface, measures it, and makes the words on screen look like they belong to the game.

Lesson 19: Text That Looks Good

The finished lesson

Every word you have put on screen since lesson one came out of overlayPrint, and overlayPrint has exactly one font: a fixed-width block of pixels built into the engine, the same size forever, in whatever color it happens to be. It is perfect for a frame counter. It is wrong for a title, a score, a menu, or anything a player is meant to look at rather than read past.

This lesson loads a real font off disk, prints with it, colors it, measures it so you can center things, and shows you what printing text actually costs. At the end you will have a title screen that looks deliberate instead of accidental.

Set the Overlay to a Size You Can Think In

Start a new file called text.singe with two lines:

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

The first line you have written many times; it loads the framework, which defines DIR, the SWITCH_* names, and the FONT_QUALITY_* names you are about to use.

The second matters more than it looks. The overlay — the surface everything you draw lands on — starts at half the size of the world. A game with no video has a 720 by 480 canvas, so the overlay starts at 360 by 240, and a 36 point font on a 360 pixel wide overlay is enormous. overlaySetResolution replaces the overlay with one of the size you ask for, and from then on every coordinate you give, and everything overlayGetWidth and overlayGetHeight tell you, is in that space.

discGetWidth() and discGetHeight() answer the size of the video when there is one and the size of the canvas when there is not, so that one line gives you an overlay that matches the world whichever kind of game this is. Call it once, at the start, before you draw anything.

Load a Font

Under that, add:

fontQuality(FONT_QUALITY_BLENDED)

local titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)

fontLoad opens a TrueType font file and hands you back a number — a handle — that you use whenever you want that font. The second argument is the point size, and it is fixed for the life of the handle. There is no way to change the size of a loaded font afterwards. If you want the same face at three sizes, you call fontLoad three times and keep three handles.

Singe/FreeSansBold.ttf is the font the engine unpacked into the Singe folder in your work folder the first time you ran anything. Every copy of Singe has it, so you can rely on it. Any other .ttf file works the same way; put it beside your script and load it as DIR .. "myfont.ttf".

Now print with it:

function onOverlayUpdate()
    overlayClear()
    fontPrint(24, 60, "ASTEROID PATROL")
    return OVERLAY_UPDATED
end

Run it. Big white letters near the top left.

Notice what you did not do: you never told fontPrint which font to use. fontLoad makes the font it just loaded the selected one, and fontPrint always draws with whatever is selected. With more than one font loaded you choose between them with fontSelect, which you will do in a moment.

Notice also that 24 and 60 are pixels, not character cells. This is the difference between fontPrint and overlayPrint that trips people up: overlayPrint(2, 2, …​) means two letters in and two lines down, while fontPrint(2, 2, …​) means two pixels in and two pixels down, which is jammed into the corner. The y you give is the top of the text, not the baseline it sits on.

Color

fontPrint takes three arguments and none of them is a color. The color comes from somewhere else:

    colorForeground(255, 211, 90)
    fontPrint(24, 60, "ASTEROID PATROL")

colorForeground sets red, green, and blue from 0 to 255, and an optional fourth number for opacity. It is not an argument to anything; it is a setting that the engine remembers. Everything drawn after it comes out in that color until you change it again, exactly the way overlayBox and overlayLine already work. So the pattern is always the same: set the color, then draw.

This is the first thing people get wrong with fonts, and the second thing is coming up in a few pages.

Quality

fontQuality decides how the letters are rasterized — how the curves of a letter are turned into pixels — and there are three choices. Try each one by putting it above the fontLoad line and looking at the result closely.

FONT_QUALITY_SOLID is the fastest. Every pixel is either the letter or it is not, so the diagonals and curves come out with visible stair steps. At 48 point it looks cheap. At 12 point on a small overlay it can look sharper than the alternatives, which is sometimes what you want.

FONT_QUALITY_SHADED smooths the edges, but it does it by blending them into the current background color, and it draws that background as a solid rectangle behind the whole string. You get a label with a box around it whether you wanted one or not. It is the right answer for a debug readout over a busy picture and the wrong answer for almost everything else.

FONT_QUALITY_BLENDED smooths the edges and keeps them see-through, so the letters sit on whatever is behind them. It costs the most and it is what you want nearly all the time. Use it unless you have a reason not to.

The setting is global, not per font, and it applies from the moment you call it onwards. Sprites you have already made keep the quality they were made with. The reference’s entry for fontQuality lists the three names and their values.

Measuring, so You Can Center Things

Sooner or later — usually about ten minutes in — you want the title in the middle of the screen. You know the screen is overlayGetWidth() wide. You do not know how wide the text is, and there is no fontMeasure call to ask.

What there is instead is fontToSprite. It renders a string with the selected font, the current quality, and the current color, and instead of putting it on screen it hands you back a sprite: the same kind of handle spriteLoad gives you, which means every sprite* call you learned in lesson nine works on it. Including the two that measure it.

fontSelect(titleFont)
colorForeground(255, 211, 90)
local titleImage = fontToSprite("ASTEROID PATROL")

And then, in onOverlayUpdate:

    local x = (overlayGetWidth() - spriteGetWidth(titleImage)) / 2
    spriteDraw(titleImage, x, 60)

That is centering, and it is the whole trick. Take the width of the space, take away the width of the thing, and half of what is left is the gap at each side.

Right alignment is the same idea with less arithmetic. To put text against the right hand margin:

    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), y)

spriteGetHeight measures the other direction, for stacking lines or centering vertically.

There is a catch in that first code block, and it is the second thing everybody gets wrong. The color is baked in when the sprite is made, not when it is drawn. colorForeground above fontToSprite changes the text. Putting it above spriteDraw instead does nothing at all, because colorForeground is a setting for drawing text and lines, and a sprite is drawn with its own pixels. If your carefully colored title comes out white, this is why.

A sprite can be recolored after it is made, but by a sprite call, not by colorForeground. spriteSetTint(image, red, green, blue) multiplies every pixel of the sprite by that color each time it is drawn, so text rendered in white can be drawn yellow today and red tomorrow without being made again. White is the color to render in when you mean to tint: anything multiplied by white stays what it was, so the tint is exactly the color you ask for.

What Printing Costs

The first time fontPrint sees a string, it does real work: it rasterizes every letter from the font’s outlines and builds an image of the whole string. Then it keeps that image. The next time you print the same string, with the same font, quality, and colors, it skips all of that and copies the image it already has, which is about what drawing a sprite costs. A string you stop printing is let go a second later, so nothing piles up.

That means the obvious way to write a title screen is also the fast one. Printing "ASTEROID PATROL" sixty times a second renders it once. A score that changes twice a second renders twice a second, on its own, with no bookkeeping from you.

The one case that costs is text that is different every frame — a timer in milliseconds, a frame counter — because every frame is a string fontPrint has never seen. On a desktop it does not matter. On a Raspberry Pi or a handheld, a screenful of it will. The cure is to change the text less often: a timer in whole seconds is a new string once a second, not sixty times.

So why did this lesson use fontToSprite at all? Because a sprite can do things printed text cannot:

  • It can be measured, which is the only way to center text or line it up against the right hand side.

  • It can be scaled and turned with the sprite* calls from lesson nine.

  • It can outlive its font, which matters in a moment.

Use fontPrint for text, and fontToSprite when you need one of those.

The score in this lesson needs one of them: it sits against the right hand margin, so it has to be measured, so it has to be a sprite. And a sprite of a score is only right until the score changes. When it does, render a new sprite and unload the old one — forgetting that leaks a sprite per change:

local function renderScore()
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontSelect(scoreFont)
    colorForeground(255, 255, 255)
    scoreImage = fontToSprite(string.format("%06d", score))
    scoreShown = score
end

scoreShown remembers which score that sprite says, so the drawing code can tell whether it is still right:

    if score ~= scoreShown then
        renderScore()
    end

string.format("%06d", score) is plain Lua, not Singe. It turns a number into a string, and %06d means "as a whole number, at least six digits, padded with zeros", which is why arcade scores have leading zeros. Change it to %d and the zeros go away.

Putting Fonts Away

fontUnload closes a font and makes its handle invalid. Sprites you made with fontToSprite are not affected — once rendered, a sprite has nothing more to do with the font — so you can unload a font and go on drawing text made from it.

One sharp edge: if you unload the font that was selected, no font is selected afterwards, and the next fontPrint ends your game with an error. Select another one first if you are going to keep printing.

The tidy place for all this is onShutdown, a callback the engine calls once when the game is closing:

function onShutdown()
    spriteUnload(titleImage)
    fontUnload(titleFont)
end

Singe cleans up after you when the game ends, so nothing catches fire if you skip this. Write it anyway. A game that releases what it loaded is a game you can load twice.

The Whole Script

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local MARGIN  = 24
local TITLE_Y = 60
local SCORE_Y = 170
local LABEL_Y = 186
local HINT_Y  = 300
local CLOCK_Y = 430

local score      = 0
local titleFont  = nil
local scoreFont  = nil
local smallFont  = nil
local titleImage = nil
local hintImage  = nil
local scoreImage = nil
local scoreShown = nil


local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end


local function renderScore()
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontSelect(scoreFont)
    colorForeground(255, 255, 255)
    scoreImage = fontToSprite(string.format("%06d", score))
    scoreShown = score
end


fontQuality(FONT_QUALITY_BLENDED)

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

fontSelect(titleFont)
colorForeground(255, 211, 90)
titleImage = fontToSprite("ASTEROID PATROL")

fontSelect(smallFont)
colorForeground(140, 200, 255)
hintImage = fontToSprite("Press the fire button to score")

renderScore()


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        score = score + 125
    end
end


function onOverlayUpdate()
    overlayClear()

    spriteDraw(titleImage, centered(titleImage), TITLE_Y)

    if score ~= scoreShown then
        renderScore()
    end
    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), SCORE_Y)

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")
    fontPrint(MARGIN, CLOCK_Y, "Running for " .. (singeGetTicks() // 1000) .. " seconds")

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(titleImage)
    spriteUnload(hintImage)
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontUnload(titleFont)
    fontUnload(scoreFont)
    fontUnload(smallFont)
end

Run it and hold the fire button. The title and the hint sit centered, the score climbs against the right margin and is re-rendered only when it changes, the hint blinks, and the label and the clock are printed with fontPrint every frame — the clock in whole seconds, so it is a new string only once a second.

What Just Happened

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

One file, three sizes, three handles. Each one costs memory for its own set of rendered glyphs, so load the sizes you use and no more. Three is normal. A dozen is a smell.

After these three lines the selected font is smallFont, because loading selects. That is why the code calls fontSelect(titleFont) before rendering the title: the last thing loaded is not the thing you want first.

local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end

Written once as a function because it is used twice, and because the next time you want something centered you will want it again. Give the arithmetic a name and you never have to read it again.

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

singeGetTicks() is the number of milliseconds since the engine started. // is division that throws away the remainder, so singeGetTicks() // 500 counts half-seconds, and % 2 is the remainder after dividing by two, which is 0, 1, 0, 1…​ So the hint is drawn for half a second and skipped for half a second. Drawing nothing is how you make something blink.

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")

Both settings are needed here, and it is worth being clear about why. Drawing a sprite does not change the selected font or the color, so the two spriteDraw calls above leave both exactly as they found them. But the setup code selected three different fonts in turn, and renderScore selects another one whenever the score moves, so the selection when this line runs is whichever one happened to be chosen last. Do not try to keep track of it. Select the font and set the color immediately before you print, every time. It is two lines and it removes a whole category of puzzled evening.

Try It

  1. Change the quality. Put FONT_QUALITY_SOLID in the fontQuality line and look at the curve of the S in ASTEROID. Then try FONT_QUALITY_SHADED and watch what happens behind every string.

  2. Make the hint yellow. Move the colorForeground(140, 200, 255) line from above fontToSprite to just above the spriteDraw that draws hintImage, and change the numbers. Work out why nothing happens. Then put it back, make the hint white instead, and turn it yellow with spriteSetTint just before it is drawn.

  3. Right align the clock. The clock is drawn with fontPrint, which cannot be measured. Get it against the right margin anyway. There is only one way, and finding it is the point.

  4. Take out the scoreShown check, so renderScore() runs every frame instead. It will look identical, but it now renders the score sixty times a second instead of when it changes — exactly the work fontPrint saves you when you let it. Then take out the spriteUnload in renderScore as well, leave it running for a minute, and watch the memory your game is using.

  5. Print a clock in milliseconds. Change the clock line to print singeGetTicks() without the // 1000. It still works; it is now a string fontPrint has never seen, every frame. On a slow machine, that is the kind of text that costs.

  6. Use your own font. Find a .ttf on your machine, copy it beside your script, and load it with DIR .. "thatfont.ttf". Some fonts look terrible at 18 point and fine at 48. That is the font’s fault, not yours.

Break It on Purpose

Add a line reading fontPrint(24, 60, "SCORE") directly under overlaySetResolution(discGetWidth(), discGetHeight()), so that it runs before any fontLoad has. Singe starts and dies at once:

4:fontPrint:  No font selected.

Read it the same way as any other error. 4 is the line. fontPrint is which engine call complained — this shape of message comes from inside the engine rather than from Lua, so it names the function instead of the file. The rest is the complaint, and here it is exact: you asked it to print and there was no font to print with.

You will meet this one for real in a less obvious way. Unload the selected font while the game is running and the next fontPrint says precisely the same thing, several hundred lines away from the fontUnload that caused it.

What You Learned

  • fontLoad opens a TrueType file at one fixed point size and returns a handle. One size, one handle.

  • Loading a font selects it; fontSelect chooses between loaded fonts.

  • fontPrint counts in pixels and overlayPrint counts in character cells.

  • Color is not an argument. colorForeground is a setting; set it, then draw.

  • fontQuality picks how letters are rasterized, and FONT_QUALITY_BLENDED is the usual answer.

  • fontPrint keeps what it renders, so printing the same text every frame is cheap; text that is different every frame is what costs.

  • fontToSprite renders into a sprite, which spriteGetWidth measures and the sprite* calls can scale and turn. Use it for that, not for speed.

  • Measuring is how you center or right align text, because nothing else can tell you how wide a string will be.

  • colorForeground reaches text when it is made, never a sprite when it is drawn; spriteSetTint is how a sprite is recolored afterwards.

  • fontUnload frees a font; the sprites it made survive it.

Next Time

Text that looks good is a long way from a menu that works. A page with a title, a list you move a cursor through, a slider, and a button is a hundred lines of drawing and cursor arithmetic if you build it out of the calls in this lesson. Lesson twenty does not build it out of those calls at all.

Lesson 20: Menus and Screens

The finished lesson

You can build a menu out of what you already know. A box, some text, a cursor that moves when the stick moves, an if for every choice, and arithmetic to keep it all lined up when you add a fourth option. It works. It is also about a hundred lines for a page with three buttons on it, and every one of those lines is yours to maintain.

Singe has a whole document engine inside it — RmlUi — and a menu written for it is a page, like a web page, with a style sheet. It wraps its own text. It lays itself out when you add an option. It knows what a button is, what a slider is, and which control the player is pointing at. This lesson builds a pause menu with it, over a game that keeps running behind.

Two Files

A GUI page is two things: a document that says what is on the page, and Lua that says what the page does. They live in separate files, and this is the whole point of the exercise — the layout stops being code.

Start with a script called menu.singe and a game so small it fits in a paragraph: a ship crossing the screen, and a score that goes up each time it gets across. You have written this kind of thing since lesson seven.

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local ship  = spriteLoad(DIR .. "art/spaceship.png")
local shipX = 0
local speed = 2
local score = 0


function onOverlayUpdate()
    overlayClear()
    shipX = shipX + speed
    if shipX > overlayGetWidth() then
        shipX = -spriteGetWidth(ship)
        score = score + 10
    end
    spriteDraw(ship, shipX, 300)
    return OVERLAY_UPDATED
end

That runs. Now the document. Beside your script, make a file called pause.rml:

<rml>
<head>
	<title>Pause</title>
	<link type="text/rcss" href="Singe/gui.rcss"/>
	<style>
		body { width: 100%; height: 100%; }
		#frame { width: 380dp; margin: 80dp auto; }
		.row { display: block; margin: 8dp 0; }
		label { display: inline-block; width: 100dp; }
		button { nav: auto; }
		input.range { nav: auto; width: 200dp; }
		#status { min-height: 28dp; }
	</style>
</head>
<body id="pause">
	<div id="frame" class="panel">
		<h1>Paused</h1>
		<p class="row">Score <span id="score">000000</span></p>
		<div class="row"><label>Speed</label><input type="range" id="speed" min="1" max="8" step="1" value="2"/></div>
		<div class="row">
			<button id="resume" autofocus>Resume</button>
			<button id="restart">Restart</button>
			<button id="quit">Quit</button>
		</div>
		<p id="status" class="muted">Arrow keys move, Return chooses.</p>
	</div>
</body>
</rml>

If you have ever seen a web page’s source, that is familiar. If you have not, here is everything you need to read it.

A document is made of elements. An element starts with a name in angle brackets, <h1>, ends with the same name and a slash, </h1>, and whatever is between them is inside it. Some elements have nothing inside and close themselves with a slash at the end, like the <input …​/> above. Elements nest, and the indentation shows the nesting the same way it shows it in Lua.

The words inside the opening tag are attributes, written name="value". Two of them matter to you more than the rest. id gives an element a name your script can find it by, which is how Lua and the document talk to each other. class puts the element in a group the style sheet can aim at; panel, muted, and list are groups the engine’s own style sheet already knows about.

The markup language is called RML and the style language is called RCSS. They are RmlUi’s, not Singe’s. The reference’s GUI chapter points at RmlUi’s own documentation for the full list of what you can write, and you will want it eventually. Everything in this lesson works without it.

Show It

Back in the script. Above onOverlayUpdate, add:

local gui  = guiNew(overlayGetWidth(), overlayGetHeight())
local page = guiLoad(gui, DIR .. "pause.rml")

guiNew makes a GUI: a rectangle of a fixed size that documents are laid out and drawn into. It returns a handle, the way fontLoad and spriteLoad do. Making it the size of the overlay means one pixel of the document is one pixel of your overlay, which keeps the arithmetic in your head simple.

guiLoad reads a document into that GUI and returns a second handle, for the document itself. Nearly every other call takes both: the GUI and the document in it. One GUI can hold up to thirty-two documents — a title page, an options page, and a game over page can share one — and up to sixteen GUIs can exist at once.

Nothing is on screen yet, because loading a document does not draw it. Add one line to onOverlayUpdate, just before the return:

    guiDraw(gui)

Run it. The panel is there, over the ship, with its heading and its three buttons and its slider, and you have written no drawing code at all.

guiDraw composites the GUI over the overlay for this frame only, like every other drawing call, so it belongs in onOverlayUpdate and has to be called again next frame. Where you put it decides what is on top: everything you drew before it is underneath, and everything you draw after it goes over it. A crosshair drawn after guiDraw is never hidden by the menu.

Let the Player Use It

Click a button. Nothing happens, and the button does not even light up.

A new GUI is a picture, not a control panel. That is deliberate: a HUD or a sign should not swallow the fire button. To make a page take input:

guiSetInput(gui, true)

Now the mouse works, the buttons light up under the pointer, and the arrow keys move between the controls, because the document asked for that with nav: auto. On a pad or a stick the four directions arrive as the arrow keys, the first action button arrives as Return, and the second arrives as Escape. A cabinet with a joystick and two buttons drives this page without knowing it is a document.

The control the keys are working on is said to have the focus, and a focused button wears a gold border. The focus starts on Resume because that button says autofocus: whenever the page is shown, the focus goes to the control marked that way. Leave it out and the arrow keys have nothing to move from until the player clicks something, which on a cabinet with no mouse is never.

Clicking still does nothing, though, because nothing is listening.

Talk to It

Three calls join the document to your script, and between them they do almost everything.

guiSetHandler(gui, page, "resume", "click", function()
    closeMenu()
end)

guiSetHandler says: when the element with this id does this thing, call this function. The id is the one in the document. The event name is RmlUi’s: "click" for buttons, "change" for anything the player adjusts, and a long list of others you can look up when you need them. One function is kept per element and per event, so setting another replaces it, and passing nil instead of a function removes it.

Your function is called with five arguments — the GUI, the document, the id, the event, and the element’s current value as a string. Take as many as you want and ignore the rest, the way you already ignore arguments in Lua.

guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
    speed = math.floor(tonumber(value))
end)

The slider hands its value over as a string, and RmlUi formats numbers its own way, so 4 arrives as "4.000000". tonumber turns the string into a number and math.floor throws away the fraction. Skipping that step and using the string as a number is a mistake you will make once.

guiSetValue(gui, page, "score", string.format("%06d", score))

guiSetValue writes into an element. For a form control it sets the control’s value; for anything else — a paragraph, a div, the <span id="score"> in your document — it replaces what is inside the element, and the page lays itself out again on the next frame. guiGetValue is the same call backwards, and it answers nil for an id nothing has, so you can ask about an element that might not be there without dying.

That is the whole everyday API: guiSetHandler, guiSetValue, guiGetValue. There is far more available through RmlUi’s own Lua objects, reachable from the global rmlui, and the reference’s GUI chapter shows how. You will get a long way before you need it.

Hide It Again

A pause menu is not up all the time. guiHide takes a document off screen and guiShow puts it back, keeping everything the player typed or chose.

The pause itself is singeSetPauseFlag(true), which stops the disc, the videos, and the sounds but keeps calling your callbacks, so you can still draw. The engine has its own pause key, which freezes the script completely, and the two would fight; singeSetPauseKeyEnabled(false) takes that key away from the engine so SWITCH_PAUSE arrives at onInputPressed like any other switch. On a keyboard that key is P.

local function closeMenu()
    paused = false
    singeSetPauseFlag(false)
    guiHide(gui, page)
    guiSetInput(gui, false)
end


local function openMenu()
    paused = true
    singeSetPauseFlag(true)
    guiSetValue(gui, page, "score", string.format("%06d", score))
    guiShow(gui, page)
    guiSetInput(gui, true)
end

Turning input off with the page is not decoration. A hidden page that still takes input eats the player’s arrow keys for the rest of the game.

What the Page Does Not Use, You Still Get

This is the rule that makes a GUI safe to leave up during play, and it is worth saying plainly: an event an element used never reaches your callbacks. A Return that pressed the focused button does not arrive as onInputPressed. An arrow that moved the focus does not arrive as SWITCH_LEFT. A click on a button is not a mouse switch.

Everything the page did not use falls straight through as usual. That is why P closes this menu: no element in the document uses P, so the key arrives at onInputPressed exactly as it does when the menu is down. It is also why a HUD that takes input still lets the fire button through.

One key does not follow the rule. RmlUi uses Tab to move focus and never gives it back, so Singe only hands Tab to a GUI while a text field is actually being typed in. A game that binds Tab to something keeps it.

Style It

Look back at the document’s <head>. One line does most of the work:

	<link type="text/rcss" href="Singe/gui.rcss"/>

That is the theme the engine ships, and it is why your panel has a border, a gradient, and a gold heading without you choosing any of it. Without a style sheet RmlUi draws almost nothing, because every element starts out inline and sized to its contents, so linking this first and overriding what you dislike is the fastest road to a page that looks like something.

The theme gives you .panel (a bordered, rounded box), .list (a scrolling box whose child div rows highlight and take focus), .muted (dimmer text for hints), headings, and every form control with its hover, focus, and pressed states. The reference’s GUI chapter lists them.

Everything after the link is yours. The <style> block in pause.rml overrides the theme for this page, later rules winning over earlier ones, and a rule aimed at an id beats one aimed at a class. For a real game put your own rules in a .rcss file beside the document and link it second, so your look is one file for every page.

The unit dp is a pixel of the GUI’s own size — your GUI is the size of the overlay, so 380dp is 380 overlay pixels. margin: 80dp auto is the trick that centers a block of a known width: auto splits whatever is left over equally between the two sides. There is no measuring and no arithmetic, which after lesson nineteen you may find slightly annoying.

To use your own font in a document, load it with guiLoadFont before the documents that use it, and name it in RCSS by the family name inside the font file, not by its file name.

When Not to Use Any of This

A GUI is a page. It is the right answer for a menu, an options screen, a high score table, a game over screen, or a HUD with a real layout.

It is the wrong answer for a score in the corner. That is two lines of fontPrint from lesson nineteen, and wrapping it in a document buys you nothing and costs you a texture. The same goes for a crosshair, a health bar you drew with overlayBox, and a line of debug text.

Three facts decide it for you.

A GUI needs a GPU. On a machine without one — an old box, a small Pi, a machine with no Vulkan, Direct3D 12, or Metal driver at all — there are no GUIs, and guiNew does not politely answer false, it ends your game. The 3D scene of lesson twenty-two goes the same way, so this is not the last time you will ask. Ask singeHasGpu() first if your game has to run in both places, and have a plain overlay version to fall back on. The engine’s own menu does exactly that.

A GUI costs a texture and a layout pass every frame, whether or not you draw it. A GUI you are finished with should be deleted with guiDelete, not merely hidden. Hiding is for a page you will show again in a minute.

And a GUI is torn down by a reload. F5, -R, and anything that restarts the script take every GUI with them, and the script makes them again when it runs. That is fine, as long as you build them in your script’s body and not in some corner that only runs once.

The Whole Script

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())
singeSetPauseKeyEnabled(false)

local SHIP_Y = 300

local ship    = spriteLoad(DIR .. "art/spaceship.png")
local hudFont = fontLoad("Singe/FreeSansBold.ttf", 20)
local shipX   = 0
local speed   = 2
local score   = 0
local paused  = false
local gui     = nil
local page    = nil


local function say(text)
    if gui ~= nil then
        guiSetValue(gui, page, "status", text)
    end
end


local function closeMenu()
    paused = false
    singeSetPauseFlag(false)
    if gui ~= nil then
        guiHide(gui, page)
        guiSetInput(gui, false)
    end
end


local function openMenu()
    paused = true
    singeSetPauseFlag(true)
    if gui ~= nil then
        guiSetValue(gui, page, "score", string.format("%06d", score))
        guiShow(gui, page)
        guiSetInput(gui, true)
    end
end


if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")
    guiHide(gui, page)
    guiSetInput(gui, false)

    guiSetHandler(gui, page, "resume", "click", function()
        closeMenu()
    end)

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

    guiSetHandler(gui, page, "quit", "click", function()
        singeQuit()
    end)

    guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
        speed = math.floor(tonumber(value))
        say("Speed " .. speed)
    end)
end


function onInputPressed(what)
    if what == SWITCH_PAUSE then
        if paused then
            closeMenu()
        else
            openMenu()
        end
    end
end


function onOverlayUpdate()
    overlayClear()

    if not paused then
        shipX = shipX + speed
        if shipX > overlayGetWidth() then
            shipX = -spriteGetWidth(ship)
            score = score + 10
        end
    end
    spriteDraw(ship, shipX, SHIP_Y)

    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    fontPrint(16, 16, string.format("SCORE %06d", score))
    fontPrint(16, 40, "P pauses")

    if paused then
        if gui ~= nil then
            guiDraw(gui)
        else
            colorForeground(255, 211, 90)
            fontPrint(16, 70, "PAUSED -- no GPU, so no menu")
        end
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    if gui ~= nil then
        guiDelete(gui)
    end
    spriteUnload(ship)
    fontUnload(hudFont)
end

What Just Happened

if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")

The whole GUI is built inside that if, and gui stays nil on a machine without one. Every call that touches the GUI is guarded with if gui ~= nil, and the pause still works without a menu. It is four extra lines and it is the difference between "does not have a menu on that machine" and "does not start on that machine".

    guiHide(gui, page)
    guiSetInput(gui, false)

guiLoad shows the document it loaded, so a page that should start hidden has to be hidden immediately. Input is off already for a new GUI, but turning it off here means openMenu and closeMenu are exact mirrors of each other, and mirrored pairs are much harder to get wrong.

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

The handler is a function with no name, written where it is used. Lua lets you write function(…​) …​ end anywhere a value is wanted, and since guiSetHandler wants a function, you can hand it one on the spot instead of naming it first and passing the name. It reaches score, shipX, and closeMenu because they are declared above it in the same file, which is the whole reason the handlers are set up below the things they touch.

    if not paused then
        shipX = shipX + speed

The pause flag stops the disc and the sounds, not your arithmetic. onOverlayUpdate keeps being called — that is the point, since otherwise the menu could not be drawn — so anything of yours that should stop while paused, you stop yourself.

Try It

  1. Add a fourth button. Copy the <button id="quit"> line, give it a new id and new text, and add a handler for it. Notice that nothing had to be re-measured or moved along.

  2. Restyle it. In the <style> block, change #frame to width: 260dp; margin: 20dp; and see the panel move and the text rewrap by itself.

  3. Take out the guiSetInput(gui, true) in openMenu. The page still appears. Work out from the screen alone what you have lost.

  4. Leave the page shown all the time. Delete the guiHide calls, change both guiSetInput(gui, false) calls to true, and draw the GUI every frame instead of only while paused. Then press the arrow keys and Return while the ship flies. The page takes them for itself: the focus moves, the slider changes the speed, and Return presses whichever button has the focus. A game that steered with those keys would never hear them. This is why a HUD is guiSetInput(gui, false).

  5. Put the score on the page instead of the HUD. Call guiSetValue for score every frame rather than only in openMenu, and delete the fontPrint line. Then decide which of the two you actually prefer, and why.

Break It on Purpose

Change one id in pause.rml, from id="resume" to id="continue", and leave the script alone. Singe starts and dies:

52:guiSetHandler:  No element "resume" in document 0 of GUI 0.

Read it as you read any engine error. The line, the call that complained, then the complaint — and this complaint is precise. It is not saying the document is broken; the document loaded perfectly. It is saying you asked for an element by a name nothing in it has.

guiSetHandler and guiSetValue both die on a missing id, because a handler you meant to attach and did not is a bug you want to hear about at once. guiGetValue is the exception: it answers nil instead, so you can ask whether something is there.

The other error worth meeting is the one you get when the document itself does not load. Rename pause.rml and run. This time Singe names the file and quotes RmlUi’s own reason, and RmlUi’s grumbles about your markup and your styles go to the console whether or not the load succeeds. Read that console the first time a page comes out blank; it will usually have said why.

What You Learned

  • A GUI is a fixed size rectangle that documents are laid out and drawn into; guiNew makes one and guiDelete frees it.

  • guiLoad puts an RML document in a GUI and shows it; guiHide, guiShow, and guiClose manage it afterwards.

  • guiDraw composites the GUI over the overlay for one frame, so it goes in onOverlayUpdate like every other drawing call.

  • A new GUI only displays; guiSetInput is what makes it usable.

  • guiSetHandler runs your function when an element is clicked or changed, guiSetValue writes into an element, and guiGetValue reads one.

  • An event an element used never reaches your own callbacks; everything else falls through as normal.

  • Singe/gui.rcss is the shipped theme; link it first and override it in a <style> block or a sheet of your own.

  • A GUI needs a GPU, so ask singeHasGpu() if your game must run without one.

  • Every GUI renders every frame whether you draw it or not, so delete the ones you have finished with.

  • A score in the corner is two lines of fontPrint, not a document.

Next Time

There is one more kind of text on screen, and it has its own system for a reason that has nothing to do with how it looks. Lesson twenty-one is about subtitles, and about the players who cannot play your game without them.

Lesson 21: Subtitles

The finished lesson

Somebody who cannot hear is going to play your game.

If your game has speech in it and no subtitles, they cannot. Not "it is harder for them" — they will reach the first scene where a character says the thing that tells the player what to do, and they will stop. That is the whole of it, and it is the reason this lesson exists rather than being a paragraph in lesson nineteen.

The other reason is practical. Retrofitting subtitles into a finished game is miserable. You have to find every line of speech, work out which frame it is on, and discover that half your timings are wrong because your video was re-encoded in the middle of the project. Done while you are writing the game, it is an afternoon. Singe gives you a system that does the hard part, and this lesson is how to use it.

It Is Not Ordinary Text Drawing

You could do subtitles yourself. Keep a list of lines with start and end times, check the clock in onOverlayUpdate, and draw the current one with fontToSprite. People have. Here is why you should not.

Subtitles are timed against the disc, not against a clock. When srtLoad reads your file it converts every timestamp into a disc frame number, there and then, using the frame rate of the disc that is loaded. From that moment the engine is not watching a clock at all; every drawn frame it asks which cue covers the frame the disc is on.

That one decision buys you the thing a hand rolled system never gets right: a subtitle survives a seek. Send the disc anywhere — discSearch, discSkipForward, a step, a branch into another segment — and the right line is up on the next drawn frame, forwards or backwards, with nothing reloaded and no clock reset. In a branching game from lesson sixteen, where the player’s choices jump the disc around constantly, that is the difference between working and almost working.

It also draws in the right place. The subtitle document sits over the picture, above your overlay, below any screen space GUI, and it follows the picture wherever the player’s settings put it — a shrunken picture, a shifted one, a rotated cabinet, a hole in a bezel. It takes no mouse input, so a light gun shot passes straight through it. Getting all of that right yourself is a week you did not plan for.

Write the File

Subtitles go in a SubRip file, which ends in .srt and is plain text you can type in any editor. It is one of the simplest formats there is. Make a file called subtitles.srt beside your script:

1
00:00:01,000 --> 00:00:04,000
They told us the cave was empty.

2
00:00:04,200 --> 00:00:08,000
They were wrong about
a great many things.

3
00:00:08,500 --> 00:00:13,000
Keep your light on the floor.

A cue is four things. A number on a line of its own. A line with two timestamps and an arrow made of two hyphens and a greater-than sign between them. One or more lines of text. A blank line to finish.

A timestamp is HH:MM:SS,mmm — hours, minutes, and seconds separated by colons, then a comma, then milliseconds. The comma is not a typo and a full stop will not do. 00:00:04,200 is four and a fifth seconds in.

The cue numbers are read and thrown away, so they do not have to be in order or even correct. Number them anyway; you will be looking for cue forty-one at some point.

Cue two shows what a two line cue looks like. The lines are shown as you wrote them, so you decide where a long line breaks, which matters more than you would think and is covered further down.

The parser is deliberately forgiving about the things that go wrong in a hand edited file. Windows line endings load unchanged, and leading and trailing spaces are stripped from every line. A cue whose timestamps do not parse is skipped and the rest of the file goes on loading, which is friendly right up until you wonder where line twelve went. A few things are not supported: the <i> and <b> tags some tools write are shown as text rather than obeyed, and the positioning coordinates some tools append to the time line are ignored. The reference’s Subtitles section is the full list.

Load It and Switch It On

Three calls, and the order matters.

if srtLoad(DIR .. "subtitles.srt") then
    srtPosition(80)
    srtEnable(true)
end

srtLoad reads the file and answers true or false. It answers false, having loaded nothing, in three cases: the file cannot be read, nothing in it parses, or there is no disc. In all three it prints a warning naming the file to the console. That is a good design and you should use it: a missing subtitle file is not worth killing a game over, but silently shipping a game with no subtitles is worth noticing.

The "no disc" case is the one that will catch you. The timestamps have to become frame numbers at the disc’s frame rate, and until a disc is open there is no frame rate to use. So load subtitles after the disc, which in an ordinary script means from the body of the script, where everything else you have written at the top level runs. It follows that a .srt cut for a video at one frame rate lands in the wrong place on a video at another. Time your file against the video you are actually going to ship.

srtEnable(true) switches the loaded cues on. A script starts with subtitles off, always, so a game that loads them must switch them on. Switching them off again takes down whatever is showing, and switching them back on puts up whatever covers the frame the disc is on right now — no hunting, no state to keep.

Keeping subtitles on is a setting, not a decision you make for the player. Put it in your options page from lesson twenty, save it with saveSet from lesson twelve, and hand srtEnable whatever the player last chose.

Where They Sit

srtPosition(70)

srtPosition is a percentage down the picture, from 1 to 95, and the default is 80. It takes effect on the cue that is up right now and on every cue after it. A number outside the range is ignored rather than clamped, which means a typo leaves the position exactly where it was and says nothing, so check yours.

Eighty per cent is low, and it is low on purpose: the bottom of the picture is usually the least interesting part of the shot. Move it up when the bottom is not boring — when your game draws a scoreboard along the bottom edge, or when the player’s light gun crosshair lives down there.

Taking One Down

srtClear()

srtClear takes whatever is on screen off at once, and leaves the loaded cues and the enabled state alone. The line that was showing stays off until the disc reaches the next cue. Use it when a scene ends early and you do not want the last line of dialogue hanging over the next shot.

There is one more call that shares the subtitle machinery, and you may have used it already:

overlayBanner("Extra life!", 20)

overlayBanner shows a short message over the picture for about thirty drawn frames and then removes it. It is drawn by the same document as the subtitles, so a banner looks like a subtitle, and while one is up it takes the place of any subtitle, which comes back when the banner times out. Its own height argument is separate from srtPosition and defaults to 47, the middle of the picture. Messages longer than sixty characters are ignored entirely, so a long one appears not to work at all.

Subtitles Already Inside the Video

Some video files carry their own subtitle tracks. If yours does, you do not need a .srt at all:

if discGetSubtitleTracks() > 0 then
    srtLoadTrack(0)
else
    srtLoad(DIR .. "subtitles.srt")
end
srtEnable(true)

srtLoadTrack takes a track number from 0 to discGetSubtitleTracks() - 1 and everything after loading is identical. discGetSubtitleLanguage(track) tells you what language a track is labeled with, as a three letter code like eng or fra, so a game can offer the player whatever its video happens to carry.

Two warnings. Reading a track walks the whole video file once, decoding no pictures, so a feature length disc takes a moment: do it while something else is on screen, not between two frames of gameplay. And subtitle tracks that hold pictures of the words rather than the words — the kinds DVDs and Blu-rays use — cannot be read. They are counted, so the numbering matches what other players show, but srtLoadTrack answers false for them.

The Whole Script

This one needs a video. You have one: Singe/menuBackground.mkv, which the engine unpacked into your work folder the first time you ran anything. Tell Singe to use it as the disc with --framefile, which also turns the disc on:

Singe --framefile=Singe/menuBackground.mkv subtitles
dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local HUD_X     = 16
local STEP      = 5
local TOP_LIMIT = 10
local LOW_LIMIT = 95

local hudFont = fontLoad("Singe/FreeSansBold.ttf", 18)
local loaded  = false
local showing = false
local height  = 80


if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

if loaded then
    srtPosition(height)
    showing = true
    srtEnable(true)
end

discPlay()


function onInputPressed(what)
    if not loaded then
        return
    end
    if what == SWITCH_BUTTON1 then
        showing = not showing
        srtEnable(showing)
        if showing then
            overlayBanner("Subtitles on", 20)
        else
            overlayBanner("Subtitles off", 20)
        end
    elseif what == SWITCH_UP then
        height = math.max(TOP_LIMIT, height - STEP)
        srtPosition(height)
    elseif what == SWITCH_DOWN then
        height = math.min(LOW_LIMIT, height + STEP)
        srtPosition(height)
    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()
    end
end


function onOverlayUpdate()
    overlayClear()
    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    if loaded then
        if showing then
            fontPrint(HUD_X, 16, "Frame " .. discGetFrame() .. "   subtitles ON at " .. height .. "%")
        else
            fontPrint(HUD_X, 16, "Frame " .. discGetFrame() .. "   subtitles OFF")
        end
        fontPrint(HUD_X, 40, "Fire toggles them, up and down move them, left rewinds")
    else
        fontPrint(HUD_X, 16, "No subtitles loaded.")
        fontPrint(HUD_X, 40, "Run with --framefile and check subtitles.srt is beside the script.")
    end
    return OVERLAY_UPDATED
end


function onShutdown()
    fontUnload(hudFont)
end

Press fire to toggle, up and down to move the lines, and left to rewind to the start. The rewind is the one to watch: the disc jumps back to frame zero and the correct cue is up on the very next frame, without you doing anything about it.

What Just Happened

if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

Take the video’s own subtitles when it has them, fall back to the file beside the script when it does not, and end up knowing which — if either — worked. Both calls answer a boolean, so the fallback is two if statements and no special cases. menuBackground.mkv carries no subtitle track, so what you will actually get is the file you typed.

function onInputPressed(what)
    if not loaded then
        return
    end

return with nothing after it leaves the function immediately. With no subtitles loaded there is nothing for any of these keys to do, and leaving early is clearer than wrapping the whole body in an if. Calling srtEnable with nothing loaded is harmless, but writing code that only makes sense when it does nothing is a habit worth not forming.

    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()

The srtClear is not necessary. The engine will put up the right cue for frame zero on the next drawn frame regardless. It is there so that you can delete it and watch what happens: the old line stays up for a fraction of a second while the disc gets where it is going. On a slow seek that flash of the wrong line is visible, and clearing first is how you avoid it.

Making Text Readable Over a Moving Picture

The system puts the words on screen. Whether anybody can read them is your problem, and it applies to every line of text you draw over video — a prompt from lesson eighteen, a score, a branch choice — not only to subtitles.

Stay out of the edges. Television sets have been cutting the edges off pictures for seventy years, and arcade monitors are worse, not better. Work on the assumption that the outer five per cent of the picture on each side may not be there at all on somebody’s screen. Keep anything a player must read inside that. This is why srtPosition stops at 95 and not 100.

Contrast is not a color choice, it is a guarantee. White text over a picture is white text over whatever the picture happens to be doing, and in two seconds that may be a snowfield. The shipped subtitle style solves it the way film subtitles do: a dark panel that hugs the text, plus a one pixel shadow. If you draw your own text over video, do one or the other — an overlayBox behind it or a dark copy of the text offset by a pixel. Do not rely on the picture.

Break your own lines. Two short lines read faster than one long one, and a line that wraps where you did not choose usually breaks in the wrong place. Aim for about forty characters a line and no more than two lines at a time. Break at a natural pause: They were wrong about / a great many things reads; They were wrong / about a great many things stumbles.

Leave them up long enough. A comfortable reading speed is somewhere around fifteen characters a second, so a forty character line wants roughly three seconds. Look at cue one in the file above: thirty-two characters, three seconds. If a line of dialogue is short and quick, keeping the cue up a beat past the end of the speech is kinder than snapping it away.

Put them where the action is not. If the important thing in the shot is at the bottom of the frame, move the subtitles up for that scene with srtPosition. You can call it as often as you like, and the player will never notice that you did.

Styling Them

The lines are drawn by a document, the same kind you met in lesson twenty, and two files in your Singe folder decide what they look like:

  • Singe/subtitle.rml — the document. It holds one element, #slot, which the engine writes the current cue or banner into.

  • Singe/subtitle.rcss — the style. .cue is the block that carries the height srtPosition asked for, and .cue .text is the bar of text inside it: white, bold, on a dark rounded panel that hugs the text, with a shadow.

Open subtitle.rcss and read it — it is about forty lines. Then leave it alone, because an edit there does not last. Every time Singe starts, it puts back its own copy of anything in the Singe folder that has been changed, and says so:

>>> Updated File:  Singe/subtitle.rcss

That folder is the engine’s. Your game brings its own copy instead. Copy both files out of Singe and into your subtitles folder, beside the script. Then open your copy of subtitle.rml and change the one line in its <head> that links the style, so that it reads:

	<link type="text/rcss" href="subtitle.rcss"/>

A name inside a document is counted from the document’s own folder, except a name that starts with Singe/, which always means the engine’s folder. The link as you copied it, Singe/subtitle.rcss, still fetches the engine’s style. The new one fetches yours.

When Singe finds a subtitle.rml beside your script, it draws the subtitles with that instead of its own. Add -p to the command and Singe describes what it is doing as it goes, a line at a time:

Singe -p --framefile=Singe/menuBackground.mkv subtitles

When the first cue comes up, one of those lines is this:

Using the game's own subtitles/subtitle.rml

Now change the font-size, the color, the background-color, the border-radius, or the font-effect in your subtitle.rcss, save, and run again. The engine only ever sets the contents of #slot and the height of .cue, so everything else in your two files is yours, and nothing Singe does when it starts will touch them. If -p says it is using yours and the look has not changed, read the link again: a copy that still says Singe/ is quietly using the engine’s style.

Because overlayBanner uses the same document, restyling subtitles restyles your banners too, which is usually what you want and is worth knowing before you wonder why.

One limit: the subtitle document is a document, and documents need a GPU. On a machine without one, srtLoad still reads your file and still answers truthfully, and nothing is drawn. A warning says so once.

Try It

  1. Add a fourth cue to subtitles.srt, between eleven and thirteen seconds. Save and run. Then put it out of order, as cue 99, first in the file, and confirm it still works.

  2. Give a cue a bad timestamp — write 00:00:05.500 with a full stop instead of a comma — and run. Watch which line disappears, and notice that nothing at all is said about it. A file that loads is not a file that is right.

  3. Restyle them. In your own subtitle.rcss — the copy beside your script, not the one in Singe — change .cue .text to yellow text on a fully transparent background, then add a heavier shadow. Then play it over the video and decide honestly whether it is still readable.

  4. Break the timing on purpose. Change every timestamp in the file so it is two seconds late, and watch a correctly working system deliver useless subtitles. This is what a re-encoded video does to you.

  5. Put the toggle in a menu. Take the pause page from lesson twenty, add a checkbox, and wire it to srtEnable. Then save the choice with saveSet so it is still on next time. This is the version your players actually want.

Break It on Purpose

Run the script without the --framefile option:

Singe subtitles

The window opens, black, with your fallback message on it, and the console says:

Warning:  No subtitles were loaded from subtitles/subtitles.srt.

No crash and no error dialog, because srtLoad answered false and your script handled it.

That is the most valuable failure in this lesson, because it is the one that happens without anybody noticing. There is no disc, so there is no frame rate, so there is nothing to turn the timestamps into, so nothing loads. If you had written srtLoad(…​) on its own and thrown the answer away, your game would have run perfectly and shown no subtitles, and you would have found out when somebody told you.

Use the answer. Every time.

What You Learned

  • A game with speech and no subtitles is a game some people cannot play at all.

  • Building subtitles in as you go is an afternoon; retrofitting them is not.

  • Subtitles are a .srt file: a number, two timestamps with -→ between them, the text, and a blank line.

  • srtLoad turns the timestamps into disc frame numbers at load time, which is why a cue survives any seek.

  • It must be loaded after the disc, and it answers false when it cannot load, including when there is no disc. Check the answer.

  • srtEnable switches them on, and a script always starts with them off.

  • srtPosition places them as a percentage down the picture, 1 to 95.

  • srtClear takes down whatever is showing, and overlayBanner shares the same document.

  • srtLoadTrack reads subtitles out of the video file itself when it has them.

  • Singe rewrites its Singe folder at every start, so to restyle subtitles you copy subtitle.rml and subtitle.rcss beside your script, point the copy’s link at your own sheet, and change that.

  • Text over a moving picture needs a safe margin, its own contrast, lines you broke yourself, and time to be read.

Next Time

That is the last of the text. Part four goes on without you having to read it in order, and the next lesson opens a door that has been shut for twenty lessons: overlayGetWidth and overlayGetHeight are two numbers, and a scene has three. Lesson twenty-two is the third one.

Lesson 22: Into 3D

The finished lesson

Everything you have drawn so far has been flat. Sprites, text, boxes, and lines all live on the overlay, which is a sheet of glass at the front of the window with the same coordinates it had in lesson one. This lesson puts a world behind that glass: a place with depth, where a thing can be nearer or further away, and where a camera decides what you see of it.

By the end you will have a box floating in space that you can turn with the arrow keys, and the numbers for its angles printed in the corner by the same overlayPrint you used on your very first day. That last part matters more than it sounds, and there is a section about it.

A Scene, a Box, and a Light

Make a folder, put a file called spin.singe in it, and type this in.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)


function onOverlayUpdate()
    nodeRotate(box, 0, 0.5, 0)
    return OVERLAY_UPDATED
end

Run it with Singe -R spin. An orange box turns slowly on a dark blue background, lit from above and to the right, with one face bright and the others falling away into shadow.

There is no camera in that script. Singe put you at (0, 0, 5) looking at the middle of the world, because a scene with no camera has to be seen from somewhere. You will replace that with your own camera in a moment.

If the window stays black, read the console. On a machine whose graphics cannot draw a 3D scene, sceneEnable stops the game with a message saying so, and there is nothing to do about it but run the lesson elsewhere. 2D games keep working on such a machine; 3D does not.

What Just Happened

The three calls at the top set up the world as a whole.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

sceneEnable(true) turns the 3D layer on. It is the one call that every 3D game makes, and until you make it nothing you build in the scene is drawn.

sceneSetBackground is the color the scene is wiped to each frame, red, green, and blue from 0 to 255, the same way colors have worked since lesson nine. There is a fourth number you can give it for transparency, which is how a game that plays video puts a 3D object in front of the film. Leave it off and the background is solid.

sceneSetAmbient is a little light coming from every direction at once. Its job is to keep the sides that no lamp reaches from being pure black. Turn it down to 0, 0, 0 later and see how hard the picture becomes.

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

A material is how a surface looks: its color, how shiny it is, whether it has a picture on it. materialNew makes one and hands back a number that stands for it, the same kind of handle spriteLoad gave you in lesson nine. Keep it in a variable, because every later call needs it.

materialSetRoughness runs from 0, a mirror with a tiny hard highlight, to 1, a chalky matte surface with no highlight at all. 0.6 is paint on wood. There are a dozen more materialSet calls, and the next lesson uses some of them; the reference’s Material section lists them all.

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

This is the important one. A node is a place in the world. It has a position, a rotation, and a scale, and on its own it draws nothing at all: it is a spot that things can be attached to. Everything in a 3D scene is a node, including the lights and the camera.

nodeNew makes an empty one at the middle of the world. nodeSetMesh hangs two things on it: a mesh, which is the shape, and the material, which is how that shape looks. meshBox(2, 2, 2) builds a box two units wide, two high, and two deep, and hands back a handle to it the way materialNew did.

Meshes and materials are worth sharing. One meshBox handle can be used by a hundred nodes, and that is how you draw a hundred crates cheaply. Making a hundred separate boxes that happen to be the same size is the beginner’s way to make a scene slow.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)

lightNew also makes a node — one carrying a light — and hands back its node handle, so you place and aim it with the same calls you use for everything else. LIGHT_DIRECTIONAL is a sun: it is so far away that only the direction it shines in counts, which is why the position here matters only in that nodeLookAt uses it to work out the direction.

Take those three lines out and run it again. The box goes nearly black, because the only light left is the dim ambient. Light is the whole of lesson twenty-three, and this is the first taste of the most common disappointment in 3D: the model loaded fine, and the scene is black because nothing is shining on it.

    nodeRotate(box, 0, 0.5, 0)

nodeRotate turns a node by so many degrees about each of its own three axes, on top of whatever rotation it already had. Half a degree a frame, at about sixty frames a second, is a turn every twelve seconds. This is the same trick as lesson two: a small change, applied every frame, reads as movement.

Which Way Is Which

Three numbers describe a place in the scene, and you have to know what each one means before you can put anything anywhere.

  • X runs to the right. Larger X is further right.

  • Y runs up. Larger Y is higher. The floor of a scene is usually y = 0.

  • Z runs toward you, out of the screen. Larger Z is nearer the default camera, and negative Z is the direction the camera looks.

That last one catches everybody. Things you want in front of the camera go at negative Z. It is not a quirk of Singe: glTF and Blender use the same arrangement, so a model exported from Blender arrives facing the way Singe expects.

Do not take my word for any of it. Add this line after the nodeSetMesh line, save, and look:

nodeSetPosition(box, 3, 1, 0)

The box jumps to the right and up. nodeSetPosition puts a node at an exact place, and it replaces whatever position the node had. There is a matching nodeMove(node, dx, dy, dz) that shifts a node by an amount instead, along its own axes, so nodeMove(ship, 0, 0, -0.1) drives a ship forward whichever way it happens to be pointing.

Try nodeSetPosition(box, 0, 0, -20) next. The box shrinks into the distance, which is negative Z doing its job. Then try (0, 0, 20): the box vanishes, because you have put it behind the camera.

Two more calls finish the set.

nodeSetRotation(box, 0, 45, 0)
nodeSetScale(box, 0.5)

nodeSetRotation sets the rotation outright in degrees, where nodeRotate adds to it. The three numbers are about X, about Y, and about Z: turning about Y is what a person standing on the floor does when they turn to face a different way, and it is the one you will use most. nodeSetScale makes the node bigger or smaller, either with one number for all three axes or with three for one each.

Take both of those experiments back out before you go on. The rest of the lesson starts from the script as you first typed it.

Your Own Camera

The default view is a courtesy, not a feature. Put a camera in.

local camera = nodeNew()
nodeSetPosition(camera, 0, 2, 7)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(60, 0.1, 100)

Put that under the light, before your onOverlayUpdate, and run it. You are now looking slightly down at the box from two units up and seven back.

A camera is a node like any other. cameraSet tells the engine which node to look out of, and the scene is drawn from that node’s position looking down the node’s own negative Z. Aiming a camera by hand with nodeSetRotation would be miserable, so nodeLookAt does it for you: give it a point in the world and it turns the node to face it.

cameraSetPerspective is the lens. The first number is the field of view in degrees, up and down: how much of the world is squeezed into the height of the window. A small number like 35 is a telephoto lens that flattens everything; a large one like 90 is a wide angle that makes the room look enormous and the corners bulge. 60 is a comfortable default. The other two numbers are the nearest and furthest distances that get drawn, and things outside that range are not drawn at all.

Because the camera is an ordinary node, everything you learned about nodes works on it. Later you will hang a camera underneath a moving car and get a chase camera for nothing.

Turning It with the Arrow Keys

Reading the coordinate system off a page is a poor way to learn it. Moving something around in it is a good one. Replace your onOverlayUpdate with this, and add the two new callbacks and the four variables above it.

local turnLeft  = false
local turnRight = false
local tiltUp    = false
local tiltDown  = false

Those go at the very top of the file, above everything else.

function onInputPressed(what)
    if what == SWITCH_LEFT then
        turnLeft = true
    elseif what == SWITCH_RIGHT then
        turnRight = true
    elseif what == SWITCH_UP then
        tiltUp = true
    elseif what == SWITCH_DOWN then
        tiltDown = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        turnLeft = false
    elseif what == SWITCH_RIGHT then
        turnRight = false
    elseif what == SWITCH_UP then
        tiltUp = false
    elseif what == SWITCH_DOWN then
        tiltDown = false
    end
end


function onOverlayUpdate()
    if turnLeft then
        nodeRotate(box, 0, -1.5, 0)
    end
    if turnRight then
        nodeRotate(box, 0, 1.5, 0)
    end
    if tiltUp then
        nodeRotate(box, -1.5, 0, 0)
    end
    if tiltDown then
        nodeRotate(box, 1.5, 0, 0)
    end

    return OVERLAY_UPDATED
end

onInputPressed and onInputReleased are callbacks, like onOverlayUpdate: you write them, and Singe calls them when a control goes down or comes back up. A press arrives once, not over and over while the key is held, which is why each one sets a variable and the drawing callback does the work. That pattern — press sets a flag, the frame reads the flag — is how you get "while the key is held" out of an engine that only tells you about changes.

The SWITCH_ names come from the engine itself, so nothing has to be loaded to use them. They are not keys, either. They are what a control means, and controls.cfg decides which key, button, or stick direction produces each one. Your arrow keys send SWITCH_LEFT and friends today; a gamepad’s stick sends the same thing, and your script never knows the difference.

The signs are chosen so that each arrow moves the face you are looking at in the direction you pressed. Turning about Y by a positive angle swings that near face to the right, so the left arrow asks for a negative one. If you find that backwards, swap the signs; they are your controls, not the engine’s.

The Overlay Is Still on Top

Add these lines to onOverlayUpdate, above the return.

    local pitch, yaw = nodeGetRotation(box)

    overlayClear()
    overlayPrint(2, 2, "Arrow keys turn the box.")
    overlayPrint(2, 4, "yaw " .. math.floor(yaw) .. "  pitch " .. math.floor(pitch))

Nothing there is new except what it is printed over. overlayPrint is the call from lesson one, counting in character cells, needing no font loaded, and it is drawing on top of a 3D scene without being told anything about it.

That is the arrangement, and it is worth saying plainly: Singe draws the video first, then the 3D scene over it, then the overlay over that. Your score, your lives, your timer, your crosshair, and your subtitles are all overlay work, exactly as they were in part two. A 3D game keeps its score in the corner with the same five lines a 2D game uses.

nodeGetRotation hands back three numbers, the angles about X, Y, and Z, and this line keeps the first two in pitch and yaw. Those are the usual names for them: pitch is the nose going up and down, yaw is turning left and right. math.floor throws away the fraction so the numbers stop flickering.

Watch the yaw as you hold the left arrow. It counts down past -180 and comes back round from 180, because the angles are reported as the smallest turn that gets you there rather than as a running total. If your game needs to know how many times the player has spun, count that yourself.

Try It

  1. Move the camera. Change nodeSetPosition(camera, 0, 2, 7) to (0, 8, 7), then (7, 2, 7), then (0, 0.2, 7). Each time the nodeLookAt keeps the box centered, so you get a different angle on the same scene for one number.

  2. Change the lens. Try cameraSetPerspective(30, 0.1, 100), then (90, 0.1, 100), without moving the camera. A game feels fast with a wide field of view and stately with a narrow one, and this is the cheapest mood knob there is.

  3. Put a second box in. Copy the two lines that made the box, rename the variable to mark, and give it nodeSetPosition(mark, 3, 0, 0) and nodeSetScale(mark, 0.3). Now you have a landmark to judge the first box against. Move it to (0, 3, 0) and (0, 0, -3) in turn and say out loud which axis is which.

  4. Share the mesh. Instead of calling meshBox twice, keep the first one in a variable and hand the same handle to both nodes. Nothing looks different. That is the point: one shape, two places.

  5. Hang the camera on the box. Keep the second box from the last step, or there will be nothing left to move against. Then look up nodeSetParent in the reference and hang the camera under the first box. Hold an arrow key: the camera rides the box’s rotation, so the box sits still and the rest of the scene swings past. That is one line away from a first-person view, and it is also how you find out that a chase camera wants a parent rather than arithmetic.

Break It on Purpose

Mistype the material’s name. Change the nodeSetMesh line to use pain instead of paint:

nodeSetMesh(box, meshBox(2, 2, 2), pain)

Singe stops before the game starts and prints something like:

15:nodeSetMesh:  Argument 3 must be a number.

This is a different shape of error from the one in lesson one, and it comes from the engine rather than from Lua. The number at the front is the line. The name after it is the call that complained. The complaint itself is that the third thing you handed it was not a number.

The reason is worth following, because it explains a whole family of errors. pain is a variable that was never given a value, and in Lua an empty variable is nil — the value that means "nothing here". Handing nil to a call that wants a material handle gives exactly this. When you see "must be a number" from an engine call, look for a misspelled variable name on that line, or for a handle you forgot to keep.

What You Learned

  • sceneEnable(true) turns the 3D layer on, and nothing is drawn in 3D until you call it.

  • A node is a place in the world with a position, a rotation, and a scale. Meshes, lights, and cameras all hang on nodes.

  • A mesh is the shape and a material is the look, and one of each can be shared by any number of nodes.

  • X is right, Y is up, and negative Z is the way the camera looks.

  • nodeSetPosition and nodeSetRotation set a value outright; nodeMove and nodeRotate change it by an amount.

  • Any node can be the camera. nodeLookAt aims it and cameraSet chooses it.

  • The field of view in cameraSetPerspective changes how the scene feels without moving anything.

  • A scene with no light is black, which is the first thing to check when nothing appears.

  • The overlay is still there, still on top, and still where your score goes.

Next Time

A box is a poor dragon. Next lesson loads a real model — one that the engine already unpacked into your work folder, so there is nothing to download and nothing to draw — places it on the floor, and lights it properly. That is lesson twenty-three.

Lesson 23: Models and Light

The finished lesson

Boxes and spheres will take you a long way, but sooner or later the game wants a dragon. A model is a shape somebody else built in a modeling program: hundreds of triangles, its own colors and surfaces, sometimes a skeleton and movements to go with it, all in one file. Loading one is two lines. Getting it to look like anything is light, and light is most of this lesson.

You need no artwork and no downloads. The first time you ever ran Singe it unpacked a folder called Singe into your work folder, and two models are sitting in it: DragonModel.glb, the dragon from the engine’s own title screen, and SingeText.glb, the lettering underneath it. This lesson uses the dragon.

The Scene Around It

A model needs somewhere to stand. Make a folder, make dragon.singe in it, and start with a floor and a camera. If you have done lesson twenty-two none of this is new; if you have not, it is a scene turned on, a flat slab to stand on, and a point to look from.

sceneEnable(true)
sceneSetBackground(10, 12, 20)
sceneSetAmbient(28, 30, 38)

local stone = materialNew()
materialSetColor(stone, 105, 105, 115)
materialSetRoughness(stone, 0.9)

local floor = nodeNew()
nodeSetMesh(floor, meshBox(24, 0.4, 24), stone)
nodeSetPosition(floor, 0, -0.2, 0)

local camera = nodeNew()
nodeSetPosition(camera, 0, 2.6, 9)
nodeLookAt(camera, 0, 1.7, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 200)


function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Run it with Singe -R dragon. A gray slab, seen from slightly above, on a dark blue background. The slab is twenty-four units across and a little under half a unit thick, and sitting it at y = -0.2 puts its top surface exactly at y = 0, which makes everything you place later easy to reason about: the floor is zero.

Loading the Dragon

Two lines.

local dragonModel = modelLoad("Singe/DragonModel.glb")
local dragon      = modelInstance(dragonModel)

Put them after the floor and save. A dragon appears, and it is far too big for the picture — you are looking at its middle.

What Just Happened

The two lines do different jobs, and the difference matters.

modelLoad reads the file, hands the shapes and their surfaces to the graphics card, and keeps the whole thing ready. It is the slow call. Do it once, when the game starts, and never in the middle of play.

modelInstance places a copy in the scene and hands you back a node — an ordinary node, the same kind nodeNew gives you, which you position, rotate, scale, and delete with the calls you already know. Instancing is the cheap call. Load one tree and instance it forty times and you have a wood, with one copy of the shapes on the graphics card and forty places they are drawn.

What comes with the model is everything the file had in it: the shapes, the surfaces and their colors, the way the parts are arranged, any skeleton, and any movements. You do not build materials for a loaded model; it brought its own.

Scale, and the First Thing That Goes Wrong

The dragon is about seven and a half units tall. Your camera is nine units back. That is why it fills the window.

nodeSetScale(dragon, 0.5)

Add that under the modelInstance line. Now it is under four units tall, stands on the floor, and fits the shot.

This is not a detail; it is the commonest first problem with a model, and it has two faces. A model built in centimeters arrives a hundred times too big and you see one enormous surface filling the screen, which usually reads as "my scene is broken" rather than "I am inside the dragon’s neck". A model built in some other unit arrives so small it is a dot, or invisible against the background, and you assume the file failed to load.

The fix is always the same: a scale on the instance’s node. Not on the parts, not in the modeling program if you can help it, but one nodeSetScale on the node modelInstance handed you, chosen by trying a number and looking. 0.01 and 100 are both perfectly ordinary answers.

When you cannot tell how big something is, give yourself a ruler. Put a one-unit box beside it:

local ruler = nodeNew()
nodeSetMesh(ruler, meshBox(1, 1, 1), stone)
nodeSetPosition(ruler, 3, 0.5, 0)

A crate-sized object next to the model tells you in one glance whether the model is a dragon or a mountain. Take the ruler out when you are done.

While you are placing it, turn it to face you:

nodeSetRotation(dragon, 0, -60, 0)

The dragon was modeled facing along positive X, which is to the right, so it starts in profile. Turning it about Y brings it round toward the camera. A model’s "front" is whatever direction the person who built it chose, and finding out means turning it and looking.

Light

Run what you have now. The dragon is there, and it is dreary: a flat, dim shape with no highlights and no shadow. That is because the only light in your scene is the ambient, the faint glow from everywhere that sceneSetAmbient sets.

This is the single most common disappointment in 3D, and it happens to everyone: the model loaded perfectly and the scene is black, or nearly so, because nothing is shining on it. Before you suspect the file, put a light in.

There are three kinds, and each is a node, so you place and aim them with nodeSetPosition and nodeLookAt like anything else.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -6, 9, 7)
nodeLookAt(sun, 0, 1.5, 0)
lightSetColor(sun, 255, 244, 224)
lightSetIntensity(sun, 1.8)
lightSetShadow(sun, true)

LIGHT_DIRECTIONAL is a sun. It is treated as being infinitely far away, so only the direction it shines in counts and everything in the scene gets the same amount of it. Its position is there for nodeLookAt to aim it with. This is the light that gives a scene its main shape, and most scenes want exactly one.

lightSetIntensity is brightness. For a directional light, 1 lights a white surface square-on to it up to white, so 1.8 is a bright day. lightSetColor tints it: a slightly warm white for sun, a cold blue for moonlight, and the reference’s Light section for the rest.

lightSetShadow(sun, true) is what makes the dragon sit on the floor rather than hover above it. Shadows are off by default because each shadow-casting light costs another pass over the whole scene every frame. Turn it on for the one light that matters and leave it off for the others; a small machine will thank you.

local torch = lightNew(LIGHT_POINT)
nodeSetPosition(torch, 3.5, 1.2, 3.0)
lightSetColor(torch, 255, 150, 70)
lightSetIntensity(torch, 14)
lightSetRange(torch, 12)

LIGHT_POINT is a bulb. It sits at a place, shines in every direction, and fades with distance. That fading is why the number is 14 and not 1: the intensity of a point light is its brightness at the light itself, and by the time it has crossed a few units there is not much left. A bulb lighting a room usually wants something in the tens. If a point light seems to do nothing, that is almost always the reason.

lightSetRange says how far it reaches before it stops entirely, which keeps a lamp in one room from faintly lighting the next one and costs nothing to set.

The third kind is LIGHT_SPOT, a cone pointing down the node’s own negative Z, with lightSetCone for the angle of the bright middle and the soft edge: a torch, a headlight, a searchlight. Up to eight lights shine at once, which is more than most scenes need. If you want more, you want fewer.

Run it now. A near-white sun from the left, a warm orange glow from the right, a shadow on the slab, and a dragon with a front and a back.

Materials, at the Level You Need Today

The dragon brought its own materials, and there are three of them: a dark metal, a paler champagne metal, and a pale glass you can see a little way into. Most of its parts are cut from more than one. You do not have to touch any of it, and most of the time you should not.

When you do want to change how a part of a model looks, you make a material the way lesson twenty-two did and put it on the part:

local red = materialNew()
materialSetColor(red, 220, 50, 40)
materialSetRoughness(red, 0.4)
nodeSetMaterial(nodeFind("crest", dragon), red)

nodeFind(name, root) searches a model instance for a part by the name it had in the file and hands back its node, or nil when there is no such name. That is how you reach inside a model: a turret, a wheel, a hand to hang a torch on, or the dragon’s crest.

The crest is one piece of one material, so its node carries the shape itself and the line above repaints it. A part built from several materials is kept as a node with one child per piece, and putting a material on the parent changes nothing you can see. When a nodeSetMaterial appears to do nothing, that is why, and nodeGetChildren will show you what is underneath.

Four numbers describe most surfaces. The color, from materialSetColor. materialSetRoughness, from 0 for a mirror to 1 for chalk. materialSetMetallic, which is 0 for nearly everything — paint, wood, plastic, skin — and 1 for actual metal, with little use for the values between. And materialSetEmissive, which makes a surface glow with its own color for screens, lamps, and hot iron, without lighting anything around it.

One thing to know about metal: a metal surface shows you its reflections rather than a color of its own, so in a scene with nothing to reflect it looks dark and dull. That is why the dragon’s dark metal needs the sun to come alive. The proper fix is a sky (sceneSetSky), which wraps the scene in a panorama that both shows behind everything and lights it; the reference’s "The Look of the Frame" covers it.

Movement the Model Brings with It

Many models carry animations: a walk, a run, an idle, a door opening. They are stored in the file, and playing one is a single call on the instance’s root node.

animationPlay(dragon, "Walk", true)

The second argument is the clip’s name as the file stores it, or its number. true means loop it forever. Two more optional numbers set the speed and the crossfade: animationPlay(hero, "Run", true, 1.2, 0.4) plays the run a fifth faster and blends into it over four tenths of a second, so a walk becomes a run without a snap. animationStop, animationPause, and animationIsPlaying do what their names say.

You cannot run that line yet, and here is the honest reason: the dragon in your Singe folder has no animations in it. It is a model, not a performance. Asking for a clip that is not there stops the game with an error, so never assume — ask:

local clips = modelGetAnimations(dragonModel)

if #clips > 0 then
    animationPlay(dragon, 1, true)
else
    debugPrint("DragonModel.glb carries no animation clips.  The wings are turned by hand.")
end

modelGetAnimations hands back a table of the clip names in the file, in order, so clips[1] is the first one and #clips is how many there are — the table calls from lesson six, on a table the engine filled in. Run it and watch the console: the message appears, because that count is zero.

Get into the habit of that check with any model you did not make yourself. It costs three lines and it turns "the game died on startup" into a sentence in the log.

Moving the Parts Yourself

A model with no animations is not a statue. Its parts are nodes, and nodes turn.

local wingLeft  = nodeFind("wingL", dragon)
local wingRight = nodeFind("wingR", dragon)
function onOverlayUpdate()
    local flap = math.sin(singeGetTicks() / 260) * 22

    nodeSetRotation(wingLeft, flap, 0, 0)
    nodeSetRotation(wingRight, -flap, 0, 0)
    nodeRotate(dragon, 0, 0.25, 0)

    overlayClear()
    overlayPrint(2, 2, "Singe/DragonModel.glb")
    overlayPrint(2, 4, "animation clips in the file: " .. #clips)
    return OVERLAY_UPDATED
end

Save it. The wings beat, the dragon turns slowly on the spot, and the shadow on the floor beats with them.

singeGetTicks is the number of milliseconds since the engine started, so it climbs steadily forever. math.sin takes that climbing number and gives back a value that slides smoothly from -1 to 1 and back, a full beat about every second and a half at this divisor. Multiplying by 22 turns it into an angle of twenty-two degrees each way. Dividing by a bigger number slows the beat; multiplying by a bigger number widens it. That one line is the cheapest animation in existence and it is worth keeping in your pocket.

The wings turn about their own X axis, and they turn around the shoulder rather than the middle of the animal, because whoever built the file put each part’s node where the joint belongs. A model that was not built that way will swing its parts around the model’s center instead, and the fix is to move the part’s node, which the reference’s Node section covers.

Notice that the whole dragon turning does not interfere with the wings turning. Parts hang under the instance root, so rotating the root carries everything with it, and each wing’s own rotation is on top of that. That arrangement — a thing inside a thing inside a thing, each moving in its parent’s world — is what a scene tree is for.

Your Own Models

When you make your own, export from Blender — or Maya, or 3ds Max, or anything else modern — as glTF 2.0 binary, which is a .glb file. That is Blender’s default choice and it is the only model format Singe reads.

The one rule is that the file must be self-contained: the shapes, the pictures on them, and the movements all inside the single .glb. A file that refers to a .bin or a .png sitting next to it is refused, with a message naming what it wanted. Blender’s exporter does the right thing on its default settings.

Not everything you can build survives the trip. The reference’s "Models and Animation" section, in the 3D Scenes chapter, is the list: what is read, what is quietly ignored, and the limits (a skeleton may have up to a hundred and twenty-eight joints, for instance). Read it once before you spend a weekend on a model, not after.

Try It

  1. Kill the lights. Comment out the whole sun block by putting -- at the start of each line, and run it. Then do the same to sceneSetAmbient. Remember what that looks like, because one day it will happen when you did not mean it.

  2. Move the sun. Change nodeLookAt(sun, 0, 1.5, 0) to nodeLookAt(sun, 0, 20, 0) so the sun aims over the dragon’s head. Watch the shadow and the highlights go. Aiming a light is not decoration.

  3. Warm the torch up. Raise the point light’s intensity from 14 to 60 and drop its range to 4. Then move it to (0, 6, 0), above the dragon. A point light is a bulb, and you are choosing where the bulb hangs.

  4. Instance it twice. Call modelInstance(dragonModel) a second time, keep it in another variable, scale it, and put it at (-4, 0, -3). One load, two dragons. Then try loading the model twice instead and understand why you should not.

  5. Find another part. The dragon’s parts are named head, jaw, neck, tail, body, crest, hornL, hornR, wingL, wingR, foreLegL, foreLegR, hindLegL, and hindLegR. Make the tail sway with its own math.sin at a different speed from the wings. Then try nodeFind("wings", dragon) and see what a wrong name does when you hand the nil straight to nodeSetRotation.

Break It on Purpose

Change the file name to Singe/Dragonmodel.glb — one capital letter — and run it. Singe stops before the game starts:

13:modelLoad:  Unable to read Singe/Dragonmodel.glb.

The line, the call, and the complaint, in that order. "Unable to read" means the engine looked and found nothing, which is nearly always one of three things: the name is misspelled, the capitalization is wrong, or the file is not where you said. On Windows the capitalization would have been forgiven and your game would then fail for everyone on Linux, which is a worse bug than this one. Type names exactly.

The same message with a real file name means the file is not where the engine looked. The Singe folder is created in the folder you run the engine from, so if you started Singe from somewhere else, Singe/DragonModel.glb points somewhere else too.

What You Learned

  • modelLoad reads a .glb once; modelInstance places copies of it as often as you like.

  • An instance’s root is an ordinary node: position, rotate, scale, and delete it like any other.

  • A model brings its own shapes and materials with it.

  • A model arrives at the size its author used, which is why one nodeSetScale on the instance is part of placing it.

  • A scene with no light is black or nearly so, and that is the first thing to check when a model looks wrong.

  • A directional light is a sun, a point light is a bulb that fades with distance and needs a much larger intensity, and a spot light is a cone.

  • Shadows are off until lightSetShadow turns them on, and each one costs.

  • nodeFind reaches a part of a model by its name from the file.

  • modelGetAnimations says what a model can play, and asking for a clip that is not there is an error.

  • A model with no animations can still be moved a part at a time.

Next Time

Everything in this scene moves because you told it to, frame by frame. Next lesson hands that job to a physics engine: crates that fall, roll, stack, and knock each other over without you writing a line of arithmetic — and the harder question of when you should let it. That is lesson twenty-four.

Lesson 24: Physics

The finished lesson

Up to now every moving thing in your games has moved because you did the arithmetic. A number went up by two each frame; if it went past an edge you turned it round. That is the honest way to make a game move, and most games are made of it.

This lesson hands the arithmetic to somebody else. A physics engine simulates the world — gravity, falling, sliding, stacking, bouncing, rolling, and things hitting each other — and moves your nodes for you. By the end you will have a tray of crates and a cannon that knocks them over. The last section is about when not to do any of this, and it is the part to read twice.

What It Does, and What It Does Not

Give a node a body and the simulation takes charge of it. From then on it falls under gravity, lands on whatever is beneath it, tips when it is hit off center, rests in a stack, slides to a stop, and the node follows wherever the simulation puts it. You stop setting its position. That is the deal: you hand over the position and rotation of that node, and in exchange you get behavior you did not have to write.

What it does not do is anything about your game. It does not know what a score is, or that the red crate is the one worth points, or that falling off the edge means a life. It does not animate a character walking, it does not know how a jump should feel, and it will not make an object move in a way you can predict exactly. Physics is a machine for producing plausible mess.

Units are meters, kilograms, and seconds. Gravity is 0, -9.81, 0 unless you say otherwise, which is Earth’s, downward, in meters per second squared. A crate that is one unit wide is one meter wide, and it falls like one. If your scene is built at some other scale, everything will look like it is falling through syrup or through a cartoon, and the fix is to build at meters.

A Floor and One Crate

Make a folder, make crates.singe, and type this in. It is a scene, a slab, a crate above the slab, and three lines of physics.

sceneEnable(true)
sceneSetBackground(16, 18, 26)
sceneSetAmbient(40, 42, 50)

local stone = materialNew()
materialSetColor(stone, 110, 110, 120)
materialSetRoughness(stone, 0.9)

local wood = materialNew()
materialSetColor(wood, 190, 140, 80)
materialSetRoughness(wood, 0.8)

local floor = nodeNew()
nodeSetMesh(floor, meshBox(16, 0.4, 16), stone)
nodeSetPosition(floor, 0, -0.2, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

local crate = nodeNew()
nodeSetMesh(crate, meshBox(0.8, 0.8, 0.8), wood)
nodeSetPosition(crate, 0.3, 4, 0)
nodeSetRotation(crate, 20, 0, 15)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
bodySetMass(crate, 4)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -5, 9, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 1.7)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 4, 11)
nodeLookAt(camera, 0, 1, 0)
cameraSet(camera)


function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Run it with Singe -R crates. The crate falls from four meters up, lands on a corner because you tilted it, rocks over onto a face, and stops. Press F5 to run it again and watch it once more.

Nothing in onOverlayUpdate moves anything. The two bodyNew calls did all of it.

What Just Happened

bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

bodyNew gives a node a body. It takes the node, what kind of body it is, what shape the simulation should use for it, and the sizes of that shape.

There are three kinds, and choosing the right one is most of the skill.

  • BODY_STATIC never moves. It is placed where the node is when you make the body, and there it stays forever. Floors, walls, the ground, the cabinet, the level. Moving its node afterwards does not move the body, which is a trap worth remembering: static means static.

  • BODY_DYNAMIC is moved by the simulation. It falls, bounces, slides, gets pushed, and drags its node along with it. This is a crate, a barrel, a ball, a piece of debris.

  • BODY_KINEMATIC goes where you put its node, and shoves dynamic bodies out of its way without ever being pushed itself. A moving platform, a paddle, a door on a track, a character’s swinging fist. It is the bridge between your arithmetic and the simulation: you drive it, it drives them.

The shape is not the mesh. It is a rough stand-in the simulation uses because it can answer questions about a box far faster than about nine hundred triangles. SHAPE_BOX takes a width, a height, and a depth; SHAPE_SPHERE takes a radius; SHAPE_CAPSULE and SHAPE_CYLINDER take a radius and a height. There is SHAPE_HULL, which shrink-wraps whatever mesh is under the node — the usual answer for a model — and SHAPE_MESH, the exact triangles, which static scenery may use and a falling object may not.

The sizes are yours to get right. Nothing checks that the body you described matches the mesh you drew, and a crate drawn at 0.8 with a body made at 2 will float above the floor and knock things over from a distance. When something behaves as if it were a different size, it is.

bodySetMass(crate, 4)

A dynamic body’s mass comes from its shape at the density of water, which makes things much heavier than you expect: a box the size of a door weighs about a hundred and forty kilograms, and nothing you can throw at it will move it. Set the mass of anything meant to feel light. Four kilograms is a crate you could pick up.

Mass matters because forces are shared out by it. The same shove moves a light thing further, and an impulse of mass times speed is what it takes to set something moving at that speed. Tune the mass first and the forces afterwards, or you will chase your own tail.

Making Things Move

Three calls push a dynamic body around, and they are not interchangeable.

bodySetVelocity(node, x, y, z) says "you are now traveling at this speed", replacing whatever it was doing. This is a serve, a launch, a spawn with some speed already on it.

bodyApplyImpulse(node, ix, iy, iz) is a hit: a kick, an explosion, a bat meeting a ball. It adds to what the body was already doing. Give it a point in the world as three more numbers and it hits there instead of at the middle, so a crate struck near the top tips over rather than sliding.

bodyApplyForce(node, fx, fy, fz) is a push that lasts: a rocket, a fan, a conveyor. A force applied for one frame does almost nothing, which surprises people who expected an impulse.

Gravity itself is physicsSetGravity(x, y, z) and it is world-wide. The moon is physicsSetGravity(0, -1.62, 0), space is all zeroes, and a game with gravity sideways is one line away.

Two more settings finish the feel of an object. bodySetBounce(node, amount) runs from 0, which stops dead, to 1, which comes back with everything it arrived with; the default is a barely-there 0.1. bodySetFriction(node, amount) is 0 for ice and 0.5 by default. Both combine between the two things touching, so an icy floor needs the low number on the floor, not on everything that walks across it.

Knowing When Things Touch

function onCollision(nodeA, nodeB, x, y, z, speed)
    if speed > 4 then
        knocks = knocks + 1
    end
end

knocks there is a variable of your own, waiting at the top of the file with local knocks = 0, and the toy below prints it.

onCollision is a callback, like onOverlayUpdate: you write it, the engine calls it. It arrives once for each new contact — two bodies that stay touching do not report again — with both nodes, the point in the world where they met, and how fast they met. The speed is what lets a bump and a crash sound different, and it is why the test above ignores the gentle settling of a stack.

The other half of the pair is onTrigger. Make a body a trigger with bodySetTrigger(node, true) and it stops pushing things: it becomes a region that reports what enters and leaves it through onTrigger(trigger, other, entered). A finish line, a doorway, a pit, a pickup. It is the 3D descendant of the collision checks from lesson eleven, and for anything shaped like "did the player reach here" it is the call you want rather than a solid body.

The Toy

Now the whole thing. Start from the script above and change it into this: a tray with four walls, six crates in a pyramid, and a steel ball you can aim and fire. The pieces are all ones you have met.

Everything the new code remembers goes at the top of the file, above the scene:

local crates     = {}
local balls      = {}
local aimX       = 0
local aimLeft    = false
local aimRight   = false
local knocks     = 0
local showShapes = false

Two more shared handles go with the materials: a polished metal for the ball and the aiming marker, and one crate mesh for all six crates.

local steel = materialNew()
materialSetColor(steel, 200, 205, 215)
materialSetMetallic(steel, 1)
materialSetRoughness(steel, 0.25)

local crateMesh = meshBox(0.8, 0.8, 0.8)

The tray’s walls are four static boxes, made in a loop from a table of placements, which is lesson six doing honest work:

local wallMesh = meshBox(16, 1, 0.4)

for _, side in ipairs({ { 0, -8, 0 }, { 0, 8, 0 }, { -8, 0, 90 }, { 8, 0, 90 } }) do
    local wall = nodeNew()
    nodeSetMesh(wall, wallMesh, stone)
    nodeSetPosition(wall, side[1], 0.5, side[2])
    nodeSetRotation(wall, 0, side[3], 0)
    bodyNew(wall, BODY_STATIC, SHAPE_BOX, 16, 1, 0.4)
end

Each entry is an X, a Z, and a turn about Y. Two walls lie across the back and front; two are turned ninety degrees to make the sides. One mesh does for all four, and the body is made after the node is placed and turned, because a static body takes the node’s position and rotation at the moment it is made.

The crates come from a function, so that six of them is six lines:

local function crateAt(x, y)
    local crate = nodeNew()

    nodeSetMesh(crate, crateMesh, wood)
    nodeSetPosition(crate, x, y, -2)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
    bodySetMass(crate, 4)
    crates[#crates + 1] = crate
end

It keeps every crate it makes in the crates table, which is how the drawing callback can ask all of them a question later. Six calls build the pyramid, three on the floor, two on those, and one on top:

crateAt(-0.9, 0.4)
crateAt(0, 0.4)
crateAt(0.9, 0.4)
crateAt(-0.45, 1.25)
crateAt(0.45, 1.25)
crateAt(0, 2.1)

The upper rows sit a finger’s width above the ones below and drop into place the moment the game starts. Leaving a small gap is easier than stacking exactly, and it is kinder to the simulation than handing it a pile that is already pressed together.

Firing makes a new ball each time:

local function fire()
    local ball = nodeNew()

    nodeSetMesh(ball, meshSphere(0.35, 24), steel)
    nodeSetPosition(ball, aimX, 1.2, 6)
    bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.35)
    bodySetMass(ball, 3)
    bodySetBounce(ball, 0.3)
    bodySetVelocity(ball, 0, 2, -14)
    balls[#balls + 1] = ball
    if #balls > 5 then
        nodeDelete(balls[1])
        table.remove(balls, 1)
    end
end

Look at the order. The node is made, given a shape to draw, and placed, and only then given a body. A dynamic body starts where its node is, and after that the traffic runs the other way: the body moves the node. Setting the position of a dynamic node yourself afterwards fights the simulation and the simulation wins. When something must be moved, give it a velocity, hit it with an impulse, or do what this does — make a new one and let the old one go.

Letting the old one go is nodeDelete, which frees the node, everything under it, and the body that was riding on it. Without those three lines every shot would stay in the world forever, and a few hundred balls later the simulation would be doing a great deal of work on things nobody can see. Cleaning up is part of using physics.

The controls and the display are the rest:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        fire()
    elseif what == SWITCH_BUTTON3 then
        showShapes = not showShapes
        if showShapes then
            physicsSetDebug(DEBUG_SHAPES + DEBUG_CONTACTS)
        else
            physicsSetDebug(DEBUG_NONE)
        end
    elseif what == SWITCH_LEFT then
        aimLeft = true
    elseif what == SWITCH_RIGHT then
        aimRight = true
    end
end

Space fires, shift turns the physics view on and off, and the arrows hold down to slide the launch point. A flat metal plate with no body on it, moved each frame to aimX, shows where the next ball will come from. The full script, with the release callback and the rest of the setup, is 24-physics.singe in the learn folder.

physicsSetDebug is the most useful call in this lesson. It draws what the simulation actually holds — the real shapes in wireframe, and a red cross wherever two bodies touched this step — over the top of your scene. The first time a crate hovers a hand’s width above the floor, or falls through it, or knocks something over from two meters away, turn this on and the answer will be on the screen. Add DEBUG_STATIC to see the floor and walls as well. It costs nothing while it is off.

Finally, the counting:

function onOverlayUpdate()
    local over    = 0
    local settled = true

    if aimLeft then
        aimX = math.max(aimX - 0.08, -5)
    end
    if aimRight then
        aimX = math.min(aimX + 0.08, 5)
    end
    nodeSetPosition(marker, aimX, 0.05, 6)

    for _, crate in ipairs(crates) do
        local pitch, _, roll = nodeGetRotation(crate)

        if math.abs(pitch) > 30 or math.abs(roll) > 30 then
            over = over + 1
        end
        if not bodyIsResting(crate) then
            settled = false
        end
    end

    overlayClear()
    overlayPrint(2, 2, "Arrows aim.  Space fires.  Shift shows the shapes.")
    overlayPrint(2, 4, "knocked over " .. over .. " of " .. #crates .. "   hard hits " .. knocks)
    if settled then
        overlayPrint(2, 6, "everything has settled")
    end
    return OVERLAY_UPDATED
end

A crate is counted as knocked over when it is leaning more than thirty degrees, which is a game rule written in one line of arithmetic on top of whatever the simulation did. nodeGetRotation gives three angles and this wants the first and the third, so the middle one is caught in a variable called _. That underscore is an ordinary name with nothing special about it, used by convention to say "I am ignoring this one".

bodyIsResting says whether the simulation has put a body to sleep because it stopped moving. That is how you know a shot is over: not a timer, not a guess, but every crate asleep. A bowling game scores its frame exactly there.

When Not to Use It

Physics is the most tempting tool in any engine and the one that wastes the most weekends. Three things are true about it, and none of them are the engine’s fault.

It is expensive. Every dynamic body is work every step, sixty times a second, whether anybody is looking at it or not. Forty crates is fine. Four thousand is not, and on a small machine four hundred is not.

It is unpredictable. Run your toy twice and the crates land differently. That is what makes it look alive, and it is also why a game cannot rely on it for anything that must come out the same each time. A door that must open, a platform that must arrive, a jump the player must be able to make: those are arithmetic, or a tween, or a kinematic body on a path you wrote. Never leave a thing the player must do to a simulation that can drop it behind a crate.

It is hard to tune. The mass, the friction, the bounce, the shape, and the size all pull on each other, and "it feels wrong" rarely has one cause. Every hour you spend making a physics crate feel good is an hour you did not spend on the game.

So reach for it when the mess is the point: things toppling, debris flying, a pile settling, a ball rattling round a room, a vehicle rolling over rough ground, a ragdoll flopping down a staircase. Nobody can write that by hand and nobody can tell you exactly how it should look.

Do not reach for it when you know what should happen. A bullet that flies straight is two lines from lesson two. A platform that goes up and down is math.sin. A player that walks and jumps the way players expect wants a character controller (playerNew, in the reference), because a person is not a box and never behaves like one. An enemy that patrols wants a path. A menu that slides in wants a tween.

The rule that serves best: use physics for the things the player watches, and arithmetic for the things the player does.

Try It

  1. Change the world. Add physicsSetGravity(0, -1.62, 0) near the top and fire again. Then try 0, -30, 0. The same crates, a different planet, one line.

  2. Change the ball. Make the ball ten times heavier with bodySetMass(ball, 30), then ten times lighter with 0.3, keeping the speed the same. Then put the mass back and change the -14 instead. Two ways to hit harder, and they do not feel the same.

  3. Make the crates ice. Add bodySetFriction(crate, 0.02) in crateAt, and add a line giving the floor a low friction too. Watch the pile refuse to stand up in the first place.

  4. Wrong the shape on purpose. In crateAt, change the body’s sizes to 2, 2, 2 while the mesh stays 0.8. Run it, see the crates hover and shove each other from nowhere, then press shift and watch the debug view explain it in one picture.

  5. Score it properly. Use bodyIsResting on every crate to notice when the shot has finished, and only then count how many are over and add that to a score. That is the scoring half of a bowling game.

Break It on Purpose

Add a line under the floor’s bodyNew making the floor heavy, which is a reasonable thing to think you want:

bodySetMass(floor, 200)

Singe stops the game with something like:

32:bodySetMass:  Node 1 is not a dynamic body, or the mass is not positive.

The first number is the line in your own file, so yours will differ.

The number after Node is the node’s handle, the number nodeNew handed back. The complaint is exact: mass belongs to things the simulation moves, and a static body is not moved by anything, so it has no mass to set. Asking is a sign that the body is the wrong type for what you had in mind — and if you truly want a heavy floor that can be shifted, what you want is a dynamic body with a large mass, or a kinematic one you move yourself.

The same message appears for a mass of 0, which people write meaning "weightless". Weightless is not a mass. It is a world with no gravity, or playerSetGravityScale on a character controller.

What You Learned

  • A body attaches to a node, and from then on the node and the body are one thing.

  • Static never moves, dynamic is moved by the simulation, and kinematic is moved by you and pushes everything else aside.

  • The collision shape is a stand-in for the mesh, and you are responsible for its sizes matching what you drew.

  • Mass defaults to the shape’s volume at the density of water, so set it on anything meant to feel light.

  • bodySetVelocity replaces a body’s motion, bodyApplyImpulse is a hit, and bodyApplyForce is a push that lasts.

  • Do not set the position of a dynamic node; delete it and make a new one when you must start it over.

  • onCollision reports each new contact with its point and its speed, and a trigger body reports arrivals and departures through onTrigger.

  • bodyIsResting tells you when everything has stopped, which is usually when a turn is over.

  • physicsSetDebug draws the simulation’s own view, and it answers most physics questions faster than reading code does.

  • Physics is expensive, unrepeatable, and fiddly. Use it for the mess, not for the things the game depends on.

Next Time

Crates falling is one kind of spectacle. The other kind is made of a thousand tiny things that live for half a second: sparks, smoke, fire, rain, and dust. Next lesson is emitters, and it ends with an explosion. That is lesson twenty-five.

Lesson 25: Particles

The finished lesson

By the end of this lesson a ship will fly across the bottom of the screen trailing fire from its engine, and a button will blow it into a hundred and forty spinning sparks that bounce off the floor. You will not write a single line that draws a spark.

That is the whole idea of this lesson. You describe the fire; the engine makes it.

Why You Do Not Draw the Sparks

You could do it the other way. You know enough: a table of sparks from lesson six, each with an x, a y, and a speed; a loop in onOverlayUpdate that moves every one of them, fades it, drops it when it dies, and draws it. It works. It is also two hundred lines of bookkeeping that every game rewrites, and it runs in Lua, one spark at a time, sixty times a second.

Singe does it for you instead. You hand it a recipe — how many sparks a second, how long each one lives, how fast and which way they set off, what pulls on them, what they look like, and what color they fade to — and it keeps the sparks itself. The thing that holds the recipe and runs it is called an emitter.

An emitter is not a picture and it is not an object in your game. It is a description of a kind of fire, kept somewhere you can point at, and it can make that fire anywhere you ask.

Start with Something That Moves

Particles are more convincing when they come off something, so start with a ship. Make a folder, copy the book’s art folder into it, and put this in particles.singe:

dofile("Singe/Framework.singe")

local SHIP_WIDTH  = 32
local SHIP_HEIGHT = 24
local SHIP_SPEED  = 120

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

local shipX = (overlayGetWidth() - SHIP_WIDTH) / 2
local shipY = overlayGetHeight() - 56

local movingLeft  = false
local movingRight = false
local lastTicks   = singeGetTicks()


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    local now     = singeGetTicks()
    local seconds = (now - lastTicks) / 1000
    lastTicks     = now

    if movingLeft then
        shipX = shipX - SHIP_SPEED * seconds
    end
    if movingRight then
        shipX = shipX + SHIP_SPEED * seconds
    end

    overlayClear()
    spriteDraw(shipSprite, shipX, shipY)
    return OVERLAY_UPDATED
end

Run it with Singe -R particles and steer with the left and right arrow keys. There is nothing new here: a sprite from lesson nine, the switches from lesson three, and singeGetTicks so the ship moves at the same speed whatever the frame rate is.

The one line worth pointing at is dofile("Singe/Framework.singe"). That is what defines DIR, the folder your script is in, so DIR .. "art/spaceship.png" finds the picture no matter which folder you started Singe from.

Give It an Exhaust

Now the fire. Add this above the callbacks, after the ship’s variables:

local exhaust = emitterNew()
emitterSetBlend(exhaust, PARTICLE_ADD)
emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)
emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)
emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)
emitterSetMax(exhaust, 120)
emitterStart(exhaust)

And two lines inside onOverlayUpdate. The first goes just before overlayClear, the second just after spriteDraw:

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)
    emitterDraw(exhaust)

Save. The ship now sits on a short tongue of yellow flame, and the flame goes with it when you steer.

Blow It Up

An exhaust runs forever. An explosion happens once, which the engine treats as a different kind of request from the same emitter.

Two more files and one more number first. These go beside the ship sprite at the top:

local sparkSprite = spriteLoad(DIR .. "art/star.png")
local boomSound   = soundLoad(DIR .. "art/boom.wav")

and this goes beside shipX and shipY, twenty units up from the bottom of the screen:

local ground = overlayGetHeight() - 20

Now the second recipe, under the first:

local boom = emitterNew()
emitterSetTexture(boom, sparkSprite)
emitterSetBlend(boom, PARTICLE_ADD)
emitterSetLife(boom, 0.4, 1.1)
emitterSetSpeed(boom, 40, 220)
emitterSetSpread(boom, 180)
emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)
emitterSetSize(boom, 10, 2, 0.4)
emitterSetSpin(boom, -240, 240)
emitterSetColor(boom, 255, 255, 220, 255, 255, 70, 20, 0)
emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)
emitterSetMax(boom, 400)

Notice that emitterStart is missing. This one is never going to stream.

Add a function to set it off, above onInputPressed:

function explode()
    if not flying then
        return
    end
    flying = false
    emitterStop(exhaust)
    emitterSetPosition(boom, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT / 2)
    emitterBurst(boom, 140)
    soundPlay(boomSound)
    timerAfter(RESPAWN_MS, function()
        flying = true
        emitterStart(exhaust)
    end)
end

That needs three more things: local RESPAWN_MS = 1400 with the other constants, local flying = true with the other variables, and a branch in onInputPressed:

    elseif what == SWITCH_BUTTON1 then
        explode()

Finally, the ship should not be there while it is in pieces. Wrap the steering and the drawing in onOverlayUpdate in if flying then …​ end, and add emitterDraw(boom) beside the other draw call. The finished script is learn/25-particles.singe.

Press the space bar — button one by default — and the ship comes apart into a cloud of tumbling stars that arc down, strike the floor, and bounce.

What Just Happened

There are a great many new calls in this lesson, and they are all the same shape: the emitter first, then the thing you are setting. Take them in groups.

local exhaust = emitterNew()

Makes an emitter and hands back a handle: a number the engine uses to find it again, exactly like the number spriteLoad gives you. With no argument you get a two dimensional emitter, which lives in overlay coordinates and is drawn from onOverlayUpdate. Give emitterNew a node instead and you get a three dimensional one, which lives in the scene and draws itself; everything else in this lesson is the same for both.

A new emitter already has a complete recipe — fifty particles a second, white, a second or two of life, drifting up the screen — so every call after this one is you disagreeing with a default. The reference’s entry for emitterNew lists them all.

emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)

Ninety particles a second, each living between fifteen hundredths and four tenths of a second. Those two numbers together decide how much fire there is: ninety a second that live for a third of a second means about thirty on screen at any moment.

Anywhere an emitter call takes a smallest and a largest, every particle gets its own value picked at random between the two. That is where the raggedness comes from. A fire where every flame lived exactly as long as every other would look like a machine.

emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)

Which way they set off, how wide the fan is, and how fast. Overlay Y grows downward, as it has since lesson one, so (0, 1) is down the screen — out of the back of a ship that points up. emitterSetSpread is half the angle of the fan: twelve degrees is a tight jet, ninety opens it to half the circle, and one hundred and eighty is every direction at once.

emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)

These two are why the flame looks like a flame. A particle does not have a size and a color; it has a size and a color at birth and another at death, and it slides evenly from one to the other over whatever life it drew. So each spark starts seven overlay units across and pale yellow, and ends one unit across and orange-red with an alpha of zero, which is invisible. It shrinks and fades out because you said where it ends, not because anything faded it.

emitterSetColor takes eight numbers, which is a lot to read: red, green, blue, and alpha at the start, then red, green, blue, and alpha at the end.

emitterSetBlend(exhaust, PARTICLE_ADD)

How a particle combines with what is behind it. PARTICLE_ALPHA is normal painting and is the default: use it for smoke, dust, rain, and rubble. PARTICLE_ADD adds its light to the picture instead, so two sparks on top of each other are brighter than one and nothing ever gets darker. Fire, sparks, lasers, and magic are additive. Smoke is not, and smoke drawn additively looks like steam lit from inside.

emitterSetMax(exhaust, 120)
emitterStart(exhaust)

emitterSetMax is the size of the pool: how many of this emitter’s particles may exist at once. When the pool is full nothing new is born until something dies. Ninety a second living up to four tenths of a second needs about thirty-six, so a hundred and twenty is comfortable. Set it before you start, because changing it later throws away every live particle.

emitterStart opens the tap. From then on the emitter makes particles every frame, whether or not you draw it, until emitterStop closes it again. Note what emitterStop does not do: it stops new particles, and the ones already alive finish their lives and fade out normally. That is why the exhaust trails away instead of vanishing when the ship explodes. If you want them gone this instant, emitterClear kills them.

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)

This is how an emitter follows something. A two dimensional emitter is born at one point, and that point is wherever you last put it, so you set it every frame from whatever is moving: a sprite’s position, a physics body’s node, the mouse. New particles appear at the new place; the ones already in the air stay where they were born, which is exactly right for exhaust, because exhaust is left behind.

A three dimensional emitter is made on a node and follows that node on its own, with no call in your update at all. And when you do want the whole cloud to travel with the thing — a shield, an aura, a thruster plume seen from outside — emitterSetLocal switches that on.

    emitterDraw(exhaust)

Two dimensional emitters are drawn when you ask, once per frame, from onOverlayUpdate. The order of your emitterDraw calls is the order they stack in. Forgetting this call is the mistake everyone makes once: the emitter keeps running, keeps spending its pool, and shows nothing.

Now the explosion’s own calls.

emitterSetTexture(boom, sparkSprite)

Without a texture every particle is a soft round blob the engine draws itself, which is what the exhaust uses and is right for flame. With one, each particle wears that picture — here star.png, eight pixels by eight. The emitter takes its own copy of the pixels, so you may unload the sprite afterward and the particles keep working.

emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)

Gravity is a steady pull, in overlay units per second per second, and it is positive downward for the same reason the exhaust fires with a positive Y. Drag is the opposite: it takes speed away, a little every frame, so the sparks fly out hard and then hang. Sparks with gravity and no drag rain straight down like a firework; drag is what makes them look like they are moving through air.

emitterSetSpin(boom, -240, 240)
emitterSetSize(boom, 10, 2, 0.4)

Spin is degrees a second, and a range that crosses zero gives you some spinning each way. It shows on a texture and does nothing at all to the built-in blob, which is round.

The third number on emitterSetSize is variation. It scales both sizes of each particle by one random factor — here anywhere from six tenths to one and four tenths — so the sparks are not all the same star at the same size.

emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)

COLLIDE_FLOOR puts a flat, invisible floor across the world at the height you name, and particles bounce off it. The two numbers before it are how much speed survives a bounce and how much sideways speed is scrubbed off. It costs nothing, because it is one comparison per particle, and it makes debris look like it landed somewhere rather than falling through the world. In a three dimensional game COLLIDE_SCENE bounces particles off the real geometry instead, which costs a great deal more.

A trail keeps the last few places a particle has been and draws a fading ribbon through them. Four positions and two units wide turns each star into a short streak.

    emitterBurst(boom, 140)

And this is the other way to make particles. emitterStart is a tap; emitterBurst is a handful thrown at once. The emitter does not have to be streaming, and this one never is. Everything else — the recipe, the pool, the position — works the same.

That distinction is worth keeping. Anything continuous is a stream you start and stop: exhaust, smoke, rain, a torch, a waterfall. Anything that happens at a moment is a burst: an explosion, a splash, a footfall in dust, a bullet hit, a muzzle flash. Plenty of effects are both, from one emitter or two: a shell bursts and then smokes.

How Many Is Too Many

The honest answer is that particles are cheap to move and expensive to look at.

Moving ten thousand particles is arithmetic, and a computer that can run a game at all can do it without noticing. What costs is the drawing, and what the drawing costs is roughly the number of screen pixels the particles cover, counting overlaps. Two hundred sparks eight pixels across cover less of the screen than one smoke puff that fills it. That is the rule: small and many is nearly free, and big and overlapping is not.

Additive blending is the expensive kind, because nothing it draws can be skipped — every layer adds to what is underneath, so the machine paints all of them. A dozen full-screen additive flashes on top of each other will slow a Raspberry Pi 4 to a crawl while ten thousand tiny bouncing sparks do not trouble it.

So: a few thousand small particles is nothing to worry about. Before you go past that, put the count on screen and watch it.

    overlayPrint(2, 4, "Particles alive: " .. (emitterGetCount(exhaust) + emitterGetCount(boom)))

emitterGetCount is how you size a pool honestly rather than by guessing. If the number sits at exactly your emitterSetMax, your pool is full and the engine is quietly refusing to make particles you asked for. If it never gets near, you are reserving memory for nothing.

Try It

  1. Turn the exhaust into smoke. Change emitterSetBlend(exhaust, PARTICLE_ADD) to PARTICLE_ALPHA, set the color to gray fading to transparent gray, and make it grow instead of shrink with emitterSetSize(exhaust, 3, 14). Three lines have made a different machine.

  2. Take the drag off the explosion. Delete the emitterSetDrag line and compare. Then put drag back and take the gravity off instead. One of those looks like fireworks and the other looks like an accident.

  3. Widen the exhaust. Set emitterSetSpread(exhaust, 180). The ship stops looking like it has an engine. Spread is doing more work than you think.

  4. Burst a thousand. Change emitterBurst(boom, 140) to emitterBurst(boom, 1000) and watch the count on screen. It will not reach a thousand. Work out from emitterSetMax why not, then raise the pool and make the sparks four times bigger, and see what that does to the frame rate.

  5. Fire the explosion where the ship is not. Put emitterSetPosition(boom, 40, 60) in explode instead of the ship’s position. An emitter is a description of a fire, not a thing that lives anywhere, and you can burst the same one in ten places in the same frame.

Break It on Purpose

The constants — PARTICLE_ADD, COLLIDE_FLOOR, OVERLAY_UPDATED — are names Singe has given to numbers. Get one slightly wrong and Lua does not complain, because in Lua a name that was never given a value is not an error: it is nil, the value that means "nothing here".

Change the exhaust’s blend line to a name that sounds just as likely:

emitterSetBlend(exhaust, PARTICLE_ADDITIVE)

Singe stops before the game starts, naming the line that call is on in your file:

22:emitterSetBlend:  Argument 2 must be a number.

This error has a different shape from the Lua errors in lesson eight, because it comes from the engine rather than from Lua. It is the line number, then the call that objected, then the complaint. Argument two of emitterSetBlend is the blend mode, and what arrived was nil, because PARTICLE_ADDITIVE is not a name anything ever defined.

"Must be a number" nearly always means this: a misspelled constant, or a variable you thought you had set. The fix is to check the name against the reference, which spells it PARTICLE_ADD.

What You Learned

  • An emitter holds a recipe for a kind of particle and keeps the particles itself, so your script never draws one.

  • emitterNew with no argument makes a two dimensional emitter in overlay coordinates; with a node it makes a three dimensional one in the scene.

  • Every emitter starts with a complete recipe, and each emitterSet…​ call changes one part of it.

  • Anywhere a call takes a smallest and a largest, every particle draws its own value at random between them, and that is where the raggedness comes from.

  • Size and color are set at birth and at death, and the particle slides from one to the other over its life.

  • emitterStart streams until emitterStop; emitterBurst throws a handful at once. Continuous effects are streams, momentary ones are bursts.

  • emitterStop lets the live particles finish; emitterClear kills them now.

  • A two dimensional emitter is moved with emitterSetPosition every frame and drawn with emitterDraw every frame. A three dimensional one follows its node and draws itself.

  • Particles cost what they cover on screen, not what they cost to move, and additive blending is the expensive kind.

  • emitterSetMax caps the pool, and emitterGetCount tells you whether you guessed the size right.

Next Time

The explosion moved a hundred and forty things without being told where any of them should go, but they were sparks, and sparks do not care what they run into. Lesson twenty-six is about something that does: a character who has to get from here to there, and a wall in the way.

Lesson 26: Characters That Move Themselves

The finished lesson

In this lesson you build a room with a wall across the middle of it and put two characters in it. One of them you send to a corner with a button press. The other picks somewhere at random, walks there, and when it arrives picks somewhere else, forever.

Neither of them walks into the wall, and you never write a line that says how to go round it. That is new. Every lesson up to this one has moved things where you told them to go. This is the first lesson where the game works out something for itself.

The Problem with Walking Toward Something

Here is the obvious way to make a character walk to a point, and it is the way everybody writes first. Take the target, subtract where you are, and step a little along the line between them, every frame, until you get there.

It works beautifully in an empty room.

Put a wall in the room and it stops working, and it stops working in a way that looks stupid rather than broken: the character marches into the wall and stands there grinding against it, a meter from a doorway it cannot see, because nothing in "step toward the target" has any idea that the world has shapes in it.

You cannot patch your way out of this. Turning aside when you touch a wall gets your character stuck in the first corner it finds. Nor is it enough to know where the walls are, because the route round a wall may be long, may go away from the target before it comes back, and may not exist at all.

What is needed is a way to ask a real question: how do I walk from here to there? Answering it needs something that knows the shape of the floor.

What a Navigation Mesh Is

Stand in a room and look at the floor. Some of it you could walk on. Some of it you could not: it is under a table, inside a wall, off the edge of a balcony, or up a step too high to climb. Now imagine painting the part you could walk on, and throwing away everything else — the walls, the furniture, the ceiling, the scenery. What you are left with is a flat shape, or several, with holes in it where the pillars are and gaps where the drops are.

That painted shape is a navigation mesh, and it is all a character needs in order to plan a walk. It is not the level. It is a simplified map of the parts of the level a person can stand on, and because it is simple, questions about it can be answered quickly.

Singe makes it for you from the level you already have. You say how big the characters are, hand it the geometry, and it works out what is walkable: floors and ramps within the slope you allow, steps no higher than you allow, with a margin trimmed off around every wall and every drop so a character with width does not clip a corner. That is called baking, it happens once, and the result can be saved to a file and loaded next time.

A Room with a Wall in It

Make a folder called navigation and start a file called navigation.singe inside it. This part is a three dimensional scene, which is lesson twenty-two’s subject: a scene is a world drawn in three dimensions, and everything in it hangs on a node, which is a position, a rotation, and a scale that you can attach a shape to.

If you skipped that lesson you can still follow this one. Take the next two blocks as "a gray floor twenty units square, three tan walls standing on it, and a camera looking down at the lot".

local ROOM         = 20
local WALL_HEIGHT  = 2
local AGENT_RADIUS = 0.4
local AGENT_HEIGHT = 1.8
local WALK_SPEED   = 2.2

sceneEnable(true)
sceneSetBackground(28, 32, 42, 255)
sceneSetAmbient(80, 86, 100)

local floorLook = materialNew()
materialSetColor(floorLook, 96, 102, 110)
materialSetRoughness(floorLook, 0.9)

local wallLook = materialNew()
materialSetColor(wallLook, 150, 128, 104)
materialSetRoughness(wallLook, 0.8)

local ground = nodeNew()
nodeSetMesh(ground, meshPlane(ROOM, ROOM), floorLook)

local wallMesh = meshBox(1, WALL_HEIGHT, 1)
local walls    = {}


function addWall(x, z, width, depth)
    local wall = nodeNew()
    nodeSetMesh(wall, wallMesh, wallLook)
    nodeSetScale(wall, width, 1, depth)
    nodeSetPosition(wall, x, WALL_HEIGHT / 2, z)
    walls[#walls + 1] = wall
end


addWall(-4, 0, 12, 0.6)
addWall(7.5, 0, 5, 0.6)
addWall(-3, -6, 0.6, 8)

The units here are meters, because that is what Singe’s three dimensional world assumes. The first two walls run across the middle of the room with a three meter gap between them: a doorway. The third is a stub sticking into the far half, to give the characters something to walk round once they are through.

Add a light and a camera so there is something to see:

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 8, 14, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 3.5)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 17, 19)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 120)


function onOverlayUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Run it with Singe -R navigation. A gray floor, a wall with a gap, and a stub, seen from above and behind.

Bake the Floor

Six lines turn that room into a map:

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)
navAddNode(nav, ground)
for _, wall in ipairs(walls) do
    navAddNode(nav, wall)
end
navBuild(nav)

Put them after the walls and before the light. Then add one line to onOverlayUpdate, under overlayClear, so you can see what you got:

    navDraw(nav, 0, 170, 190)

Run it again. A web of blue-green triangles is laid over the floor, and it stops short of the walls. The gap it leaves is not decoration: it is the 0.4 meters of clearance a character with a radius of 0.4 meters needs so that its shoulders do not go through the stone. The doorway is still a doorway in the mesh, because three meters is wide enough to walk through; make the gap half a meter and the blue would close across it, and as far as every character in your game was concerned there would be no door there at all.

Look at it for a moment, because navDraw is the tool you will reach for every time a character does something inexplicable. Nine times in ten the answer is on the floor in front of you.

Somebody to Walk It

A character is a node. What it looks like is not navigation’s business, so build the cheapest thing that shows which way it is facing: a box with a nose on it.

function makeWalker(x, z, look)
    local walker = nodeNew()
    nodeSetPosition(walker, x, 0, z)
    local body = nodeNew()
    nodeSetParent(body, walker)
    nodeSetMesh(body, meshBox(0.7, AGENT_HEIGHT, 0.7), look)
    nodeSetPosition(body, 0, AGENT_HEIGHT / 2, 0)
    local nose = nodeNew()
    nodeSetParent(nose, body)
    nodeSetMesh(nose, meshSphere(0.22, 16), look)
    nodeSetPosition(nose, 0, 0.4, -0.45)
    return walker
end

That goes with addWall. It needs a color, so add one beside the other materials:

local walkerLook = materialNew()
materialSetColor(walkerLook, 225, 85, 60)
materialSetEmissive(walkerLook, 70, 18, 10)

And now the line this lesson exists for. After navBuild:

local walker      = makeWalker(-7, 7, walkerLook)
local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

navAgentNew puts the node on the mesh and hands back an agent: the engine’s word for something it is willing to walk around for you. From this moment the engine owns that node’s position. Every frame it moves it, and turns it to face the way it is going, and it will keep doing that until you tell it where to go or take the agent away.

Run it. A red box with a nose appears in the near corner and does absolutely nothing, because you have not asked for anything yet.

Sending It Somewhere

Give it a list of places and a button.

local posts = {
    {  7, 0,  7 },
    {  7, 0, -7 },
    { -7, 0, -7 },
    { -7, 0,  7 },
    { 30, 0, 30 }
}
local post    = 0
local message = "Button 1 sends the red one somewhere."


function onInputPressed(what)
    if what ~= SWITCH_BUTTON1 then
        return
    end
    post = post % #posts + 1
    local target = posts[post]
    if navAgentMoveTo(walkerAgent, target[1], target[2], target[3]) then
        message = string.format("Walking to post %d.", post)
    else
        message = string.format("No path to post %d.  Staying put.", post)
    end
end

Print the message so you can see what is going on. In onOverlayUpdate, after navDraw:

    overlayPrint(2, 2, message)

Run it and press button one — the space bar by default. The box turns, walks to the far corner of its own half of the room, and stops. Press again. It walks along the wall, finds the doorway, goes through it, comes out the other side, and stops in the far corner. Press a third time and it goes round the stub to the fourth corner. You did not tell it about the doorway. Nothing in your script mentions the doorway. It found it, because the doorway is a hole in a shape and going round holes is what the mesh is for.

Each posts entry is three numbers, an x, a y, and a z, because a point in a three dimensional world needs three. Y is up, and yours are all zero because everything here is on the ground. The posts table is a table of tables, from lesson six, and posts[post] is one of the inner ones.

Knowing When It Arrives

The box stops when it gets there, but your script does not know that it has. Ask to be told:

function onNavArrived(agent)
    message = string.format("Arrived at post %d.", post)
end

This is a callback, the same idea as onOverlayUpdate in lesson one: you write it, the engine calls it. This one runs once, the moment an agent reaches the target it was given. Not when it is near, and not every frame afterward — once, on arrival.

It is handed the agent, because a game has more than one. That argument is the number navAgentNew gave back, and comparing it is how you tell which of your characters has just got where it was going.

When There Is No Path

Press the button a fifth time and the message reads No path to post 5. Staying put., and the box does not move.

Post five is at { 30, 0, 30 }, which is twenty meters outside a room twenty meters across. There is no walkable floor there, there is no route to it, and there is nothing sensible for a character to do about it. navAgentMoveTo says so by handing back false, and it leaves the agent exactly as it was.

This is the part beginners skip, and it is the part that bites. Real games ask for impossible walks constantly, because the target is usually the player and the player gets everywhere: standing on a crate, mid-jump, in the water, behind a door that closed, or through a gap the nav mesh trimmed away as too narrow. Every one of those makes a perfectly reasonable navAgentMoveTo return false.

Your script decides what that means. A guard who cannot reach you should go back to patrolling, or walk to the nearest point it can reach and wait there, or shout. What it must not do is nothing while your code quietly ignores a returned false and you wonder for an hour why one enemy in twenty is frozen.

Two other calls help here, and they are worth knowing before you need them. navNearest takes any point and hands back the closest spot on the mesh, or nil if there is nothing near it, which is how you turn "where the player is" into "somewhere a character can actually stand". And navPath asks the same question as navAgentMoveTo without moving anybody: it hands back the corners of the route as a table of points, or nil when there is no route. You can measure it, draw it, or decide the walk is too long to bother with.

Drawing it is the useful trick. Add this to onOverlayUpdate:

    local target = posts[post]
    if target ~= nil then
        local x, y, z = nodeGetWorldPosition(walker)
        local route   = navPath(nav, x, y, z, target[1], target[2], target[3])
        if route ~= nil then
            for i = 2, #route do
                local a = route[i - 1]
                local b = route[i]
                lineDraw(a[1], a[2] + 0.1, a[3], b[1], b[2] + 0.1, b[3], 255, 215, 60)
            end
        end
    end

Now a yellow line runs from the box to wherever it is going, bending through the doorway, shortening as it walks. Send it to post five and the line is not drawn at all, because navPath returned nil and the if caught it. You are watching the decision that the agent is making, drawn on the floor.

A Second Walker

One character avoiding walls is navigation. Two characters avoiding walls and each other is what the engine actually gives you, and it costs four more lines.

Add a blue material beside the red one, then this under the first agent:

local wanderer      = makeWalker(6, -6, wandererLook)
local wandererAgent = navAgentNew(nav, wanderer, AGENT_RADIUS, AGENT_HEIGHT, 1.4)

Send it somewhere to start it off, after the camera:

navAgentMoveTo(wandererAgent, navRandomPoint(nav))

And teach onNavArrived to tell the two apart:

function onNavArrived(agent)
    if agent == wandererAgent then
        navAgentMoveTo(agent, navRandomPoint(nav))
    else
        message = string.format("Arrived at post %d.", post)
    end
end

navRandomPoint picks somewhere on the walkable mesh — anywhere on it, never inside a wall — and hands back three numbers, which is exactly what navAgentMoveTo wants next. Because the callback fires on arrival and its answer is another journey, the blue box now wanders the room for as long as the game runs, out of four lines and no state at all.

Watch the two of them meet in the doorway. Neither one stops dead and neither one walks through the other: they both lean aside a little, in good time, and pass. That is the agents steering round each other, and it is the difference between characters and furniture.

The finished script is learn/26-navigation.singe.

What Just Happened

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)

Starts a navigation mesh, and the four numbers are a description of the person it is for: 0.8 meters wide, 1.8 meters tall, able to walk a slope of up to forty-five degrees, and able to climb a step of up to 0.3 meters.

Every one of those changes the shape that comes out. A wider character loses more floor to the margin around walls and may find a doorway closed. A taller one cannot walk under a low beam. Allow a steeper slope and a ramp becomes a road; allow less and it becomes a cliff.

The radius also decides how finely the floor is measured, so a very small radius over a very large level takes a long time to bake. The reference’s entry for navNew is worth reading before you pick your numbers.

navAddNode(nav, ground)
navBuild(nav)

navAddNode hands over geometry — a node and everything hanging under it, as it stands in the world at that moment, so place things before you add them. One call takes a whole loaded model. Only actual shapes count: a light, a sound, or a physics body on its own adds nothing.

navBuild does the baking, and it is the slow call in this lesson: nothing you would notice for a room like this one, a tenth of a second for a cathedral on a desktop machine, several seconds on a Raspberry Pi. Do it while a title screen is up, not while the player waits.

Afterward the geometry is thrown away and the mesh is closed. You cannot add more. If your level changes shape — a door opens, a bridge falls — you bake another mesh, and navDelete frees the old one.

On a slow machine you would rather not bake at all, so navSave writes the finished mesh to a file and navLoad reads it back, built and ready. Bake once on your own machine, ship the file with the game, and the player never waits.

local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

An agent is a node the engine has agreed to walk about for you. The radius and height here are what it uses to keep clear of other agents, and the last number is its top speed in meters a second — 2.2 is a brisk walk, 1.4 is an amble, 6 is a sprint.

From here on, do not set that node’s position yourself. Two things moving one node fight, and the fight looks like stuttering. If your character needs to be shoved about by physics as well as walk, there is a call for that — navAgentSetPlayer hands the steering to a physics controller instead — and the reference’s entry for it explains when you want it.

local ok = navAgentMoveTo(walkerAgent, x, y, z)

Sets the target. It does not walk there; it says where "there" is, and the engine gets on with it over the following frames. You may call it again at any moment and the new target replaces the old one, which is how a guard follows a player who is running: re-aim it once or twice a second, not sixty times.

And it hands back true or false, and you must look.

navAgentStop(walkerAgent)

Not used above, but the other half of the pair: it forgets the target and the agent slows to a stand where it is. onNavArrived does not fire, because it did not arrive. Use it when the reason for the journey has gone away.

Fast Is Not the Point

One more call, because it is what turns this from a demonstration into something that looks like a game.

    local vx, vy, vz = navAgentGetVelocity(walkerAgent)
    local speed      = math.sqrt(vx * vx + vz * vz)
    overlayPrint(2, 4, string.format("Speed %.2f", speed))

navAgentGetVelocity tells you how the agent is moving right now: not where it is going, but how fast and in which direction it is actually traveling this frame. Watch the number as the box sets off and as it comes to a halt. It eases in and eases out.

That number is what you hang an animation on. A character whose legs move at the speed it is actually traveling looks alive; one whose walk cycle runs at a fixed rate while it accelerates looks like it is skating. With a real model in place of the box you would compare that speed against a couple of thresholds and play an idle, a walk, or a run — which is lesson twenty-three’s subject, and the reference’s example under navAgentGetVelocity is written for exactly that.

Which is the real point of this lesson. A character that takes the fast straight line and grinds along a wall is worse than one that sets off a second later, turns properly, goes round through the door, and slows down when it arrives. Nobody watching a game measures how quickly an enemy reached them. They notice, immediately and without being able to say why, when something moves in a way a living thing would not.

Try It

  1. Close the door. Change the first two walls so the gap between them is half a meter instead of three: addWall(-4, 0, 13, 0.6) and addWall(6.5, 0, 7, 0.6). Run it and look at what navDraw shows before you press anything. Then send the box across and see what it does.

  2. Make everybody fat. Set AGENT_RADIUS to 2.0 and run it. The doorway is still three meters wide and the blue triangles are gone from it. Nothing is broken; the mesh is answering a different question now.

  3. Send it to the mouse. Take the point under the mouse pointer with sceneUnproject, snap it onto the mesh with navNearest, and send the box there when the button is pressed. navNearest returning nil is the case you must handle, and it happens whenever the pointer is off the floor.

  4. Add four more wanderers. Put the blue walker’s four lines in a for loop from lesson four, keep the agents in a table, and let them all wander. Watch the doorway when three of them want it at once.

  5. Bake it once. Call navSave(nav, "room.nav") after navBuild, then replace navNew, the navAddNode calls, and navBuild with a single navLoad("room.nav", AGENT_RADIUS, AGENT_HEIGHT). Now change a wall’s position and run it again. What you see is the trap that comes with baked meshes, and it is worth meeting once on purpose.

Break It on Purpose

Baking closes the mesh. Try to add one more thing after the fact — a crate you placed late, or a wall you forgot — by putting this line straight after navBuild(nav):

navAddNode(nav, ground)

Singe stops before the game starts, naming the line that call is on in your file:

68:navAddNode:  The mesh is already built.

The shape of an engine error is the line, the call that objected, and the complaint, and this complaint means what it says: navBuild consumed the geometry it was given and there is no longer anything to add to.

The fix is never to move the navAddNode call. It is to notice that you have two levels' worth of geometry and want two meshes, or that you baked too early. Add everything, then build, and build last.

What You Learned

  • Stepping toward a target works in an empty room and fails the moment there is a wall, and no amount of patching fixes it.

  • A navigation mesh is a simplified map of the floor a character can stand on, with the walls, the drops, and the clearance around them taken out.

  • navNew describes the character the mesh is for, navAddNode hands over the level’s geometry, and navBuild bakes it. After the bake, nothing more can be added.

  • navSave and navLoad keep a baked mesh in a file so the player never waits for it.

  • navDraw shows you the mesh, and it is the first thing to look at when a character behaves strangely.

  • navAgentNew gives a node to the engine to walk about; from then on, do not move that node yourself.

  • navAgentMoveTo sets a target and hands back false when there is no way to get there. Handling that is your job, and it happens often.

  • onNavArrived is called once when an agent reaches its target, and is told which agent.

  • navPath answers the same question without moving anyone, and nil means no route.

  • Agents steer round each other as well as round the level.

  • navAgentGetVelocity is how a walk cycle matches the ground being covered.

Next Time

Your two boxes now walk around a room in silence. Lesson twenty-seven is about what you put behind them: music that loops properly and stays in step with video, and MIDI, which lets a game play an instrument — or lets a real instrument play the game.

Lesson 27: Music and MIDI

The finished lesson

This lesson is two lessons that happen to live together.

The first half is music: how a game plays a piece of music properly, why that is not the same thing as playing a sound effect, and what to do when the music has to stay in step with video.

The second half is MIDI, which most people have never met and which gives a game something nothing else does. By the end of it, a keyboard plugged into your computer will be playing your game.

A Sound Effect and a Piece of Music Are Different Things

You already know how to play a sound. Lesson ten loaded a .wav with soundLoad and fired it with soundPlay, and if you point those two calls at a four minute song they will play it.

Do not. Singe keeps sound effects and music apart, and the separation is worth having for four reasons.

  • They have their own volumes. soundSetVolume never touches the music and musicSetVolume never touches the gunshots. Every game that has ever shipped needed that, because players turn the music down and the effects up.

  • Music has no channel limit. Sound effects share sixteen channels, and when all sixteen are busy the seventeenth does not play. A music track is not on a channel, so nothing can crowd it out.

  • One handle is one track, and it pauses, resumes, stops, and fades on its own without disturbing anything else.

  • Music pauses with the game. Hit the pause key and it holds where it is. Come back and it picks up. You write nothing to make that happen.

One thing that is not different is worth knowing, because people assume the opposite: Singe decodes a music file into memory up front, exactly as it does a sound effect. A long track costs memory. It is not streamed off the disk a piece at a time. Five minutes of music is a few tens of megabytes of memory while it is loaded, so load the track for the level you are on and musicUnload it when you leave.

Playing a Track

Every reader of this book already has a piece of music, because the engine unpacked one into your work folder the first time you ran anything. Start a file with these three lines:

local theme = musicLoad("Singe/menuIntro.flac")
musicSetVolume(64)
musicPlay(theme, -1)


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Music: " .. (musicIsPlaying(theme) and "playing" or "stopped"))
    return OVERLAY_UPDATED
end

Run it with Singe -R music. Ten seconds of music, and then it starts again, and it keeps starting again.

That is what the -1 does. musicPlay takes a number of loops: leave it out or pass 0 and the track plays once, pass 3 and it plays four times in all, and pass -1 and it repeats until something stops it. A menu, a title screen, or a level’s background is nearly always -1.

Two details in that little script are worth the ink. musicLoad takes a path and not a DIR .. path, because Singe/menuIntro.flac is one of the engine’s own files and sits in the folder the engine unpacked into your work folder. musicIsPlaying answers true or false, and the and …​ or …​ in the middle of that overlayPrint is the Lua shorthand from lesson three for choosing one of two values.

The Volume Scale Is Not the One You Know

musicSetVolume(64) sets it to about half. Sound effects run from 0 to 63; music runs from 0 to 128, which is twice as far.

That is not a mistake and it is not a joke. Singe can run games written for Hypseus, an engine whose music volume has always been a 0 to 128 scale, and changing the numbers would silently make those games' music twice as loud as their authors meant. So Singe keeps both scales, each attached to the family of calls it belongs to. Effects: 0 to 63. Music: 0 to 128. Give musicSetVolume a number outside its range and the script stops, which you will see for yourself at the end of this lesson.

What Singe Will Play

Nearly anything. WAV, Ogg Vorbis, Opus, MP3, FLAC, WavPack, AAC, and a long list past that, all through the same musicLoad.

Two families are more interesting than the ordinary ones, and both exist because they are tiny.

Tracker modules — .mod, .s3m, .xm, .it, and fifty-odd relatives — hold a handful of short recorded instruments and a list of which notes to play them at. A four minute tune can be under a hundred kilobytes.

Chiptunes — .nsf, .spc, .vgm, .gbs, and their kin — go further: they hold the register writes for the actual sound chip of a Nintendo, a Mega Drive, or a Spectrum, and Singe emulates the chip to play them. If you want a game to sound like 1989 rather than to sound like a recording of 1989, this is how.

Either loads with musicLoad like anything else. The reference’s Video, Audio, and Container Formats section has the full list, including which container goes with which codec.

Stopping, Pausing, and Fading

musicPause(theme)
musicResume(theme)
musicStop(theme)
musicStop(theme, 2000)

musicPause holds the track where it is and musicResume carries on from that spot. musicStop ends it, and the track goes back to its beginning the next time you play it. With a second number, musicStop fades the track out over that many milliseconds instead of cutting it dead — two seconds here. That fade is the single easiest thing you can do to make a game feel finished. Music that stops mid-bar when the player walks through a door sounds like a bug, even to someone who could not say why.

Call any of the four with no handle at all and they act on every piece of music at once, which is what a pause screen wants.

Now the honest limit, because you will look for this and it is not there: Singe cannot crossfade two tracks. musicSetVolume is one gain over all music, not a volume per track, so there is no way to bring one track up while another goes down. What you can do is fade the old one out and start the new one as it goes, which is close enough for a level change and audibly not the same thing for a battle theme sliding in under an exploration theme. If you need a true crossfade today, the way to get it is to make the two pieces one file and seek within it, or to accept the overlap.

Music, Video, and Staying in Step

If your game plays video — part three’s subject — there is one thing to know about sound, and it is not a music call at all.

Singe shows a video frame when the sound that belongs with it is heard, not on a timer. The audio is the clock and the picture follows it. That is the right way round, because an ear notices a fifth of a second of drift in a voice and an eye does not notice the same drift in a mouth.

The engine measures its own audio path when it starts. What it cannot measure is everything after the operating system hands the sound away: an amplifier, a television, an HDMI receiver, a Bluetooth headset. Each of those adds a delay of its own, it is different on every machine, and it shows up as sound arriving slightly after the thing that made it.

The fix is one number:

singeSetAudioDelay(45)

Forty-five milliseconds of "the audio is late; hold the picture back to match". You can also pass it as --audiodelay=45 on the command line or put it in the game’s games.dat entry. singeGetAudioDelay reads back whatever is in force, which is what a service menu shows next to its slider.

You do not have to guess the number. Singe’s own menu has a calibration screen: it plays a click once a second and flashes the screen white, you adjust until the flash and the click happen together, and it saves the result for every game on that machine. The reference’s Audio Sync section describes it and explains why it works. If you build a cabinet, run it once after you wire the speakers, and never think about it again.

The Other Thing Called MIDI

MIDI is two unrelated things with one name, and keeping them apart is most of understanding it.

Here is the first, in one paragraph. A recording — a .wav, an .mp3 — is a measurement of a sound, taken forty-four thousand times a second. MIDI is not that. A MIDI file holds what was played: at this moment, on this channel, press key sixty this hard; a little later, let go of it. It is closer to sheet music, or to a player piano’s punched roll, than to a recording. That is why a MIDI file is a few kilobytes when the same music as audio is a few megabytes, and it is also why a MIDI file does not contain any sound at all. Something has to play the notes.

A MIDI file is music, so it plays like music:

local tune = musicLoad("music/overworld.mid")
musicPlay(tune, -1)

But the thing that plays the notes has to come from somewhere, and that thing is a soundfont: a file full of recorded instruments — a piano, a trumpet, a snare drum — with the notes and the loop points marked, so the engine can build any note of any instrument out of them.

Singe does not ship one. A good soundfont is tens of megabytes, and it would be tens of megabytes carried by every copy of the engine for a format most games never touch. So you name one with --soundfont, or you put one at Singe/soundfont.sf2 so that a packed game carries its own, or you let Singe find the one your Linux distribution installed. With no soundfont anywhere, loading a .mid fails and says so.

This is why the same MIDI file sounds different on two machines and why it sounded so bad on the computers of the nineteen nineties. The file is a list of notes. What you hear is whichever soundfont happened to play them: a good one is a room full of instruments, a cheap one is a room full of toys, and the notes are identical in both. If a MIDI file is going in your game, ship the soundfont with it. Otherwise you have not chosen how your music sounds; you have left it to whatever is installed on the player’s machine.

MIDI as a Wire

Now the second thing, which is the interesting one.

MIDI is also a cable, and messages that travel along it. Plug a musical keyboard into your computer and every key you press sends a message: note on, channel 1, key 60, velocity 90. Turn a knob on a control surface and it sends controller 7 on channel 1 is now 40. These messages exist whether or not anything is playing any music. They are another input device, like a joystick with eighty-eight buttons that know how hard you hit them.

And it goes the other way. Your game can send those messages out, to a synthesizer, a sound module, a stage light controller, or anything else on the wire.

Ports are numbered from zero, and Singe opens nothing until you ask — a game that never mentions MIDI never pays for MIDI. One input port and one output port may be open at a time. Take stock of the machine like this:

local inPort  = "none"
local outPort = "none"

if midiInputCount() > 0 and midiOpenInput(0) then
    inPort = midiInputName(0)
end
if midiOutputCount() > 0 and midiOpenOutput(0) then
    outPort = midiOutputName(0)
end

On a machine with no MIDI at all the counts are zero, the open calls answer false, and nothing fails. That matters: it means you can write this code into a real game and ship it, and the ninety-nine players in a hundred with no MIDI keyboard will never know it is there. The names are for a settings screen that lets a player choose which port, because port zero is rarely the one they want. midiRescan looks again for something plugged in while the game is running.

Listening

Every message that arrives goes to a callback, in the same way that every key press goes to onInputPressed:

local MIDI_NOTE_ON = 0x90


function onMidiMessage(status, data1, data2, bytes)
    if (status & 0xF0) ~= MIDI_NOTE_ON or data2 == 0 then
        return
    end
    heard = noteName(data1)
end

Most MIDI messages are three bytes long, and the three numbers you are handed are those bytes exactly as the device sent them. A message with fewer bytes hands you a 0 in place of each one it does not have.

status says what kind of message it is and which channel it came from, mixed together: the kind is the top four bits and the channel is the bottom four. 0x90 is note on, and a note on channel 1 arrives as 0x90 while the same note on channel 5 arrives as 0x94. status & 0xF0 keeps the top half and throws the channel away, which is what you want unless you care which channel it was. (& is Lua’s bitwise and, and 0x90 is a number written in hexadecimal — base sixteen — because that is how every MIDI document in the world writes them.)

data1 and data2 are the other two bytes, and what they mean depends on the kind. For a note on they are the key and the velocity: key 60 is middle C, and velocity is how hard it was struck, 1 to 127.

The check for data2 == 0 is not fussiness. A note on with a velocity of zero means note off: it is how nearly every keyboard ever made says "I let go", and if you do not filter it your game will fire twice for every key.

bytes is the whole message as a string, which is how you read a message longer than three bytes.

Playing

Sending is easier than receiving.

midiNoteOn(1, 60, 100)
midiNoteOff(1, 60)

Middle C on channel 1, struck at a hundred, and then released. Channels here are 1 to 16 as a person counts them, not 0 to 15 as the wire does, which is Singe being kind to you.

Every midiNoteOn needs a midiNoteOff. A note that is never released sounds until something stops it, and the classic first MIDI bug is a game that crashes or quits with three notes held down and leaves a chord hanging in the room. So pair them, and pair them through a timer rather than by hand:

function playTarget()
    if not midiIsOutputOpen() then
        return
    end
    local key = target
    midiNoteOn(1, key, 100)
    timerAfter(HOLD_MS, function()
        midiNoteOff(1, key)
    end)
end

local key = target is doing real work. timerAfter runs its function four tenths of a second later, and by then target may have changed to a different note; copying it into a local means the timer releases the note that was actually pressed. Copy anything a timer will need later.

The other sending calls do the rest of what MIDI is: midiProgramChange chooses which instrument a channel plays, midiControlChange moves a controller (volume is 7, pan is 10, the sustain pedal is 64), midiPitchBend bends a channel, and midiSend sends any message at all as raw bytes for the things the named calls do not cover.

A Reason to Care

All of which is machinery. Here is what it is for.

Put the two halves together and the game asks for a note, the player plays it on a real instrument, and the game knows whether they got it right:

function onMidiMessage(status, data1, data2, bytes)
    if (status & 0xF0) ~= MIDI_NOTE_ON or data2 == 0 then
        return
    end
    heard = noteName(data1)
    if data1 == target then
        score = score + 1
        pickTarget()
        playTarget()
    end
end

Eleven lines, and you have the skeleton of a music teaching game. Add a clock and you have a rhythm game that scores real playing rather than four plastic buttons. Add data2 to the test and it cares how hard you hit the note. Compare the time the note arrived against the time it was due and you are grading timing to the millisecond.

And because MIDI goes out as well as in, a cabinet can do things nothing else can. A real instrument wired to the machine. An external sound module playing the score so the tune has depth no sample bank gives it. Stage lights on the cabinet that flash on the beat because the game sent them the beat. If you are the sort of person who builds arcade cabinets, this is the call that lets the cabinet be a thing rather than a box round a computer.

The finished script is learn/27-midi.singe: the music controls, the port list, and the guessing game, in about a hundred lines. The space bar sends the note out, Left Alt pauses the music, Left Shift fades it, and the up and down arrows move the volume. Run it with no MIDI hardware and the music half works and the MIDI half says none twice, which is how it should behave on a player’s machine.

Cleaning Up

function onShutdown()
    midiCloseInput()
    midiCloseOutput()
    musicUnload(theme)
end

onShutdown is called once when the game ends, and it is where a script gives things back. Closing a port that is not open does nothing, so there is nothing to check first.

Try It

  1. Make it loop four times instead of forever. Change musicPlay(theme, -1) to musicPlay(theme, 3) and count. The number is how many times it repeats, not how many times it plays.

  2. Fade for longer. Change the fade on the button that stops the music to musicStop(theme, 4000) and listen to the difference four seconds makes. Then try musicStop(theme, 100).

  3. Show the channel. In onMidiMessage, work out the channel with (status & 0x0F) + 1 and print it. Play your keyboard and see which channel it is on — and then find its settings and change that channel, to prove to yourself that the number is real.

  4. Score the velocity. Give a point for the right note, and three points if data2 is over a hundred, so the game rewards playing it like you mean it.

  5. Play the answer. When the player gets a note right, make the game play a small chord back at them with three midiNoteOn calls a couple of notes apart and three timers to release them. You will need a real output port or a software synthesizer for this, and on Linux that is any program that registers itself with ALSA.

Break It on Purpose

The two volume scales are easy to mix up, and Singe would rather stop than play your music at a level you did not mean. Add one line under musicPlay(theme, -1), using the number that would be full volume for a sound effect if you doubled it in your head and got it wrong:

musicSetVolume(200)

Singe stops before the game starts, naming the line that call is on in your file:

107:musicSetVolume:  Invalid music volume value:  200

The line, the call that objected, and the complaint, which here quotes the number back at you so there is no argument about what arrived. Music is 0 to 128. Sound effects are 0 to 63. When a volume call stops your game, the question to ask is which of the two families you are talking to.

What You Learned

  • Music and sound effects are separate in Singe: their own volumes, no channel limit for music, and a pause that follows the game’s pause.

  • A music file is decoded into memory up front, so a long track costs memory and should be unloaded when you leave the level.

  • musicPlay(track, -1) loops forever; a positive number is how many times it repeats.

  • Music volume is 0 to 128 and effects volume is 0 to 63, and the difference is Hypseus compatibility, not a mistake.

  • musicStop(track, milliseconds) fades out, and a fade is the cheapest polish there is. There is no crossfade, because one gain covers all music.

  • Singe presents video against the audio clock, and singeSetAudioDelay corrects for the delay of whatever the sound comes out of.

  • A MIDI file holds notes, not sound, and needs a soundfont to be heard at all. Singe ships none, so ship your own or your music is whatever the player’s machine happens to have.

  • MIDI ports are a separate thing entirely: live messages in and out, on a wire, with nothing to do with MIDI files.

  • onMidiMessage hands you the raw bytes. The top four bits of status are the kind, the bottom four are the channel, and a note on with velocity zero means note off.

  • Every midiNoteOn needs a midiNoteOff, and a timer is how you pair them.

  • On a machine with no MIDI, every call answers false or zero and nothing fails, so MIDI support is safe to ship.

Next Time

Your game has music, and a score that a MIDI keyboard can run up. Lesson twenty-eight takes that score off the machine: accounts, high score tables that other people can see, and the catalogue that lists your game to the world.

Lesson 28: Online

The finished lesson

In lesson twelve you saved a high score. It is still there the next morning, which is most of what a high score is for, but it is a high score on one machine. This lesson puts a score on a board that other people can see.

It is also the lesson about failure. Everything else you have written fails for reasons you can find: a file is missing, a number is wrong, a function is misspelled. The network fails for reasons nobody in the room can see. A cable was unplugged in a building you have never been to, and your game has to keep playing. Most of what follows is about that.

What the Service Is

Singe can talk to a master service, a server that holds three things:

  • an account, which belongs to the machine and not to any one game;

  • a catalogue of games to download and update;

  • high score boards, one or more per game.

The default service is master.singeengine.com, and an operator running their own points the machine somewhere else. The manual’s section on the online service describes both sides.

Now the part people skip. The service is not multiplayer: there is no way for two players to be in the same game. It is not a save-game cloud; lesson twelve’s save stays on the machine. It is not copy protection, and nothing in it stops anybody playing your game. It is not required: a game that never signs in runs exactly as it always did, which is the only sane default for something that needs a working connection.

So the board is an extra. Keep the local high score from lesson twelve, keep showing it, and let the online board be the thing that is sometimes there.

Signing In Happens Once, and Not in Your Game

The account belongs to the machine. It is created and signed in from the bundled menu, behind the key mapped to INPUT_SERVICE, in the tool called Online Account. The token it gets is written to master.dat in the data root, one level above any game’s own data directory, so every game on the machine posts under the same sign-in.

Your game never asks for an email address and never asks for a password. There is no function to do it with, and that is deliberate: a player typing a password into a game they downloaded has no way to know where it goes.

What a player appears as on a board is a handle: three to twenty characters of letters, digits, hyphens, and underscores, starting and ending with a letter or a digit. No spaces, no dots, and no @, so a handle cannot even look like an email address. It is kept apart from the account, it is the only thing about a player that other players see, and it is chosen once — an operator can change one, a player cannot, because a board whose names keep moving is not really anybody’s history. Until a handle has been chosen, scores are refused, since a score with nobody’s name on it is not on a board in any useful sense.

The Online Account tool shows the name this machine posts under, and your game reads it with scorePlayerName(), which answers nil when there is none. Worth knowing before it puzzles you: a score submitted with no handle behind it is refused by the service, not by scoreSubmit, so your game is told nothing about it. If scorePlayerName() is nil, say so on screen while there is still somebody there to read it.

Your Game Needs an Id

A board has to be kept under something. That something is GAME_ID in your game’s games.dat entry, the file you made in lesson thirteen:

GAME_ID = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10"

It is a UUID, in exactly that shape: eight hexadecimal digits, three groups of four, then twelve, separated by hyphens. Generate one however you like and paste it in; it does not matter which one you get, only that it never changes again. The reference’s entry for singeGetGameId explains why nothing else is accepted.

singeGetGameId() hands it back, or nil when the entry has none. A game without an id can be played but cannot be ranked, and asking first is how you avoid offering a leaderboard that can never work:

if singeGetGameId() then
    -- showLeaderboardButton is your own function, not one of Singe's.
    showLeaderboardButton()
end

The Six Calls

Everything a game does with the service is six functions, and they come from Singe/Framework.singe, so the dofile at the top of your script is not optional here:

dofile("Singe/Framework.singe")

scoreBegin() says a play is starting. scoreSubmit(value) queues a score. scoreBoard(onDone) fetches the board. scorePlayerName() is the handle. scoreWaiting() is how many scores have not gone out yet. And scoreUpdate() has to run once a frame, from onOverlayUpdate, or none of the others ever finish.

That last one is the whole trick of this lesson, so it gets said twice. Nothing here talks to the network when you call it. scoreSubmit writes to a queue and returns immediately. scoreBoard remembers what you want and returns immediately. The actual work happens a slice at a time inside scoreUpdate, between your frames, which is why your game never stutters while the wire is slow. Leave scoreUpdate out and nothing breaks, nothing errors, and nothing ever happens.

function onOverlayUpdate()
    scoreUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Posting a Score

At the end of a game:

if scoreSubmit(score) then
    fetchBoard()
else
    saying = "Kept here only:  " .. whyNotPosted()
end

scoreSubmit answers false when there is no account or the game has no GAME_ID, and true when the score went into the queue. Notice what the else does not do: it does not throw the score away, it does not apologize at length, and it does not stop the player starting another game. It says one short line, because the player did nothing wrong and cannot fix it from here.

The queue is the reason this is safe. A queued score is written to disk, so it survives the machine being switched off, and it is handed to the service the next time there is a connection — an hour later, or next Tuesday. That is why a cabinet in a room with bad wifi still ends up on the board.

Be honest with yourself about the edge of that promise: the queue holds scores for a machine that has an account. If nobody ever signed in, scoreSubmit answers false and the score is not kept for later, because there is nobody to keep it for. scoreWaiting() tells you how many are still in the queue, and showing that number somewhere is a kindness: it is the difference between "the service is broken" and "three of your scores are waiting for the internet to come back".

scoreBegin() is worth a paragraph of its own. Call it when a play starts, and the service notes the moment by its own clock. The score that follows carries how long the play took, measured on the server, which is the one number in a submission that has not been through the player’s machine. Nothing is rejected on it: it is shown to whoever runs the service, beside the score, and a person decides. A machine that was offline when the play started records no time, which is honest rather than broken.

And while we are being honest: a submitted score is a claim. The game runs on the player’s computer, so nothing the client can do makes it more than that, and a secret key shipped inside your game would only look like security. The service records who claimed what, limits how fast scores can arrive, and flags the wild ones for a person to look at. Design your board knowing that.

Reading the Board Back

scoreBoard is the first function in this book that takes a function as an argument.

scoreBoard(function(ok, result)
    ...
end)

You wrote functions in lesson five and gave them names. This one has no name: it is written where it is used, handed straight to scoreBoard, and called later — possibly seconds later — when the answer arrives. That is a callback again, the same idea as onOverlayUpdate, except that this time you choose who calls it.

ok is true or false. When it is false, result is a short string saying why. When it is true, result is a table with two parts:

  • result.top, a list of rows, each with a name and a value;

  • result.standing, this player’s own value, rank, and the number of players on the board — which may be missing, if this player has nothing on it.

Between the call and the callback your game keeps running and drawing. That gap is real and the player can see it, so put something in it. The script below sets a line of text to "Asking the service…​" before it calls, and the callback replaces that line with either the board or the reason there is none. A screen that says nothing for four seconds looks broken; a screen that says what it is doing is just slow.

The Catalogue

The third thing the service does is list games. The menu’s Get Games tool shows everything the service offers, marks what is already installed on this machine, and downloads, updates, or removes it. A download is checked against the digest the catalogue published before it replaces anything, so a transfer that arrives damaged fails instead of installing a game that will not run. A game the service has withdrawn keeps working and is shown as installed but no longer offered: all that stops is being given an update, because somebody who has a game has it.

Your game does not call any of this, and should not. The catalogue matters to you as the author of a game rather than as the writer of a script: it is where your .game file goes when you publish it, which is lesson thirty, and it is another reason your games.dat needs a GAME_ID that never changes. If you ever do want the list from inside a script, Singe/Master.singe is the module underneath all of this and is worth reading once.

What the Service Knows About a Player

If you ship a game that posts scores, you are handing somebody else’s data to a server, and that is your responsibility even though you did not write the server. So say it plainly, in your own game’s about screen or read-me:

  • The service holds an email address and a password for the account. The address is how a lost password is recovered and nothing else. It is never shown to other players and cannot be changed afterwards.

  • The handle is what appears on boards. It is deliberately kept apart from the account so that an address is never what other players see, and it is checked against a list of names nobody should claim and words that do not belong on a screen in a public room.

  • A score carries its value, the board it is on, the time the service recorded, and the handle. That is all.

  • The catalogue knows which games are installed on the machine, and which version, because that is how it offers you an update.

What none of it does is follow a player between games, sell anything, or reach into the machine for anything you did not send. Your game should not add to the list. If you attach extra information to a score — scoreSubmit takes an optional third argument for that — keep it about the game.

The Script

A reaction test: wait for the word, press the button, score what is left of a thousand. It is a small game, and the rest of it is the online part.

Make a folder called reaction and put this in reaction.singe inside it. Give the folder a games.dat like lesson thirteen’s, naming reaction/reaction.singe, with the GAME_ID line from above in its entry.

dofile("Singe/Framework.singe")

local WAIT_MIN = 1000
local WAIT_MAX = 3000
local PERFECT  = 1000

local state    = "attract"
local goAt     = 0
local score    = 0
local best     = saveGet("best", 0)
local saying   = "Button 1 to play."
local top      = nil
local standing = nil


local function whyNotPosted()
    if not singeGetGameId() then
        return "this game has no GAME_ID."
    end
    return "this machine is not signed in."
end


local function fetchBoard()
    top      = nil
    standing = nil
    saying   = "Asking the service..."
    scoreBoard(function(ok, result)
        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end
        top      = result.top
        standing = result.standing
        if #top == 0 then
            saying = "The board is empty.  You could be first."
        else
            saying = ""
        end
    end)
end


local function finish(reaction)
    score = PERFECT - reaction
    if score < 0 then
        score = 0
    end
    if score > best then
        best = score
        saveSet("best", best)
    end
    state = "result"
    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end
end


local function play()
    state    = "waiting"
    goAt     = singeGetTicks() + math.random(WAIT_MIN, WAIT_MAX)
    score    = 0
    top      = nil
    standing = nil
    saying   = ""
    scoreBegin()
end


function onInputPressed(what)
    if what ~= SWITCH_BUTTON1 then
        return
    end
    if state == "waiting" then
        state  = "result"
        score  = 0
        saying = "Too soon.  Nothing posted."
    elseif state == "go" then
        finish(singeGetTicks() - goAt)
    else
        play()
    end
end


function onOverlayUpdate()
    scoreUpdate()

    if state == "waiting" and singeGetTicks() >= goAt then
        state = "go"
    end

    overlayClear()
    overlayPrint(2, 0, "REACTION TEST")

    if state == "attract" then
        overlayPrint(2, 2, "Button 1 to play.")
    elseif state == "waiting" then
        overlayPrint(2, 2, "Wait for it...")
    elseif state == "go" then
        overlayPrint(2, 2, "NOW!")
    else
        overlayPrint(2, 2, "You scored " .. score .. ".  Button 1 plays again.")
    end

    overlayPrint(2, 4, "Best on this machine:  " .. best)
    overlayPrint(2, 5, "Posting as:  " .. (scorePlayerName() or "nobody yet"))
    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())
    overlayPrint(2, 8, saying)

    if top then
        for place, row in ipairs(top) do
            if place > 5 then
                break
            end
            overlayPrint(2, 9 + place, place .. ".  " .. row.name .. "  " .. row.value)
        end
    end
    if standing then
        overlayPrint(2, 16, "You are " .. standing.rank .. " of " .. standing.players .. ".")
    end

    return OVERLAY_UPDATED
end

Run it with Singe -R reaction. On a machine that has never been signed in, it plays, it keeps your best score, and it says Kept here only: this machine is not signed in. That is the important run, and it is the one most of your players will have.

What Just Happened

local top      = nil
local standing = nil

Two variables that are nil most of the time. nil means "nothing here", and it is what a variable holds before anything is put in it. These hold the board when there is one, and nil when there is not: while the request is in flight, after a failure, and before the first game. The drawing code asks if top then and draws nothing when there is nothing, which is the shape of almost every piece of network code you will write.

    saying   = "Asking the service..."
    scoreBoard(function(ok, result)

The order matters. The line of text is set before the call, because the call returns at once and the callback may not run for seconds. If you set the text inside the callback only, the screen shows the last game’s message until the answer arrives, which is exactly the wrong message at exactly the wrong moment.

        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end

The failure comes first, and it is short. tostring turns whatever came back into text so that joining it with .. cannot fail; result is a string when ok is false, but a line of drawing code that trusts the type of something it got from a server is a line waiting to crash. The player sees one sentence, and the game carries on.

    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end

scoreSubmit answering false is not an error. It is a fact about this machine, and the two facts it can mean are worth telling apart, which is what whyNotPosted does: a missing GAME_ID is your mistake, and an unsigned-in machine is nobody’s. The local best score was already saved, two lines above, before any of this was attempted. Save first, post second, always.

    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())

The queue, on screen. On a machine with a connection this reads 0 forever and nobody notices it. On a machine without one it climbs, and the player knows the game is holding their scores rather than eating them.

function onOverlayUpdate()
    scoreUpdate()

First line of the frame, before anything else. Put it somewhere it cannot be skipped by an if, because a scoreUpdate that only runs on the game-over screen is a queue that only drains on the game-over screen.

Try It

  1. Pull the plug. Disconnect the machine from the network, play a few games, and watch the Waiting to send number. Plug it back in and watch it go down without you doing anything.

  2. Delete the id. Take GAME_ID out of your games.dat and run it again. The message changes. Put it back.

  3. Show more of the board. The loop stops at five rows. The overlay is eighteen character rows tall by default, so work out how many you can actually fit, and move the standing line if you need to.

  4. Name the board. scoreSubmit(score, "reaction") and scoreBoard(onDone, "reaction") use a board of that name instead of the one named for your script. Post to two boards from the same game — say, one for the score and one for a fastest single reaction — and let button 2 switch which one is shown.

  5. Make the wait visible. Between calling scoreBoard and the callback running, draw a dot that moves. Then find out how long that actually lasts on your connection, and whether it was worth drawing.

Break It on Purpose

Take the first line out of onOverlayUpdate, so the scoreUpdate() call is gone, and play a game.

Nothing happens. No error, no message, no board, and the Waiting to send number goes up and stays up forever. The game plays perfectly.

This is the worst kind of bug and it is worth meeting once on purpose: a missing step that produces silence rather than a complaint. There is no line number to look at, because nothing went wrong — you asked for work and then never gave it a chance to happen. When something in Singe that takes a callback never calls you back, the first question is always whether the thing that drives it is running every frame.

The other one you will meet is noisier. Put scoreUpdate() back, delete the dofile line at the top, and run it:

Error executing function 'onOverlayUpdate':  reaction/reaction.singe:89: attempt to call a nil value (global 'scoreUpdate')
stack traceback:
	reaction/reaction.singe:89: in function 'onOverlayUpdate'

Line 89 is the scoreUpdate() you put back, one line higher now that the dofile is gone. Read the first line as always: the function the engine was calling, the file, the line, and the complaint. nil again — the name scoreUpdate has nothing in it, because the file that defines it was never loaded. All six of these calls live in Singe/Framework.singe.

What You Learned

  • The service holds an account, a catalogue, and high score boards. It is not multiplayer, not a save cloud, and never required.

  • The account belongs to the machine and is signed in from the menu’s service tools. A game never asks for a password.

  • A board is kept under GAME_ID in games.dat, a UUID that must never change. singeGetGameId() reads it.

  • scoreSubmit queues a score to disk and returns at once; the queue survives the machine being switched off.

  • scoreUpdate() must run every frame or nothing the service does ever finishes.

  • scoreBoard hands its answer to a function you write, which runs later. Draw something in the meantime.

  • Every network call can fail, and failing is not an error. Say one short line and keep playing.

  • A posted score is a claim, and the service treats it as one.

  • Keep the local high score. It is the one that always works.

Next Time

A high score is one number, and lesson twelve’s save is the right place for it. Lesson twenty-nine is for everything else a game wants to keep: every round anybody plays, the stages you ship, and the questions you want to ask of both. It takes this reaction test and gives it a database.

Lesson 29: Keeping Data

The finished lesson

Lesson twelve saved a high score: one number, under one name, there the next morning. That is exactly right for a high score, and wrong for almost everything else a game wants to keep. A list of every round anybody has played. The best time on each of twenty tracks. Forty levels somebody designed in a spreadsheet. The question "what is my best on the hard stage?", which a pile of saved numbers cannot answer without you writing the answer by hand.

That is what a database is for, and Singe has one built in. This lesson takes the reaction test from lesson twenty-eight, gives it stages that ship with the game, and has it keep every run anybody plays and answer questions about them.

What a Database Is

A database is a file of tables. A table is rows and columns, like a spreadsheet with the column names decided in advance: a table of runs might have a stage, a score, and a time for every row. You put rows in and you ask questions to get rows out, and the questions are written in SQL, a small language that has been doing this job since before most programming languages you have heard of.

The database Singe carries is SQLite. It is not a server you install or a service you sign up for. It is a library, the database is one ordinary file, and the same SQLite is in your phone, your browser, and probably your car. You do not have to know SQL to follow this lesson; every statement in it is explained as it goes past, and the three you will use most — CREATE TABLE, INSERT, and SELECT — are all here.

Opening One

local sqlite3 = require("sqlite3")

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

require("sqlite3") loads a library that comes with Singe and hands it back as a table, so everything SQLite can do is sqlite3. something. sqlite3.open opens a database file and creates it if it is not there yet, so the first run of your game makes an empty one and every run after that finds it again.

The file goes in singeGetDataPath(), and for the same reason lesson twelve’s save does: a game’s own folder may be on a disc, on a share, or packed into one file, and none of those can be written to. Everything a game writes goes in its data directory.

Making a Table

An empty database has no tables. You make one by describing it:

runs:exec([[
    CREATE TABLE IF NOT EXISTS runs (
        id    INTEGER PRIMARY KEY,
        stage TEXT    NOT NULL,
        score INTEGER NOT NULL,
        at    INTEGER NOT NULL
    )
]])

exec runs SQL that does not hand anything back. The double square brackets are Lua’s long string: everything between them, newlines included, is one string, which is how you keep SQL readable.

CREATE TABLE names the table and its columns, each with a type: TEXT for words and INTEGER for whole numbers. NOT NULL means every row must have a value there. INTEGER PRIMARY KEY is special: SQLite fills it in by itself, counting up, so every row gets its own number without you thinking about it.

IF NOT EXISTS is what makes this safe to run every time the game starts. The first time, it makes the table. Every time after that, the table is already there and the line does nothing. Without those three words the second run of your game would stop with an error saying the table already exists.

Putting a Row In

You could build the SQL for a new row by gluing strings together:

runs:exec("INSERT INTO runs (stage, score, at) VALUES ('" .. stage .. "', " .. score .. ", " .. os.time() .. ")")

Do not. It works until a name has an apostrophe in it, at which point the quote ends the string early and the statement is nonsense. In a game that lets players type, it gets worse: whatever they type becomes part of your SQL.

The right way is to write the statement once, with question marks where the values go, and hand the values over separately:

local addRun = runs:prepare("INSERT INTO runs (stage, score, at) VALUES (?, ?, ?)")

local function record(stage, points)
    addRun:bind_values(stage, points, os.time())
    addRun:step()
    addRun:reset()
end

prepare turns the SQL into a statement that can be used again and again. bind_values puts a value in each question mark, in order. Whatever a value contains, apostrophes included, it is a value and never part of the SQL. step runs the statement, and reset makes it ready to run again. os.time() is plain Lua: the current time as a number of seconds, which is the easiest way to store "when".

Preparing once and reusing the statement is also faster, because SQLite works out how to run it only once. For a game that writes one row a minute that does not matter. For a level editor that writes a thousand, it does.

Asking Questions

Rows come back out with nrows, which runs a SELECT and hands you each row as a table with the column names as keys:

for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC LIMIT 5") do
    debugPrint(row.stage .. "  " .. row.score)
end

Read the SQL left to right. SELECT stage, score says which columns you want. FROM runs says which table. ORDER BY score DESC sorts the rows by score, highest first, and LIMIT 5 stops after five. That is a high score table, and it never needed sorting code of yours.

The questions can be cleverer than the ones you would want to write by hand:

for row in runs:nrows("SELECT stage, MAX(score) AS top, COUNT(*) AS tries FROM runs GROUP BY stage ORDER BY stage") do
    debugPrint(row.stage .. ":  best " .. row.top .. " of " .. row.tries)
end

GROUP BY stage gathers the rows into one group per stage, and MAX(score) and COUNT(*) are worked out for each group: the best score on that stage and how many times it has been played. AS top names the answer, which is the key you read it back with.

When a question has one answer, urows hands back the columns themselves rather than a table, which is tidier for a count:

for count in runs:urows("SELECT COUNT(*) FROM runs") do
    played = count
end

Ask When It Changes

None of those questions belong in onOverlayUpdate. A query is fast, but sixty of them a second, to get answers that change once a minute, is the game asking the same question and getting the same answer fifty-nine times out of sixty.

So the game asks when the answer can have changed — once at the start, and again each time a run is recorded — and keeps what came back in ordinary tables:

local function refresh()
    best = {}
    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do
        best[#best + 1] = row
    end
    -- and the same for the other two questions
end

onOverlayUpdate draws from best, which costs nothing. record calls refresh after every new row, so the table on screen is never out of date.

Data That Ships With the Game

The other half of a game’s data is the part you write before anybody plays: the stages, the levels, the items, the lines of dialogue. That can be a database too, made with any SQLite tool — the sqlite3 program on the command line, or a program with windows such as DB Browser for SQLite — and put in your game’s folder beside its art. The art kit has one, stages.db, with a name and the shortest and longest wait for each stage.

A game opens that one differently:

local stages  = {}
local shipped = sqlite3.open(DIR .. "art/stages.db", sqlite3.OPEN_READONLY)

for row in shipped:nrows("SELECT name, waitMin, waitMax FROM stages ORDER BY id") do
    stages[#stages + 1] = row
end
shipped:close()

DIR is your game’s folder, where the art is. sqlite3.OPEN_READONLY says you only mean to read it, and that matters for the day you ship. When you pack your game into one file in the next lesson, a database opened read only is read straight out of that file, with nothing unpacked. One opened for writing is copied, once, to the game’s data directory, and the copy is what you change from then on; the file you shipped is never written.

So keep the two kinds apart. What you made goes in your folder and is opened read only. What the game makes goes in the data directory. The stages here are read once at the start into an ordinary table and the database is closed, because a list of four stages is not worth keeping a file open for.

Closing Up

Statements and databases hold memory and a file open until you say you are finished, and the tidy place to say it is onShutdown:

function onShutdown()
    addRun:finalize()
    runs:close()
end

finalize is close for a statement. A database will not close while a statement made from it is still around, so the statements go first.

The Whole Script

Make a folder called runs, copy the book’s art folder into it for stages.db, and put this in runs.singe:

dofile("Singe/Framework.singe")

local sqlite3 = require("sqlite3")

local PERFECT = 1000

-- What ships with the game:  the stages, read once and closed.
local stages  = {}
local shipped = sqlite3.open(DIR .. "art/stages.db", sqlite3.OPEN_READONLY)

for row in shipped:nrows("SELECT name, waitMin, waitMax FROM stages ORDER BY id") do
    stages[#stages + 1] = row
end
shipped:close()

-- What the game writes:  every run anybody plays, kept in the data directory.
local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

runs:exec([[
    CREATE TABLE IF NOT EXISTS runs (
        id    INTEGER PRIMARY KEY,
        stage TEXT    NOT NULL,
        score INTEGER NOT NULL,
        at    INTEGER NOT NULL
    )
]])

local addRun   = runs:prepare("INSERT INTO runs (stage, score, at) VALUES (?, ?, ?)")
local stageAt  = 1
local state    = "attract"
local goAt     = 0
local score    = 0
local best     = {}
local perStage = {}
local played   = 0


-- The questions, asked when a run is added rather than every frame.
local function refresh()
    best = {}
    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do
        best[#best + 1] = row
    end
    perStage = {}
    for row in runs:nrows("SELECT stage, MAX(score) AS top, COUNT(*) AS tries FROM runs GROUP BY stage ORDER BY stage") do
        perStage[#perStage + 1] = row
    end
    for count in runs:urows("SELECT COUNT(*) FROM runs") do
        played = count
    end
end


local function record(stage, points)
    addRun:bind_values(stage, points, os.time())
    addRun:step()
    addRun:reset()
    refresh()
end


local function play()
    local stage = stages[stageAt]

    state = "waiting"
    goAt  = singeGetTicks() + math.random(stage.waitMin, stage.waitMax)
    score = 0
end


function onInputPressed(what)
    if what == SWITCH_BUTTON2 and state ~= "waiting" and state ~= "go" then
        stageAt = stageAt % #stages + 1
        return
    end
    if what ~= SWITCH_BUTTON1 then
        return
    end
    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)
    elseif state == "go" then
        score = math.max(0, PERFECT - (singeGetTicks() - goAt))
        state = "result"
        record(stages[stageAt].name, score)
    else
        play()
    end
end


function onOverlayUpdate()
    if state == "waiting" and singeGetTicks() >= goAt then
        state = "go"
    end

    overlayClear()
    overlayPrint(2, 0, "REACTION TEST:  " .. stages[stageAt].name)

    if state == "attract" then
        overlayPrint(2, 2, "Button 1 to play, button 2 for another stage.")
    elseif state == "waiting" then
        overlayPrint(2, 2, "Wait for it...")
    elseif state == "go" then
        overlayPrint(2, 2, "NOW!")
    else
        overlayPrint(2, 2, "You scored " .. score .. ".  Button 1 plays again.")
    end

    overlayPrint(2, 4, "Runs kept:  " .. played)
    overlayPrint(2, 6, "BEST RUNS")
    for place, row in ipairs(best) do
        overlayPrint(2, 6 + place, string.format("%d.  %-8s %4d", place, row.stage, row.score))
    end
    overlayPrint(24, 6, "BY STAGE")
    for line, row in ipairs(perStage) do
        overlayPrint(24, 6 + line, string.format("%-8s best %4d of %d", row.stage, row.top, row.tries))
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    addRun:finalize()
    runs:close()
end


refresh()

Run it with Singe -R runs. Button 1 starts a round and stops it, as in lesson twenty-eight, and button 2 between rounds moves to the next stage. Play a few on each. Then quit and run it again: every run is still there, the best five at the left and each stage’s best at the right.

What Just Happened

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

Two files are in play, and they are not alike. art/stages.db is yours: you wrote it, it ships with the game, and the game only reads it. runs.db is the game’s: it did not exist until the first run made it, it lives in the data directory, and nobody ships it.

    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)

A button pressed too soon still records a run, with a score of nothing. The database is a record of what happened, and a jumped start happened. Whether to show those rows is a question for the SELECT, not something to hide by never writing them.

    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do

ORDER BY score DESC, id sorts by score, and where two scores are equal, by id — the order they were played. Without the second key, two equal scores come back in whatever order SQLite finds convenient, which can change between runs. A table that reshuffles itself for no visible reason looks broken even when it is not.

Try It

  1. Show the date. os.date("%Y-%m-%d", row.at) turns a stored time back into something a person can read. Add the date to each of the best runs.

  2. Ignore the jumped starts. Add WHERE score > 0 to the best-runs question, between FROM runs and ORDER BY. Then count the jumped starts on each stage with a question of your own.

  3. Add a stage. Open stages.db in a SQLite tool, add a row, and run the game. Nothing in the script changes. That is the point of keeping data out of the script.

  4. Reset the history. runs:exec("DELETE FROM runs") empties the table. Put it on a button, call refresh after it, and watch everything go to nothing. This is the "clear high scores" in a service menu.

  5. Write a thousand rows. Loop record a thousand times and time it with singeGetTicks. Then put runs:exec("BEGIN") before the loop and runs:exec("COMMIT") after it, and time it again. A transaction makes many writes one, and the difference is large enough to be worth remembering.

Break It on Purpose

Take addRun:reset() out of record and play three rounds on three different stages.

No error. The game plays perfectly. But the table at the right says you played the first stage three times, and the best runs are three copies of your first score. bind_values could not put new values into a statement that had already run and not been reset, so it gave up — quietly, returning a number you were not checking — and step ran the statement again with the values it already had.

This is the bug that matters in this lesson, because it does not look like one. A query that fails is loud. A write that writes the wrong thing is silent, and you find it a week later in the data. When the rows in a database are not what you expect, look at the code that put them there before the code that reads them.

Put reset back, and break it the loud way: change score to scroe in the first SELECT in refresh.

Error running script:  no such column: scroe
stack traceback:
	[C]: in method 'nrows'
	runs/runs.singe:42: in local 'refresh'
	runs/runs.singe:132: in main chunk

SQLite reads the column names when it prepares the question, so a misspelled one stops the game at once, and the message names it exactly. The traceback reads from the inside out: nrows complained, refresh called it at line 42, and the script itself called refresh at line 132, the last line, as the game started. That is why it says running script rather than naming a function the engine called: it never got as far as the first frame.

What You Learned

  • A database is a file of tables; a table is rows with named columns.

  • require("sqlite3") gives you SQLite. sqlite3.open opens a file and creates it if it is missing.

  • What the game writes goes in singeGetDataPath(). What you ship goes in your folder, opened with sqlite3.OPEN_READONLY.

  • CREATE TABLE IF NOT EXISTS is safe to run every time the game starts.

  • Values go in through prepare, bind_values, step, and reset, never by gluing strings into SQL.

  • nrows hands back rows as tables; urows hands back the columns themselves.

  • ORDER BY, LIMIT, GROUP BY, MAX, and COUNT answer the questions you would otherwise write loops for.

  • Ask when the answer can change, not every frame.

  • Statements are finalized, then the database is closed, in onShutdown.

Next Time

Your game now has a folder full of things: a script, art, sounds, and a database or two. Lesson thirty turns that folder into one file a stranger can copy onto their own machine and play — and your read-only database goes with it, still opening exactly as it does now.

Lesson 30: Shipping It

The finished lesson

You have a folder. It has a script in it, some pictures, a few sounds, and the games.dat you wrote in lesson thirteen. It runs, because everything it needs is where you left it and you know where that is.

This lesson turns that folder into one file that somebody who has never met you can copy onto their machine and play. Most of it is two command lines. The rest is the part nobody teaches: what belongs in the file, whose work is in there besides yours, and how to find out whether it works anywhere but here.

One File

A finished Singe game ships as a single .game file. Packing one is:

Singe --pack MyGame MyGame.game

The first name is your game’s folder, the second is the file to write. Singe reads every file in the folder into a database and says what it did:

>>> Packed 42 files (3819204 bytes) from MyGame into MyGame.game

Run it the same way you run anything:

Singe MyGame.game

That runs the first entry in the games.dat inside it; --entry=2 runs the second, for a file holding more than one game. To install it, the player copies MyGame.game next to the Singe program. The bundled menu finds it and lists it. There is nothing else: no installer, no archive to unpack, no folder to put in the right place.

What Packing Does to Every File Name

Nothing in your game has to change to be packed, and it is worth knowing why, because it is the thing most likely to surprise you.

Every name your game uses — dofile, require, io.open, spriteLoad, soundLoad, fontLoad, videoLoad, a framefile, a controls.cfg — goes through one lookup. For a loose folder, that lookup is the ordinary filesystem. For a packed game, the name is tried in three places and the first hit wins:

  1. a loose folder named like the file without its extension — MyGame/ beside MyGame.game;

  2. the game’s data directory, under files/, which is where anything the game writes has landed;

  3. the database itself.

Inside the database, names are matched without regard to capital letters, with either kind of slash, and relative to the game’s root. A leading folder name equal to the game’s own is ignored, so MyGame/art/spaceship.png, art/spaceship.png, and DIR .. "art/spaceship.png" all find the same file.

Two rules follow from that, and if you have been following the book you already obey both. Use DIR for everything you load, so a name never depends on where Singe was started. And write only under singeGetDataPath(), which is where saveSet already puts things — a packed game is opened read only and is never written to, so a game that saves beside itself works loose and fails packed.

Two names go somewhere else on purpose. Anything beginning with Singe/ stays on the real filesystem, so dofile("Singe/Framework.singe") keeps working, and so does the data directory. And a name with .. in it that tries to climb out of the game resolves nowhere at all: io.open hands back nil and a message saying the name reaches outside the game, and spriteLoad and its relatives report the file as missing.

The Loose Folder Still Wins

That first place in the list is the one you will use every day. A folder named like the packed file, sitting beside it, beats the packed copies file by file.

MyGame.game        the packed game
MyGame/            a folder with one changed file in it

Drop a single corrected art/spaceship.png in there and the packed game runs with your new picture and everything else out of the database. Nothing has to be repacked to try a change, and you can keep your whole working folder there while you finish the game. It is also how a player mods one, which you may or may not think is a feature.

Two things follow. Check your game once with that folder renamed away, or you will ship a file that only works on the machine that has the folder. And know that packing hides nothing: --unpack is a documented option and anybody can run it. Pack your game because it is one file, not because it is a locked one.

Patching a Released Game

Somebody has your game, there is a bug in one script, and you do not want to send them forty megabytes again.

Singe --patch MyGame.game fixes

fixes is a folder laid out like the game — the same names in the same places — holding only the files that changed. Files the patch does not name are left alone. The whole change is one transaction, so an interrupted patch leaves the game exactly as it was rather than half replaced.

A patch can travel as a file of its own, made with the packer:

Singe --pack fixes MyGame-1.0.2.patch
Singe --patch MyGame.game MyGame-1.0.2.patch

A .patch needs no games.dat, cannot be run, and the menu ignores it. It may also carry a removed(path) table naming files to delete, for the artwork you replaced with something under a different name. Either way, Singe checks the patched game afterwards the same way it checks a new one, so a patch cannot leave your games.dat pointing at a file that is no longer there.

And to get everything back out:

Singe --unpack MyGame.game MyGameUnpacked

What the Packer Refuses

The packer will not build a game out of just anything, and every refusal is about something that would break later. It refuses a folder with no games.dat at its root. It refuses a Framework.singe, a controls.dat, anything ending in exe, sh, bat, or cmd, and an extensionless file whose name starts with singe — in other words, a copy of the engine or its support files that wandered into your game folder. It refuses two files whose names differ only in capital letters, since the lookup cannot tell them apart. It refuses a top level entry named like the folder itself. And it checks your games.dat before it commits: every entry needs a SCRIPT, and every SCRIPT, VIDEO, CABINET, MARQUEE, and ATTRACT it names has to be a file that is actually in there. A bad path is reported with the entry’s title and nothing is written.

Each complaint names the file, and there is a list of them rather than the first one, so one run tells you everything to fix.

What to Include and What to Leave Out

Look in your game folder. Some of what is in it is the game, and some of it is how the game got made.

Ship: the script and anything it loads, the games.dat, the artwork the menu shows (CABINET, MARQUEE, and the ATTRACT clip), your credits and license files, and a read-me if you have one.

Leave out: the drawings you exported the artwork from, the takes of the sound you did not use, your notes, test scripts, screenshots, anything named old or backup, the data folder with your own saves and your own high scores in it, and anything you would not want a stranger reading. All of it packs perfectly well, which is the problem: it goes out with the game and it is one --unpack away from anybody.

The reliable way to find out what you actually shipped is to unpack it into an empty folder and look. Do that once for every release. It takes a minute and it is the only check that sees what you forgot rather than what you remember.

Credits and Licenses

If any art, sound, music, or font in your game was made by somebody else, you are shipping their work, and the terms they gave it under are an obligation rather than a courtesy. This is not a formality and it is not about lawyers: a person made that thing and asked for one specific thing in return, usually their name.

Keep a record while you work, not at the end. A plain text file in the game folder with one line per item: what the file is, where it came from, who made it, what license, and what that license requires. Writing it as you go takes seconds. Reconstructing it the night before a release, from a browser history, is how credits get left out.

A few things worth knowing before you need them. "Free to download" is not a license; look for the actual terms. Creative Commons BY means you must give the named credit, and it has no exception for games. CC0 and public domain ask nothing, and crediting anyway costs you a line. Fonts carry their own licenses, and some allow embedding while others do not. Music from a video is almost never yours to use. Anything generated by a tool is only as clean as the tool’s terms.

Then put the credits somewhere a player can reach them, inside the game. Not only in a text file next to it — a packed game is one file and the text file is inside it, where nobody will look. The script at the end of this lesson is that screen.

Singe’s own Singe/LICENSES is the shape to copy: one line per library, with its version, its license, and where it came from. Your game’s list will be shorter and the job is the same.

A Version Number That Means Something

Your game will have a second release. The first one will be out there for as long as the internet lasts, and somebody will send you a bug report about it with no idea which version they have.

So pick a number, put it where a player can read it, and never reuse one. Three parts is the common shape — 1.0.2 — and what the parts mean matters less than that they only ever go up. Raise the last one for a fix, the middle for something new, the first when you have made a different game. Whatever you choose, write it down in your read-me so that future you obeys it too.

games.dat has no version key, so the number is yours to carry. Put it in the script as a constant, show it on the credits screen, and put it in the name of what you send out (MyGame-1.0.2.game, MyGame-1.0.2.patch). Then the bug report says the version on the screen, and you know which files it is about.

Testing on a Machine That Is Not Yours

Your machine is the worst possible place to test a release. It has the fonts you installed, the folder you were editing, the save file with your settings in it, and the engine in whatever state a month of work left it.

The minimum test, in order:

  1. Unpack the release into an empty folder and read the file list.

  2. Copy only the .game file to a different folder, with a fresh copy of Singe and nothing else, and run it from the menu the way a player will.

  3. Delete that folder’s data directory and run it again. That is a first run on a new machine: no saved settings, no high scores, no signed-in account. A game that only works on its second run is a common bug and this is how you find it.

  4. Give it to one person who has never seen it, and watch without helping.

Then test the machine as well as the game. It will have a different screen shape, so look at your game windowed and full screen. It may have no 3D device at all, which is why the menu has a second renderer. The service tools' System Information page lists the engine version, the operating system, the processor, the renderer, the decoders, and the data directory on one screen; a photograph of that page answers most of a bug report, and telling your players that in your read-me will save you a week of guessing.

The Script

A credits and version screen. It is a small thing to write and it is the part of shipping that most games get wrong.

dofile("Singe/Framework.singe")

local GAME_NAME    = "Rock Dodger"
local GAME_VERSION = "1.0.2"

local CREDITS = {
    "Written and drawn by   <your name here>",
    "",
    "Music                  \"Night Drive\" by A. Composer",
    "                       Creative Commons BY 4.0",
    "                       example.org/night-drive",
    "",
    "Explosion              freesound.org user \"thud\"",
    "                       Creative Commons CC0",
    "",
    "Font                   FreeSansBold",
    "                       GPL with the font exception",
    "",
    "Engine                 Singe " .. SINGE_VERSION_STRING,
    "                       GPL version 3",
    "                       See Singe/LICENSES for the",
    "                       libraries Singe is built on.",
    "",
    "Thank you for playing.",
}

local FIRST_ROW = 4
local ROWS      = 10

local scroll = 0


local function scrollBy(lines)
    local most = #CREDITS - ROWS

    if most < 0 then
        most = 0
    end
    scroll = scroll + lines
    if scroll < 0 then
        scroll = 0
    end
    if scroll > most then
        scroll = most
    end
end


function onInputPressed(what)
    if what == SWITCH_UP then
        scrollBy(-1)
    elseif what == SWITCH_DOWN then
        scrollBy(1)
    elseif what == SWITCH_BUTTON1 then
        scroll = 0
    end
end


function onOverlayUpdate()
    local line = nil

    overlayClear()
    overlayPrint(2, 0, GAME_NAME .. "  version " .. GAME_VERSION)
    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then
            overlayPrint(2, FIRST_ROW + row, line)
        end
    end

    overlayPrint(2, FIRST_ROW + ROWS + 1, "Saves go to:")
    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())
    overlayPrint(2, 17, "Up and down scroll.  Button 1 goes back to the top.")

    return OVERLAY_UPDATED
end

Replace every line of CREDITS with the truth about your own game. The placeholders are there to show the shape: what it is, who made it, what license, and where it came from.

What Just Happened

local GAME_VERSION = "1.0.2"

One place, at the top, in capitals because it never changes while the game runs. Everything that shows the version reads this, so raising it is one edit rather than a search.

    "Music                  \"Night Drive\" by A. Composer",

Those backslashes are the escape you met in lesson one: a double quote that belongs to the text rather than ending the string. Titles have quotes in them, which is why a credits list runs into this on its first line.

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then

Ten rows of screen showing ten lines out of a list that is longer than ten. scroll is how far down the list the window has moved. The + 1 is because Lua counts a list from one and the screen rows count from zero, and the if line then is because the end of the list is nil — reading past the end of a table is not an error in Lua, it just gives you nothing, and printing nothing would be.

    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

Three facts a bug report needs and a player cannot otherwise find: your version on the line above, the engine’s version, and the game’s id. SINGE_VERSION_STRING is a global the engine sets before your script runs. or "none" covers the case where the game has no games.dat entry, so the line prints instead of crashing on a nil.

    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())

Where this game writes. On a packed game that is the only place anything is written, and it is the folder a player deletes to start clean. Showing it turns "where are my saves" into a sentence you never have to answer.

If that path runs off the right of the screen, it is not broken: overlayPrint drops the characters that would go past the edge. The default overlay is sixty character cells wide.

Try It

  1. Pack it. Put this script in your game folder, run --pack, and run the .game file. Then unpack it into an empty folder and read the list of what came out.

  2. Override one file. Beside the packed file, make a folder named like it without the extension, and put one changed file inside. Run the packed game and watch your loose file win.

  3. Make a patch. Change the version to 1.0.3, put only the script into a fixes folder, pack that as a .patch, and apply it to the game you already made. Check the version on screen.

  4. Break the packer. Rename your games.dat for a moment and try to pack. Then put it back, point one of its SCRIPT names at a file that is not there, and try again. Two different refusals, both before anything is written.

  5. Write the real credits. Go through your game’s folder file by file and write a line for each one you did not make. If you cannot remember where something came from, that is the answer to whether you should be shipping it.

Break It on Purpose

Run Singe once from inside your game folder, so the engine unpacks its support files there, and then pack it:

Singe --pack MyGame MyGame.game
!!! MyGame has Framework.singe:  Singe/Framework.singe
!!! MyGame has sh file:  Menu.sh

Nothing is written. Each line is the file it will not take and why, and you may get them in either order or get others besides. There is a copy of the engine’s own support folder inside your game, and the launcher script the engine wrote beside it, because you ran Singe from in there at some point. A game must never carry either one: the support files belong to whatever Singe the player is running, not to your game, and a packed Framework.singe would be loaded in place of theirs. On Windows the second line names Menu.bat instead.

Delete the Singe folder and Menu.sh (or Menu.bat) from inside your game, keep your game folder as one folder beside the Singe program rather than around it, and pack again. This is the same layout lesson thirteen described, and this error is what happens when it slips.

What You Learned

  • Singe --pack folder name.game turns a game folder into one file, and copying that file beside the Singe program installs it.

  • Every file name inside a packed game is looked up in a loose folder first, then the data directory, then the database.

  • A loose folder named like the packed file overrides it file by file, which is how you keep working — and how you ship a broken release if you forget it is there.

  • Load with DIR and write only under singeGetDataPath(), or your game will work loose and fail packed.

  • --patch replaces files in a released game in one transaction; --unpack writes everything back out.

  • The packer refuses engine files, name clashes, and a games.dat that points at files it does not have.

  • Unpack your own release and read what is in it before you send it anywhere.

  • Somebody else’s art and sound come with terms, and meeting them means a credits screen inside the game.

  • A version number only ever goes up, and it belongs on the screen.

  • Test on a machine that is not yours, starting with no data folder at all.

Next Time

One file, installed, credited, and numbered. The last lesson puts it in a wooden box with a coin slot and no keyboard, which changes more about your game than you would think.

Lesson 31: In a Cabinet

The finished lesson

There is a difference between a game and an arcade machine, and it is not the wood. A machine switches itself on in the morning, plays to an empty room, takes a coin from somebody who has never read a word about it, and is still running at midnight with nobody having touched a keyboard, because there is no keyboard. Everything in this lesson comes from that.

You do not need a cabinet to do any of it. A stick and two buttons on a desk, or a gamepad, is enough to find every mistake in this lesson, and most of what you learn here makes a game better on a desktop too.

There Is No Keyboard

Start with what is missing, because it is the thing that breaks games.

A cabinet has a stick, some buttons, a coin door, a start button, and somewhere inside it a small switch an operator can reach. That is all. No Escape, no letters, no mouse, no way to type. So:

  • Every menu in your game has to be reachable with up, down, and a button. If any screen in your game says "press Y to continue", it does not work in a cabinet.

  • Entering initials is three buttons and a letter that scrolls, not a text field. That is why arcade games have three letter names.

  • A prompt that names a key by its letter is wrong. Say "button 1", or draw the button.

  • There is no way out. A player cannot quit, and should not be able to.

Go through your game once, screen by screen, and ask of each: could somebody get through this with a stick and one button? That pass on your own game is worth more than the rest of this lesson.

controls.cfg

Since lesson three you have been reading input as SWITCH_UP, SWITCH_BUTTON1, SWITCH_COIN1, and the rest, and you have never once said which key those are. That is the point of them. Somewhere between the microswitch in the cabinet and your onInputPressed is a file that decides, and your game is not in that conversation.

The file is controls.cfg. It is Lua, like your script, and it is a list of tables — one per switch — naming everything that can produce it:

INPUT_1P_START = { SCANCODE.MAIN_1, GAMEPAD_0.BUTTON_START }
INPUT_1P_COIN  = { SCANCODE.MAIN_5, GAMEPAD_0.BUTTON_LEFT_BUMPER }
INPUT_ACTION_1 = { SCANCODE.LCTRL, GAMEPAD_0.BUTTON_A }
INPUT_UP       = { SCANCODE.UP, GAMEPAD_0.DPAD_UP, GAMEPAD_0.AXIS_LEFT_Y_U }

Each INPUT_ name in the file becomes the matching SWITCH_ value in your game: INPUT_ACTION_1 is the SWITCH_BUTTON1 you have been testing for, and INPUT_1P_COIN is SWITCH_COIN1. Every entry in a table produces the same switch, so a game does not care whether the player pressed the key, the pad button, or pushed the stick.

You do not have to write the whole file. Singe starts with its own defaults and reads controls.cfg from four places in turn — the game’s script folder, the folder Singe was started in, the folder above the game’s data directory, and the game’s data directory — and each one it finds overrides what came before, key by key. So a cabinet has one file at the top for the whole machine, and a game that needs one extra button has a four line file of its own. There is a controls.cfg.example in the Singe folder to copy from.

DEAD_ZONE is in there too: how far a stick has to move before it counts as pressed, in the raw units the hardware reports, where full deflection is 32767. The default is 15000. A worn stick that creeps needs a bigger number, and DEAD_ZONES sets one axis at a time for the one stick that is tired. The manual’s section on customizing the controls covers all of it.

Every Device Is a Gamepad

An arcade cabinet’s buttons are wired to an encoder board, which the computer sees as some kind of joystick, and it is nothing like an Xbox pad. Singe writes a mapping for a device like that itself and then opens it as GAMEPAD_0, so it reaches controls.cfg and your game exactly as a recognized pad does. There is one family of device and no second vocabulary to learn.

The mapping it invents is a straight one: the board’s buttons in order become BUTTON_A, BUTTON_B, BUTTON_X, BUTTON_Y and so on. If your cabinet’s buttons are not wired in that order, they will come out in the wrong places, and the fix is not in your game: --program traces the mapping Singe wrote in a form you can edit and put in a gamecontrollerdb.txt beside the game.

When a button "does nothing", the menu’s Input Test tool answers the question in five seconds. It shows every device the engine can see, and the last switch a game would have been given. Either the switch arrives and your game is ignoring it, or it never arrives and the problem is the mapping or the wire.

Four Switches Are Not Yours

Most switches go straight to your game. Four do not: the engine acts on pause, quit, screenshot, and the mouse grab toggle itself.

Pause is genuinely useful for free. While the engine owns it, the key mapped to INPUT_PAUSE freezes everything — the disc, every video, every sound, and your script — draws its own indicator, and thaws again on the next press. Anything your game thought was held down is released properly and pressed again afterwards, so a stick held through a pause never sticks.

Quit is the one to take away, which a later section does.

Coins, Credits, and Start

An arcade machine has a shape older than any of us, and players know it without being told:

  1. Attract. Nobody is there. The machine shows what it is, blinks INSERT COIN, and asks for nothing.

  2. Credit. A coin arrives as SWITCH_COIN1. Coins become credits at whatever rate the operator set — not always one for one.

  3. Play. SWITCH_START1 spends a credit and starts.

  4. Game over. The score, briefly, and back to attract on its own. Nobody presses anything to leave; the player has walked away.

Two details people get wrong. Coins are counted, not spent: at two coins per credit, one coin has to sit there waiting for its partner, and a player who put one in and walked off has left it for the next person. And the machine must find its own way back to attract, because the last thing a player does is stop playing.

Behind the Service Switch

Inside the coin door there is a button that the player never sees and the operator uses constantly. It is SWITCH_SERVICE, and the engine hands it straight to you.

An operator opening your service menu expects to find, roughly in this order:

  • the price — coins per credit, and a free play setting for a machine at home or at a show;

  • the difficulty, because a machine in a bar and a machine in an arcade want different answers;

  • a way to clear the high score table, which is the single most requested thing in this list;

  • what the machine is — the engine version, the screen, where the data lives — so a fault report has facts in it;

  • a way out, without turning anything off.

Everything an operator changes has to survive the power being cut, which in an arcade means cut in the middle of a play, without warning, by somebody pulling a plug. saveSet writes at the end of the frame, which is soon enough for a score and not soon enough for a setting somebody just adjusted. saveFlush() writes immediately, and a service menu is exactly what it is for.

The bundled menu’s own service tools, behind the same switch, are worth knowing since they are on every machine your game will run on: the input test, the sound and light gun tests, the display geometry, the audio delay, the online account, and a page that deletes any one game’s saved data. Yours does not have to duplicate them.

A Machine That Starts Itself and Never Quits

The cabinet is switched on at the wall. Nobody logs in. A game must be on the screen in a minute or so and stay there.

Getting Singe to run at power on is your operating system’s job rather than Singe’s — the machine starts the Menu.sh or Menu.bat that the engine writes beside your games, or your game directly. What is your job is what happens for the rest of the day.

Take the quit key away:

singeSetQuitKeyEnabled(false)

The engine then ignores the switch mapped to INPUT_QUIT and delivers it to you as SWITCH_QUIT like any other, so you can ask first, save first, or do nothing at all. The window’s close button always quits, whatever you set, which matters in a minute.

Then a handful of options belong to the machine rather than to your script, and go in a settings.cfg beside the games — the same names as the command line options, with the dashes removed:

fullscreen  = true
screen      = 2
idleexit    = 900
startsilent = true

idleexit quits after that many seconds with no input of any kind, for a cabinet that should hand the screen back to a menu or a front end. startsilent starts muted until somebody touches something, which is how a room full of machines is bearable. There are more; the manual’s settings and command line sections list every one.

Artwork Round the Picture

A real cabinet has a printed bezel around the screen: artwork with a hole in it that the game shows through. Singe draws one for you.

Singe --bezel cabinet.png MyGame.game

The file is looked for in a bezels folder inside the game — a packed game can carry its own — and then in a bezels folder in the data directory, so a player can put their own artwork on a game without touching it. Beside the image, named after it, a small Lua file says where the picture goes, in the artwork’s own pixels:

-- bezels/cabinet.cfg
CUTOUT = { x = 200, y = 120, width = 800, height = 500 }

Because those numbers are the artwork’s own, they stay right at any window size: the image and the hole scale together. With no such file the picture keeps the whole window as it always has.

By default the artwork is behind everything and your game covers the hole. --bezelflip puts it in front instead, so only its transparency lets the game through, which is what you want for soft or shaped edges — and then your overlay is underneath it too, unless you say otherwise:

if mainBezelLoaded() then
    setOverlayOnTop(true)
end

mainBezelLoaded() also tells you whether there is artwork at all, which is how a game decides to draw its own frame when there is none.

A Monitor on Its Side

Plenty of arcade monitors are mounted vertically. Turn the whole presentation:

Singe --rotate=90 MyGame.game

The picture, the overlay, any GUI, a 3D scene, and the particles all turn together, and mouse and light gun positions are turned back, so a click still lands where the player sees it. A quarter turn also swaps the shape of the area, so a tall window is filled rather than letterboxed into a strip.

Only 0, 90, 180, and 270 are accepted. A script can change it while running with vldpSetRotate, which answers false for anything else rather than ending your game, and vldpGetRotate() reads it back — which is worth putting on a service screen, since "the picture is sideways" and "the monitor is sideways" are different faults.

What rotation does not do is rewrite your game. A game drawn for a wide screen, turned ninety degrees, is a wide game on its side. Designing for a tall screen means designing for a tall screen.

The Script

The whole shape: attract, coin, credit, play, game over, service, and a quit that asks. The game in the middle is one button and a fifteen second timer, because the game is not the point this time — the machine around it is.

dofile("Singe/Framework.singe")

local ROUND_MS  = 15000
local MENU      = { "Coins per credit", "Difficulty", "Free play", "Clear high score", "Exit service" }
local HARDNESS  = { "Easy", "Normal", "Hard" }

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)
local best           = saveGet("best", 0)

local state    = "attract"
local goBackTo = "attract"
local coins    = 0
local credits  = 0
local score    = 0
local endsAt   = 0
local item     = 1
local saying   = ""
local hasBezel = false


local function wrap(value, low, high)
    if value < low then
        return high
    end
    if value > high then
        return low
    end
    return value
end


local function canStart()
    return freePlay or credits > 0
end


local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end


local function startGame()
    if not freePlay then
        credits = credits - 1
    end
    score  = 0
    endsAt = singeGetTicks() + ROUND_MS
    state  = "play"
end


local function endGame()
    if score > best then
        best = score
        saveSet("best", best)
    end
    saveFlush()
    endsAt = singeGetTicks() + 5000
    state  = "over"
end


local function settingOf(which)
    if which == 1 then
        return tostring(coinsPerCredit)
    elseif which == 2 then
        return HARDNESS[difficulty]
    elseif which == 3 then
        if freePlay then
            return "on"
        end
        return "off"
    elseif which == 4 then
        return tostring(best)
    end
    return ""
end


local function adjust(step)
    if item == 1 then
        coinsPerCredit = wrap(coinsPerCredit + step, 1, 4)
        saveSet("coinsPerCredit", coinsPerCredit)
    elseif item == 2 then
        difficulty = wrap(difficulty + step, 1, #HARDNESS)
        saveSet("difficulty", difficulty)
    elseif item == 3 then
        freePlay = not freePlay
        saveSet("freePlay", freePlay)
    end
    saveFlush()
end


local function serviceInput(what)
    if what == SWITCH_UP then
        item = wrap(item - 1, 1, #MENU)
    elseif what == SWITCH_DOWN then
        item = wrap(item + 1, 1, #MENU)
    elseif what == SWITCH_LEFT then
        adjust(-1)
    elseif what == SWITCH_RIGHT then
        adjust(1)
    elseif what == SWITCH_BUTTON1 then
        if item == 4 then
            best = 0
            saveSet("best", 0)
            saveFlush()
            saying = "High score cleared."
        elseif item == 5 then
            state = goBackTo
        end
    elseif what == SWITCH_BUTTON2 or what == SWITCH_SERVICE then
        state = goBackTo
    end
end


function onInputPressed(what)
    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

    if state == "confirm" then
        if what == SWITCH_BUTTON2 then
            state = goBackTo
        end
        return
    end

    if state == "service" then
        serviceInput(what)
        return
    end

    if what == SWITCH_SERVICE then
        goBackTo = state
        saying   = ""
        state    = "service"
        return
    end

    if what == SWITCH_COIN1 then
        insertCoin()
        return
    end

    if state == "play" then
        if what == SWITCH_BUTTON1 then
            score = score + 10 * difficulty
        end
        return
    end

    if what == SWITCH_START1 and canStart() then
        startGame()
    end
end


local function drawAttract()
    overlayPrint(2, 2, "ROCK DODGER")
    if canStart() then
        overlayPrint(2, 4, "PRESS START")
    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end
    overlayPrint(2, 6, "High score  " .. best)
end


local function drawService()
    overlayPrint(2, 0, "SERVICE MENU")
    for row, name in ipairs(MENU) do
        if row == item then
            overlayPrint(1, row + 1, ">")
        end
        overlayPrint(3, row + 1, name)
        overlayPrint(24, row + 1, settingOf(row))
    end
    overlayPrint(2, 8, saying)
    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())
    if hasBezel then
        overlayPrint(2, 11, "Bezel artwork loaded.")
    else
        overlayPrint(2, 11, "No bezel artwork.")
    end
    overlayPrint(2, 12, singeGetDataPath())
    overlayPrint(2, 16, "Up/Down choose.  Left/Right change.  Button 1 does it.")
    overlayPrint(2, 17, "Button 2 or the service switch leaves.")
end


function onOverlayUpdate()
    overlayClear()

    if state == "play" and singeGetTicks() >= endsAt then
        endGame()
    elseif state == "over" and singeGetTicks() >= endsAt then
        state = "attract"
    end

    if state == "service" then
        drawService()
    elseif state == "confirm" then
        overlayPrint(2, 2, "QUIT THIS GAME?")
        overlayPrint(2, 4, "Quit again to quit.  Button 2 stays.")
    elseif state == "play" then
        overlayPrint(2, 2, "SCORE  " .. score)
        overlayPrint(2, 3, "TIME   " .. ((endsAt - singeGetTicks()) // 1000))
        overlayPrint(2, 5, "Button 1 scores.  " .. HARDNESS[difficulty] .. ".")
    elseif state == "over" then
        overlayPrint(2, 2, "GAME OVER")
        overlayPrint(2, 4, "You scored " .. score .. ".")
        overlayPrint(2, 6, "High score  " .. best)
    else
        drawAttract()
    end

    if state ~= "service" then
        overlayPrint(2, 17, "CREDITS " .. credits .. "   COINS " .. coins .. "/" .. coinsPerCredit)
    end

    return OVERLAY_UPDATED
end


singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()
if hasBezel then
    setOverlayOnTop(true)
end

Run it and press 5 for a coin, 1 for start, and 9 for the service switch — those are the defaults in the shipped controls.cfg. Then press Escape, and read what it says before you press it again.

What Just Happened

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)

The operator’s settings are read once, at the top, with a sensible value for a machine that has never been set up. saveGet with a second argument hands back that value when nothing was saved, which is how a first run is told from a later one.

local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end

Coins in, credits out, at whatever rate the operator set. The while rather than an if is not caution about impossible input — it is the operator lowering the price from four coins to one while three coins are sitting in there.

    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

The quit switch reaches your game only because of the singeSetQuitKeyEnabled(false) at the very bottom of the script. Pressing it once asks; pressing it again, from the asking screen, calls singeQuit() yourself. goBackTo remembers where the player was, so saying no puts them back in their game rather than on the attract screen.

This block is first in the function and it ends in return, so nothing else can swallow the switch. Every other state in the game is handled below it.

    if state == "service" then
        serviceInput(what)
        return
    end

The same shape again. While the service menu is open, every switch belongs to it — the stick does not steer the game underneath, a coin does not land in the middle of an adjustment. One if, early, with a return. Any screen that sits on top of another one needs this, and a game that grows three of them and does not have it produces bugs that are almost impossible to describe.

        saveSet("coinsPerCredit", coinsPerCredit)
    ...
    saveFlush()

Set, then flush. Without the flush, the write happens at the end of the frame, which is fast but not immediate. An operator adjusts a setting and pulls the plug out ten seconds later, and this is the one place in a game where that actually happens.

    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end

The blink. singeGetTicks() is milliseconds since the engine started, // divides and throws away the remainder, so the number changes every four hundred milliseconds, and % 2 makes it alternate between zero and one. No variable, no timer, nothing to reset: the clock was already counting.

    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())

The operator’s half of the service page. A version, a rotation, whether there is artwork, and where the data lives. None of it is for the player, and all of it is what you will wish you had when somebody telephones you about a machine three hundred miles away.

singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()

At the bottom, outside every function, so it runs once when the script loads. Neither is a thing to do every frame, and mainBezelLoaded cannot change while the game runs.

Try It

  1. Change the price. Open the service menu, set coins per credit to two, and put one coin in. Watch the credit not appear, and watch the coin counter on the bottom line. Then quit, start it again, and see that the price stuck.

  2. Play free. Turn free play on and check that start works with no coins and that credits do not go negative.

  3. Add a page. Put a second page of service information behind button 3 — the fields of singeGetSystemInfo() are a good start, and the reference’s entry lists all of them.

  4. Turn the screen. Run it with --rotate=90 and look at your layout. Then make the service page readable at that rotation, which is harder than it sounds and is exactly the work a vertical cabinet asks for.

  5. Take the keyboard away. Unplug it, or promise yourself not to touch it, and play through every screen with a pad. Anything you cannot reach is a bug.

Break It on Purpose

Delete the SWITCH_QUIT block from onInputPressed, leaving singeSetQuitKeyEnabled(false) where it is, and run it.

Now nothing quits. Escape does nothing, Q does nothing, and your game has no way out, which is precisely what you asked for. This is not a crash and there is no message; the engine did exactly as it was told.

Close the window with its close button. That always works, whatever a script says, and it is the door you left yourself. In full screen, Alt-Enter puts you back into a window first.

It is worth feeling this one. Turning off the quit key is the only thing in this book that can leave you with a program you cannot get out of, and the habit that prevents it is simple: write the way out in the same sitting you turn the quit key off, never later.

What You Learned

  • A cabinet has no keyboard, so every screen in the game has to work with a stick and a button.

  • controls.cfg maps keys, pad buttons, and stick directions onto the SWITCH_ names your game already uses, and your game never learns which was pressed.

  • Four files of mappings are read in turn, each overriding the last, so a machine-wide file and a per-game file can both exist.

  • Every device Singe opens is a gamepad, including an arcade encoder board, and the Input Test tool says what is arriving.

  • The engine keeps pause, quit, screenshot, and mouse grab for itself; the rest are yours.

  • Coins are counted into credits at the operator’s rate, and a machine returns to attract by itself.

  • SWITCH_SERVICE is the operator’s switch, and what is behind it is the price, the difficulty, a way to clear the scores, and what the machine is.

  • saveFlush() writes a setting now, because a cabinet loses power without warning.

  • singeSetQuitKeyEnabled(false) hands the quit switch to your game. Write the way out at the same moment.

  • A bezel is artwork with a hole in it, and --rotate turns the whole presentation for a vertical monitor.

The End

That is thirty-one lessons, and you can write a game.

Not a perfect one, and not a large one yet, but the gap between here and either of those is time and practice rather than another book. You started with five lines that put a word on a black screen. You now know what a variable is, what a function is for, how to draw, how to make a noise, how to tell when two things touched, how to keep a score somewhere it survives, how to run film as a world, how to put a model in a room with a light on it, and how to hand the whole thing to a stranger.

What you need now is the Singe Reference, not this book. It is the reference to every function, every argument, and every return value, and it is the thing you will actually have open while you work. It comes with this book, as Reference.pdf and Reference.html. Read the entry before you use the call; there is a note in most of them about the mistake people make with it.

Read the scripts that come with Singe, too. Singe/Menu.singe, Singe/Tools.singe, and Singe/Framework.singe are not demonstrations written to be read — they are the menu and the service tools you have been using all along, doing real work with the same functions you have. Working out how somebody else’s program does something is a skill of its own, and those are a kind place to practice it.

And there is Forge, a separate tool with a book of its own, for describing a game rather than writing one. It is a different road. You do not need it, but it is there.

The next game is yours. Make the small one first, finish it, and put it in front of somebody. Finishing is the part nobody tells you is the hard part, and it is the only part that turns a folder full of scripts into a game that somebody played.

Go and build it.