Bring the tutorials back in line with the fixed interpreter

Eleven of the thirteen defects these two games found are fixed, and the
chapters that taught around them said things that are no longer true.

Chapter 17: the drawing verbs are no longer invisible, they are covered by a
text layer that `WINDOW` can now shrink; the cell size is `RGR(3)` and the grid
is `RWINDOW`, not a hand-measured constant; a character written past a short
row's end lands. Chapter 18: traps 3 and 4 -- the skipped block that broke its
caller's `RETURN`, and `SSHAPE` ignoring a subscript -- become history rather
than warnings, and Step 3 no longer claims a sprite is the *only* way to put a
picture up, only the one that costs nothing.

**Neither `.bas` listing changes, and both READMEs now say why.** The character
game still writes `CW# = 16` and the artwork game still keeps six brick stamps
in six scalars. What those listings are worth is being what a program written
against those constraints looks like, with comments explaining what each one was
avoiding -- rewriting them to pretend the problems never existed would throw
that away. So Chapter 17 Step 2 shows the `RGR(3)`/`RWINDOW` form and says
plainly that the listing beside it does not use it. That is the one place in
either chapter where a quoted fragment is not verbatim from the game.

Also: the closing pointers now say which entries are struck and which stand, and
the budgets table in Chapter 18 notes that several of those budgets were tighter
when the game was written.

TODO.md section 9 item 3 is updated rather than struck: the `WINDOW` half is
fixed, the default text area owning the whole window is not, and whether that
default is right is a question rather than a defect.

Verified against the fixed interpreter: both games run 45 seconds on the SDL
frontend with no error line and the score climbing; both suites are green in
both configurations; `docs_examples` passes and `docs_screenshots --check`
re-renders all thirteen figures byte-identically; coverage is 95.0% of lines
against the 90 gate, with src/variable.c at 100%; and every other quoted
fragment still appears verbatim in the listing it came from.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-02 00:31:06 -04:00
parent c3d9e91bbd
commit 91fadf032b
5 changed files with 75 additions and 30 deletions

View File

@@ -39,9 +39,10 @@ a completely different program.
## Known warts, this game's own
- **The cell size is a constant.** `CW#` and `CH#` are 16, measured with the bundled
C64_Pro_Mono at 16 points in the 800×600 window; the grid is 50×37. BASIC cannot ask —
`WINDOW` knows, but the standalone frontend never offers it. Change the font or the
window size and those two numbers have to change with them.
C64_Pro_Mono at 16 points in the 800×600 window; the grid is 50×37. When this was
written BASIC had no way to ask. It has now — `RGR(3)`, `RGR(4)` and `RWINDOW`, added
because of this listing — and the listing has not been changed to use them, because
what it demonstrates is what a program does when the interpreter will not tell 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.
@@ -56,8 +57,13 @@ a completely different program.
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 item 30 and §9, each
with a reduction that fits on a screen.
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 itself is unchanged**, and deliberately: it is what a program
written against those constraints looks like, and its comments explain what it was
working around.
## How this was checked

View File

@@ -68,9 +68,9 @@ Crediting Kenney is not required by CC0. It is here because it should be.
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 is not much room anywhere else. 121 of the interpreter's
128 variables are spoken for, four more are the ones it makes itself, and the label table
is at 61 of 64.
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
@@ -82,5 +82,13 @@ Named honestly rather than left to be discovered:
- **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, the file and line of the cause, and what a fix would
touch.
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 is unchanged**, and deliberately: it is what a program written against those
constraints looks like, and its comments explain what it was working around. Six separate
scalars for six brick stamps is no longer necessary, and it is still what the file does.