How it works · write-up

Ship attachment renderer validation

xenondoc/SHIP_ATTACHMENT_RENDER_TESTS.md · 10 KB · updated 2026-10-06

xenon_tools/validate_ship_attachments.py tests original-game weapon installations instead of substituting attachment codes in RAM. It starts each case from a Sell-mode shop checkpoint, patches only cash, sells existing weapons, buys the requested item through the original menu, and confirms the installed loadout. Successive purchases explore the original power grades and additional mounts. The original installer refusing another purchase terminates that family.

The test uses a full-stock shop with an availability limit of at least 6000. Only the test cash balance is changed; no compatibility or slot checks are bypassed. The new control command SET_SHOP_TEST_CASH (26, big-endian u32) requires a paused shop and stopped native autopilot, with value 0..999999. Normal autopilot play never calls it.

The fixed shop input helper is a test driver, not a Python autopilot. The resident C pilot handles the loading-screen FIRE prompt. The harness waits for the gameplay player and verifies that the weapon survived the shop exit. Each recorded probe then uses validate_campaign.py native-run --connect, resident C control, visible Hatari, fast-forward, both original/Sprite AVIs, 150-frame checkpoints and graceful AVI finalization. Only owned emulator processes are stopped. Both Hatari and the replay DLL are rebuilt by --build using hatari_dev.ps1.

Example from the repository root (also valid in cmd.exe as one line):

python xenon_tools/validate_ship_attachments.py --checkpoint E:/xenon_runs/level4-full-after-level3-20261003-r278.validation/checkpoints/f38513-periodic.sav --output E:/xenon_runs/NEW-ATTACHMENT-MATRIX --build --frames 200 --max-purchases 16

--items 19 --max-purchases 1 runs a short Drone smoke test. Weapon families: Forward, Rear, both Mines, Side, Electro Ball, Double, Cannon, Missile Launcher, Laser, Drone, Flamer, Bomb and Homing Missile. The default Forward Shot is created by the original game after selling the primary upgrade; it is not manufactured by the test. Nashwan, Dive and Protection purchases are additional non-weapon checks. Buying Dive alone does not test activation of its manual control.

Laser upgrades need POWERUP purchases, rather than more Laser purchases once the four auxiliary mounts are occupied. ReVa $5126 selects the lowest power below its maximum among the seven equipped slots, retaining the first slot on ties, and increments its object +$42. Cannon and Missile Launcher have maximum zero in the tested original objects. Four base Lasers plus the base Forward Shot need five POWERUPs for all power 1, and ten for all power 2:

python xenon_tools/validate_ship_attachments.py --checkpoint E:/xenon_runs/level4-full-after-level3-20261003-r278.validation/checkpoints/f38513-periodic.sav --output E:/xenon_runs/NEW-LASER-GRADE1 --items 18 --min-purchases 4 --max-purchases 4 --powerups 5 --frames 200

Use a new output directory and --powerups 10 for grade 2. This also exercises the original Forward Shot at both upgraded powers. The observed loadout in the report is authoritative; the harness does not patch power words.

Homing Missile can occupy either wing. Use --items 23 --max-purchases 1 --preload-items 19 to install a Drone first and test the Homing Missile in the right wing through the original compatibility checks. Other wing weapons have fixed mounts. --preload-items is recorded in the report and setup evidence.

Each setup directory retains shop.ram, the original transactions with frames and cash changes, and installed loadouts. Each .validation directory contains the native recording, both AVIs/VBL indices, manifest/source snapshot, incidents, comparison JSON and the worst original/Sprite/difference image. The manifest explicitly marks the cash cheat and links back to the setup and original checkpoint. report.json retains every script option, successful case and failure; report.md summarizes coverage.

Comparison uses exact VBL tags, authentic latency +2 VBL, original AVI dimensions (normally 2x logical pixels), and the full 192-row playfield excluding the eight-row HUD. Loading frames are not accepted as weapon coverage. No recorded firing frames is a failed probe. Differences can include clipping, overlap and host overlays; inspect the comparison image before attributing them to a missing weapon. Whole-frame identity alone does not prove offscreen, hit-flash or every possible weapon/terrain interaction correct.

Refresh an existing matrix's comparisons without running an emulator:

python xenon_tools/validate_ship_attachments.py --output E:/xenon_runs/EXISTING-MATRIX --compare-only

The corrected Drone smoke test is E:/xenon_runs/attachment-matrix-20261004-smoke6/attachment-19-buy1.validation/attachment-19-buy1.x2events. All 188 aligned playfield frames match, with 94 firing frames. Earlier smoke attempts are rejected harness development runs, not rendering validation.

The complete 2026-10-04 matrix and its remaining differences follow.

Results — 2026-10-04

41 visible resident-C gameplay probes tested every purchasable weapon family, the observed original power grades, all four auxiliary mounts, and both Homing Missile wing placements. Each used real shop transactions after a cash-only cheat. Nashwan, Dive and Protection purchases were also exercised. Dive manual activation was not tested.

All 82 paired AVI files passed the RIFF/container/index structural audit. All probes fired. Across 9377 aligned playfield frames, 7632 were pixel-identical; 19 of the 41 probes were identical throughout. This is coverage with remaining rendering differences, not a declaration that every render is correct.

Coverage

Forward Shot powers 1 and 2 were additionally exercised in the two full-mount Laser POWERUP probes. The Forward row above counts only its dedicated base probe.

Reproduction and recordings

See the harness instructions above. Source checkpoint: E:/xenon_runs/level4-full-after-level3-20261003-r278.validation/checkpoints/f38513-periodic.sav. The five result directories each contain report.json with every option and transaction, and report.md with recording paths:

• E:\xenon_runs\attachment-matrix-20261004-all
• E:\xenon_runs\attachment-laser-grade1-20261004
• E:\xenon_runs\attachment-laser-grade2-20261004
• E:\xenon_runs\attachment-homing-right-20261004
• E:\xenon_runs\attachment-bound-check-20261004

The initial matrix also attempted one purchase beyond the original maximum. Twelve such attempts were recorded as acknowledgement timeouts by the first harness version; they are not successful renderer tests. The corrected harness returns “no additional offer/grade” when cash and inventory remain unchanged. A fresh Electro Ball bound check verifies that outcome. Existing errors remain in the original report rather than being rewritten as passes.

Remaining differences

• Most nonidentical ordinary-weapon probes differ by 4–16 physical pixels. Keep these as residuals; whole-frame similarity does not prove correct clipping or overlapping draws.
• Laser mount probes differ by up to 64 pixels at power 0, 40 at power 1 and 68 at power 2. Saved worst pairs show isolated pixels around launcher/beam edges while the actual launcher bodies and upgraded beams are present. Their origin has not been fully traced.
• The original Nashwan probe had the largest mismatch: median 856, worst 1364 physical pixels at frame 40340, VBL 150282. The gray shape below the player is now confirmed as its countdown digit, drawn directly at $6BA4 outside the object list. The new hook captures it; all ten digits match in 168/168 aligned digit regions. Whole-playfield residuals remain, including weapon edges. See countdown trace and fresh recording.

Problem recording: E:/xenon_runs/attachment-matrix-20261004-all/attachment-06-buy1.validation/attachment-06-buy1.x2events. Paired AVIs and worst-comparison.png are beside it. The comparison uses exact VBL tags with the established Original +2 VBL delay and excludes only the eight-row HUD.

Draw audit records identify Level 5 procedures $50FD4 and $50FDA (update $50E00). Every observed audited invocation in these probes captured one draw. Some recordings using these procedures are pixel-identical, so an unfamiliar wrapper alone is not evidence of a missing sprite. Audit overflow and duplicate samples were zero. The Web replay inspector displays these level-tagged records.

All tests cover short early-Level-5 windows. They do not exhaust every mixed loadout, hit-flash state, offscreen pose, terrain interaction or manual Dive activation. Further rendering work should reproduce the concrete residuals above, rather than change autopilot tactics to hide them.