How it works · write-up
Retained loading-screen text
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:

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

At frame 7425, HD replacement glyphs also remain present:
