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

include/akbasic/akgl.h

@@ -288,6 +288,51 @@ typedef struct
     float32_t shapex2[AKBASIC_MAX_SPRITES];
     float32_t shapey2[AKBASIC_MAX_SPRITES];
     bool shapeexplicit[AKBASIC_MAX_SPRITES];
+
+    /**
+     * SOLID's static geometry: a proxy and a shape per registered rectangle.
+     *
+     * **Not registered with any partitioner, and there is no
+     * `akgl_CollisionWorld` here at all.** libakgl's uniform grid keeps its cell
+     * heads, its cell size and its origin in file-scope statics
+     * (`deps/libakgl/src/collision_grid.c`), 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 that has its own collision world would destroy every
+     * registration that game had made, on the first `SOLID` a script ran.
+     *
+     * So the geometry is indexed here, by an ordinary array, and pairs go
+     * straight to `akgl_collision_test()` -- which takes two positioned proxies
+     * and needs no world. At sixty-four rectangles that is the right answer
+     * anyway: libakgl's own measurements put a naive all-pairs sweep at 0.7% of
+     * a frame at sixty-four objects, and a broad phase is bookkeeping that only
+     * repays itself well above that.
+     */
+    akgl_CollisionProxy *solidproxies[AKBASIC_MAX_SOLIDS];
+    akgl_CollisionShape solidshapes[AKBASIC_MAX_SOLIDS];
+    SDL_FRect solidbox[AKBASIC_MAX_SOLIDS];
+    bool solidactive[AKBASIC_MAX_SOLIDS];
+
+    /**
+     * What the last scan saw, so an unchanged scan can answer without redoing
+     * the work.
+     *
+     * The scan runs at the top of every interpreter step -- up to 256 times a
+     * rendered frame -- and its inputs are the sprites' boxes, which sprite
+     * slots are collidable, and the static geometry. A sprite moves at most once
+     * in that time. If none of those changed, the answer cannot have changed
+     * either, and eight rectangle comparisons say so far more cheaply than
+     * recomputing it.
+     *
+     * This is what makes static geometry affordable at all: eight sprites
+     * against sixty-four rectangles is five hundred and twelve tests, which is
+     * fine once a frame and is not fine two hundred and fifty-six times.
+     */
+    SDL_FRect lastbox[AKBASIC_MAX_SPRITES];
+    bool lastlive[AKBASIC_MAX_SPRITES];
+    uint16_t lastmask;
+    uint16_t lastsolidmask;
+    bool lastvalid;
 } akbasic_AkglSprites;
 
 /**

include/akbasic/sprite.h

@@ -52,6 +52,19 @@
 /** @brief One past the last kind, for the range check. */
 #define AKBASIC_SHAPE_LAST		5
 
+/**
+ * @brief Static collision rectangles a program can register with SOLID.
+ *
+ * Sixty-four, which is the smallest power of two that holds a sixty-brick wall
+ * with headroom. The ceiling matters because these come out of libakgl's
+ * collision proxy pool, which is shared with whatever host this interpreter is
+ * embedded in: eight sprites plus sixty-four solids is seventy-two of
+ * #AKGL_MAX_HEAP_COLLISION_PROXY, and the rest is the host's.
+ */
+#ifndef AKBASIC_MAX_SOLIDS
+#define AKBASIC_MAX_SOLIDS		64
+#endif
+
 /** @brief Width of a Commodore sprite in pixels. */
 #define AKBASIC_SPRITE_WIDTH		24
 /** @brief Height of a Commodore sprite in pixels. */
@@ -121,6 +134,23 @@ typedef struct
     bool shapeexplicit;
 } akbasic_Sprite;
 
+/**
+ * @brief One rectangle registered by SOLID, as BASIC sees it.
+ *
+ * The id is the array index plus one and is the program's own number, not a
+ * minted handle. A brick in a sixty-brick wall has a natural index; making the
+ * program carry one back out of the interpreter would be inventing a second
+ * numbering for something that already has one.
+ */
+typedef struct
+{
+    bool active;
+    double x1;
+    double y1;
+    double x2;
+    double y2;
+} akbasic_Solid;
+
 /**
  * @brief The sprite verbs' own state, which lives on the runtime.
  *
@@ -133,9 +163,11 @@ typedef struct
 typedef struct
 {
     akbasic_Sprite sprites[AKBASIC_MAX_SPRITES];
+    akbasic_Solid solids[AKBASIC_MAX_SOLIDS];
     int sharedcolor1;		/* SPRCOLOR's two multicolour registers, 1-16	*/
     int sharedcolor2;
     uint16_t bumped;		/* bit n-1 set when sprite n has collided	*/
+    uint16_t bumpedsolid;	/*   and when it has met static geometry	*/
     int64_t lastservicems;	/* when MOVSPR's continuous motion last moved	*/
 } akbasic_SpriteState;
 
@@ -226,6 +258,30 @@ typedef struct akbasic_SpriteBackend
      */
     akerr_ErrorContext AKERR_NOIGNORE *(*shape)(struct akbasic_SpriteBackend *self, int n, int kind,
 						double x1, double y1, double x2, double y2);
+    /**
+     * Register, replace or retire static collision geometry @p id.
+     *
+     * @p define false retires it and the rectangle is ignored. Rectangles are in
+     * window pixels -- the coordinates `BOX` draws in and `MOVSPR` positions in,
+     * with `SCALE` not applying, exactly as for a sprite.
+     *
+     * Optional, like `shape`. A backend that withholds it makes `SOLID` refuse
+     * by name.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*solid)(struct akbasic_SpriteBackend *self, int id, bool define,
+						double x1, double y1, double x2, double y2);
+    /**
+     * Report which sprites are overlapping static geometry.
+     *
+     * Bit n-1 is set when sprite n overlaps at least one rectangle `solid`
+     * registered. Answered from the same pass as `collisions`, so the two are
+     * always about the same instant whichever order they are called in.
+     *
+     * Optional. A runtime whose backend withholds it reports no static
+     * collisions rather than refusing, exactly as one with no backend at all
+     * reports none -- a step is not a statement and has no line to blame.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*solids)(struct akbasic_SpriteBackend *self, uint16_t *mask);
 } akbasic_SpriteBackend;
 
 /**