Files
Neutron/docs/checkpoint/next-work-plan.md
T

11 KiB
Raw Blame History

Next work plan: recover interactions, then implement verified changes

2026-11-05. Proposed execution order following the user's request for a plan. 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 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.

Later execution update: menu/player lifetime closes the successful TSK story path's source ordering gate. MAIN loads a background Level1D/Jimmy; successful TSK load uses that controlled Jimmy and the ordinary retained-object loader. Program's first-story classification is corrected without another angle reset. Step3's first-neutral-tick/300-idle Vulkan and eight managed trajectories pass. Integrated/native SDL checks and clean ea04210 packages now pass, including4 identical standalone Linux readbacks and a preliminary isolated Wine64 Carl replay. All539 originals remain unchanged. Original Windows comparison remains a step5 obligation, not a completed claim. Step4's derived-caller/body-transform investigation is also recorded, with broader dynamic/special contacts and playback dependencies still open.

Step4 continuation: ordered pair lifecycle now has28 complete original/C# comparisons,6 new REA pseudocode results and20 guarded VR04 class bindings. The pair component is verified separately; scene admission remains gated on full physical registration/activation, real callbacks and shared reclip.

Registration continuation now covers all72 serialized VR04 records/13 interfaces and12 original registration/loader cases, plus21 guarded helper edges. This closes the bounded common registration and per-object loader contracts, not complete fresh/retained helper membership. See registration. Next resolve helper re-entry/deletion/activation and dynamic shared reclip state; keep live scene admission unchanged until those dependencies close.

2026-11-07 continuation: dynamic context executes17 original mode2/reclip cases and captures12 kernel triangle/normal arguments. Test-only C# composition matches complete snapshots, including retained old polygon and callback publication. Jeep default deletion eligibility is guarded, while cleanup mutations/children/order remain open. Next extend to nonempty static reclip and ordered-body context, then real actor callbacks and retained helper cleanup. Keep the current live solver and924ad2f packages while those gates remain.

Populated follow-up: dynamic reclip now matches14 complete observations and12 kernel steps. Direct source-store corrections remove two rounding divergences without admitting new actors. Next prioritize real Jimmy/ VR04 callback mutations and live getter timing, then constructor-only helper cleanup/order across LOAD/RETURN; integrate the bounded response only afterward.

Objective

Establish the original ownership and timing of player state across gameplay, contact, cutscenes, landing and level return, then correct the port in small, verified chunks. Start with the concrete reported failure: jump while banked, enter Carl's lab conversation, skip, release controls, remain upright afterward. Ordinary landing bank must remain faithful to the original, as the user confirmed.

1. Close the original Carl skip-to-idle sequence

Trace the actual supplied route: physical contact → Carl talk activation → neutron1a activation → accepted skip → Carlwalk → DEFAULT → first idle input and player update. Follow direct callers, virtual targets and registry positions through REA, checking the authoritative bytes and GAM records.

Record support, raw control owner, movement mode, stored turn, current Euler, destination Euler, dirty flag, skip state, action latch, input suppression and frame delta at every boundary. Include contact/support state before entry: the port's grouped contacts might start the scene with different retained state.

Investigate the concrete remaining gaps: skip input-latch consumption and release, per-camera completion order, same-frame control changes, and fresh/retained actor ordering. Reuse the three new pseudocode results and existing instruction Evidence. Keep the unresolved DEFAULT procedure boundary explicit; use its guarded assembly and a changed analysis strategy where necessary rather than repeat failed queries.

Deliverable: an annotated original event/state trace and a clear explanation of where the original prevents the stale airborne bank from being republished. A local no-reset result or another plausible hypothesis does not close this gate.

2. Compare the original sequence with the reproducible port failure

Extend the existing48-case diagnostic around the original boundaries. Use an isolated original-code composition with explicit synthetic dependencies and/or an original-game runtime capture from a generated copy where the available runtime supports it. Record limitations, including any callbacks not executed.

Compare fresh and retained ordering; grounded and airborne entry; Left/Right bank; neutral and held input; Escape/Space skip and natural completion. Natural completion is a separate comparison—the user's confirmed failure concerns skip. Keep source viewport seconds, morph/engine timing and the port's60Hz policy explicit rather than assuming they share one clock.

Deliverable: a differential trace naming the first meaningful divergence, its owner and its consequences. Expected outcomes must agree with original instructions/composition and the user's observation. If they conflict, specify the exact missing observation before changing gameplay.

3. Implement the supported cutscene correction

Resume runtime work once steps1–2 establish the missing transition or ordering. Change the smallest coherent owner/lifecycle boundary, retaining the existing playable movement baseline. Preserve normal landing bank, heading, queued body work and the separately recovered fire/control lifecycles.

Convert the reported skipped-Carl/neutral-return scenario into a regression that fails on the current baseline. Cover the first resumed frame and sustained idle, both insertion orders, natural completion, held-input return, and repeated scenes.

Done when: the source explanation and implementation agree; Jimmy remains upright after skipping Carl; legitimate landing bank remains; targeted movement, Director, jetpack and visual checks pass. State any remaining approximation.

4. Deepen the remaining movement interaction contracts

After closing Carl's lifecycle, prioritize the existing core-system gaps:

  1. Body/contact ownership: real Jimmy callbacks, dynamic pair eligibility, support admission, callback-mutated root/modes and successful fence/ladder or hazard paths. Preserve the lab/outside capsule until its replacement gate closes.
  2. Animation lifecycle: original action acceptance, playback clocks, completion callbacks and interruption across jump, land, STOP, talk, skip and control return.
  3. Shared camera/input state: final scripted eye, first resumed follow update, clipping, pause/menu/input gates and retained scene ordering.

Use each recovered transition to update the coverage map and remove a named assumption. Existing original arithmetic fixtures remain regression evidence; JN-Engine supplies original-decompiler leads, not replacement movement tuning.

Deliverable: per-system state/ownership contracts with addresses, file offsets, callers, dependencies, confidence and unresolved questions, plus bounded source probes where needed. Implement each supported correction as its own verified chunk.

5. Validate the route as one interacting system

Exercise lab → VR04 → lab → outside with fresh entry and RETURN. Include normal and skipped conversations, banked jumps, landing/idle, jetpack cleanup, held input, objectives, music/speech, camera handoff and persistent/reset state.

Run targeted checks for each change and the full suite at the integrated route checkpoint. Validate native Linux SDL/Vulkan, then obtain native Windows build feedback for the same scenarios. Compare original behavior where observed; managed tests, original components, Linux rendering and Windows execution remain separate evidence categories.

Done when: the route and reported bug pass the defined scenarios, original hashes remain unchanged, platform results/limits are recorded, and both packages identify a clean verified runtime commit. Push source/tools/docs to the approved Gitea remote; keep originals, generated traces and packages local.

6. Choose the next reconstruction checkpoint from the updated coverage map

Once movement and route handoffs are stable, rank the remaining audio/music, UI, progression/save-load and actor/AI gaps by how much existing gameplay they block. Recover and implement them in that dependency order. New gadgets and level-specific features stay behind the core movement/route checkpoint.

Deliverable: a short next-chunk plan based on measured gaps, with a concrete source question, implementation boundary and validation condition for each item. Do not require understanding every level before executing a supported core change.

Parallel work and ownership

Use two independent investigators when the questions are substantial:

  • Original input/skip/state ownership: jimmy-cutscene-return source report and its named binary analysis helpers.
  • Contact/registry/script ordering: jimmy-cutscene-chain-order source report and its named binary analysis helpers.

Primary owns the port diagnostic, integrated trace, coverage/status documents, runtime/test integration and commits. Establish exclusive ownership before work; review shared conclusions before editing gameplay. No investigator changes another's files or commits shared work.

Checkpoint discipline

Every checkpoint reports recovered facts, inference, current implementation, verification and open questions separately. Save Evidence/probe identities and findings on disk. Commit and push completed, verified milestones. Gameplay work remains paused until the Carl source/differential gate above is satisfied; this plan itself introduces no gameplay or package changes.