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:
@@ -38,10 +38,11 @@ without your program doing anything:
|
||||
- the **sprites**, walked slot by slot after it.
|
||||
|
||||
The drawing verbs are not one of them. `DRAW`, `BOX`, `CIRCLE` and `PAINT` go straight
|
||||
into the renderer's back buffer, and the text layer paints over the whole window on its
|
||||
way past — so in the standalone SDL build **nothing you draw with them is ever visible**.
|
||||
That is recorded as a defect (`TODO.md` §9 item 3) rather than a design, but it is the
|
||||
interpreter you have.
|
||||
into the renderer's back buffer, and **the text layer owns every row of the window by
|
||||
default** — so it paints over anything they drew on its way past. `WINDOW` shrinks the
|
||||
text area and gives the rest of the window to the drawing verbs, but a drawing still has
|
||||
to be re-issued every frame and has to fit in one batch to survive the capture; see
|
||||
[Chapter 13](13-differences.md#graphics).
|
||||
|
||||
So this game uses no drawing verb at all. Anything that has to move smoothly is a sprite;
|
||||
anything that can live on a 16-pixel grid is text. Ball and paddle move; bricks, score
|
||||
@@ -751,5 +752,6 @@ game against:
|
||||
differently from BASIC 7.0.
|
||||
- **[Chapter 14](14-architecture.md)** is the interpreter itself — the step loop, the
|
||||
pools and how to debug a program that stops for no visible reason.
|
||||
- `TODO.md` §6 and §9 carry the defects this game found, each with a reduction that fits
|
||||
on a screen and what a fix would touch.
|
||||
- `TODO.md` §6 and §9 carry the thirteen defects these two games found, with the
|
||||
reduction for each. Eleven have since been fixed and are struck; the entries are kept
|
||||
because the reduction and the cause are worth more than the tidiness of deleting them.
|
||||
|
||||
@@ -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