From 531883aaac67df75651d25d405bd8064fff0c5a4 Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Sun, 25 Oct 2026 12:56:17 -0400 Subject: [PATCH] Document architecture checkpoint and restore original task callback order --- AGENTS.md | 8 +- README.md | 10 +- docs/analysis/lab-progression.md | 4 +- docs/checkpoint/README.md | 40 +++ docs/checkpoint/baseline.md | 25 ++ docs/checkpoint/camera-audio-ui.md | 278 ++++++++++++++++++ docs/checkpoint/camera-ray-predicate.md | 211 +++++++++++++ docs/checkpoint/coverage.md | 72 +++++ docs/checkpoint/implementation-plan.md | 55 ++++ docs/checkpoint/input-frame-bridge.md | 135 +++++++++ docs/checkpoint/lab-registry.md | 129 ++++++++ docs/checkpoint/loop-motion.md | 113 +++++++ docs/checkpoint/review.md | 74 +++++ docs/checkpoint/scene-loader.md | 194 ++++++++++++ docs/checkpoint/script-state-route.md | 206 +++++++++++++ docs/checkpoint/voice-clock.md | 61 ++++ docs/compatibility.md | 8 + docs/decisions.md | 12 + docs/progress.md | 25 ++ docs/tasks.md | 20 ++ src/GamePort/Game/SceneDirector.cs | 22 +- src/GamePort/Game/SceneInteractions.cs | 32 +- src/GamePort/Game/TaskStates.cs | 4 + src/GamePort/Program.cs | 2 +- tests/GamePort.DataTests/Program.cs | 6 + tests/GamePort.DirectorTests/Program.cs | 39 +++ tests/GamePort.InteractionTests/Program.cs | 32 +- tests/GamePort.LabRouteTests/Program.cs | 2 +- .../GamePort.UndergroundRouteTests/Program.cs | 2 +- tests/test_checkpoint_camera_audio_ui.py | 32 ++ tests/test_checkpoint_camera_ray.py | 59 ++++ tests/test_checkpoint_input_frame.py | 28 ++ tests/test_checkpoint_lab_registry.py | 26 ++ tests/test_checkpoint_loop_motion.py | 25 ++ tests/test_checkpoint_scene_loader.py | 57 ++++ tests/test_checkpoint_script_state.py | 60 ++++ tests/test_checkpoint_voice_clock.py | 19 ++ tools/binary/checkpoint_camera_audio_ui.py | 106 +++++++ tools/binary/checkpoint_camera_ray.py | 156 ++++++++++ tools/binary/checkpoint_input_frame.py | 104 +++++++ tools/binary/checkpoint_lab_registry.py | 108 +++++++ tools/binary/checkpoint_loop_motion.py | 65 ++++ tools/binary/checkpoint_scene_loader.py | 108 +++++++ tools/binary/checkpoint_script_state.py | 144 +++++++++ tools/binary/checkpoint_voice_clock.py | 60 ++++ 45 files changed, 2935 insertions(+), 43 deletions(-) create mode 100644 docs/checkpoint/README.md create mode 100644 docs/checkpoint/baseline.md create mode 100644 docs/checkpoint/camera-audio-ui.md create mode 100644 docs/checkpoint/camera-ray-predicate.md create mode 100644 docs/checkpoint/coverage.md create mode 100644 docs/checkpoint/implementation-plan.md create mode 100644 docs/checkpoint/input-frame-bridge.md create mode 100644 docs/checkpoint/lab-registry.md create mode 100644 docs/checkpoint/loop-motion.md create mode 100644 docs/checkpoint/review.md create mode 100644 docs/checkpoint/scene-loader.md create mode 100644 docs/checkpoint/script-state-route.md create mode 100644 docs/checkpoint/voice-clock.md create mode 100644 tests/test_checkpoint_camera_audio_ui.py create mode 100644 tests/test_checkpoint_camera_ray.py create mode 100644 tests/test_checkpoint_input_frame.py create mode 100644 tests/test_checkpoint_lab_registry.py create mode 100644 tests/test_checkpoint_loop_motion.py create mode 100644 tests/test_checkpoint_scene_loader.py create mode 100644 tests/test_checkpoint_script_state.py create mode 100644 tests/test_checkpoint_voice_clock.py create mode 100644 tools/binary/checkpoint_camera_audio_ui.py create mode 100644 tools/binary/checkpoint_camera_ray.py create mode 100644 tools/binary/checkpoint_input_frame.py create mode 100644 tools/binary/checkpoint_lab_registry.py create mode 100644 tools/binary/checkpoint_loop_motion.py create mode 100644 tools/binary/checkpoint_scene_loader.py create mode 100644 tools/binary/checkpoint_script_state.py create mode 100644 tools/binary/checkpoint_voice_clock.py diff --git a/AGENTS.md b/AGENTS.md index c611d1b..591e454 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,5 +35,9 @@ other agents' active changes. Keep updates concise, save detailed evidence to di Use bounded endian-aware parsers, portable paths, clear C#, deterministic tests, and explicit unmanaged ownership. Build frequently. Update `docs/progress.md`, `docs/tasks.md`, `docs/decisions.md`, and compatibility evidence before transitions. -Current priority is exact asset recovery and one reconstructed original scene; -read those documents for actual completion status and next actions. +Current mode is evidence-led architecture continuation. The initial checkpoint is +documented in docs/checkpoint/review.md. Pause feature expansion; use the playable +69d0187 baseline as a comparison tool. Read +docs/checkpoint/README.md, coverage.md and implementation-plan.md before gameplay +changes. Only evidence probes or directly evidenced corrections belong in this +checkpoint; distinguish static recovery, port tests and original runtime evidence. diff --git a/README.md b/README.md index 6c3457b..6a2e237 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,15 @@ Local reconstruction of the supplied **Jimmy Neutron: Boy Genius** installation using C#/.NET 10, Silk.NET.Vulkan (Vulkan 1.3), and SDL3. Original files remain -untouched in `../Original`. There are no Git remotes or runtime online services. +untouched in `../Original`. Work is local; no remote operations or runtime online +services are used. + +**Current direction: architecture recovery; feature expansion paused.** The +[checkpoint review](docs/checkpoint/review.md), [coverage map](docs/checkpoint/coverage.md) +and [implementation plan](docs/checkpoint/implementation-plan.md) compare source +owners, update order and lifecycles with the port. Clean69d0187 and its packages +are preserved locally as the playable baseline. Task/objective and Carl callback +ordering are the first verified corrections from this investigation. **Current milestone: original lab story, interactions and jet pack practice flow.** The runtime includes recovered camera/speech triggers, moving props, Carl/Goddard diff --git a/docs/analysis/lab-progression.md b/docs/analysis/lab-progression.md index 0808e29..a137254 100644 --- a/docs/analysis/lab-progression.md +++ b/docs/analysis/lab-progression.md @@ -70,7 +70,9 @@ The follow-up below recovers and implements the actual contact/talk dispatcher and the internally named shrinkray jet pack checkpoint/inventory/practice/gadget effects. General AI sensing, weapon behavior and all special pickups remain incomplete. -LOAD LABTONEIGH GAM0xA43 goes tolevel1.gam/startlevel1, SCENE60/radius200. +LOAD LABTONEIGH GAM0xA43 goes tolevel1.gam/level1, SCENE60/radius200. +The destination start tag is `level1`; the earlier `startlevel1` spelling was a +documentation error. Checkpoint helper re-reads the original GAM field directly. Underground LOAD0x8360 requires scene65, start riverlab. Binary0x457F32..7F5F: none requiredtask bypasses; taskvalue-1 bypasses; otherwise >=RequiredLevel and ExactLevel!=-1 additionally requires equality to that numeric ExactLevel. diff --git a/docs/checkpoint/README.md b/docs/checkpoint/README.md new file mode 100644 index 0000000..05180ab --- /dev/null +++ b/docs/checkpoint/README.md @@ -0,0 +1,40 @@ +# Architecture checkpoint + +Feature expansion is paused. The existing port is a preserved baseline and a tool +for testing interpretations. This checkpoint connects original state ownership, +update order and lifecycle to the lab → VR04 → lab → outside route; it does not +require recovering every level or certify complete gameplay fidelity. + +Start with [baseline](baseline.md), [coverage map](coverage.md), +[loop and motion](loop-motion.md), [script/state route](script-state-route.md), +[camera/audio/UI](camera-audio-ui.md), and [implementation plan](implementation-plan.md). +Core reports and [input/frame bridge](input-frame-bridge.md) have returned to +primary ownership. Follow-ups cover [lab registry](lab-registry.md), +[camera ray](camera-ray-predicate.md), [voice clock](voice-clock.md), and +[scene loader](scene-loader.md). All investigators have returned file ownership. +Primary owns integration/runtime corrections. [Exit review](review.md) records +checkpoint completion, verified changes and the next evidence gates. + +Evidence labels used throughout: + +- **Recovered:** static instructions, serialized original data, or a specifically + named isolated-original probe. Preferred image VAs and PE-mapped file offsets + refer to the hashed supplied binaries, not ASLR runtime addresses. +- **Inference:** an interpretation whose missing callers, ordering or filters are + explicitly listed. It is not promoted to fact because a replay looks plausible. +- **Implementation:** what this port currently does, including modern policies. +- **Verification:** state separately whether a source-byte check, managed test, + port runtime, isolated original component, or full original runtime was tested. + +Earlier analysis documents retain useful evidence but can describe older +implementations. This checkpoint supersedes their architecture/priority summaries; +focused reports remain authoritative for their cited instructions/data. In +particular, movement mode1 reaches the airborne fall-through path, TSK writing is +recovered, and source per-level far planes are recovered; broad older statements +that those are wholly unknown are stale. + +Checkpoint exit requires every requested core system to have an evidence anchor, +owner/lifetime, interaction mapping, baseline comparison, explicit unknowns and a +bounded next action. Completion means enough architectural coverage to execute the +plan, not complete disassembly or original gameplay comparison. Preserve unresolved +questions as gates on individual plan chunks, not a reason to block all work. diff --git a/docs/checkpoint/baseline.md b/docs/checkpoint/baseline.md new file mode 100644 index 0000000..ed41452 --- /dev/null +++ b/docs/checkpoint/baseline.md @@ -0,0 +1,25 @@ +# Preserved playable baseline + +Baseline: `69d0187a2178deab1edff961d5126dad1cce3a05`, clean source tree at checkpoint +entry, local annotated tag `baseline-re-checkpoint-2026-10-25`. Existing Linux and +Windows packages were copied, without hard links, to +`artifacts/re-checkpoint/baseline/{linux-x64,win-x64}`. Their BuildInfo records +identify69d0187 and clean source. These ignored local copies are comparison tools; +subsequent builds must not overwrite them. + +`artifacts/re-checkpoint/original-preservation-start.log` verifies all539 original +files against `docs/original-manifest.json`. Originals were read, never modified or +executed in place. All work remains local. A pre-existing `Gitea` Git remote is +configured; it was not contacted or changed. No fetch/push/remote-service operation +was performed. Older notes saying the repository has no remotes are stale. + +The user has traversed lab → tutorial → lab → outside in their Windows build. +Earlier Linux managed, GPU and SDL tests demonstrate port behavior; package +cross-compilation and Wine checks do not establish native Windows verification. +No usable running-original gameplay capture exists. Static code evidence and +isolated DLL probes must not be reported as original end-to-end verification. + +Modern authorized baseline policies include F1/F2 diagnostics, persistent SDL/Vulkan +presentation across level changes and uniform widescreen UI. They are not claims +about the original. Fixed60Hz simulation, provisional player capsule/feet grounding, +grouped system phases and duration-driven camera completion remain fidelity gaps. diff --git a/docs/checkpoint/camera-audio-ui.md b/docs/checkpoint/camera-audio-ui.md new file mode 100644 index 0000000..4d3c849 --- /dev/null +++ b/docs/checkpoint/camera-audio-ui.md @@ -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. diff --git a/docs/checkpoint/camera-ray-predicate.md b/docs/checkpoint/camera-ray-predicate.md new file mode 100644 index 0000000..d480acc --- /dev/null +++ b/docs/checkpoint/camera-ray-predicate.md @@ -0,0 +1,211 @@ +# C5 gate: source camera obstruction predicate + +This is a bounded static continuation of `camera-audio-ui.md`, against the +unchanged Neutron.exe SHA-256 +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. +Originals were read only; no original instructions were executed. Modern runtime +code is unchanged. Preferred EXE VA → file offset is VA−0x400000 for all code, +vtable and initialized constants below. Zero-fill grid/output globals have no +physical file offset. + +**Decision:** enough source evidence now exists to construct a separate static +camera segment-query adapter. It must preserve wall-grid priority, source cell +and insertion order, one-sided winding and first-hit return. Reusing the existing +nearest-hit support query or swept camera sphere would produce a different +algorithm. Full follow-camera integration still requires camera state continuity, +source angle/previous-eye handling and the remaining input-mode branches. + +## Actual caller arguments and unused actor getter + +Jimmy complete vtable4A3BDC, slot16C at4A3D48 (fileA3D48), resolves43B820. +Its caller439702..439714 (files39702..39714) supplies computed look target by +value and a pointer to computed desired eye. At43B820 entry let stack pointer beS: + +| Entry address | Argument / location | +| --- | --- | +| S+4..S+13 |16-byte input look-target vector | +| S+14 | Desired-eye pointer | +| S−18 | Stack pointer after `sub14; push esi` | +| S−10..S−1 | Local16-byte actor-position getter output | +| S−14 | Local float return gain initialized1.0 | + +Hex numbers in this table are offsets, e.g. S+14 means20 decimal bytes. +Both virtual310 calls43B83F and43B84E (files3B83F/3B84E) write local scratch. +Jimmy interface vtable4A373C slot310 at4A3A4C (fileA3A4C) is472300 +(file71300), which copies interface fields214/218/21C/220 to its output and +returns with `ret4`; it has no callback or mutation side effect. The local +position vector is not copied to the ray arguments. + +After loading end pointer `[esp+2C]` at43B854, caller pushes0 then copies the +desired eye to a16-byte argument. It reserves another16 and uses +`lea edx,[esp+40]` at43B868: this is exactlyS+4, the **incoming look target**, +not the getter output.43B874 calls47C210 with +`(lookPoint, desiredEye, twoSided=false)` and cleans24 hex bytes. The source +therefore has no actor-root ray origin or actor exclusion pointer here. + +On hit43B884..43B8F4 reads shared hitXYZ5CFC60/64/68 and changes the pointed eye +to `lookPoint−.75*(lookPoint−hit)`. It returns1.5; miss returns initial1.0. +This caller-level fact corrects any description of25% movement toward actor root. + +## Query priority: first wall hit, then first general hit + +| Function | File offset | Contract | +| --- | --- | --- | +|47C210..47C279 |7C210..7C279 | Global enable gate; call wall query; immediate return on hit; otherwise all query | +|47C280..47C4A4 |7C280..7C4A4 | Rectangle scan of wall/ceiling static grid509B24 | +|47C4B0..47C6D4 |7C4B0..7C6D4 | Same scan of all-polygon static grid5CFC7C | +|469530..4695A9 |69530..695A9 | Build48-byte segment: start+0, delta+10, end/hit+20 | +|469A10..469B66 |69A10..69B66 | Fetch first three polygon corners, add supplied translation, call triangle kernel | +|469B70..469E26 |69B70..69E26 | Source-winding segment/triangle kernel; recovered earlier for support | + +47C210 passes unchanged start/end and sidedness to both queries; the second is +**not a reverse-direction retry**. Wall call47C23D (file7C23D) returns immediately +47C249..47C24C on success; all-grid fallback is47C26C. Both scan functions reset +shared hit polygon/shape identity695D54/695D58 at entry and rebuild global segment +5CFC40. Camera hit output5CFC60 is that segment's+20 vector. + +Within each scan,469A10 returns a bool and shared hit point. A true branch at +47C44C or47C67C immediately stores current polygon and shape pointers to +695D54/695D58 then returns true. There is **no nearest-distance comparison**. +Thus a farther wall polygon in the first eligible cell can win over a nearer wall +later in that list, or a nearer floor in the second grid. A successful wall pass +prevents the all-grid pass entirely. This is materially different from47C6E0 +used by body support, which retains strictly nearer hits. + +Global enable byte4F69E5 is initialized1 at physical fileF69E5, unlike the +zero-fill grids.47C210/280/4B0 independently test it; zero returns false. No +entity-radius, dynamic actor-pair query, visibility, renderer-layer mask, camera +near/far, or material-alpha test appears in the predicate or triangle-call path. +Those static lists were filtered at registration instead. + +## Grid coordinates, traversal and insertion order + +Float cell scale4D6A04 (fileD6A04) is exactly +`0.0020000000949949026f`, origin49B1FC (file9B1FC) is130.0f. Nominal cell width +is500 world units; use the stored float rather than exact decimal1/500 when +testing source boundaries. For X and Z independently: + +``` +index = int16(truncate_toward_zero(worldComponent * storedScale + 130)) +``` + +47F940 (file7F940) changes x87 control rounding to truncation, converts through +signed64 and returns low32; query comparisons retain low signed16. Multiplication +and addition remain x87 intermediates before conversion. This matters for exact +cell boundaries and extreme coordinates; Python's double order oracle below is +not an original x87 execution probe. Normal route coordinates fit the grid. + +47C2E2..47C386 converts both endpointX/Z values, takes componentwise minima and +maxima, and scans the full inclusive **axis-aligned endpoint-cell rectangle**, +not a DDA path or intersecting-cell distance order. Outer indexX increases; +inner indexZ increases.47C3A4..47C3C6 rejects index<0 or>=260. Cell record stride +is12 bytes; list-pointer address is `gridBase+12*(260*x+z)` with gridBase509B24 +or5CFC7C. Record pointer addresses differ from their structure starts by4 bytes. + +47C3DF..47C3EA fetches cell sentinel then first node. Node layout is next+0, +previous+4, polygon-registration pointer+8. Each polygon registration record +has polygon pointer+0 and shape pointer+4. Traversal follows next until sentinel; +47C44E..47C459 and47C67E..47C689 continue only after miss. A polygon spanning +multiple cells can be tested multiple times; there is no per-query visited set. + +479800..47991B (file79800..7991B) registers into the general grid, rejects +duplicate polygon pointers **within that cell**, and appends new nodes at the +tail.479897..4798A8 sets new.next=sentinel/new.previous=oldTail then links it; +the query therefore visits FIFO registration order, not reversed insertion. +It also appends to the wall grid when **stored polygon normal.Y<0.7f** at +4798B3..4798CF; equality is excluded. Threshold48D974 (file8D974) is the same +float used elsewhere for objective timing, which does not establish shared logic. + +479140 (file79140) iterates the source shape polygon array in48-byte increments +at479473..479482. It calculates each polygon's XZ vertex bounds, converts extrema +with the same scale/origin/truncation, and registers the polygon in every cell of +that inclusive rectangle479336..479400. Centroid/radius data are retained in the +registration record, but this camera scan does not consult them for nearestness. + +Shared scene loader44DBF0 uses shape resource ID/index initialized0 at44DC21, +fetches with477BA0, increments at44DEAF and tests existence through477C10. For +the three route archives shape IDs are ascending; current file enumeration order +also happens to be ascending, but an adapter should use source shape IDs and +polygon array indices explicitly. Port merged render-draw order is not evidence +for source registration order. The source's behavior at a missing intermediate +shape ID should be preserved or separately investigated before generic reuse. + +## Registration filters and route asset coverage + +Shared loader lowercases the first two shape-name characters and skips terrain +InitPhysics for NC prefix:44DD2F/44DD64/44DD67 (files4DD2F/4DD64/4DD67). +The ordinary path calls terrain interface2C at44DD6D →464B00 →479140 at464B18. +This excludes a complete NC shape from **both** grids, without removing its draw +geometry. Details and exact source shape payload offsets are in +`../analysis/water-collision.md`. + +For remaining shapes4791C7..4791E5 first excludes checkpoint materials via +4794C0 then calls game polygon callback4797A0/virtual134. Null material causes +checkpoint filter false at4794E8; retain such polygons. Route game complete +vtables CLevel01BGame4C3CD0, CLevelVR044CE910 and CLevel01Game4C5A80 all have +slot134→475CD0, which returns false. These three scenes add no exclusion through +that hook. Do not generalize to every level callback. + +Fresh decoded data from originals, after NC/checkpoint gates: + +| Archive | Registered polygons | Wall-grid eligible | NC excluded | Checkpoint excluded | +| --- | --- | --- | --- | --- | +|level1b.omt |2851 |2483 |18 |0 | +|VR04.omt |508 |420 |0 |0 | +|level1.omt |5231 |3860 |24 |0 | + +All remaining route polygons have exactly3 corners.469A10 fetches only first +three corners through477F10 (file77F10); registration bounds use all corners. +This distinction is immaterial for these archives, but cannot justify blindly +fan-triangulating larger original polygons for a future source camera query. +477F10 indexes polygon corner data then raw shape vertices+68; it applies no +terrain transform.469A10 adds supplied translation, which these grid queries +pass as identity vector(0,0,0,1). Runtime moving-body collision is separate. + +Route OMT hashes and counts are printed by the new helper; source files remain +untouched. Layer509A30 versus509A3C far masks belong to rendering, not these +camera-obstruction grids. + +## Triangle acceptance and offset84C clarification + +Camera passesfalse sidedness.469B70 normalizes segment direction using the +recovered OMT quick magnitude, accepts source determinant<=−epsilon, barycentric +u/v edges inclusive, t>=0 but **t.4,8s, energy. | Explicit state table with post-collision effect ticking and VR immunity. | S/M/R. Fresh same-pass countdown recovered; retained child lifecycle, sound and expiry→animation open. | Trace retained Jimmy/fire resets and phase end events before scheduler integration. | +| COLL |479D20/47BD80 body response; support and quick magnitude; dynamic boxes; NC-shape registration exclusion. | Source support and box pieces around modern swept24-unit capsule, feet/root grounding and slide. | S/P/M/R. Response/masks/stairs/contact order not fully recovered; source radius60 is not port capsule24. | C4: isolate response and root convention; replace adapter behind route tests. | +| ANIM | Engine morph10002DB0; linear interpolation10002F9A; game logical→OMT sync4624B0. | ASE sample timing, unconditional loop closure, pose/action aliases,1/60 advance. | S/P/M/R. Playback flags, rate, completion callbacks, transition order open. | Recover one-shot/loop/end notifications before more aliases. | +| SCRIPT | Source AI/CAM/MCA dispatch and chains; task45F990 objective406F50 BEFORE records BEFORE per-entity424. | Bounded synchronous director; baseline objective after records/actor batch. | S/M/R. Script callbacks recovered for route; generic class coverage and reentrancy incomplete. | C1: ordered objective notification; C2: per-actor Carl override. | +| CONTROL | Global5099E4 null during valid CAM/MCA; PlayerControlled completion target; DEFAULT447D..447F restores camera/UI/music. | Director raw ownership plus explicit debug effective override; player physics stops when uncontrolled. | S/M/R. Null control is not proof all objects/physics stop; scheduler gap remains. | Map raw ownership transitions against phase gates and deferred LOAD. | +| CAMERA | Shared viewport; strict>1000 DEFAULT snap;43B820 ray correction;47C210 first wall-grid hit then first general-grid hit, FIFO cells; source per-level far planes. | Shot-time interpolation, separate chase eye stale during cutscenes, fixed follow gains and nearest sphere obstruction; merged max far plane. | S/M/R. Static grid predicate/filters now recovered; x87 boundaries, source angle/previous-eye and input branches open. | C5: static source adapter then shared camera handoff/follow; no nearest-hit substitution. | +| AUDIO | CAM416776..E1 stops music; DEFAULT447F12..45 restarts; bank696008 / gate4F8434; handle47D890 polls inherited software duration and repeat+30. | Separate SDL streams, floating-file-duration cutscene completion, independent per-file SFX. | S/M/R (dummy streams). Source duration/allocation/play-failure/bank/attenuation lifecycle incomplete; speakers/native Windows timing not verified. | C6: explicit bank owner and software channel-clock tests; SDL queue-empty is not the source oracle. | +| UI |406F50 selector/timer;4043D9 controlled clock;407070/O edge;404D97 practice resume.44 objective flags distinct from selector. | Timed objective subset, modal practice, modern UiViewport/debug. | S/M/R. Other flags/gadgets/highlights/cursor/energy/layout transitions open; source widescreen not recovered. | Keep modern scale policy separate; recover UI dispatcher/mode gates before expanding. | +| LOAD | CEditor+74C/+74D deferred scene request; selective teardown/reuse;Jimmy/Goddard retention; per-object28→40C. RETURN root+9A8/flags954/9A5, restore423A90, STRT suppress4427F2. | RuntimeCheckpoint carried root/return bool, reconstructed actors/audio, app-owned presentation. | S/M/R. Core loader chain recovered; per-field resets, retained helper/current-game lifetime and fades open.50988A is editor R input, not load reset. | C7: retained-field/route lifecycle trace, then state-container integration; keep modern presentation. | +| SAVE | TSK45FEE0 writer /4603F0 reader; records, arrays, return strings, stored departure root; queued460E70→460EA0. | Original-format round-trip and CLI save, scene snapshots; no full source save UI/load lifecycle. | S/M. Source reader duplicates matching task callback then all-entity420 post-task hook; this is distinct from Jimmy placement PostLoad423A90. Current fresh-director path differs. | C7 after C1/C2; test repeated callbacks before adopting loader behavior. | +| CHECKPOINT | Pickup42AF00 stores+1E38 root/+1E48 level separately from+9A8 RETURN root. | Capture exposed, not used for return; source capture consumers unknown. | S/M. Do not interpret as death/respawn until read consumer found. | Track unresolved consumer; no speculative gameplay. | + +## Interaction and ownership map + +| State / owner | Changes when / consumers | Persists or resets | +|---|---|---| +| Task records4FC5FC, name+0/state+64 |45F990 objective hook → record mutation → matching actor424; queries gate triggers/LOAD/NPC | TSK serialized; carried snapshots in port. Same-value assignments still dispatch. | +| Current controlled entity5099E4 | Input dispatch, Jimmy behavior, UI clock, script/camera handoff | Runtime ownership; not interchangeable with task state or whole-world pause. Port F1 override is separate modern state. | +| Scene actor game interface, body, OMT morph | Physics prior body state → registry update → logical/visual sync; animation on engine path | Level-owned construction/destruction; exact spawned effects order not yet recovered. | +| Objective selector4F8194 / transient timing and flags | Task hook406F50, O and practice modal; UI dispatcher reads control | Selector serialized; timer starts hidden20 and is runtime-only. Port implements one selected objective rather than full flags. | +| Departed root complete+9A8 | Ordinary43B5A0 captures; RETURN preserves; PostLoad consumes pending flag | TSK StoredVector persists; pending+954/+9A5 not serialized. STRT yaw remains authored. | +| Return level/start strings | Practice choice records origin; RETURN LOAD selects them | TSK persists strings independently of root and pickup capture. | +| Pickup checkpoint complete+1E38/+1E48 | Pickup callback42AF00 writes; read consumer not proven | Do not equate with departure root or invent reset/respawn semantics. | +| Music/effects/cutscene voice | CAM takes bank/voice and stops music; DEFAULT restores source defaults | Runtime bank/handle lifetime, not task ownership; current port independently opens WAVs. | +| Viewport/camera target | CAM/MCA target/eye; DEFAULT snap and follow; clip/layer resource settings | Original camera handoff is shared viewport state; baseline chase and scripted cameras diverge. | +| Modern application presentation and debug | RenderSession keeps window/GPU; debug visibility across loads | User-authorized session policy, outside original TSK or gameplay claims. Scene audio/gameplay disposed/recreated. | + +## Assumptions and symptom-level adapters to replace + +1. Fixed60Hz and controller-before-physics currently make tests deterministic; + they are not recovered original scheduling. Preserve arithmetic tests but do + not treat existing travel measurements as the source oracle. +2. Floor snap/visual sole correction and24-unit swept capsule solve visible + penetration/navigation symptoms. They do not recover Jimmy's body/root geometry + or47BD80 response. Keep rendering pivot and physics support investigations separate. +3. Carl activation is applied after a generic actor batch in the baseline; + source virtual callbacks execute per actor in registry order. C2 replaces this + adapter without inventing full NPC sensing. +4. Chase interpolation/sphere clipping and DEFAULT's simple camera reset mask + camera ownership gaps. Per-level far limits are recovered; merged-layer maximum + is a rendering policy pending masks/fog, not complete clipping recovery. +5. File duration is a cutscene completion estimate. The source also uses software + duration, but integer elapsed boundaries, repeat, invalid/stopped channels, + clock pause and effects-bank ownership remain lifecycle inputs. SDL queue-empty + is not a better source oracle. Dummy playback does not verify original timing + or physical speaker output. See `voice-clock.md` for the resolved vtable evidence. +6. Current RETURN root, MCA control target, NC exclusion, air-turn clear and + objective timeout have direct evidence. Retain those rules, but revalidate their + phase/owner when the surrounding scheduler changes; don't discard them as guesses. + +## Limits and unresolved gates + +Route coverage is stronger than later levels, but still lacks original end-to-end +runtime comparison. No feature-expansion work is justified by this map alone. +The source's UI/task/return state boundaries are sufficient for C1/C2 now. Scheduler, +physics, camera, audio and loader chunks each require their specified probe before +changing behavior. See the linked reports for exact offsets and additional questions. diff --git a/docs/checkpoint/implementation-plan.md b/docs/checkpoint/implementation-plan.md new file mode 100644 index 0000000..e5eb94a --- /dev/null +++ b/docs/checkpoint/implementation-plan.md @@ -0,0 +1,55 @@ +# Evidence-based continuation + +Checkpoint exit is architecture coverage, not full-game completion. Preserve +baseline69d0187 and original hashes, finish reports/byte checks, then execute these +chunks in dependency order. Each chunk gets its own evidence, regression result +and local milestone; a failed gate triggers further bounded investigation rather +than invented behavior or new levels/features. + +| Chunk | Concrete change / evidence gate | Verification and completion condition | +|---|---|---| +| C1 |45F990: notify objectives before changing task records; then dispatch actors. Expose explicit pre-assignment boundary. | Byte assertions45FB5B/7F/D9; observers see old task during objective selection and new task during actor notification; repeat/missing tasks still broadcast. Run Data/Interaction/Director/route regressions. | +| C2 | Preserve per-actor virtual task override boundary. Generic activation then Carl override413F30 before advancing to next actor, rather than applying all Carl overrides after all actors. | Confirm base/derived call bytes; check actor notification sees final per-actor state and authored marker; regression task50→60 conversation/control and lab route. Do not add other class overrides without evidence. | +| C3 | Build original registry/construction/input/frame phase oracle for lab. Split pending motion/controller/effect phases only when registration order and engine callback bridge are recovered. | Assert physics before normal object update, next-node timing, transform sync after callbacks. Compare input→impulse→next-physics→ground/pose trace; test pause/control loss/return. Keep cadence as unresolved policy until engine timer evidence. | +| C4 | Recover47BD80 and Jimmy root/body fields. Replace provisional capsule/feet and wall response behind bounded source adapter. Depends on C3 phase semantics. | Isolated original collision probes plus deterministic wall/step/ceiling/floor/dynamic-body cases; no invisible NC terrain; lab/tutorial route and visual root checks. | +| C5 | Recover follow ray47C210 filtering and coefficients, then implement shared viewport handoff/DEFAULT snap and follow43B820. | Source byte/probe predicate, below/equal/above1000 eye-distance boundary (snap strictly above), obstruction hit adjustment, controlled/scripted/return camera continuity, per-level projection. Port GPU checks remain separate from original visual comparison. | +| C6 | Recover source allocation/failure and sound+44 duration conversion. Source slot14 uses software duration milliseconds and repeat+30, not hardware status. Model that channel state plus current SFX bank/default gate, then connect CAM/MCA completion. | Strict elapsed>duration boundary, repeat/stop/invalid handle/clock pause; bank unload/reload/default/scene disposal. SDL dummy tests validate transport only; queue-empty is not source timing. Physical/native Windows output remains separate. | +| C7 | Queued TSK load460E70→460EA0→4603F0: repeated task424 and all-entity420 post-task hooks. Ordinary scene placement separately uses46E61A→Jimmy40C423610. Recover enclosing loader, RETURN flags/root/STRT and acquired-reset gate50988A. | C1/C2 first. Trace source duplicate-callback effect before adopting; original12-save byte round-trip; fresh load vs RETURN vs practice No/Yes; persistent arrays/score/energy/strings vs reset timers/handles/actors. | +| C8 | Morph playback flags/rate/end events and UI dispatcher mode/layout gates. | Original clip/end-state probes; action interruption/landing/cutscene restoration; objective/practice controls. Preserve modern widescreen/debug policy and test pointer anchors separately. | + +Implementation expansion into later levels, gadgets/combat, menus and full save UI +resumes only after these core contracts support it. Later-level investigation is +allowed where it resolves a core-system question, without waiting for every level. + +## Execution ledger + +- Entry: baseline69d0187 preserved;539 original hashes verified. Dedicated + investigators assigned independent loop/motion, script/state and camera/audio/UI + files. Main loop findings integrated by primary after investigator usage limit. +- C1: implemented pre-assignment objective boundary. Data/Interaction/Director, + input-only lab route and RETURN regressions pass. Source45FB5B/7F/D9 checked + independently and retained in the script/state helper. No scheduler changes. +- C2: captured SCENE before generic activation, moved LV1B Carl override into the + same per-actor director callback, and removed the interactions-layer batch fix. + Original413F3D/413F4E/414068..414118 independently checked. Director callback + observers now see the final derived state before later actors. Director, + Interaction and input-only lab route regressions pass; broader checks pending. +- C3 investigation: input/frame bridge and fresh lab partial construction order + recovered and byte-checked. Fresh game input→Jimmy controller→fire runs after + global physics. Retained registry/lifecycle remains the integration gate; no + speculative global reorder applied. +- C6 investigation: `voice-clock.md` resolves derived slot14 to inherited software + elapsed/duration and+30 to repeat. Replaced the proposed hardware/SDL-playing + interpretation before changing runtime. Original bytes and one new regression pass. +- C5 investigation: `camera-ray-predicate.md` recovers static grid registration, + wall priority, FIFO first-hit and source kernel, with four order/data regressions. + A static adapter is now justified; complete camera handoff still needs its state. +- C7 investigation: `scene-loader.md` closes app deferred request→teardown→GAM→ + per-object initialization/PostLoad. Jimmy/Goddard retention/reuse is proven; + per-field reset/old-game/helper lifetime remains a bounded next trace. Editor R + reset distinguished from ordinary load. Consistency review leaves old-game + removal/eligibility explicit rather than treating current pointer overwrite as + deletion. Five evidence regressions pass. This is the next C3/C7 integration gate. +- Exit review: core architecture checkpoint documented in `review.md`; feature + expansion remains paused. C1/C2 full integration passes; final follow-up Python + discovery and original hashes recorded under artifacts/re-checkpoint/. diff --git a/docs/checkpoint/input-frame-bridge.md b/docs/checkpoint/input-frame-bridge.md new file mode 100644 index 0000000..78dad28 --- /dev/null +++ b/docs/checkpoint/input-frame-bridge.md @@ -0,0 +1,135 @@ +# Input dispatch belongs to the viewport game-object pass + +Static recovery, 2026-10-25. This follow-up resolves the input/world-logic bridge +left open in [loop-motion.md](loop-motion.md). Originals were read, never executed +or changed. SHA256: Neutron.exe +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`; +OMT2.dll `3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`. +The helper maps original bytes through PE sections and verifies30 decisive +anchors, direct calls and vtable entries. File offsets below are hexadecimal. + +## Recovered dispatch bridge + +The level game receives input dispatch during the same viewport callback that +integrates physics. It is **not** called by the engine world's OMT logic update. +There are two distinct update interfaces, with different ownership and clocks. + +| Step | Module VA / file offset | Evidence | +|---|---|---| +| Viewport first integrates physics | EXE47E554 /7E554 →479BC0 | Direct call before game-object pass | +| Viewport updates registry | EXE47E582 /7E582 →473740 | Registry50999C, node+8 payload, slot10 call at473758 /73758 | +| Lab game interface enters normal update | EXE4C387C /C387C =470280;4C3C30 /C3C30 =44DF80 | CLevel01BGame interface vtable4C386C: slot10 wrapper; slot3C4 actual callback | +| Base game has identical dispatch | EXE4C2C94 /C2C94 =470280;4C3048 /C3048 =44DF80 | CJimmyGame interface vtable4C2C84 | +| Wrapper supplies frame argument | EXE47028E /7028E;4702C5 /702C5 | Stores dt at interface+294; calls slot3C4 unless supervisor+8C selects3C8 | +| Game updates timer/event records first | EXE44DF89 /4DF89 →45F510 | Direct call before input;45F5BF..D3 advances record float+10 by dt*owner+8 | +| Game dispatches input | EXE44DF94 /4DF94 →475A70 | Same dt argument propagated | +| Dispatcher obtains controlled object | EXE475A9C /75A9C;475AA9 /75AA9 | Global5099E4 null skips input; nonnull calls its interface slot3CC | +| Jimmy receives input | EXE4A3B08 /A3B08 =426030;426084 /26084 →438A60 | Jimmy vtable4A373C slot3CC; guards precede base movement input | +| Later logical objects update | EXE4A3B00 /A3B00 =424600 | Jimmy slot3C4 eventually calls437940 at424C34 /24C34 | +| Entire registry synchronizes transforms | EXE47E587 /7E587 →473770 | Separate traversal after all ordinary callbacks | +| Base viewport draws | EXE47E6DF /7E6DF imports48D304 | Named import OMediaViewPort::render_viewport | + +**Pointer coordinates:** CJimmyGame and CLevel01BGame game-interface pointers +are **complete+8C**, whereas C3DJimmy is **complete+C0**. RTTI locators +EXE4E0768 /E0768 (base game) and4E08F0 /E08F0 (lab game) hold displacement8C. +Instruction475A8A /75A8A explicitly reads the complete vptr from interface-8C +and475A90 forms that complete pointer. Do not apply Jimmy's-C0 conversion here. +For the game, interface+294 is complete+320; for Jimmy it is complete+354. + +The registry constructor appends to the tail, so input relative to Jimmy's +ordinary update depends on insertion order. The recovered guarantee is: + +```text +physics of registered bodies + -> game-object registry traversal in insertion order + game object: event timers -> controlled object's input callback + Jimmy object: base/rotation -> movement/jump/jetpack controller + other objects/effects in their actual registered positions + -> whole-registry logical-to-visual synchronization -> draw +``` + +Game-before-Jimmy ordering for an actual loaded lab still requires a bounded +construction trace, including constructor-created shadow/fire objects. The +diagram deliberately does not assert that relative order. Even without it, +Jimmy's current controller cannot change the physics pass that already ran. +Queued jump impulses are consumed by a later physics invocation. A separate +class-specific collision query/update during an object callback must not be +mistaken for replaying the earlier global physics pass. + +## Engine OMT logic is separate, and runs before render broadcast + +DLL100215C0 /215C0 sends logic message-604 at100215D4 /215D4 when global +1013D6DC is zero, then sends render message-605 at100215E8 /215E8, passing +that global as the render-message argument. These are synchronous virtual +broadcaster calls. World listener100F9C40 /F9C40 converts its listener pointer +by-30 and calls complete world slot30, update_logic100F9B10 /F9B10. +World update_elements100F9C80 /F9C80 invokes complete OMT element slot3C, +parent before descendants, preserving its pre-callback next-node pointer. + +For CLevel01BGame, complete OMT vtable4C3CD0 slot3C at4C3D0C /C3D0C is +4747A0; this forwards through IAT48D230 at4747A5 /747A5 to +OMediaElement::update_logic, DLL100EFF20 /EFF20, a `ret4` no-op. Thus this +path does not dispatch44DF80 or player input. For Jimmy, complete vtable4A3BDC +slot3C at4A3C18 /A3C18 is462260; it forwards at462265 /62265 through48D244 +to OMedia3DMorphAnim::update_logic10002DB0 /2DB0. That calls +OMediaAnim::update_logic10020CF0 /20CF0 with the morph subobject at complete+90. +Eligible animation updates therefore run through OMT logic before the ensuing +render message's game callbacks select/change poses. Logic can be skipped by the +periodical flag, world pause or timer gate. Exact displayed first-frame and +completion effects still require analysis of animation flags and listener order. + +The render message reaches engine listener1006BCB0 /6BCB0, which converts its +listener by-10 and calls engine slot14 at1006BCCA /6BCCA. The full renderer +backend/surface/viewport route remains a separately bounded follow-up; the +viewport's own physics→registry→draw order is already established independently. + +## Timer units, defaults and limits + +| Owner/field | Source VA / file offset | Recovered value or transition | +|---|---|---| +| World pause count+44 | DLL100F9B18 /F9B18 | Nonzero returns without world logic | +| Timer begins world+48 | DLL100F9B26 /F9B26 | Elapsed obtained by100FA0A0 /FA0A0 unless timer byte+0D is set | +| Timer mode world+58 | DLL100F989D /F989D | Constructor writes1 | +| Timer period world+5C | DLL100F98A0 /F98A0 | Constructor writes40 | +| Maximum elapsed world+60 | DLL100F98A7 /F98A7 | Constructor writes500;100F9B42..47 clamps larger elapsed if max nonzero | +| Minimum elapsed world+64 | DLL100F98AE /F98AE | Constructor writes1;100F9B51..5B skips below this if timer is running | +| Engine clock | DLL100F8D18 /F8D18 | GetTickCount import1011410C, minus global epoch1017A308 in ordinary path; optional override/pause branches exist | +| Engine elapsed passed to elements | DLL100F9BCC..E6 /F9BCC | Unsigned integer elapsed converted to float, no seconds division before world slot3C traversal | +| Viewport game clock | EXE47E490 /7E490;47E502 /7E502 | QPC delta/frequency float seconds stored696030; accepted only0 Jimmy interface+C0 enters registry + -> owned jetpack fire interface+C0 + -> other Jimmy constructor helpers + -> owned Jimmy shadow interface+C8 + -> additional constructor helpers + -> remaining serialized lab entities in file order, with their own helpers + -> postload callbacks in registry order + Jimmy creates absent Goddard interface+C0 + -> Goddard shadow interface+C8, then other Goddard helpers +``` + +This is a **partial order**, not adjacent nodes or absolute list indices. The +helper intentionally does not manufacture a full registry from the GAM alone: +constructor-owned objects are not serialized entity records. Geometry/other +postload objects can also intervene. The ordering does establish that normal +fresh-lab input from the game object runs before Jimmy's controller, Jimmy runs +before his fire effect, and Goddard follows both in the game callback pass. + +| Boundary | Calls / source instructions (VA; file offset follows VA-400000) | +|---|---| +| Header first | Loader46E319..32B reads initial FourCC through imported stream operator48D3E0;46E335 /6E335 calls factory459CB0 before entity count read46E36A /6E36A | +| LV1B class allocation | Factory45D3FD /5D3FD →44F300, allocating5C0 bytes; constructor44F3B8 /4F3B8 sets LV1B | +| Game base chain |44F358 →44D2B0;44D306 →4745A0;474602 forms complete+8C;47460A →4586F0;458712 →46FBE0 | +| Common registry insert |46FF4A..7F /6FF4A: global50999C sentinel; alloc12; node.next=sentinel;node.prev=oldtail;sentinel.prev=node;oldtail.next=node;node+8=interface | +| First entity | Lab GAM has129 records; first is3JIM/JIM1 at file000008;46E37F reads its code and fresh branch46E3B9 calls factory459CB0 | +| Jimmy factory/base chain |45B1E2 →422160;4221B1 →437280;4372DA →40D110;40D162 →462040;4620A2 forms complete+C0;4620AA →4586F0 →46FBE0 | +| Fire during player base construction |4374DF →421D80;421DD2 →40D110, so it registers after Jimmy;4374EF stores fire complete pointer at Jimmy complete+7F8 | +| Jimmy shadow |42250C →43F640;43F692 →4352F0;435341 →463F10;463F6C forms complete+C8;463F74 →4586F0 →46FBE0;42251C stores shadow at Jimmy complete+A2C | +| Remaining GAM records |46E3FD invokes stream extraction48D190 on the current interface;46E426 reads next code;fresh branch46E49A calls factory;46E4BA loops to46E3D1 | +| Postload after records |46E4FF invokes supervisor slot128. Vtable4D5EA0 entry4D5FC8 /D5FC8 resolves46E570, which traverses registry and invokes interface40C at46E61A | +| Jimmy postload |Vtable4A373C entry4A3B48 /A3B48 resolves423610. This callback contains the Goddard construction below | +| Goddard is runtime-owned |Lab GAM contains zero3GOD records.423C6A..72 tests Jimmy interface+95C; if absent,423C98 →41C810;423CAE stores Goddard complete pointer at interface+95C (complete+A1C) | +| Goddard registers before his shadow |41C861 →407A40;407A92 →40D110 →462040 →4586F0;41C95F →43F640 builds his shadow afterward;41C96F stores shadow complete pointer at Goddard complete+994 | + +The postload traversal reads next after the callback at46E668, so a newly +tail-appended Goddard is eligible to receive postload later in that same traversal. +This follows from the linked-list operations; it is not an original runtime +capture. Allocation failure and callbacks that remove/reorder nodes need separate +handling and are not silently interpreted as the normal successful load. + +## Fresh input/controller/effect frame consequence + +[input-frame-bridge.md](input-frame-bridge.md) establishes that viewport47E4F0 +first calls global physics479BC0, then registry updater473740, then transform +synchronization473770, then base draw. Combining that with the fresh partial +order gives the bounded interaction: + +1. Physics consumes existing Jimmy velocity/acceleration/queued impulse. +2. Game44DF80 advances timer records and dispatches input475A70 to current5099E4. +3. Jimmy424600 updates base/rotation/controller437940, which may queue a jump or + start/stop/change a burst. +4. Owned fire421FB0 runs later, observes that controller state and decrements + its timer/energy according to its already recovered rules. +5. Goddard's ordinary game update occurs later in the same registry pass. +6. All surviving logical actor transforms are synchronized before rendering. + +Thus a fresh controller-created impulse waits until a later global physics pass, +while a newly assigned positive fire timer can be decremented by its effect +callback in the same game-object pass. This resolves the previous open +Jimmy-versus-fire ordering without inventing a nominal60Hz source cadence. +The baseline port's combined controller→physics→effect call differs at the first +boundary. Splitting pending body inputs is directly supported for this fresh-load +case; actual gameplay comparison remains required for latency/apex fidelity. + +## Reuse and transition ordering remain a separate gate + +Source explicitly supports existing-object reuse: + +- Jimmy constructor42275A writes complete+C9=1, or interface+09. Goddard + constructor41C9C0 writes the equivalent flag. Common constructor46FFAE starts + interface+09 at0. This is an observed reuse flag; it alone does not prove + lifetime across any particular level transition. +- Supervisor vtable4D5EA0 slot11C at4D5FBC /D5FBC resolves46E6A0. It walks + registry50999C and requires matching interface+404 class code **and** nonzero + interface+09 at46E6B9..C6. Slot110 at4D5FB0 /D5FB0 resolves46E6E0, returning + the first matching existing object without moving/re-appending its node. +- Loader46E38B /6E38B and46E45A /6E45A use this predicate before choosing the + fresh factory branch. Reusing Jimmy therefore does not repeat his constructor + or append his fire/shadow again. Jimmy postload separately reuses his existing + Goddard pointer if present. + +**Follow-up for lab→tutorial→lab:** `scene-loader.md` now proves Jimmy/Goddard's +zero teardown predicate and positive reuse flag together. Their retention/reuse +contract is recovered, but the complete retained helper set, field resets and +old current-game removal/eligibility remain open. Deferred transition46DFF0 queries each object's +slot200, calls lifecycle slots20/34, marks some interface+06 for deletion and +calls473710.473710 deletes flagged nodes through interface slot0 and restarts +the list scan. A complete retained-set proof needs each relevant slot200 getter +and flag write, plus each object's lifecycle callbacks and owned-child cleanup. +Slot200 for Jimmy/Goddard is4719B0, reading interface+139; **it is not** the +reuse flag+09. Conflating those two fields would fabricate persistent ordering. +Do not assume the fresh game-before-Jimmy relation after a transition: the new +game appends later, while old-game callback eligibility needs its own proof. + +## Verification and bounded next implementation + +`python3 tools/binary/checkpoint_lab_registry.py` verifies source hashes, +12 decisive instruction ranges,23 direct calls and4 virtual entries, then parses +the original lab GAM for its header/count/first record and absent3GOD record. +`python3 -m unittest discover -s tests -p test_checkpoint_lab_registry.py -v` +passes the original-data regression. This is static evidence; no port or original +gameplay runtime verification was performed for this follow-up. + +Baseline69d0187 groups simulation, mechanisms, patrols, director and effects by +subsystem. A C3 scheduler can now model the fresh lab's proven input→Jimmy→fire +ordering after global physics, with logical-to-visual synchronization last. +Keep initial source-order replay separate from current playable policy while +covering queued jump, same-pass burst countdown, landing and control transfer. +For the tutorial return, first trace cleanup46DFF0→lifecycle20/34→473710 and +prove the surviving node sequence; use that sequence when serializing/rebuilding +the scheduler. Other Jimmy/Goddard helper identities, construction-time nested +spawns and later runtime appends still need an explicit registry trace before +claiming the complete list or all-level ordering is recovered. diff --git a/docs/checkpoint/loop-motion.md b/docs/checkpoint/loop-motion.md new file mode 100644 index 0000000..0a5f290 --- /dev/null +++ b/docs/checkpoint/loop-motion.md @@ -0,0 +1,113 @@ +# Main loop, input, motion and animation + +Static recovery from supplied Neutron.exe (SHA256 +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`) and +OMT2.dll (`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`). +Investigated independently, integrated and byte-checked by primary. No original +whole-game runtime comparison. `checkpoint_loop_motion.py` reports PE-mapped +file offsets and verifies decisive calls/vtable anchors. For the EXE anchors below, +file offset is VA minus400000; do not apply that shortcut to DLL addresses. + +## Recovered loop and ownership + +| Boundary / owner | Original evidence | Interaction | +|---|---|---| +| Application pump | EXE4802F2 CRT →4789B0 WinMain →46A4A0 bootstrap; DLL100218A0 application start →10060720 devote_time | Engine periodicals own dispatch; not an established60Hz game loop | +| Engine animation periodical | DLL100215C0 emits -604 logic and -605 animation/render; world100F9B10 →100F9C80, world+48 timer and pause/min/max periods | Engine logic and game render callback are separate timing paths; exact interleaving needs trace | +| Game frame entry | EXE47E374 (file7E374) assigns viewport vtable4D74C4; slot+B8 at4D757C points to47E4F0 | This is a viewport render override, not an ordinary world logic tick | +| Frame time | 47E4FC virtual+D4;47E502 stores float seconds696030; guards47E508..52A accept0.4,8s burst and.5/s energy drain + are narrowly recovered. Registry insertion order of Jimmy/effect must be traced + before deciding same-frame vs next-frame effect expiry and impulse application. +- Source support/ray/magnitude and dynamic box broadphase have byte/DLL evidence. + Static response47BD80, stairs, all body masks and contact side effects remain + incomplete. NC shape exclusion is a recovered registration gate, not a water fix. + +## Animation + +There is a separate OMT logic/morph path: EXE462260 forwards its argument through +IAT48D244 to OMT morph update10002DB0. Common logical/visual transforms are copied +by the later registry sync. Morph interpolation is recovered at DLL10002F9A; +original mode2 probes for tested standing/jump clips return zero dynamic-point +offsets. These probes do not establish full animation scheduling or collision pose. + +Port `MorphAnimation` samples extracted ASE timing with linear interpolation, +loops the final sample to first unconditionally, and rejects irregular samples. +`PreviewAnimationLibrary` chooses from pose/action aliases; Program resets poseTime +on clip change and adds1/60 every port tick. Actor visuals likewise run after the +grouped gameplay passes. Playback-end callbacks, one-shot vs looping flags, +class-specific speed, state transitions and interrupt rules remain unresolved. + +## Baseline comparison and verification + +Baseline69d0187 runs `LabSimulation.Step` controller → physics → jetpack effect → +camera, then contacts/mechanisms → patrols → director → objective timer → animation. +This contradicts the recovered physics-before-object-update contract and replaces +construction-order callbacks with subsystem groups. A global reorder now would +invent ordering for spawned effects, scripts and NPCs. First build a lab registry +and phase trace and assert source contracts; only then split simulation phases. + +The helper and Python regression verify exact original bytes/call order; managed +tests verify port arithmetic and deterministic route outcomes. Neither proves source +cadence, input latency or original end-to-end gameplay. Keep both traces separate. + +## Explicit unresolved questions / next work + +1. Input bridge is resolved: registry3C4→44DF80 after physics. Exact event-pump, + pause/focus/invalid-dt/multiple-viewport behavior remains open. Engine world + timer is milliseconds, default mode1/min1/max500, distinct from QPC game seconds; + see the follow-up before interpreting the40ms period or choosing a cadence. +2. Capture lab construction registry including Goddard, jetpack effect, transient + objects and deletions; identify462A20/4693A0/477DB0 dependencies precisely. +3. Recover47BD80 response, Jimmy body/root/capsule relationship and source contact + ordering before replacing provisional feet grounding/sweep-slide collision. +4. Trace morph flags/end events and class animation selection, including cutscene + exit, jump→fall→land and jetpack state/energy transitions. +5. Probe isolated source components where possible; full original timing remains + unverified until a usable original runtime exists. Do not use nominal60Hz as fact. diff --git a/docs/checkpoint/review.md b/docs/checkpoint/review.md new file mode 100644 index 0000000..b36596b --- /dev/null +++ b/docs/checkpoint/review.md @@ -0,0 +1,74 @@ +# Checkpoint exit and implementation continuation + +The initial architecture checkpoint is complete: all requested core systems have +source anchors, state owners/lifetimes, route interactions, baseline comparison, +explicit unknowns and bounded implementation actions. Feature expansion remains +paused. This is an architecture milestone, not complete original-game fidelity. + +## Exit criteria and evidence + +| Criterion | Durable result | +|---|---| +| Entire specification/current findings/code reviewed | Full1281-line prompt.MD, both AGENTS files, runtime and focused prior findings reviewed; stale architecture claims reconciled through checkpoint index | +| Preserve playable port and originals | Clean69d0187 local baseline tag and independent Linux/Windows package copies;539 original hashes unchanged at entry and final verification | +| Main loop/input/motion/jump/jetpack/collision/animation | loop-motion.md, input-frame-bridge.md, lab-registry.md; source frame order, two clocks, pointer interfaces, controller/effect ownership, pending collision/morph gaps | +| Scripts/tasks/cutscene/control/progression | script-state-route.md; synchronous objective→records→per-actor callbacks, raw control ownership and route-specific script/task transitions | +| Camera/clipping/audio/UI | camera-audio-ui.md, camera-ray-predicate.md, voice-clock.md; shared viewport, strict snap, first-hit grid order, software audio clock/bank lifecycle, modal/objective timers and modern layout policy | +| Level transitions/persistence/checkpoints/save-load | scene-loader.md and script-state-route.md; deferred ordinary load vs TSK load, selective retention/reuse, placement vs post-task callbacks, distinct pickup capture/RETURN root | +| First route case study | lab STARTEXP/intro→explanation35→pickup50/practice→VR04→RETURN lab→Carl60/dialogue→level1.gam/level1; state/owner/reset boundaries recorded | +| Coverage/assumption audit and concrete plan | coverage.md and implementation-plan.md; source facts, inference, port behavior and verification separated; explicit per-chunk gates rather than waiting for every level | + +Three independent investigators used exclusive files; primary reviewed decisive +bytes and integrated reports. All ownership has returned. No new levels, gadgets, +combat or gameplay features were added. No originals were modified/executed in +place. Existing remote configuration was left unused; work stayed local. + +## Implemented and verified chunks + +**C1:** `TaskStates.Assigning` selects objectives before records change. Entity +callbacks still follow mutation, including repeated and missing-name assignments. +Tests assert old-state observation at objective notification and new-state +observation afterward. This corrects original45FB5B/45FB7F/45FBD9 ordering. + +**C2:** Carl's LV1B override now belongs to his director task callback: capture +SCENE, apply generic activation, then marker/state/visibility override before the +next actor. Removed the interactions-layer post-batch fix and redundant level-code +argument. Tests cover callback observation, source activation boundaries and +existing lab/Carl/RETURN routes. Other class overrides remain unported. + +`artifacts/re-checkpoint/integration.log`: full `scripts/test.sh` passed, including +49 Python checks at its start, all managed groups, GPU story/practice/return/Carl/ +objective/jetpack/animation replays, SDL dummy audio and539 original hashes. +All GPU runs report zero Vulkan validation errors. Additional follow-up byte tests +were added afterward; final Python discovery passes62 tests, recorded separately +in `artifacts/re-checkpoint/python-final.log`. Build succeeds without warnings. +These are port/static checks; no new native Windows runtime or original whole-game +runtime verification is claimed. Physical audio and original cadence remain open. + +## Plan continuation and exact next gates + +C3 investigation recovered fresh game input→Jimmy→fire order after physics. C5 +recovered source static obstruction, C6 corrected the proposed audio status model, +and C7 recovered the ordinary loader. These are executed investigation chunks, +not implemented scheduler/camera/audio/loader replacements. + +1. Resolve **old level-game registry removal/eligibility**, since constructor + overwrite of509948 is not destruction and its initialization can set the + teardown predicate0. Trace retained Jimmy/fire/shadow/Goddard field resets + through property read and per-object28/40C. Then construct the route's callback + trace and split pending physics/controller/effect/sync phases. Do not impose + fresh insertion order on retained objects. +2. Independently implement/test the static camera query using source shape/polygon + IDs, registration filters, sparse cells and FIFO wall-first reduction. Then + integrate shared viewport handoff and follow state, preserving strict>1000 snap. + Modern nearest-sphere clipping cannot stand in for that source algorithm. +3. Recover sound duration conversion and allocation/play-failure cases, model + software channel duration/repeat/stop/clock pause plus bank ownership, then + change CAM/MCA completion. SDL queued bytes are transport state, not source time. +4. Continue collision response/root, morph end events and UI mode/layout recovery + under the remaining plan gates. Original runtime comparison is still required + before claiming source fidelity, but does not block directly evidenced chunks. + +Use implementation-plan.md as the execution ledger. Continue locally and +autonomously; user confirmation is not a gate for the authorized investigations +or directly evidenced corrections. diff --git a/docs/checkpoint/scene-loader.md b/docs/checkpoint/scene-loader.md new file mode 100644 index 0000000..650295d --- /dev/null +++ b/docs/checkpoint/scene-loader.md @@ -0,0 +1,194 @@ +# Ordinary scene loader and editor reset boundary + +Read-only C7 follow-up, 2026-10-25. Original `Neutron.exe` SHA-256 +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. +Every VA in this report is in that module at preferred base400000. The inspected +sites map to file offset **VA−400000**; `checkpoint_scene_loader.py` independently +maps PE sections and emits each VA/raw offset/bytes/vtable dependency. Static +facts do not constitute original runtime verification. No originals were executed +or modified; modern gameplay was not changed for this investigation. + +## Main result + +The ordinary scene request is owned by the long-lived **CEditor** application +object at global509980, not by the current level game object509948 or the queued +TSK reader. Its deferred loader selectively tears down scene objects, loads GAM +records, then invokes per-object initialization and actual PostLoad. Jimmy and +Goddard constructors explicitly select survival through that teardown predicate +and mark themselves reusable. The enclosing retention/reuse contract is recovered; +class initialization and PostLoad still reset fields independently. + +The previously unresolved “reset flag”50988A is **keyboard R** in the input array, +and its acquired-item reset consumer is **Jimmy's editor update**, not ordinary +loading. Do not turn it into a gameplay load/reset policy. + +## Receiver, request and consumption chain + +| Link / state | Source fact / offset | +|---|---| +|Application identity|Bootstrap46A641 calls constructor46B160; constructor46B200 installs complete vtable4D5EA0 and46B237 stores this in509980. Literal4F57D8 is`CEditor()`. Bootstrap46A654 also stores the returned pointer.| +|Player request|43B7F1 dispatches slot100 on509980 after staging strings and departure root.4D5EA0+100→46DF70.| +|Deferred state|46DF76 writes byte app+74C=1;46DF7D selects filename buffer+74D and copies the argument. This is one pending flag/name, not a demonstrated multi-request queue.| +|Application update|4D5EA0+C4→46BEC0; its final46C052 checks+74C and46C05E invokes104→46DFF0. Earlier update logic includes an alternate signed frame countdown+7FA that can also set+74C at46BEDF.| +|Consume request|46DFF0 checks+74C again and performs teardown;46E152 dispatches app+FC→46E170 with stored filename and−1;46E158 clears+74C after return.| +|Load completion|46E170 reads GAM, creates/reuses records;46E4FF dispatches app128→46E570. This closes the formerly missing source edge to actual placement PostLoad.| +|Placement pass|46E570 registry traversal calls each object's28 at46E5C3, then40C at46E61A; Jimmy4A373C+40C→423610. At traversal end46E681 invokes app10C and46E694 resets the performance timer47E470.| + +App10C resolves46E710. Its inspected body traverses registry and logs object +tag/class/id; do not label it a cleanup/free operation solely because callers +surround it with “gcu” logs. App+7A4 receives the currently loading filename at +46E19F; pending+74D and current+7A4 are separate strings. + +## Teardown phases and survival predicate + +46DFF0 first calls app10C and479000, then makes three registry50999C passes. +Each pass calls object slot200, which for Jimmy/Carl/lab game interfaces resolves +4719B0: return byte **interface+139**. + +1. If predicate nonzero, call object20 at46E054 (logs “Uniniting”). +2. If predicate nonzero, call object34 at46E091 (same log). +3. If predicate nonzero, set interface+6=1 at46E0CA (“Delme”). + +46E0D9 calls473710, which repeatedly finds a marked interface+6 object and calls +its slot0 with argument1, restarting traversal after deletion. Thus this is +selective teardown; the “Deleted all objects” log is not proof of universal +destruction.4685F0 and app10C run next;46E117 calls46B000, which traverses a +database registry and closes referenced databases. Exact meaning of479000 and +4685F0 is outside this bounded audit and remains unnamed here. + +**Survival provenance.** Generic setter470F40 writes supplied byte tointerface+11 +then calls slot204; Jimmy/Carl204 resolves4719C0, storinginterface+139. Generic +constructor46FDB3..B7 passes1; Jimmy constructor4226B5..BF passes zero instead, +and Goddard41C99B..99E does likewise. Jimmy and Goddard therefore start with the +non-destructible predicate. This explains why the departure root/RETURN flags +can be fields on the character object across a scene change. It does not prove +every character field remains unchanged: initialization, property loading, +gadget cleanup and PostLoad can reset fields independently. + +The lab game object also explicitly sets predicate0 at44D456/44D472. An object's +retention and the current-level global509948 are distinct: GAM loading assigns +509948 to the destination's game object at46E360 after factory construction. +Further class-specific lifecycle flags or later predicate changes require their +own evidence; do not generalize the constructor default into a full object map. + +**Critical integration consistency gate: old level-game ownership.** The lab game +is itself selected for preservation (interface4C386C slots200/204 resolve +4719B0/C0;44D456 pushes0 before44D472 dispatches204). Ordinary GAM loading then +constructs a new destination game. A bounded inspection of46E170 through factory +46E335 found prefix46E26C→4766E0, whose literal is`UnInitCaptions()` and whose +registry is5099FC;46E271→479000 clears physics records rooted509B04. Neither +inspected prefix identifies an old509948 game destructor. + +The lab constructor chain44F300→44F358/44D2B0→44D306/4745A0 was also inspected. +4745A0 constructs/links a new OMT element (IAT48D284 is OMediaElement constructor; +48D320 is OMediaElement::link), registers its game interface, clears control via +475A40(0) at474683, then overwrites global509948 at474688. No explicit old-game +destructor/removal was established in this inspected chain. **Overwriting the +current-game pointer does not remove an old game from registry50999C.** + +Consequently the remaining contract must include the old level-game registry +membership and callback eligibility: locate its explicit removal/deactivation +or account for its retained28/40C/update callbacks. Do not infer a clean sequence +containing only Jimmy/Goddard plus the new game from selective deletion alone. +Possible later class/OMT ownership effects remain open; this negative bounded +audit does not prove that old games accumulate or remain active at runtime. + +## GAM construction/reuse and initialization + +46E170 builds`gam\\`+filename, opens a bounded original stream, reads FourCC, and +uses class factory459CB0 for the game. Factory-returned game interface is shifted +by−8C to its complete object and stored as current game509948. It then reads +entity count and serialized objects. For each class/ObjectID it asks app11C +(46E45A), resolving46E6A0: scan registry for matchinginterface+404 and require +interface byte+9 nonzero. App110 (46E46E) resolves46E6E0: return the matching +interface. Otherwise46E49A calls factory459CB0. The object's property stream is +read at46E3FD through IAT48D190 before proceeding to the next record. + +**Coordinated constructor proof.** The loop/registry investigator independently +recovered Jimmy42275A and Goddard41C9C0 writing complete+C9=1, which is game +interface+9. Both exact sequences are now guarded by this report's helper too. +Together with their zero destruction predicate, this establishes that Jimmy and +Goddard are retained and can be reused by class code. Factory3JIM branch45B1C1 +allocates and calls constructor422160 when no reusable object qualifies; it is +not itself a singleton lookup. Other surviving classes need their own+9 proof. +See [lab-registry.md](lab-registry.md) for insertion order and constructor details. + +After successful stream close,46E4FF→app12846E570 processes the resulting live +registry in order. It invokes object28, handles attached render-object state, +then object40C, handles attached render state again, then advances registry. +These are per-object boundaries, not “initialize all, then PostLoad all.” Jimmy's +28 is437890; it calls4587F0→470540 and resets movement fieldsinterface+608/+614/ ++618 and captures another velocity component+61C. Jimmy40C423610 applies: + +1. Matching source STRT root42399D and rotation4239E6. +2. Existing companion source root423A36. +3. Pending RETURN flag test423A90 and clear423A9E. +4. Saved departure root423ABF; identical companion root423B1E. +5. Game control assignment423B3D, followed by viewport camera fields423B43. + +STRT's own40C callback and trigger-suppression flag consumption run at its +position in that same registry pass. The exact registry ordering for the +lab/practice route still needs a construction trace. Existing recovered placement +and suppression behavior stays valid; its enclosing temporal interactions must +be tested when implementing retention. + +## Acquired reset belongs to editor input + +Key handlers46A360/380 read virtual-key byte and set/clear509838[key] at46A370/ +46A390.50988A−509838=52hex, ASCII/Windows virtual key **R**. Therefore4235D8 +reads R, not a scene-loader-owned flag. If pressed,4235E2 sets count1068hex=4200, +4235E9 chooses4F8438 and4235EE clears4200 integers; it then iterates29 group2 +inventory entries through403910. + +Jimmy interface slot3C8→4235B0. Wrapper470280 chooses3C8 at4702B5 only when +app509980 exists and byteapp+8C is nonzero; otherwise4702C5 chooses normal3C4 +Jimmy424600. This matches the current source naming of editor versus normal +update. The reset routine also handles a saved sound/effect handle before the +key test. It is not present as an unconditional phase in46DFF0/46E170. + +## Route persistence versus TSK load + +| State / event | Ordinary lab→VR04→lab→outside | TSK reader4603F0 | +|---|---|---| +|Request owner|CEditor app+74C/+74D, consumed in app update|Globals4FC67C/4FC604, consumed by460EA0; distinct request path| +|Character root/RETURN fields|Character stores+9A8 and transient954/9A5; predicate selects retention, PostLoad consumes flags|Reader restores three departure floats; flags are absent from file| +|GAM properties/actors|Selective teardown, class factory/reuse, per-object28→40C|Does not itself execute this ordinary scene teardown/GAM loader| +|Task assignment|Class initialization/task callbacks depend on registry and source task records|Calls45F990, then duplicate matching424; positive task-count path finally invokes all-object420; distinct from40C| +|Acquired items|No unconditional4200 reset found in this chain; R reset is editor-only|Explicit4200 serialized integers read into globaltable| +|Score, energy, inventory, objective|Global ownership; no blanket zeroing in inspected loader. Jimmy construction itself sets energy20 at4226E5, making exact reuse significant.|Reader restores explicit fields/inventory/task data| +|Clocks/render/audio|PostLoad resets performance timer; database closes and render attachment phases exist. Exact per-bank/handle ownership pending.|Reader has its own stream/object callbacks; not a complete scene lifecycle| + +**Current implementation at baseline69d0187.** Program carries OriginalSave +snapshots and explicit RETURN root/identity while reconstructing scene actors, +physics and audio, with application-owned RenderSession kept alive. This is a +useful playable testing harness; it is not the recovered retained-object loader. +Keep its presentation ownership as the user-authorized modern policy. Do not +force original editor R semantics into the game's current R reset control. + +## Bounded continuation gate + +1. Resolve old level-game removal/deactivation and callback eligibility across + destination construction. Then trace a retained Jimmy through one departure, + identifying every mutation + from property load, initialization and PostLoad. Constructor evidence closes + byte+9 ownership; it does not substitute for this per-field reset trace. +2. Build an event trace covering request, three teardown passes, destructor, + property load, per-object28/40C, STRT suppression and first input/physics tick. + Use source target/vtable evidence; test retained versus recreated objects. +3. Map per-level class constructors/initializers' score/energy/inventory writes + before adopting global persistence beyond the demonstrated route. +4. Contrast ordinary load trace against queued TSK load and its duplicate424/420 + callbacks. Preserve full wire data and do not silently serialize transient + RETURN flags or reinterpret StoredVector as immediate position. + +The loader retention contract can now support a bounded state-container design; +transferring every arbitrary field unchanged would still be unsupported. The +source chain and editor-reset correction replace an unbounded “loader unknown” +task with these concrete tests. + +Validation: five Python tests pass, covering the original hash,39 exact byte +sites,14 virtual targets, object factory/destruction/timer dependencies and R key +identity. Run `python3 -m unittest discover -s tests -p +test_checkpoint_scene_loader.py -v`. Helper JSON is reproducible with +`python3 tools/binary/checkpoint_scene_loader.py ../Original`. These are static +evidence checks, not original or port runtime verification. diff --git a/docs/checkpoint/script-state-route.md b/docs/checkpoint/script-state-route.md new file mode 100644 index 0000000..27b7bb4 --- /dev/null +++ b/docs/checkpoint/script-state-route.md @@ -0,0 +1,206 @@ +# Script, task and transition ownership checkpoint + +Read-only original investigation, 2026-10-25. Baseline audited: +`69d0187a2178deab1edff961d5126dad1cce3a05`. Preserve that playable baseline. +This checkpoint uses **fact** for original bytes/GAM data, **inference** for their +interpretation, **implementation** for modern source, and **runtime** only for an +executed game. No original-game runtime capture was obtained for this report. + +## Source identity and reproducible evidence + +| Original file | SHA-256 | +|---|---| +|`Neutron.exe`|`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`| +|`gam/level1b.gam`|`316fff40db565c2add5b07cbccdef640ddb67c64d6625fea1429ce2a0542a234`| +|`gam/VR04.gam`|`e34f6b6aa11ba1137dc4410148565b3c29db9d02c5fcc1f145017dafd2f3ca04`| + +All executable addresses below are preferred-base Neutron.exe VAs. The inspected +sites have raw file offset **VA−0x400000**, independently checked using PE section +mapping, not assumed by the helper. GAM offsets are raw offsets in the named file. +`tools/binary/checkpoint_script_state.py ../Original` emits hashes, individual +VA/offset/byte records, resolved direct calls/vtable targets, and exact route GAM +fields. It reads originals and writes only stdout. The corresponding Python test +guards the decisive evidence. Cached `artifacts/binary/neutron.asm` was used for +cross-reference discovery; decisive sites were re-disassembled from the original. + +## New inconsistency audit: task ordering + +**Fact.** `45F990` does more than set a task value. Its phases are: + +1. For matching SCENE milestones, call objective helper `406F50` at + **45FB5B / file5FB5B**, before task record mutation. +2. Traverse task list `4FC5FC`; case-insensitive match; store supplied state at + record+64 at **45FB7F / file5FB7F**. It updates existing records, including + repeated values; it does not insert unknown names. +3. Traverse game-object registry `50999C`; compare interface+430 TaskName; + matching objects receive interface slot424 at **45FBD9 / file5FBD9**. + +The objective callback can therefore observe the **old task state**. Per-object +task callbacks observe the **new task state**. The call is synchronous: each +derived callback finishes before moving to the next registry object. This is an +ownership/order contract, not merely an eventual-state assertion. + +**Baseline implementation mismatch.** `TaskStates.SetExisting` mutated records, +then invoked one `Assigned` event. `SceneDirector` was the first subscriber and +updated a batch of generic actors; `SceneInteractions` subscribed afterward and +selected the objective and applied all Carl overrides. Both objective timing and +derived-callback boundaries differed from the original. This justifies C1/C2 in +[implementation-plan.md](implementation-plan.md). The primary has implemented a +separate pre-assignment objective boundary during this checkpoint; integration +results belong to the primary ledger, not this static evidence report. + +**Carl callback detail (new audit).** Interface vtable495364+424 points to413F30. +At **413F3D / file13F3D** it queries current SCENE via45FEA0, saves it in EBX at +413F45, then at **413F4E / file13F4E** calls generic40E340 with the supplied +callback value. Only after that base callback returns does it inspect level code +and run the LV1B override414068..414118. Thus its contract is **capture SCENE → +base activation → derived action**, inside one object callback. The override +uses the captured SCENE value, not a later reread. No reentrant task mutation was +observed in this investigation; this does not prove such mutation impossible. + +For LV1B, scene outside0..60 disables Carl; >30 resolves CARLESC3, sets AIstate6 +at4140AA and copies marker root via slot314 at4140E0; <60 activates him, exactly60 +leaves base activation unchanged. Repeated assignments can therefore reposition +him. Applying this as a post-batch correction masks class behavior and can expose +partially updated state to actor observers. + +## State owners, structures and lifetimes + +Jimmy has a complete C++ object and a game interface at complete+C0. Mixing those +bases produced earlier apparent contradictions. Constructor4221E8/42220B installs +complete vtable4A3BDC and game-interface vtable4A373C. Player base constructor +437280 initializes inherited transition state. Read/write sites below retain the +base used by the actual instruction. + +| Owner / field | Writes, consumers and lifetime | +|---|---| +|Global5099E4, controlled game interface|Game setter475A40; script/control handoffs replace it. Input, UI and player logic consult it. Null is a control state, not evidence that all world updates stop. Not a TSK field.| +|Task list4FC5FC; record name+0/state+64|45F990 mutates/broadcasts synchronously; trigger, actor and LOAD queries consume. Serialized by TSK.| +|Global4F8194 objective selector|406F50 updates selector and transient objective flags before SCENE mutation. TSK serializes selector; flags/timer are separate runtime state.| +|Jimmy complete+724, +774|Transition/start strings, written by43B5A0; writer460057..6F persists both. +774's wider role remains unresolved.| +|Jimmy complete+88C/+8F0|RETURN level/start strings, written by43B5A0, consumed by LOAD RETURN and persisted in TSK.| +|Jimmy complete+955|Staged level-name string, copied43B772..78C; not one of the four TSK strings. Dependency on game loader pending further recovery.| +|Jimmy complete+9A8..9B7|16-byte departure root captured by43B5A0 unless+9A5. First three floats serialize as TSK StoredVector. No yaw/velocity/camera state in this copy.| +|Jimmy complete+954|RETURN sets it; matching STRT consumes it to suppress the initial trigger once. Separate from root restoration; not serialized.| +|Jimmy complete+9A5|RETURN sets it; staging preserves departure root; Jimmy PostLoad consumes it and restores root. Not serialized.| +|Jimmy complete+1E38..1E47/+1E48|Independent pickup capture root/level.42AF00 writes;42AF50 writes plus attached effect callback. Not the TSK departure root. Read consumer unresolved.| +|Globals4FC604 filename/4FC67C pending|460E70 queues TSK load;460EA0 update consumes and clears. One pending filename, not a proven request queue.| +|Acquired table4F8438;19 inventory entries;score4F83C0;energy4F83D4|Global/save-owned data. Pickup/inventory/score actions mutate; TSK persists. Complete state-reset policy for ordinary level load is still open.| + +**Vtable provenance.**4A3BDC+168→43B5A0, +1E8→42AF00, ++1EC→42AF50. Carl495364+424→413F30. LOAD4D025C+424→458880 only stores taskstate; +it must not inherit animated activation merely because its base has TaskName. + +## First end-to-end source case study + +| Route event | Recovered fact and state boundary | +|---|---| +|New game/lab entry|NewGame.tsk has SCENE30. LV1B STRT STARTEXP **GAM5B0E**, yaw155, StartTrigger LABEXP. STRT4426A7 validates the deferred target and clears controlled entity before dispatch.| +|Intro completion|AI/CAM/MCA chain recovered in lab-progression.md; DEFAULT447CF0 restores Jimmy/inventory, clears skip and conditionally restarts music. It does not simply assign SCENE35/60. Speech-end handles drive CAM/MCA update; port sample-duration timing remains an approximation.| +|Explanation|Special AI40CB43..6B maps SCENE30/31→35. Task setter selects objective1 before task records35 and actor callbacks.| +|Jetpack pickup|LV1B3PIC **GAM1799**, internal tagshrinkray, index301,+50,radius125. Generic435CE0 marks acquired/hides; special4365D0 only at SCENE35 calls Jimmy+1E8→42AF00 first; then SCENE50, group0/item3=1,406F90(0) practice prompt, gadget3. Positive score occurs after special hook. Pickup outside35 still has generic acquisition/+50 without those special side effects.| +|Practice No|UI modal resumes current level. It does not stage a departure or overwrite the RETURN root. Modern practice modal behavior is covered separately in camera/audio/UI checkpoint.| +|Practice Yes|4046AF stages VR04/PHONEBOOTH with current level/current STRT as RETURN context via complete+168→43B5A0.43B78E sees no pending RETURN, captures the live root into+9A8, then schedules game slot100 at43B7F1. Capture happens on acceptance, not necessarily on pickup.| +|Tutorial entry|VR04 STRT PHONEBOOTH **GAM48C**, yaw290, trigger sr1. Persistent task/inventory/acquired/score save-like state is distinct from new scene actors and playback handles. Source exact loader teardown order remains unresolved.| +|Tutorial exit|Two VR04 LOAD RETURN gates **GAMB0D7/B4C5**, radii400/350. RETURN457FF7 cleans gadget, sets+954 at458014 and+9A5 at458028; resolves saved level/start and dispatches transition168 at45815C. Staging must preserve lab departure root instead of capturing tutorial exit.| +|Lab RETURN|Jimmy423A90..9E consumes pending+9A5; root setter423ABF receives savedXYZ. Companion423AE3..423B1E receives identical saved root, no offset/yaw. Requested STRT supplies yaw155. STRT4427F2 consumes+954 and suppresses LABEXP entirely; fast-forwarding LABEXP would wrongly execute its actor/task actions.| +|Carl approach|Contact target match40A44C; AIstate6 contact40A676..68D sets0. Friend update41B950 invokes generic AI then41B972..988 dispatches talk when resultingstate0. General sensing/facing remains incomplete in port.| +|Carl conversation|Talk41BB20 chooses first existing matching task/wildcard target, retains it, derived callback413E50 first awards+100 and SCENE50→60, then41B7D3 dispatches selected neutron1a. Score150/SCENE60 precede dialogue. neutron1a **GAME0B** has5 shots, PlayerControlledJIM1 as completion target and NextTriggercarlwalk. Activation43159E clears control; completion4311F0 restores target.| +|Outside exit|LABTONEIGH **GAMA43** requiresSCENE≥60, no exact gate, radius200; destination **level1.gam / level1**. Earlier lab-progression.md's `startlevel1` is a documentation error: the exact GAM value is `level1`. Runtime source-field lookup already uses this value. LOAD contact's required-task gate457F32..5F is separate from generic activation.| + +The source route does not require interpreting pickup42AF00 as respawn. It also +does not justify replacing ordinary level load with TSK file load: those are +distinct entry points with different transient flags. + +## Save/load boundary: new call and callback audit + +**Fact.** Writer45FEE0 locatesJIM1 via474070 at460043; the lookup returns game +interface. Its+8E8/+8EC/+8F0 writes46008B..B0 are complete+9A8/+9AC/+9B0. +Reader460A79 explicitly subtractsC0 from controlled interface, then460BA3/BAD/BBA +stores the same complete-object vector. This proves TSK StoredVector is departure +state; it does not serialize the separate pickup capture or pending954/9A5. + +**New queue provenance.**460E70 sets pending4FC67C at**460E7B / file60E7B** and +copies requested name to4FC604. Caller sites include404B54 (NewGame),406E80, +40D08E,4247F0,424BCF,42B1B9..42B21B (slot-name dispatch).460EA0 first executes +its inherited/update logic473240, then460EE1 tests pending,460EF0 calls4603F0 +with filename,460EF8 clears pending. These are deferred TSK load calls; menu +request ownership and engine update scheduling require the loop investigation. + +**New double-callback fact.** Each valid saved task is sent through45F990 at +**460CE2 / file60CE2**, including its objective and ordinary actor callbacks. +The reader then makes another registry traversal and calls matching non-none +TaskName slot424 again at**460D2E / file60D2E**. Thus duplicate per-task callback +execution is present in the supplied binary. A final all-object slot420 traversal +appears at**460D87 / file60D87**, after positive-count task loading; the no-task +branch460C65 jumps to cleanup460D98 and skips that traversal. + +Do **not** call slot420 Jimmy placement PostLoad: vtable4A373C+420 is472970, +the log helper; Carl495364+420 is413EB0. The placement/root code423A90 belongs +to a different initialization path. Exact function names for slot420 remain +unproven; use “post-task slot420” until class-specific behavior is mapped. + +**Actual placement PostLoad provenance (new audit).** Jimmy game vtable +4A373C+40C points to423610; its first log literal4EF3B4 explicitly says +`Calling PostLoad for C3DJimmy()`. Registry traversal46E570 invokes each object's +slot28 at46E5C3, conditionally handles an attached/render object, then invokes +slot40C at **46E61A / file6E61A**, before moving to the next registry entry. +Within Jimmy PostLoad, matching STRT lookup42385B..423885 precedes authored root +application42399D, authored rotation4239E6, available companion source-root +application423A36, RETURN test423A90/clear423A9E, saved-root application423ABF, +same-root companion application423B1E, and game control assignment423B3D. Camera +viewport setup follows423B43. This establishes local call order, not the full +caller chain from game slot100 to46E570; the latter remains C7 work. + +Separate lifecycle callback4235B0 (Jimmy game slot3C8) conditionally clears4200 +acquired integers at4235E9..5EE and calls group2 inventory helper for29 entries +when global50988A is set. Follow-up `scene-loader.md` proves this is R in the +virtual-key table509838, consumed only in editor3C8 mode. It is not an ordinary +loader-reset flag. Ordinary selective retention and per-field PostLoad behavior +must be traced separately before generalizing item reset/persistence. + +**Baseline implementation.** `OriginalSave` parses/encodes all12 supplied TSKs; +`TaskStates` and fresh `SceneDirector` construction restore modern state. +CLI `--write-save` serializes existing StoredVector, not necessarily current +player root; this matches the recovered departure-field identity, but is not a +complete original save UI. `Program.SceneContinuation` carries root and explicit +Returning; `SceneInteractions.Snapshot` carries arrays/task/inventory/score/ +energy/return strings. New scene actors/audio are reconstructed. The port does +not reproduce the queued TSK reader, duplicate broadcasts or all-object420 path. +These should be investigated before implementing full source resume behavior. + +## Independent checkpoint consumer audit + +42AF00 captures current game level from509948+490 into+1E48 and root getter310 +into+1E38.42AF50 repeats this then attached+ A18 object's slot4B8 effect call. +Constructor4221E2 initializes checkpoint vector fourth component+1E44 to1. +An explicit operand search in the EXE disassembly for complete+1E38/+1E3C/ ++1E40/+1E44/+1E48 and interface-relative+1D78/+1D7C/+1D80/+1D84/+1D88 found +capture/constructor writes, but no demonstrated read consumer.42B2A3's subtract +1E48 is a virtual-base adjustment thunk, not a checkpoint read. This bounded +search is negative evidence only: aliases, indexed/member pointers and other +modules can hide consumers. No death/respawn/reset policy is established. + +## Coverage, unresolved questions and next gates + +| ID | Remaining question / evidence gate | Bounded action | +|---|---|---| +|S1|Full registry order and reentrant mutations unknown; capture-before-base matters for Carl.|C2 preserve per-actor query/base/derived boundary and test notification sees final Carl state. Do not add invented class callbacks.| +|S2|What owns ordinary game slot100 load request and which globals/actors persist?|C7 trace43B7F1 receiver vtable, staged+955 string and loader update through scene construction/destruction. Contrast with460E70 TSK path.| +|S3|Why does TSK reader duplicate callbacks; what does420 do per class?|Build source callback trace for Carl/pickup/LOAD; compare same-value assignment/load before adopting duplicates. Preserve exact no-task branch distinction.| +|S4|Independent pickup root/level consumers unknown.|Trace virtual-base/member aliases and constructor RTTI before labeling respawn. No gameplay change justified now.| +|S5|RETURN flag survival and matching STRT consumption through all loader paths.|Trace actual ordinary scene loader and PostLoad order; test initial trigger suppression independently from placement and TSK resume.| +|S6|Exact script/physics/contact scheduling and sound-handle completion incomplete.|C3/C6 phase and voice trace; avoid treating null control as whole-world pause or file duration as source end event.| +|S7|Persistent energy/inventory/29 counters reset policy beyond route unclear.|Recover load/constructor globals writes; preserve unknown wire values; no normalization or minimum task assumptions.| + +Recovered route contracts and these explicit boundaries are sufficient for C1/C2, +and for a concrete C7 investigation. Full source resume, generic scripts and +other levels remain incomplete. Current route managed/headless tests and user +Windows reachability provide port evidence only; they do not prove the original +end-to-end behavior or original runtime timing. + +Validation for this report: `python3 -m unittest discover -s tests -p +test_checkpoint_script_state.py -v`; five tests assert binary identity,25 byte +sites,8 vtable dependencies, task/Carl ordering, deferred load call, distinct +source destinations and bounded helper rejection. Source files only were read; +no original executable was run. diff --git a/docs/checkpoint/voice-clock.md b/docs/checkpoint/voice-clock.md new file mode 100644 index 0000000..c01fe0f --- /dev/null +++ b/docs/checkpoint/voice-clock.md @@ -0,0 +1,61 @@ +# C6 follow-up: completion is software duration plus repeat + +Primary static recovery,2026-10-25; same hashed EXE/DLL identities as the core +camera/audio/UI report. `checkpoint_voice_clock.py` verifies12 DLL instruction +anchors,3 vtable targets and2 constants, emitting PE-mapped physical file offsets. +No original executable was run. This refines the earlier unresolved “voice status” +interpretation; it does not establish transport output or native timing fidelity. + +## Recovered call and field provenance + +EXE47D890's channel slot14 is **not** a backend hardware-playing query. Both +DirectSound channel vtable10115420+14 (file115434) and WinSound channel +10116B3C+14 (file116B50), as well as base1011629C+14 (file1162B0), point to +DLL10071E40 (file71E40), exported `OMediaSoundChannel::get_playing_sound_info`. +Constructors1003AF58 and100F87DA install the respective derived tables. + +10071E40 returns elapsed time through its first unsigned output and stored +duration+1C through the second. If duration is zero both outputs become zero. +When timer running (2C/2D clear), elapsed is engine millisecond clock100F8CF0 +plus channel+28 minus channel+20; otherwise it uses frozen+24. At10071E7F..83 +only **elapsed > duration** expires and clears duration+1C. Equality still reports +nonzero duration. This is neither a DirectSound GetStatus result nor a speaker +audibility check. The backend may query GetStatus in queue pumping, a different +consumer from this slot14 predicate. + +After successful play, DX1003B46E..482 and Win100F891A..92E compute channel+1C +from sound+44 using `durationSeconds*1000 + .5` then integer conversion helper +10104E04. Constants10115450=1000 and10115448=.5. Exact conversion-mode semantics +of10104E04 and sound+44's decoder provenance still need a bounded follow-up; +do not assert PCM sample duration is always its bit-identical source. + +Byte+30 is copied from the final boolean play argument: DX1003B32B reads it, +1003B338..343 turns it into the buffer's play flags,1003B46B stores it. Win +100F8893 selects flags2017/201F and100F8917 stores it. This is the **repeat/loop +flag**, not a pending-start flag. DX stop1003B657 clears+30 and+1C; Win stop +100F898F/100F8996 does the same. DX queue pump1003B691 skips its ordinary queued +advance when+30 is set. The interpretation is supported by matching play/stop/ +queue branches in both backends; no original playback was observed. + +Therefore EXE47D890's final predicate is structurally: + +```text +valid engine + in-range handle + existing channel + AND (software duration returned by slot14 != 0 OR channel repeat flag != 0) +``` + +Calling this “hardware voice status” would be an overclaim. The explicit bank, +handle stop/release, failed play and engine timer pause still matter. The baseline +port's prepared-file-duration clock is closer to the ordinary one-shot source +clock than an SDL queue-empty predicate would be, but differs in integer boundary, +source duration identity, pause/clock ownership, invalid handles and dispatch order. + +## Implementation consequence and remaining gate + +Do not replace CAM/MCA completion with SDL queued bytes merely because source +polls a handle. First model source channel state (duration milliseconds, elapsed, +repeat, stop/invalid handle and engine clock pause), recover47D060 allocation/ +play failure and source sound+44 derivation, then connect director completion to +that state. Independent SDL transport can remain the output mechanism. Current +duration/leftover-dt director behavior stays explicitly approximate until that +contract is tested. This bounded correction changes the C6 plan, not gameplay yet. diff --git a/docs/compatibility.md b/docs/compatibility.md index 483e36f..5adcd93 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -3,6 +3,14 @@ Compilation, native runtime, original behavior and full feature completion are separate evidence categories. **The game is not fully reconstructed/playable yet.** +Architecture checkpoint: see `checkpoint/review.md` for coverage and remaining +gates. C1 objective/task order and C2 per-actor Carl callback corrections pass the +full `scripts/test.sh` integration, all GPU runs with zero Vulkan validation +errors. Final Python discovery passes62 tests including the additional source +evidence follow-ups. All539 original hashes remain unchanged. These checks do not +add native Windows or original whole-game runtime verification; earlier Windows +user reports remain limited to their tested builds and route. + | Feature | Implemented / tested | Evidence and limits | |---|---|---| | Original preservation | Verified after extraction/runtime tests | All539 original SHA-256 hashes unchanged | diff --git a/docs/decisions.md b/docs/decisions.md index 325d8c9..9730fb6 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -100,3 +100,15 @@ canvases and anchor objectives bottom/right and F2 top-left. Map logical input through actual drawable dimensions with double precision for strict bounds. This is authorized modern widescreen policy, not original algorithm recovery. +23. **Pause feature expansion for architecture recovery.** Preserve clean69d0187 + as a local tag and independent package copies. Use the lab/tutorial/return/ + outside route to map state owners, callers, phases and persistence before more + gameplay. `checkpoint/` supersedes older architecture/priority summaries. + Evidence probes and directly evidenced corrections are permitted. A documented, + gated implementation plan ends the investigation checkpoint; continue through + it without waiting to understand every level. +24. **Separate task objective and entity phases.** Original45FB5B selects the + objective before task record mutation45FB7F and entity dispatch45FBD9. Expose + pre-assignment notification rather than relying on subscriber registration + order. Preserve repeated/missing assignment dispatch. Source loader's additional + task callbacks/PostLoad are a distinct lifecycle question, not implied by this fix. diff --git a/docs/progress.md b/docs/progress.md index 7761c55..9bb00fc 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -1,5 +1,30 @@ # Progress — 2026-10-25 +## Architecture reverse-engineering checkpoint + +User direction supersedes feature-expansion priorities below. Full `prompt.MD` +read; current code/findings/progress audited. Clean playable69d0187 is preserved +by local tag `baseline-re-checkpoint-2026-10-25` and copied Linux/Windows packages +under `artifacts/re-checkpoint/baseline/`. All539 originals verified unchanged. +The existing Gitea remote configuration was left untouched and unused; older +claims below that no remotes are configured are stale. No remote work occurred. + +Canonical continuation: `checkpoint/README.md`, `coverage.md`, +`implementation-plan.md` and the three system reports. New evidence separates +viewport physics/object update/sync from engine logic/morph timing, identifies +construction-order registry traversal, objective-before-task assignment and +per-actor Carl callbacks, DEFAULT camera snap, bank/voice ownership gaps and TSK +queued/duplicate-callback lifecycle. No original full-game runtime verification. + +Initial architecture checkpoint exit is recorded in `checkpoint/review.md`. +C1 objective-before-records and C2 per-actor Carl callbacks are implemented; +the full integration suite passes, with zero GPU validation errors and539 hashes +unchanged. C3 fresh registry/input bridge, C5 first-hit static ray, C6 software +duration/repeat clock and C7 selective ordinary loader follow-ups are documented. +All investigator ownership returned. Exact old level-game registry eligibility +and retained-field reset traces gate scheduler integration; camera/audio/physics +chunks have independent concrete evidence gates. See the execution ledger. + **The full reconstruction is incomplete.** The current implementation extends the user-verified Windows rendering checkpoint into an interactive original lab and jet pack tutorial flow. This is not a verified faithful complete scene or release. diff --git a/docs/tasks.md b/docs/tasks.md index e0f7a14..6e57552 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -42,6 +42,26 @@ compile, runtime and original-fidelity verification are separate. ## Immediate continuation +**Direction changed: pause feature expansion for the architecture checkpoint.** +Read `checkpoint/README.md`, `coverage.md` and `implementation-plan.md`. Preserved +baseline69d0187 remains the testing tool. The loop/motion, script/state and +camera/audio/UI investigations document the original lab→VR04→lab→outside route. +Complete core owner/order/lifetime evidence and unknowns, then execute the gated +plan in verified chunks. Earlier priorities below are a backlog. + +- [x] Preserve clean playable source tag and independent Linux/Windows package copies. +- [x] Verify539 unchanged originals at checkpoint entry. +- [x] Recover frame-before-controller physics and construction-order registry passes. +- [x] Record core-system coverage, state ownership, assumptions and bounded plan. +- [x] Integrate independent reports/original-byte regressions; architecture exit review. +- [x] C1 objective-before-records order; managed and full integration checks pass. +- [x] C2 per-actor Carl override; full integration and route checks pass. +- [x] C3 input/frame/fresh construction, C5 grid predicate, C6 software voice clock + and C7 ordinary selective-loader evidence follow-ups. +- [ ] Next: current-game registry removal/eligibility and retained Jimmy/helper + resets; then split scheduler phases against a source route lifecycle trace. + Static camera adapter can proceed independently with source first-hit rules. + 1. Lab regressions are corrected and republished, with user verification of their own Windows build. Keep comprehensive native Windows driver/audio/input coverage separate from that report and preliminary Wine checks. Continue diff --git a/src/GamePort/Game/SceneDirector.cs b/src/GamePort/Game/SceneDirector.cs index 26759c5..5fe54d6 100644 --- a/src/GamePort/Game/SceneDirector.cs +++ b/src/GamePort/Game/SceneDirector.cs @@ -528,8 +528,28 @@ public sealed class SceneDirector // animated actor's TaskName activation contract. Applying the latter // here disables the lab exit even when SCENE reaches60. if (source.Kind == "LOAD") return; + // Carl413F30 captures SCENE before generic40E340, then executes his + // derived policy in the same callback, before the next registry actor. + var carlScene = source.Kind == "3CAR" ? tasks.Get("SCENE") : 0; var active = source.Kind == "3PIC" ? TaskActivation.Pickup(source, state) : TaskActivation.Animated(source, state); - if (active.HasValue) { actor.Active = actor.Visible = active.Value; ActorChanged?.Invoke(actor); } + if (active.HasValue) actor.Active = actor.Visible = active.Value; + var carlOverride = source.Kind == "3CAR" && level.Code == "LV1B"; + if (carlOverride) + { + //414068..414118. Other levels' derived policies remain unported. + if (carlScene is < 0 or > 60) actor.Active = actor.Visible = false; + else + { + if (carlScene > 30 && FindActor("CARLESC3") is { } marker) + { + actor.AIstate = 6; + actor.Position = marker.Position; + } + // At60 retain the generic activation result. + if (carlScene < 60) actor.Active = actor.Visible = true; + } + } + if (active.HasValue || carlOverride) ActorChanged?.Invoke(actor); } private void Block(GamEntity source, string detail, string? next) diff --git a/src/GamePort/Game/SceneInteractions.cs b/src/GamePort/Game/SceneInteractions.cs index fbb19ee..1e82a70 100644 --- a/src/GamePort/Game/SceneInteractions.cs +++ b/src/GamePort/Game/SceneInteractions.cs @@ -15,7 +15,6 @@ public sealed class SceneInteractions private readonly SceneDirector director; private readonly TaskStates tasks; private readonly OriginalSave initial; - private readonly string levelCode; private readonly int[] itemStates; private readonly HashSet contacts = []; private readonly HashSet unsupported = []; @@ -34,15 +33,15 @@ public sealed class SceneInteractions public event Action? ConversationStarted; public event Action? ObjectiveChanged; - public SceneInteractions(SceneDirector director, TaskStates tasks, OriginalSave save, string? levelCode = null) + public SceneInteractions(SceneDirector director, TaskStates tasks, OriginalSave save) { this.director = director; this.tasks = tasks; initial = save; - this.levelCode = levelCode ?? save.LevelCode; Inventory = new SceneInventory(save.InventoryStates); itemStates = save.ItemStates.ToArray(); Score = save.Score; Energy = save.PlayerValue; CurrentObjective = save.OtherCounter; ReturnLevel = save.ReturnLevel; ReturnStart = save.ReturnStart; + tasks.Assigning += OnTaskAssigning; tasks.Assigned += OnTaskAssigned; Reset(); } @@ -68,7 +67,6 @@ public sealed class SceneInteractions { contacts.Clear(); HideCollected(); - ApplyCarlTask(); } public void HideCollected() @@ -191,36 +189,20 @@ public sealed class SceneInteractions } } - private void OnTaskAssigned(string name, int value) + private void OnTaskAssigning(string name, int value) { - HideCollected(); if (Equal(name, "SCENE")) { - //45F990 jump tables ->406F50: clear the transient objective flags, - //select this objective and set its flag1; TSK writes selector4F8194. + //45FB5B ->406F50 runs BEFORE records change at45FB7F and before + //entity slot424 callbacks at45FBD9. TSK writes selector4F8194. var objective = ObjectiveForScene(value); if (objective != 0) { CurrentObjective = objective; ObjectiveChanged?.Invoke(objective); } - ApplyCarlTask(); } } - private void ApplyCarlTask() + private void OnTaskAssigned(string name, int value) { - //Carl's override413F30 follows generic activation; LV1B branch414068. - //Other levels' custom visibility/position policies are not ported here. - if (levelCode != "LV1B") return; - var state = tasks.Get("SCENE"); - foreach (var actor in director.Actors.Where(a => a.Kind == "3CAR" && Equal(a.SourceGam?.Text("TaskName"), "SCENE"))) - { - if (state is < 0 or > 60) { actor.Visible = actor.Active = false; continue; } - if (state > 30 && director.FindActor("CARLESC3") is { } marker) - { - actor.AIstate = 6; - actor.Position = marker.Position; - } - //At60 the override leaves the generic activation result unchanged. - if (state < 60) actor.Active = actor.Visible = true; - } + HideCollected(); } private static bool Equal(string? a, string? b) => a is not null && b is not null diff --git a/src/GamePort/Game/TaskStates.cs b/src/GamePort/Game/TaskStates.cs index 859ae26..79a564f 100644 --- a/src/GamePort/Game/TaskStates.cs +++ b/src/GamePort/Game/TaskStates.cs @@ -6,6 +6,9 @@ namespace GamePort.Game; public sealed class TaskStates { private readonly List tasks; + /// 45FB5B objective dispatch, before task records or actor callbacks change. + public event Action? Assigning; + /// 45FBD9 entity dispatch, after all matching task records change. public event Action? Assigned; public TaskStates(IEnumerable initial) => tasks = initial.ToList(); private static bool Equal(string a, string b) => Fold(a) == Fold(b); @@ -16,6 +19,7 @@ public sealed class TaskStates public int Get(string? name) => name == null ? 0 : tasks.FirstOrDefault(t => Equal(t.Name, name))?.State ?? 0; public void SetExisting(string name, int value) { + Assigning?.Invoke(name, value); for (var i = 0; i < tasks.Count; i++) if (Equal(tasks[i].Name, name)) tasks[i] = tasks[i] with { State = value }; // Original broadcasts even repeated assignments and unknown task names. diff --git a/src/GamePort/Program.cs b/src/GamePort/Program.cs index 1bd4360..37ff645 100644 --- a/src/GamePort/Program.cs +++ b/src/GamePort/Program.cs @@ -320,7 +320,7 @@ internal static class Program var tasks = new TaskStates(save.Tasks); storyTasks = tasks; director = new SceneDirector(level!, tasks, resources.Duration); - interactions = new SceneInteractions(director, tasks, save, level!.Code); + interactions = new SceneInteractions(director, tasks, save); objectivePanel = new ObjectivePanel(interactions.CurrentObjective); interactions.ObjectiveChanged += objectivePanel.Select; simulation!.Energy = interactions.Energy; diff --git a/tests/GamePort.DataTests/Program.cs b/tests/GamePort.DataTests/Program.cs index 3666218..6d67432 100644 --- a/tests/GamePort.DataTests/Program.cs +++ b/tests/GamePort.DataTests/Program.cs @@ -32,12 +32,18 @@ Require(newGame.LevelCode == "LV1B" && newGame.StartPoint == "STARTEXP", "Wrong var tasks = new TaskStates(newGame.Tasks); Require(tasks.Get("scene") == 30 && tasks.Get("missing") == 0, "Original task query semantics differ"); var assignments = 0; +var assignmentPhases = new List(); +tasks.Assigning += (name, value) => assignmentPhases.Add($"before:{tasks.Get(name)}:{value}"); +tasks.Assigned += (name, value) => assignmentPhases.Add($"after:{tasks.Get(name)}:{value}"); tasks.Assigned += (_, _) => assignments++; tasks.SetExisting("ScEnE", 35); tasks.SetExisting("missing", 77); tasks.SetExisting("SCENE", 35); Require(tasks.Get("SCENE") == 35 && tasks.Get("missing") == 0 && tasks.Snapshot().Length == 12 && assignments == 3, "Task assignment must broadcast without creating missing entries"); +Require(assignmentPhases.SequenceEqual(new[] { "before:30:35", "after:35:35", "before:0:77", + "after:0:77", "before:35:35", "after:35:35" }), + "Objective phase must see old records, entity phase new records, including repeated/missing assignments"); var changed = newGame with { Score = 15, Tasks = tasks.Snapshot() }; Require(OriginalSave.Parse(changed.Encode()).Score == 15 && OriginalSave.Parse(changed.Encode()).Tasks[3].State == 35, "Modified original save did not persist recovered fields"); diff --git a/tests/GamePort.DirectorTests/Program.cs b/tests/GamePort.DirectorTests/Program.cs index b2baf04..afc6cdf 100644 --- a/tests/GamePort.DirectorTests/Program.cs +++ b/tests/GamePort.DirectorTests/Program.cs @@ -7,6 +7,45 @@ using GamePort.Application; var root = Path.GetFullPath(args.Length == 1 ? args[0] : "../Original"); var level = GamLevel.Load(AssetPath.Resolve(root,"gam/level1b.gam")); var save = OriginalSave.Load(AssetPath.Resolve(root,"NewGame.tsk")); +// Original Carl413F30 owns its complete base+derived task callback. Observers +// must never see a generic-only Carl state or wait for SceneInteractions to fix it. +var orderedTasks = new TaskStates(save.Tasks); +var orderedDirector = new SceneDirector(level, orderedTasks, (_, _) => 1); +var orderedCarl = orderedDirector.FindActor("C3DCARL")!; +var orderedMarker = orderedDirector.FindActor("CARLESC3")!; +var notifiedCarl = false; +var notifiedAfterCarl = false; +orderedDirector.ActorChanged += actor => +{ + if (ReferenceEquals(actor, orderedCarl)) + { + Check(orderedTasks.Get("SCENE") == 50 && actor.Active && actor.Visible && actor.AIstate == 6 + && actor.Position == orderedMarker.Position, "Carl callback observer sees final derived state"); + notifiedCarl = true; + } + else if (notifiedCarl) + { + Check(orderedCarl.Position == orderedMarker.Position && orderedCarl.AIstate == 6, + "Later actor callbacks observe completed Carl override"); + notifiedAfterCarl = true; + } +}; +orderedCarl.Position = Vector3.Zero; orderedCarl.AIstate = 0; +orderedTasks.SetExisting("SCENE", 50); +Check(notifiedCarl && notifiedAfterCarl, "Authored registry includes Carl followed by task actors"); +foreach (var scene in new[] { -1, 0, 30, 31, 59, 60, 61 }) +{ + var boundaryTasks = new TaskStates(save.Tasks.Select(t => t.Name == "SCENE" ? t with { State = scene } : t)); + var boundaryDirector = new SceneDirector(level, boundaryTasks, (_, _) => 1); + var actor = boundaryDirector.FindActor("C3DCARL")!; + var generic = TaskActivation.Animated(actor.SourceGam!, scene); + Check(actor.Active == (scene is >= 0 and < 60 || scene == 60 && generic != false), + "LV1B Carl derived activation boundaries and generic result at60"); + if (scene is > 30 and <= 60) + Check(actor.AIstate == 6 && actor.Position == boundaryDirector.FindActor("CARLESC3")!.Position, + "Carl marker/state override follows base activation at construction"); +} +Console.WriteLine("PASS per-actor Carl task callback order, derived observation and LV1B boundaries"); var tasks = new TaskStates(save.Tasks); var director = new SceneDirector(level,tasks,(_,_)=>.1); var cues = 0; diff --git a/tests/GamePort.InteractionTests/Program.cs b/tests/GamePort.InteractionTests/Program.cs index 8497e06..14eb8c7 100644 --- a/tests/GamePort.InteractionTests/Program.cs +++ b/tests/GamePort.InteractionTests/Program.cs @@ -10,7 +10,7 @@ var lab = GamLevel.Load(AssetPath.Resolve(root, "gam/level1b.gam")); var counter = 1; var tasks = new TaskStates(original.Tasks); var director = new SceneDirector(lab, tasks, (_, _) => 5); -var interactions = new SceneInteractions(director, tasks, original, lab.Code); +var interactions = new SceneInteractions(director, tasks, original); director.Begin(lab.FindStart()!); interactions.Reset(); director.Skip(); @@ -25,7 +25,19 @@ var help = -1; var selected = -1; var events = new List(); interactions.CheckpointCaptured += p => { checkpoint = p; events.Add("checkpoint"); }; -tasks.Assigned += (name, state) => { if (name == "SCENE" && state == 50) events.Add("task50"); }; +interactions.ObjectiveChanged += objective => +{ + if (objective != 2) return; + Check(tasks.Get("SCENE") == 35, "Objective callback observes old task records before assignment"); + events.Add("objective2"); +}; +tasks.Assigned += (name, state) => +{ + if (name != "SCENE" || state != 50) return; + Check(interactions.CurrentObjective == 2 && tasks.Get(name) == 50, + "Entity assignment observers see the selected objective and new task records"); + events.Add("task50"); +}; interactions.PracticeRequested += page => { help = page; events.Add("help"); }; interactions.Inventory.GadgetSelected += gadget => { selected = gadget; events.Add("gadget"); }; interactions.Collected += (_, points) => events.Add("score" + points); @@ -33,10 +45,10 @@ interactions.Update(shrinkray.Position); Check(tasks.Get("SCENE") == 50 && interactions.Score == 50, "Shrinkray grants50 and original task35->50"); Check(interactions.Inventory.State(0, 3) == 1 && selected == 3 && help == 0, "Shrinkray inventory/help/gadget side effects"); Check(checkpoint == shrinkray.Position && !shrinkray.Visible && !shrinkray.Active, "Capture current root before hiding acquired shrinkray"); -Check(events.SequenceEqual(new[] { "checkpoint", "task50", "help", "gadget", "score50" }), "Recovered special hook ordering"); +Check(events.SequenceEqual(new[] { "checkpoint", "objective2", "task50", "help", "gadget", "score50" }), "Recovered special hook ordering"); Check(interactions.Snapshot().ItemStates[301] == 1 && interactions.CurrentObjective == 2, "Acquired state and objective2 persist"); interactions.Update(shrinkray.Position); -Check(interactions.Score == 50 && events.Count == 5, "Repeated overlap cannot recollect"); +Check(interactions.Score == 50 && events.Count == 6, "Repeated overlap cannot recollect"); Console.WriteLine("PASS source intro/explanation/shrinkray state, inventory and event ordering"); var carl = director.FindActor("C3DCARL")!; @@ -69,7 +81,7 @@ Check(decoded.InventoryStates[3] == 1 && decoded.ItemStates[301] == 1 && decoded Check(decoded.StoredVector == original.StoredVector, "Pickup42AF00 does not overwrite the separate saved transition root"); var restoredTasks = new TaskStates(decoded.Tasks); var restoredDirector = new SceneDirector(lab, restoredTasks, (_, _) => 5); -var restored = new SceneInteractions(restoredDirector, restoredTasks, decoded, lab.Code); +var restored = new SceneInteractions(restoredDirector, restoredTasks, decoded); restoredDirector.Begin(lab.FindStart()!); restored.Reset(); restoredDirector.Skip(); Check(!restoredDirector.FindActor("shrinkray")!.Active && restored.Inventory.State(0, 3) == 1, "Resume retains collected shrinkray/inventory"); restored.Update(restoredDirector.FindActor("shrinkray")!.Position); @@ -82,7 +94,7 @@ foreach (var state in new[] { 30, 36, 50 }) { var boundaryTasks = new TaskStates(original.Tasks.Select(t => t.Name == "SCENE" ? t with { State = state } : t)); var boundaryDirector = new SceneDirector(lab, boundaryTasks, (_, _) => 1); - var boundary = new SceneInteractions(boundaryDirector, boundaryTasks, original, lab.Code); + var boundary = new SceneInteractions(boundaryDirector, boundaryTasks, original); boundary.Update(boundaryDirector.FindActor("shrinkray")!.Position); Check(boundaryTasks.Get("SCENE") == state && boundary.Inventory.State(0, 3) == 0 && boundary.Score == 50, "Shrinkray special effect exact task35 gate, ordinary score remains"); @@ -100,7 +112,7 @@ foreach (var talkState in new[] { -1, -2, 50, 49 }) ("TalkState2", -2), ("TalkTrigger2", "fallback")); var testTasks = new TaskStates([new("SCENE", 50)]); var testDirector = new SceneDirector(new("TEST", [body, friend, camera0, camera1]), testTasks, (_, _) => 5); - var test = new SceneInteractions(testDirector, testTasks, original, "TEST"); + var test = new SceneInteractions(testDirector, testTasks, original); test.Update(Vector3.Zero); Check(testDirector.CurrentTag == (talkState is -2 or 50 ? "first" : "fallback"), "First existing match/wildcard; -1 disabled, missing target skipped"); Check(testTasks.Get("SCENE") == 60 && test.Score == 100, "Selected trigger alone invokes Carl callback"); @@ -109,7 +121,7 @@ var noneFriend = Entity("3CAR", "friend", ("AIState", 6), ("TargetName", "jim"), ("TalkState0", 49), ("TalkTrigger0", "first")); var noTasks = new TaskStates([new("SCENE", 50)]); var noDirector = new SceneDirector(new("TEST", [body, noneFriend, camera0]), noTasks, (_, _) => 5); -var noTalk = new SceneInteractions(noDirector, noTasks, original, "TEST"); +var noTalk = new SceneInteractions(noDirector, noTasks, original); noTalk.Update(Vector3.Zero); Check(noTasks.Get("SCENE") == 50 && noTalk.Score == 0 && noDirector.FindActor("friend")!.AIstate == 0, "No matching talk target leaves state0 without award/task mutation"); @@ -121,13 +133,13 @@ foreach (var distance in new[] { 160f, 159.5f }) ("TalkState0", 50), ("TalkTrigger0", "first")); var edgeTasks = new TaskStates([new("SCENE", 50)]); var edgeDirector = new SceneDirector(new("TEST", [body, friend, camera0]), edgeTasks, (_, _) => 5); - var edge = new SceneInteractions(edgeDirector, edgeTasks, original, "TEST"); + var edge = new SceneInteractions(edgeDirector, edgeTasks, original); edge.Update(new(distance, 0, 0)); Check(edge.Score == (distance < 160 ? 100 : 0), "Strict original sum-radius Carl contact boundary"); } var waiting = new SceneDirector(lab, new TaskStates(original.Tasks), (_, _) => 5); waiting.Begin(lab.FindStart()!); -var locked = new SceneInteractions(waiting, new TaskStates(original.Tasks), original, lab.Code); +var locked = new SceneInteractions(waiting, new TaskStates(original.Tasks), original); locked.Update(waiting.FindActor("shrinkray")!.Position); Check(locked.Score == 0 && locked.Snapshot().ItemStates[301] == 0, "Noncontrolled intro cannot collect pickups"); Console.WriteLine("PASS strict recovered Carl radius boundary and active-player control gate"); diff --git a/tests/GamePort.LabRouteTests/Program.cs b/tests/GamePort.LabRouteTests/Program.cs index e9e39cd..bf01f10 100644 --- a/tests/GamePort.LabRouteTests/Program.cs +++ b/tests/GamePort.LabRouteTests/Program.cs @@ -14,7 +14,7 @@ var save = OriginalSave.Load(Path.Combine(original, "NewGame.tsk")); var tasks = new TaskStates(save.Tasks); var resources = new PreparedEntityResources(Path.Combine(prepared, "level1b/entities/entities.json")); var director = new SceneDirector(level, tasks, resources.Duration); -var interactions = new SceneInteractions(director, tasks, save, level.Code); +var interactions = new SceneInteractions(director, tasks, save); var mechanisms = new SceneMechanisms(director); var visuals = new StaticSceneVisuals(world, director, original, Path.Combine(prepared, "level1b/models")); var simulation = new LabSimulation(new SceneCollision(world), AseMesh.Load(AssetPath.Resolve(original, "ASE/jimstop.ase")), diff --git a/tests/GamePort.UndergroundRouteTests/Program.cs b/tests/GamePort.UndergroundRouteTests/Program.cs index cc61a47..e3631e7 100644 --- a/tests/GamePort.UndergroundRouteTests/Program.cs +++ b/tests/GamePort.UndergroundRouteTests/Program.cs @@ -16,7 +16,7 @@ var tasks = new TaskStates(save.Tasks); tasks.SetExisting("SCENE", 65); var resources = new PreparedEntityResources(Path.Combine(prepared, "level1b/entities/entities.json")); var director = new SceneDirector(level, tasks, resources.Duration); -var interactions = new SceneInteractions(director, tasks, save, level.Code); +var interactions = new SceneInteractions(director, tasks, save); var mechanisms = new SceneMechanisms(director); var visuals = new StaticSceneVisuals(world, director, original, Path.Combine(prepared, "level1b/models")); var simulation = new LabSimulation(new SceneCollision(world), AseMesh.Load(AssetPath.Resolve(original, "ASE/jimstop.ase")), diff --git a/tests/test_checkpoint_camera_audio_ui.py b/tests/test_checkpoint_camera_audio_ui.py new file mode 100644 index 0000000..9a7e8dc --- /dev/null +++ b/tests/test_checkpoint_camera_audio_ui.py @@ -0,0 +1,32 @@ +"""Immutable PE contract and bounded recovered camera algebra checks.""" +import importlib.util +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools' / 'binary')) +spec = importlib.util.spec_from_file_location('checkpoint_camera_audio_ui', + ROOT / 'tools' / 'binary' / 'checkpoint_camera_audio_ui.py') +checkpoint = importlib.util.module_from_spec(spec) +spec.loader.exec_module(checkpoint) + + +class CameraAudioUiCheckpointTests(unittest.TestCase): + def test_original_contract_and_offsets(self): + result = checkpoint.recover(ROOT.parent / 'Original') + self.assertEqual(len(checkpoint.ANCHORS), len(result['anchors'])) + self.assertEqual(len(checkpoint.CONSTANTS), len(result['constants'])) + for entry in result['anchors'] + result['constants']: + self.assertEqual(int(entry['va'], 16) - 0x400000, int(entry['file_offset'], 16)) + self.assertTrue(all(g['file_offset'] is None for g in result['globals'])) + + def test_ray_adjustment_toward_look_point(self): + self.assertEqual((0, 25, 75), checkpoint.obstructed_eye((0, 100, 0), (0, 0, 100))) + self.assertEqual((5, -4, 3), checkpoint.obstructed_eye((5, -4, 3), (5, -4, 3))) + # Translation must not affect the weighting; this guards point vs direction confusion. + self.assertEqual((100, 125, 175), checkpoint.obstructed_eye((100, 200, 100), (100, 100, 200))) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_checkpoint_camera_ray.py b/tests/test_checkpoint_camera_ray.py new file mode 100644 index 0000000..8203e50 --- /dev/null +++ b/tests/test_checkpoint_camera_ray.py @@ -0,0 +1,59 @@ +"""Source camera predicate priorities/order, including deliberately non-nearest hits.""" +import importlib.util +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools' / 'binary')) +spec = importlib.util.spec_from_file_location('checkpoint_camera_ray', + ROOT / 'tools' / 'binary' / 'checkpoint_camera_ray.py') +ray = importlib.util.module_from_spec(spec) +spec.loader.exec_module(ray) + + +class CameraRayCheckpointTests(unittest.TestCase): + def test_source_and_route_data(self): + data = ray.recover(ROOT.parent / 'Original') + self.assertEqual(len(ray.ANCHORS), len(data['anchors'])) + expected = {'level1b.omt': (2851, 2483, 18), 'VR04.omt': (508, 420, 0), + 'level1.omt': (5231, 3860, 24)} + for name, (polygons, walls, excluded) in expected.items(): + entry = data['route_geometry'][name] + self.assertEqual({3: polygons}, entry['registered_polygon_corner_counts']) + self.assertEqual(walls, entry['wall_grid_polygons']) + self.assertEqual(excluded, entry['nc_polygons_excluded']) + self.assertEqual(0, entry['checkpoint_polygons_excluded']) + self.assertTrue(entry['shape_ids_ascending']) + + def test_grid_rectangle_order_and_negative_truncation(self): + self.assertEqual(129, ray.cell_coordinate(-1)) + self.assertEqual(130, ray.cell_coordinate(0)) + expected = [(130, 130), (130, 131), (131, 130), (131, 131)] + self.assertEqual(expected, list(ray.cells_between((0, 0, 0), (501, 0, 501)))) + self.assertEqual(expected, list(ray.cells_between((501, 100, 501), (0, -100, 0)))) + self.assertEqual([], list(ray.cells_between((1e6, 0, 1e6), (1e6, 0, 1e6)))) + + def test_first_wall_hit_overrides_nearer_all_grid_hit(self): + wall = {(130, 130): ['far', 'near']} + all_grid = {(130, 130): ['nearest_floor']} + distances = {'far': 80, 'near': 20, 'nearest_floor': 10} + query = lambda p, a, b, sides: distances[p] + self.assertEqual(('far', 80), ray.first_hit((0, 0, 0), (100, 0, 0), wall, all_grid, query)) + + def test_cell_priority_duplicate_tests_fallback_and_gate(self): + seen = [] + wall = {(130, 130): ['miss'], (130, 131): ['miss']} + all_grid = {(130, 130): ['hit']} + def accept(p, start, end, sides): + seen.append((p, sides)) + return 1 if p == 'hit' else None + self.assertEqual(('hit', 1), ray.first_hit((0, 0, 0), (0, 0, 501), wall, all_grid, accept)) + self.assertEqual([('miss', False), ('miss', False), ('hit', False)], seen) + seen.clear() + self.assertIsNone(ray.first_hit((0, 0, 0), (0, 0, 501), wall, all_grid, accept, enabled=False)) + self.assertEqual([], seen) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_checkpoint_input_frame.py b/tests/test_checkpoint_input_frame.py new file mode 100644 index 0000000..e4961c8 --- /dev/null +++ b/tests/test_checkpoint_input_frame.py @@ -0,0 +1,28 @@ +"""Regress the actual binary bridge, not a guessed phase-order simulation.""" +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools' / 'binary')) +from checkpoint_input_frame import collect, SLOTS, CALLS + + +class InputFrameEvidenceTests(unittest.TestCase): + def test_original_dispatch_and_timer_evidence(self): + original = ROOT.parent / 'Original' + if not (original / 'Neutron.exe').exists(): + self.skipTest('Original evidence is local-only and absent') + report = collect(original) + self.assertEqual(len(report['evidence']), 30) + self.assertEqual(len(SLOTS), 8) + self.assertEqual(len(CALLS), 6) + + def test_physics_precedes_registry_in_same_viewport_override(self): + sites = {label: va for va, _, label in CALLS} + self.assertLess(sites['physics'], sites['all game objects']) + self.assertLess(sites['all game objects'], sites['all logical-to-visual transforms']) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_checkpoint_lab_registry.py b/tests/test_checkpoint_lab_registry.py new file mode 100644 index 0000000..257795b --- /dev/null +++ b/tests/test_checkpoint_lab_registry.py @@ -0,0 +1,26 @@ +"""Original-source construction boundaries for the scheduler checkpoint.""" +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools' / 'binary')) +from checkpoint_lab_registry import collect, ANCHORS, CALLS, SLOTS + + +class LabRegistryEvidenceTests(unittest.TestCase): + def test_original_lab_construction_trace(self): + original = ROOT.parent / 'Original' + if not (original / 'Neutron.exe').exists(): + self.skipTest('Local original files absent') + report = collect(original) + self.assertEqual(len(report['evidence']), len(ANCHORS) + len(CALLS) + len(SLOTS)) + self.assertEqual(report['lab']['code'], 'LV1B') + self.assertEqual(report['lab']['entities'], 129) + self.assertEqual(report['lab']['first_record'], dict(kind='3JIM', offset='0x8', tag='JIM1')) + self.assertEqual(report['lab']['serialized_goddards'], 0) + self.assertIn('Retained/reused', report['boundary']) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_checkpoint_loop_motion.py b/tests/test_checkpoint_loop_motion.py new file mode 100644 index 0000000..bfaedc0 --- /dev/null +++ b/tests/test_checkpoint_loop_motion.py @@ -0,0 +1,25 @@ +import importlib.util +from pathlib import Path +import sys +import unittest + +PROJECT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(PROJECT / 'tools/binary')) +from checkpoint_loop_motion import recover + + +class CheckpointLoopEvidence(unittest.TestCase): + def test_original_frame_and_registry_anchors(self): + evidence = recover(PROJECT.parent / 'Original') + self.assertEqual([x['target'] for x in evidence['calls']], + ['0x479bc0', '0x462a20', '0x4693a0', '0x47d8f0', + '0x473740', '0x473770', '0x477db0']) + self.assertEqual(evidence['viewport_slot_b8']['target'], '0x47e4f0') + self.assertEqual(len(evidence['anchors']), 11) + for item in evidence['calls'] + evidence['anchors']: + self.assertEqual(int(item['va'], 16) - 0x400000, + int(item['file_offset'], 16)) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_checkpoint_scene_loader.py b/tests/test_checkpoint_scene_loader.py new file mode 100644 index 0000000..9f6bc41 --- /dev/null +++ b/tests/test_checkpoint_scene_loader.py @@ -0,0 +1,57 @@ +"""Static evidence guards; no original executable is launched.""" +import importlib.util +from pathlib import Path +import unittest + +ROOT = Path(__file__).resolve().parents[1] +SPEC = importlib.util.spec_from_file_location( + "checkpoint_scene_loader", ROOT / "tools/binary/checkpoint_scene_loader.py") +loader = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(loader) + + +class SceneLoaderEvidenceTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.report = loader.collect(ROOT.parent / "Original") + + def test_exact_original_sites_and_receiver_vtables(self): + self.assertTrue(self.report["known_binary"]) + for site in self.report["sites"] + self.report["vtables"]: + with self.subTest(site=site["name"]): + self.assertTrue(site["matches"], site) + + def test_pending_game_load_and_tsk_load_are_different_owners(self): + tables = {t["name"]: t["target"] for t in self.report["vtables"]} + self.assertEqual(tables["editor request load"], "0x46df70") + self.assertEqual(tables["editor consume load"], "0x46dff0") + self.assertEqual(tables["editor load GAM"], "0x46e170") + self.assertEqual(tables["editor reset/postload"], "0x46e570") + self.assertEqual(tables["Jimmy placement PostLoad"], "0x423610") + + def test_reset_is_R_input_not_serialized_loader_flag(self): + self.assertEqual(self.report["acquired_reset_virtual_key"], ord("R")) + sites = {s["name"]: s for s in self.report["sites"]} + self.assertEqual(sites["acquired_reset_count"]["actual"], "b968100000") #4200 dwords + self.assertEqual(sites["jimmy_constructor_flag"]["direct_call_target"], "0x470f40") + self.assertEqual(sites["goddard_constructor_flag"]["direct_call_target"], "0x470f40") + self.assertEqual(sites["jimmy_constructor_reusable"]["actual"], "c685c900000001") + self.assertEqual(sites["goddard_constructor_reusable"]["actual"], "c686c900000001") + + def test_factory_destruction_and_timer_dependencies(self): + sites = {s["name"]: s for s in self.report["sites"]} + self.assertEqual(sites["object_factory"]["direct_call_target"], "0x459cb0") + self.assertEqual(sites["teardown_delete_sweep"]["direct_call_target"], "0x473710") + self.assertEqual(sites["registry_timer_reset"]["direct_call_target"], "0x47e470") + + def test_game_constructor_and_prefix_do_not_identify_old_game_removal(self): + sites = {s["name"]: s for s in self.report["sites"]} + self.assertEqual(sites["load_prefix_caption_cleanup"]["direct_call_target"], "0x4766e0") + self.assertEqual(sites["load_prefix_physics_cleanup"]["direct_call_target"], "0x479000") + self.assertEqual(sites["lab_constructor_base"]["direct_call_target"], "0x44d2b0") + self.assertEqual(sites["game_constructor_base"]["direct_call_target"], "0x4745a0") + self.assertEqual(sites["game_constructor_clear_control"]["direct_call_target"], "0x475a40") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_checkpoint_script_state.py b/tests/test_checkpoint_script_state.py new file mode 100644 index 0000000..4d0d7f4 --- /dev/null +++ b/tests/test_checkpoint_script_state.py @@ -0,0 +1,60 @@ +"""Original-data evidence for task ordering and separate transition state.""" +import importlib.util +from pathlib import Path +import unittest + +ROOT = Path(__file__).resolve().parents[1] +SPEC = importlib.util.spec_from_file_location( + "checkpoint_script_state", ROOT / "tools/binary/checkpoint_script_state.py") +evidence = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(evidence) + + +class ScriptStateEvidenceTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.original = ROOT.parent / "Original" + cls.report = evidence.collect(cls.original) + + def test_binary_identity_sites_and_virtual_call_provenance(self): + self.assertTrue(self.report["known_binary"]) + for site in self.report["sites"] + self.report["vtables"]: + with self.subTest(site=site["name"]): + self.assertTrue(site["matches"], site) + + def test_objective_record_and_actor_call_order(self): + sites = {s["name"]: s for s in self.report["sites"]} + names = ["task_objective_before_records", "task_record_mutation", "task_entity_callback"] + self.assertEqual([int(sites[n]["va"], 16) for n in names], [0x45FB5B, 0x45FB7F, 0x45FBD9]) + self.assertEqual(sites[names[0]]["direct_call_target"], "0x406f50") + self.assertEqual(sites["carl_query_scene"]["direct_call_target"], "0x45fea0") + self.assertEqual(sites["carl_generic_callback"]["direct_call_target"], "0x40e340") + + def test_tsk_rebroadcast_and_deferred_load(self): + sites = {s["name"]: s for s in self.report["sites"]} + self.assertEqual(sites["tsk_setter_call"]["direct_call_target"], "0x45f990") + self.assertEqual(sites["load_update_reader"]["direct_call_target"], "0x4603f0") + # Slot420 is not Jimmy's placement PostLoad: its actual target matters. + slots = {s["name"]: s["target"] for s in self.report["vtables"]} + self.assertEqual(slots["Jimmy game post-task hook"], "0x472970") + + def test_route_keeps_return_distinct_from_outside(self): + lab, tutorial = self.report["route"] + self.assertEqual((lab["code"], tutorial["code"]), ("LV1B", "VR04")) + exits = [e["fields"] for e in lab["entities"] if e["kind"] == "LOAD"] + self.assertTrue(any(e.get("LevelName", "").casefold() == "level1.gam" + and e.get("StartPoint", "").casefold() == "level1" + and e.get("RequiredLevel") == 60 for e in exits)) + self.assertTrue(any(e["fields"].get("LevelName", "").casefold() == "return" + for e in tutorial["entities"])) + + def test_non_call_and_negative_read_rejected(self): + pe = evidence.PE(evidence.find_case(self.original, "neutron.exe")) + with self.assertRaises(ValueError): + evidence.rel_call_target(pe, 0x45FB7F) + with self.assertRaises(ValueError): + evidence.read_va(pe, 0x45FB7F, -1) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_checkpoint_voice_clock.py b/tests/test_checkpoint_voice_clock.py new file mode 100644 index 0000000..ff1b11e --- /dev/null +++ b/tests/test_checkpoint_voice_clock.py @@ -0,0 +1,19 @@ +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools/binary')) +from checkpoint_voice_clock import collect + + +class VoiceClockEvidenceTests(unittest.TestCase): + def test_original_voice_uses_software_time_and_repeat(self): + report = collect(ROOT.parent / 'Original') + self.assertEqual(len(report['vtables']), 3) + self.assertEqual(len(report['anchors']), 12) + self.assertEqual([c['value'] for c in report['constants']], [.5, 1000.0]) + + +if __name__ == '__main__': + unittest.main() diff --git a/tools/binary/checkpoint_camera_audio_ui.py b/tools/binary/checkpoint_camera_audio_ui.py new file mode 100644 index 0000000..8924197 --- /dev/null +++ b/tools/binary/checkpoint_camera_audio_ui.py @@ -0,0 +1,106 @@ +#!/usr/bin/env python3 +"""Read-only camera/audio/UI checkpoint anchors, with PE-mapped offsets. + +Run from GamePort: python3 tools/binary/checkpoint_camera_audio_ui.py ../Original +This checks immutable source instructions; it neither executes nor writes originals. +""" +import argparse +import hashlib +import json +from pathlib import Path +import struct + +from pe_inspect import PE + +EXE_SHA256 = 'f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8' +DLL_SHA256 = '3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943' + +# Deliberately selected instruction sequences, rather than matching whole functions. +ANCHORS = ( + ('follow_default_eye_y200', 0x437742, 'c781cc07000000004843'), + ('follow_virtual_ray_callback', 0x439714, 'ff966c010000'), + ('follow_x_gain', 0x4397B1, 'd88d54080000d84c2414d88c2480000000'), + ('follow_y_extra_gain', 0x4397C2, 'd98558080000dc05d02a4a00'), + ('follow_viewport_position', 0x4397F8, 'a1509a5000'), + ('follow_ray_call', 0x43B874, 'e897090400'), + ('follow_hit_adjustment', 0x43B8AD, 'd826d80dacd54900'), + ('follow_hit_gain', 0x43B8F7, 'd90538314a00'), + ('jimmy_complete_vtable_ray_slot', 0x4A3D48, '20b84300'), + ('cam_interface_update_slot', 0x497FC0, '905f4100'), + ('cam_complete_activate_slot', 0x498138, 'a0654100'), + ('mca_interface_update_slot', 0x4A9328, 'a00d4300'), + ('mca_complete_activate_slot', 0x4A94A0, '80124300'), + ('default_local_eye', 0x447E2F, '680000fac3680000fa43'), + ('default_snap_threshold', 0x447E9D, 'd81dace54800dfe0f6c441'), + ('default_snap_store', 0x447EAA, 'd95944'), + ('cam_voice_poll', 0x415FC2, '8b8eb408000051e8c2780600'), + ('cam_music_bank', 0x416776, 'a104606900'), + ('cam_effect_bank_release_gate', 0x416813, '891d08606900881d34844f00'), + ('mca_effect_bank_release_gate', 0x4315C2, '891d08606900881d34844f00'), + ('default_effect_bank_restore_gate', 0x447F64, 'a30860690085c07406881d34844f00'), + ('voice_duration_and_repeat_flag', 0x47D8CB, 'ff50148b44240c85c075078a463084c07405'), + ('ui_dispatch_base_first', 0x404080, '83ec1453558b6c242056578bf155e8adf10600'), + ('ui_controlled_clock_then_draw', 0x4043D9, + '391de49950000f8495000000d90588814f00d84424288bced91d88814f008b16ff92d0040000'), + ('modal_pause_game', 0x407022, '8b0d48995000538b01ff9068010000'), +) + +CONSTANTS = ( + ('default_snap_distance', 0x48E5AC, 'f', 1000.0), + ('ray_hit_weight', 0x49D5AC, 'f', .75), + ('ray_hit_follow_gain', 0x4A3138, 'f', 1.5), + ('follow_y_gain_extra', 0x4A2AD0, 'd', .2), + ('special_eye_state_threshold', 0x495338, 'd', 1.7), + ('special_eye_back_multiplier', 0x4AFCF0, 'd', 3.7), + ('look_target_height_multiplier', 0x4AFCE8, 'd', 1.9), +) + +GLOBALS = (('viewport', 0x509A50), ('controlled', 0x5099E4), + ('music_database', 0x696004), ('current_wave_database', 0x696008), + ('sound_engine', 0x69600C), ('default_positional_sfx_gate', 0x4F8434), + ('objective_timer', 0x4F8188), ('objective_selector', 0x4F8194), + ('modal_active', 0x4F8198), ('modal_type', 0x4F8048)) + + +def recover(original): + original = Path(original) + pe = PE(original / 'Neutron.exe') + exe_hash = hashlib.sha256(pe.data).hexdigest() + dll_hash = hashlib.sha256((original / 'OMT2.dll').read_bytes()).hexdigest() + if exe_hash != EXE_SHA256 or dll_hash != DLL_SHA256: + raise ValueError('Unrecognized original module hash; do not apply preferred-VA evidence') + result = {'module_hashes': {'Neutron.exe': exe_hash, 'OMT2.dll': dll_hash}, + 'anchors': [], 'constants': [], 'globals': []} + for name, va, expected in ANCHORS: + off = pe.offset(va - pe.base) + actual = pe.data[off:off + len(bytes.fromhex(expected))].hex() + if actual != expected: + raise ValueError(f'{name}: expected instruction bytes differ at {va:#x}') + result['anchors'].append({'name': name, 'va': hex(va), + 'file_offset': hex(off), 'bytes': actual}) + for name, va, fmt, expected in CONSTANTS: + off = pe.offset(va - pe.base) + actual = struct.unpack_from('<' + fmt, pe.data, off)[0] + if actual != expected: + raise ValueError(f'{name}: constant differs') + result['constants'].append({'name': name, 'va': hex(va), + 'file_offset': hex(off), 'value': actual, 'format': fmt}) + for name, va in GLOBALS: + try: + off = hex(pe.offset(va - pe.base)) + except ValueError: + off = None # PE zero-fill; a VA is not automatically a physical file offset. + result['globals'].append({'name': name, 'va': hex(va), 'file_offset': off}) + return result + + +def obstructed_eye(look, hit): + """43B8AD..43B8F4 algebra, independent of unrecovered ray layer/filter rules.""" + return tuple(a - (a - b) * .75 for a, b in zip(look, hit, strict=True)) + + +if __name__ == '__main__': + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('original', type=Path) + args = parser.parse_args() + print(json.dumps(recover(args.original), indent=2)) diff --git a/tools/binary/checkpoint_camera_ray.py b/tools/binary/checkpoint_camera_ray.py new file mode 100644 index 0000000..5cb676b --- /dev/null +++ b/tools/binary/checkpoint_camera_ray.py @@ -0,0 +1,156 @@ +#!/usr/bin/env python3 +"""Read-only C5 ray evidence and bounded grid-order reference (not runtime code).""" +import argparse +from collections import Counter +import hashlib +import json +import math +from pathlib import Path +import struct +import sys + +from pe_inspect import PE + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'extractors')) +from omt import Database, read_shape + +EXE_HASH = 'f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8' +CELL_SCALE = struct.unpack(' dict: + pe = PE(find_case(root, "Neutron.exe")) + sites = [] + for name, va, expected in SITES: + actual = read_va(pe, va, len(bytes.fromhex(expected))).hex() + item = dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)), + expected=expected, actual=actual, matches=actual == expected) + if actual.startswith("e8"): + item["direct_call_target"] = hex(rel_call_target(pe, va)) + sites.append(item) + tables = [] + for name, table, slot, expected in VTABLES: + target = struct.unpack(" None: + cli = argparse.ArgumentParser(description=__doc__) + cli.add_argument("original", type=Path) + result = collect(cli.parse_args().original) + print(json.dumps(result, indent=2)) + if not result["known_binary"] or not all(s["matches"] for s in result["sites"] + result["vtables"]): + raise SystemExit(1) + + +if __name__ == "__main__": + main() diff --git a/tools/binary/checkpoint_script_state.py b/tools/binary/checkpoint_script_state.py new file mode 100644 index 0000000..94b05ce --- /dev/null +++ b/tools/binary/checkpoint_script_state.py @@ -0,0 +1,144 @@ +#!/usr/bin/env python3 +"""Read-only script/task/RETURN checkpoint evidence from the supplied originals. + +Reports preferred-base VAs, PE-mapped file offsets, exact bytes and dependencies. +No original code is executed. Assertions establish the inspected binary identity +and call/field provenance, not original-game runtime behavior. +""" +from __future__ import annotations + +import argparse +import hashlib +import json +from pathlib import Path +import struct +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "levels")) +from pe_inspect import PE +import gam + +EXE_SHA256 = "f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8" + +# Small decisive sites, independently checked against objdump. Offsets are never +# assumed to equal RVA: PE.offset performs the actual section mapping. +SITES = ( + ("task_objective_before_records", 0x45FB5B, "e8f073faff"), + ("task_record_mutation", 0x45FB7F, "895f64"), + ("task_entity_callback", 0x45FBD9, "ff9024040000"), + ("carl_query_scene", 0x413F3D, "e85ebf0400"), + ("carl_generic_callback", 0x413F4E, "e8eda3ffff"), + ("carl_lab_derived_branch", 0x414068, "85db0f8c9800000083fb3c"), + ("carl_marker_state", 0x4140AA, "6a06ff9024010000"), + ("carl_marker_root", 0x4140E0, "ff9214030000"), + ("pickup_checkpoint_level", 0x42AF1B, "898e481e0000"), + ("pickup_checkpoint_root", 0x42AF30, "81c6381e0000"), + ("stage_preserve_test", 0x43B78E, "8a83a509000084c07537"), + ("stage_root_write", 0x43B7B1, "8d8ba8090000"), + ("stage_game_load_request", 0x43B7F1, "ff9200010000"), + ("return_suppress_start", 0x458014, "889054090000"), + ("return_preserve_root", 0x458028, "8890a5090000"), + ("return_stage_dispatch", 0x45815C, "ff9268010000"), + ("scene_postload_dispatch", 0x46E61A, "ff920c040000"), + ("jimmy_postload_return_root", 0x423ABF, "ff926c010000"), + ("jimmy_postload_control", 0x423B3D, "ff9218010000"), + ("tsk_setter_call", 0x460CE2, "e8a9ecffff"), + ("tsk_second_matching_callback", 0x460D2E, "ff9024040000"), + ("tsk_all_entity_420", 0x460D87, "ff9220040000"), + ("load_request_pending", 0x460E7B, "c6057cc64f0001"), + ("load_update_reader", 0x460EF0, "e8fbf4ffff"), + ("load_update_clear_pending", 0x460EF8, "c6057cc64f0000"), +) + +VTABLES = ( + ("Jimmy complete transition", 0x4A3BDC, 0x168, 0x43B5A0), + ("Jimmy complete pickup capture", 0x4A3BDC, 0x1E8, 0x42AF00), + ("Jimmy complete capture/effect", 0x4A3BDC, 0x1EC, 0x42AF50), + ("Carl game task callback", 0x495364, 0x424, 0x413F30), + ("Carl game post-task hook", 0x495364, 0x420, 0x413EB0), + ("Jimmy game post-task hook", 0x4A373C, 0x420, 0x472970), + ("Jimmy game placement PostLoad", 0x4A373C, 0x40C, 0x423610), + ("LOAD game task callback", 0x4D025C, 0x424, 0x458880), +) + + +def find_case(root: Path, relative: str) -> Path: + current = root + for component in Path(relative).parts: + matches = [p for p in current.iterdir() if p.name.casefold() == component.casefold()] + if len(matches) != 1: + raise ValueError(f"missing or ambiguous original path: {relative}") + current = matches[0] + return current + + +def read_va(pe: PE, va: int, size: int) -> bytes: + if size < 0: + raise ValueError("negative byte count") + start = pe.offset(va - pe.base) + if size and pe.offset(va + size - 1 - pe.base) != start + size - 1: + raise ValueError("VA range is not contiguous file data") + result = pe.data[start:start + size] + if len(result) != size: + raise ValueError("truncated VA range") + return result + + +def rel_call_target(pe: PE, va: int) -> int: + raw = read_va(pe, va, 5) + if raw[0] != 0xE8: + raise ValueError(f"not a direct relative call at {va:#x}") + return va + 5 + struct.unpack_from(" dict: + pe = PE(find_case(root, "Neutron.exe")) + digest = hashlib.sha256(pe.data).hexdigest() + sites = [] + for name, va, expected in SITES: + actual = read_va(pe, va, len(bytes.fromhex(expected))).hex() + site = dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)), + expected=expected, actual=actual, matches=actual == expected) + if actual.startswith("e8"): + site["direct_call_target"] = hex(rel_call_target(pe, va)) + sites.append(site) + vtables = [] + for name, table, slot, expected in VTABLES: + va = table + slot + actual = struct.unpack(" None: + cli = argparse.ArgumentParser(description=__doc__) + cli.add_argument("original", type=Path) + args = cli.parse_args() + result = collect(args.original) + print(json.dumps(result, indent=2, allow_nan=False)) + if not result["known_binary"] or not all(s["matches"] for s in result["sites"] + result["vtables"]): + raise SystemExit(1) + + +if __name__ == "__main__": + main() diff --git a/tools/binary/checkpoint_voice_clock.py b/tools/binary/checkpoint_voice_clock.py new file mode 100644 index 0000000..d16a0c6 --- /dev/null +++ b/tools/binary/checkpoint_voice_clock.py @@ -0,0 +1,60 @@ +#!/usr/bin/env python3 +"""Read-only evidence: sound completion uses inherited software timing, not GetStatus.""" +import argparse +import hashlib +import json +from pathlib import Path +import struct + +from pe_inspect import PE +from checkpoint_camera_audio_ui import EXE_SHA256, DLL_SHA256 + +ANCHORS = [ + (0x10071E50, '8b461c85c0', 'duration field guards status'), + (0x10071E65, 'e8866e0800', 'status uses engine millisecond clock'), + (0x10071E7C, '8b4e1c3bc17602b301', 'strict elapsed greater than duration expires'), + (0x10071E87, '890f', 'second output is duration, not hardware status'), + (0x1003B32B, '8a9c24f4000000', 'DX repeat argument'), + (0x1003B338, '84db0f95c1516a006a0057ff5030', 'repeat boolean sent to buffer play flags'), + (0x1003B46B, '885e30', 'DX stores repeat flag at30'), + (0x1003B46E, 'd94544dc0d50541110dc0548541110', 'sound duration seconds times1000 plus.5'), + (0x1003B657, '885f30895f1c', 'DX stop clears repeat and duration'), + (0x100F8893, '8a5c2424', 'Win repeat argument'), + (0x100F8917, '885e30', 'Win stores repeat flag at30'), + (0x100F8996, 'c6463000', 'Win stop clears repeat'), +] + + +def collect(original): + original = Path(original) + dll = PE(original / 'OMT2.dll') + exe = PE(original / 'Neutron.exe') + if hashlib.sha256(dll.data).hexdigest() != DLL_SHA256 or hashlib.sha256(exe.data).hexdigest() != EXE_SHA256: + raise ValueError('Unsupported original identity') + result = {'anchors': [], 'vtables': [], 'constants': []} + for va, expected, label in ANCHORS: + off = dll.offset(va - dll.base) + raw = bytes.fromhex(expected) + if dll.data[off:off + len(raw)] != raw: + raise ValueError(f'Changed {label} at {va:#x}') + result['anchors'].append(dict(va=hex(va), file_offset=hex(off), bytes=expected, label=label)) + for table in [0x10115420, 0x1011629C, 0x10116B3C]: + va = table + 0x14 + off = dll.offset(va - dll.base) + target = dll.u32(off) + if target != 0x10071E40: + raise ValueError('SoundChannel slot14 no longer inherited software clock') + result['vtables'].append(dict(va=hex(va), file_offset=hex(off), target=hex(target))) + for va, expected in [(0x10115448, .5), (0x10115450, 1000.0)]: + off = dll.offset(va - dll.base) + actual = struct.unpack_from('