Let a program say what part of a sprite collides

`SPRHIT n, kind [,x1, y1, x2, y2]` gives a sprite a collision shape: a box, a
circle inscribed in it, or a capsule. `RSPHIT(n, f)` reads it back in SPRHIT's
own argument order, the way RSPRITE and RSPPOS already do, and needs no device
because it answers from interpreter state.

The rectangle is two corners measured from the sprite's top-left, in device
pixels -- the same `x1, y1, x2, y2` that `BOX` and `SSHAPE` take. A dialect with
two spellings for a rectangle is one nobody can write from memory. Omit it and
the shape fits whatever the picture turned out to be, which is what a sprite
loaded from a file needs: `SPRSAV "ship.png", 1` takes the image's own size and
the program never learns what that was.

**A sprite nobody has shaped collides with its whole frame, expansion bits
included, exactly as before.** That is a promise rather than a convenience, and
it has its own test: the same two sprites in the same two places, once with no
SPRHIT and once with a four-pixel box, reporting a collision and then not.

Named SPRHIT rather than SPRSHAPE because "shape" already means "a region SSHAPE
saved" in this dialect, in this very chapter -- `SPRSAV A$, 1` takes one -- and a
reader who typed `SPRSHAPE A$, 1` would have had every reason to. Both names, and
RSPHIT, were grepped against every label in docs/, examples/ and both corpora
first: a bare word is a label here, so a verb and a label share one namespace and
taking a name a checked-in listing already uses would break it silently.

`SPRHIT n, 0` takes a sprite out of collision while leaving it on the screen --
the ghost, the flashing invulnerable player, the pickup already taken. Hiding it
with `SPRITE n, 0` stops it colliding too, and is what you want when it should
not be seen either.

The circle answers the complaint chapter 8 already ships a figure of. That figure
shows two discs whose *boxes* touch at a corner while the artwork is nowhere
near, and `BUMP(1)` reporting a collision; two `SPRHIT n, 2` and it stops. The
test asserts both halves so the figure's caption stays true.

`tests/verbs_table.c` caught RSPHIT filed after RSPPOS rather than before it,
which is the sorted-table test doing exactly the job it exists for.

Docs: a new section in chapter 8, rows in the verb and function references in
alphabetical order, and chapter 13's "collision is by bounding box" becomes
"collision is by shape" with the addition named. 111 with akgl, 110 without, and
the artwork breakout still runs clean.

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

docs/08-sprites.md

@@ -155,6 +155,55 @@ The artwork here includes a border around the whole 40 by 40 sprite, so each spr
 draws its own bounding box. Those boxes overlap at one corner and the two discs are
 nowhere near each other — and `BUMP(1)` reports a collision.
 
+## Giving a sprite a shape
+
+That false positive is what `SPRHIT` is for. It says what part of a sprite collides,
+rather than leaving it as the whole picture:
+
+```basic norun
+SPRHIT n, kind
+SPRHIT n, kind, x1, y1, x2, y2
+```
+
+| `kind` | Is |
+|---|---|
+| 0 | nothing — the sprite stays on screen and stops colliding |
+| 1 | a box |
+| 2 | a circle, inscribed in the rectangle |
+| 3 | a capsule, round ends left and right |
+| 4 | a capsule, round ends top and bottom |
+
+The rectangle is **two corners measured from the sprite's top-left**, in device pixels —
+the same `x1, y1, x2, y2` that `BOX` and `SSHAPE` take, because a dialect with two
+spellings for a rectangle is one nobody can write from memory. Leave it out and the shape
+fits whatever the picture turned out to be, which is what a sprite loaded from a file
+needs: `SPRSAV "ship.png", 1` takes the image's own size and the program never learns what
+that was.
+
+So the two discs above stop colliding as soon as they are discs:
+
+```basic norun
+90 SPRHIT 1, 2
+100 SPRHIT 2, 2
+```
+
+and a ship whose art does not fill its frame can say so:
+
+```basic norun
+SPRHIT 1, 1, 4, 2, 20, 19
+```
+
+**A sprite nobody has shaped collides with its whole frame**, expansion bits included,
+which is what every sprite did before `SPRHIT` existed. Adding the verb changed no existing
+program.
+
+`SPRHIT n, 0` is the ghost, the flashing invulnerable player and the pickup that has
+already been taken: still drawn, no longer in the way. Hiding the sprite with `SPRITE n, 0`
+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.
+
 ## Reading state back
 
 | Function | Gives |

docs/11-verb-reference.md

@@ -92,6 +92,7 @@ for the reasoning in each case.
 | `SLEEP` | `SLEEP seconds` | Pause. Holds the program, not the host. |
 | `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. |
 | `SPRITE` | `SPRITE n [,on] [,col] [,...]` | Configure a sprite. Omitted arguments are left alone. |
 | `SPRSAV` | `SPRSAV source, n` | Give sprite `n` a picture. Three source forms; see Chapter 8. |
 | `SSHAPE` | `SSHAPE A$, x1, y1 [,x2, y2]` | Save a screen region; `A$` receives a handle. |

docs/12-function-reference.md

@@ -29,6 +29,7 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
 | `RWINDOW` | 1 | `RWINDOW(f)` | The current text window's rows (0) or columns (1). Field 2 is a C128 screen mode and is refused. |
 | `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
+| `RSPHIT` | 2 | `RSPHIT(n, f)` | One of `SPRHIT`'s settings for sprite `n`, in `SPRHIT`'s own argument order: 0 the kind, 1 to 4 the two corners. |
 | `RSPPOS` | 2 | `RSPPOS(n, f)` | A sprite's x (0), y (1) or speed (2). |
 | `RSPRITE` | 2 | `RSPRITE(n, f)` | One of a sprite's `SPRITE` settings, in `SPRITE`'s argument order. |
 | `SGN` | 1 | `SGN(n)` | -1, 0 or 1 according to the sign. |

docs/13-differences.md

@@ -172,7 +172,12 @@ interpreter's error code, which bears no relation to a Commodore error number. P
   cannot hold a zero byte. It also takes an **image file path**, which a C128 cannot.
 - **A sprite loaded from a file keeps the image's own size**, not 24 by 21.
 - **`MOVSPR`'s speed unit is a choice.** The manual does not say what a unit is worth.
-- **Collision is by bounding box**, not by pixel, and only type 1 exists.
+- **Collision is by shape**, not by pixel. A sprite nobody has shaped collides with its
+  whole frame, expansion bits included, which is what a bounding box means here; `SPRHIT`
+  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.
 - **Priority and multicolour are recorded but not drawn.**
 - **`SPRDEF` is out of scope.**