230 lines
8.6 KiB
Text
230 lines
8.6 KiB
Text
= Learn to Program with Singe
|
|
Scott Duensing <scott@kangaroopunch.com>
|
|
: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 Manual_ is the reference: every function, every argument, every
|
|
return value. 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.
|
|
|
|
== 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[]
|