dmnet.st Xenon 2

How it works · write-up

Retained loading-screen text

xenondoc/LOADING_TEXT_RENDERING_20261007.MD · 8 KB · updated 2026-10-07

Sources were pulled from origin/xenon2 at 886ee93b56fc73a013ff1eb3352d00af50a01b27 before implementation.

Cause

The loading heading is captured correctly during zoom-in, including its final 16×22 glyphs. The original game then retains those pixels while loading, rather than drawing the heading again. A Sprite Stream frame contains only its new draw commands, so it lost the heading after zoom-in.

There was a second error: the central digit is drawn into the display buffer at $40A, whereas capture always measured its destination against the draw buffer at $406. In the original Level 2 probe this produced Y=306 instead of Y=90. It is a loading-progress countdown, calculated from the remaining and total decompressed byte counts, not a gameplay pickup timer.

The original loader also copies a whole framebuffer. Tracking draws and clears without tracking this copy passed Level 2 but failed Level 3, where the heading was drawn into the other physical buffer before the copy.

Original location Meaning
$7F96 Clear the current physical draw buffer; invalidate its loading text.
$8004 Native 16×22 text draw, also reached when zoom-in finishes.
$8074 Scaled text capture after native destination setup.
$8C46 Live 20-character LOADING LEVEL n field.
$8FA4 Copy setup completed: A1 is the source buffer, A0 the destination.
$9204 Update and draw the loading digit directly into the display buffer.
$9202 Current digit character.
$2924 Loading VBL handler; installed after zoom-in and removed before shrink.
$97FC, $9800 Remaining and total decompressed byte counts.

Implementation

src/drawCommandStream.c keeps one bounded heading and digit cache for each of the two physical framebuffers. Actual glyph draws replace that buffer's cached text, including during shrink. The original clear and screen-copy operations update the corresponding cache. Gameplay and snapshot restoration discard it.

Retained glyphs are submitted before perspective stars, once per captured frame, so stars remain visible in the glyphs' black spaces. The same normal draw entries reach desktop rendering, browser rendering and .x2events; no protocol change or web decoder change is required.

Starting from a checkpoint already inside loading needs one cache reconstruction. It checks the native VBL handler and current text field, then uses the known heading destination and current digit state. There is no framebuffer pixel scan. The previous LoadingTextGlyphIsPresent helper was removed. This follows the state/cache approach used by the intro banner (s_introBannerShown) and title logo.

Steady gameplay has no text replay or pixel inspection. Loading holds at most 20 heading glyphs plus one digit per buffer, with no dynamic allocation. A normal heading contains 13 visible glyphs, so loading adds at most 14 retained quads per displayed frame. The native controller/prediction code is unchanged.

Reproduce and audit

Use the official build wrapper, then validate_campaign.py native-run with a checkpoint before the loading transition. Keep both original and Sprite AVIs. For example, from the repository root:

powershell -NoProfile -ExecutionPolicy Bypass -File xenon_tools/hatari_dev.ps1 build -BuildType Release -BuildDirectory out/build/codex-validate
python xenon_tools/validate_campaign.py native-run loading-text-probe --build-type Release --build-directory out/build/codex-validate --fast-forward --output-root E:/xenon_runs --resume E:/xenon_runs/latest-full-render-compare-20261007-r591-1.validation/checkpoints/f7206-periodic.sav --stop-at-level 2 --frames 650
python xenon_tools/audit_loading_text.py E:/xenon_runs/loading-text-probe.validation/loading-text-probe.x2events --output work/loading-text-probe-audit

The reusable audit saves comparison screenshots and JSON. It checks retained heading/digit entries and their coordinates, plus their removal during gameplay. Loading interrupts temporarily change $406 and restore it in the same VBL; the audit therefore uses the last completed capture per VBL, matching the displayed frame rather than treating the intermediate pointer write as another displayed image.

The original AVI is compared at +2 VBLs, as in the existing renderer comparator. Some digit-update edges differ under that fixed video alignment; the audit checks digit persistence after its first semantic draw and also reports pixel differences. It does not claim every countdown-update instant is pixel-identical. HD artwork is also expected to differ from original artwork.

Baseline evidence

Recording: E:/xenon_runs/latest-full-render-compare-20261007-r591-1.validation/latest-full-render-compare-20261007-r591-1.x2events. The audit detects missing headings in all 652 sampled full-size loading frames. Example frames are 7450 (Level 2), 16189 (Level 3), 28817 (Level 4), 41019 (Level 5) and 51199 (return to Level 1).

Final recorded validation

The official Release Hatari executable and native replay DLL were rebuilt. All seven focused live checks passed: 841 full-size loading frames and 317 subsequent gameplay frames were audited. Both AVIs were recorded, finalized, and the created Hatari instances were closed. These are renderer checks, not another full-campaign gameplay validation. Runtime overhead was not separately benchmarked.

Case Recording Audited loading frames Result
Level 2 loading-text-level2-20261007-r598.x2events 109 Pass
Restore midway through Level 2 loading loading-text-level2-mid-loading-20261007-r598.x2events 81 Pass
Level 3 loading-text-level3-20261007-r598.x2events 131 Pass
Level 4 loading-text-level4-20261007-r598.x2events 167 Pass
Level 5 loading-text-level5-20261007-r598.x2events 115 Pass
Return to Level 1 after final shop loading-text-return-level1-20261007-r598.x2events 114 Pass
Level 2, HD sprites/high FPS, 1280×800 loading-text-level2-hd-20261007-r599.x2events 124 Pass

Each recording folder contains the corresponding -original.avi and -sprite.avi. JSON results and comparison images are under D:/src/hatari/work/loading-text-audit-{case}-r598/, or D:/src/hatari/work/loading-text-audit-level2-hd-r599/ for the HD check; the three shown below are copied into xenondoc/loading-text-audit/. The native-art heading comparisons differ by at most two logical pixels, caused by stars/alignment, rather than missing glyphs. HD comparisons deliberately show differences in the replacement artwork.

At frame 7439, the retained Level 2 heading and progress digit match:

Level 2 original, Sprite Stream and difference mask

At frame 16163, the Level 3 heading survives the loader's framebuffer copy:

Level 3 original, Sprite Stream and difference mask

At frame 7425, HD replacement glyphs also remain present:

HD Level 2 original, Sprite Stream and difference mask