Files
Neutron/.planning/codebase/STACK.md
T
2026-11-12 11:06:58 -05:00

92 lines
7.1 KiB
Markdown

---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
# Technology Stack
**Analysis Date:** 2026-11-12
## Languages
**Primary:**
- C# targeting `net10.0` for the shared executable and managed regression programs; no explicit `LangVersion` override is declared in `GamePort.csproj` or `tests/GamePort.DataTests/GamePort.DataTests.csproj`.
**Secondary:**
- Python 3 for local asset preparation, binary evidence tooling and unittest regressions in `tools/` and `tests/`; `docs/dependencies.md` records Python 3.12. These tools are not runtime requirements.
- Bash for local dependency setup, builds, tests and packaging in `scripts/`.
- GLSL vertex/fragment shaders compiled to SPIR-V in `src/GamePort/Rendering/Shaders/mesh.vert` and `src/GamePort/Rendering/Shaders/mesh.frag`.
- C for isolated original-component probes such as `tools/binary/actor_contact_probe.c`; do not treat probe code as the game runtime.
## Runtime
**Environment:**
- .NET 10 executable, with invariant globalization, nullable analysis, implicit usings and unsafe interop enabled in `GamePort.csproj`.
- SDK selection: `global.json` requests `10.0.100`, permits `latestFeature` roll-forward and disables prerelease SDKs. `scripts/bootstrap.sh` downloads SDK `10.0.402` with a pinned SHA-256.
- `docs/dependencies.md` records self-contained runtime pack `10.0.13`; verify generated publish metadata when establishing package provenance rather than equating SDK and runtime versions.
- Native Vulkan 1.3 minimum: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs` requests `Vk.Version13` and filters physical devices below it.
**Package Manager:**
- NuGet through the .NET SDK (`dotnet restore` in `scripts/bootstrap.sh`); no separately pinned NuGet client version.
- Lockfile present: `packages.lock.json`; `GamePort.csproj` enables `RestorePackagesWithLockFile`.
- Use `scripts/env.sh` to select the project-local SDK and `.nuget/packages` cache and disable .NET CLI telemetry.
## Frameworks
**Core:**
- Silk.NET.Vulkan, Silk.NET.Vulkan.Extensions.KHR and Silk.NET.Vulkan.Extensions.EXT `2.23.0` provide Vulkan bindings and extensions in `GamePort.csproj`.
- SDL3 `3.4.2` is provisioned by `scripts/bootstrap.sh`; window/input/Vulkan-surface and audio bindings are handwritten P/Invoke in `src/GamePort/Platform/Sdl.cs`.
- Game logic, binary formats, asset readers and UI are project C# modules under `src/GamePort/`; no general game engine is declared in `GamePort.csproj`.
**Testing:**
- Python standard-library `unittest`, invoked by `scripts/test.sh` against `tests/test_*.py` and the HUD checks.
- Standalone .NET 10 executable test projects, rather than a declared xUnit/NUnit dependency; `tests/GamePort.DataTests/GamePort.DataTests.csproj` links production source directly.
- `scripts/test.sh` also runs real Vulkan rendering checks and SDL dummy-audio checks; read `docs/compatibility.md` for recorded platform scope.
**Build/Dev:**
- MSBuild/.NET CLI solution and executable configuration: `GamePort.slnx`, `GamePort.csproj`, `global.json`.
- `glslangValidator` and `spirv-val` compile/validate Vulkan 1.3 shaders in `scripts/compile-shaders.sh`; distro package versions are not pinned there.
- CMake builds SDL locally in `scripts/bootstrap.sh`; curl, Python, and optional apt-get/dpkg-deb provision local dependencies without system installation.
- REA/Ghidra/JDK/Node are analysis-only tools selected by `scripts/rea.sh`; defaults reference Ghidra `12.1.4_PUBLIC` and a Java 21 JDK directory. Node and REA versions are not pinned in that launcher.
- Wine is an original-reference/preliminary compatibility tool, not a production dependency; `docs/dependencies.md` records Wine `11.0`.
## Key Dependencies
**Critical:**
- Silk.NET Vulkan/KHR/EXT `2.23.0`: native renderer access, swapchain/surface handling and validation messaging in `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`; direct pins in `GamePort.csproj`.
- SDL3 `3.4.2`: native window, input and audio backend, provisioned in `scripts/bootstrap.sh` and consumed through `src/GamePort/Platform/Sdl.cs` and `src/GamePort/Audio/SdlAudio.cs`.
- Host Vulkan loader and graphics ICD: required even for packaged self-contained builds; `scripts/package.sh` documents the Vulkan 1.3 prerequisite.
**Infrastructure:**
- Locked transitives in `packages.lock.json`: Silk.NET.Core `2.23.0`, Microsoft.DotNet.PlatformAbstractions `3.1.6`, Microsoft.Extensions.DependencyModel `9.0.9`.
- .NET built-ins supply numerics, compression, JSON and filesystem operations; examples are `src/GamePort/Game/RuntimeCheckpoint.cs`, `src/GamePort/Assets/PngImage.cs` and `src/GamePort/Assets/AssetPath.cs`.
- Local asset converters are project modules, such as `tools/extractors/prepare.py`, `tools/extractors/omt.py` and `tools/extractors/sound_bank.py`, not a hosted conversion service.
## Configuration
**Environment:**
- Runtime configuration uses CLI options in `src/GamePort/Program.cs`, including `--assets`, `--scene`, `--level`, `--load-save`, `--write-save`, dimensions, headless rendering and mute/debug switches.
- Native SDL lookup checks the executable directory, project-local native library directory and platform loader in `src/GamePort/Platform/Sdl.cs`.
- `scripts/env.sh` configures SDK/cache paths, optional native-tool paths, `LD_LIBRARY_PATH` and `VK_LAYER_PATH`; no runtime service credentials are required.
- Preserve originals and write prepared assets outside their root; `tools/extractors/prepare.py` rejects output inside the original installation.
**Build:**
- `GamePort.csproj` explicitly includes `src/GamePort/**/*.cs`, copies SPIR-V shaders and conditionally includes platform SDL binaries.
- `scripts/build-linux.sh` and `scripts/build-windows.sh` self-contained publish to `dist/linux-x64` and `dist/win-x64` and require the corresponding SDL library.
- `scripts/package.sh` assembles local assets/scenes/audio, runtime libraries, licenses, documentation and source provenance into both packages; generated packages are not source-control upload artifacts (`AGENTS.md`).
## Platform Requirements
**Development:**
- .NET 10 SDK; Python 3 for preparation/regressions; Vulkan-capable driver/loader and SDL backend dependencies for native checks (`README.md`, `scripts/test.sh`).
- Linux bootstrap additionally uses CMake and native build tooling for SDL and optional Ubuntu package extraction for shader/X11/audio/validation tools (`scripts/bootstrap.sh`).
- Read-only evidence work uses separate generated targets and local analysis tools (`tools/binary/rea_decompile_batch.py`, `scripts/rea.sh`); never execute or modify originals in place (`AGENTS.md`).
**Production:**
- Shared `linux-x64` and `win-x64` source implementation, with self-contained .NET and native SDL packaging declared in `GamePort.csproj` and `scripts/package.sh`.
- Native Linux and Windows 10/11 x64 are required by `../prompt.MD`; host Vulkan 1.3+ driver/loader remains necessary.
- Offline operation is intentional (`AGENTS.md`). Native Linux scene evidence, Windows cross-publish, Wine runs and native Windows gameplay are separate claims; `docs/progress.md` and `docs/compatibility.md` retain bounded verification and outstanding broader/native Windows comparisons.
---
*Stack analysis: 2026-11-12*