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
4.4 KiB
Breakout
Breakout, written entirely in BASIC for the AKGL BASIC interpreter. The ball and the
paddle are sprites defined from DATA in the listing; the bricks, the HUD and the
messages are characters in the text grid.
../../../build-akgl/basic breakout.bas
It needs the SDL build. The stdio build has no graphics device, so the first RGR refuses
and the game stops there — which is exactly what it should do.
| Key | Does |
|---|---|
| left / right | move the paddle |
| space | start a game from the title screen, then launch the ball |
| P | pause |
| Q or escape | quit |
The title screen plays itself. Attract mode is a real feature and it is also how the game was tested without a hand on the keyboard.
Three lives, six rows of bricks worth 60 down to 10 points a row, three level layouts that repeat with a faster ball each time, and a high score that lasts as long as the process does.
How it works, and how to write your own
Chapter 17 of the guide builds this program in
fifteen steps you can type in one at a time, starting from an empty file: measuring the
screen, declaring every name before anything uses it, making the two sprites out of DATA,
building a text row whole, the main loop, the ball, the bounce, and the attract mode. It is
the tutorial; this is the finished thing.
Chapter 18 does the same for
../sprites, which builds the same game out of loaded artwork and comes out
a completely different program.
Known warts, this game's own
- The cell size used to be a constant.
CW#andCH#were 16, measured by hand against the bundled C64_Pro_Mono at 16 points, because BASIC had no way to ask — and it was the one thing here that would break on a different font.RGR(3),RGR(4)andRWINDOWwere added to the interpreter because of this listing, and it uses them now, so the game fits whatever window and font the host gives it. - Every character the game draws also goes to stdout, because the frontend tees the text sink to the terminal. It made the whole game auditable from a log file during development and it is pure noise the rest of the time. Redirect it.
- Collision is against the cell the ball's leading edge is in, so a brick clipped at the very corner can be missed by up to seven pixels' worth of ball. Testing the centre instead was worse: the ball sank four pixels into a brick before it turned.
- There is a stall watchdog. Ten seconds without touching a brick and the ball gets a new angle — at the next paddle bounce, never in mid-air.
- The demo cannot lose, it re-serves. It also cannot be paused;
Pis ignored until a real game starts. - Sound is asked for once and then believed. On a machine with no audio device the game is silent rather than dead.
- No high score on disk. There is no disk in this interpreter.
The interpreter defects this game turned up are filed in TODO.md §6 and §9, each with a
reduction that fits on a screen. Most are now fixed — the value pool that killed the first
version after twenty-five seconds, the unreachable WINDOW, the character written past a
short row — and the entries are struck rather than deleted, because the reduction is worth
keeping.
The listing takes the geometry fix and leaves the rest of its shape alone. Measuring
the cell instead of assuming it makes the game strictly better, so it does. Declaring
every name up front and looping with GOTO are no longer forced by anything, and are
still what the file does — its comments now say which rules stand and which are history.
How this was checked
- Parses clean under the stdio
basic(it then stops at the first graphics verb, as it should). - Attract mode run for 145 seconds and again for 110: no runtime error, score climbing throughout, 39 bricks in the second run.
- Level clear verified against a copy whose first layout is a single row:
LEVEL CLEARED, layout 2 loaded, ball speed up, play continues. - Input driven with
xdotoolagainst the real window: paddle moves and clamps at both edges, ball launches,Ppauses and unpauses, three lives drain toGAME OVER, space starts a new game,Qexits printing the final and high scores. - Every direction change logged for a whole run and read back: each one is a wall, a brick or the paddle. Nothing turns without a reason.