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

8.7 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/package validation is underway. 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.

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.