Teach the artwork tutorial the converted listing

Chapter 18 still taught the machinery the listing lost when it moved onto
SOLID and the persistent drawing layer: the frame-boundary PACE routine, the
flattened live list, the SSHAPE pool accounting, and the sixty lines of
BALLBRICKS/TESTCELL that computed a minimum translation axis by hand.

Step 8 now registers each brick with SOLID, arms COLLISION 2 and reads the
contact back with RCOLLISION, including the point that costs an evening if it
is missed: the BUMP mask is by sprite, and the balls are sprites 5, 6 and 7,
so their bits are 16, 32 and 64. The FOR-with-equal-bounds rule that every
one-item case in the chapter depends on is now stated where it is first used
rather than referred to from a step that no longer exists.

The listing loses six declarations orphaned by the conversion and the comment
blocks that still described the captures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
This commit is contained in:
2026-08-02 13:13:51 -04:00
parent 39d1d0c80c
commit a01554d304
3 changed files with 248 additions and 369 deletions

View File

@@ -48,10 +48,10 @@ dive across the field into a save at both ends.
## How it works, and how to write your own
**[Chapter 18 of the guide](../../../docs/18-tutorial-breakout-artwork.md)** 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.
program step by step: loading artwork, budgeting the eight sprite slots, taking the text
layer out of the way so a drawing can be seen, stamping the brick field, registering the
bricks as collision geometry, the stroke font, the bounce without a square root, and the
gems.
[Chapter 17](../../../docs/17-tutorial-breakout.md) does the same for
[`../characters`](../characters), which builds the same game out of the text grid and two
@@ -71,18 +71,16 @@ 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 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.
the third voice for it; there was not much room anywhere else when it was written. The
conversion gave some of that room back — the variable table is under the 128 ceiling with
a handful to spare and the label table is at 57 of 64, where it was at 61.
- **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.
- **No attract mode**, unlike `../characters`. It sits on the title screen until somebody
presses space, which also means it cannot test itself unattended the way that one can.
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**
@@ -92,8 +90,14 @@ drawing. The two that stand are the left-operand arithmetic rule, which turned o
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.
**The listing has since been converted**, and its header records what went. It used to
spend two of its eight sprites on the screen itself — an `SSHAPE` of the HUD strip and one
of the whole play field, because a drawing lasted a single frame and a sprite was the only
thing redrawn for nothing. A drawing persists now, so both slots are free, the `PACE`
routine that hunted for a frame boundary is gone with the captures it protected, and the
flattened live list that made a full-field redraw cheap is gone with the redraw itself: a
broken brick is erased in place.
What has *not* changed is the shape of the workarounds that no longer cost anything — six
separate scalars for six brick stamps, loops guarded by `GOTO` rather than wrapped in a
block. Its comments say which of the five traps still stand and which are marked FIXED.

View File

@@ -145,9 +145,9 @@ DIM BRV#(6)
BRN# = 0
REM ------------------------------------------------------- shapes and dirt
REM SHN# counts the SSHAPE slots spent. There are sixteen, nothing gives
REM one back, and GRAPHIC 5 gives back all of them at once -- so the brick
REM stamps are thrown away and rebuilt every time the pool runs dry.
REM Eight of the sixteen SSHAPE slots, spent once in DRAWPROTOS and never
REM again: six brick stamps and the two erasers. Nothing captures per frame
REM any more, so the pool never runs dry and GRAPHIC 5 is never called.
REM One scalar per row colour, and scalars rather than an array because
REM SSHAPE and GSHAPE used to read the leaf they were handed without
REM applying its subscript -- a string array element always resolved to
@@ -160,8 +160,6 @@ S3$ = ""
S4$ = ""
S5$ = ""
Z$ = ""
REM 99 means the stamps are gone and have to be rebuilt before anything
REM can be drawn with them.
DHUD# = 1
DPLAY# = 1
BAN$ = ""
@@ -228,12 +226,6 @@ T3# = 0
T4# = 0
BX1# = 0
BY1# = 0
LFT# = 0
TOP# = 0
RGT# = 0
BOT# = 0
CC1# = 0
CC2# = 0
RR1# = 0
RR2# = 0
HIT# = 0
@@ -310,14 +302,10 @@ GOSUB TITLESCREEN
REM =====================================================================
REM The frame loop
REM
REM PACE first, because it is what puts the drawing at the top of a host
REM batch; then at most one capture, because a capture is the only thing
REM with a deadline; then the game, which may take as long as it likes.
REM At most one drawing job, then the game, which may take as long as it
REM likes. Nothing here has a deadline: a drawing that spans two host
REM batches simply arrives over two frames and the layer keeps both halves.
REM =====================================================================
REM No pacing. PACE spun on TI# until a batch boundary so that an SSHAPE
REM capture would not be cut in half by a present; nothing is captured now, so
REM a drawing that spans two batches simply arrives over two frames and the
REM layer keeps both halves.
LABEL FRAME
GOSUB DRAWJOB
GOSUB READKEYS
@@ -338,18 +326,17 @@ PRINT "FINAL SCORE " + SCORE# + " BEST " + HISCORE#
END
REM =====================================================================
REM One capture per frame, and only one
REM One drawing job per frame, and only one
REM
REM Rebuilding the brick stamps comes first, because everything else
REM draws with them and GRAPHIC 5 has just thrown them away.
REM The field is the expensive one -- sixty stamps and a border -- so it
REM never shares a frame with the HUD. Both are flagged rather than drawn
REM where the change happens, so a routine that changes three things costs
REM one drawing.
REM =====================================================================
REM Labels rather than BEGIN blocks here. When this was written it was not
REM a style choice -- a loop inside a block that was skipped left the
REM interpreter with no GOSUB to return from and stopped the program. That
REM is fixed; the shape is kept because it reads the same either way.
REM The stamps are built once now rather than counted and rebuilt. Nothing
REM captures per frame any more, so the sixteen SSHAPE slots are spent once and
REM stay spent -- eight of them -- and GRAPHIC 5 is never called.
LABEL DRAWJOB
LABEL DRAWJOB2
IF DPLAY# = 0 THEN GOTO DRAWJOB3
@@ -1002,10 +989,9 @@ FOR I# = 0 TO 59
BRK#(I#) = 0
NEXT I#
REM Retire the previous level's rectangles *before* laying this one out, not
REM after. This is where GOSUB BUILDLIVE used to sit, and it meant something
REM different: rebuild the list of what is standing. Left in place, the clear
REM ran after FILLROW had registered all sixty and threw them all away again --
REM which cost nothing visible and simply stopped the ball hitting anything.
REM after. Put after FILLROW it throws away all sixty rectangles that were
REM just registered, which costs nothing visible and simply stops the ball
REM hitting anything.
SOLID
FOR R# = 0 TO 5
IF R# < T3# THEN GOSUB FILLROW