Say what was hit, which way is out, and how far

The narrowphase has been producing a contact since it went in, and the interpreter
was throwing it away. `RCOLLISION(n, f)` reports it: what was hit (a sprite or a
`SOLID` rectangle), which one, the contact normal, the penetration depth, the
contact point, and which axis to reverse.

**The normal points out of the other thing and toward this one**, so a program
moves along it by the depth and is exactly clear. That sign is the one assertion
in the new test that could not be caught any other way -- both parties of a
sprite-against-sprite hit get their own record, each pointing the way *that*
sprite has to move, and sharing one would tell both to go the same direction,
which is how two things end up stuck inside each other.

**Field 7 is the one that deletes the most BASIC.** It is the minimum translation
axis, computed from the normal in C, and it is there because doing it in BASIC
means comparing two floats -- which is exactly where this dialect's left-operand
rule catches people. `BALLBRICKS`/`TESTCELL` in the artwork breakout spend six
lines computing an overlap rectangle and comparing its width to its height to get
this number.

The record is **sticky and deepest-wins**: replaced whenever that sprite is in a
contact and otherwise left alone, so `BUMP` stays the event and this stays the
detail of it. Making it clear itself when nothing touches would break the pairing,
because `BUMP` accumulates across steps and a once-a-frame poll would find the
detail already gone. Reading `BUMP` clears both, so they cannot disagree.

Deliberately narrower than `akgl_Contact`: no actor pointers, because BASIC has no
actor; no tile fields, because there is no tilemap; no z, because every test is
planar; and **no `dt` and no `sensor`**, which libakgl documents as filled in by
the resolver. This interpreter never resolves anything, so those two come back
zero and mean nothing, and an always-zero field in a reference table is a lie.

Documented with the two caveats that matter: fields 2, 3 and 4 are floats and want
a `%` variable, and the contact *point* is exact only for two boxes -- libakgl's
solver returns a point on the portal it converged to, while the normal and depth
are exact for every pair.

Chapter 8's collision section stops claiming only type 1 exists, which has been
false since the previous commit.

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

docs/08-sprites.md

@@ -129,10 +129,13 @@ the target disarms it.
 **reading it clears it**, which is what makes "has anything hit me since I last looked"
 answerable.
 
-Only type 1, sprite-to-sprite, is implemented. Types 2 and 3 are refused by name.
+Type 1 is sprite against sprite and **type 2 is sprite against the static geometry
+`SOLID` registers** — a second handler, on its own accumulator, so the two never disturb
+each other. Type 3 is refused: there is no light pen.
 
-Collision is by bounding box, not by pixel: two sprites whose boxes overlap but whose
-artwork does not are reported as colliding.
+Collision is by shape, not by pixel, and a sprite nobody has shaped collides with its
+whole picture — so two sprites whose frames overlap but whose artwork does not are
+reported as colliding.
 
 ```basic requires=akgl screenshot=sprite-collision
 10 COLOR 1, 2
@@ -258,6 +261,60 @@ sixty-fifth is refused by name.
 would be an unexplainable collision in the next; `CLR` leaves them alone, because it clears
 variables and a rectangle is not one.
 
+## What was hit, and which way to go
+
+`BUMP` says *that* something collided. `RCOLLISION(n, f)` says what it was and how:
+
+| `f` | Gives |
+|---|---|
+| 0 | what sprite `n` last hit — 0 nothing yet, 1 a sprite, 2 static geometry |
+| 1 | which: the other sprite's number, or the `SOLID` id |
+| 2 | the contact normal's x, a float from -1 to 1 |
+| 3 | the normal's y. Negative means the surface is above, because y grows downward |
+| 4 | how deep, in pixels |
+| 5 | where they touched, x |
+| 6 | where they touched, y |
+| 7 | which axis to reverse: 1 for x, 2 for y |
+
+**The normal points out of the other thing and toward this one.** Move along it by the
+depth and you are exactly clear:
+
+```basic norun
+D% = RCOLLISION(1, 4)
+BX# = BX# + (RCOLLISION(1, 2) * D%)
+BY# = BY# + (RCOLLISION(1, 3) * D%)
+```
+
+**Field 7 is the one that deletes the most BASIC.** Working out which axis to reverse from
+an overlap rectangle is four `IF`s and a comparison, and doing it from the normal means
+comparing two floats — which is where [Chapter 13](13-differences.md)'s left-operand rule
+catches people. So it is computed for you:
+
+```basic norun
+A# = RCOLLISION(1, 7)
+IF A# = 1 THEN BVX# = 0 - BVX#
+IF A# = 2 THEN BVY# = 0 - BVY#
+```
+
+Both sides of a sprite-against-sprite hit get their own record, each pointing the way *that*
+sprite has to move. Sharing one would tell both to go the same direction, which is how two
+things end up stuck inside each other.
+
+**Fields 2, 3 and 4 are floats**, so assign them to a `%` variable. A `#` variable throws
+the fraction away and a push-out lands a pixel short.
+
+**The record is sticky.** It is replaced whenever that sprite is in a contact and otherwise
+left alone, so `BUMP` stays the event and this stays the detail of it — ask `BUMP` first,
+then read the record. Reading `BUMP` clears it, so the two never disagree about whether
+there was anything to describe.
+
+A sprite in several overlaps at once reports the **deepest**, because the deepest is the one
+you have to undo.
+
+**Fields 5 and 6 are exact for two boxes and approximate for anything else** — libakgl's
+solver returns a point on the portal it converged to. The normal and the depth are exact for
+every pair, so if you need the contact *point*, keep both shapes boxes.
+
 ## Reading state back
 
 | Function | Gives |