Files
Neutron/AGENTS.md
T

11 KiB

Neutron GamePort

Follow ../AGENTS.md and ../prompt.MD. This is the local Git repository. User workflow update (2026-11-05): push completed, verified commits to the existing Gitea remote; main tracks Gitea/main. This supersedes earlier no-remote/no-push rules. Keep builds/tests local; do not upload originals or generated packages or use cloud CI. Originals are in ../Original/ and must remain byte-identical; verify using python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json.

Use .NET 10, Silk.NET.Vulkan Vulkan 1.3+, SDL3 and shared Linux/Windows x64 code. Keep recovered data/algorithms distinct from unverified approximations. Require runtime evidence before claiming working gameplay or platform compatibility.

Working map

  • src/GamePort/: runtime, platform, rendering, assets and game systems.
  • tools/: Python analysis/extraction tools (stdlib where practical).
  • tests/: original-data regressions and bounded parser tests.
  • scripts/: local dependency, build, test and packaging entry points.
  • docs/: durable evidence and continuation notes.
  • .tools/, .nuget/, artifacts/, dist/: ignored local generated data.

Build from this directory with dotnet build, dotnet run; project-local SDK is selected by source scripts/env.sh (consult README for verified invocation). Python tests: python3 -m unittest discover -s tests -v. Local builds: scripts/build-linux.sh, scripts/build-windows.sh; tests: scripts/test.sh; packages: scripts/package.sh.

Coordination

Native subagents supported, max three investigators alongside primary. Explicit exclusive file ownership; primary reviews, integrates, tests and commits milestones. Binary agent: tools/binary/, binary/graphics analysis. Asset agent: extractors, asset/format docs, extractor tests. Infrastructure agent: runtime/build scripts and infrastructure report. Primary: GAM loader, gameplay/recon/docs and integration. Coordinate any ownership transfer before editing shared files. No agent commits other agents' active changes. Keep updates concise, save detailed evidence to disk.

Use bounded endian-aware parsers, portable paths, clear C#, deterministic tests, and explicit unmanaged ownership. Build frequently. Update docs/progress.md, docs/tasks.md, docs/decisions.md, and compatibility evidence before transitions. Current direction: preserve exact original movement; keep gameplay expansion paused. The menu/background→successful TSK-load lifetime now establishes retained Jimmy-before-level-input order on first story entry. Correct that initialization classification, preserving fresh direct-scene order and all movement/rotation algorithms. See docs/gameplay/main-menu-player-lifetime.md. The strengthened Vulkan Carl fixture reproduces the old first-neutral-tick bank and passes after the correction; broader/native Windows comparison remains separate. 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.

Pair continuation: docs/checkpoint/pair-lifecycle.md records28 complete original/ C# cases and20 VR04 class bindings. OriginalPairCollision is a bounded component, not live scene admission. Next recover full physical registration/activation and helpers, real actor responses and shared dynamic reclip before replacing existing collision. Gated pairs retain contacts; sphere exclusions use the earlier actor.

2026-11-06 continuation: the earlier292 original component cases plus50 derived- caller cases and body/visual-sync audit supply no extra reset. Startup diagnostics now observe backgroundLevel1D/Jimmy allocation after an explicit OS repaint acknowledgement, with black frames/timing perturbation recorded. Source lifetime, not those frames, proves the TSK ordering correction. Preserve normal landing bank; never substitute a leveling reset. Historical runtime/package baseline is a2e89c6/dae13ac. Read the current progress/compatibility results before packaging. 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; 13 Jimmy source guards,26 movement/20 body groups and all five native SDL jump aliases pass. Source pressure requires a real support polygon; lab/outside keep capsule compatibility. The next bounded air-target/root-render bridge is now implemented (docs/gameplay/jimmy-air-bridge.md):146 saved source observations compare, including12 air targets and12 degree/14 hierarchical transforms. Target dirty/Init and retained apply-owned pitch seeds stay separate from current Euler. Modern local sole correction and final OMT render-decomposition precision remain explicit; broader special/root-changing/dynamic contacts are next.27 contact dispatch observations still do not establish live special callbacks. Body publication/mode foundation now implements fresh previous/live XYZW, independent source flags, retained context and post-landing payload ownership. 100 new complete original comparisons plus six bounded callback-state cases pass; see docs/checkpoint/body-contact-implementation.md. Keep admission gated: actual Jimmy hazards/climbs, multi-frame actor mode/facing/animation and dynamic/shared scene context are still open. No automatic lab/outside solver replacement. No Remote/new-gadget implementation until this movement priority is handled. The initial architecture checkpoint is documented in docs/checkpoint/review.md; use the playable 69d0187 baseline as a comparison tool. Read docs/checkpoint/README.md, coverage.md and implementation-plan.md before gameplay changes. Current gadget controls/resources/primary-fire findings belong in docs/gameplay/. Distinguish static recovery, implementation, port tests and original runtime evidence. Main owns integration/runtime; gadget investigators have exclusive named files, not shared directories. Scooter feedback fixes: docs/gameplay/scooter-dismount-leveling.md and scooter-pitch.md. Preserve dismount Euler copy; source4096E0 levels Goddard X/Z in the bounded follow bridge. ScooterAudio adds47D9D0 positional frequency/history after the unchanged engine formula; current shared listener includes parked/script cameras.11 native facing +11 frequency traces,13 Scooter/2 audio/10 Patrol groups and24 Python guards pass; both native input replays pass with zero validation errors. Both packages identify cleanfccc0b9; standalone Linux repeats both scenes with20 matching readbacks. Whole-original/audible Windows comparison remains open. Latest gadget continuation: docs/gameplay/scooter-live.md. Scooter is live in VR05 and outsideLEV1 through normal owned tile/F1. Separate C3DJEEP body and four real wheel supports, source drive/input/impact/default camera, exact source-pivot art, pitch-controlled engine and summon/contact mount/cleanup/RETURN are integrated. 53 copied-original observations match managed formulas;10-phase headless/native Linux replays pass in both scenes, zero validation errors. The32-row debug Player page fits ultrawide. Whole-original/native Windows comparison, modes2..20, mouse/analog, dynamic pairs and arbitrary retained LOAD/save remain open. Goddard follow is an opt-in bounded adapter in these scenes. Source/REA artifacts are under artifacts/scooter-*-live; all ownership is primary. Package evidence is in the live report. Both packages identify clean62c07a3, resources match, and standalone Linux from /tmp passes both10-phase native replays with20 identical readbacks. All303 Python+2 HUD/managed/36 main GPU regressions and539 original hashes pass. Preserve parked Jimmy collision; Scooter's source callback is independent. Grappler remains live boundedVR08; see docs/gameplay/grappler-live.md for113 original-component observations,13 managed/40 Python checks and9-phase SDL replay. The user clarified orbit's remaining issue was inverted Left/Right; Left/A and Right/D azimuth mappings are corrected, Up/Down unchanged. The historical orbit packages identified clean70cba65; native input/resize/validation passes. See docs/orbit-camera.md. Rocketship remains live in boundedVR02: source body/callbacks, registration-ordered input, maneuvers/camera, original driver/Goddard/flame resources and F1 grant.96 isolated original component cases support the source contracts; full pair discovery, other levels, special mission/ hazard/RNG effects and whole-original/native Windows comparison remain open. Its wall-impact material RGBA correction is docs/gameplay/rocketship-impact-render.md; 13 managed/22 Python checks and final native Linux flight replay pass. Grappler source is in docs/gameplay/grappler.md. Friend research assessment is docs/reviews/jn-engine-survey.md; use its decompiler leads with REA/source checks, not its tuned C gameplay. All ownership has returned. Preserve baseline69d0187 and parked35a2a66/0272f7b collision checkpoints. Latest package provenance and validation are recorded in the live report. Baseball continuation: docs/gameplay/baseball-implementation.md. Its20-slot pool, hold/release aiming, original TIME art and boundedVR07 moving targets are implemented; original dynamic pair discovery/other enemy consumers remain open. Scooter historical recovery is docs/gameplay/scooter.md; live coverage is scooter-live.md. Bubble's mode2, original sprite and boundedVR01 source body/floor state are implemented and tested; Invisible, ray/jetpack and shared energy state remain integrated. Other gadgets and broader collision/camera/retained-helper behavior remain separate gates. All current investigator ownership has returned to primary. Keep full enemy AI, suppression globals, render state and original/native Windows verification distinct.

Use REA for original-binary investigations from now on, including delegated investigations. Preserve its Evidence and cross-check relevant addresses/bytes; record provider gaps explicitly and use supporting analysis when needed. Ordinary source edits and builds do not require a REA call. Local REA/Ghidra is available through scripts/rea.sh; see docs/rea.md for the ignored launcher environment and JDK paths. Existing client MCP registration was not changed. Use generated copies, preserve complete Evidence/snapshots, and keep static decompilation distinct from source execution. Current C3 continuation: docs/checkpoint/control-phase-implementation.md; remaining body/wrapper/camera gates are in its final section and the implementation ledger. Current C4 follow-up is docs/checkpoint/collision-response.md with ceiling-wrapper, body-root-registration and camera-handoff reports. The source sphere kernel is isolated/probed; do not treat it as live capsule replacement. Next integration report is collision-body-probe.md: source grid/retry component and seven original dispatcher comparisons, contact/material/friction contracts and ten ordinary-body observations are recorded. collision-body-implementation.md now records matched ordinary composition and VR04 static-only live integration. Next: original dynamic actor eligibility/pair state and special contacts before lab/outside expansion; shared camera state remains separate. Retain modern render/noclip boundaries.