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

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);
     }
-    PASS(errctx, akgl_collision_shape_box(&state->shapes[i], &body, 0.0f));
+    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;
-	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);
+	collision_box(state, i, &box[i]);
     }
 
     /*
@@ -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 */