Files
Neutron/docs/analysis/ui.md
T

137 lines
7.6 KiB
Markdown

# Original laboratory objectives and practice modal
Evidence: read-only Neutron.exe disassembly (`artifacts/binary/neutron.asm`),
original `omt/screens.omt`, and `alpha.omt`. EXE VAs below equal file offsets
plus `0x400000` for these sections. Static evidence and decoded original art
are verified; original modal/HUD runtime comparison remains outstanding.
## Recovered screen resources and coordinates
`402687..4026E8` registers slot0=`screens:Canv156` objectivePad,
slot1=120 labobjective0A, slot2=121 labobjective0B, slot3=122 labobjective0C.
Their original pixels say **GET JET PACK.**, **TALK TO CARL.**, and
**FOLLOW CARL OUTSIDE.** respectively. GAM pickup tag `shrinkray` is the
prototype/internal name of the lab jetpack (inventory group0/item3); the art
does not describe it as a shrink-ray weapon.
| Element | Original identity | Native dimensions | Reference top-left |
| --- | --- | --- | --- |
| Objective pad | screens Canv156 | 320x173 | (384,380+offset) |
| Current objective | screens Canv120/121/122 | 256x29 | (384,448+offset) |
| Objective selector digit | alpha Canv83/84/85 | 8x8 | (393,450+offset) |
| PracticeYesNo | screens Canv169 | 207x100 | (210,210) |
`402C40` positions visible flagged objectives at x384,
y=`448 + self[4EC] + visibleRow*15`. `407070` renders the pad at x384,
y=`380+self[4EC]` during its stationary phase and prints selector `%d`
(`4EC794`) at (393,450+offset), font tag SMAL (`534D414C`). `401F9D`
initializes offset=-69; `406590` changes -69 to0, while `406650` changes0 to-69.
These source paths toggle vertical layout and other gadget UI. They are separate
from O, whose recovered timer toggle is documented in objective-timing.md. The pad extends beyond the640x480 reference viewport;
retain clipping rather than repositioning it to fit.
`406F50(index,flag)` only accepts index>0: it clears44 dword flags at4F7D00,
sets selector4F8194, resets animation timer4F8188, then enables the selected
entry. It does not map selector0 to objective1. The source has sliding/timed objective presentation, now implemented by
Game/ObjectivePanel.cs:0.7-second entry, stationary until7 seconds, exit until8.7.
Pad and content have independent visibility. O toggles this timer.
See objective-timing.md for exact source rules and regression evidence.
`402D70/402CC0` convert positions using windowWidth/640 and windowHeight/480;
constants at file8D40C=1/640 and8D408=1/480. The port quads use NDC
`(2*x/640-1,2*y/480-1,0)` with an identity overlay transform. Original bitmap
UV orientation is top-down, retained as(0,0) at top-left.
Gameplay text uses individual `alpha.omt` canvases, not editor
`fontsmall.png`: `4683E0` loads `alpha.omt` (string4F51D8), copies6x64
Canv pointer sets from table4F4ED8, and `468B80` maps uppercase ASCII-32.
SMAL selects set1; table entries for '1'/'2'/'3' are83/84/85. The separate
fontsmall CanvasFont is created in editor initialization46B280..46B3C7 and
must not silently substitute for gameplay digits.
## Practice request, input and dispatch
`402243..402273` binds Canv169 at(210,210). `406F90(type)` guards against
an existing modal (4F8198), shows the matching canvas, enables cursor,
pauses the main game through virtual168, then stores type at4F8048. Type0
uses169, whose pixels explicitly ask **DO YOU WANT TO PRACTICE? YES / NO**.
`46A360/46A380` set/clear keyboard bytes at509838+virtualKey;
46A3A0/46A3B0 track left mouse at509834. Consequently modal code reads
Y=509891, N=509886, Enter=509845. Source404523..404586 defines strict
Yes hit bounds225<x<305,240<y<300; No404BD0..404C40 is315<x<395 with
the same y bounds. Y accepts regardless of pointer; N dismisses. Enter
accepts Yes while hovering its region and otherwise follows No. Mouse
click accepts the corresponding hovered region; no blanket click dismissal.
Controller state paths also exist but remain unmapped. Escape handling is
not established by this modal branch.
Type0 Yes dispatch is `40469E` jump table4=404DA8 ->4046AF. It hides the
modal/highlight, clears4F8198, disables cursor, invokes4063E0 for screen155,
and calls Jimmy virtual168 (`43B5A0`) with:
```
targetLevel = "VR04.gam" (4EC77C)
targetStart = "PHONEBOOTH" (4EC788)
returnLevel = Jimmy+955
returnStart = Jimmy+724
```
The latter field names follow how43B5A0 stages requested/current strings;
the argument addresses and literal targets are certain. Modal1/2/3 dispatch
VR03/VR02/VR01 respectively, so type0 must not be routed toVR01.
Runtime checkpoint42AF00 captures the current level code and a16-byte
actor root into Jimmy+1E48/+1E38 separately. This does not prove the
meaning of the saved TSK StoredVector by itself. Follow-up43B5A0/RETURN/TSK
recovery proves that vector is the separate departure root at+9A8; see
runtime-checkpoint.md for capture/restore and initial-trigger suppression.
No path404D1E hides practice elements, clears4F8198, disables cursor and
unpauses main game virtual168(0); yes continues into the level transition.
## Implementation and verification
- `tools/extractors/ui.py` exports only the8 proven canvases, retaining original
identity, database, offset, source size, whole-input hashes and decoded RGBA
hashes. It validates every requested identity/dimension before writing and
rejects destinations overlapping source directories.
- `Application/SceneHud.cs` bounds manifest/depth/count, exact canvas dimensions,
paths and decoded byte counts; appends screen-space indexed quads to the scene,
preserves world draws/textures, and updates the final merged vertex buffer.
Selector0 produces no invented objective image. Input/modal state belongs to
the caller.
- `python3 tests/GamePort.HudTests/test_ui.py` verifies exact original RGBA,
output roundtrip, missing-resource rejection and input hash preservation.
- `dotnet run --project tests/GamePort.HudTests -- artifacts/prepared/ui/ui.json`
verifies final-buffer writes, original coordinates, digit/objective/modal
visibility, retained implicit world draw, and malformed-resource rejection.
Both targeted commands passed24Oct2026. Integrated headless overlays/VR04 entry
and GTX1070/Xvfb modal pause/N/resume/resize pass with zero validation errors.
The packaged Windows Wine64 modal check also passes with validation disabled;
native Windows/original-game comparison remain outstanding.
## Return-context field confirmation
Follow-up field tracing confirms the meaning of the two staged return arguments:
- Literal4EF524 is `level1b.gam`. Jimmy constructor437656..437684 copies it
to complete-object+955, initializing the current/requested GAM filename.
- Constructor437589..4375B5 initializes+724 from4ECA6C=`none`, not PHONEBOOTH.
- PlayerLoadLevel43B5A0 copies its second argument (requested start tag) to+724
at43B6A7..43B6E0, first argument (requested GAM) to+955 at43B764..43B78C,
third argument (return GAM) to+88C, and fourth argument (return start) to+8F0.
- TSK load460A83..460AE5 reads the saved StartPoint string and copies it to
+724 and+774. The supplied NewGame StartPoint is STARTEXP, so a lab practice
transition after loading NewGame should carry ReturnStart=STARTEXP, rather
than copying NewGame's preexisting ReturnStart=`none`.
-40B70A..40B770 looks up+724 with actor lookup474070 and assigns that actor's
root transform to Jimmy, independently confirming that this buffer is a
start entity tag. Runtime checkpoint42AF00 does not alter it.
Therefore source modal0 Yes preserves current `level1b.gam`/`STARTEXP` as the
return pair for the normal NewGame route, while entering VR04/PHONEBOOTH.
Its separately captured pickup checkpoint root and TSK departure root remain
distinct. RETURN restores the latter after applying the requested STRT yaw and
suppresses that STRT's initial trigger; no new PHONEBOOTH marker is invented.