andrew/akbasic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Collide sprites with rectangles that are not sprites
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m19s
Details
akbasic CI Build / sanitizers (push) Failing after 4m33s
Details
akbasic CI Build / coverage (push) Failing after 3m41s
Details
akbasic CI Build / akgl_build (push) Failing after 21s
Details
akbasic CI Build / mutation_test (push) Failing after 3m29s
Details

Browse Source 
`SOLID id, x1, y1, x2, y2` registers static collision geometry; `SOLID id`
retires one and a bare `SOLID` retires them all, the way `TRAP`, `COLLISION` and
`DCLOSE` all read absence. `COLLISION 2` and `BUMP(2)` stop being refused and
mean *sprite met static geometry*.

**This is the thing eight sprite slots made impossible.** A wall of bricks wants
sixty, so until now a program could only collide with one by doing the
arithmetic itself against its own array -- which is exactly what both breakout
listings do, at about two hundred lines between them. A rectangle costs no sprite
slot.

The id is the **program's own number**, 1 to 64, not a minted handle. That is the
whole trick for "which brick did I hit": the id comes back out again, so a wall
built as `SOLID I#, ...` maps onto `B#(I#)` with no lookup, and retiring a broken
brick is `SOLID I#`.

`COLLISION 2` was refused with "sprite-to-background collision needs the screen
read back every frame", which was true of the question a C128 asks -- a sprite
against the bitmap's set pixels. `SOLID` gives this interpreter a background made
of rectangles instead, which is the same question in a form it can answer. Same
move `SPRSAV` made when it learned to take an image path.
`AKBASIC_INTERRUPT_BACKGROUND` has been sitting in the interrupt table commented
"COLLISION 2 -- sprite met background; refused" the whole time. Its accumulator is
separate, so a sprite hitting a wall never sets a bit in `BUMP(1)`.

**There is no `akgl_CollisionWorld` here, and that is deliberate.** libakgl's
uniform grid keeps its cell heads, cell size and origin in file-scope statics, so
it is one index per process -- and `akgl_collision_world_init()` ends in a
`reset()` that memsets those heads *and* calls
`akgl_heap_init_collision_cells()`. An interpreter embedded in a game with its
own collision world would have destroyed every registration that game had made,
on the first `SOLID` a script ran. So the geometry is indexed by an ordinary
array here and pairs go straight to `akgl_collision_test()`, which needs no
world. At sixty-four rectangles that is the right answer anyway; libakgl's own
numbers put a naive sweep at 0.7% of a frame at sixty-four objects.

**The scan now short-circuits when nothing has moved**, and that is what makes
any of it affordable. Its inputs are the sprites' boxes, which slots are
collidable, and the static geometry; if none changed the answer cannot have. A
frame runs one full scan and 255 cached ones. Eight sprites against sixty-four
rectangles is five hundred and twelve tests -- fine once a frame, ruinous 256
times.

The benchmark was rewritten to say which path it is timing, because with the
cache in place a loop that only calls the scan measures the short circuit and
nothing else. Breakout now costs 590.6 ns for its one full scan plus 255 cached
at 40.0, which is 10.8 us against a 1.19 ms frame -- **0.91%, less than the 2.0%
it cost before any of this work**, with static geometry and contacts added on
top.

`NEW` retires the rectangles, where it cannot undefine a sprite pattern: there
*is* an entry point for this one, so leaving them would be a choice, and the
wrong one -- a rectangle is invisible, so one left behind by a deleted program is
an unexplainable collision in the next. `CLR` leaves them alone.

`tests/sprite_verbs.c` gains the whole second path against the mock and its
`COLLISION 2` case is rewritten: it pinned the refusal, and now pins that type 2
arms its own handler without disturbing type 1's. `tests/akgl_backends.c` gains
the end-to-end version, including a full sixty-four-rectangle wall so the proxy
budget is exercised at its ceiling and the pool has to come back intact, and the
sixty-fifth refused by name.

A bare `SOLID` needed `akbasic_parse_optional_arglist` rather than
`akbasic_parse_arglist`, which `DCLOSE` already uses for the same shape.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
This commit is contained in:
Andrew Kesterson
2026-08-02 10:25:35 -04:00
parent f005b88980
commit 802bbcc17a
15 changed files with 764 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
tests/akgl_backends.c
View File

@@ -844,6 +844,99 @@ static akerr_ErrorContext AKERR_NOIGNORE *test_sprite_shapes(void)
SUCCEED_RETURN(errctx);
}
/** @brief Run a program and report the static-geometry mask. */
static akerr_ErrorContext AKERR_NOIGNORE *solidmask_for(const char *source, uint16_t *dest)
{
PREPARE_ERROR(errctx);
PASS(errctx, start_runtime(source));
TEST_REQUIRE_STR(OUTPUT, "");
PASS(errctx, SPRITES.solids(&SPRITES, dest));
SUCCEED_RETURN(errctx);
}
/**
* @brief SOLID puts a collidable rectangle on the field without spending a sprite.
*
* This is the point of the whole exercise. A brick is not a sprite -- there are
* eight and a wall wants sixty -- so until now a program could only collide with
* one by doing the arithmetic itself against its own array. Now it registers a
* rectangle and the interpreter answers.
*/
static akerr_ErrorContext AKERR_NOIGNORE *test_static_geometry(void)
{
PREPARE_ERROR(errctx);
uint16_t mask = 0;
/* A 24x21 sprite at (100, 100) squarely inside a rectangle. */
PASS(errctx, solidmask_for("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 SPRITE 1, 1\n"
"70 SOLID 7, 90, 90, 140, 140\n"
"80 MOVSPR 1, 100, 100\n", &mask));
TEST_REQUIRE_INT(mask, 0x01);
stop_runtime();
/* Moved clear of it, nothing. */
PASS(errctx, solidmask_for("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 SPRITE 1, 1\n"
"70 SOLID 7, 90, 90, 140, 140\n"
"80 MOVSPR 1, 200, 200\n", &mask));
TEST_REQUIRE_INT(mask, 0);
stop_runtime();
/*
* Retired, and the sprite has not moved. This is the assertion that catches
* a proxy released without its registration going with it -- the shape would
* still be found and the mask would still come back set.
*/
PASS(errctx, solidmask_for("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 SPRITE 1, 1\n"
"70 SOLID 7, 90, 90, 140, 140\n"
"80 MOVSPR 1, 100, 100\n"
"90 SOLID 7\n", &mask));
TEST_REQUIRE_INT(mask, 0);
stop_runtime();
/*
* A full wall registered, walked into, and cleared -- sixty-four of them, so
* the proxy budget is exercised at its ceiling and the pool has to come back
* intact afterwards or the next case fails.
*/
PASS(errctx, solidmask_for("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 SPRITE 1, 1\n"
"70 FOR I# = 1 TO 64\n"
"80 X# = I# * 30\n"
"90 SOLID I#, X#, 0, X# + 20, 20\n"
"100 NEXT I#\n"
"110 MOVSPR 1, 300, 5\n", &mask));
TEST_REQUIRE_INT(mask, 0x01);
stop_runtime();
/* And the sixty-fifth is refused by name rather than exhausting the pool. */
PASS(errctx, start_runtime("10 SOLID 65, 0, 0, 10, 10\n"));
TEST_REQUIRE(strstr(OUTPUT, "outside 1..64") != NULL,
"SOLID 65 should be refused, got \"%s\"", OUTPUT);
stop_runtime();
SUCCEED_RETURN(errctx);
}
int main(void)
{
PREPARE_ERROR(errctx);
@@ -913,6 +1006,7 @@ int main(void)
CATCH(errctx, test_collision_pairs());
CATCH(errctx, test_collision_cross_shape());
CATCH(errctx, test_sprite_shapes());
CATCH(errctx, test_static_geometry());
} CLEANUP {
if ( font != NULL ) {
TTF_CloseFont(font);

36
tests/collision_perf.c
View File

@@ -121,6 +121,26 @@ static void sprite_program(char *dest, size_t size, int n, bool stacked)
}
}
/**
* @brief Move sprite 1 a pixel, then scan. One full scan, no cache hit.
*
* The scan short-circuits when no sprite has moved since the last one, which is
* what 255 of every 256 calls a frame do -- so a loop that only calls the scan
* measures the short circuit and nothing else. Nudging a sprite first is what
* makes a row mean "a scan that actually ran".
*/
static float32_t bench_nudge = 0.0f;
static akerr_ErrorContext AKERR_NOIGNORE *move_and_scan(uint16_t *mask)
{
PREPARE_ERROR(errctx);
bench_nudge = (bench_nudge > 0.5f ? 0.0f : 1.0f);
PASS(errctx, SPRITES.move(&SPRITES, 1, 20.0 + (double)bench_nudge, 20.0));
PASS(errctx, SPRITES.collisions(&SPRITES, mask));
SUCCEED_RETURN(errctx);
}
/**
* @brief The arrangement examples/breakout/sprites/breakout.bas actually has.
*
@@ -162,7 +182,17 @@ static akerr_ErrorContext AKERR_NOIGNORE *bench_breakout_shaped(void)
"200 MOVSPR 7, 600, 400\n"
"210 MOVSPR 8, 200, 150\n"));
bench_start("spr_collisions, breakout's own layout", "call", 0.0);
bench_start("full scan, breakout's own layout", "call", 0.0);
BENCH_LOOP(inner, i, iterations, move_and_scan(&mask));
bench_stop((uint64_t)iterations);
PASS(errctx, inner);
/*
* And the other path, on the same population: what the other 255 calls a
* frame cost once the first has done the work. This row is the reason the
* per-step cadence is affordable at all.
*/
bench_start("cached scan, nothing moved", "call", 0.0);
BENCH_LOOP(inner, i, iterations, SPRITES.collisions(&SPRITES, &mask));
bench_stop((uint64_t)iterations);
PASS(errctx, inner);
@@ -184,10 +214,10 @@ static akerr_ErrorContext AKERR_NOIGNORE *bench_scan(int n, bool stacked)
sprite_program(source, sizeof(source), n, stacked);
PASS(errctx, load(source));
snprintf(name, sizeof(name), "spr_collisions, %d sprites, %s", n,
snprintf(name, sizeof(name), "full scan, %d sprites, %s", n,
(stacked ? "all overlapping" : "spread out"));
bench_start(name, "call", 0.0);
BENCH_LOOP(inner, i, iterations, SPRITES.collisions(&SPRITES, &mask));
BENCH_LOOP(inner, i, iterations, move_and_scan(&mask));
bench_stop((uint64_t)iterations);
PASS(errctx, inner);
SUCCEED_RETURN(errctx);

45
tests/mockdevice.h
View File

@@ -56,6 +56,7 @@ typedef struct
/* Sprites */
uint16_t collisions; /* what the next collisions() call reports */
uint16_t solidcollisions; /* and what the next solids() call reports */
int patternbytes[AKBASIC_MAX_SPRITES]; /* bytes the last define() carried, per sprite */
} akbasic_MockDevice;
@@ -428,6 +429,40 @@ static akerr_ErrorContext *mock_spr_collisions(akbasic_SpriteBackend *self, uint
SUCCEED_RETURN(errctx);
}
static akerr_ErrorContext *mock_spr_solids(akbasic_SpriteBackend *self, uint16_t *mask)
{
PREPARE_ERROR(errctx);
(void)self;
FAIL_ZERO_RETURN(errctx, (mask != NULL), AKERR_NULLPOINTER, "NULL mask in solids");
*mask = MOCK.solidcollisions;
SUCCEED_RETURN(errctx);
}
static akerr_ErrorContext *mock_spr_shape(akbasic_SpriteBackend *self, int n, int kind,
double x1, double y1, double x2, double y2)
{
PREPARE_ERROR(errctx);
(void)self;
mock_log("sprhit %d,%d,%g,%g,%g,%g\n", n, kind, x1, y1, x2, y2);
SUCCEED_RETURN(errctx);
}
static akerr_ErrorContext *mock_spr_solid(akbasic_SpriteBackend *self, int id, bool define,
double x1, double y1, double x2, double y2)
{
PREPARE_ERROR(errctx);
(void)self;
if ( !define ) {
mock_log("solid %d off\n", id);
SUCCEED_RETURN(errctx);
}
mock_log("solid %d,%g,%g,%g,%g\n", id, x1, y1, x2, y2);
SUCCEED_RETURN(errctx);
}
/* ---------------------------------------------------------------- fixture -- */
/** @brief Reset the recorder and populate all three vtables. */
@@ -485,6 +520,9 @@ static void mock_devices_init(void)
MOCK_SPRITES.configure = mock_spr_configure;
MOCK_SPRITES.shared_colors = mock_spr_shared_colors;
MOCK_SPRITES.collisions = mock_spr_collisions;
MOCK_SPRITES.solids = mock_spr_solids;
MOCK_SPRITES.shape = mock_spr_shape;
MOCK_SPRITES.solid = mock_spr_solid;
}
/** @brief Set what the next collisions() call will report. Bit n-1 is sprite n. */
@@ -494,6 +532,13 @@ static void mock_set_collisions(uint16_t mask)
MOCK.collisions = mask;
}
/** @brief Set what the next solids() call will report. Bit n-1 is sprite n. */
__attribute__((unused))
static void mock_set_solid_collisions(uint16_t mask)
{
MOCK.solidcollisions = mask;
}
/** @brief Prime the input backend with keystrokes GET will drain in order. */
__attribute__((unused))
static void mock_push_keys(const char *keys)

94
tests/sprite_verbs.c
View File

@@ -350,9 +350,32 @@ static void test_collision_arming(void)
"COLLISION with no target should disarm");
harness_stop();
TEST_REQUIRE_OK(run_program("10 COLLISION 2, 100\n"));
TEST_REQUIRE(strstr(HARNESS_OUTPUT, "read back every frame") != NULL,
"COLLISION 2 should be refused with a reason, got \"%s\"", HARNESS_OUTPUT);
/*
* Type 2 arms a *second* handler, on its own interrupt source, and leaves
* type 1's alone. It used to be refused -- a C128's type 2 is a sprite
* against the bitmap screen's set pixels, which needs the render target read
* back every frame -- and SOLID is what turned it into a question this
* interpreter can answer, against rectangles instead of pixels.
*/
TEST_REQUIRE_OK(run_program("10 COLLISION 1, 100\n"
"20 COLLISION 2, 200\n"));
TEST_REQUIRE_STR(HARNESS_OUTPUT, "");
TEST_REQUIRE(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].armed,
"COLLISION 1 should still have armed the sprite interrupt");
TEST_REQUIRE_INT(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].line, 100);
TEST_REQUIRE(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_BACKGROUND].armed,
"COLLISION 2 should have armed the background interrupt");
TEST_REQUIRE_INT(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_BACKGROUND].line, 200);
harness_stop();
/* And disarming one leaves the other armed. */
TEST_REQUIRE_OK(run_program("10 COLLISION 1, 100\n"
"20 COLLISION 2, 200\n"
"30 COLLISION 2\n"));
TEST_REQUIRE(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].armed,
"disarming type 2 should not have disarmed type 1");
TEST_REQUIRE(!HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_BACKGROUND].armed,
"COLLISION 2 with no target should disarm");
harness_stop();
TEST_REQUIRE_OK(run_program("10 COLLISION 3, 100\n"));
@@ -407,6 +430,70 @@ static void test_collision_fires(void)
harness_stop();
}
/**
* @brief SOLID registers static geometry, and COLLISION 2 fires on meeting it.
*
* The whole second path, against the mock: the device is told about a rectangle,
* the scan reports a sprite touching one, the service accumulates it on its own
* accumulator and raises its own interrupt, and BUMP(2) reports and clears
* without disturbing BUMP(1).
*/
static void test_solid_geometry(void)
{
TEST_REQUIRE_OK(harness_start(NULL));
mock_devices_init();
TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, NULL, NULL,
&MOCK_SPRITES));
TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME,
"1 COLLISION 2, 5\n"
"2 SOLID 7, 100, 100, 140, 120\n"
"3 PRINT \"MAIN\"\n"
"4 GOTO 3\n"
"5 PRINT \"WALL \" + BUMP(2)\n"
"6 PRINT \"SPRITES \" + BUMP(1)\n"
"7 RETURN\n"));
TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 3));
TEST_REQUIRE(strstr(MOCK.log, "solid 7,100,100,140,120") != NULL,
"SOLID should have reached the device, log was \"%s\"", MOCK.log);
/* Sprite 1 meets a wall; nothing meets another sprite. */
mock_set_solid_collisions(0x01);
TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 2));
TEST_REQUIRE(strstr(HARNESS_OUTPUT, "WALL 1") != NULL,
"the type 2 handler should have reported sprite 1, got \"%s\"", HARNESS_OUTPUT);
mock_set_solid_collisions(0);
TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 2));
/* The two accumulators are separate: BUMP(1) saw nothing. */
TEST_REQUIRE(strstr(HARNESS_OUTPUT, "SPRITES 0") != NULL,
"a static collision should not set BUMP(1), got \"%s\"", HARNESS_OUTPUT);
TEST_REQUIRE_INT(HARNESS_RUNTIME.sprite_state.bumpedsolid, 0);
harness_stop();
/* SOLID with no arguments retires every one of them. */
TEST_REQUIRE_OK(run_program("10 SOLID 3, 0, 0, 10, 10\n"
"20 SOLID 4, 20, 20, 30, 30\n"
"30 SOLID\n"));
TEST_REQUIRE(strstr(MOCK.log, "solid 3 off") != NULL,
"bare SOLID should have retired 3, log was \"%s\"", MOCK.log);
TEST_REQUIRE(strstr(MOCK.log, "solid 4 off") != NULL,
"bare SOLID should have retired 4, log was \"%s\"", MOCK.log);
harness_stop();
/* Out of range, and a rectangle that is not one. */
TEST_REQUIRE_OK(run_program("10 SOLID 999, 0, 0, 10, 10\n"));
TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 1..") != NULL,
"SOLID 999 should be refused, got \"%s\"", HARNESS_OUTPUT);
harness_stop();
TEST_REQUIRE_OK(run_program("10 SOLID 1, 10, 10, 10, 20\n"));
TEST_REQUIRE(strstr(HARNESS_OUTPUT, "not a rectangle") != NULL,
"a zero-width SOLID should be refused, got \"%s\"", HARNESS_OUTPUT);
harness_stop();
}
/** @brief The readbacks answer from interpreter state, so they need no device. */
static void test_readbacks(void)
{
@@ -518,6 +605,7 @@ int main(void)
test_sprsav_refuses_to_write();
test_collision_arming();
test_collision_fires();
test_solid_geometry();
test_readbacks();
test_no_device();
test_new_clears_sprites();