Andrew Kesterson
1fb808f480
Chapters 17 and 18 read as a code review of a finished listing: they explained why each decision had been made, walked through the project's own history, and led with what had once been broken. A reader who wanted to build the game got the reasoning and had to reconstruct the program. Both are now step-by-step. Each opens with a picture of the finished game and a bullet list of the steps, each bullet is a section, and each section states its goal, shows the code, and says how to check it. Chapter 17 is sixteen steps and Chapter 18 is thirteen, and the last of each is the assembly: the order of the file, the full declaration block, and the routines the earlier steps referred to. Project history is gone -- it belongs in Chapter 14 and in git -- and where a listing has to do something awkward, the tutorial shows how first and names the `TODO.md` item that will make it unnecessary second. **Three defects had no entry anywhere**, which the rewrite found by trying to state each rule as a rule. §6 item 35: `a - b + c` computes `a - (b + c)`, because `subtraction()` sits above `addition()` as its own precedence level and the inner loop eats the `+`. Item 36: only one unparenthesised `AND` or `OR` is matched, which is item 12's `if`-where-`while` on the one operator pair item 12 did not reach. Item 37: a `GOTO` out of a `FOR` or a `DO` leaks the loop's scope, so a main loop written that way stops on the thirty-second lost life -- which is why both games are built out of `LABEL` and `GOTO`, and it is a workaround rather than a preference. Chapter 3 gains the identifier rule the third trial ran into: there is no underscore in a name, and the error says `UNKNOWN TOKEN _`. **`tools/screenshot.c` learned to draw the text layer**, behind a new `text=1` fence attribute, because Chapter 17's game is characters in the grid and a figure without that layer is two sprites on black. It opens the bundled font at the size the standalone frontend uses, so a figure's cell size is the reader's cell size, and it uses the akgl sink alone rather than a tee so the program's output lands in the picture instead of on the stdout the caller reads to decide a figure failed. Both new figures -- `breakout-game.png` and `breakout-game-artwork.png` -- are generated from listings in the chapters like every other one. Verified by handing each chapter, alone, to an agent on a much smaller model and telling it to build the game from the tutorial text with the `examples/` tree off limits. The first pass scored 3.5 and 3 out of 10 and named what was missing: routines referred to but never shown, the third level layout, the sprite `DATA`, the font table, edits to earlier routines that were never marked as edits. Those are now in. The second pass built a 658-line Chapter 17 game that plays itself for ninety seconds with the score at 1890 and no error line, and the third built a 1053-line Chapter 18 game with 61 labels, no invented routines, no gaps found, and forty seconds clean. 9/10 and 8/10. One real bug in the new prose, caught in review: Chapter 18's `HITBAR` did not set the `HIT#` that `BALLPADDLE` reads to decide whether the paddle already caught the ball. Both suites green in both configurations, `docs_examples` and `docs_screenshots --check` pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Breakout, with artwork
Breakout, written entirely in BASIC for the AKGL BASIC interpreter, using downloaded CC0
sprite artwork for the paddles, the balls and the powerup gems. The bricks, the HUD and
the lettering are drawn, captured with SSHAPE and installed as sprites — because a
sprite is the one thing this interpreter puts on the screen for nothing. The text layer
owns every row of the window unless a program takes some back with WINDOW, and even
then a drawing has to be re-issued every frame; a sprite is drawn from state the
interpreter keeps.
../../../build-akgl/basic breakout.bas
It needs the SDL build. Without a graphics device the first SPRSAV refuses by name and
the program stops there, which is the right thing for it to do.
| Key | Does |
|---|---|
| left / right | move the paddle |
| space | start a game, launch the ball, release a stuck ball |
| P | pause |
| S | sound on and off |
| Q or escape | quit |
Three lives, six rows of bricks worth 60 down to 10 points a row, and a field that cycles six rows, then five, then four while the ball gets faster every level up to a ceiling. A gem is worth 50 on top of whatever it does.
The powerups
A broken brick drops a gem about one time in seven, and only ever one at a time. Catch it with the paddle. The colour of the gem is what tells you which it is; the banner that flashes over the field names it as well.
| Gem | Name | Does | For |
|---|---|---|---|
| red | EXPAND | doubles the paddle's width | 20 seconds |
| yellow | MULTI | throws two more balls off the one in play | until they are lost |
| green | SLOW | drops the ball's speed to about two thirds | 16 seconds |
| blue | STICKY | the ball sticks where it lands; space fires it | 18 seconds |
| purple | CATCH | a second bar appears higher up the field | 24 seconds |
The second bar mirrors the paddle rather than following it, so it covers the side you just left. A second bar directly above the first is worth nothing; a mirrored one turns a dive across the field into a save at both ends.
How it works, and how to write your own
Chapter 18 of the guide builds this
program in twelve steps: loading artwork, budgeting the eight sprite slots, capturing a
drawing into one, stamping the brick field, finding the host's frame boundary with TI#,
moving everything that is not drawing out of the deadline, the stroke font, the bounce
without a square root, and the gems.
Chapter 17 does the same for
../characters, which builds the same game out of the text grid and two
DATA sprites — a completely different program, and the shorter one to read first.
Where the artwork came from
Kenney's Puzzle Pack 1, released under
CC0. The files in art/ are the
pack's own PNG/Default/ versions, unmodified, with the pack's licence file beside them.
art/PROVENANCE.md says which file is used for what and why the double-size set is not.
Crediting Kenney is not required by CC0. It is here because it should be.
What is not in it
Named honestly rather than left to be discovered:
- No music under the game, only event sounds and two four-note stings. There is room in the third voice for it; there was not much room anywhere else when it was written. 121 of the interpreter's 128 variables are spoken for and the label table is at 61 of 64 — several of them spent working around defects that have since been fixed.
- One gem at a time. There is one sprite slot for it. A brick broken while a gem is falling drops nothing.
- Sticky and multiball share one offset. Two balls stuck to the paddle at once sit on top of each other. It is rare enough that fixing it would cost a variable I do not have.
- The score lags a frame behind the bricks. Only one capture happens per frame and the field goes first, so a brick disappears one frame before the score that counts it. At thirty frames a second nobody can see it, and it is a deliberate trade rather than an oversight.
- No high score on disk. There is no disk.
The eight interpreter defects this game turned up are filed in TODO.md §9, each with a
reduction that fits on a screen and the file and line of the cause. Six are now fixed
— the leaking DEF call, the skipped block that broke its caller's RETURN, the ignored
subscript on SSHAPE, GRAPHIC CLR, a negative DATA item, and half of the invisible
drawing. The two that stand are the left-operand arithmetic rule, which turned out to be a
decision rather than a defect and is now documented as one, and the 256-line batch tear,
which belongs to the host.
The listing's code is unchanged, and deliberately: it is what a program written
against those constraints looks like, and none of the workarounds costs anything now that
they are not needed. Six separate scalars for six brick stamps, and loops guarded by
GOTO rather than wrapped in a block, are both still what the file does. Its comments say
which of the five traps stand and which are marked FIXED.