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.**
 

include/akbasic/akgl.h

@@ -272,6 +272,22 @@ typedef struct
      * this is compared rather than flagged.
      */
     SDL_FRect syncedbox[AKBASIC_MAX_SPRITES];
+
+    /**
+     * SPRHIT's shape per slot, as the device was told it.
+     *
+     * A second copy of what akbasic_Sprite already carries, and deliberately: a
+     * device is told about changes and never asked what they were
+     * (include/akbasic/sprite.h), so the backend has to be able to answer from
+     * its own state rather than reaching back into the runtime it does not have
+     * a pointer to.
+     */
+    int shapekind[AKBASIC_MAX_SPRITES];
+    float32_t shapex1[AKBASIC_MAX_SPRITES];
+    float32_t shapey1[AKBASIC_MAX_SPRITES];
+    float32_t shapex2[AKBASIC_MAX_SPRITES];
+    float32_t shapey2[AKBASIC_MAX_SPRITES];
+    bool shapeexplicit[AKBASIC_MAX_SPRITES];
 } akbasic_AkglSprites;
 
 /**

include/akbasic/sprite.h

@@ -37,6 +37,21 @@
 /** @brief Sprites a program has. Eight, as on a C128; the verbs number them 1-8. */
 #define AKBASIC_MAX_SPRITES		8
 
+/**
+ * @brief The collision shapes SPRHIT understands.
+ *
+ * **Deliberately libakgl's own numbers**, so the two documents agree and nobody
+ * has to maintain a mapping between them. A kind this interpreter has no use for
+ * is still refused by name rather than silently accepted.
+ */
+#define AKBASIC_SHAPE_NONE		0
+#define AKBASIC_SHAPE_BOX		1
+#define AKBASIC_SHAPE_CIRCLE		2
+#define AKBASIC_SHAPE_CAPSULE_X		3
+#define AKBASIC_SHAPE_CAPSULE_Y		4
+/** @brief One past the last kind, for the range check. */
+#define AKBASIC_SHAPE_LAST		5
+
 /** @brief Width of a Commodore sprite in pixels. */
 #define AKBASIC_SPRITE_WIDTH		24
 /** @brief Height of a Commodore sprite in pixels. */
@@ -87,6 +102,23 @@ typedef struct
     double y;
     double angle;		/* MOVSPR's continuous motion: degrees		*/
     int speed;			/*   clockwise from vertical, and 0-15		*/
+
+    /**
+     * SPRHIT's collision shape: one of the #AKBASIC_SHAPE_* kinds, and a
+     * rectangle measured from the sprite's top-left corner.
+     *
+     * `shapeexplicit` is what separates "the program asked for the whole frame"
+     * from "the program has not said". They are the same shape today and will
+     * not stay that way: a frame-fitting shape has to be rebuilt when the
+     * picture or an expansion bit changes, and one the program gave in pixels
+     * must not be.
+     */
+    int shapekind;
+    double shapex1;
+    double shapey1;
+    double shapex2;
+    double shapey2;
+    bool shapeexplicit;
 } akbasic_Sprite;
 
 /**
@@ -181,6 +213,19 @@ typedef struct akbasic_SpriteBackend
      * remember anything.
      */
     akerr_ErrorContext AKERR_NOIGNORE *(*collisions)(struct akbasic_SpriteBackend *self, uint16_t *mask);
+    /**
+     * Give sprite @p n a collision shape.
+     *
+     * @p kind is an #AKBASIC_SHAPE_NONE .. #AKBASIC_SHAPE_CAPSULE_Y, and the
+     * rectangle is two corners measured from the sprite's top-left, in device
+     * pixels -- the same form `BOX` and `SSHAPE` take, because a dialect with two
+     * spellings for a rectangle is a dialect nobody can write from memory.
+     *
+     * Optional. A backend that withholds it makes `SPRHIT` refuse by name, which
+     * is what a device that cannot do what was asked is supposed to do.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*shape)(struct akbasic_SpriteBackend *self, int n, int kind,
+						double x1, double y1, double x2, double y2);
 } akbasic_SpriteBackend;
 
 /**

src/runtime_sprite.c

@@ -692,6 +692,126 @@ akerr_ErrorContext *akbasic_fn_rsppos(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
     SUCCEED_RETURN(errctx);
 }
 
+/** @brief Take a scratch float value from the per-line pool for a function result. */
+static akerr_ErrorContext *float_result(akbasic_Runtime *obj, double value, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *out = NULL;
+
+    PASS(errctx, akbasic_environment_new_value(obj->environment, &out));
+    PASS(errctx, akbasic_value_zero(out));
+    out->valuetype = AKBASIC_TYPE_FLOAT;
+    out->floatval = value;
+    *dest = out;
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- SPRHIT -- */
+
+akerr_ErrorContext *akbasic_cmd_sprhit(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Sprite *sprite = NULL;
+    double args[6];
+    int count = 0;
+    int index = 0;
+    int kind = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in SPRHIT");
+    PASS(errctx, require_sprites(obj, "SPRHIT"));
+    FAIL_ZERO_RETURN(errctx, (obj->sprites->shape != NULL), AKBASIC_ERR_DEVICE,
+		     "SPRHIT needs a sprite device that can carry a collision shape, and this one cannot");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "SPRHIT", args, 6, &count));
+    FAIL_ZERO_RETURN(errctx, (count >= 2), AKBASIC_ERR_SYNTAX,
+		     "SPRHIT expected a sprite number and a shape kind");
+    FAIL_ZERO_RETURN(errctx, (count == 2 || count == 6), AKBASIC_ERR_SYNTAX,
+		     "SPRHIT takes a kind alone or a kind and four corners, not %d arguments",
+		     count);
+    PASS(errctx, sprite_index((int)args[0], "SPRHIT", &index));
+    sprite = &obj->sprite_state.sprites[index];
+
+    kind = (int)args[1];
+    FAIL_ZERO_RETURN(errctx, (kind >= AKBASIC_SHAPE_NONE && kind < AKBASIC_SHAPE_LAST),
+		     AKBASIC_ERR_BOUNDS,
+		     "SPRHIT: shape kind %d is outside 0..%d", kind, AKBASIC_SHAPE_LAST - 1);
+    sprite->shapekind = kind;
+
+    /*
+     * Two arguments means "fit the frame", which is what a sprite loaded from a
+     * file needs: `SPRSAV "ship.png", 1` gives it the image's own size and the
+     * program never learns what that was. The device recomputes it from the
+     * picture, so the rectangle recorded here stays zero and RSPHIT reports what
+     * the device worked out rather than what was not said.
+     */
+    sprite->shapeexplicit = (count == 6);
+    if ( count == 6 ) {
+	FAIL_ZERO_RETURN(errctx, (args[4] > args[2] && args[5] > args[3]), AKBASIC_ERR_VALUE,
+			 "SPRHIT: (%g, %g) to (%g, %g) is not a rectangle with a positive width and height",
+			 args[2], args[3], args[4], args[5]);
+	sprite->shapex1 = args[2];
+	sprite->shapey1 = args[3];
+	sprite->shapex2 = args[4];
+	sprite->shapey2 = args[5];
+    } else {
+	sprite->shapex1 = 0.0;
+	sprite->shapey1 = 0.0;
+	sprite->shapex2 = 0.0;
+	sprite->shapey2 = 0.0;
+    }
+
+    PASS(errctx, obj->sprites->shape(obj->sprites, index + 1, sprite->shapekind,
+				     sprite->shapex1, sprite->shapey1,
+				     sprite->shapex2, sprite->shapey2));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_fn_rsphit(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Sprite *sprite = NULL;
+    int64_t n = 0;
+    int64_t field = 0;
+    int index = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in RSPHIT");
+    PASS(errctx, nth_number(obj, expr, "RSPHIT", 0, &n));
+    PASS(errctx, nth_number(obj, expr, "RSPHIT", 1, &field));
+    PASS(errctx, sprite_index((int)n, "RSPHIT", &index));
+    sprite = &obj->sprite_state.sprites[index];
+
+    /*
+     * The five fields are SPRHIT's own arguments in SPRHIT's own order, which is
+     * the rule RSPRITE and RSPPOS already follow. No device is needed: this
+     * answers from interpreter state, because asking the device would be asking
+     * it to repeat what it was told.
+     */
+    switch ( field ) {
+    case 0:
+	PASS(errctx, integer_result(obj, (int64_t)sprite->shapekind, dest));
+	break;
+    case 1:
+	PASS(errctx, float_result(obj, sprite->shapex1, dest));
+	break;
+    case 2:
+	PASS(errctx, float_result(obj, sprite->shapey1, dest));
+	break;
+    case 3:
+	PASS(errctx, float_result(obj, sprite->shapex2, dest));
+	break;
+    case 4:
+	PASS(errctx, float_result(obj, sprite->shapey2, dest));
+	break;
+    default:
+	FAIL_RETURN(errctx, AKBASIC_ERR_BOUNDS,
+		    "RSPHIT: field %" PRId64 " is outside 0..4", field);
+    }
+    SUCCEED_RETURN(errctx);
+}
+
 akerr_ErrorContext *akbasic_fn_rsprite(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
 {
     akbasic_Sprite *sprite = NULL;

src/sprite_akgl.c

@@ -491,7 +491,8 @@ static bool slot_collidable(akbasic_AkglSprites *state, int i)
 {
     return (state->actors[i] != NULL
 	    && state->sprites[i] != NULL
-	    && state->actors[i]->visible);
+	    && state->actors[i]->visible
+	    && state->shapekind[i] != AKBASIC_SHAPE_NONE);
 }
 
 /**
@@ -509,6 +510,55 @@ static bool slot_collidable(akbasic_AkglSprites *state, int i)
  * sprite-against-sprite first, and taking the library's default would make
  * BUMP(1) report nothing at all, silently.
  */
+/**
+ * @brief Record the shape SPRHIT asked for. The next scan builds it.
+ *
+ * Nothing is built here, and the reason is worth stating: a frame-fitting shape
+ * depends on the picture and the expansion bits, both of which may change after
+ * this call and before the next scan, so deriving it now would be deriving it
+ * from the wrong numbers. Zeroing the synced rectangle is what makes the next
+ * scan rebuild rather than recognise the position as unchanged and skip.
+ */
+static akerr_ErrorContext *spr_shape(akbasic_SpriteBackend *self, int n, int kind,
+				     double x1, double y1, double x2, double y2)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    int i = 0;
+
+    PASS(errctx, slot_of(self, n, &state, &i));
+    state->shapekind[i] = kind;
+    state->shapex1[i] = (float32_t)x1;
+    state->shapey1[i] = (float32_t)y1;
+    state->shapex2[i] = (float32_t)x2;
+    state->shapey2[i] = (float32_t)y2;
+    state->shapeexplicit[i] = (x2 > x1 && y2 > y1);
+    memset(&state->syncedbox[i], 0, sizeof(state->syncedbox[i]));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief The rectangle slot @p i collides with, in device pixels.
+ *
+ * Either what SPRHIT was given, offset to where the sprite is, or the whole
+ * drawn frame -- which is what a sprite nobody has shaped has always collided
+ * with, and is the default this must keep reproducing exactly.
+ */
+static void collision_box(akbasic_AkglSprites *state, int i, SDL_FRect *dest)
+{
+    dest->x = state->actors[i]->x;
+    dest->y = state->actors[i]->y;
+    if ( state->shapeexplicit[i] ) {
+	dest->x += state->shapex1[i];
+	dest->y += state->shapey1[i];
+	dest->w = state->shapex2[i] - state->shapex1[i];
+	dest->h = state->shapey2[i] - state->shapey1[i];
+	return;
+    }
+    dest->w = (float32_t)state->sprites[i]->width * (state->xexpand[i] ? 2.0f : 1.0f);
+    dest->h = (float32_t)state->sprites[i]->height * (state->yexpand[i] ? 2.0f : 1.0f);
+}
+
 static akerr_ErrorContext AKERR_NOIGNORE *sync_proxy(akbasic_AkglSprites *state, int i,
 						     SDL_FRect *box)
 {
@@ -546,7 +596,28 @@ static akerr_ErrorContext AKERR_NOIGNORE *sync_proxy(akbasic_AkglSprites *state,
     if ( body.w <= 0.0f || body.h <= 0.0f ) {
 	SUCCEED_RETURN(errctx);
     }
+    switch ( state->shapekind[i] ) {
+    case AKBASIC_SHAPE_CIRCLE:
+	/*
+	 * Inscribed, and in the *smaller* of the two half-extents. A circle that
+	 * fitted the larger one would poke out of the rectangle the program
+	 * asked for, which is the opposite of what "give this sprite a circle"
+	 * means to somebody looking at a disc drawn inside a square frame.
+	 */
+	PASS(errctx, akgl_collision_shape_circle(&state->shapes[i],
+						 body.w / 2.0f, body.h / 2.0f,
+						 (body.w < body.h ? body.w : body.h) / 2.0f,
+						 0.0f));
+	break;
+    case AKBASIC_SHAPE_CAPSULE_X:
+    case AKBASIC_SHAPE_CAPSULE_Y:
+	PASS(errctx, akgl_collision_shape_capsule(&state->shapes[i], &body,
+						  (uint8_t)state->shapekind[i], 0.0f));
+	break;
+    default:
 	PASS(errctx, akgl_collision_shape_box(&state->shapes[i], &body, 0.0f));
+	break;
+    }
     state->shapes[i].collidemask = AKGL_COLLISION_LAYER_ACTOR | AKGL_COLLISION_LAYER_STATIC;
     PASS(errctx, akgl_collision_proxy_sync(state->proxies[i], &state->shapes[i],
 					   box->x, box->y, 0.0f));
@@ -576,10 +647,7 @@ static akerr_ErrorContext *spr_collisions(akbasic_SpriteBackend *self, uint16_t
 	if ( !live[i] ) {
 	    continue;
 	}
-	box[i].x = state->actors[i]->x;
+	collision_box(state, i, &box[i]);
-	box[i].y = state->actors[i]->y;
-	box[i].w = (float32_t)state->sprites[i]->width * (state->xexpand[i] ? 2.0f : 1.0f);
-	box[i].h = (float32_t)state->sprites[i]->height * (state->yexpand[i] ? 2.0f : 1.0f);
     }
 
     /*
@@ -687,6 +755,13 @@ akerr_ErrorContext *akbasic_sprite_init_akgl(akbasic_SpriteBackend *obj, akbasic
     for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
 	SDL_FRect placeholder = { 0.0f, 0.0f, 1.0f, 1.0f };
 
+	/*
+	 * A box fitting the frame, which is what every sprite collided with
+	 * before SPRHIT existed and is what one nobody has shaped must go on
+	 * collided with.
+	 */
+	state->shapekind[i] = AKBASIC_SHAPE_BOX;
+
 	PASS(errctx, akgl_collision_shape_box(&state->shapes[i], &placeholder, 0.0f));
 	/*
 	 * Acquire and initialize adjacent, with nothing between them: the slot
@@ -708,6 +783,7 @@ akerr_ErrorContext *akbasic_sprite_init_akgl(akbasic_SpriteBackend *obj, akbasic
     obj->configure	= spr_configure;
     obj->shared_colors	= spr_shared_colors;
     obj->collisions	= spr_collisions;
+    obj->shape		= spr_shape;
     SUCCEED_RETURN(errctx);
 }
 

src/verbs.c

@@ -140,6 +140,7 @@ static const akbasic_Verb VERBS[] = {
     { "RGR",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_rgr },
     { "RIGHT",        AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_right },
     { "RSPCOLOR",     AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_rspcolor },
+    { "RSPHIT",       AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsphit },
     { "RSPPOS",       AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsppos },
     { "RSPRITE",      AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsprite },
     { "RUN",          AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_run },
@@ -156,6 +157,7 @@ static const akbasic_Verb VERBS[] = {
     { "SOUND",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sound },
     { "SPC",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_spc },
     { "SPRCOLOR",     AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sprcolor },
+    { "SPRHIT",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sprhit },
     { "SPRITE",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sprite },
     { "SPRSAV",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sprsav },
     { "SSHAPE",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sshape },

src/verbs.h

@@ -90,11 +90,13 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_on(struct akbasic_Runtime *obj, a
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_collision(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_movspr(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sprcolor(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sprhit(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sprite(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sprsav(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_bump(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rspcolor(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rsppos(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rsphit(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rsprite(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 
 /* Verb handlers -- src/runtime_housekeeping.c */

tests/akgl_backends.c

@@ -760,6 +760,90 @@ static akerr_ErrorContext AKERR_NOIGNORE *test_collision_cross_shape(void)
     SUCCEED_RETURN(errctx);
 }
 
+/** @brief The 24x21 pattern program the shape cases share, with @p tail appended. */
+static akerr_ErrorContext AKERR_NOIGNORE *two_sprites(const char *tail, uint16_t *dest)
+{
+    PREPARE_ERROR(errctx);
+    char source[2048];
+
+    snprintf(source, sizeof(source),
+	     "10 DIM P#(63)\n"
+	     "20 FOR I# = 0 TO 62\n"
+	     "30   P#(I#) = 255\n"
+	     "40 NEXT I#\n"
+	     "50 SPRSAV P#, 1\n"
+	     "60 SPRSAV P#, 2\n"
+	     "70 SPRITE 1, 1\n"
+	     "80 SPRITE 2, 1\n"
+	     "%s", tail);
+    PASS(errctx, mask_for(source, dest));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief SPRHIT narrows what a sprite collides with, and the default is the frame.
+ *
+ * The first case is the one that matters most and the reason this whole change
+ * could be made at all: **a program that never says SPRHIT must behave exactly as
+ * it did.** Everything else here is new surface; that one is a promise.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_sprite_shapes(void)
+{
+    PREPARE_ERROR(errctx);
+    uint16_t mask = 0;
+
+    /* Two 24x21 frames, ten pixels apart: overlapping, as they always were. */
+    PASS(errctx, two_sprites("90 MOVSPR 1, 10, 10\n"
+			     "100 MOVSPR 2, 20, 20\n", &mask));
+    TEST_REQUIRE_INT(mask, 0x03);
+    stop_runtime();
+
+    /*
+     * A box in the top-left corner of sprite 1 only, four pixels square. Sprite
+     * 2's frame starts at 20 and the shape ends at 14, so they no longer meet --
+     * with both sprites in exactly the places the case above had them.
+     */
+    PASS(errctx, two_sprites("85 SPRHIT 1, 1, 0, 0, 4, 4\n"
+			     "90 MOVSPR 1, 10, 10\n"
+			     "100 MOVSPR 2, 20, 20\n", &mask));
+    TEST_REQUIRE_INT(mask, 0);
+    stop_runtime();
+
+    /* And the shape is offset from the sprite, so moving the sprite moves it. */
+    PASS(errctx, two_sprites("85 SPRHIT 1, 1, 0, 0, 4, 4\n"
+			     "90 MOVSPR 1, 18, 18\n"
+			     "100 MOVSPR 2, 20, 20\n", &mask));
+    TEST_REQUIRE_INT(mask, 0x03);
+    stop_runtime();
+
+    /* Kind 0 takes a sprite out of collision while leaving it on the screen. */
+    PASS(errctx, two_sprites("85 SPRHIT 1, 0\n"
+			     "90 MOVSPR 1, 10, 10\n"
+			     "100 MOVSPR 2, 10, 10\n", &mask));
+    TEST_REQUIRE_INT(mask, 0);
+    stop_runtime();
+
+    /*
+     * A circle is inscribed in the frame, so two frames touching at their
+     * corners -- which is the false positive docs/08-sprites.md ships a figure
+     * of -- stop colliding when both become circles. This is the case that
+     * figure exists to complain about.
+     */
+    PASS(errctx, two_sprites("90 MOVSPR 1, 0, 0\n"
+			     "100 MOVSPR 2, 23, 20\n", &mask));
+    TEST_REQUIRE_INT(mask, 0x03);
+    stop_runtime();
+
+    PASS(errctx, two_sprites("85 SPRHIT 1, 2\n"
+			     "86 SPRHIT 2, 2\n"
+			     "90 MOVSPR 1, 0, 0\n"
+			     "100 MOVSPR 2, 23, 20\n", &mask));
+    TEST_REQUIRE_INT(mask, 0);
+    stop_runtime();
+
+    SUCCEED_RETURN(errctx);
+}
+
 int main(void)
 {
     PREPARE_ERROR(errctx);
@@ -828,6 +912,7 @@ int main(void)
 	CATCH(errctx, test_sprite_from_shape());
 	CATCH(errctx, test_collision_pairs());
 	CATCH(errctx, test_collision_cross_shape());
+	CATCH(errctx, test_sprite_shapes());
     } CLEANUP {
 	if ( font != NULL ) {
 	    TTF_CloseFont(font);