Files
Neutron/.planning/research/STACK.md
T

7.7 KiB

Technology and Verification Foundation

Project: Neutron GamePort remaining full reconstruction
Researched: 2026-11-12
Method: Local specification, source/configuration cross-checks and existing verification reports. No dependency updates, new runtime tests or binary analysis were performed.

Keep the Existing Stack

Component Repository version/requirement Role and decision
C# / .NET net10.0; SDK selector 10.0.100 with latestFeature roll-forward; bootstrap SDK 10.0.402 Retain one shared Linux/Windows x64 executable. Do not plan a foundation rewrite.
Silk.NET.Vulkan / KHR / EXT 2.23.0 Existing Vulkan bindings, pinned in the project and lockfile.
Vulkan 1.3 minimum Existing renderer requests Version13 and rejects older devices. Host driver/loader remains required even with self-contained packages.
SDL3 3.4.2 in bootstrap Existing handwritten P/Invoke for native window, input, surface and audio. Retain the shared platform boundary.
GLSL / SPIR-V tools Local shader compiler and validator Preserve original fixed-function behavior through explicit Vulkan shaders/states rather than modernizing the look.
Python / Bash / C Local tooling; documented Python 3.12 Offline preparation, repeatable local scripts and isolated original-component probes. None is a packaged gameplay runtime dependency.
REA / Ghidra / full JDK Existing launcher; documented Ghidra 12.1.4 / Java 21 paths Required investigation route for original binaries. Check actual local launcher/tool identities when producing new evidence.
Wine Documented 11.0 Isolated original/component investigation and preliminary Windows compatibility only. It cannot substitute for native Windows verification.

Versions describe this repository, not upstream latest releases or newly verified installations. docs/dependencies.md records runtime pack 10.0.13; confirm generated publish runtime metadata for each package rather than deriving runtime version from SDK version.

Sources: project, SDK selection, bootstrap, dependencies, renderer, REA launcher.

Existing Local Delivery and Evidence Facilities

  • scripts/env.sh selects local SDK/cache/native tools and disables .NET CLI telemetry. NuGet dependencies are locked in packages.lock.json.
  • scripts/test.sh combines Python parser/source regressions, managed algorithm programs, Vulkan rendering and SDL dummy-audio checks. Tests must retain their bounded claims: exact component output does not establish original full-game scheduling or visuals.
  • scripts/build-linux.sh, scripts/build-windows.sh and scripts/package.sh already implement local self-contained publishing and original-derived asset assembly. Packages include SDL3, shaders, resources, licenses and source provenance. They remain local artifacts.
  • Original preservation uses tools/recon/inventory.py with docs/original-manifest.json. Existing reports record 539 hashes; run the verifier at actual implementation/package checkpoints.
  • Runtime has no required hosted service, account system, remote database or telemetry. Gitea is solely the authorized source-control destination for completed verified source/tools/docs.

Sources: integration map, test entry, packaging, project rules.

Remaining Capability Gaps

Gap Existing evidence Required closure and roadmap implication
Whole-original reference execution Compatibility reports record isolated Wine windows with unusable original GL/Vulkan rendering; component execution is available Establish a working local original reference environment/capture path early. Use a generated copy, local Windows/legacy VM or other supported local investigation path. Feasibility of a particular environment is unverified. Do not silently promote component probes to whole-game reference evidence.
Native Windows verification Windows x64 cross-publish, preliminary Wine checks and bounded user reports exist Plan repeatable native Windows input, audio, resize, driver and integrated progression checks. Record revision, device/environment and scenario results. A new cross-publish does not refresh prior Windows runtime evidence.
Audible and positional audio comparison Dummy streams verify consumption/lifecycle; broader speakers/latency/attenuation verification remains open Compare effects/bank selection, spatial behavior, timing and actual listening output against the original on both native platforms. SDL API availability alone does not resolve policy.
Rendering equivalence Native Linux/llvmpipe GPU checks and readbacks exist Add reference-matched camera/scene captures and per-state discrepancy review for materials, lighting, fog, alpha, pivots and animation. Zero Vulkan validation errors proves API correctness, not fidelity.
Timing and retained system composition Numerous copied-original component cases; fixed 60 Hz port policy; source ordering corrections already integrated Recover remaining shared scheduling, actor lifetime and callback contracts before broad solver admission. Compare event/state traces as well as pixels and final positions.
Full content and release coverage 35 GAMs catalogued, 33 with matching geometry; local packages contain substantial playable content Audit all reachable original routes and resources. Missing Level3B/E geometry is recorded but normal gameplay use is unverified: it is not an established blocker or permission to fabricate replacement assets.

Sources: compatibility ledger, current progress, next-work plan, authoritative specification.

Roadmap Decisions

  1. Treat the existing shared renderer/platform/build system as the foundation. Extend focused recovered modules and local checks instead of reselecting engines or libraries.
  2. Establish the original-reference and native-platform comparison matrix at the start and grow it with each gameplay slice; reserve final cross-platform acceptance for complete routes and clean packages.
  3. Keep the current Jimmy stabilization and collision admission gates ahead of gameplay expansion. Additional tooling should answer a named unresolved source/runtime question, not become an independent infrastructure rewrite.
  4. Preserve generated extraction, original-code probes, snapshots and build output separately from immutable originals. Commit findings/tools/source only; no original assets or generated packages may be pushed.
  5. Record source commit, package identity and verification scope together. Research does not refresh historical runtime receipts.

Confidence and Unresolved Questions

The stack/configuration observations are directly cross-checked against repository files; historical runtime results are report evidence, not newly reproduced results. No claim is made about current upstream releases. The generic GSD classify-confidence --provider curated --verified returned LOW without a recognized package/ecosystem; that provider score does not independently validate these local artifacts.

Open questions are the working original capture environment, comprehensive native Windows availability, original cadence/reference trace coverage, audible output parity and the complete reachable content matrix. These require phase-specific local investigation and execution; they are not reasons to replace the mandated technology stack.