Collide sprites with rectangles that are not sprites

`SOLID id, x1, y1, x2, y2` registers static collision geometry; `SOLID id`
retires one and a bare `SOLID` retires them all, the way `TRAP`, `COLLISION` and
`DCLOSE` all read absence. `COLLISION 2` and `BUMP(2)` stop being refused and
mean *sprite met static geometry*.

**This is the thing eight sprite slots made impossible.** A wall of bricks wants
sixty, so until now a program could only collide with one by doing the
arithmetic itself against its own array -- which is exactly what both breakout
listings do, at about two hundred lines between them. A rectangle costs no sprite
slot.

The id is the **program's own number**, 1 to 64, not a minted handle. That is the
whole trick for "which brick did I hit": the id comes back out again, so a wall
built as `SOLID I#, ...` maps onto `B#(I#)` with no lookup, and retiring a broken
brick is `SOLID I#`.

`COLLISION 2` was refused with "sprite-to-background collision needs the screen
read back every frame", which was true of the question a C128 asks -- a sprite
against the bitmap's set pixels. `SOLID` gives this interpreter a background made
of rectangles instead, which is the same question in a form it can answer. Same
move `SPRSAV` made when it learned to take an image path.
`AKBASIC_INTERRUPT_BACKGROUND` has been sitting in the interrupt table commented
"COLLISION 2 -- sprite met background; refused" the whole time. Its accumulator is
separate, so a sprite hitting a wall never sets a bit in `BUMP(1)`.

**There is no `akgl_CollisionWorld` here, and that is deliberate.** libakgl's
uniform grid keeps its cell heads, cell size and origin in file-scope statics, so
it is one index per process -- and `akgl_collision_world_init()` ends in a
`reset()` that memsets those heads *and* calls
`akgl_heap_init_collision_cells()`. An interpreter embedded in a game with its
own collision world would have destroyed every registration that game had made,
on the first `SOLID` a script ran. So the geometry is indexed by an ordinary
array here and pairs go straight to `akgl_collision_test()`, which needs no
world. At sixty-four rectangles that is the right answer anyway; libakgl's own
numbers put a naive sweep at 0.7% of a frame at sixty-four objects.

**The scan now short-circuits when nothing has moved**, and that is what makes
any of it affordable. Its inputs are the sprites' boxes, which slots are
collidable, and the static geometry; if none changed the answer cannot have. A
frame runs one full scan and 255 cached ones. Eight sprites against sixty-four
rectangles is five hundred and twelve tests -- fine once a frame, ruinous 256
times.

The benchmark was rewritten to say which path it is timing, because with the
cache in place a loop that only calls the scan measures the short circuit and
nothing else. Breakout now costs 590.6 ns for its one full scan plus 255 cached
at 40.0, which is 10.8 us against a 1.19 ms frame -- **0.91%, less than the 2.0%
it cost before any of this work**, with static geometry and contacts added on
top.

`NEW` retires the rectangles, where it cannot undefine a sprite pattern: there
*is* an entry point for this one, so leaving them would be a choice, and the
wrong one -- a rectangle is invisible, so one left behind by a deleted program is
an unexplainable collision in the next. `CLR` leaves them alone.

`tests/sprite_verbs.c` gains the whole second path against the mock and its
`COLLISION 2` case is rewritten: it pinned the refusal, and now pins that type 2
arms its own handler without disturbing type 1's. `tests/akgl_backends.c` gains
the end-to-end version, including a full sixty-four-rectangle wall so the proxy
budget is exercised at its ceiling and the pool has to come back intact, and the
sixty-fifth refused by name.

A bare `SOLID` needed `akbasic_parse_optional_arglist` rather than
`akbasic_parse_arglist`, which `DCLOSE` already uses for the same shape.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL

docs/08-sprites.md

@@ -204,6 +204,60 @@ also stops it colliding, and is what you want when it should not be seen either.
 `RSPHIT(n, f)` reads it back, in `SPRHIT`'s own argument order — 0 the kind, then 1 to 4
 for the two corners. It needs no sprite device, the way `RSPPOS` does not.
 
+## Colliding with things that are not sprites
+
+There are eight sprites. A wall of bricks wants sixty, and until now the only way to
+collide with one was to do the arithmetic yourself against your own array.
+
+`SOLID` registers a rectangle the interpreter will collide sprites against, and it costs
+no sprite slot:
+
+```basic norun
+SOLID id, x1, y1, x2, y2      register or replace rectangle id
+SOLID id                      retire it
+SOLID                         retire them all
+```
+
+`id` is 1 to 64 and it is **your own number**. That is the whole trick for "which brick did
+I hit": the id comes back out again, so a wall built as `SOLID I#, ...` maps straight onto
+`B#(I#)` with no lookup. Retiring a broken brick is the same verb, `SOLID I#`.
+
+Rectangles are in window pixels — the coordinates `BOX` draws in and `MOVSPR` positions in,
+with `SCALE` not applying, exactly as for a sprite. So a brick drawn with
+`BOX 1, X#, Y#, X# + 24, Y# + 10` is registered with the same four expressions.
+
+The bare form retiring everything is what a level change wants, and it follows `TRAP`,
+`COLLISION` and `DCLOSE`, which all read absence as "off".
+
+**`COLLISION 2` is how you hear about it.** On a C128 type 2 is a sprite against the set
+pixels of the bitmap screen; here it is a sprite against the rectangles `SOLID` registered,
+which is the same question in a form this interpreter can answer. `BUMP(2)` is its mask,
+and it is a **separate** accumulator from `BUMP(1)` — a sprite hitting a wall never sets a
+bit in the sprite-to-sprite mask, so a program that only cares about one of them is not
+disturbed by the other.
+
+```basic norun
+10 COLLISION 2, WALL
+20 FOR I# = 1 TO 60
+30   SOLID I#, BX#(I#), BY#(I#), BX#(I#) + 24, BY#(I#) + 10
+40 NEXT I#
+...
+100 LABEL WALL
+110 M# = BUMP(2)
+120 IF (M# AND 1) = 0 THEN RETURN
+130 REM ... the ball hit something ...
+140 RETURN
+```
+
+Sixty-four is the ceiling, and it is a real budget rather than a round number: these come
+out of a pool of collision proxies shared with whatever game this interpreter is embedded
+in, and eight sprites plus sixty-four rectangles is most of akbasic's share of it. The
+sixty-fifth is refused by name.
+
+`NEW` retires them all. A rectangle is invisible, so one left behind by a deleted program
+would be an unexplainable collision in the next; `CLR` leaves them alone, because it clears
+variables and a rectangle is not one.
+
 ## Reading state back
 
 | Function | Gives |

docs/11-verb-reference.md

@@ -22,7 +22,7 @@ for the reasoning in each case.
 | `CIRCLE` | `CIRCLE src, x, y, rx, ry [,...]` | Draw an ellipse, arc or polygon. |
 | `CLR` | `CLR` | Drop every variable and function, keeping the program. |
 | `COLLECT` | `COLLECT` | **Refused.** Validates a disk's block allocation map. |
-| `COLLISION` | `COLLISION 1 [,target]` | Call a subroutine when sprites collide. No target disarms it. |
+| `COLLISION` | `COLLISION type [,target]` | Call a subroutine when sprites collide. No target disarms it. |
 | `COLOR` | `COLOR src, index` | Bind a colour source to a palette index, 1 to 16. |
 | `CONCAT` | `CONCAT "a", "b"` | Append file `a` to file `b`. |
 | `CONT` | `CONT` | Resume a program stopped by `STOP`. |
@@ -90,6 +90,7 @@ for the reasoning in each case.
 | `SCNCLR` | `SCNCLR` | Clear the text screen. |
 | `SCRATCH` | `SCRATCH "name"` | Delete a file. |
 | `SLEEP` | `SLEEP seconds` | Pause. Holds the program, not the host. |
+| `SOLID` | `SOLID [id [,x1, y1, x2, y2]]` | Register static collision geometry a sprite can hit. No rectangle retires it; no arguments retires them all. See Chapter 8. |
 | `SOUND` | `SOUND v, freq, dur [,...]` | Play a tone on a voice. Does not block. |
 | `SPRCOLOR` | `SPRCOLOR [c1] [,c2]` | Set the two shared multicolour registers. |
 | `SPRHIT` | `SPRHIT n, kind [,x1, y1, x2, y2]` | Give a sprite a collision shape. Kind 0 none, 1 box, 2 circle, 3 or 4 capsule. No rectangle fits the frame. See Chapter 8. |

docs/13-differences.md

@@ -177,7 +177,12 @@ interpreter's error code, which bears no relation to a Commodore error number. P
   narrows that to a box, a circle or a capsule. None of them is pixel-exact.
 - **`SPRHIT` and `RSPHIT` are an addition.** BASIC 7.0 has `COLLISION` and `BUMP` and
   nothing else, and nothing about them changes an existing program.
-- **Only collision type 1 exists.** Types 2 and 3 are refused by name.
+- **Collision types 1 and 2 exist.** Type 2 means the rectangles `SOLID` registered, not a
+  screen read back — a C128 collides a sprite against the bitmap's set pixels and this
+  cannot, so the question is asked against geometry instead. Type 3 is still refused;
+  there is no light pen.
+- **`SOLID` is an addition.** BASIC 7.0 has no static collision geometry at all, and it is
+  what lets a program collide with something that is not one of the eight sprites.
 - **Priority and multicolour are recorded but not drawn.**
 - **`SPRDEF` is out of scope.**