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

src/sprite_akgl.c

@@ -625,6 +625,61 @@ static akerr_ErrorContext AKERR_NOIGNORE *sync_proxy(akbasic_AkglSprites *state,
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Keep @p contact for slot @p i if it is deeper than what is there.
+ *
+ * A sprite may be in several overlaps at once -- a ball touching two bricks at a
+ * corner -- and only one can be reported. The deepest is the one that has to be
+ * undone, so it is the one worth keeping.
+ *
+ * The normal comes out of libakgl pointing out of the *other* shape and toward
+ * this one, which is the direction a program wants: move along it by the depth
+ * and you are clear.
+ */
+static void record_contact(akbasic_AkglSprites *state, int i, int what, int other,
+			   akgl_Contact *contact)
+{
+    akbasic_Contact *dest = &state->contacts[i];
+
+    if ( state->hascontact[i] && dest->depth >= (double)contact->depth ) {
+	return;
+    }
+    dest->what = what;
+    dest->other = other;
+    dest->nx = (double)contact->nx;
+    dest->ny = (double)contact->ny;
+    dest->depth = (double)contact->depth;
+    dest->px = (double)contact->px;
+    dest->py = (double)contact->py;
+    /*
+     * The minimum translation axis, from the normal rather than from an overlap
+     * rectangle: whichever component is larger is the axis the shapes are least
+     * far through, and therefore the one to reverse. Computed here because doing
+     * it in BASIC means comparing two floats, which is exactly where this
+     * dialect's left-operand rule bites.
+     */
+    dest->axis = ((contact->nx < 0.0f ? -contact->nx : contact->nx)
+		  >= (contact->ny < 0.0f ? -contact->ny : contact->ny)) ? 1 : 2;
+    state->hascontact[i] = true;
+}
+
+static akerr_ErrorContext *spr_contact(akbasic_SpriteBackend *self, int n,
+				       akbasic_Contact *dest, bool *found)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    int i = 0;
+
+    PASS(errctx, slot_of(self, n, &state, &i));
+    FAIL_ZERO_RETURN(errctx, (dest != NULL && found != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in contact");
+    *found = state->hascontact[i];
+    if ( *found ) {
+	*dest = state->contacts[i];
+    }
+    SUCCEED_RETURN(errctx);
+}
+
 /**
  * @brief Run the scan if anything has changed, and leave both masks on the state.
  *
@@ -690,6 +745,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_scan(akbasic_AkglSprites *state)
     }
     state->lastmask = 0;
     state->lastsolidmask = 0;
+    memset(state->hascontact, 0, sizeof(state->hascontact));
 
     /*
      * **Two phases, and the split is the whole performance story.**
@@ -756,6 +812,15 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_scan(akbasic_AkglSprites *state)
 	    if ( hit ) {
 		state->lastmask |= (uint16_t)(1u << i);
 		state->lastmask |= (uint16_t)(1u << j);
+		record_contact(state, i, 1, j + 1, &contact);
+		/*
+		 * And the mirror for the other sprite. The normal points out of
+		 * b toward a, so b's own copy has to be negated or both sprites
+		 * would be told to move the same way.
+		 */
+		contact.nx = -contact.nx;
+		contact.ny = -contact.ny;
+		record_contact(state, j, 1, i + 1, &contact);
 	    }
 	}
     }
@@ -789,6 +854,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_scan(akbasic_AkglSprites *state)
 					     AKGL_COLLISION_TEST_PLANAR, &contact, &hit));
 	    if ( hit ) {
 		state->lastsolidmask |= (uint16_t)(1u << i);
+		record_contact(state, i, 2, j + 1, &contact);
 	    }
 	}
     }
@@ -959,6 +1025,7 @@ akerr_ErrorContext *akbasic_sprite_init_akgl(akbasic_SpriteBackend *obj, akbasic
     obj->shape		= spr_shape;
     obj->solid		= spr_solid;
     obj->solids		= spr_solids;
+    obj->contact	= spr_contact;
     SUCCEED_RETURN(errctx);
 }