Document architecture checkpoint and restore original task callback order
This commit is contained in:
1 parent
69d0187a21
commit
531883aaac
45 files changed
+2935
-43
No files matched your search
@@ -0,0 +1,278 @@
|
||||
# Camera, audio and UI architecture checkpoint
|
||||
|
||||
Scope: playable baseline `69d0187`, lab → VR04 → lab → outside. Read `prompt.MD`
|
||||
all1281 lines and both AGENTS files. This checkpoint changes no runtime behavior.
|
||||
Original files were read only. Source-byte checks below are static evidence,
|
||||
not original-game runtime comparison. Existing Linux GPU/SDL smoke tests and user
|
||||
Windows reports describe the port, not a recovered original reference recording.
|
||||
|
||||
## Evidence identity and reproduction
|
||||
|
||||
| Module | SHA-256 |
|
||||
| --- | --- |
|
||||
| Neutron.exe | f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8 |
|
||||
| OMT2.dll | 3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943 |
|
||||
|
||||
`python3 tools/binary/checkpoint_camera_audio_ui.py ../Original` verifies25
|
||||
selected instruction sequences and7 constants against those identities and prints
|
||||
mapped physical offsets. `python3 -m unittest discover -s tests -p
|
||||
'test_checkpoint_camera_audio_ui.py' -v` also checks ray-adjustment algebra.
|
||||
Fresh bounded objdump reads corroborate the cached `artifacts/binary/neutron.asm`;
|
||||
RTTI was checked with `tools/binary/rtti_map.py`.
|
||||
|
||||
All EXE code/constant VAs in this report have physical offsets VA−0x400000.
|
||||
Examples and decisive ranges are listed explicitly. **The globals below occupy
|
||||
PE zero-fill and have no physical file offset**; subtracting the image base from
|
||||
their VA does not produce an original-file byte location.
|
||||
|
||||
| Runtime owner/global | VA | Meaning supported by consumers |
|
||||
| --- | --- | --- |
|
||||
| Controlled game-interface pointer | 0x5099E4 | Input ownership; null also suppresses objective clock/draw |
|
||||
| Shared viewport pointer | 0x509A50 | Position+44/+48/+4C; signed angle words+50/+52/+54 |
|
||||
| Current music database | 0x696004 | Separate from current Wave/effects/speech bank |
|
||||
| Current Wave database | 0x696008 | CAM/MCA replace it with authored speech bank; DEFAULT restores effects |
|
||||
| Sound engine | 0x69600C | Channel array+40; virtual24 returns channel count |
|
||||
| Default positional-effect gate | 0x4F8434 | Wrapper4589C0 tests it; cutscenes clear, DEFAULT enables |
|
||||
| Objective time / selector | 0x4F8188 / 0x4F8194 | Separate transient presentation and persistent selection |
|
||||
| Objective44 flags | 0x4F7D00 | Independent per-row visibility/selection state |
|
||||
| Modal active / type | 0x4F8198 / 0x4F8048 | UI continues handling modal while main gameplay is paused |
|
||||
|
||||
## Shared camera state and ownership
|
||||
|
||||
**Recovered fact.** There is a shared viewport, not independent original
|
||||
"gameplay eye" and "cutscene eye" objects selected by renderer priority.
|
||||
CAM/MCA and player callbacks write that same position/orientation. MCA helper
|
||||
431670 (file31670) writes eye+44/+48/+4C at431677/431683/431694, derives angles
|
||||
using imported angle routine48D108 at4316F9, writes words+50/+52 and roll0 at
|
||||
43170D..431717, and mirrors camera globals4F8418..4F842C. CAM formulas are at
|
||||
4161CD..416585 (file161CD..16585), MCA formulas431027..4311C1
|
||||
(file31027..311C1). Their authored transforms are already documented in
|
||||
`../analysis/lab-progression.md` and represented by SceneDirector.UpdateCamera.
|
||||
|
||||
CAM activation4165E2..4166FA (file165E2..166FA) resolves PlayerControlled:
|
||||
`none` preserves, `NULL` clears, a named found actor grants control through game
|
||||
virtual118. Before clear, it calls controlled actor virtual410/438 and rewrites
|
||||
transform state. MCA431502..4315A7 (file31502..315A7) similarly prepares prior
|
||||
controlled actor then clears through game virtual118(NULL). Its PlayerControlled
|
||||
field is completion ownership at4311F0..431228, not an activation grant.
|
||||
Control loss does not prove all physics/actors should stop. Main-loop report owns
|
||||
the enclosing update pass and any per-actor active gates.
|
||||
|
||||
**New recovered DEFAULT handoff.** DEFAULT447CF0 has a Jimmy-already-controlled
|
||||
early branch447D5C..447D9C (file47D5C..47D9C). Even that branch reloads the
|
||||
default effects bank; it skips camera reposition and music restart. Otherwise
|
||||
447E1E..447E27 restores control, then447E2D..447EC3
|
||||
(file47E2D..47EC3) computes actor-local point `(0,500,-500)` using game-interface
|
||||
virtual384, compares distance from current viewport position against float1000
|
||||
at48E5AC (file8E5AC), and writes the point to viewport only when distance is
|
||||
**strictly greater than1000**. At equality the original `fcomp; test ah,41; jne`
|
||||
skips the snap. Non-Jimmy mode-dependent restore targets also exist447DAC..447E1E;
|
||||
the port's unconditional Jimmy restore is only the route subset.
|
||||
|
||||
**Current implementation.** Program selects LabSimulation.CameraEye then replaces
|
||||
it with SceneDirector.CameraEye while a shot exists. `RestoreControl` clears the
|
||||
shot eye; it neither transfers current viewport state into follow state nor
|
||||
performs the source conditional snap. LabSimulation only advances when Jimmy
|
||||
controls input. Calling its eye "always advanced" is inaccurate; it remains a
|
||||
separate stale state during ordinary uncontrolled cutscenes. This is an ownership
|
||||
mismatch, not a reason to add another transition easing heuristic.
|
||||
|
||||
## Follow camera, obstruction and clipping
|
||||
|
||||
**Recovered fact.** Jimmy complete-object vtable4A3BDC (fileA3BDC), slot124 →
|
||||
438BC0 walking, slot128 →439900 airborne, slot16C at4A3D48 (fileA3D48) →
|
||||
43B820 camera ray callback, slot170 →437740 default camera setup. The separate
|
||||
game-interface vtable4A373C (fileA373C) has complete-object displacement+C0;
|
||||
do not apply complete-object offsets directly to an interface pointer.
|
||||
|
||||
| Complete-player field | Source initialization/use |
|
||||
| --- | --- |
|
||||
| +7C8/+7CC/+7D0 | Eye local0,200,−350 at437740..43776D (file37740..3776D) |
|
||||
| +7D8/+7DC/+7E0 | Look local0,80,0 at437752..437774 |
|
||||
| +854/+858/+85C | Axis gains1.6,1,1.6 at43775E..437787 |
|
||||
| +804..+810 | Cached desired eye when special-state branch retains it439658..4396A5 |
|
||||
| +714/+718/+71C | Prior camera position used by follow deltas43971E..439748 |
|
||||
| +828, +830, +84C, +851 | Additional state affects offsets/gains; complete semantic names unresolved |
|
||||
|
||||
4395CF..4398E4 (file395CF..398E4) does not simply follow a fixed local offset.
|
||||
Normal eye height is `eyeY−2*self[84C]`; target height is
|
||||
`lookY+1.9*self[84C]` at439625..4396DA. Special+828/+830 branches use cached
|
||||
eye or flip/scale backward distance by3.7 after threshold1.7. Float64 constants
|
||||
are4AFCE8/4AFCF0/495338 (filesAFCE8/AFCF0/95338). Do not rename84C to ground
|
||||
height or infer its units without tracing writers.
|
||||
|
||||
**New ray contract.** Caller439702..439714 passes look-point by value and
|
||||
desired-eye pointer through complete-object virtual16C. Callee43B820..43B90C
|
||||
(file3B820..3B90C) calls ray predicate47C210 at43B874; on hit reads16-byte hit
|
||||
global5CFC60 and mutates desired eye to
|
||||
`lookPoint−0.75*(lookPoint−hitPoint)`, i.e. `.25*look+.75*hit`. It returns1.5
|
||||
on hit (float4A3138,fileA3138), otherwise1.0. Predicate layer/filter/ordering and
|
||||
its use of actor-query virtual310 still require recovery; this algebra alone
|
||||
does not authorize replacing its ray with the port capsule sweep.
|
||||
|
||||
Normal interpolation4397B1..4397F1 multiplies X/Z delta by axis gain, ray return
|
||||
gain and dt; Y uses `(gainY+0.2)*rayGain*dt`. +851 selects a0.2 branch and
|
||||
+828 selects another branch without these axis multipliers. Position is added
|
||||
to current viewport4397F8..43982D, then look angles derive from prior-position
|
||||
fields and wrap with mask3FFF at439865..4398E4. This order matters and needs an
|
||||
isolated trace before replacing the source adapter.
|
||||
|
||||
**Current approximation.** LabSimulation.DesiredEye uses root+(yaw-rotated
|
||||
0,180,−350), target root+99, fixed gains1.6/1.2/1.6 and modern sphere/capsule
|
||||
obstruction before and after interpolation. 180/99 match only an inferred
|
||||
selected offset state, not the complete field-driven algorithm above.
|
||||
|
||||
**Clipping fact versus policy.** OMT2 layer constructor1004D340
|
||||
(DLL file4D340) defaults near20/far3200/FOV0xAAA. Source initializers override
|
||||
geometry-layer far values: LV1B44F5A5/44F5B1 (files4F5A5/4F5B1)=10000,
|
||||
VR04456C04/456C4A (files56C04/56C4A)=50000, outside45086F
|
||||
(file5086F) sets layer509A3C to28000 while509A30 retains3200. Full35-scene
|
||||
table is `../analysis/camera-clipping.md`. SceneProjection's maximum of two
|
||||
layers is a documented merged-renderer policy; layer masks/clip/fog and dynamic
|
||||
LV4B clip transition are incomplete. Orbit scene-radius far distance only hid
|
||||
the earlier wrong gameplay3200 range. Widescreen aspect is a modern policy.
|
||||
|
||||
## Audio owns cutscene completion, banks and channel lifetime
|
||||
|
||||
RTTI disambiguates the camera callback structures: C3DCutSceneCamera complete
|
||||
vtable498060 (file98060), slotD8 at498138 →4165A0 activation; its **+C8**
|
||||
game-interface vtable497BFC (file97BFC), slot3C4 at497FC0 →415F90 update.
|
||||
Thus update-relative handle+8B4/active+8B8/elapsed+8F0 are complete-object
|
||||
+97C/+980/+9B8 respectively. C3DMultiCutSceneCamera complete vtable4A93C8
|
||||
(fileA93C8), slotD8 at4A94A0 →431280; its+C8 game-interface vtable4A8F64
|
||||
(fileA8F64), slot3C4 at4A9328 →430DA0. MCA update-relative handle+DC0,
|
||||
active+DC4, elapsed+DE0 are complete+E88/+E8C/+EA8. Camera's interface
|
||||
displacement is C8, whereas Jimmy's is C0; conflating them shifts every field.
|
||||
|
||||
**Recovered fact.** CAM415F90 calls base update463090, increments elapsed+8F0
|
||||
at415FB2..415FBC, then polls sound handle+8B4 at415FC2..415FD3
|
||||
(file15FC2..15FD3) with47D890. While sound reports active it updates camera and
|
||||
skip handling. When inactive it stops/releases handle, changes target animation,
|
||||
deactivates and invokes next trigger4160A4..4160E2. MCA uses the same predicate
|
||||
at430DD2 before advancing shot; per-shot elapsed reset43190F. Animation is an
|
||||
effect of activation/completion, not the recovered cutscene clock owner.
|
||||
|
||||
47D890..47D8E6 (file7D890..7D8E6) validates engine, nonnegative index and channel
|
||||
count, reads voice at `engine[40][handle]`, calls voice virtual14 with two outputs,
|
||||
and reports active if the second output is nonzero **or voice byte+30 is nonzero**.
|
||||
Missing engine/index/voice returns false. Follow-up [voice-clock.md](voice-clock.md)
|
||||
resolves both derived vtables: slot14 is inherited software elapsed/duration,
|
||||
and+30 is repeat/loop state. This is not a hardware-playing or audibility query.
|
||||
The ordinary one-shot clock is duration-based, but source integer boundaries,
|
||||
invalid handles, engine clock pause, play failure and stop still need modeling.
|
||||
|
||||
47D7A0..47D849 (file7D7A0..7D849) stops voice virtual0C, optionally releases its
|
||||
resource from selected database via virtual38, clears handle resource table
|
||||
695EC0[handle], and clears global music handle4F6B30 when equal. Parameter0
|
||||
still stops/clears handle association; parameter1 additionally releases database
|
||||
resource. These are source runtime handles, not original Wave identity numbers.
|
||||
|
||||
| Lifecycle | Original transition / offsets | Port boundary |
|
||||
| --- | --- | --- |
|
||||
| Jimmy PostLoad |423642..423656 (file23642..23656) loads SoundEffects.omt into696008; selected music stored complete+A4C, handle+A38 | Per-scene prepared files; selectedMusic tuple held by SceneAudio |
|
||||
| CAM takes audio |416776..4167E1 stops Jimmy music handle with47D7A0(handle,0), unloads selected archive, clears696004 | MusicStopped event disposes stream; tuple retained for restart |
|
||||
| CAM takes Wave bank |4167FD..416830 (file167FD..16830) unloads default bank, clears696008/gate4F8434, loads authored speech bank | Speech opens explicit independent WAV; SFX default gate absent |
|
||||
| MCA takes Wave bank |4315AD..4315F5 (file315AD..315F5) performs analogous bank/gate replacement; does not establish universal music stop | Standalone MCA intentionally does not mute all music |
|
||||
| DEFAULT resumes |447F12..447F45 (file47F12..47F45) reloads selected archive, starts Wave0 and stores new music handle | Restart selected track from start; independent streams |
|
||||
| DEFAULT restores effects |447F4B..447F6F (file47F4B..47F6F) restores volume/bank/gate; early Jimmy-owned branch447D60..447D76 also restores bank/gate | No explicit bank switch; always SoundEffects.omt Effect(id) |
|
||||
| Level teardown/reset | Full global sound reset is not proven by these callbacks alone | SceneAudio.Dispose destroys every per-scene stream; RenderSession survives |
|
||||
|
||||
458980→47D390 is nonpositional wrapper;4589C0→47D640 checks default gate4F8434.
|
||||
Therefore "mute every effect during every speech" would be a false generalization.
|
||||
Recover wrapper call sites before suppressing objective216 or mechanism effects.
|
||||
Original volume, attenuation, spatial pan, voice limits/allocation and stream
|
||||
pause ownership remain incomplete. Source general-bank switching is broader than
|
||||
the narrow fixed default bank in `../analysis/sound-effects.md`.
|
||||
|
||||
**Current implementation.** SceneDirector consumes prepared PCM sample duration,
|
||||
including leftover dt across shots; no SDL voice status participates. SceneAudio
|
||||
uses independent SDL streams for speech/music/one-shots/owner loops. SdlAudio.Pump
|
||||
queues loop data below one source-buffer length; bytes queued are not proof all
|
||||
converted output reached the speaker. Debug SetPaused is a modern menu feature.
|
||||
The lab16-cue SDL dummy smoke validates port stream bookkeeping only. Physical
|
||||
speaker output and native Windows end timing remain separate verification.
|
||||
|
||||
## UI update, modal timing and layout
|
||||
|
||||
**Recovered fact.** UI dispatcher404080 (file4080) calls base473240 first at
|
||||
40408E, normalizes pointer using original1/640 and1/480 at4040B7/4040C5, processes
|
||||
cursor repeat state when mode flag4F8181 or modal4F8198 is active, then invokes
|
||||
UI virtual4E4/4DC at40420B..40421B. Notification timers4F8154/58/5C are separate
|
||||
from objective timer. After virtual4E0 at4043D3, controlled-pointer condition
|
||||
4043D9 advances objective time and invokes virtual4D0; null-control branch
|
||||
40447A..4044BD hides art without advancing. Modal branch4044C2 follows this,
|
||||
so its forced objective time8.7 overrides any earlier increment that UI tick.
|
||||
This is a recovered local ordering, not proof of frame-wide input/UI scheduling.
|
||||
|
||||
Objective407070 (file7070) has .7 entry, stationary until7, exit until8.7; O
|
||||
edge toggles timer0/7, not layout. Positive Select406F50 resets timer even when
|
||||
selection repeats; initialization4018A8 and423EC6 sets20 hidden. Exact timings,
|
||||
sound216 latch, fields, art identities and byte checks are in
|
||||
`../analysis/objective-timing.md`. UI row flags are44 independently selected
|
||||
entries; single selector digit and visible flag set are not interchangeable.
|
||||
|
||||
Practice406F90 (file6F90) guards existing modal, shows chosen art and cursor,
|
||||
then407022..407031 invokes game virtual168(1) and stores type. UI continues to
|
||||
accept selection while gameplay is paused.4044CE excludes type12 from forced
|
||||
objective hide. No404D1E..404D97 hides modal, restores main game and resets
|
||||
objective time0. Yes type0 stages VR04/PHONEBOOTH and departure context;
|
||||
source mode1/2/3 map VR03/02/01. Exact keyboard/pointer strict bounds are in
|
||||
`../analysis/ui.md`; controller navigation/highlight/cursor ownership remain open.
|
||||
|
||||
**Current implementation.** ObjectivePanel correctly separates timer/selector
|
||||
and controlled/modal gates for the implemented objective subset. Program.Key
|
||||
adds Jimmy-owned/inventory/focus/inspection/debug gates; original local clock
|
||||
checks any nonnull controlled entity. Modern focus/orbit/debug gates are not
|
||||
recovered source rules. PracticePrompt implements only modes0..3 and no source
|
||||
highlight/controller state. SceneHud shows only lab objectives1..3, pad/digit and
|
||||
practice art; gadget inventories and layout callbacks406590/406650 are absent.
|
||||
|
||||
Original402CC0/402D70 (files2CC0/2D70) scale horizontal/vertical positions with
|
||||
width/640 and height/480 separately. Current UiViewport deliberately uses uniform
|
||||
minimum scale with centered modal/bottom-right anchors and inverse DPI-aware
|
||||
pointer mapping, following the user's widescreen requirement. This is an
|
||||
intentional modern policy, not a claim that the original had anchored ultrawide
|
||||
layout. F1/F2 debug UI is likewise modern; keep its state out of source save/UI
|
||||
fields. The objective pad extending off reference viewport is authored clipping.
|
||||
|
||||
## Route interaction and reset map
|
||||
|
||||
| Route point | Camera/audio/UI dependencies and ownership |
|
||||
| --- | --- |
|
||||
| Lab NewGame/STARTEXP | Loaded selector does not imply visible pad: timer20. STRT/intro activates CAM/MCA chain, takes shared viewport/control; CAM stops music and replaces effects bank. First CAM bank gate persists through chained MCA until DEFAULT. |
|
||||
| Intro DEFAULT | Restores actor control, conditionally snaps existing viewport only for distance>1000, restarts music if control was not already Jimmy, restores effects bank/gate. UI objective clock resumes with nonnull control; task selector changes remain separate. |
|
||||
| Jetpack pickup/practice | Objective changes reset timer; practice modal pauses main game and forces objective hidden. No unpauses/reopens timer0. Yes stages VR04/PHONEBOOTH plus return context; script-state report owns persistent departure root/strings. |
|
||||
| VR04 | Initial geometry layer far50000; scene-specific camera/speech/music state rebuilt by port. Original full teardown/global reset needs loader recovery; do not infer all fields persist because TSK does. |
|
||||
| RETURN lab | Source return applies STRT/root/one-time trigger suppression; intro should not replay solely because scene rebuilt. Viewport/music/UI reset ordering depends on PostLoad and retained task state, not generic "resume previous audio". Current port constructs fresh SceneAudio, ObjectivePanel and director. |
|
||||
| Carl → outside | CAM/MCA null control suppresses input/objective time, not all actor advancement. DEFAULT/LOAD order owns camera/music restoration vs scene destruction. Outside geometry far28000 is layer-specific, while current combined renderer uses28000 globally. |
|
||||
|
||||
## Coverage, assumptions and next bounded chunks
|
||||
|
||||
| Area | Recovered | Remaining source gap / evidence gate | Current implementation gap |
|
||||
| --- | --- | --- | --- |
|
||||
| Script cameras | Local transforms, elapsed, shared viewport writes, control handoff | Vtable caller phase/target transforms after actor motion; full skip/loader ordering | Separate eye state and duration clock |
|
||||
| Follow | Fields, branches, ray mutation/return gain, viewport/angle writes |47C210 layer masks/nearest-hit semantics;84C writers; cached camera updates | Fixed offsets/gains and capsule clipping |
|
||||
| DEFAULT | Strict>1000 snap, existing viewport retention, effect/music reset | Mode-dependent control targets outside route | Unconditional Jimmy restore and discarded scripted eye |
|
||||
| Projection | Source layer defaults/all35 initial limits | Assignment/masks/fog, dynamic transitions | Merged maximum and orbit policy |
|
||||
| Audio | Handle polling, software duration/repeat, bank/gate ownership, stop/reload | Source duration conversion/allocation/play failures, engine pause | Per-file independent streams, floating-duration/leftover-dt completion |
|
||||
| UI | Local dispatch order/objective/modal gates and resource coords | Mode4F8181/4F8430 semantics, full flags/gadget/highlights/controller | Lab subset, modern input gating and uniform anchors |
|
||||
|
||||
1. C5: trace47C210 filter/caller contract; build shared viewport handoff tests
|
||||
using source snap999.99/1000/1000.01 and ray-hit weighting. Preserve viewport
|
||||
at control return, apply source conditional snap, then follow. Do not transplant
|
||||
gains while leaving its previous-position/angle/collision dependencies guessed.
|
||||
2. C6: voice-clock follow-up resolves virtual14/+30; recover allocation/failure
|
||||
and source duration conversion before modeling the channel clock. Model
|
||||
explicit bank/gate state separately from independent stream transport.
|
||||
Test invalid/missing handle, delayed start, natural end, skip, paused playback,
|
||||
DEFAULT already controlled, and level disposal before switching CAM/MCA clock.
|
||||
3. C8: recover UI mode/pause callback boundaries and44 flags; preserve existing
|
||||
tested timer rules. Add source gadget/layout/controller state only with call
|
||||
evidence. Uniform widescreen/debug policy remains intentional and independently
|
||||
tested. Recover animation end notifications separately from speech end.
|
||||
|
||||
These support the primary `coverage.md` and `implementation-plan.md`; they do not
|
||||
claim all systems faithful or require every level/original GPU capture before a
|
||||
bounded implementation correction. Stale broad binary.md mode1-no-action and
|
||||
universal3200 clipping claims are superseded by movement/clipping reports. Broad
|
||||
"camera recovered"/"audio implemented" labels must retain the boundaries above.
|
||||
Reference in new issue
Block a user