From 4cd62d362791f177ced35d206e7530e66d0c4f0a Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Fri, 6 Nov 2026 10:27:10 -0500 Subject: [PATCH] Trace Carl lifecycle and add read-only original state observer --- AGENTS.md | 8 + docs/checkpoint/coverage.md | 8 + docs/checkpoint/next-work-plan.md | 6 + docs/decisions.md | 9 + docs/gameplay/jimmy-base-return.md | 148 +++++++ docs/gameplay/jimmy-carl-entry.md | 84 ++++ docs/gameplay/jimmy-cutscene-decompilation.md | 9 + docs/gameplay/jimmy-cutscene-lifecycle.md | 85 ++++ docs/gameplay/jimmy-cutscene-return-source.md | 8 +- docs/gameplay/jimmy-default-decompilation.md | 60 +++ docs/gameplay/jimmy-skip-composition.md | 126 ++++++ docs/gameplay/jimmy-task-return.md | 153 +++++++ docs/gameplay/original-state-observer.md | 212 +++++++++ docs/progress.md | 19 +- docs/reference-testing.md | 20 + docs/tasks.md | 11 + tools/binary/default_raw_carrier.py | 59 +++ tools/binary/jimmy_base_return.py | 147 +++++++ tools/binary/jimmy_base_return_probe.c | 133 ++++++ tools/binary/jimmy_carl_entry.py | 142 ++++++ tools/binary/jimmy_carl_entry_probe.c | 64 +++ tools/binary/jimmy_skip_composition.py | 26 ++ tools/binary/jimmy_skip_composition_probe.c | 80 ++++ tools/binary/jimmy_task_return.py | 245 +++++++++++ tools/binary/jimmy_task_return_probe.c | 60 +++ tools/recon/original_observer_smoke.c | 43 ++ tools/recon/original_state_observer.c | 407 ++++++++++++++++++ tools/recon/reference_capture.py | 20 +- 28 files changed, 2387 insertions(+), 5 deletions(-) create mode 100644 docs/gameplay/jimmy-base-return.md create mode 100644 docs/gameplay/jimmy-carl-entry.md create mode 100644 docs/gameplay/jimmy-cutscene-lifecycle.md create mode 100644 docs/gameplay/jimmy-default-decompilation.md create mode 100644 docs/gameplay/jimmy-skip-composition.md create mode 100644 docs/gameplay/jimmy-task-return.md create mode 100644 docs/gameplay/original-state-observer.md create mode 100644 tools/binary/default_raw_carrier.py create mode 100644 tools/binary/jimmy_base_return.py create mode 100644 tools/binary/jimmy_base_return_probe.c create mode 100644 tools/binary/jimmy_carl_entry.py create mode 100644 tools/binary/jimmy_carl_entry_probe.c create mode 100644 tools/binary/jimmy_skip_composition.py create mode 100644 tools/binary/jimmy_skip_composition_probe.c create mode 100644 tools/binary/jimmy_task_return.py create mode 100644 tools/binary/jimmy_task_return_probe.c create mode 100644 tools/recon/original_observer_smoke.c create mode 100644 tools/recon/original_state_observer.c diff --git a/AGENTS.md b/AGENTS.md index d73d804..ce0e07a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,6 +46,14 @@ movement reset or scheduler change. See docs/gameplay/jimmy-cutscene-decompilati The broader priority remains Jimmy movement stabilization, with gadgets paused. Preserve current movement as baseline; do not substitute JN-Engine native/Godot movement. Use its original decompiler index only as leads, verified with REA/authoritative originals. See docs/gameplay/jimmy-movement-stabilization.md. + +2026-11-06 continuation: docs/gameplay/jimmy-cutscene-lifecycle.md records292 +new bounded original-code cases, mapped DEFAULT recovery and a read-only copied- +original launch/attach observer. No source-supported reset is established; actual +original Carl entry/return state remains the implementation gate. Wine32 observer +attach works but only MAIN/no Jimmy/black frames were observed locally. Preserve +runtime a2e89c6/packages dae13ac and normal landing bank. The user reiterates exact +original behavior; do not substitute a leveling reset or global scheduling change. The prior collision work is resumed where needed for movement; preserve the 35a2a66/0272f7b checkpoints and their source gates before broader body admission. Controller checkpoint integrates108 native ground/air/facing/jump comparisons; diff --git a/docs/checkpoint/coverage.md b/docs/checkpoint/coverage.md index 2b14976..ca68a48 100644 --- a/docs/checkpoint/coverage.md +++ b/docs/checkpoint/coverage.md @@ -1,5 +1,13 @@ # Core architecture coverage map +2026-11-06: [Carl lifecycle trace](../gameplay/jimmy-cutscene-lifecycle.md) adds +292 bounded original-code cases and closes local contact/task/animation/STOP and +DEFAULT-provider questions. Actual first-resumed-frame state remains unobserved. +The new original-state observer passes Wine32 attach/read/leave-running; local +original captures show MAIN only and remain visually unusable. This expands S/P +and investigation-tool coverage, not original gameplay comparison or a new port fix. +MOVE/CONTROL/INPUT's Carl gate and full-body/OMT dependencies stay open. + 2026-11-05 follow-up: camera-entry reset is verified, but post-skip neutral idle remains a port bug. CONTROL/INPUT/skip coverage is reopened around Carl's full lifecycle;48 port traces and additional original boundaries are documented in diff --git a/docs/checkpoint/next-work-plan.md b/docs/checkpoint/next-work-plan.md index 2314b06..fbcfedf 100644 --- a/docs/checkpoint/next-work-plan.md +++ b/docs/checkpoint/next-work-plan.md @@ -5,6 +5,12 @@ Gameplay expansion remains paused. Current research checkpoint68154df preserves runtime a2e89c6 and packaged runtime dae13ac. This plan does not mark the remaining post-skip tilt fixed or authorize an unsupported rotation reset. +Execution update2026-11-06: [integrated lifecycle findings](../gameplay/jimmy-cutscene-lifecycle.md) +add292 bounded original-code cases, complete DEFAULT recovery and a working +read-only copied-original observer. Steps1–2 remain open at the actual original +Carl entry/resumed-frame observation. Step3 has not begun; source composition +agrees with the port's stale writer under the same synthetic order/state. + ## Objective Establish the original ownership and timing of player state across gameplay, diff --git a/docs/decisions.md b/docs/decisions.md index f0ee716..3bb5766 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -364,3 +364,12 @@ assets and generated packages stay excluded. movement fields or changing the scheduler. Current source/component findings do not yet explain the whole-original upright return. See gameplay/jimmy-cutscene-decompilation.md for the recovery gate. + +53. **Observe the actual original handoff when composed source matches the port.** + 292 new bounded original-code cases do not establish another movement reset; + fresh input-before-player composition itself restores bank. Retain the user's + upright-original requirement without inventing an owner/DEFAULT/animation reset. + Use the copied-original read-only observer to measure actual route state and + registry membership. Its successful Wine32 attach is tool validation, while + MAIN-only black frames are not gameplay evidence. Keep runtime/packages fixed + until the source/differential gate closes. See gameplay/jimmy-cutscene-lifecycle.md. diff --git a/docs/gameplay/jimmy-base-return.md b/docs/gameplay/jimmy-base-return.md new file mode 100644 index 0000000..df5c052 --- /dev/null +++ b/docs/gameplay/jimmy-base-return.md @@ -0,0 +1,148 @@ +# Jimmy base, animation completion and STOP during cutscene return + +2026-11-06. Bounded original-code investigation of the dependencies omitted by +[the skip composition](jimmy-skip-composition.md). No runtime change or new +rotation reset is justified by these results. + +## Identity and evidence + +Original Neutron.exe SHA256 +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. +Retained complete REA instruction Evidence +`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904` +is reused and its subject hash verified. The helper verifies original identity, +virtual bindings and PE-maps the source ranges. Addresses below are preferred +EXE VAs; the listed text file offsets equal VA minus400000. + +JN-Engine's C3DAnimated/C3DPlayer/C3DJimmy reports supplied indexing leads. +The conclusions here come from authoritative bytes, retained REA instructions +and the bounded native execution, rather than its reconstructed movement. + +## Recovered base/update contract + +| Boundary / VA / file offset | Original ownership and effects | +|---|---| +|Jimmy424600..424D10 /24600..24D10|The ordinary derived frame callback eventually invokes437940 at424C34. Its null-control prelude handles helpers/menu/sound; the inspected function contains no direct mode704/turn614 reset. It also calls other Jimmy helpers; this is not a full execution proof of that frame.| +|43796A→40E050 /3796A→E050|Player wrapper invokes animated base **before** its raw-owner identity gate437A1B. Base behavior therefore remains relevant while raw control is null.| +|40E050..40E1C8 /E050..E1C8|Global readiness gate; one-time pickup-link work; common object update462520; optional authored-transform pin when game58C CanMove==0; animation clock/completion check. No direct movement-mode/turn reset. Actual lab JIM1 CanMove is1, as the earlier supplied-GAM investigation records.| +|462520..462649 /62520..62649|Optional body-context/current-root bridge, then458930→473240. A missing body context skips the former bridge but still reaches the common update.| +|473240..473298 /73240..73298|Calls game3D4→4732B0 to maintain sound handles, expiration callback if its timer expires, then game3D8→43A420 facing.| +|40E162..40E1C0 /E162..E1C0|Requires both game574/575 readiness bytes. Increments game4C4/complete584 clock. If completeAD play-loop is0 and game56C/complete62C record exists, current frame at least record48−1 calls complete104. There is no completion latch here.| +|complete4A3BDC+104→43A900 /A3CE0→3A900|Actual Jimmy animation-ended callback. Tests current action through complete100→40DF80. STOP, ordinary talk and FALL do nothing in this callback.| +|43A92E..43A9A9 /3A92E..3A9A9|FENCE/LADDER completion selects STOP, clears shared4F83E0 and special timer, invokes Stop, clears special movement fields, restores saved **position** through game314, and enables body state. No mode704/turn614 or Euler reset.| +|43A9CA..43AA38 /3A9CA..3AA38|SPLAT/HIT completion selects STOP; HIT additionally clears shared4F83E0/special timer. This is not an ordinary scene-return rotation reset.| + +The optional body-context bridge in462520 has not been exercised with a real +world/body here. Its current-root writes and any level callback side effects +remain a separate boundary; a null synthetic context must not establish their +absence in the whole original. + +## STOP is two different entry paths + +Script preparation's game410→42AFC0 is not the same entry as assigning a target +deactivation animation through completeE0: + +``` +game410 ->42AFC0 + ->43A750: speed608=0, velocity XYZ via2C4->471F40, sound148->429A00 + ->sound148->429A00 again + ->complete150->43AFF0("STOP"): action acceptance + ->completeE0->40DD90("STOP",1) if accepted + +TargetDeactAnim STOP ->completeE0->40DD90("STOP",1) directly +``` + +43AFF0 first rejects an unchanged current action and protected HIT/SPLAT/FENCE/ +LADDER/other special states; it then recognizes STOP at43B28A. Its accepted STOP +branch stops sound, selects the animation and clears acceleration through +game278. There is no mode/turn/Euler reset. A Stop call can therefore clear +speed/velocity while its STOP animation request is rejected. Direct animation +selection has a distinct acceptance boundary. + +| Selection dependency / VA / file offset | Recovered effects and limits | +|---|---| +|40DD90..40DF7C /DD90..DF7C|Requires complete634/635. Resets local animation clock; may bind the selected shape, call completeC8 shape refresh and preserve scale; builds the resource key with HI/LOW prefix; finds the animation record; updates name/record; dispatches completeE4 with start frame/repeat and completeC0 with animation definition. No movement-mode/turn/Euler reset in this procedure.| +|completeC8→462270 /62270..62331|Reads bound shape radius and bounds. Calls game110→471240, game2E8→472120 and game2E0→4720C0. The latter setters write game1D4/1C4 bounding vectors, not Euler or destination Euler.| +|completeE4→40DA30 /DA30..DAAD|Calls morph subobject frame/repeat and pause methods, mirrors loop byte completeAD, selects frame metadata if present. No mode/turn/Euler reset.| +|completeC0→47ED54 /7ED54|OMT animation-definition transport is represented by an explicit resource adapter in the probe. Full DLL animation playback is not executed.| + +## Native observations + +`tools/binary/jimmy_base_return.py` and `_probe.c` generate a private mapped-source +probe; it runs in the existing network-isolated Wine32 copy environment. +Original files are neither modified nor mounted in that execution namespace. +The final run emits the required success marker and exits0. Post-capture Python +assertions validate **140 finite cases**: + +- **84 base cases:** seven action names STOP/TALK/FALL/HIT/SPLAT/FENCE/LADDER, + three readiness states, loop0/1 and before/at-final-frame. Each runs180 actual + base/common/facing updates. Both Euler vectors stay(0,155,0), movement mode1 + and stored turn11.666668 survive. Eligible non-loop completion is called180 + times. The action-selection adapter in this matrix records/copies the new + action name without changing playback flags; repeated completion here is + deliberately not a claim about the full selected animation's playback. +- **56 STOP cases:** same seven initial actions, readiness off/on, record absent/ + present and game410 Stop versus direct completeE0 selection. These execute + actual42AFC0,43A750,429A00,43AFF0,40DD90,40DA30 and462270 as applicable. + STOP selection/frame/pause paths are checked, including protected-action + rejection versus direct selection. Mode/turn and initially distinct Euler + vectors remain unchanged. Non-direct Stop clears speed and velocity. + After an **explicit synthetic upright seed**, another180 actual base updates + retain upright vectors and the old mode/turn. Successful real STOP selection + sets loop1, so this interval has no animation-ended callback. + +Base cases execute the actual462520 chain with a synthetic null body-context +pointer. The pickup link is marked checked, CanMove is1, sound handles invalid, +timer0 and facing dirty0. Resource lookup, shape/animation binding, shape bounds, +morph current-frame/frame-set/pause transport and special Stop/restore/enable +callbacks are explicit adapters. Actual action-name getter and string comparison +semantics are used. These are original components on synthetic state, not actual +Carl startup, body integration, registry scheduling, a full Jimmy frame, OMT +playback/rendering or native Windows gameplay. + +## Consequence and remaining question + +The omitted base completion and accepted STOP request paths do not supply a +hidden ordinary-mode or stored-turn reset in these bounded source cases. The +successfully selected STOP loop also prevents a later completion callback from +quietly repairing those fields. This strengthens the existing composition's +retained-state interpretation; it still does not establish the actual original +first resumed input order or entry state. + +Preserve the evidence gate. The next comparison must identify a real divergence +in entry/contact state, registry/frame placement, input eligibility or the +remaining live body/derived-frame context before changing the port. A blanket +rotation reset or switching all fresh sessions to retained ordering is not +supported by this result. + +## Artifacts and reproduction + +- artifacts/jimmy-base-return/build/source.json: source ranges, PE offsets, + hashes, virtual bindings and retained REA excerpts. +- artifacts/jimmy-base-return/native-observations.json: all140 case records and + source/probe/log/capture hashes. +- probe/wine.log and probe/capture.json: final success marker and exit0. + +``` +python3 tools/binary/jimmy_base_return.py ../Original \ + --output artifacts/jimmy-base-return/build \ + --rea artifacts/jimmy-movement-audit/rea-original-disassembly.json +i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wl,--image-base,0x10000000 \ + -I tools/binary artifacts/jimmy-base-return/build/jimmy_base_return_probe.c \ + -o artifacts/jimmy-base-return/build/probe.exe +python3 tools/recon/reference_capture.py --asset-probe \ + --probe-executable artifacts/jimmy-base-return/build/probe.exe \ + --probe-success JIMMY_BASE_RETURN_COMPLETE --seconds 12 \ + --output artifacts/jimmy-base-return/probe +python3 tools/binary/jimmy_base_return.py ../Original \ + --output artifacts/jimmy-base-return/build \ + --rea artifacts/jimmy-movement-audit/rea-original-disassembly.json \ + --capture artifacts/jimmy-base-return/probe +``` + +First-run prefix setup exceeded its initial capture interval; the initialized +rerun established the84 base cases. The expanded resource adapter initially +expected STOP instead of the source's HISTOP lookup; that harness assertion was +corrected before the successful140-case capture. Source virtual bindings are +checked before compilation. No failed harness/setup attempt is original gameplay +evidence. No runtime/shared documentation edit or commit is made by this agent. diff --git a/docs/gameplay/jimmy-carl-entry.md b/docs/gameplay/jimmy-carl-entry.md new file mode 100644 index 0000000..1c291bc --- /dev/null +++ b/docs/gameplay/jimmy-carl-entry.md @@ -0,0 +1,84 @@ +# Carl contact and conversation entry + +2026-11-05. This investigation closes the local contact/admission boundary. It does **not** identify a source-supported fix for the bank returning after skipping Carl. Physical collision admission, the complete task callback graph, and the complete skip/resume frame remain separate boundaries. + +## Evidence and reproduction + +Original `Neutron.exe` SHA-256: `f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. Retained REA disassembly: `artifacts/jimmy-movement-audit/rea-original-disassembly.json`, evidence `ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`. JN-Engine was used as an index; executable bytes and actual GAM fields establish the statements below. + +Read-only guard/generator: `tools/binary/jimmy_carl_entry.py`. It checks the executable identity, direct calls, virtual bindings and instruction sites, records original file offsets/range hashes, and can retain bounded REA extracts. All addresses here are preferred-base VAs. For the cited executable text/data sites, raw file offset is VA minus `0x400000`; the helper calculates offsets from PE sections rather than assuming this mapping. + +```sh +python3 tools/binary/jimmy_carl_entry.py ../Original \ + --rea-disassembly artifacts/jimmy-movement-audit/rea-original-disassembly.json \ + --generate-probe artifacts/jimmy-carl-entry/native \ + > artifacts/jimmy-carl-entry/source.json +i686-w64-mingw32-gcc -O0 -Wall -Wextra \ + -o artifacts/jimmy-carl-entry/native/probe.exe \ + artifacts/jimmy-carl-entry/native/jimmy_carl_entry_probe.c +python3 tools/recon/reference_capture.py --asset-probe \ + --probe-executable artifacts/jimmy-carl-entry/native/probe.exe \ + --probe-success JIMMY_CARL_ENTRY_COMPLETE --seconds 12 \ + --output artifacts/jimmy-carl-entry/probe +``` + +The generator compiled without warnings. The copied-original component ran under Wine in the existing network-disabled namespace, with `Original/` unmounted. `artifacts/jimmy-carl-entry/probe/wine.log` reports 96 passing cases and `JIMMY_CARL_ENTRY_COMPLETE`; `capture.json` records exit 0. This is **isolated original component execution**, not native Windows/full original gameplay verification. Originals were not executed in place or changed. + +## Recovered contact and talk ownership + +Carl's game interface is complete-object `+0xC0`. Its game vtable `0x495364` binds contact slot `0x40` to `0x40A3C0`, ordinary actor update `0x3C4` to `0x41B950`, and velocity preparation `0x410` to `0x40A6B0`. Its complete vtable `0x495804` binds state setter `0x124` to `0x4089B0`, talk `0x140` to `0x41B7B0`, trigger resolution `0x17C` to `0x41BB20`, and progress callback `0x180` to `0x413E50`. + +| Boundary | Original evidence | State and dependencies | +|---|---|---| +| Physical notification gates | `47A46E/47A48F`, `47A4AA/47A4BD` | Both actors' game220 bind471A30 (own byte140 collision-enable); both game3A0 bind472F80 (`mov al,1; ret4`). Thus these pair-permission callbacks contain no raw-control, current-action or support admission check. Game178 on both binds471720 (own collision-kind124); kind2 selects47A5E0, otherwise47B3E0. Geometry/actual values remain a separate boundary. | +| Contact prelude | `40A3CD→470A90` | Own slot `3C→470A60` checks duplicate membership in own contact list. Own deletion byte `+6` can suppress list append. Appends contacted pointer to own `+260` list and increments `+264`. Own `+408` may receive current-game callback `144`; lab complete table `4C3CD0+144→475D40` is exactly `or eax,-1; ret8`, with no actor side effects. | +| Target admission | `40A44C..40A460` | Reads **Carl game+600** target; requires non-null and exact identity with incoming contacted game pointer. This is not a raw-controlled-pointer requirement. | +| Talk-ready transition | `40A676..40A693` | Requires **Carl game+608 == 6**; invokes **Carl complete slot124(0)**. No support getter, Jimmy mode/turn write, target velocity/root/Euler store, distance threshold, or vertical threshold occurs in this branch. | +| State ownership | `4089E5..408A04` | Setter copies own complete `+6C8` to `+6CC`, then writes requested state to `+6C8` (game+608). Complete byte `+970` can suppress state0/6 assignment. State0 tail `408B44..408B90` prepares/animates the NPC if its own flags permit it. | +| AI before talk | `41B95D→408000`; `41B972..41B988` | Friend update runs inherited AI, increments own timer, then reads **resulting own AI state**. State0 dispatches complete140. It is not a test for a null target pointer. | +| AI state0 dependencies | `408438..4084FC` | Reads target's **game+49D** targetability/invisibility flag at `40847C`; uses own facing/AI helpers and own distance/range data; can restore own state6/2. This is not Jimmy's support flag. The inherited update includes gates and indirect own AI callbacks; the native probe below does not execute this whole update. | +| Conversation trigger selection | `41BB20..41BC1F` | Up to five named trigger lookups through `474070`; TalkState must not be `-1` and must equal own complete+554 task state or wildcard `-2`. No Jimmy support query. | +| Progress before activation | `41B7CD→Carl413E50→41B810` | Base awards score100 through `42ADC0`, then invokes **Carl game410→40A6B0**, which sets **Carl velocity** to zero through own game2C4. It does not prepare Jimmy. Carl then advances `SCENE50→60` (other paths65→70,270→280) through `45F990`. Task notifications remain a separate dependency. | +| Synchronous camera activation | `41B7D3..41B7D8` | Invokes resolved trigger's game slot5C with that trigger as argument. Only after it returns, `41B7DD..41B7FA` increments NPC talk counter, clears own elapsed timer, sets own AIstate9, and stops own animation. | +| Jimmy counterpart contact | game table `4A373C+40→422D30`; `422D50→470A90` | Jimmy also receives a contact callback. Its subsequent concrete-type ladder tests pendulum, vehicles, projectile/enemy classes, button, AIT and load-level. It has no Carl/friends/AI generic test. Carl matches none of those concrete classes, so the C3DLOADLEVEL false branch `4232D0→423563` finishes without mode/turn/Euler preparation. This is static path analysis, not execution of the counterpart in the finite probe. | + +The optional marker logic earlier in contact (`40A3E7..40A44C`, own game+8CD) has raw-controlled/Goddard identity handling and NPC marker/animation writes. It is separate from the state6 exact-target admission branch and supplies no Jimmy grounding gate. The state4 branch transforms relative positions/directions into **NPC-owned** fields; state6 does not execute it. + +Actual `level1b.gam`, SHA-256 `316fff40db565c2add5b07cbccdef640ddb67c64d6625fea1429ce2a0542a234`, binds Carl at raw `0x1455` to target `Jim1`, TaskName `SCENE`, initial AIState9, and TalkState0=50/TalkTrigger0=`neutron1a`. Jimmy at raw `0x8` has TaskName `none`, RequiredLevel0, ExactLevel/RemoveLevel `-1`. `neutron1a` MCA at raw `0xE0B` names PlayerControlled=`JIM1`, NextTrigger=`carlwalk`. Carlwalk AIT at raw `0x1AFD` targets `C3DCARL`, sets AIState3 and chains `default`; it does not change Jimmy root/yaw. The helper retains these actual entity fields and entity file offsets. + +## Finite component result + +`jimmy_carl_entry_probe.c` executes complete original contact `40A3C0`, base `470A90`, actual duplicate-list predicate `470A60`, state setter `4089B0` and lab callback `475D40`. It uses synthetic complete objects/vtables, a native allocator adapter, a false-returning incoming type-query adapter, and NPC animation/preparation adapters. Original constructors, dynamic collision admission, AI update, task callbacks, trigger resolution, camera activation and skip are outside the probe. + +Across 96 combinations of incoming target identity, own AIState6/3, raw-controlled identity, Jimmy mode0/1, Jimmy turn `-12/0/+12`, and synthetic support0/1: + +- Actual base contact appends one contact node. +- Own state becomes0 exactly when contacted target matches and own state was6. +- Own state0 idle preparation/animation callbacks occur in those cases. +- The entire `0x1F00`-byte synthetic Jimmy object remains unchanged, including mode, turn, bank and Euler destination. +- Jimmy support virtual218 is never queried. The synthetic support value is a callback experiment, not a claim about a recovered physical-support field. + +This confirms the local source reading: adding a grounded-only Carl-talk gate or resetting Jimmy mode/turn in the contact callback has no support in this recovered boundary. It does **not** prove the physical pair engine admits every airborne trajectory or that the full conversation activation frame leaves Jimmy unchanged; camera activation itself has its recovered orientation suffix. + +## Startup/reuse hypothesis audit + +A proposed explanation for the original/port difference was that original New Game might preload the lab behind the main menu, leaving a reusable Jimmy before the first playable lab controller. The inspected startup gives no positive support for that explanation: + +| Source chain | Observation | +|---|---| +| `46A641→46B160`; `46A654` | Constructs application and stores global509980. | +| `46A65B` pushes MAIN; `46A660→46A310→46A33D/44D0E0` | Startup selects a constructed MAIN controller. | +| `44D122→459110→459168/44D2B0→44D306/4745A0` | Constructs CMainMenu using Jimmy-game/generic-game base constructors. Installs complete4D1070/game4D0C0C; class literal4F291C is `CMAINMENU`. This is not a level1b GAM load. | +| `4591C3→4749A0→completeB4/44D3D0` | Menu InitGame clears task list through45F4C0, initializes world/camera defaults through474A10, sets own lifetime fields; no direct Jimmy constructor or lab request here. | +| `44D139` app118→46F760; `44D149` app12C(3)→46F830 | Opens resource database and creates a 2D image from it, respectively. These bounded bodies do not load a lab or construct Jimmy. | +| `404B4F..404B54` | Actual menu New Game item pushes string4EC71C (`NewGame.tsk`) and calls460E70. It then changes own menu/current-game state. | +| `40D089..40D08E` | The other executable reference to NewGame.tsk is the script RESTARTGAME action. | +| `45B1E2→422160` | Sole direct `C3DJimmy` constructor call in retained executable disassembly is inside the generic object factory. | + +**Inference limit:** this is a positive constructor/initialization chain and a bounded negative result for preload. Menu-frame event/deferred-task behavior and any attract/demo route have not been exhaustively executed here. The result does not certify initial full registry order, and does not justify changing the port's fresh/retained ordering. Existing loader reuse facts remain valid when a prior Jimmy actually exists. + +## Remaining questions and implementation comparison + +The current port approximates contact using a broad sphere and starts Carl talk from its actor update after player processing. Original physical contact notifications occur through47A430 before ordinary registry updates; Carl's own talk then occurs from41B950 after its inherited AI update. Their relationship to Jimmy's update depends on actual registry order, collision state, and callback ownership; this report does not replace that schedule with a guessed global order. + +Still unresolved: exact physical admission at the actual jumping contact; complete entry frame with task callbacks and source bodies; full MCA skip→Carlwalk→DEFAULT→first resumed input composition; and original first-play registry order at the user-observed case. No runtime implementation was changed by this investigation. Ordinary landing bank must remain until directly contradicted by evidence; contact preparation supplies no basis for a global upright clamp. diff --git a/docs/gameplay/jimmy-cutscene-decompilation.md b/docs/gameplay/jimmy-cutscene-decompilation.md index 033e3af..d70f8e7 100644 --- a/docs/gameplay/jimmy-cutscene-decompilation.md +++ b/docs/gameplay/jimmy-cutscene-decompilation.md @@ -5,6 +5,15 @@ implementation. Preserve runtime baseline a2e89c6 and packaged runtime dae13ac. No src/, regression test, build script, original or packaged binary changes are part of this checkpoint. New work is read-only diagnostics and source findings. +2026-11-06 continuation: [integrated lifecycle trace](jimmy-cutscene-lifecycle.md) +records292 additional bounded original-code cases and complete DEFAULT recovery. +Known original components reproduce the port's order-sensitive first stale writer; +contact/task/STOP/ordinary animation paths supply no new reset. A copied-original +read-only observer is implemented and its Wine32 attach path verified. Local +original rendering still supplies no Jimmy/Carl gameplay trace. The source gate +remains open; preserving exact original behavior takes precedence over forcing +the diagnostic upright with an unsupported reset. + ## Confirmed requirement and corrected coverage User comparison confirms ordinary landing can leave Jimmy banked in the original. diff --git a/docs/gameplay/jimmy-cutscene-lifecycle.md b/docs/gameplay/jimmy-cutscene-lifecycle.md new file mode 100644 index 0000000..fcb960b --- /dev/null +++ b/docs/gameplay/jimmy-cutscene-lifecycle.md @@ -0,0 +1,85 @@ +# Carl skip lifecycle: recovered boundaries and the remaining observation + +2026-11-06. Execution of the accepted next-work plan, with the user's requirement +to preserve original behavior exactly. Runtime a2e89c6 and packages dae13ac remain +unchanged. This checkpoint adds evidence and observation tools, not a tilt fix. + +## Event/state trace + +Original source identity, PE offsets and REA Evidence are in the linked reports. +These rows combine static facts and explicitly synthetic original-code execution; +they are not a captured whole-original frame sequence. + +| Boundary | Recovered state ownership | Evidence / remaining limit | +|---|---|---| +|Dynamic contact→Carl state0|Matching target and Carl state6 admit the talk-ready transition. Jimmy is not modified and support is not queried by that callback.|[Contact report](jimmy-carl-entry.md):96 native cases; actual physical trajectory/admission and whole AI update are separate.| +|Carl talk→SCENE50→60→neutron1a|Task assignment/broadcast precedes the synchronous camera trigger. Jimmy's authored TaskName is `none`. All89 authored SCENE listeners across17 kinds are inventoried; six callback paths do not supply another Jimmy movement reset.|[Task report](jimmy-task-return.md): static callback closure and48 native dispatcher/objective cases; actor callbacks in that probe are adapters.| +|MCA initial preparation|StopMotion clears speed/velocity independently of STOP animation acceptance. Both current and destination Euler become(0,currentYaw,0); dirty is preserved. Raw control is removed.|Earlier20 camera-entry cases; [full STOP/base report](jimmy-base-return.md) supplies the omitted selection/completion dependencies.| +|Uncontrolled interval|Known controller ownership gate retains mode1/stored turn. Actual base/facing and ordinary STOP/talk/FALL completion provide no reset. Playback/resource state is distinct from movement mode.|140 native base/STOP cases. Full body context, complete Jimmy frame and OMT playback remain outside these probes.| +|Accepted skip|Original sets Jimmy action/menu latch complete1E00 and shared skip4F83E4; stops sound, deactivates current actor/animation and invokes completion.|[Return source](jimmy-cutscene-return-source.md); actual skip prefix is executed by the composition. The complete skip frame is not.| +|MCA completion→Carlwalk→DEFAULT|Completion grants named JIM1; Carlwalk changes Carl's AI. DEFAULT's already-owned early branch clears shared skip/resources, with no new Jimmy reset.|[Complete DEFAULT recovery](jimmy-default-decompilation.md) closes the previous provider-boundary gap using an explicitly mapped static carrier.| +|First resumed callback|On synthetic supported/released state, input-before-player republishes stale roll before the controller clears mode/turn. Player-before-input clears those fields first and stays upright.|[Composition](jimmy-skip-composition.md):8 actual original-component cases agree with48 port traces. This does not establish the original route's actual entry state/order/delta.| + +At the problematic composed boundary the seed is mode1, turn±11.666668, +current/destination(0,155,0), supported=true and dt1/60. Fresh input reduces turn +to±10.000001 and publishes the opposite roll. The next controller clears mode +and turn; neutral ground input then retains the banked destination. Skip-prefix +latch writes do not change this result. These values are measured synthetic +component inputs/results, not values measured from the original Carl route. + +## What this permits and what remains unresolved + +The first stale port writer is known. Its arithmetic also occurs in the composed +original routines, so adding a reset to raw control grant, DEFAULT, Carl contact, +task broadcast or ordinary animation completion would lack source support. +The user's observation that the original stays upright remains authoritative; +the actual original state/order entering that first input is still missing. +Normal landing bank must remain intact. No per-frame leveling, scheduler switch +or input suppression has been introduced to make the diagnostic green. + +The fresh-construction order is a conditional source fact, not a runtime trace +of the user's route. Startup inspection constructs MAIN directly and supplies +no positive lab-preload/reusable-Jimmy explanation. A new read-only observer can +record real registry positions, raw ownership, mode, turn, current/destination +Euler, dirty, cached support, viewport delta and input/skip flags. Its samples +are non-atomic and cannot alone certify exact callback chronology. + +## Runtime observation tool and local limit + +[Original-state observer](original-state-observer.md) supports launch or attach +to a verified generated game copy. It never writes actor memory or injects code. +The attach path leaves the observed game running. Three exact executable profiles +have24 independent instruction guards; the supplied HDnoCD variant has its own +REA Evidence and global addresses, rather than assumed canonical equivalence. + +The local Wine32 attach integration passes:928 parsed samples, source guards +accepted, observer exit0, original still running after sampling. Provenance is +`artifacts/original-state-observer/attach-runtime/observations.json`. The legacy +window remains black; observed registry contains MAIN and no Jimmy, with viewport +delta0. Focus/normal Return input and an isolated desktop also failed to reach a +usable gameplay reference. Neither accepted input events nor MAIN's zero gameplay +delta proves a menu selection or a whole-game timing fault. Native Windows and +the actual Carl skip were not observed by this work. + +To collect the missing comparison on native Windows, run a **copied** original, +reach Carl, then attach for the banked entry/skip/neutral-return interval: + +```text +observer.exe --attach-copied-pid=1234 --seconds=60 > carl-original.jsonl +``` + +Use the copied game's actual PID. Keep its path outside an `Original` directory; +the tool checks the actual executable identity/path and refuses unsupported +images. No automatic keys or close request are sent in attach mode. If the trace +misses the first transition, a narrower callback-level observation is required; +do not fill it with an inferred reset. + +## Checkpoint status + +292 new bounded original-code cases pass:96 contact,8 input/controller/skip-prefix +composition,48 task/objective and140 base/STOP. They deliberately have different +synthetic dependencies. The48 port diagnostic cases still describe the preserved +failure, not successful gameplay. The mapped DEFAULT carrier regenerates exactly; +539 original files remain unchanged. No src/tests/scripts or package change is +part of this checkpoint. Steps1–2 of the next-work plan remain open at the actual +original resumed-frame observation; step3's gameplay correction gate is not met. diff --git a/docs/gameplay/jimmy-cutscene-return-source.md b/docs/gameplay/jimmy-cutscene-return-source.md index 78d0059..9891d3b 100644 --- a/docs/gameplay/jimmy-cutscene-return-source.md +++ b/docs/gameplay/jimmy-cutscene-return-source.md @@ -67,12 +67,18 @@ artifacts/jimmy-cutscene-return/rea-completion/. New successful pseudocode: |438A60 retained-mode input dispatch|ev_77ee22e6d49adc0c983af92ba74273faf5f4daf697ab520ea45d22b08bc11bcb| |42AE00 cleanup wrapper|ev_2ee50b10018363378445be32df38ab4f6b2125247b69485304867674d5d484da| -DEFAULT entry447CF0 did not resolve to a Ghidra procedure; the provider then +DEFAULT entry447CF0 did not resolve to a Ghidra procedure in the original PE database; the provider then reported the numeric selector as an unmapped file offset. Its complete error is retained as00.json; no pseudocode is attributed to it. The guarded retained REA instructions support the DEFAULT statements above. No unchanged retry or claim that the whole original was executed follows from that provider result. +2026-11-06: a changed input strategy now supplies complete DEFAULT pseudocode +through a separately mapped static raw carrier. Its Evidence subject and mapping +are explicit in [the DEFAULT recovery report](jimmy-default-decompilation.md). +The original PE function-boundary failure remains recorded; the carrier result +agrees with the guarded instructions and supplies no additional Jimmy reset. + ## Port cause versus original explanation [The port diagnostic](jimmy-cutscene-port-trace.md) reproduces48 cases. On fresh diff --git a/docs/gameplay/jimmy-default-decompilation.md b/docs/gameplay/jimmy-default-decompilation.md new file mode 100644 index 0000000..0035c71 --- /dev/null +++ b/docs/gameplay/jimmy-default-decompilation.md @@ -0,0 +1,60 @@ +# DEFAULT source recovery through a mapped analysis carrier + +2026-11-06. This closes a provider function-boundary gap, not the Carl return +behavior gate. No gameplay change follows from this result. + +The original PE database did not recognize447CF0 as a function. Instead of +repeating that failed selector, `tools/binary/default_raw_carrier.py` maps the +verified EXE's initialized sections from VA447CF0 onward into a separate raw +analysis file. It retains the original virtual spacing and zero-fills virtual +tails/gaps. `mapping.json` identifies every source file range and carrier offset. +This file is static analysis input; it is neither an executable nor a captured +process image. Imports, earlier code and runtime-initialized state are not supplied. + +Source EXE SHA256: +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. +Carrier SHA256: +`a5bf4114beaf23fcaaf608e042a5873ff353ab4fa1189ba6b7466ed55fe91b99`. +The regenerated carrier is byte-identical to the analyzed file. + +REA/Ghidra12.1.4 successfully decompiled entry447CF0 using this changed input. +Evidence: +`ev_58ecada52eaf5028945af6330fc9721a6a085495dbfd8ffdbb665a1fcad27420`. +Complete result, provider snapshot, mapping and stderr remain local under +`artifacts/jimmy-skip-raw-default/`. The Evidence subject is the carrier hash, +not the EXE hash. The existing original-instruction guard independently binds +the relevant instructions to EXE offsets447CF0−400000 and onward. + +## Recovered behavior and limits + +The complete decompilation agrees with the guarded original instructions: + +- `none` returns; named triggers resolve and dispatch according to concrete type. +- DEFAULT447D34..447FC5 resolves JIM1. If JIM1 already owns raw control, its early + branch447D5C..447D9A loads sound effects, clears the applicable actor flag and + shared skip, and returns. It does not execute the later owner/camera/music branch. +- Otherwise it selects the appropriate Jimmy/vehicle owner, grants through118, + conditionally snaps the shared camera eye when distance exceeds1000, and handles + sound/music/UI/shared state. The SCENE30 menu callback is a separate conditional. +- No direct Jimmy mode704/turn614/current-or-destination-Euler reset appears in + DEFAULT. A raw owner grant is still475A40's pointer store, not actor Init. + +Carl's MCA completion names JIM1 before dispatching Carlwalk→DEFAULT, making the +already-owned early branch relevant. This result supplies no hidden reset to +explain the user's upright original return. Indirect callees retain the coverage +and limits documented in the return-source report; pseudocode is a navigation aid, +and the original instructions remain authoritative. + +## Reproduction + +From GamePort, with the local REA/Ghidra environment: + +```sh +python3 tools/binary/default_raw_carrier.py ../Original --output artifacts/default-recovery +scripts/rea.sh decompile artifacts/default-recovery/default.bin 0x447cf0 \ + --provider ghidra --target-format raw-binary --architecture x86 \ + --entry-point 0x447cf0 --snapshot artifacts/default-recovery/snapshot.json \ + --format json --full-output > artifacts/default-recovery/result.json +``` + +No original code was executed by this analysis and no original files were changed. diff --git a/docs/gameplay/jimmy-skip-composition.md b/docs/gameplay/jimmy-skip-composition.md new file mode 100644 index 0000000..230369f --- /dev/null +++ b/docs/gameplay/jimmy-skip-composition.md @@ -0,0 +1,126 @@ +# Original input/controller composition after scene return + +2026-11-05. Independent bounded original-code execution for the accepted next-work +plan. This addresses whether the port's fresh-versus-retained distinction is an +invented implementation artifact or also exists in the known original components. +It does not execute original startup, complete Carl activation or all skip logic. + +## Source identity and recovery + +Original Neutron.exe SHA256 +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. +REA complete instruction Evidence +`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904` +provides the bounded source instruction context. The generator verifies that +Evidence's subject identity, verifies the authoritative EXE hash, PE-maps every +copied range and records source range hashes. Originals are never modified or +executed in place. The generated probe runs under the existing isolated Wine32 +asset-probe boundary, with no network or original-directory mount. + +## Executed source and synthetic boundary + +| Original VA / raw file offset | Executed role | +|---|---| +|431518..431590 /31518..31590|Initial MCA current/destination flatten suffix; actual328→4723F0 and32C→472450 leaves.| +|430F1D..430F5C /30F1D..30F5C|Accepted skip's JIM1 lookup, complete1E00 latch, shared4F83E4 set and audio-stop prefix. Lookup/audio transport are recorded shims; target cleanup and completion are outside this prefix.| +|475A40..475A4C /75A40..75A4C|Actual raw control-pointer grant and removal. Shared skip is explicitly cleared to represent the already-verified DEFAULT field effect; complete DEFAULT is not executed.| +|438A60..438BA2 /38A60..38BA2|Actual retained-mode dispatch. Its absolute jump-table operand and four table entries are relocated into the private source image.| +|439900..439E33 /39900..39E33|Actual keyboard/zero-mouse ordinary air input through the real36C→472660 destination writer. The camera tail is replaced by the proper source-function epilogue.| +|437940..437C3A /37940..37C3A|Actual player wrapper including control identity, jump/support dispatch, mode/turn reset and publication. Its40E050 base call is replaced only by actual43A420 facing; unrelated base resource/animation behavior is not simulated.| +|43A420..43A5CD /3A420..3A5CD|Actual facing, actual334→458F90→472480 Euler-add chain; global ready gate forced true.| +|429910..429963 /29910..29963|Actual landing effect/menu helper with synthetic menu488/noop and invalid sound handle. It does not change mode/turn/Euler.| +|43915D..4395CF /3951D..395CF|Actual neutral ground keyboard suffix after the wrapper has selected mode0; ground camera/device prefix omitted.| + +The actor is synthetic, supported=true, jump-held=false, ordinary raw gadget-1, +zero mouse/analog/keyboard and initial speed0. Complete/game vtables are explicit. +Ground/air motion apply and animation actions are recorded no-op resource shims; +the known mode/turn writes and facing/input arithmetic execute from original code. +The current-action helper represents STOP versus RUN inequality. There is no body, +world collision, registry, full derived Jimmy input callback426030, animation engine, +renderer, complete MCA update/completion, original startup or full-game execution. + +The initial state deliberately models the problematic boundary: retained movement +mode1 and stored turn±11.666668, with both current/destination flattened to +(0,155,0). After180 uncontrolled player wrappers, those vectors remain upright +and mode/turn survive. The composition then grants control and orders input/player +callbacks either fresh-input-first or retained-player-first, followed by300 idle +callbacks. Each order is run with and without the original skip-prefix writes, +and with both turn signs: eight finite cases. + +## Observed results + +All8 cases complete with the required marker and capture wineExit0. Finite +post-capture assertions validate the boundary values below. + +| Order | Skip prefix | First resumed effect | After300 idle callbacks | +|---|---|---|---| +|Input before player|Off or on|Air input decays turn±11.666668 to±10.000001 and writes target roll∓10.000001. Actual player wrapper then clears mode/turn, after facing has consumed the bad target.|Four cases retain approximately±10° bank.| +|Player before input|Off or on|Actual supported/released player wrapper clears mode1/turn before input. Mode0 neutral ground suffix preserves upright target.|Four cases stay exactly upright.| + +Representative positive-turn fresh result is bit-for-print equivalent to the +existing managed diagnostic: first target roll-10.000001; first player current +roll360, mode0/turn0; idle current roll350.000183. Negative-turn result converges +to9.99999523. This is original code reproducing the same component composition, +not proof that this fresh composition is the normal original playable lifecycle. + +With skip enabled, the prefix sets both latch and shared skip to1 and records +one stopped sound; mode and turn remain unchanged. Those writes alone therefore +do not erase the first stale target in this composition. Their full menu/input +consumer and caller timing remain separate questions. + +## Consequences and unresolved original behavior + +The known controller/input contracts agree with the port's first-writer trace; +there is no new source evidence for adding a rotation or turn reset at raw grant. +The critical question is which callback order and entry state actual original +startup and the reported Carl route establish. A fresh allocation partial-order +proof must not be substituted for normal New Game execution: original startup/ +menu/loading may already have created a retained Jimmy before the first playable +lab. Proving that chain would explain upright return without an invented reset. +This investigation does not independently establish that startup chain. + +Follow-up2026-11-06: [Carl/startup audit](jimmy-carl-entry.md) positively traces +MAIN construction and supplies no lab-preload/Jimmy construction in that bounded +chain. The new observer also sees only MAIN before the unusable black-screen +boundary. Neither result supports switching all fresh scenes to retained order. +The broader [lifecycle trace](jimmy-cutscene-lifecycle.md) keeps actual original +Carl entry state/order/delta unresolved instead of adopting the preload hypothesis. + +One additional inspected base branch is not a reset justification:40E050 pins +current transform to authored transform when game58C CanMove==0, but actual +lab JIM1 has serialized CanMove1. Other base resources/callbacks remain omitted +from the composition and must be tracked if startup/order does not explain the +user's whole-original observation. + +## Artifacts and reproduction + +- tools/binary/jimmy_skip_composition.py and _probe.c: read-only source guards, + relocation generator and bounded synthetic composition. +- artifacts/jimmy-skip-composition/build/source.json: ten original range hashes, + PE offsets and relocation operands. +- artifacts/jimmy-skip-composition/native-observations.json: all eight cases, + per-boundary fields and source/harness/executable/log/capture provenance hashes. +- probe/wine.log and probe/capture.json: successful marker and wineExit0. + +From GamePort: + +``` +python3 tools/binary/jimmy_skip_composition.py ../Original \ + --output artifacts/jimmy-skip-composition/build \ + --rea artifacts/jimmy-movement-audit/rea-original-disassembly.json +i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wl,--image-base,0x10000000 \ + -I tools/binary artifacts/jimmy-skip-composition/build/jimmy_skip_composition_probe.c \ + -o artifacts/jimmy-skip-composition/build/probe.exe +python3 tools/recon/reference_capture.py --asset-probe \ + --probe-executable artifacts/jimmy-skip-composition/build/probe.exe \ + --probe-success JIMMY_SKIP_COMPOSITION_COMPLETE --seconds 12 \ + --output artifacts/jimmy-skip-composition/probe +``` + +Harness corrections preceded the successful run: initial Wine prefix creation +outlasted its first capture, the absolute dispatch jump table needed relocation, +and the skip-prefix exit initially preceded its cdecl argument cleanup. These +failures were probe construction gaps, not original gameplay observations. +The final compiled probe has no warnings; only the final success marker/exit and +validated eight-case outputs establish the observations. No production/runtime/ +regression-test/build-script change or commit is made by this investigator. diff --git a/docs/gameplay/jimmy-task-return.md b/docs/gameplay/jimmy-task-return.md new file mode 100644 index 0000000..ea72de8 --- /dev/null +++ b/docs/gameplay/jimmy-task-return.md @@ -0,0 +1,153 @@ +# SCENE60 task broadcast and Jimmy's retained bank + +2026-11-06. This investigation covers the task broadcast that Carl's talk +progress runs **before** `neutron1a` activation. It provides no source-supported +Jimmy movement reset and does not close the whole original skip-to-idle frame. +No runtime, test, build-script or package change is made here. + +## Identity and evidence + +Authoritative `Neutron.exe` SHA256: +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. +Retained REA complete instruction Evidence: +`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`. +The helper validates that Evidence's subject hash, the authoritative binary, +PE-mapped source sites, direct calls, tables and actual GAM records. Addresses +below are preferred VAs; the listed text file offsets equal VA minus400000, +independently checked through PE sections. + +JN-Engine's `docs/decomp_ledger.csv` and `docs/gam_schema.md` supplied class/table +leads only. All17 matching FourCC registrations, constructor game-table stores +and game424 targets are verified against the supplied original. JN-Engine's +movement implementation is not used. + +## Assignment phases and direct Jimmy admission + +| Original VA / file offset | Recovered owner/transition | +|---|---| +|413E5A,413E9D /13E5A,13E9D|Carl progress queries SCENE;50 becomes60 through45F990. The friend talk caller subsequently dispatches the selected conversation. This is an entry phase, not an automatic skip-completion broadcast.| +|45F9EC,45F9F2 /5F9EC,5F9F2|SCENE milestone switch. Byte45FC48[60−35] is2;45FBF0[2] points45FA0B, which supplies objective arguments3,1.| +|406F50..406F88 /6F50..6F88|For positive objective id, clear44 dwords at4F7D00, store id4F8194, zero timer4F8188, store low argument byte at indexed objective flag. This complete leaf does not write modal4F8198 or input suppression4F8430.| +|45FB63..45FB8B /5FB63..5FB8B|Traverse task records4FC5FC, case-insensitively match name, then store supplied state at record+64. Repeated assignments are not suppressed.| +|45FB8D..45FBE8 /5FB8D..5FBE8|Traverse registry50999C in list order. Compare supplied task against each game interface+430 TaskName. Only exact case-insensitive matches receive game424, synchronously.| +|458880..45888A /58880..5888A|Plain task callback stores supplied state at **own** game494 and returns.| +|4A373C+420,+424 /A3B5C,A3B60|Jimmy binds post-task hook472970 (no-op) and task callback40E340. Actual lab JIM1 has TaskName`none`, so the SCENE60 broadcast never reaches its424 callback. The45F990 loop does not invoke420.| + +Actual `gam/level1b.gam` SHA256: +`316fff40db565c2add5b07cbccdef640ddb67c64d6625fea1429ce2a0542a234`. +JIM1 is index0/raw8, TaskName`none`, RequiredLevel0, ExactLevel/RemoveLevel−1. +Carl is index8/raw1455, TaskName`SCENE`, RequiredLevel0, +ExactLevel/RemoveLevel−1. Direct Jimmy exclusion alone would not prove that +another listener cannot affect him; the following inventory addresses that gap. + +## All authored matching listeners + +There are89 serialized SCENE listeners, spanning17 kinds and six callback +targets. The generated `source.json` retains every record index/raw offset, +tag, authored gate, callback and a50/60 gate comparison. This is an inventory of +**authored records**, not a runtime census of constructor-created helpers or +retained actors. + +| Callback VA / offset | Kinds and matching count | Recovered behavior | +|---|---|---| +|458880 /58880|3CAM,3MCA,3LIO,3NEU,3PAT,3SOU,STRT,LOAD:43|Store own TaskState. In particular, CAM/MCA task callbacks do **not** dispatch activation, prepare Jimmy, take control or play shots.| +|40CA80..40CA9D /CA80..CA9D|3AIT:14|Store own TaskState, query its own task name through45FEA0, discard query result and return. This callback does not call AIT trigger40C300 or grant control.| +|40E340..40E3D0 /E340..E3D0|3DUD,3BUT,3OMT,3TEL:9|Store own TaskState and apply own exact/required/remove activation gates through own complete110. Every matching authored instance in these kinds has all three gates−1, so50 and60 preserve existing activation.| +|45F2B0..45F3A5 /5F2B0..5F3A5|3PIC,3ANI:21|Store own TaskState; if its picture is uncollected, test own exact/required gate. Set own visibility, pickup-active byte and collision byte. No NextTrigger/ActivateObject/ToggledObject dispatch occurs in this task callback.| +|43EBB0..43EC07 /3EBB0..3EC07|3ROC:1|Run generic animated callback. If own linked pointer game680 is nonzero, set own rendering/effect and collision flags. The inspected callback tests that pointer without dereferencing it as another actor. Authored exact/required/remove gates are all−1.| +|413F30..41411E /13F30..1411E|3CAR:1|Query new SCENE, run generic activation, then LV1B override on Carl. At60, resolve CARLESC3, set **Carl** AIstate6 and copy marker root to **Carl**, then leave base activation unchanged.| + +For the pickup/sprite paths, `shrinkray` (required0), the unnamed animated sprite +index72 (required0) and the late pickup index120 (required140) preserve the same +gate outcome at50 and60. `apple` (exact30) is disabled at both. All remaining +matching pickup/sprite records have required/exact−1 and preserve state. +Actual collection table4F8438 and live visibility are not reconstructed by this +authored gate calculation. All21 callbacks can still store their own TaskState +on repeated assignments. + +The source helper records exact game tables and constructor/registration sites +for all17 kinds. Representative bindings include AIT48F8C0+424→40CA80, +CAM497BFC+424→458880, MCA4A8F64+424→458880, +PIC4AE548+424→45F2B0, Rocket4B25AC+424→43EBB0, +Carl495364+424→413F30 and LOAD4D025C+424→458880. + +## Activation dependencies and state ownership + +The inspected callback tails do not contain a Jimmy mode704/turn614/Euler +reset or a raw control-pointer grant. Their relevant indirect calls keep the +listener as `this`: + +- Animated complete110→40E3E0 controls that actor's display and collision. + Its complete10C hook is472970 for the matching Button/DUD/OMT/TEL/Rocket + classes. Carl's hook413D60 is an own-animation resource/preparation path, + guarded by its own complete635 loaded byte; it requests Carl's STOP and + sets Carl's motion parameters. It does not invoke a cutscene or Jimmy cleanup. +- Own game3A4/3AC→473030/4730E0 forwards false/true to own game224. + The common224→471A40 only writes own game140 collision-enabled byte. + Own game214→471A00 writes own game13E, and pickup game1F4→471980 + writes own game134. These are flags, not immediate collision-pair callbacks. +- Carl complete124→4089B0, state6, enters the408AC2 branch when eligible. + Its own game410→40A6B0 preparation clears Carl velocity/speed. Carl + game314→472360 copies Vec4 only to own game214 root. Neither receiver is + Jimmy. Equal/locked-state branches remain local as well. +- Display slot58 forwards to OMT resource visibility. This report does not + execute the complete OMT renderer/animation graph or claim arbitrary engine + observers have been exhausted. The recovered task callbacks themselves do + not publish another actor's Euler/mode/turn or trigger a camera chain. + +This closes the proposed **direct SCENE60 task reset** explanation and the +authored CAM/MCA/AIT activation explanation. It does not establish the original +first resumed frame or justify a blanket rotation reset, actor rescheduling or +new input suppression. Later UI consumers of objective flags, runtime-created +listeners and the full original registry remain separate observation boundaries. + +## Bounded native verification + +`jimmy_task_return_probe.c` executes original45F990 assignment/dispatch, +406F50 objective selection and458880 state store from a private mapped copy. +Only original absolute operands/jump-table targets needed by this finite path +are relocated. Task and registry lists, game objects/vtables and `_stricmp` +transport are explicit synthetic adapters. Matching actor callbacks in this +probe are **adapters**, not actual Carl/pickup/Rocket/engine callbacks; those +paths above are statically recovered. + +All48 cases pass, varying prior task50/60, authored-like Jimmy task`none` +versus synthetic matching`SCENE`, movement mode0/1, turn−12/0/+12 and both +modal/input-flag seeds0/1. Each callback observes assigned task60 and already +selected objective3. Authored-like Jimmy receives zero callbacks and remains +byte-for-byte unchanged across all1F00 bytes. Synthetic matching Jimmy's only +change is own game494 TaskState. Modal4F8198 and input suppression4F8430 +retain both tested seed values; objective timer4F8188 becomes zero. + +Final capture reports wineExit0 and `JIMMY_TASK_RETURN_COMPLETE`; parsed output +and provenance are in `artifacts/jimmy-task-return/native-observations.json`. +The probe binary, generated source, complete copied EXE identity, static guards, +Wine log and capture metadata are hashed there. No original startup, full Carl +talk, skip, body, input/controller or renderer executes in this probe. + +Initial capture timed out during Wine prefix creation. A missing-module repair +then failed kernel32 loading. The successful run uses a copy of the previously +successful generated Carl-contact Wine32 prefix. Logs for failed setup attempts +and prefix repair/reuse metadata are retained; none is gameplay evidence. +Original files were not modified or executed in place; isolated runs have no +network or original-directory mount. + +## Reproduction + +From GamePort, with the existing local REA Evidence and Wine32 tooling: + +``` +python3 tools/binary/jimmy_task_return.py ../Original \ + --rea artifacts/jimmy-movement-audit/rea-original-disassembly.json \ + --output artifacts/jimmy-task-return/build +i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wl,--image-base,0x10000000 \ + -I tools/binary artifacts/jimmy-task-return/build/jimmy_task_return_probe.c \ + -o artifacts/jimmy-task-return/build/probe.exe +python3 tools/recon/reference_capture.py --asset-probe \ + --probe-executable artifacts/jimmy-task-return/build/probe.exe \ + --probe-success JIMMY_TASK_RETURN_COMPLETE --seconds 12 \ + --output artifacts/jimmy-task-return/probe +``` + +A fresh Wine prefix may need more time for initialization; successful completion requires +both marker and process exit0, not merely screenshots or a returned wrapper. diff --git a/docs/gameplay/original-state-observer.md b/docs/gameplay/original-state-observer.md new file mode 100644 index 0000000..844df43 --- /dev/null +++ b/docs/gameplay/original-state-observer.md @@ -0,0 +1,212 @@ +# Read-only original process-state observer + +2026-11-06. This investigation tool is separate from the modern runtime. It is +intended to establish actual startup registry state and narrow the unresolved +Carl skip-to-idle discrepancy. It does not supply a gameplay fix or certify exact +callback order. No original execution is claimed by the initial compile/guard +checks below. + +## Execution boundary + +`tools/recon/original_state_observer.c` launches one explicitly attested generated +game copy with `CreateProcessA`, samples it with `ReadProcessMemory`, then requests +ordinary `WM_CLOSE` on that process's own visible window. It never writes target +memory, installs breakpoints, invokes target functions, forces actor state, or +terminates another process. If ordinary close does not succeed, the child remains +running; the caller must handle its own isolated environment. Existing Wine +capture infrastructure cleans up only its private wineserver afterward. + +The first argument must be `--copied-game=`. This is the caller's explicit +attestation that the target is a generated copy. Both the absolute path and the +handle-resolved final path reject a case-insensitive `Original` path component. +The tool accepts only the three exact hashes below and the original1019904-byte +file size. It holds an authenticated read handle without write/delete sharing +through process creation. The flag is not a cryptographic proof of provenance; +use the existing generated-copy wrapper, never a hard link to an original file. + +Alternatively, `--attach-copied-pid=` explicitly attests that an already +running process uses a generated copy. This mode acquires only +`PROCESS_VM_READ | PROCESS_QUERY_LIMITED_INFORMATION | SYNCHRONIZE`, obtains its +actual image path with `QueryFullProcessImageNameA`, and applies the same final +path, size, file hash and live instruction guards. PID is a strict positive +32-bit decimal value; malformed/overflowed values are rejected. The process +handle binds the selected process throughout validation/sampling, rather than +reopening a potentially reused PID. Attach mode never calls `CreateProcess`, +focuses a window, sends input, requests `WM_CLOSE`, or terminates the target. +`--menu-keys` is rejected before opening the process. Sampling ends while the +original session remains under the user's control. + +No network API is used. Run under `tools/recon/reference_capture.py` for its +existing no-network/no-original-mount boundary. Native Windows execution must +likewise use a generated directory containing copies of the game and its assets. +Game-created settings/saves then remain in that generated environment. + +## Supported subjects and evidence + +| Profile | Exact executable SHA256 | +|---|---| +|canonical|`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`| +|hd-resolution|`b6675b7e7f3fc37512185ddb4d6ce1fbe9a36c8b83f3b4b3ed6979a56db3d2d4`| +|hd-nocd|`8cd5d21997835a40978b8b83e344c97c92217bf6cd6858f7458b76935d64dedb`| + +Canonical instruction Evidence is +`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`, +retained in artifacts/jimmy-movement-audit/rea-original-disassembly.json. +The HDnoCD subject has separate complete REA instruction Evidence +`ev_23555fac476985c913a80805a12b25c26c25347c6e8210ee188471dd815c276d`, +retained in artifacts/jimmy-skip-original-sw/rea-hdnocd-disassembly.json. +The supplied HD resolution variant preserves the observed operands. The HDnoCD +profile is independently identified; its observation is not automatically a +canonical-original behavior claim. Other supplied variants are rejected. + +Each global address is independently guarded by its actual live instruction +operand before sampling. Runtime inspection is refused if those anchors do not +match within5s. This avoids assuming that the other variant has identical data +addresses. Preferred-base VAs and PE file offsets follow: + +| Read role | Instruction VA / file offset | canonical and HD global | HDnoCD global | +|---|---|---|---| +|Raw control owner|475A40..475A4B /75A40..75A4B setter|5099E4|509A04| +|Registry sentinel pointer|473740 /73740 load|50999C|5099BC| +|Viewport seconds|47374F /7374F load|696030|696050| +|Current game complete pointer|46E360 /6E360 store|509948|509968| +|Shared skip|430F3E /30F3E store|4F83E4|4F8404| +|Input block|426062 /26062 load|4F8430|4F8450| +|Modal gate|407060 /7060 load|4F8198|4F81B8| +|Skip suppression|430F11 /30F11 compare|4F8182|4F81A2| + +Registry nodes are `{next,previous,payload}` at offsets0/4/8, from the recovered +46FF4A..46FF7F insertion and473740 traversal. Traversal stops at the sentinel, +1024 nodes, an unreadable node or a repeated payload. `complete:false` means the +sample cannot establish the whole list; mutation during a read is possible. +Jimmy is recognized by game-interface vtable4A373C. The current game registry +payload is its complete pointer+8C. A successful full-list sample records their +actual indices without executing either actor or inferring constructor order. + +Jimmy samples use the game interface: current Euler224..230, destination274..280, +dirtyA, movement mode704, stored turn614, and action latch1D40 (=complete1E00). +Support fields13F and4A0 are reported separately as cached and force-support +bytes: actual458960 reads4A0 first, otherwise471A10 reads13F. They are not an +executed support query. The source addresses are code-field contracts, not +guessed layouts or corresponding fields from the modern simulation. + +## Output and ordinary input + +Output is bounded JSONL on stdout: authenticated identity, registry changes, +nominal10ms state samples, optional normal input events, finish and completion +marker. `Sleep(10)` is a sampling request, not a guaranteed interval or a game +clock. Each record includes actual elapsed wall-clock milliseconds. Floating +point NaN/infinity is written as JSON null. Narrow Win32 path/title bytes outside +ASCII are escaped so the output remains valid JSON; use ASCII generated paths +for reliable cross-machine reproduction. + +`valid_mask` uses bits0..3 for readable skip/input/modal/suppression bytes, bit4 +for readable viewport delta, and bit5 for a readable full Jimmy field block. +Zero values without the corresponding valid bit are placeholders, not evidence +that the game state was zero. Jimmy fields are omitted without bit5. + +By default no keys are sent. `--menu-keys` explicitly opts into ordinary Return +presses at approximately3/6/9s, each held100ms while sampling continues. It finds +only the child process's visible unowned window, requests normal window focus, +and uses `SendInput` only when that window is foreground. Records include title, +window/foreground handles, press/release and events accepted by `SendInput`. +Accepted events do not prove that the game's input system consumed them or that +a particular menu item was selected. This sequence is not a recovered New Game +macro. `--copied-game-menu=` is an explicit single-argument equivalent for +the existing capture wrapper, which passes one `--probe-model` argument. + +Samples consist of multiple independent reads without suspending the game. They +can miss transitions shorter than the interval and can mix adjacent callbacks. +They establish observed retained state and list membership; they cannot alone +prove the first writer, same-frame control order, exact input/controller order, +physics chronology, or the complete Carl skip lifecycle. A black screenshot is +still not a usable visual reference even if process state can be read. + +## Build and use + +From GamePort: + +```sh +mkdir -p artifacts/original-state-observer +i686-w64-mingw32-gcc -std=c11 -O2 -Wall -Wextra -Werror \ + tools/recon/original_state_observer.c -lbcrypt \ + -o artifacts/original-state-observer/observer.exe +python3 tools/recon/reference_capture.py --asset-probe \ + --probe-executable artifacts/original-state-observer/observer.exe \ + --probe-model=--copied-game=NeutronHDnoCD.exe \ + --probe-success ORIGINAL_STATE_OBSERVER_COMPLETE --seconds 24 \ + --output artifacts/original-state-observer/capture +``` + +The observer itself defaults to15s and accepts `--seconds=1..120` on native +Windows. For normal +input opt-in, substitute +`--probe-model=--copied-game-menu=NeutronHDnoCD.exe` above. Original variants with +a CD prompt may not proceed to gameplay in this environment; no prompt bypass or +executable modification is implemented by this tool. + +On native Windows, first start an ordinary generated copy and reach the desired +Carl/tutorial route. Obtain that game's process ID, then start the observer from +a separate terminal, redirecting stdout to a local trace: + +```text +observer.exe --attach-copied-pid=1234 --seconds=60 > carl-original.jsonl +``` + +Replace1234 with the copied game's actual PID. The existing session is left +running and receives no observer-generated input or close request. `--help` +prints usage without opening a file or process. The same process path/hash +restrictions apply even if another executable is named Neutron.exe. + +Initial verification: MinGW32 compilation with all warnings treated as errors +passes. All24 independently PE-mapped source anchors (8 per supported subject) +match; artifacts/original-state-observer/source-guards.json records original +hashes, exact bytes, addresses and file offsets. These are compilation/static +checks only. The primary investigator owns subsequent isolated runtime captures, +integration, additional evidence and any commit. + +## Integrated Wine32 observation + +The primary's generated-copy launch and focus/Return checks reach MAIN only: +game-interface table4D0C0C, no Jimmy, black captures. An isolated xfwm4 desktop +does not produce a usable gameplay reference. Viewport delta0 here does not prove +the menu selected New Game or that menu/engine clocks share the gameplay clock. + +The final attach revision is exercised by +`tools/recon/original_observer_smoke.c`. This Wine-only driver requires the +wrapper's generated `Z:\work\game` directory, launches the supplied HDnoCD +copy, then attaches the observer for10s. It verifies observer exit0 and that the +original remains active afterward, before sending its own child's ordinary close. +The observer itself sends no input or close in attach mode.928 JSON samples parse, +the exact live guards pass, and capture wineExit0 plus both completion markers +are present. MAIN only is observed; this is API/tool validation, not a Carl trace. + +The tested observer source/build hashes, driver identity, logs/capture metadata +and parsed summary are in +`artifacts/original-state-observer/attach-runtime/observations.json`. The initial +launch capture lacked a pre-recorded observer executable hash and includes a +Wine diagnostic interleaved with JSON; it is retained separately as a limited +functional observation. The final attach capture has explicit build provenance +and928 intact samples. Native Windows execution remains unverified. + +Reproduce after building the observer and driver, using the already prepared +generated Wine copy/prefix (no source original is mounted): + +```sh +i686-w64-mingw32-gcc -std=c11 -O2 -Wall -Wextra -Werror \ + tools/recon/original_observer_smoke.c -o artifacts/original-state-observer/attach-smoke.exe +cp artifacts/original-state-observer/observer.exe artifacts/jimmy-skip-original-sw/observer-under-test.exe +python3 tools/recon/reference_capture.py --asset-probe \ + --probe-executable artifacts/original-state-observer/attach-smoke.exe \ + --probe-success ORIGINAL_OBSERVER_ATTACH_COMPLETE --seconds 18 \ + --output artifacts/jimmy-skip-original-sw +``` + +Primary's launch observation, before attach support: separate HDnoCD profile +passes all live guards; normal focused menu input and an isolated window manager +still yield only MAIN (game index0, interface vtable4D0C0C), no Jimmy, and delta0. +The final run recorded2042 samples across22.02s. This validates the observer's +bounded launch/read path under Wine, not original gameplay or Carl's return. +Attach support was added for a reference machine where the user can reach the +route before starting a bounded trace. Its strict compilation/source checks are +separate from native Windows attach execution, which remains unverified here. diff --git a/docs/progress.md b/docs/progress.md index d217fa4..1a3ba16 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -1,4 +1,4 @@ -# Progress — 2026-11-05 +# Progress — 2026-11-06 Workflow update: the user authorizes pushing completed, verified commits to the existing `Gitea/main` upstream from now on. See docs/decisions.md and AGENTS.md. @@ -7,6 +7,23 @@ Next-work plan: [recover interactions, then implement verified changes](checkpoi It defines the Carl source/differential gate, the bounded implementation step, movement/contact/animation recovery and the end-to-end platform checkpoint. +## Carl lifecycle investigation and original-state observer + +The accepted plan is underway; its gameplay correction gate remains open. +[Integrated lifecycle trace](gameplay/jimmy-cutscene-lifecycle.md) records292 new +bounded original-code cases:96 contact,8 input/controller/skip-prefix,48 task/ +objective and140 base/STOP. Complete DEFAULT pseudocode is recovered through a +verified mapped analysis carrier. None supplies a source-supported movement reset; +the original components reproduce the port's order-sensitive stale-bank writer. + +A read-only Windows32 observer now launches or attaches to a verified **copied** +original. Wine32 attach/read/leave-running integration passes928 samples, with +observer exit0 and original still running. Local original rendering remains black: +only MAIN, no Jimmy/gameplay reference, was observed. Native Windows Carl state, +actual entry mode/turn, registry order and first-resume timing remain required. +All539 originals are unchanged. Runtime a2e89c6/packages dae13ac and the48-case +port diagnostic remain unchanged; no new gameplay fix or fidelity claim is made. + ## Decompilation first: Carl skip-to-idle remains open User reports the remaining tilt after skipping Carl and confirms original landing diff --git a/docs/reference-testing.md b/docs/reference-testing.md index 80d135f..408119a 100644 --- a/docs/reference-testing.md +++ b/docs/reference-testing.md @@ -37,6 +37,26 @@ No native Windows installation/VM or Windows 98 image was available in the initi environment/tool inventory. A local reference machine remains necessary if Wine cannot render correctly. Native Windows port execution remains separately untested. +2026-11-06 follow-up: a fresh generated prefix initially lacked Wine builtin +modules; missing files were copied only from the already-installed local Wine +tree. Missing32-bit EGL/GBM/Wayland libraries were downloaded into the local cache +and extracted under `.tools/native`, without a system installation. The supplied +HDnoCD variant then creates its window without the earlier GL-context failure, +but frames remain black. The normal Return/focus check and optional +`--managed-desktop` (isolated `dbus-run-session`/xfwm4) do not establish playable +startup. This is a different observed failure boundary, not a usable reference. +Canonical Neutron/HD also encounter a CD prompt; no executable patch is applied. + +[Read-only state observer](gameplay/original-state-observer.md) now supports a +verified copied-original launch or attach. Its Wine32 attach smoke passes928 +samples and leaves the original running. Only MAIN, no Jimmy, was observed; +native Windows Carl skip/return remains unverified. Variant identities, mappings, +probe build/log hashes and setup details stay local in +artifacts/original-state-observer/ and artifacts/jimmy-skip-original-sw/. +`--probe-arg=VALUE` forwards repeatable generated-probe arguments, including +option-shaped arguments, and `probe-identity.json` binds the executable hash and +arguments before capture; a changed probe hash invalidates the observation. + ## Preliminary Windows-port smoke under Wine64 `python3 tools/recon/reference_capture.py --port-smoke --seconds 24 --debug` diff --git a/docs/tasks.md b/docs/tasks.md index 24c47ee..1e4583a 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -48,6 +48,17 @@ compile, runtime and original-fidelity verification are separate. Execution order and acceptance criteria: [next work plan](checkpoint/next-work-plan.md). +- [x] Expand original lifecycle coverage:96 Carl contact,8 composed input/ + controller/skip-prefix,48 task/objective and140 base/STOP cases; recover complete + DEFAULT pseudocode through a mapped carrier. See gameplay/jimmy-cutscene-lifecycle.md. +- [x] Implement copied-original read-only launch/attach observation; verify actual + Wine32 attach,928 samples and leave-running behavior. Three exact subject profiles + have24 source anchors. Native Windows remains separate. +- [ ] Capture the actual original Carl banked-entry/skip/neutral-return interval. + Local Wine reaches MAIN with black frames and no Jimmy; the composed original + routines do not establish a reset. Use the observer on a working copied original + before changing gameplay. Preserve ordinary landing bank. + - [ ] Current user direction: decompile the complete Carl skip-to-idle state lifecycle before further gameplay implementation. Preserve a2e89c6/dae13ac. Close original support/mode/turn/input/skip ownership and same-frame ordering; diff --git a/tools/binary/default_raw_carrier.py b/tools/binary/default_raw_carrier.py new file mode 100644 index 0000000..9441b32 --- /dev/null +++ b/tools/binary/default_raw_carrier.py @@ -0,0 +1,59 @@ +#!/usr/bin/env python3 +"""Map verified original sections into a static Ghidra carrier at DEFAULT. + +This is analysis input, not a runnable executable or a loaded-process image. +It preserves initialized section bytes and zero-fills virtual gaps/tails. +""" +import argparse +import hashlib +import json +from pathlib import Path + +from checkpoint_script_state import EXE_SHA256, find_case +from pe_inspect import PE + +START = 0x447CF0 + + +def generate(original, output): + original, output = Path(original).resolve(), Path(output).resolve() + if output.is_relative_to(original) or original.is_relative_to(output): + raise ValueError('Output must be separate from originals') + pe = PE(find_case(original, 'Neutron.exe')) + if hashlib.sha256(pe.data).hexdigest() != EXE_SHA256: + raise ValueError('Unexpected original executable') + end = max(pe.base+s['rva']+max(s['virtual_size'], s['raw_size']) + for s in pe.sections) + if not START < end <= START+16*1024*1024: + raise ValueError('Unexpected source image extent') + carrier = bytearray(end-START) + ranges = [] + for section in pe.sections: + a = max(START, pe.base+section['rva']) + b = min(end, pe.base+section['rva']+section['raw_size']) + if a >= b: + continue + offset = pe.offset(a-pe.base) + source = pe.data[offset:offset+b-a] + if len(source) != b-a: + raise ValueError('Truncated source section') + carrier[a-START:b-START] = source + ranges.append(dict(source_offset=offset, va=a, length=b-a, + carrier_offset=a-START)) + result = dict(source_sha256=EXE_SHA256, + carrier_sha256=hashlib.sha256(carrier).hexdigest(), + start=hex(START), end=hex(end), ranges=ranges, + scope='Static raw analysis carrier with original byte mappings ' + 'and zero virtual tails, not an executable or runtime capture.') + output.mkdir(parents=True, exist_ok=True) + (output/'default.bin').write_bytes(carrier) + (output/'mapping.json').write_text(json.dumps(result, indent=2)+'\n') + return result + + +if __name__ == '__main__': + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('original', type=Path) + parser.add_argument('--output', required=True, type=Path) + args = parser.parse_args() + print(json.dumps(generate(args.original, args.output), indent=2)) diff --git a/tools/binary/jimmy_base_return.py b/tools/binary/jimmy_base_return.py new file mode 100644 index 0000000..3c41b50 --- /dev/null +++ b/tools/binary/jimmy_base_return.py @@ -0,0 +1,147 @@ +#!/usr/bin/env python3 +"""Read-only original base/facing/animation return guards and probe generator.""" +import argparse +import hashlib +import json +from pathlib import Path +import re +import struct +import subprocess + +from checkpoint_script_state import EXE_SHA256, find_case, read_va +from pe_inspect import PE + +REA_ID = 'ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904' +RANGES = ((0x40e050, 0x40e1c8), (0x462520, 0x462649), + (0x458930, 0x45893d), (0x473240, 0x473298), + (0x43a420, 0x43a5cd), (0x472480, 0x472570), (0x4732b0, 0x47331d), + (0x43a900, 0x43aa38), (0x424600, 0x424d10), + (0x43b28a, 0x43b2f4), (0x42afc0, 0x42aff0), (0x43a750, 0x43a786), + (0x43aff0, 0x43b5a2), (0x40dd90, 0x40df7c), (0x40da30, 0x40daad), + (0x462270, 0x462331), (0x429a00, 0x429a25)) +SLOTS = ((0x4a3bdc, 0x104, 0x43a900), (0x4a3bdc, 0x100, 0x40df80), + (0x4a3bdc, 0xe0, 0x40dd90), (0x4a373c, 0x3d8, 0x43a420), + (0x4a373c, 0x3d4, 0x4732b0), (0x4a373c, 0x210, 0x4719f0), + (0x4a373c, 0x338, 0x472570), (0x4a373c, 0x410, 0x42afc0), + (0x4a3bdc, 0x150, 0x43aff0), (0x4a3bdc, 0xe4, 0x40da30), + (0x4a3bdc, 0xc8, 0x462270), (0x4a3bdc, 0x148, 0x429a00), + (0x4a373c, 0x110, 0x471240), (0x4a373c, 0x2e0, 0x4720c0), + (0x4a373c, 0x2e8, 0x472120)) + + +def generate(original, output, rea): + original, output = Path(original).resolve(), Path(output).resolve() + if output.is_relative_to(original) or original.is_relative_to(output): + raise ValueError('Separate output required') + pe = PE(find_case(original, 'Neutron.exe')) + if hashlib.sha256(pe.data).hexdigest() != EXE_SHA256: + raise ValueError('Original EXE identity') + evidence = next(r for r in json.loads(Path(rea).read_text())['records'] + if r['evidence_id'] == REA_ID) + if evidence['subject']['digest']['sha256'] != EXE_SHA256: + raise ValueError('REA subject identity') + for table, slot, expected in SLOTS: + actual, = struct.unpack(' 1e-6: + raise ValueError('Retained state mismatch') + if line.startswith('CASE '): + ready, loop, last = (int(row[k]) for k in ('ready', 'loop', 'last')) + eligible = ready == 2 and not loop and last + special = row['action'] in ('FENCE', 'LADDER') + changed = special or row['action'] in ('HIT', 'SPLAT') + if int(row['ended']) != (180 if eligible else 0): + raise ValueError('End callback count') + if int(row['selected']) != int(eligible and changed): + raise ValueError('Selection count') + for field in ('stop', 'restore', 'enable'): + if int(row[field]) != int(eligible and special): + raise ValueError('Special cleanup count') + if row['current'] != '0,155,0' or row['target'] != '0,155,0': + raise ValueError('Euler publication') + base.append(row) + else: + if int(row['ticks']) != 180: + raise ValueError('Post-STOP base update count') + eligible = int(row['ready']) and (int(row['direct']) or row['prior'] in ('TALK', 'FALL')) + bound = int(bool(eligible) and bool(int(row['found']))) + if int(row['lookup']) != int(bool(eligible)) or int(row['shape']) != int(bool(eligible)): + raise ValueError('STOP acceptance path') + if any(int(row[k]) != bound for k in ('anim', 'frames', 'pauses')): + raise ValueError('STOP resource path') + if row['final'] != ('STOP' if eligible else row['prior']): + raise ValueError('STOP final action') + stop.append(row) + if len(base) != 84 or len(stop) != 56: + raise ValueError('Incomplete finite case matrix') + provenance = {} + for name, path in [('generated_source', output/'jimmy_base_return_probe.c'), + ('executable', output/'probe.exe'), + ('log', capture/'wine.log'), ('capture', capture/'capture.json'), + ('source_contract', output/'source.json')]: + provenance[name] = dict(path=str(path), sha256=hashlib.sha256(path.read_bytes()).hexdigest()) + result = dict(source_sha256=EXE_SHA256, rea_evidence_id=REA_ID, + base_cases=base, stop_cases=stop, provenance=provenance, + scope='140 bounded copied-original cases; synthetic body/resources, not full original gameplay.') + (output.parent/'native-observations.json').write_text(json.dumps(result, indent=2)+'\n') + return dict(base_cases=len(base), stop_cases=len(stop), wine_exit=0) + + +if __name__ == '__main__': + cli = argparse.ArgumentParser(description=__doc__) + cli.add_argument('original', type=Path) + cli.add_argument('--output', type=Path, required=True) + cli.add_argument('--rea', type=Path, required=True) + cli.add_argument('--capture', type=Path) + args = cli.parse_args() + result = generate(args.original, args.output, args.rea) + if args.capture: + result['observations'] = observations(args.output, args.capture) + print(json.dumps({k: v for k, v in result.items() if k != 'rea_extracts'}, indent=2)) diff --git a/tools/binary/jimmy_base_return_probe.c b/tools/binary/jimmy_base_return_probe.c new file mode 100644 index 0000000..76e2984 --- /dev/null +++ b/tools/binary/jimmy_base_return_probe.c @@ -0,0 +1,133 @@ +/* Actual animated base + common object + facing + animation-ended callback. + Synthetic body/resource records; no world, full Jimmy frame or renderer. */ +#define main unused_scalar_main +#include "grappler_scalar_probe.c" +#undef main + +typedef struct { float x,y,z,w; } Vec4; +static uintptr_t game[0x450/4], complete[0x220/4], morph[0x30/4]; +static unsigned char record[0x50]; +static unsigned char bounds_shape[0x60], definition[0x40]; +static uintptr_t bounds_table[0x50/4]; +static int found, lookups, bound_shapes, bound_anims, frame_sets, pauses; +static int frame_pos, ended, selected, stopped, restored, enabled; +#define OF(o) (*(float*)(object+(o))) +#define GF(o) OF(0xc0+(o)) +#define MODE (*(short*)(object+0x7c4)) + +static void fix(uint32_t a,uint32_t b){ + const uint32_t targets[]={/* RELOCATIONS */}; + for(;a+4<=b;a++){ + uint32_t v;memcpy(&v,AT(a),4); + for(unsigned i=0;iContextRecord->Eip,e->ContextRecord->Eip-(uintptr_t)mapped+0x400000, + e->ExceptionRecord->ExceptionCode,e->ExceptionRecord->ExceptionInformation[1]); + ExitProcess(2);return EXCEPTION_CONTINUE_SEARCH; +} +static int TC get_frame(void*self){require(self==object+0x90,"morph subobject");return frame_pos;} +static void TC anim_ended(void*self){require(self==object,"complete callback");ended++;((void(TC*)(void*))AT(0x43a900))(self);} +static void TC select_animation(void*self,const char*name,int force){ + require(self==object,"select receiver");(void)force;selected++; + strncpy((char*)object+0x5e8,name,31);object[0x5e8+31]=0; +} +static void TC stop_motion(void*self){require(self==object+0xc0,"stop receiver");stopped++;} +static void TC restore_position(void*self,Vec4 v){require(self==object+0xc0,"position receiver");memcpy(object+0x2d4,&v,sizeof(v));restored++;} +static void TC enable_body(void*self,int value){require(self==object+0xc0&&value==1,"enable receiver");enabled++;} +static void*TC find_record(void*self,const char*name){require(self==object&&!strcmp(name,"HISTOP"),"record lookup");lookups++;return found?record:NULL;} +static void TC bind_shape(void*self,void*value){require(self==object&&value==bounds_shape,"shape binding");*(void**)(object+0x8c)=value;bound_shapes++;} +static void TC bind_anim(void*self,void*value){require(self==object&&value==definition,"animation binding");bound_anims++;} +static void TC set_frame(void*self,int frame,int loop){require(self==object+0x90&&frame==0&&loop==1,"frame selection");*(int*)(object+0xa0)=frame;frame_pos=frame;frame_sets++;} +static void TC set_pause(void*self,int value){require(self==object+0x90&&value==1,"animation pause");pauses++;} +static void TC shape_bounds(void*self,float*x1,float*y1,float*z1,float*x2,float*y2,float*z2){ + require(self==bounds_shape,"shape bounds");*x1=-10;*y1=0;*z1=-20;*x2=10;*y2=70;*z2=20; +} +static void stop_suite(void){ + complete[0xe0/4]=(uintptr_t)AT(0x40dd90);complete[0xe4/4]=(uintptr_t)AT(0x40da30); + complete[0xdc/4]=(uintptr_t)find_record;complete[0xc0/4]=(uintptr_t)bind_anim; + complete[0xc8/4]=(uintptr_t)AT(0x462270);complete[0x148/4]=(uintptr_t)AT(0x429a00); + complete[0x150/4]=(uintptr_t)AT(0x43aff0); + game[0x260/4]=(uintptr_t)AT(0x471b30);game[0x264/4]=(uintptr_t)AT(0x471b40); + game[0x278/4]=(uintptr_t)AT(0x471ba0);game[0x2c4/4]=(uintptr_t)AT(0x471f40); + game[0x110/4]=(uintptr_t)AT(0x471240);game[0x2e0/4]=(uintptr_t)AT(0x4720c0);game[0x2e8/4]=(uintptr_t)AT(0x472120); + morph[0x10/4]=(uintptr_t)set_frame;morph[0x24/4]=(uintptr_t)set_pause; + bounds_table[0x44/4]=(uintptr_t)shape_bounds;*(void**)bounds_shape=bounds_table;*(float*)(bounds_shape+0x4c)=80; + *(void**)AT(0x48d198)=bind_shape; + const char*actions[]={"STOP","TALK","FALL","HIT","SPLAT","FENCE","LADDER"}; + for(unsigned a=0;aContextRecord->Eip,e->ContextRecord->Eip-(uintptr_t)mapped+0x400000,e->ExceptionRecord->ExceptionCode);fprintf(stderr,"fault=%lx eax=%lx ecx=%lx edx=%lx esi=%lx esp=%lx\n",e->ExceptionRecord->ExceptionInformation[1],e->ContextRecord->Eax,e->ContextRecord->Ecx,e->ContextRecord->Edx,e->ContextRecord->Esi,e->ContextRecord->Esp);ExitProcess(2);return EXCEPTION_CONTINUE_SEARCH;} +#define OF(o) (*(float*)(object+(o))) +#define GF(o) OF(0xc0+(o)) +#define MODE (*(short*)(object+0x7c4)) +static void fix(uint32_t a,uint32_t b){ + const uint32_t targets[]={/* RELOCATIONS */}; + for(;a+4<=b;a++){uint32_t v;memcpy(&v,AT(a),4);for(unsigned i=0;i0?357:3;GF(0x274)=-40;GF(0x278)=153;GF(0x27c)=-sign*11.666668f; + *(void**)(object+0xa18)=menu_object;*(int*)(object+0xa3c)=-1; + actions=moves=stops=0; + printf("CASE order=%s skip=%d sign=%d\n",after?"retained":"fresh",skip,sign);snap("before_entry"); + flatten();snap("after_entry"); + ((void(TC*)(void*,void*))AT(0x475a40))(NULL,NULL); + for(int i=0;i<180;i++)((void(TC*)(void*,float))AT(0x437940))(object+0xc0,1.f/60); + snap("locked"); + if(skip)skip_prefix(); + snap("after_skip_prefix"); + ((void(TC*)(void*,void*))AT(0x475a40))(NULL,object+0xc0);*AT(0x4f83e4)=0;snap("control_granted"); + if(after){((void(TC*)(void*,float))AT(0x437940))(object+0xc0,1.f/60);snap("first_player");((void(TC*)(void*,float))AT(0x438a60))(object+0xc0,1.f/60);snap("first_input");} + else {((void(TC*)(void*,float))AT(0x438a60))(object+0xc0,1.f/60);snap("first_input");((void(TC*)(void*,float))AT(0x437940))(object+0xc0,1.f/60);snap("first_player");} + for(int i=0;i<300;i++){ + if(after)((void(TC*)(void*,float))AT(0x437940))(object+0xc0,1.f/60); + ((void(TC*)(void*,float))AT(0x438a60))(object+0xc0,1.f/60); + if(!after)((void(TC*)(void*,float))AT(0x437940))(object+0xc0,1.f/60); + }snap("after_idle"); +} +int main(void){ + setbuf(stdout,NULL);map_source();AddVectoredExceptionHandler(1,exception); + const uint32_t ranges[][2]={{0x437940,0x437c3a},{0x438a60,0x438ba2},{0x439900,0x439e33},{0x43915d,0x4395cf},{0x43a420,0x43a5cd},{0x472480,0x472570},{0x475a40,0x475a4c},{0x431518,0x431590},{0x430f1d,0x430f5c},{0x429910,0x429963}}; + for(unsigned i=0;i= required and (pickup or removed == -1 or state < removed) + qualifier = 'if pickup state is uncollected' if pickup else 'own actor' + return ('enable' if enabled else 'disable')+' '+qualifier + + +def collect(original, rea): + original = Path(original) + pe = PE(find_case(original, 'Neutron.exe')) + if hashlib.sha256(pe.data).hexdigest() != EXE_SHA256: + raise ValueError('Unexpected original executable') + record = next(r for r in json.loads(Path(rea).read_text())['records'] + if r['evidence_id'] == REA_ID) + if record['subject']['digest']['sha256'] != EXE_SHA256: + raise ValueError('Retained REA subject mismatch') + calls, sites, slots = [], [], [] + for name, va, target in CALLS: + if rel_call_target(pe, va) != target: + raise ValueError(f'Changed direct call: {name}') + calls.append(dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)), + target=hex(target))) + for name, va, expected in SITES: + actual = read_va(pe, va, len(bytes.fromhex(expected))).hex() + if actual != expected: + raise ValueError(f'Changed source site: {name}: {actual}') + sites.append(dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)), + bytes=actual)) + for name, table, slot, target in SLOTS: + actual, = struct.unpack(' +#include +#include + +static BOOL CALLBACK close_owned(HWND window, LPARAM pid) { + DWORD owner = 0; + GetWindowThreadProcessId(window, &owner); + if (owner == (DWORD)pid && IsWindowVisible(window)) PostMessageA(window, WM_CLOSE, 0, 0); + return TRUE; +} + +int main(void) { + STARTUPINFOA start = {0}; + PROCESS_INFORMATION game = {0}, observer = {0}; + char cwd[MAX_PATH], command[256]; + DWORD code = 1, game_code = 0; + setbuf(stdout, NULL); + /* This driver deliberately works only at the generated Wine wrapper path. */ + if (!GetCurrentDirectoryA(sizeof(cwd), cwd) || _stricmp(cwd, "Z:\\work\\game")) return 2; + start.cb = sizeof(start); + strcpy(command, "NeutronHDnoCD.exe"); + if (!CreateProcessA(command, command, NULL, NULL, FALSE, 0, NULL, cwd, &start, &game)) return 3; + CloseHandle(game.hThread); + Sleep(1000); + snprintf(command, sizeof(command), "Z:\\work\\observer-under-test.exe --attach-copied-pid=%lu --seconds=10", game.dwProcessId); + if (!CreateProcessA("Z:\\work\\observer-under-test.exe", command, NULL, NULL, FALSE, 0, NULL, cwd, &start, &observer)) return 4; + CloseHandle(observer.hThread); + if (WaitForSingleObject(observer.hProcess, 20000) != WAIT_OBJECT_0) return 5; + GetExitCodeProcess(observer.hProcess, &code); + GetExitCodeProcess(game.hProcess, &game_code); + printf("OBSERVER_ATTACH_EXIT %lu ORIGINAL_STILL_RUNNING %d\n", code, game_code == STILL_ACTIVE); + /* Only the launcher-owned game receives an ordinary close, after the test. */ + EnumWindows(close_owned, game.dwProcessId); + CloseHandle(observer.hProcess); CloseHandle(game.hProcess); + if (code || game_code != STILL_ACTIVE) return 6; + puts("ORIGINAL_OBSERVER_ATTACH_COMPLETE"); + return 0; +} diff --git a/tools/recon/original_state_observer.c b/tools/recon/original_state_observer.c new file mode 100644 index 0000000..5ca2eb3 --- /dev/null +++ b/tools/recon/original_state_observer.c @@ -0,0 +1,407 @@ +/* Read-only, sampled original-state observer. It never patches target memory. + Launch only a generated game copy, with an explicitly attested path. + Build: i686-w64-mingw32-gcc -std=c11 -O2 -Wall -Wextra -Werror + tools/recon/original_state_observer.c -lbcrypt -o observer.exe + See docs/gameplay/original-state-observer.md for source identity and limits. */ +#define WIN32_LEAN_AND_MEAN +#define _WIN32_WINNT 0x0601 +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define MAX_NODES 1024 +#define GAME_BYTES 0x1d44 +#define CANONICAL_SHA "f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8" +#define HD_SHA "b6675b7e7f3fc37512185ddb4d6ce1fbe9a36c8b83f3b4b3ed6979a56db3d2d4" +#define HD_NOCD_SHA "8cd5d21997835a40978b8b83e344c97c92217bf6cd6858f7458b76935d64dedb" + +typedef struct { + const char *name, *sha; + uint32_t owner, registry, dt, current, skip, input, modal, suppression; +} Profile; +static const Profile profiles[] = { + {"canonical",CANONICAL_SHA,0x5099e4,0x50999c,0x696030,0x509948,0x4f83e4,0x4f8430,0x4f8198,0x4f8182}, + {"hd-resolution",HD_SHA,0x5099e4,0x50999c,0x696030,0x509948,0x4f83e4,0x4f8430,0x4f8198,0x4f8182}, + {"hd-nocd",HD_NOCD_SHA,0x509a04,0x5099bc,0x696050,0x509968,0x4f8404,0x4f8450,0x4f81b8,0x4f81a2} +}; + +typedef struct { uint32_t payload, vtable; } Node; +typedef struct { + uint32_t sentinel, current, owner, jimmy, count; + int current_index, jimmy_index, registry_complete; + Node nodes[MAX_NODES]; +} Registry; + +static int read_memory(HANDLE process, uint32_t address, void *dest, SIZE_T length) { + SIZE_T got = 0; + return address >= 0x10000 && + ReadProcessMemory(process, (const void *)(uintptr_t)address, dest, length, &got) && + got == length; +} + +static uint32_t u32(const unsigned char *p) { + return (uint32_t)p[0] | (uint32_t)p[1]<<8 | (uint32_t)p[2]<<16 | (uint32_t)p[3]<<24; +} + +static float f32(const unsigned char *p) { + uint32_t bits = u32(p); + float value; + memcpy(&value, &bits, sizeof(value)); + return value; +} + +static void json_float(float value) { + if (isfinite(value)) printf("%.9g", (double)value); + else fputs("null", stdout); +} + +static void json_string(const char *s) { + putchar('"'); + for (; *s; ++s) { + unsigned char c = (unsigned char)*s; + if (c == '\\' || c == '"') printf("\\%c", c); + else if (c < 32 || c >= 127) printf("\\u%04x", (unsigned)c); + else putchar(c); + } + putchar('"'); +} + +static int original_component(const char *path) { + while (*path) { + const char *begin; + size_t length; + while (*path == '\\' || *path == '/') ++path; + begin = path; + while (*path && *path != '\\' && *path != '/') ++path; + length = (size_t)(path-begin); + if (length == 8 && !_strnicmp(begin, "Original", 8)) return 1; + } + return 0; +} + +static int sha256(HANDLE file, char hex[65]) { + BCRYPT_ALG_HANDLE alg = NULL; + BCRYPT_HASH_HANDLE hash = NULL; + unsigned char buffer[16384], digest[32]; + DWORD got; + LARGE_INTEGER zero; + int ok = 0; + zero.QuadPart = 0; + if (!SetFilePointerEx(file, zero, NULL, FILE_BEGIN) || + BCryptOpenAlgorithmProvider(&alg, BCRYPT_SHA256_ALGORITHM, NULL, 0) < 0 || + BCryptCreateHash(alg, &hash, NULL, 0, NULL, 0, 0) < 0) goto done; + for (;;) { + if (!ReadFile(file, buffer, sizeof(buffer), &got, NULL)) goto done; + if (!got) break; + if (BCryptHashData(hash, buffer, got, 0) < 0) goto done; + } + if (BCryptFinishHash(hash, digest, sizeof(digest), 0) < 0) goto done; + for (unsigned i = 0; i < sizeof(digest); ++i) sprintf(hex+2*i, "%02x", digest[i]); + hex[64] = 0; + ok = 1; +done: + if (hash) BCryptDestroyHash(hash); + if (alg) BCryptCloseAlgorithmProvider(alg, 0); + return ok; +} + +/* The allow-listed hashes authenticate these anchors and all source offsets. + Retain an independent anchor check to detect an incorrectly mapped image. */ +static int operand_guard(HANDLE process, uint32_t pc, const unsigned char *expected, + size_t length, unsigned operand, uint32_t address) { + unsigned char actual[16], guarded[16]; + if (length > sizeof(actual) || operand+4 > length) return 0; + memcpy(guarded, expected, length); + for (unsigned i = 0; i < 4; ++i) guarded[operand+i] = (unsigned char)(address>>(8*i)); + return read_memory(process, pc, actual, length) && !memcmp(actual, guarded, length); +} + +static int runtime_identity(HANDLE process, const Profile *p) { + static const unsigned char setter[] = {0x8b,0x44,0x24,0x04,0xa3,0,0,0,0,0xc2,0x04,0x00}; + static const unsigned char registry[] = {0xa1,0,0,0,0,0x56,0x8b,0x30}; + static const unsigned char dt[] = {0x8b,0x15,0,0,0,0}; + static const unsigned char current[] = {0xa3,0,0,0,0}; + static const unsigned char skip[] = {0xc6,0x05,0,0,0,0,1}; + static const unsigned char input[] = {0xa0,0,0,0,0}; + static const unsigned char suppression[] = {0x38,0x1d,0,0,0,0}; + return operand_guard(process,0x475a40,setter,sizeof(setter),5,p->owner) && + operand_guard(process,0x473740,registry,sizeof(registry),1,p->registry) && + operand_guard(process,0x47374f,dt,sizeof(dt),2,p->dt) && + operand_guard(process,0x46e360,current,sizeof(current),1,p->current) && + operand_guard(process,0x430f3e,skip,sizeof(skip),2,p->skip) && + operand_guard(process,0x426062,input,sizeof(input),1,p->input) && + operand_guard(process,0x407060,input,sizeof(input),1,p->modal) && + operand_guard(process,0x430f11,suppression,sizeof(suppression),2,p->suppression); +} + +static void registry_snapshot(HANDLE process, const Profile *profile, Registry *r) { + uint32_t next, node[3]; + memset(r, 0, sizeof(*r)); + r->current_index = r->jimmy_index = -1; + if (!read_memory(process, profile->current, &r->current, 4) || + !read_memory(process, profile->owner, &r->owner, 4) || + !read_memory(process, profile->registry, &r->sentinel, 4) || + !read_memory(process, r->sentinel, &next, 4)) return; + while (next != r->sentinel && r->count < MAX_NODES) { + if (!read_memory(process, next, node, sizeof(node))) return; + for (uint32_t i = 0; i < r->count; ++i) + if (r->nodes[i].payload == node[2]) return; /* concurrent mutation/cycle */ + r->nodes[r->count].payload = node[2]; + if (!read_memory(process, node[2], &r->nodes[r->count].vtable, 4)) return; + if (node[2] == r->current+0x8c) r->current_index = (int)r->count; + if (r->nodes[r->count].vtable == 0x4a373c) { + r->jimmy = node[2]; + r->jimmy_index = (int)r->count; + } + ++r->count; + next = node[0]; + } + r->registry_complete = next == r->sentinel; +} + +static void print_registry(const Registry *r, ULONGLONG elapsed) { + printf("{\"kind\":\"registry\",\"elapsed_ms\":%llu,\"complete\":%s,\"sentinel\":%lu," + "\"current_game\":%lu,\"raw_owner\":%lu,\"jimmy\":%lu,\"game_index\":%d,\"jimmy_index\":%d,\"nodes\":[", + (unsigned long long)elapsed, r->registry_complete ? "true" : "false", + (unsigned long)r->sentinel, (unsigned long)r->current, (unsigned long)r->owner, + (unsigned long)r->jimmy, r->current_index, r->jimmy_index); + for (uint32_t i = 0; i < r->count; ++i) + printf("%s[%lu,%lu]", i ? "," : "", (unsigned long)r->nodes[i].payload, + (unsigned long)r->nodes[i].vtable); + puts("]}"); +} + +static void vector(const unsigned char *p) { + putchar('['); + for (unsigned i = 0; i < 4; ++i) { if (i) putchar(','); json_float(f32(p+4*i)); } + putchar(']'); +} + +static void print_sample(HANDLE process, const Profile *profile, const Registry *r, ULONGLONG elapsed) { + unsigned char actor[GAME_BYTES], flags[4], dt[4]; + const uint32_t addresses[] = {profile->skip,profile->input,profile->modal,profile->suppression}; + unsigned valid = 0; + memset(actor, 0, sizeof(actor)); + memset(flags, 0, sizeof(flags)); + memset(dt, 0, sizeof(dt)); + for (unsigned i = 0; i < 4; ++i) + if (read_memory(process, addresses[i], flags+i, 1)) valid |= 1u<dt, dt, 4)) valid |= 16; + if (r->jimmy && read_memory(process, r->jimmy, actor, sizeof(actor))) valid |= 32; + printf("{\"kind\":\"sample\",\"elapsed_ms\":%llu,\"valid_mask\":%u,\"raw_owner\":%lu,\"current_game\":%lu,\"jimmy\":%lu,\"dt\":", + (unsigned long long)elapsed, valid, (unsigned long)r->owner, + (unsigned long)r->current, (unsigned long)r->jimmy); + json_float(f32(dt)); + printf(",\"shared_skip\":%u,\"input_block\":%u,\"modal_gate\":%u,\"skip_suppression\":%u", + flags[0],flags[1],flags[2],flags[3]); + if (valid & 32) { + printf(",\"mode\":%d,\"turn\":", (int)(int16_t)(actor[0x704] | actor[0x705]<<8)); + json_float(f32(actor+0x614)); + printf(",\"dirty\":%u,\"action_latch\":%u,\"cached_support\":%u,\"force_support\":%u,\"current_euler\":", + actor[0xa], actor[0x1d40], actor[0x13f], actor[0x4a0]); + vector(actor+0x224); + fputs(",\"destination_euler\":", stdout); vector(actor+0x274); + } + puts("}"); +} + +static BOOL CALLBACK owned_window(HWND window, LPARAM parameter) { + DWORD pid; + DWORD *search = (DWORD *)parameter; + GetWindowThreadProcessId(window, &pid); + if (pid == search[0] && IsWindowVisible(window) && !GetWindow(window, GW_OWNER)) { + search[1] = (DWORD)(uintptr_t)window; + return FALSE; + } + return TRUE; +} + +static HWND find_window(DWORD pid) { + DWORD search[2] = {pid, 0}; + EnumWindows(owned_window, (LPARAM)search); + return (HWND)(uintptr_t)search[1]; +} + +static void menu_key(DWORD pid, ULONGLONG elapsed, int release) { + HWND window = find_window(pid); + HWND foreground; + INPUT event; + char title[256]; + DWORD thread = window ? GetWindowThreadProcessId(window,NULL) : 0; + unsigned sent = 0; + memset(&event, 0, sizeof(event)); + memset(title,0,sizeof(title)); + if (window) GetWindowTextA(window,title,sizeof(title)); + if (window && !release) { + int attached = thread != GetCurrentThreadId() && AttachThreadInput(GetCurrentThreadId(),thread,TRUE); + BringWindowToTop(window); SetForegroundWindow(window); SetActiveWindow(window); SetFocus(window); + if (attached) AttachThreadInput(GetCurrentThreadId(),thread,FALSE); + } + foreground = GetForegroundWindow(); + if (release || (window && foreground == window)) { + event.type = INPUT_KEYBOARD; event.ki.wVk = VK_RETURN; + event.ki.dwFlags = release ? KEYEVENTF_KEYUP : 0; + sent = SendInput(1, &event, sizeof(INPUT)); + } + printf("{\"kind\":\"normal_input\",\"elapsed_ms\":%llu,\"key\":\"Return\",\"release\":%s,\"events_sent\":%u,\"window\":%lu,\"foreground\":%lu,\"title\":", + (unsigned long long)elapsed, release?"true":"false",sent, + (unsigned long)(uintptr_t)window,(unsigned long)(uintptr_t)foreground); + json_string(title); puts("}"); +} + +static void usage(FILE *stream) { + fputs("Usage: observer.exe --copied-game= [--seconds=1..120] [--menu-keys]\n" + " observer.exe --copied-game-menu= (single-argument menu-input opt-in)\n" + " observer.exe --attach-copied-pid= [--seconds=1..120] (read-only, no input/close)\n" + "Each copied option explicitly attests that the selected executable is a generated copy outside Original.\n",stream); +} + +int main(int argc, char **argv) { + char path[32768], final[32768], directory[32768], hash[65], command[32772]; + HANDLE file; + STARTUPINFOA start; + PROCESS_INFORMATION child; + Registry previous, current; + unsigned seconds = 15, key_index = 0, samples = 0; + int keys = 0, previous_valid = 0, identified = 0; + DWORD attach_pid = 0; + int key_down = 0; + ULONGLONG key_began = 0; + const Profile *profile = NULL; + ULONGLONG began, elapsed; + DWORD exit_code = STILL_ACTIVE; + const char *target = NULL; + memset(&child,0,sizeof(child)); + if (argc == 2 && !strcmp(argv[1],"--help")) { usage(stdout); return 0; } + if (argc >= 2 && !strncmp(argv[1], "--copied-game=", 14)) target=argv[1]+14; + else if (argc >= 2 && !strncmp(argv[1], "--copied-game-menu=", 19)) { target=argv[1]+19; keys=1; } + else if (argc >= 2 && !strncmp(argv[1], "--attach-copied-pid=", 20)) { + char *end; + const char *number=argv[1]+20; + errno=0; + unsigned long pid=strtoul(number,&end,10); + if (!isdigit((unsigned char)*number) || *end || errno || !pid) return 2; + attach_pid=(DWORD)pid; + } + if ((!target || !*target) && !attach_pid) { + usage(stderr); + return 2; + } + for (int i = 2; i < argc; ++i) { + char *end; + if (!strncmp(argv[i], "--seconds=", 10)) { + unsigned long n = strtoul(argv[i]+10, &end, 10); + if (*end || n < 1 || n > 120) return 2; + seconds = (unsigned)n; + } else if (!strcmp(argv[i], "--menu-keys")) keys = 1; + else return 2; + } + if (attach_pid && keys) { + fputs("Attach mode never sends input; remove --menu-keys.\n",stderr); + return 2; + } + setbuf(stdout, NULL); + DWORD length; + if (attach_pid) { + child.hProcess=OpenProcess(PROCESS_VM_READ|PROCESS_QUERY_LIMITED_INFORMATION|SYNCHRONIZE,FALSE,attach_pid); + if (!child.hProcess) { fprintf(stderr,"OpenProcess failed: %lu\n",GetLastError()); return 2; } + child.dwProcessId=attach_pid; + length=sizeof(path); + if (!QueryFullProcessImageNameA(child.hProcess,0,path,&length) || !length || length>=sizeof(path)) { + fprintf(stderr,"QueryFullProcessImageName failed: %lu\n",GetLastError()); + CloseHandle(child.hProcess); return 2; + } + } else length=GetFullPathNameA(target, sizeof(path), path, NULL); + if (!length || length >= sizeof(path) || original_component(path)) { + fputs("Rejected target path: use an explicitly attested generated copy outside Original.\n", stderr); + if (child.hProcess) CloseHandle(child.hProcess); + return 2; + } + file = CreateFileA(path, GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL); + if (file == INVALID_HANDLE_VALUE) { + fprintf(stderr,"Cannot open copied game: %lu\n",GetLastError()); + if (child.hProcess) CloseHandle(child.hProcess); + return 2; + } + LARGE_INTEGER size; + if (!GetFileSizeEx(file,&size) || size.QuadPart != 1019904) { + fputs("Rejected target size.\n",stderr); CloseHandle(file); + if (child.hProcess) CloseHandle(child.hProcess); + return 2; + } + length = GetFinalPathNameByHandleA(file, final, sizeof(final), FILE_NAME_NORMALIZED); + if (sha256(file, hash)) + for (unsigned i = 0; i < sizeof(profiles)/sizeof(profiles[0]); ++i) + if (!strcmp(hash,profiles[i].sha)) profile = profiles+i; + if (!length || length >= sizeof(final) || original_component(final) || !profile) { + fputs("Rejected target identity/path; only explicitly supported verified source profiles are accepted.\n", stderr); + CloseHandle(file); + if (child.hProcess) CloseHandle(child.hProcess); + return 2; + } + /* Keep the authenticated file handle open without FILE_SHARE_WRITE/DELETE + through process creation, preventing target-file replacement after hashing. */ + if (!attach_pid) { + strcpy(directory, path); + char *slash = strrchr(directory, '\\'); + if (!slash) { CloseHandle(file); return 2; } + *slash = 0; + snprintf(command, sizeof(command), "\"%s\"", path); + memset(&start, 0, sizeof(start)); start.cb = sizeof(start); + if (!CreateProcessA(path, command, NULL, NULL, FALSE, 0, NULL, directory, &start, &child)) { + fprintf(stderr,"CreateProcess failed: %lu\n",GetLastError()); CloseHandle(file); return 2; + } + CloseHandle(child.hThread); + } + CloseHandle(file); + fputs("{\"kind\":\"identity\",\"target\":", stdout); json_string(path); + printf(",\"sha256\":\"%s\",\"profile\":\"%s\",\"pid\":%lu,\"attached\":%s,\"interval_ms\":10,\"duration_ms\":%u,\"scope\":\"read-only sampled process state; no callback-order or whole-frame guarantee\"}\n", + hash, profile->name, child.dwProcessId, attach_pid?"true":"false",seconds*1000); + began = GetTickCount64(); + do { + elapsed = GetTickCount64()-began; + if (WaitForSingleObject(child.hProcess, 0) == WAIT_OBJECT_0) break; + if (!identified) { + identified = runtime_identity(child.hProcess,profile); + if (!identified && elapsed > 5000) { + fputs("{\"kind\":\"error\",\"reason\":\"runtime source anchors unavailable after 5s; sampling refused\"}\n",stdout); + break; + } + } + if (identified) { + registry_snapshot(child.hProcess,profile,¤t); + if (!previous_valid || memcmp(¤t, &previous, sizeof(current))) { + print_registry(¤t, elapsed); previous = current; previous_valid = 1; + } + print_sample(child.hProcess,profile,¤t,elapsed); ++samples; + } + if (!attach_pid && key_down && elapsed-key_began >= 100) { + menu_key(child.dwProcessId,elapsed,1); key_down=0; + } + if (!attach_pid && keys && !key_down && key_index < 3 && elapsed >= (ULONGLONG)(key_index+1)*3000) { + menu_key(child.dwProcessId,elapsed,0); ++key_index; key_began=elapsed; key_down=1; + } + Sleep(10); + } while (elapsed < seconds*1000); + if (!attach_pid && key_down) menu_key(child.dwProcessId,GetTickCount64()-began,1); + GetExitCodeProcess(child.hProcess, &exit_code); + printf("{\"kind\":\"finish\",\"elapsed_ms\":%llu,\"samples\":%u,\"identified\":%s,\"game_exit\":%lu,\"left_running\":%s}\n", + (unsigned long long)(GetTickCount64()-began), samples, identified?"true":"false", + exit_code, exit_code == STILL_ACTIVE ? "true" : "false"); + /* Request ordinary shutdown only for this launcher-owned process. Do not + terminate it or enumerate/kill unrelated game or Wine processes. */ + if (!attach_pid && exit_code == STILL_ACTIVE) { + HWND window = find_window(child.dwProcessId); + if (window) PostMessageA(window, WM_CLOSE, 0, 0); + } + CloseHandle(child.hProcess); + if (!identified || !samples) return 3; + puts("{\"kind\":\"complete\",\"marker\":\"ORIGINAL_STATE_OBSERVER_COMPLETE\"}"); + return 0; +} diff --git a/tools/recon/reference_capture.py b/tools/recon/reference_capture.py index 8ff6d42..89a1329 100644 --- a/tools/recon/reference_capture.py +++ b/tools/recon/reference_capture.py @@ -7,6 +7,7 @@ writable inside the namespace, and the original directory is not mounted. """ import argparse import ctypes +import hashlib import json import os from pathlib import Path @@ -41,12 +42,14 @@ def inside(args): if args.port_smoke: (work/'port-frame.ppm').unlink(missing_ok=True) with (work/'xvfb.log').open('w') as xlog, (work/'wine.log').open('w') as wlog: display = subprocess.Popen(['/native/usr/bin/Xvfb', ':89', '-screen', '0', '1024x768x24', '-nolisten', 'tcp'], stdout=xlog, stderr=xlog) - wine = None + wine = manager = None try: for _ in range(30): if Path('/tmp/.X11-unix/X89').exists(): break if display.poll() is not None: raise RuntimeError('Xvfb failed; see xvfb.log') time.sleep(0.1) + if args.managed_desktop: + manager = subprocess.Popen(['dbus-run-session', '--', 'xfwm4', '--compositor=off'], stdout=xlog, stderr=xlog) wine_env = dict(os.environ, LIBGL_DRIVERS_PATH='/native/usr/lib/i386-linux-gnu/dri') application = ['/opt/wine-stable/bin/wine', args.game] if args.port_smoke: @@ -79,7 +82,7 @@ def inside(args): '--assets', r'Z:\port\assets', '--cutscene-audio-smoke', r'Z:\port\scenes\level1b\entities\entities.json'] if args.asset_probe: - application = ['/opt/wine-stable/bin/wine', r'Z:\probe.exe', args.probe_model] + application = ['/opt/wine-stable/bin/wine', r'Z:\probe.exe', args.probe_model, *args.probe_arg] wine = subprocess.Popen(application, cwd='/work' if args.port_smoke else '/work/game', stdout=wlog, stderr=wlog, env=wine_env) captures = [] for index in range(3): @@ -102,6 +105,7 @@ def inside(args): finally: subprocess.run(['/opt/wine-stable/bin/wineserver', '-k'], timeout=10, check=False) if wine and wine.poll() is None: wine.terminate() + if manager and manager.poll() is None: manager.terminate() display.terminate() display.wait(timeout=5) @@ -113,6 +117,7 @@ def main(): p.add_argument('--seconds', type=int, default=24) p.add_argument('--enter', action='store_true', help='Send Return after each screenshot') p.add_argument('--debug', action='store_true', help='Record Wine process and exception diagnostics') + p.add_argument('--managed-desktop', action='store_true', help='Run an isolated xfwm4 desktop for original focus/fullscreen diagnostics') p.add_argument('--wine-renderer', choices=['gl','vulkan'], default='gl') p.add_argument('--port-smoke', action='store_true', help='Preliminary Windows port check under Wine64; not native Windows validation') p.add_argument('--port-window', action='store_true', help='Windows port SDL window/input/resize/animation smoke under Wine64') @@ -124,6 +129,7 @@ def main(): p.add_argument('--port-regression', choices=['objectives', 'carl'], help='Windows lab popup or conversation runtime regression under Wine64') p.add_argument('--asset-probe', action='store_true', help='Run compiled read-only OMT shape probe inside isolated copy') p.add_argument('--probe-model', default=r'ASE\jimstop.ase') + p.add_argument('--probe-arg', action='append', default=[], help='Additional explicit argument for the generated component probe (repeatable)') p.add_argument('--probe-executable', type=Path, help='Local probe executable to mount read-only for --asset-probe') p.add_argument('--probe-success', default='VERTICES ', help='Required output marker for an isolated component probe') p.add_argument('--output', type=Path) @@ -136,6 +142,7 @@ def main(): if args.port_cutscene_audio and (args.port_practice or args.port_story or args.port_walk or args.port_window or args.port_jetpack): p.error('Select audio lifecycle or rendering check') if args.port_jetpack and (args.port_practice or args.port_story or args.port_walk or args.port_window): p.error('Select one jetpack or other port check') if args.probe_executable and not args.asset_probe: p.error('--probe-executable requires --asset-probe') + if args.probe_arg and not args.asset_probe: p.error('--probe-arg requires --asset-probe') if not 3 <= args.seconds <= 120: p.error('--seconds must be 3..120') if args.inside: return inside(args) project = Path(__file__).resolve().parents[2] @@ -163,6 +170,9 @@ def main(): if args.asset_probe: probe = (args.probe_executable or project/'artifacts/binary/omt_shape_probe.exe').resolve(strict=True) if probe.is_relative_to(source.resolve()): p.error('Probe must be a generated executable outside originals') + probe_identity = {'path': str(probe), 'sha256': hashlib.sha256(probe.read_bytes()).hexdigest(), + 'arguments': [args.probe_model, *args.probe_arg]} + (work/'probe-identity.json').write_text(json.dumps(probe_identity, indent=2)+'\n') cmd += ['--ro-bind', str(probe), '/probe.exe'] for key,value in {'HOME':'/work/home', 'WINEPREFIX':'/work/prefix', 'WINEARCH':'win64' if args.port_smoke else 'win32', 'DISPLAY':':89', 'PATH':'/opt/wine-stable/bin:/usr/bin:/bin', 'LANG':'C.UTF-8', @@ -180,6 +190,7 @@ def main(): cmd += ['--setenv', 'VK_DRIVER_FILES', '/native/usr/share/vulkan/icd.d/lvp_icd.json'] cmd += ['/usr/bin/python3', '/capture.py', '--inside', '--game', args.game, '--seconds', str(args.seconds)] if args.enter: cmd += ['--enter'] + if args.managed_desktop: cmd += ['--managed-desktop'] if args.port_smoke: cmd += ['--port-smoke'] if args.port_window: cmd += ['--port-window'] if args.port_walk: cmd += ['--port-walk'] @@ -188,7 +199,8 @@ def main(): if args.port_cutscene_audio: cmd += ['--port-cutscene-audio'] if args.port_jetpack: cmd += ['--port-jetpack'] if args.port_regression: cmd += ['--port-regression', args.port_regression] - if args.asset_probe: cmd += ['--asset-probe', '--probe-model', args.probe_model] + if args.asset_probe: cmd += ['--asset-probe', '--probe-model='+args.probe_model] + for argument in args.probe_arg: cmd += ['--probe-arg='+argument] print('Running isolated Windows port' if args.port_smoke else 'Running copied original', 'with no network and no original-directory mount:', work, flush=True) subprocess.run(cmd, check=True, timeout=args.seconds + 40) print('Capture metadata:', work/'capture.json') @@ -201,6 +213,8 @@ def main(): print('Windows port audio lifecycle passed under Wine; native Windows validation is still required' if args.port_cutscene_audio else 'Windows port rendered under Wine; native Windows validation is still required') if args.asset_probe: + if hashlib.sha256(probe.read_bytes()).hexdigest() != probe_identity['sha256']: + raise SystemExit('Probe executable changed during capture; observation identity is invalid') result = json.loads((work/'capture.json').read_text()) if result['captures'][-1]['wineExit'] != 0 or args.probe_success not in (work/'wine.log').read_text(): raise SystemExit('Original component probe did not complete; inspect wine.log')