Add two Breakout examples and the tutorials that build them
Two complete games in `examples/breakout/`, both 100% BASIC: `characters/`
draws its wall in the text grid with two `DATA` sprites for the ball and
paddle, and `sprites/` loads CC0 artwork and captures its whole screen with
`SSHAPE`/`SPRSAV`. They take opposite shapes for reasons that are entirely
this interpreter's, which is what the chapters are for.
`docs/17-tutorial-breakout.md` and `docs/18-tutorial-breakout-artwork.md`
build each one a step at a time, and end in a checklist of the rules a real
program runs into: create every name before the loop starts, write a text row
whole, loop with `GOTO` rather than `DO`, put the float on the left. Every
trap is a runnable block with its own output rather than a claim -- the value
pool dying at four thousand names, the skipped `BEGIN` block that breaks its
caller's `RETURN`, `SSHAPE` ignoring a subscript, `READ`'s single cursor.
Five figures, generated from the listings beside them by `docs_screenshots`,
and a `breakout_art` setup so the ones that load artwork load the example's
own. The character game's wall cannot be photographed -- the screenshot host
omits the text layer on purpose -- so it is shown as compared output instead.
`docs/07-sound.md` never said `SOUND`'s frequency is a SID register value
rather than hertz, which both games depend on. It says so now, with the
conversion from `src/audio_tables.c:84`.
`TODO.md` gains the thirteen defects the two games turned up -- §6 items 30
to 33 and all of §9 -- each with a reduction that fits on a screen, the file
and line of the cause, and what a fix would touch.
Verified: `docs_examples` passes in both build configurations,
`docs_screenshots --check` re-renders all thirteen figures and byte-compares
them, the full 109-test suite passes in both builds, every quoted fragment
was checked to appear verbatim in the listing it came from, and every
relative link and anchor resolves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 22:54:42 -04:00
|
|
|
# Breakout, with artwork
|
|
|
|
|
|
|
|
|
|
Breakout, written entirely in BASIC for the AKGL BASIC interpreter, using downloaded CC0
|
|
|
|
|
sprite artwork for the paddles, the balls and the powerup gems. The bricks, the HUD and
|
Stop the artwork breakout drawing its screen into two sprites
It captured the HUD strip into sprite 1 and the whole play field into sprite 2,
and its own header called them "the screen". That was never a choice: a drawing
lasted one frame, so a sprite was the only thing the interpreter would redraw for
nothing. Both slots are free now, and five things went with them.
**`WINDOW 0, 35, 49, 36` is the first executable line.** The text layer repaints
every row it owns and by default owns the whole window; moved to two rows at the
bottom, it leaves the other thirty-five to the drawing verbs, and what the
program draws stays.
**`PACE` is gone.** It spun on `TI#` until a batch boundary so an `SSHAPE`
capture would not be cut in half by a present. Nothing is captured, so a drawing
spanning two batches simply arrives over two frames and the layer keeps both
halves. The 256-line drawing deadline that shaped every draw routine in this
listing does not apply to it any more.
**The flattened live list is gone** -- `BUILDLIVE`, `BUILDROW`, `STAMPROW` and
the four arrays behind them. They existed so a full-field redraw could be one
stamp and an advance per brick, and a full-field redraw existed because removing
one brick meant rebuilding all sixty. A broken brick is now erased in place with
a blank stamp, so the field is drawn once per level and not again.
**`BALLBRICKS` and `TESTCELL` are gone** -- about sixty lines that turned the
ball's box into a range of candidate cells, walked them with a nested `DO`, and
computed an overlap rectangle to pick an axis. `SOLID` registers each brick as
the level is laid out, `COLLISION 2` fires, and `RCOLLISION` says which brick,
which way out, how far, and which axis to reverse.
**The `SSHAPE` pool accounting is gone.** `SHN#` counted slots because every
frame's capture spent another and `GRAPHIC 5` had to throw them all away
periodically; eight are now spent once and never again.
Three mistakes worth recording, because each was silent:
- **The bricks were registered and then immediately thrown away.**
`GOSUB BUILDLIVE` sat *after* the fill loop in `SETUPLEVEL` and meant "rebuild
the list of what is standing"; replaced in place by a bare `SOLID`, it meant
"retire everything" and ran after all sixty had been registered. Nothing
failed -- the ball simply passed through the wall.
- **The handler tested the wrong bits.** `BUMP` is a mask by *sprite*, and the
balls are sprites 5, 6 and 7, so their bits are 16, 32 and 64. Testing 1, 2 and
4 asked about the HUD and field sprites that no longer exist.
- **The eraser stamps were undeclared**, so `SSHAPE` filled them inside
`DRAWPROTOS` and they were empty everywhere else -- exactly the scope trap
chapter 17 Step 3 is about, found by printing the handle inside the routine and
again outside it.
Verified by driving it: a copy with a tracking paddle and auto-relaunch breaks
thirteen bricks in sixty seconds with no error line, and the shipped listing runs
clean. Both suites green.
Chapter 18 still describes the architecture this commit removed; that is the rest
of section 6 item 39.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
2026-08-02 12:58:08 -04:00
|
|
|
the lettering are drawn — `WINDOW` moves the text layer to two rows at the bottom, and
|
|
|
|
|
everything the program draws then stays on the screen without being redrawn or captured.
|
|
|
|
|
|
|
|
|
|
The bricks are also **collidable without being sprites**: `SOLID` registers a rectangle
|
|
|
|
|
the interpreter collides against, so sixty of them cost none of the eight slots.
|
Add two Breakout examples and the tutorials that build them
Two complete games in `examples/breakout/`, both 100% BASIC: `characters/`
draws its wall in the text grid with two `DATA` sprites for the ball and
paddle, and `sprites/` loads CC0 artwork and captures its whole screen with
`SSHAPE`/`SPRSAV`. They take opposite shapes for reasons that are entirely
this interpreter's, which is what the chapters are for.
`docs/17-tutorial-breakout.md` and `docs/18-tutorial-breakout-artwork.md`
build each one a step at a time, and end in a checklist of the rules a real
program runs into: create every name before the loop starts, write a text row
whole, loop with `GOTO` rather than `DO`, put the float on the left. Every
trap is a runnable block with its own output rather than a claim -- the value
pool dying at four thousand names, the skipped `BEGIN` block that breaks its
caller's `RETURN`, `SSHAPE` ignoring a subscript, `READ`'s single cursor.
Five figures, generated from the listings beside them by `docs_screenshots`,
and a `breakout_art` setup so the ones that load artwork load the example's
own. The character game's wall cannot be photographed -- the screenshot host
omits the text layer on purpose -- so it is shown as compared output instead.
`docs/07-sound.md` never said `SOUND`'s frequency is a SID register value
rather than hertz, which both games depend on. It says so now, with the
conversion from `src/audio_tables.c:84`.
`TODO.md` gains the thirteen defects the two games turned up -- §6 items 30
to 33 and all of §9 -- each with a reduction that fits on a screen, the file
and line of the cause, and what a fix would touch.
Verified: `docs_examples` passes in both build configurations,
`docs_screenshots --check` re-renders all thirteen figures and byte-compares
them, the full 109-test suite passes in both builds, every quoted fragment
was checked to appear verbatim in the listing it came from, and every
relative link and anchor resolves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 22:54:42 -04:00
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
../../../build-akgl/basic breakout.bas
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
It needs the SDL build. Without a graphics device the first `SPRSAV` refuses by name and
|
|
|
|
|
the program stops there, which is the right thing for it to do.
|
|
|
|
|
|
|
|
|
|
| Key | Does |
|
|
|
|
|
|---|---|
|
|
|
|
|
| left / right | move the paddle |
|
|
|
|
|
| space | start a game, launch the ball, release a stuck ball |
|
|
|
|
|
| P | pause |
|
|
|
|
|
| S | sound on and off |
|
|
|
|
|
| Q or escape | quit |
|
|
|
|
|
|
|
|
|
|
Three lives, six rows of bricks worth 60 down to 10 points a row, and a field that cycles
|
|
|
|
|
six rows, then five, then four while the ball gets faster every level up to a ceiling. A
|
|
|
|
|
gem is worth 50 on top of whatever it does.
|
|
|
|
|
|
|
|
|
|
## The powerups
|
|
|
|
|
|
|
|
|
|
A broken brick drops a gem about one time in seven, and only ever one at a time. Catch it
|
|
|
|
|
with the paddle. The colour of the gem is what tells you which it is; the banner that
|
|
|
|
|
flashes over the field names it as well.
|
|
|
|
|
|
|
|
|
|
| Gem | Name | Does | For |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| red | EXPAND | doubles the paddle's width | 20 seconds |
|
|
|
|
|
| yellow | MULTI | throws two more balls off the one in play | until they are lost |
|
|
|
|
|
| green | SLOW | drops the ball's speed to about two thirds | 16 seconds |
|
|
|
|
|
| blue | STICKY | the ball sticks where it lands; space fires it | 18 seconds |
|
|
|
|
|
| purple | CATCH | a second bar appears higher up the field | 24 seconds |
|
|
|
|
|
|
|
|
|
|
The second bar **mirrors** the paddle rather than following it, so it covers the side you
|
|
|
|
|
just left. A second bar directly above the first is worth nothing; a mirrored one turns a
|
|
|
|
|
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
|
2026-08-02 13:13:51 -04:00
|
|
|
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.
|
Add two Breakout examples and the tutorials that build them
Two complete games in `examples/breakout/`, both 100% BASIC: `characters/`
draws its wall in the text grid with two `DATA` sprites for the ball and
paddle, and `sprites/` loads CC0 artwork and captures its whole screen with
`SSHAPE`/`SPRSAV`. They take opposite shapes for reasons that are entirely
this interpreter's, which is what the chapters are for.
`docs/17-tutorial-breakout.md` and `docs/18-tutorial-breakout-artwork.md`
build each one a step at a time, and end in a checklist of the rules a real
program runs into: create every name before the loop starts, write a text row
whole, loop with `GOTO` rather than `DO`, put the float on the left. Every
trap is a runnable block with its own output rather than a claim -- the value
pool dying at four thousand names, the skipped `BEGIN` block that breaks its
caller's `RETURN`, `SSHAPE` ignoring a subscript, `READ`'s single cursor.
Five figures, generated from the listings beside them by `docs_screenshots`,
and a `breakout_art` setup so the ones that load artwork load the example's
own. The character game's wall cannot be photographed -- the screenshot host
omits the text layer on purpose -- so it is shown as compared output instead.
`docs/07-sound.md` never said `SOUND`'s frequency is a SID register value
rather than hertz, which both games depend on. It says so now, with the
conversion from `src/audio_tables.c:84`.
`TODO.md` gains the thirteen defects the two games turned up -- §6 items 30
to 33 and all of §9 -- each with a reduction that fits on a screen, the file
and line of the cause, and what a fix would touch.
Verified: `docs_examples` passes in both build configurations,
`docs_screenshots --check` re-renders all thirteen figures and byte-compares
them, the full 109-test suite passes in both builds, every quoted fragment
was checked to appear verbatim in the listing it came from, and every
relative link and anchor resolves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 22:54:42 -04:00
|
|
|
|
|
|
|
|
[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
|
|
|
|
|
`DATA` sprites — a completely different program, and the shorter one to read first.
|
|
|
|
|
|
|
|
|
|
## Where the artwork came from
|
|
|
|
|
|
|
|
|
|
Kenney's [Puzzle Pack 1](https://kenney.nl/assets/puzzle-pack-1), released under
|
|
|
|
|
[CC0](http://creativecommons.org/publicdomain/zero/1.0/). The files in `art/` are the
|
|
|
|
|
pack's own `PNG/Default/` versions, unmodified, with the pack's licence file beside them.
|
|
|
|
|
`art/PROVENANCE.md` says which file is used for what and why the double-size set is not.
|
|
|
|
|
|
|
|
|
|
Crediting Kenney is not required by CC0. It is here because it should be.
|
|
|
|
|
|
|
|
|
|
## What is not in it
|
|
|
|
|
|
|
|
|
|
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
|
2026-08-02 13:13:51 -04:00
|
|
|
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.
|
Add two Breakout examples and the tutorials that build them
Two complete games in `examples/breakout/`, both 100% BASIC: `characters/`
draws its wall in the text grid with two `DATA` sprites for the ball and
paddle, and `sprites/` loads CC0 artwork and captures its whole screen with
`SSHAPE`/`SPRSAV`. They take opposite shapes for reasons that are entirely
this interpreter's, which is what the chapters are for.
`docs/17-tutorial-breakout.md` and `docs/18-tutorial-breakout-artwork.md`
build each one a step at a time, and end in a checklist of the rules a real
program runs into: create every name before the loop starts, write a text row
whole, loop with `GOTO` rather than `DO`, put the float on the left. Every
trap is a runnable block with its own output rather than a claim -- the value
pool dying at four thousand names, the skipped `BEGIN` block that breaks its
caller's `RETURN`, `SSHAPE` ignoring a subscript, `READ`'s single cursor.
Five figures, generated from the listings beside them by `docs_screenshots`,
and a `breakout_art` setup so the ones that load artwork load the example's
own. The character game's wall cannot be photographed -- the screenshot host
omits the text layer on purpose -- so it is shown as compared output instead.
`docs/07-sound.md` never said `SOUND`'s frequency is a SID register value
rather than hertz, which both games depend on. It says so now, with the
conversion from `src/audio_tables.c:84`.
`TODO.md` gains the thirteen defects the two games turned up -- §6 items 30
to 33 and all of §9 -- each with a reduction that fits on a screen, the file
and line of the cause, and what a fix would touch.
Verified: `docs_examples` passes in both build configurations,
`docs_screenshots --check` re-renders all thirteen figures and byte-compares
them, the full 109-test suite passes in both builds, every quoted fragment
was checked to appear verbatim in the listing it came from, and every
relative link and anchor resolves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 22:54:42 -04:00
|
|
|
- **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.
|
|
|
|
|
- **No high score on disk.** There is no disk.
|
2026-08-02 13:13:51 -04:00
|
|
|
- **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.
|
Add two Breakout examples and the tutorials that build them
Two complete games in `examples/breakout/`, both 100% BASIC: `characters/`
draws its wall in the text grid with two `DATA` sprites for the ball and
paddle, and `sprites/` loads CC0 artwork and captures its whole screen with
`SSHAPE`/`SPRSAV`. They take opposite shapes for reasons that are entirely
this interpreter's, which is what the chapters are for.
`docs/17-tutorial-breakout.md` and `docs/18-tutorial-breakout-artwork.md`
build each one a step at a time, and end in a checklist of the rules a real
program runs into: create every name before the loop starts, write a text row
whole, loop with `GOTO` rather than `DO`, put the float on the left. Every
trap is a runnable block with its own output rather than a claim -- the value
pool dying at four thousand names, the skipped `BEGIN` block that breaks its
caller's `RETURN`, `SSHAPE` ignoring a subscript, `READ`'s single cursor.
Five figures, generated from the listings beside them by `docs_screenshots`,
and a `breakout_art` setup so the ones that load artwork load the example's
own. The character game's wall cannot be photographed -- the screenshot host
omits the text layer on purpose -- so it is shown as compared output instead.
`docs/07-sound.md` never said `SOUND`'s frequency is a SID register value
rather than hertz, which both games depend on. It says so now, with the
conversion from `src/audio_tables.c:84`.
`TODO.md` gains the thirteen defects the two games turned up -- §6 items 30
to 33 and all of §9 -- each with a reduction that fits on a screen, the file
and line of the cause, and what a fix would touch.
Verified: `docs_examples` passes in both build configurations,
`docs_screenshots --check` re-renders all thirteen figures and byte-compares
them, the full 109-test suite passes in both builds, every quoted fragment
was checked to appear verbatim in the listing it came from, and every
relative link and anchor resolves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 22:54:42 -04:00
|
|
|
|
|
|
|
|
The eight interpreter defects this game turned up are filed in `TODO.md` §9, each with a
|
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>
2026-08-02 00:31:06 -04:00
|
|
|
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.
|
|
|
|
|
|
2026-08-02 13:13:51 -04:00
|
|
|
**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.
|