279 lines
20 KiB
Markdown
279 lines
20 KiB
Markdown
# 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.
|