Answer sprite collision through libakgl's narrowphase

`spr_collisions()` computed axis-aligned overlaps itself, because at libakgl
0.7.0 there was nothing to delegate to: `akgl_collide_rectangles()` has a
documented corner-containment defect and the physics backend's `collide` slot
raised "Not implemented". 0.8.0 brought a real narrowphase, and this moves onto
it.

The mask is bit-identical and every test from the previous commit passes
**unmodified**, which was the gate this stage had to clear -- including the two
that were written to be hard to satisfy. Edge-to-edge is still not a collision,
so a tile-aligned program is unaffected. The cross-shaped overlap is still
reported, which is the one that could have regressed: it is the case
`akgl_collide_rectangles()` gets wrong and the reason the hand-written loop
existed, and `akgl_collision_test()`'s box path gets it right.

What it buys is the contact -- a normal, a penetration depth and a point --
which four comparisons cannot produce. Nothing consumes it yet; that is the next
commit. It is here now because the mask and the contact come out of the same
test, and computing them in two places would be two things to keep in step.

**The first attempt was ten times slower and the benchmark caught it.** Syncing
all eight proxies and running the narrowphase on all twenty-eight pairs measured
984 ns a scan against 96 ns for the loop it replaced -- 21% of a frame at 256
scans a frame -- to produce a mask that was bit-identical and a contact that was
thrown away. Two changes fixed it, and both are what a broad phase *is* rather
than workarounds for a slow library:

- **Reject on the bounding boxes first.** The four comparisons that were always
  here now decide which pairs are worth an exact answer. The narrowphase still
  decides the bit -- the box test only says "maybe", which will matter the moment
  a shape is not the whole frame.
- **Do not sync a proxy that has not moved.** The scan runs at the top of every
  interpreter step and a sprite moves at most once in that time, so almost every
  sync would rewrite a proxy with what it already holds. Compared against the
  last synced rectangle rather than flagged by the verbs, because a host game can
  move a BASIC sprite through the actor registry and a flag would miss that.

Measured after: 54.9 ns at eight sprites spread out, which is *faster* than the
96.3 ns it replaced -- boxes are now built eight times a scan instead of
fifty-six. The number that matters is the new benchmark row for the arrangement
`examples/breakout/sprites/breakout.bas` actually has, which is 211.8 ns, or
4.5% of a frame. That game reaches it because two of its eight sprites are the
screen -- a captured HUD strip and a captured play field -- so the field's box
covers everything and those pairs can never be rejected. Roughly double the old
cost, for contacts. Recorded in MAINTENANCE.md with the two synthetic extremes
either side of it as a bracket.

The eight proxies are claimed once at init and held, so exhaustion of the pool
shared with an embedding host is an initialization failure that names the pool
rather than a collision scan refusing halfway through somebody's game. The shape
is built before the proxy is spawned from it and the acquire sits adjacent to the
initialize, which are two traps libakgl hit itself and documents.

`tests/akgl_backends.c` now tears the sprite backend down between cases. It never
did, and got away with it while init claimed nothing; eight proxies apiece across
twenty cases is a hundred and sixty against a pool of a hundred and twenty-eight.
A host releases what it took, and so does the harness.

Both games run forty seconds headless with no error line. 111 with akgl, 110
without.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
This commit is contained in:
2026-08-02 09:48:11 -04:00
parent 1da37cf374
commit f06c53110d
5 changed files with 335 additions and 56 deletions

View File

@@ -31,6 +31,7 @@
#include <akgl/actor.h>
#include <akgl/character.h>
#include <akgl/collision.h>
#include <akgl/renderer.h>
#include <akgl/sprite.h>
#include <akgl/version.h>
@@ -235,6 +236,42 @@ typedef struct
/** Per-axis expansion, which an actor's single `scale` cannot carry. */
bool xexpand[AKBASIC_MAX_SPRITES];
bool yexpand[AKBASIC_MAX_SPRITES];
/**
* One collision proxy per slot, claimed once at init and held for the life
* of the backend.
*
* Claimed up front rather than per scan for two reasons. The pool is shared
* with whatever host this interpreter is embedded in -- a game with its own
* shaped actors draws from the same #AKGL_MAX_HEAP_COLLISION_PROXY -- so
* running out is a real possibility, and it should be an init-time failure
* naming the pool rather than a collision scan that starts refusing halfway
* through a game. And a proxy carries a *copy* of its shape, so there is
* nothing to rebuild per scan beyond the position.
*
* These are not registered with any partitioner. akgl_collision_test()
* takes two positioned proxies and needs no world, which is what lets eight
* sprites be tested pairwise without paying for a broad phase that eight
* objects would not repay.
*/
akgl_CollisionProxy *proxies[AKBASIC_MAX_SPRITES];
/**
* The shape each proxy is synced from.
*
* Kept here rather than read back off the proxy because
* akgl_collision_proxy_sync() wants a live shape to copy from, and because
* the shape is derived from the sprite's frame and expansion bits every scan
* -- a sprite whose picture or expansion changed has a different box, and
* the cheapest correct thing is to rebuild it rather than track what
* invalidates it.
*/
akgl_CollisionShape shapes[AKBASIC_MAX_SPRITES];
/**
* The rectangle each proxy was last synced from, so a scan can tell whether
* there is anything to sync. See sync_proxy() in src/sprite_akgl.c for why
* this is compared rather than flagged.
*/
SDL_FRect syncedbox[AKBASIC_MAX_SPRITES];
} akbasic_AkglSprites;
/**