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:
@@ -100,15 +100,21 @@ broken while a gem is falling drops nothing.
|
||||
## Step 3: Turn what you drew into a sprite
|
||||
|
||||
In the standalone SDL build the text layer repaints every row of the window, opaque,
|
||||
after your program's steps have run and before the frame is presented — so **anything
|
||||
`DRAW`, `BOX` or `CIRCLE` puts on the screen is painted over before anybody sees it**.
|
||||
Sprites are drawn after the text layer. A sprite is the only thing on the screen a
|
||||
program can rely on being visible. (`TODO.md` §9 item 3; the figures in this chapter are
|
||||
rendered by a tool that omits the text layer, which is why they can show a drawing at
|
||||
all.)
|
||||
after your program's steps have run and before the frame is presented — so by default
|
||||
**anything `DRAW`, `BOX` or `CIRCLE` puts on the screen is painted over before anybody
|
||||
sees it**. Sprites are drawn after the text layer, which makes a sprite the one thing a
|
||||
program can rely on being visible without doing anything else about it.
|
||||
|
||||
That leaves exactly one way to put a picture up: **draw it, capture it with `SSHAPE`,
|
||||
install the capture with `SPRSAV`.**
|
||||
`WINDOW 0, 0, 49, 1` would hand the rest of the window to the drawing verbs. This program
|
||||
does not, and would not want to: a drawing has to be re-issued every frame to survive
|
||||
double buffering *and* fit inside one 256-line batch to survive the capture, which is
|
||||
Step 4. A sprite has neither constraint — it is drawn from state the interpreter keeps.
|
||||
|
||||
So: **draw it, capture it with `SSHAPE`, install the capture with `SPRSAV`.** Once it is
|
||||
a sprite it stays on the screen for nothing.
|
||||
|
||||
(The figures in this chapter are rendered by a tool that draws no text layer, which is
|
||||
why they can show a bare drawing at all.)
|
||||
|
||||
```basic norun
|
||||
SSHAPE Z$, 0, 60, 800, 600
|
||||
@@ -619,8 +625,12 @@ A silenced voice costs nothing to issue. One line beats eleven scattered through
|
||||
|
||||
## Five things in this dialect that do not do what they look like
|
||||
|
||||
Each of these cost an evening. All five are filed in `TODO.md` §9 with a reduction and
|
||||
the file and line of the cause.
|
||||
Each of these cost an evening, and each was filed in `TODO.md` §9 with a reduction and
|
||||
the file and line of the cause. **Three of the five have since been fixed**, and are kept
|
||||
here as the history of why this program is shaped the way it is — a listing whose
|
||||
comments explain what it was avoiding is worth more than one quietly rewritten to pretend
|
||||
the problem never existed. The two that remain are the first and the last, and the first
|
||||
is the dangerous one.
|
||||
|
||||
### 1. The left operand decides integer or float arithmetic
|
||||
|
||||
@@ -787,6 +797,11 @@ and two four-note stings; one gem at a time; sticky and multiball share one offs
|
||||
balls stuck to the paddle sit on top of each other; and no high score on disk, because
|
||||
there is no disk.
|
||||
|
||||
**Several of these budgets were tighter when this was written.** A scalar cost a pool
|
||||
slot, a saved shape could not live in an array, and a loop inside a skipped block leaked
|
||||
a scope — so a program had to spend variables to avoid all three. The listing has not
|
||||
been rewritten to take the room back, because what it does instead is show its working.
|
||||
|
||||
## Where to go next
|
||||
|
||||
- **[Chapter 8](08-sprites.md)** is the sprite reference: every form of `SPRSAV`, the
|
||||
@@ -796,5 +811,6 @@ there is no disk.
|
||||
- **[Chapter 7](07-sound.md)** is `SOUND`, `PLAY`, `ENVELOPE` and `VOL`.
|
||||
- **[Chapter 14](14-architecture.md)** explains the step loop and the pools this chapter
|
||||
keeps running into, from the interpreter's side.
|
||||
- `TODO.md` §9 is the eight defects this game found, each with a reduction, the cause and
|
||||
what a fix would touch.
|
||||
- `TODO.md` §9 is the eight defects this game found, each with a reduction and the cause.
|
||||
Six are fixed and struck; the two that stand are the left-operand rule, which is a
|
||||
decision rather than a defect, and the batch tear, which is the host's to own.
|
||||
|
||||
Reference in New Issue
Block a user