Skip to content

Restore original Supaplex behavior in 11 assembly translation fixes - #82

Merged
sergiou87 merged 13 commits into
masterfrom
fix-assembly-translation
Oct 20, 2026
Merged

sergiou87 merged 13 commits into
masterfrom
fix-assembly-translation

Conversation

@sergiou87

Copy link
Copy Markdown
Owner

Summary

Restore behavior from the original SpeedFix v6.3 implementation across 11 assembly-to-C translation fixes. Each fix is isolated in its own commit and backed by a counterexample plus controls checked against the unmodified original under DOSBox.

This is a compatibility change, including preservation of unusual border behavior and signed-byte ordering—not a redesign of the original game rules.

Gameplay fixes

  1. Require a stationary infotron when collecting downward (ca28d30). The C code checked only the tile type, allowing Murphy to collect an already-falling infotron and survive. Match the original cmp ax, 4 by requiring state zero as well. falling-infotron-down.sp must fail; its one-tile stationary-infotron control must succeed.

  2. Preserve reserved Space after downward infotron collection (ff9a6af). The vacated cell was incorrectly marked as Base instead of Space with its movement state preserved. A debug B-key press could clear that reservation early, let a zonk fall, and then erase the zonk when Murphy finished moving. The new debug adapter supplies the real B-key event at frame 34; the counterexample must fail, while the real-Base control remains solvable.

  3. Allow zonks to roll beneath a falling zonk (fbe339d). When the right-hand destination is reserved as 0x9999, the original executable checks the upper-right zonk's tile byte without requiring its animation state to be zero. Remove the extra state restriction. The two-zonk counterexample and hardware control both solve in the original and now in C. The executable's byte comparison is documented in the regression notes rather than changing the assembly reference.

  4. Match special-port records by their exact encoded position (6b8ab2e). Dividing the stored byte offset by two rounded odd offsets down, incorrectly activating records for neighboring coordinates. Compare the full 16-bit byte offset instead. Offset 1221 must not match the port at offset 1220; the matching-offset control still enables gravity and fails as expected.

  5. Keep planted red-disk positions signed (0055710). A disk planted through an empty top border can occupy tile -49. The unsigned C position became tile 65487, leaving the actual disk missing and changing subsequent movement. Use a signed tile index, matching Murphy's position and the original address arithmetic. The short-input counterexample now fails like the original; the longer-input control still succeeds. Signed, legacy unsigned-negative, and positive savegame round trips were checked.

  6. Preserve hardware explosion immunity for nonzero states (8cc9b21). Hardware immunity depends only on tile type, not on its state byte. The counterexample reaches the existing padded hardware word 0x8E06 without injecting a tile state: the original survives, while the old C code exploded it and killed Murphy. Both the hardware-bump replay and no-bump control now succeed.

  7. Preserve shared playfield and explosion-timer storage (6bc1632). The original timer bytes immediately follow the level words and can also be reached as off-field tiles. Separate C allocations lost that aliasing. Introduce a shared LevelMemory union with the existing array views and initialization assertions. A real countdown can therefore expose an exit at tile 1536, matching the original counterexample; the one-tile control still fails. Existing serialized region sizes are unchanged, with legacy load, aliasing in both directions, and save/load round trips checked.

  8. Require zero state when entering an exit downward (bd850f2). Match the original cmp ax, 7, not just the exit tile byte. The restored timer alias makes the distinction observable: word 0x0707 must not count as a usable exit, while the 0x0007 control must succeed.

Menu and score fixes

  1. Preserve 16-bit wraparound in menu autorepeat (f7e4315). C integer promotion made frame-counter subtraction negative after wraparound and stalled repeated input. Cast the subtraction back to uint16_t in all seven level/player/ranking scrolling and level-set rotation guards. A 177-frame original mouse trace crosses 0xFFFF naturally and verifies repeat timing; a 65-frame nonwrapping control preserves existing behavior.

  2. Restore original player-ranking time tie-breaks (f2a532b). Both elapsed-time totals were calculated from the same player, making the tie-break ineffective; its comparison direction also disagreed with the original. Compare progress descending, then hours/minutes/seconds ascending, using the original signed-byte keys and stable ordering for equal keys. Displayed time bytes remain unsigned. Original player-file cases cover each time field, equal-time stability, completed players, the current player's rank, long-hour signed ordering, and a distinct-progress control.

  3. Use signed time comparisons for Hall of Fame insertion (fd19527). Match the original signed jl instructions for hours, minutes, and seconds. This preserves the original treatment of 128–255-hour totals, which the unsigned C comparisons rejected against ordinary existing entries. Eight cases were captured after actually completing the original game's final level, covering the 127/128 boundary, 200 and 255 hours, faster insertion, minute/second comparisons, and a slower player. The adapter checks all three resulting entries and the completion flag. Stored/displayed bytes and empty-entry handling are unchanged.

Regression infrastructure

  • Add 16 synthetic .SP replays and 12 CSV cases, with dedicated adapters for debug keyboard input, menu traces, rankings, and Hall of Fame updates.
  • Extend run-tests.rb with explicit expected exit codes, alternate test executables, and CSV patterns. Expected-failure replays must return exactly 1; crashes and other exit codes are failures. The legacy tests/failures collection remains excluded.
  • Invoke test executables with argument arrays and an explicit working directory instead of interpolated shell commands.
  • Fix skipped replay workers (82ea831): join the worker removed from the queue rather than the next worker. Otherwise an unfinished worker could report after suite totals were recorded, omitting a test or failure. Add a deterministic scheduler regression and run it before the CI build.
  • Build and package all adapters in the existing test/CI flow. Fixture behavior, original references, and controls are documented in tests/README.md.

Verification and scope

  • Complete automated corpus: 6,922 passed, 0 failed, including all eight Hall of Fame cases after fixing the scheduler.
  • Normal headless test build and standalone scheduler regression pass. No sanitizer launches were used for the final validation.
  • Original-game evidence comes from recorded playback, input traces, loaded player files, and saved results. The observer/input helpers do not patch the original executable or inject game state.
  • Reference executable: unmodified SpeedFix v6.3, SHA-256 6599ce5c175a74db1af288fbaf82103f66deb6f8a98d53f863688bfbb8537159.
  • asm/ has no net changes against the base branch. Commit f2543e2 restores an earlier operand annotation; the assembly remains the read-only reference. The zonk executable/assembly operand-width discrepancy is documented separately.
  • The explicitly excluded cached-demo metadata initialization issue is not changed. No renderer/audio or dependency changes are included.

Match loc_4E1A1's word comparison by requiring an infotron with zero
state before Murphy can collect it while moving down.

Add a falling-infotron replay that must fail and a one-tile stationary
control that must succeed, both verified against SpeedFix 6.3. Run the
regression suites with explicit expected exit codes so crashes cannot
satisfy expected-failure cases.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Match loc_4E5BA by keeping Murphy's vacated cell as reserved Space
until downward collection finishes. Marking it as Base allowed debug B
to clear it early, letting a zonk enter and then be erased by movement
cleanup, which could incorrectly open a route to the exit.

Add a replay proven to fail in SpeedFix 6.3 but succeed before this fix,
plus a one-tile positive control. A test-only keyboard adapter supplies
the frame-34 B key because debug keys are not stored in demo streams.
Build and run both debug regression suites in CI.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Match SpeedFix 6.3's byte comparison at loc_48011: a zonk may roll
right into a 0x9999 reservation when the tile above it is a zonk,
regardless of that upper zonk's animation state. The extra state-zero
check delayed the roll and caused otherwise valid replays to fail.

Make the byte operand explicit in the assembly reference, verified
against the unmodified executable's instruction at CS:1400. Add a
minimal two-zonk solution and a one-tile positive control, both proven
successful in the original game under DOSBox.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Keep the assembly source unchanged and record the verified SpeedFix 6.3
operand-width evidence only in regression documentation. Retain the C
zonk-roll fix and its original-backed replay coverage.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Compare the full 16-bit byte offset used by the original sub_4F2AF
routine instead of dividing stored coordinates before comparison.
Division rounded odd, nonmatching records down to real port positions
and could incorrectly enable gravity or change freeze flags.

Add an original-backed replay whose odd record must be ignored and a
one-byte matching-position control that must enable gravity. The former
succeeds in SpeedFix 6.3 but failed before this fix; the control fails
in both engines. Keep the assembly reference unchanged.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Use the same signed tile-index type as Murphy so red disks planted
above an empty top border address the existing pre-playfield padding.
The unsigned position wrapped tile -49 to 65487, updating unrelated
memory instead of placing the disk and allowing invalid replay wins.

Add an original-backed failing replay and a longer-input successful
control. Verify negative positions and legacy unsigned savegame values
still load correctly. Leave the assembly reference unchanged.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Match sub_4A61F's tile-byte comparison: hardware remains immune to an
explosion regardless of its state byte. The extra state-zero condition
could destroy existing pre-playfield hardware and kill Murphy when
walking through an empty top border.

Add an original-backed replay that bumps the existing 0x8E06 hardware
word at tile -300 and returns to the exit, plus a no-bump control. No
tile states are injected and the assembly reference stays unchanged.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Model the original contiguous level words and explosion timer bytes
with two views of one allocation. Border movement can interpret timer
bytes as tiles; separate C arrays lost that alias and accessed unrelated
memory beyond the level-state allocation.

Keep the existing array views and serialized sizes intact so legacy
savegames still load. Assert the original two-byte tile and timer-offset
layout at initialization.

Add an original-backed replay that enters an exit represented by timer
bytes 07 00 and a one-tile control that leaves the timer clear. Leave
the assembly reference unchanged.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Match loc_4E1A9's full-word cmp ax,7 by checking both the exit tile
and its state. The missing state check allowed Murphy to complete a
level through a nonzero-state tile that the original game rejects.

Add a replay that generates exit word 0x0707 through two explosion
timers and a one-tile control that generates usable exit word 0x0007.
Both outcomes were verified in unmodified SpeedFix 6.3 under DOSBox.
Leave the assembly reference unchanged.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Match the original AX subtraction before unsigned timestamp comparison
in level, player, and ranking scrolling and level-set rotation. C integer
promotion kept negative subtraction results instead of wrapping at 16
bits, stalling menu autorepeat when the frame counter wrapped.

Add a 177-frame mouse-input trace recorded from unmodified SpeedFix 6.3
across its natural counter wrap and a 65-frame nonwrapping control.
Replay their original counter observations against all seven C handlers
in the automatic test suite. Keep the assembly reference unchanged.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Replace the duplicated current-player time totals with the original
lexicographic comparator: progress descending, then hours, minutes, and
seconds ascending. Preserve signed-byte sort keys and stable equal-time
ordering while keeping displayed time bytes unsigned.

Add player-file cases captured from the unmodified original menu,
covering each time field, long-hour signed ordering, stable ties,
completed players, current-player rank, and distinct-progress control.
Run the ranking adapter in the automatic regression suite.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Join the worker removed from the queue instead of joining the next
worker. Otherwise an untracked worker can finish after suite totals
are recorded, omitting a case or its failure from the result.

Add a deterministic pending-worker scheduler regression and run it
before the CI test build. This was exposed while validating the new
eight-case Hall of Fame regression suite.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
Interpret hours, minutes, and seconds as signed bytes for insertion
comparisons, matching the original JL instructions while preserving
unsigned stored and displayed time values.

Add eight cases captured from unmodified SpeedFix v6.3 after completing
the actual final level. Cover the 127/128-hour boundary, 200- and
255-hour counterexamples, and normal time-field insertion controls.
Wire the adapter into the automatic regression suite and CI build.

Copilot-Session: 0874adb5-cd69-4c8a-8cd0-71f2f9f7201f
@sergiou87
sergiou87 marked this pull request as ready for review October 20, 2026 15:11
@sergiou87
sergiou87 merged commit 040f18a into master Oct 20, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant