= Learn to Program with Singe Scott Duensing :revnumber: 3.00 :revdate: 2026 :doctype: book :toc: left :toclevels: 3 :title-logo-image: image:singeLogo.png[Singe, pdfwidth=2.6in, align=center] :source-highlighter: rouge :icons: font :experimental: :imagesdir: images [preface] == 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. [literal] ---- 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 Singe has a second book, _Forge_, which teaches you to make 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 to read the Forge 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 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. . *Hello* -- a script, a function, a string, and something on screen. . *Numbers That Change* -- variables, arithmetic, and making it move. . *Making Decisions* -- `if`, comparison, and reading the controls. . *Doing It Again* -- `for` and `while`, and drawing a hundred of something. . *Your Own Functions* -- arguments, return values, and why you would bother. . *Lists of Things* -- tables, `ipairs`, adding and removing. . *A Game* -- everything so far, playable, in about eighty lines. . *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. [start=9] . *Pictures* -- sprites, loading, drawing, and frames. . *Sound* -- effects, music, and when to load which. . *Hitting Things* -- collision, the game kit, and hitboxes. . *Score, Lives, and Game Over* -- state, saving, and starting again. . *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. [start=14] . *Playing Video* -- the disc, frames, seeking, and waiting. . *The Other Way to Write It* -- the threaded model, and why it suits video. . *Branching* -- choices, paths, and the shape of a branching video game. . *Light Guns* -- aiming, firing, and the calibration a cabinet needs. . *Quick-Time Events* -- prompts, windows, and scoring the player's timing. *Part Four: Everything Else.* Each lesson stands alone; take them in any order. [start=19] . *Text That Looks Good* -- fonts, quality, and measuring. . *Menus and Screens* -- the GUI, documents, and styling. . *Subtitles* -- and why they are their own system. . *Into 3D* -- scenes, cameras, and coordinates. . *Models and Light* -- glTF, materials, and animation. . *Physics* -- bodies, forces, joints, and when not to use them. . *Particles* -- emitters, and making an explosion. . *Characters That Move Themselves* -- navigation and pathfinding. . *Music and MIDI* -- tracks, soundfonts, and instruments. . *Online* -- accounts, high score tables, and the catalogue. . *Shipping It* -- packing, patching, licences, and the release. . *In a Cabinet* -- controls, service menus, bezels, and the things that only matter on real hardware. include::lessons/01-hello.adoc[] include::lessons/02-numbers.adoc[] include::lessons/03-decisions.adoc[] include::lessons/04-repeating.adoc[] include::lessons/05-functions.adoc[] include::lessons/06-tables.adoc[] include::lessons/07-a-game.adoc[] include::lessons/08-when-it-goes-wrong.adoc[] include::lessons/09-pictures.adoc[] include::lessons/10-sound.adoc[] include::lessons/11-hitting-things.adoc[] include::lessons/12-score.adoc[] include::lessons/13-game-folder.adoc[] include::lessons/14-video.adoc[] include::lessons/15-threaded.adoc[] include::lessons/16-branching.adoc[] include::lessons/17-light-guns.adoc[] include::lessons/18-qte.adoc[] include::lessons/19-text.adoc[] include::lessons/20-gui.adoc[] include::lessons/21-subtitles.adoc[] include::lessons/22-3d.adoc[] include::lessons/23-models.adoc[] include::lessons/24-physics.adoc[] include::lessons/25-particles.adoc[] include::lessons/26-navigation.adoc[] include::lessons/27-midi.adoc[] include::lessons/28-online.adoc[] include::lessons/29-shipping.adoc[] include::lessons/30-cabinet.adoc[]