diff --git a/AGENTS.md b/AGENTS.md
index 378033a..c611d1b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,7 +18,7 @@ runtime evidence before claiming working gameplay or platform compatibility.
- `.tools/`, `.nuget/`, `artifacts/`, `dist/`: ignored local generated data.
Build from this directory with `dotnet build`, `dotnet run`; project-local SDK
-may require `scripts/dotnet.sh` (consult README for verified invocation).
+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`.
diff --git a/GamePort.csproj b/GamePort.csproj
new file mode 100644
index 0000000..b190914
--- /dev/null
+++ b/GamePort.csproj
@@ -0,0 +1,21 @@
+
+
+ Exe
+ net10.0
+ enable
+ enable
+ true
+ false
+ true
+ true
+
+
+
+
+
+
+
+
+
+
+
diff --git a/GamePort.slnx b/GamePort.slnx
new file mode 100644
index 0000000..26fe364
--- /dev/null
+++ b/GamePort.slnx
@@ -0,0 +1,3 @@
+
+
+
diff --git a/NuGet.Config b/NuGet.Config
new file mode 100644
index 0000000..59628a7
--- /dev/null
+++ b/NuGet.Config
@@ -0,0 +1,5 @@
+
+
+
+
+
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e796f16
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+# Jimmy Neutron reconstruction
+
+Local reconstruction of the supplied **Jimmy Neutron: Boy Genius** installation
+using C#/.NET 10, Silk.NET.Vulkan (Vulkan 1.3), and SDL3. Original files remain
+untouched in `../Original`. There are no Git remotes or runtime online services.
+
+**Current milestone: recovered original assets, a native rendered lab scene with
+an animated Jimmy preview, and Linux/Windows investigation packages. Full
+playable gameplay has not been reconstructed.** Controls, collision, introductory
+cutscenes, interactions, progression and saves still require implementation and
+comparison. See [progress](docs/progress.md) and [compatibility](docs/compatibility.md).
+
+## Build and run locally
+
+From `GamePort/`, using an installed .NET 10 SDK or the already provisioned local SDK:
+
+```bash
+source scripts/env.sh
+dotnet build
+python3 tools/extractors/prepare.py --audio sounds musicsecretlab
+dotnet run -- --with-player
+```
+
+The default scene is the original secret lab (LV1B) with its recorded start camera.
+Press **C** to switch between stored and inspection cameras; arrows/WASD orbit,
+plus/minus zoom, F11 toggles fullscreen, Escape quits. These are investigation
+controls. Original gameplay controls are documented in `docs/analysis/gameplay.md`.
+Without a prepared scene, the app previews the original Jimmy base model.
+
+Headless verification on a machine with Vulkan 1.3 (Mesa lavapipe works):
+
+```bash
+dotnet run -- --headless --with-player --time 0.05 --screenshot artifacts/lab.ppm
+dotnet run -- --headless --model ASE/jimstop.ase --texture png/jimycarl.png
+dotnet run -- --audio artifacts/extracted/musicsecretlab/Wave_00000000_HuntingBuildupVar2_11k.wav --loop-audio
+dotnet run -- --help
+```
+
+Explicit original paths can be supplied with `--assets /path/to/Original`.
+`--scene` accepts generated scene JSON; `--level` accepts an original GAM relative
+to the original root. `--original-camera` uses its matching startpoint. Player
+preview uses `--with-player` or `--animation path/to/animation.json`. Morph sample
+interpolation is recovered; loop closure and playback speed remain preview policies.
+
+If tooling is missing on Linux, `scripts/bootstrap.sh` downloads pinned official
+SDK/SDL dependencies and obtains build tools using the existing Ubuntu apt index,
+all under `.tools`. It needs network access for dependencies, Python 3.12+, CMake,
+a C compiler and ordinary native runtime libraries. It does not install host packages.
+Restore uses NuGet; subsequent builds/tests use local caches. The runtime needs
+a Vulkan 1.3 driver/loader, plus X11/Wayland on Linux for visible windows.
+
+## Test and package
+
+```bash
+scripts/test.sh
+scripts/build-linux.sh
+scripts/build-windows.sh
+scripts/package.sh
+```
+
+The publish scripts perform equivalent self-contained publishes:
+
+```bash
+dotnet publish -c Release -r linux-x64 --self-contained true
+dotnet publish -c Release -r win-x64 --self-contained true
+```
+
+Packages are local directories `dist/linux-x64` and `dist/win-x64`. Run
+`launch-scene.sh` or `launch-scene.cmd`; append `--headless --frames 1` for a
+render smoke test. They include the .NET runtime, SDL3 native library, SPIR-V,
+original asset copies, prepared lab/Jimmy resources, audio and limitations.
+Windows cross-publishing is verified; native Windows execution is **unverified**.
+These are investigation packages, not a finished game release.
+
+`scripts/test.sh` runs 20 Python regressions, native C# data/algorithm checks,
+all PNG/ASE decoders, actual Vulkan GPU readback, dummy-device SDL3 audio, and
+original SHA-256 verification. Set `NEUTRON_WINDOW_TEST=1` with a working DISPLAY
+to include injected keyboard and swapchain-resize verification. Full OMT audit:
+
+```bash
+python3 tools/extractors/audit.py ../Original --report artifacts/extracted/audit.json
+python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
+```
+
+## Investigation and continuity
+
+Start with [AGENTS.md](AGENTS.md), [tasks](docs/tasks.md),
+[reverse-engineering index](docs/reverse-engineering.md), and
+[architecture](docs/architecture.md). Detailed binary/graphics/asset/gameplay
+reports are under `docs/analysis`. `tools/extractors` contains bounded OMT/ASE/PNG
+decoders; `tools/levels/gam.py` round-trips all original level records.
+
+Original reference capture uses `tools/recon/reference_capture.py` with local
+Wine/Xvfb, bubblewrap and ImageMagick. It executes a separate copy with no network
+and no original-directory mount. Wine is for investigation only; the port does not
+use Wine, DirectX or OpenGL. See `docs/reference-testing.md` for actual results.
+
+All generated extraction output, local SDK/native dependencies, captures and
+packages are ignored by the nested local Git repository. Never configure a remote,
+upload assets, or overwrite the original installation.
diff --git a/docs/analysis/gameplay.md b/docs/analysis/gameplay.md
index a52c83a..f659b04 100644
--- a/docs/analysis/gameplay.md
+++ b/docs/analysis/gameplay.md
@@ -70,5 +70,33 @@ meaning depends on each property.
Save data has a fixed-looking region followed by Pascal task names and big endian
values (NewGame.tsk tail includes SCENE = 30). Save writing is not yet recovered.
-Physics, jumping, collision, AI, RNG, combat, progression and cutscene execution
-remain under investigation. No original gameplay session has been captured yet.
+## Recovered arithmetic fragments
+
+Binary analysis has now resolved actual game gravity, jump impulse and basic
+integration order. `src/GamePort/Game/RecoveredMotion.cs` implements those narrow
+fragments independently of the still-unrecovered full controller/collision system.
+
+- CJimmyGame setup `0x44D414` overrides generic engine gravity to (0,-800,0).
+- Jump branch `0x4383B3` queues a one-frame (0,550,0) impulse.
+- Player airborne logic additionally changes acceleration: state<3 at `0x438148`
+ uses `gravity*1.33-gravity`, producing roughly -1064 effective vertical
+ acceleration. Other states/jetpack gates remain unresolved. Therefore the
+ tested -800 free-motion fragment is **not** a complete normal-jump controller.
+- Physics `0x479EBB..0x479FC0` consumes/clears impulse, adds acceleration*dt and
+ gravity*dt, then computes displacement from the updated velocity (semi-implicit
+ Euler). Subsequent collision resolution and activation flags remain unresolved.
+- Player speed increment 30, idle decay 35 and maximum 600 are per invocation,
+ without dt. Constructor fields and branch addresses are in binary.md. Rendering
+ frame rate must not silently become the simulation invocation rate.
+- The original uint32 RNG at `0x438D52` wraps `state*1664525+32767` and returns
+ `state>>16`. A System.Random replacement would produce different sequences.
+- The -350 value originally suspected during investigation is a camera offset,
+ **not** gravity. Follow offset (0,200,-350), look target offset (0,80,0).
+
+C# regressions exercise impulse consumption/order, limits, initial original data,
+and RNG overflow. These establish the reconstructed arithmetic, without claiming
+bit-identical x87 behavior or a complete faithful controller.
+
+Physics gating, collisions, AI, combat, progression, cutscene execution and
+simulation cadence remain under investigation. No original gameplay session has
+been captured yet.
diff --git a/docs/architecture.md b/docs/architecture.md
index 9aa0d02..e84d6d1 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -23,6 +23,18 @@ verification possible without a desktop; this is distinct from SDL presentation.
Simulation implementation must follow recovered algorithms and timing. A generic
fly camera or rendered model alone does not satisfy the playable-scene requirement.
+The completed foundation includes a single synchronous Vulkan renderer supporting
+offscreen and SDL surface presentation, an independent SDL WAV stream, bounded
+GAM/PNG/scene readers, and a retained-topology morph sampler. Prepared scene JSON
+avoids a Python runtime dependency in native packages. Mesh draw ranges omit null
+materials following the original renderer, while retaining their geometry. Default
+normal atlas and morph transforms are supported by binary/duplicate-asset evidence.
+
+Physics arithmetic fragments are independent of a full controller; no invented
+collision/task system has been silently inserted. The main program remains a
+scene investigation runtime; future simulation must be a separate stateful module
+with recovered timing, input, collision, triggers and progression.
+
Subsystem implementation and validated ownership are documented in
`infrastructure.md`, `analysis/graphics.md` and `rendering.md` as they become
available. Persistent docs distinguish planned architecture from verified behavior.
diff --git a/docs/compatibility.md b/docs/compatibility.md
index 50e0ea9..67f67c9 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -1,21 +1,38 @@
# Compatibility and validation
-Status is evidence-based; compilation alone is not runtime verification.
+Compilation, native runtime, original behavior and full feature completion are
+separate evidence categories. **The game is not fully reconstructed/playable yet.**
-| Feature | Implemented | Tested | Evidence / limits |
-|---|---|---|---|
-| Original preservation | Hash baseline | Initial corpus | 539 files in original-manifest.json |
-| GAM reader/encoder Python | Yes | Linux, all 35 levels | Byte-for-byte round trip, six tests |
-| GAM C# loader | Yes | Pending compilation | Original scene/player/camera exposed |
-| OMT geometry recovery | In progress | Original level1 meshes | Asset agent integration pending |
-| .NET 10 Linux build | In progress | Pending | Project-local SDK installed |
-| Windows x64 build/package | Pending | Unverified | Cross-build will not prove execution |
-| Vulkan frame | In progress | Pending | Headless Mesa available; no initial display |
-| SDL3 window/input/audio | In progress | Pending | Native dependencies being built locally |
-| Playable scene / original fidelity | No | No | Rendering foundation does not establish gameplay |
-| Original execution/reference capture | No | No | Wine absent initially; originals not executed |
-| Animation/AI/combat/progression/save | No | No | Reverse engineering ongoing |
+| Feature | Implemented / tested | Evidence and limits |
+|---|---|---|
+| Original preservation | Verified after extraction/runtime tests | All539 original SHA-256 hashes unchanged |
+| GAM Python / C# | All35 files,3299 entities | Exact Python round-trip; C# corpus/start/corruption checks |
+| OMT recovery | All100 archives audited | 2155meshes,2183materials,1614textures,875RIFF, zero failures |
+| C# original loaders | Linux runtime | All128 PNG /254 ASE base meshes; morph/base UV tests |
+| .NET10 Linux build | Pass, zero warnings/errors | Local SDK10.0.402/runtime10.0.13 |
+| Windows x64 publish | Pass | Correct PE32+ app and SDL3.dll; native execution untested |
+| Linux self-contained package | Native run verified | Two headless frames without SDK/source/originals mounted |
+| Vulkan1.3 lab | llvmpipe + GTX1070 | Real indexed/textured/depth frame/readback; validation enabled, zero errors |
+| Original camera/projection | Data/math integrated | GAM camera, recovered FOV/clips; startup/follow behavior not compared |
+| Jimmy normal texture / morph | Native preview verified | Correct atlas slot0, base topology/UV retained; state speed/loop unverified |
+| Null-material visibility | Binary rule implemented/tested | Original DX renderer skips null pointers; proxy geometry retained |
+| SDL3 presentation/input | Linux Xvfb + GTX1070 | Six frames; injected keyboard event received |
+| Swapchain resize | Linux tested | 960x720 ->800x600, zero validation errors |
+| Focus / fullscreen | Code present, partial/unverified | Focus clears keys; fullscreen toggle not dynamically tested |
+| Mouse/relative input/controller | Incomplete | SDL entry point declaration alone is not behavior |
+| Audio stream | Linux dummy device | Original11025Hz mono WAV consumed10752bytes/500ms; speakers untested |
+| Physics fragments/RNG | Standalone C# tests | Recovered arithmetic; controller/jump/collision state incomplete |
+| Intro/task/entity/gameplay loop | Incomplete | GAM data recovery is not task execution or gameplay |
+| Menus/AI/combat/progression/saves | Incomplete | Required future work |
+| Original execution | Attempted under isolated Wine11 | Window created, GL/Vulkan rendering unusable; no reference comparison |
+| Native Windows functionality | Unverified | Requires local Windows installation or VM |
-Current known limitations: no reconstructed complete gameplay loop yet; no native
-Windows testing or reference captures. Exact camera, physics, fixed-function
-lighting/blending/fog and task behavior need binary/observational validation.
+Generated evidence: artifacts/final-tests.log, test-level1b.ppm, test-player.ppm,
+resize-input.ppm, package-linux.ppm, extracted/audit.json and reference*/ logs.
+The lab/player images have been visually inspected; they do not establish original
+visual equivalence. Windows cross-publishing must not be represented as Windows
+runtime validation. Package scope and prerequisites are in infrastructure.md.
+
+Known visual/behavior limits include incomplete lighting/fog/blend/culling/material
+mapping, inferred initial look-at, preview animation loop/speed, no reconstructed
+intro/controller/collision/trigger execution and no original comparison captures.
diff --git a/docs/dependencies.md b/docs/dependencies.md
new file mode 100644
index 0000000..6119b1b
--- /dev/null
+++ b/docs/dependencies.md
@@ -0,0 +1,19 @@
+# Local dependencies
+
+| Component | Version used | Source / license metadata |
+|---|---|---|
+| .NET SDK | 10.0.402 | Official builds.dotnet.microsoft.com archive; pinned SHA-256 in bootstrap.sh |
+| .NET runtime | 10.0.13 | Self-contained publish runtime pack; bundled LICENSE and THIRD-PARTY-NOTICES |
+| Silk.NET.Vulkan / KHR / EXT | 2.23.0 | NuGet packages, locked transitive versions in packages.lock.json; MIT license expression |
+| SDL3 Linux / Windows | 3.4.2 | Official libsdl.org archives; zlib license, copied to packages/licenses/SDL3.txt |
+| glslang/SPIR-V tools | Ubuntu local packages | Development shader compilation/validation only |
+| Vulkan loader/ICD | Host platform | Runtime Vulkan 1.3 driver/loader prerequisite |
+| Khronos validation layer | 1.3.275 | Local Ubuntu package; development verification only |
+| Python | 3.12 | Existing host interpreter; analysis/preparation only, stdlib extractors |
+| Wine | 11.0 | Official WineHQ stable Ubuntu amd64/i386 packages; original-reference testing only |
+
+The .NET runtime pack version must be checked against the generated publish
+runtimeconfig; the SDK and runtime have distinct version numbers. Library license
+metadata is recorded for continuity; original game assets retain their original
+ownership. Packages are local artifacts, not public distribution authorization.
+No project files or assets were uploaded to dependency sources.
diff --git a/docs/infrastructure.md b/docs/infrastructure.md
new file mode 100644
index 0000000..576da23
--- /dev/null
+++ b/docs/infrastructure.md
@@ -0,0 +1,61 @@
+# Native infrastructure and package scope
+
+Verified environment: Ubuntu 24.04 x86-64; project-local .NET SDK 10.0.402,
+Silk.NET 2.23.0, SDL 3.4.2 built from official source (Linux) and official x64
+SDL3.dll (Windows). GLSL compiled to Vulkan 1.3 SPIR-V and checked by spirv-val.
+Khronos validation layers are installed locally. No root installation is required.
+
+`scripts/env.sh` selects local SDK, NuGet cache, native tools and validation layer;
+it also disables .NET CLI telemetry. `bootstrap.sh` reproduces dependency setup
+on the tested Ubuntu host using official pinned SDK/SDL archives and apt packages.
+Downloaded archive SHA-256 values are checked before extraction. Tool/dependency
+downloads are permitted by the specification; no project material is uploaded.
+
+## Implemented
+
+- C# .NET 10 shared executable and local-only solution/build scripts.
+- Vulkan 1.3 instance/device/graphics queue, descriptors, buffers, texture uploads,
+ sampler, indexed graphics pipeline, depth attachment, offscreen target/readback.
+- SDL3 Vulkan surface, swapchain/presentation, resize/recreation, synchronization,
+ cleanup, keyboard, focus handling and fullscreen toggle.
+- SDL3 WAV streams with conversion, optional looping and lifecycle cleanup.
+- Original OMT-derived world geometry/materials/textures; original ASE model and
+ retained-base vertex morph animation samples; original GAM entities/camera.
+- Self-contained Linux/Windows publishing with matching native SDL3 libraries.
+
+The renderer completes submissions synchronously. This deliberately simple early
+implementation is maintainable but does not target final performance. It currently
+has a texture-times-color pipeline, nearest mip level/linear sampling, alpha
+discard and depth. Original per-material culling/blending, lighting, fog and
+animation state/render sorting are incomplete. See rendering.md for evidence.
+
+## Verified checks
+
+- `scripts/test.sh`: Python extraction/GAM tests, C# data/morph/arithmetic tests,
+ all 128 PNG and 254 ASE base meshes, actual original lab and player rendering.
+- Offscreen Mesa llvmpipe: lab 2,869 source triangles / 33 recovered textures;
+ combined Jimmy preview 3,683 triangles / 34 textures; zero Vulkan validation
+ errors. Readback is saved locally, visually reviewed and compared before/after
+ material/texture fixes. This is not original-game visual equivalence proof.
+- SDL3 window on NVIDIA GeForce GTX 1070 under Xvfb: six frames, injected keyboard
+ received, resize 960x720 -> 800x600, zero validation errors. Tested with scoped
+ escalation because the restricted tool sandbox blocks display-socket access.
+- Recovered 11,025 Hz mono WAV: dummy-device SDL3 stream consumed 10,752 bytes
+ in 500 ms. Physical speaker output, positional mixing and original timing are
+ unverified.
+- Linux/Windows self-contained cross-publishing succeeds. Native Windows execution
+ remains unverified; Wine reference testing is a separate investigation path.
+
+## Scope limits
+
+This is an investigation/runtime foundation, not complete reconstructed gameplay.
+Original collisions, task/trigger execution, introductory cutscene, inventory,
+combat, enemies, progression, save/load, original mouse/control behavior and
+remaining scenes are incomplete. Player rendering at the original startpoint is
+an animated preview; its interpolation loop/speed are not a recovered state machine.
+
+Packages include local copies of asset directories (ASE/png/gam/omt), original
+font PNGs/NewGame/readme, lab/Jimmy scene resources, recovered music, .NET runtime,
+SDL3, SPIR-V and these limitations. Legacy EXEs/DLLs, old user save slots, tool
+caches and analysis databases are not runtime dependencies. Vulkan drivers remain
+platform prerequisites. No claim of native Windows runtime validation is made.
diff --git a/docs/progress.md b/docs/progress.md
index 41fbe52..a0fcd45 100644
--- a/docs/progress.md
+++ b/docs/progress.md
@@ -1,25 +1,71 @@
-# Progress
+# Progress — current checkpoint
-## Verified so far
-- Read complete primary specification, inspected originals, established ownership.
-- Created local-only Git repository under GamePort and persistent project guidance.
-- Recorded all 539 original-file SHA-256 hashes (224,601,234 bytes).
-- Identified PE32 x86 MSVC C++ game and Open Media Toolkit 2.0 DR4 engine.
-- Fully decoded 35 GAM levels, 3,299 entities, 93 class codes, 84,044 properties.
-- Python GAM reader/encoder round-trips every original byte; six targeted tests pass.
-- C# GAM reader added with explicit endian handling and original startpoint/camera.
-- OMT resource index and meshes recovered by asset investigation; integration ongoing.
-- Scoped dependency download approved; local .NET 10 SDK/Silk/SDL setup ongoing.
+**Full reconstruction is incomplete.** The current milestone is an evidence-backed
+asset recovery toolchain and a native original-scene/animation investigation
+runtime with local Linux/Windows packages. No completed playable-scene claim.
-## Current work
-Binary/rendering investigation, exact material/texture/audio recovery, C# runtime,
-Vulkan offscreen verification, SDL3 presentation, cross-platform packaging.
-No claim of full playable reconstruction, original behavior comparison, or Windows
-runtime validation. See `tasks.md` and `compatibility.md` for remaining work.
+## Verified
+
+- Full `../prompt.MD` specification read; originals preserved and local Git initialized.
+- All 539 original files (224,601,234 bytes) still match recorded SHA-256 hashes.
+- Native PE32 x86 MSVC C++ game, Open Media Toolkit 2.0 DR4, Direct3D7/DirectDraw7,
+ DirectInput8 and DirectSound identified with addresses in analysis reports.
+- 35 GAM files: 3,299 entities, 93 class codes, 84,044 properties, byte-for-byte
+ round-trip in Python and full corpus decoding in native C#.
+- 100 OMT files / 7,027 indexed resources audited: 2,155 meshes, 2,183 materials,
+ 1,614 textures, 875 bounded RIFF resources; zero decode failures.
+- ASE/OMT coordinate and UV conversion proven with duplicate assets. Jimmy morph
+ sample vectors retain original base UV/topology; normal texture corrected to
+ jimycarl.png via actual InitObject code, with shock atlas kept separate.
+- .NET SDK10.0.402/runtime10.0.13, Silk.NET2.23.0, SDL3.4.2 provisioned locally.
+- C# builds without warnings/errors; 20 Python tests plus native C# corpus,
+ malformed-data, arithmetic, visibility, case lookup, morph and merge tests pass.
+- Native Vulkan lab rendering: 2,869 triangles / 33 textures; combined Jimmy
+ preview: 3,683 triangles / 34 textures. Real GPU readback, zero validation errors
+ under llvmpipe; scene/player screenshots visually reviewed.
+- Fixed original null-material skipping removes false white collision-proxy
+ surfaces. Original startpoint/camera and recovered projection are available.
+- SDL3 hardware window/presentation on GTX1070 under Xvfb: six frames, injected
+ keyboard received, resize to800x600, zero validation errors.
+- SDL3 recovered WAV stream consumes bytes on dummy device. Speaker output untested.
+- Self-contained linux-x64/win-x64 packages built under dist/. Linux package also
+ renders inside a separate filesystem namespace with no SDK/project/original
+ directory mounted. Windows native execution remains unverified.
+- Official Wine11 original-copy runs attempted in isolated filesystem/network
+ namespaces. Both GL and Vulkan backends produce unusable frames; details below.
+
+## Build and run
+
+From GamePort: `source scripts/env.sh`, `dotnet build`, then `dotnet run -- --with-player`.
+Asset preparation: `python3 tools/extractors/prepare.py --audio sounds musicsecretlab`.
+Tests: `scripts/test.sh`; packages: `scripts/package.sh`. See README for exact options.
+Generated outputs and dependencies are ignored, and everything remains local.
+
+## Remaining and current constraints
+
+No original gameplay reference has been captured. Wine GL cannot obtain a suitable
+pixel format/3D surface; Wine Vulkan logs unsupported fixed-function state and a
+swapchain image count mismatch. Native Windows/VM access has been requested for
+reference/fidelity and native port validation. These failures do not establish
+original behavior. Static reverse engineering can continue independently.
+
+Original controller, collision resolution, introductory LABEXP cutscene, entity
+activation/task/trigger execution, interactions, combat, AI, progression, menus,
+mouse behavior and saves remain incomplete. Gravity/impulse integration fragments
+are tested, but the player jump state machine adds extra acceleration and is not
+implemented as a complete controller. Animation looping/speed are explicit preview
+policies. Rendering material/lighting/fog/blend state mapping also remains incomplete.
+
+Three subagents contributed independent investigation/infrastructure work and then
+hit a usage limit. Primary reviewed/integrated their work, corrected texture and
+visibility assumptions, finished scripts/tests/packages, and owns the current files.
+Do not assume their final reports imply completed gameplay.
## Continuation
-Read AGENTS, this file, tasks, architecture and analysis reports. Check local Git
-status and active agents before editing. Avoid repeating completed inventory/GAM
-analysis. Original initial-scene evidence points to LV1B / STARTEXP, with VR01 as
-a smaller resource-validation scene. Exact movement defaults now recovered in
-binary investigation; do not substitute unverified gameplay guesses.
+
+Read AGENTS, tasks, architecture, compatibility, reverse-engineering index, and
+analysis reports. Check Git status before editing. Avoid repeating solved inventory,
+GAM decoding or OMT extraction. LV1B/STARTEXP is initial scene evidence; its LABEXP
+trigger still needs reconstruction. VR01 provides a smaller, 16-entity test scene.
+Next actionable addresses/tasks are in tasks.md; original execution procedure and
+errors are in reference-testing.md. Commit history preserves local milestones.
diff --git a/docs/reference-testing.md b/docs/reference-testing.md
new file mode 100644
index 0000000..4125e41
--- /dev/null
+++ b/docs/reference-testing.md
@@ -0,0 +1,38 @@
+# Original reference testing
+
+Originals are never executed in place. `tools/recon/reference_capture.py` copies
+Original to ignored `artifacts/reference/game`, then launches official Wine 11.0
+in bubblewrap with all namespaces unshared, no network, a minimal read-only host
+filesystem, and writable generated work/prefix only. Original paths and home are
+not mounted. Xvfb runs inside the namespace; ImageMagick captures its root window.
+Return key injection is optional. The new port has no Wine dependency.
+
+Local WineHQ Ubuntu noble stable amd64/i386 packages were downloaded separately,
+verified against official index SHA-256 and extracted under `.tools/wine`. The
+wrapper also needs `.tools/native/usr/bin/Xvfb`, bubblewrap, xkbcomp, ImageMagick,
+32-bit Wine runtime libraries and an appropriate Wine graphics backend. Mesa
+software-driver dependencies are kept project-local. Network namespace creation
+needs scoped tool escalation in this environment; no host installation is used.
+
+Reproduce (Linux host with those tools):
+
+```sh
+python3 tools/recon/reference_capture.py --seconds 24 --enter --debug
+```
+
+The supplied NeutronNoCD.exe was launched in the isolated copy and created its
+1024x768 'Jimmy Neutron' window. Initial captures were uniform white. Debug logs
+show Wine DirectDraw/Direct3D initialization failing to find a suitable GL pixel
+format, then failing to allocate a 3D-capable surface (0x8876086a). These captures
+are **not usable gameplay references**. Original timing, startup, cutscene,
+lighting, camera, collision and audio have therefore not yet been compared.
+The wrapper records screenshots, Wine/Xvfb logs, window tree and isolated process
+list, all locally under artifacts/reference. An alternate Wine Vulkan backend is
+also tested with `--wine-renderer vulkan --output artifacts/reference-vulkan`.
+It created a Vulkan device/window but logged unsupported fixed-function states
+and a requested swapchain image count1 outside the driver's supported3..16 range.
+Those frames are also unusable. Failures must not be treated as original behavior.
+
+No native Windows installation/VM or Windows 98 image was available in the initial
+environment/tool inventory. A local reference machine remains necessary if Wine
+cannot render correctly. Native Windows port execution remains separately untested.
diff --git a/docs/rendering.md b/docs/rendering.md
new file mode 100644
index 0000000..416c6f9
--- /dev/null
+++ b/docs/rendering.md
@@ -0,0 +1,46 @@
+# Current Vulkan rendering and evidence
+
+Original API and state maps: `analysis/graphics.md`. Mesh/material/texture formats:
+`file-formats.md`. Vulkan code: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`.
+
+Default prepared LV1B view uses the GAM STARTEXP camera; positive-Z projection
+uses recovered FOV `0xAAA/16384*360` degrees, near 20, far 10000. Generic engine
+far default is 3200; other scene-specific overrides remain to be mapped. Camera
+target offset (0,80,0) is recovered, but startup look-at and follow interpolation
+have not been dynamically compared. Vulkan viewport Y is handled in projection.
+
+World OMT coordinates and per-corner UVs are unchanged. ASE conversion (x,z,y)
+and (u,-v) is verified using duplicate gate/yokianpart assets; no invented light
+is applied to Jimmy. The original normal texture is jimycarl.png (InitObject
+0x422C96), while jimyshock.png is texture slot 1, a separate effect (0x422CA7).
+The normal atlas and scene/player captures have been visually inspected locally.
+
+## Null-material visibility correction
+
+LV1B references material 18 from 45 draw ranges but that material does not exist
+in its original resource index. Names include phoneblock, blockfan and Box/Plane
+objects. Rendering them with white fallback surfaces incorrectly obscured the
+actual lab. Disassembly of OMT2.dll DX draw_shape at `0x1003756C` loads the
+polygon material pointer, tests it at `0x1003756F`, and jumps directly to polygon
+advance at `0x10037A7F` when null. Therefore the modern scene loader retains this
+geometry but excludes unresolved-material draw ranges, matching the original
+render path. It does not assign collision semantics solely from names.
+
+The original also tests in-memory polygon flag 4 (0x10037577). For v2 resources,
+the first serialized bool sets flag 2 at 0x10003F83 (DX disables culling for that
+bit at 0x10037731); the second bool sets flag 1 at 0x10003F9B. Other legacy
+fields and per-material pipeline states still need full mapping.
+
+## Animation preview
+
+MorphAnimation reads prepared base topology/UV and sample vertex positions, with
+linear interpolation following DLL 0x10002F9A. It can append a player draw with
+independent texture to original scene geometry and updates the mapped coherent
+vertex buffer after synchronous frame completion. Source frame sample timing is
+used for preview. Loop closure, state selection, state-specific playback speed,
+normal interpolation, clothing variants and gameplay pose transforms remain
+unverified. This is not a complete animation/gameplay reconstruction.
+
+GPU readback evidence: `artifacts/test-level1b.ppm`, `artifacts/test-player.ppm`,
+`artifacts/jimmy-normal.ppm`, `artifacts/resize-input.ppm` (generated/ignored).
+No original reference image equivalence or pixel-perfect claim is made.
diff --git a/docs/reverse-engineering.md b/docs/reverse-engineering.md
index 3b78a69..1297885 100644
--- a/docs/reverse-engineering.md
+++ b/docs/reverse-engineering.md
@@ -19,7 +19,11 @@ C3DJimmy update 0x424600, input 0x426030; player input 0x438A60, walking branch
0x438BC0. Player defaults ctor region 0x4372A0 sets acceleration 30, deceleration
35, maximum speed 600; increments occur per simulation invocation, while movement
uses elapsed time. A future simulation must recover update cadence before calling
-these coefficients timestep-independent. Jump/gravity values remain provisional.
+these coefficients timestep-independent. Gravity and jump have since been
+resolved: game setup 0x44D414 sets gravity Y=-800; jump branch 0x4383B3 queues
+Y=550 impulse, consumed/cleared at 0x479EBB..0x479EF2. Semi-implicit free-motion
+fragment implemented in Game/RecoveredMotion.cs and regression tested; collision
+and activation gating remain unresolved. See analysis/gameplay.md.
## Unresolved
diff --git a/docs/tasks.md b/docs/tasks.md
index cdc502d..cb58811 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -1,30 +1,63 @@
# Tasks
-## Completed
-- [x] Full specification read; original inventory, hashes and local Git established.
-- [x] Capabilities/tool reconnaissance; independent investigators with file ownership.
-- [x] Executable format and engine identification.
-- [x] Decode/round-trip all 35 GAM files; reader corruption and original-data tests.
-- [x] Implement C# GAM asset reader (compilation/runtime checks pending).
+## Completed milestones
-## Active
-- [ ] Complete binary/graphics report with addresses, rendering state and camera.
-- [ ] Recover player timing, movement, gravity, collision and input algorithms.
-- [ ] Extract OMT meshes, textures, materials, animations, sound and music robustly.
-- [ ] Verify asset schema and integration into native Vulkan renderer.
-- [ ] Compile .NET 10 runtime and verify real offscreen rendering/readback.
-- [ ] Integrate SDL3 window/input/audio; exercise local display where possible.
-- [ ] Local Linux and Windows self-contained builds and dependency packaging.
-- [ ] Test original preservation after tools; checkpoint stable work locally.
+- [x] Entire specification; original inventory/hashes; local-only Git and guidance.
+- [x] Binary/compiler/API identification and address-based reports.
+- [x] All GAM entities decoded and byte-round-tripped; C# corpus reader tested.
+- [x] All indexed OMT meshes/materials/textures/RIFF resources decoded and audited.
+- [x] ASE transform/morph-base UV/topology recovery and regression tests.
+- [x] .NET10 + SDL3 + Vulkan1.3 shared source; real scene/model/texture rendering.
+- [x] Original LV1B lab plus original Jimmy morph preview at GAM startpoint.
+- [x] Correct normal atlas and null-material visibility from binary evidence.
+- [x] Recovered impulse/gravity/speed/RNG arithmetic fragments with tests.
+- [x] Native Linux Vulkan offscreen and SDL3 window/input/resize verification.
+- [x] SDL3 recovered WAV stream consumption test (dummy device).
+- [x] Self-contained Linux and Windows local packages, matching SDL3 libraries.
+- [x] Packaged Linux runtime isolated from SDK/source/originals; renders successfully.
+- [x] Isolated copied-original Wine attempts; actual failures documented.
-## Required after foundation
-- [ ] Run original in isolated copied-data Wine prefix or local Windows VM.
-- [ ] Capture original startup, controls, camera, animation, audio and gameplay.
-- [ ] Reconstruct LV1B opening sequence and one complete playable scene.
-- [ ] Implement/verify collision, interactions, trigger/task system and progression.
-- [ ] Implement original animation playback and correct rendering states.
-- [ ] Implement menus, inventory, gadgets, combat/AI and all remaining scenes.
-- [ ] Recover save/load behavior, configuration, audio mixing and transitions.
-- [ ] Compare reconstruction to original references; resolve fidelity differences.
-- [ ] Run native Windows tests; distinguish cross-publishing from runtime evidence.
-- [ ] Produce verified local release packages and accurate known limitations.
+## Next implementation priorities
+
+1. Recover full player physics/collision and controller before calling any preview
+ playable. Trace `0x479D20` past displacement integration, shared collision call
+ via interface slot0x130 in `0x462520`, and object collision caches. Retain
+ invisible/null-material geometry; its exact collision masks remain unresolved.
+2. Finish airborne state table at `0x437F90` (jump at `0x4383B3`, extra acceleration
+ `0x438148`, held predicate `0x42A730`, mode dispatch `0x437A8C`). Gravity is -800,
+ queued impulse550, but normal jump states add gravity*1.33-gravity; avoid the
+ incomplete '-800 only' jump model. Map landing, retrigger and jetpack gates.
+3. Finish walking friction/input/cadence: `0x438BC0`, `0x437C40`, destination yaw
+ `0x472660`, yaw interpolation `0x43A430`. Resolve mixed per-call acceleration
+ with timed integration; rendering refresh rate must not accelerate movement.
+4. Execute LV1B STARTEXP/LABEXP intro. GAM parsing supplies records; implement task
+ prerequisites, object activation/visibility, camera triggers and progression
+ from code/observations. Then build a complete small scene (VR01 if useful).
+5. Recover original morph state selection, playback speed, smooth normals and
+ transitions. Current interpolation is original; loop/speed are preview policy.
+6. Continue material/fog/light/blend/culling and render sorting mapping, then
+ compare visuals to original; current unlit modulation is only a foundation.
+
+## Required validation and expansion
+
+- [ ] Usable original reference captures under local Windows/VM or working Wine.
+- [ ] Original walking/jump/collision/camera/input comparisons and first complete scene.
+- [ ] Physical audio output and original SFX/music timing, mixing/panning/positional audio.
+- [ ] Fullscreen, minimized-window, mouse/relative capture, display scaling and controller behavior.
+- [ ] Pickups, score/health, gadgets/inventory, combat/AI, all levels and transitions.
+- [ ] Original menus, cutscenes, dialogue/voice and state-dependent rendering.
+- [ ] Save/load schema and configuration persistence; NewGame reference is not save support.
+- [ ] Native Windows execution/input/audio/resize/driver testing (cross-build already passes).
+- [ ] Fidelity regression references, remaining discrepancies and actual release candidate.
+
+## Repeatable commands
+
+- `source scripts/env.sh; dotnet build`
+- `scripts/test.sh` (20 Python tests, C# checks, native offscreen/audio, original hashes)
+- `python3 tools/extractors/audit.py ../Original --report artifacts/extracted/audit.json`
+- `NEUTRON_WINDOW_TEST=1 scripts/test.sh` with DISPLAY for input/resize smoke
+- `scripts/package.sh` for local investigation packages (not a finished game release)
+
+Keep runtime, tests and docs coherent. No remotes/uploads/cloud CI. Do not modify
+originals or claim unobserved fidelity. All prior agent ownership has returned to
+primary; use explicit file ownership if further parallel work is started.
diff --git a/global.json b/global.json
new file mode 100644
index 0000000..2a74454
--- /dev/null
+++ b/global.json
@@ -0,0 +1 @@
+{"sdk":{"version":"10.0.100","rollForward":"latestFeature","allowPrerelease":false}}
diff --git a/packages.lock.json b/packages.lock.json
new file mode 100644
index 0000000..8f990c9
--- /dev/null
+++ b/packages.lock.json
@@ -0,0 +1,55 @@
+{
+ "version": 1,
+ "dependencies": {
+ "net10.0": {
+ "Silk.NET.Vulkan": {
+ "type": "Direct",
+ "requested": "[2.23.0, )",
+ "resolved": "2.23.0",
+ "contentHash": "3/irtlSWXZ3eTi8N6nelI6L34NTB8ZJHpqVMNzZx2aX7Ek9YEQ34NoQW8/Tljrtmkg8KRhHW8hKTEzZaKV8PgA==",
+ "dependencies": {
+ "Silk.NET.Core": "2.23.0"
+ }
+ },
+ "Silk.NET.Vulkan.Extensions.EXT": {
+ "type": "Direct",
+ "requested": "[2.23.0, )",
+ "resolved": "2.23.0",
+ "contentHash": "+Oth189ksRiL6HvGCwIdnsYHawqrbO8y49u1H61z3wsfcHhQZeVDYe/wF5LD7fk3NcdgDvwFD3mLm1QWhdZySw==",
+ "dependencies": {
+ "Silk.NET.Core": "2.23.0",
+ "Silk.NET.Vulkan": "2.23.0"
+ }
+ },
+ "Silk.NET.Vulkan.Extensions.KHR": {
+ "type": "Direct",
+ "requested": "[2.23.0, )",
+ "resolved": "2.23.0",
+ "contentHash": "uRaf4j+SmH3DumjSSSUbFg33BnsGZUyXGj93O9NgGKZSJN3OTmNmQDxRew+/KiVLcgH6qzbto8aNGZ++j9GFWg==",
+ "dependencies": {
+ "Silk.NET.Core": "2.23.0",
+ "Silk.NET.Vulkan": "2.23.0"
+ }
+ },
+ "Microsoft.DotNet.PlatformAbstractions": {
+ "type": "Transitive",
+ "resolved": "3.1.6",
+ "contentHash": "jek4XYaQ/PGUwDKKhwR8K47Uh1189PFzMeLqO83mXrXQVIpARZCcfuDedH50YDTepBkfijCZN5U/vZi++erxtg=="
+ },
+ "Microsoft.Extensions.DependencyModel": {
+ "type": "Transitive",
+ "resolved": "9.0.9",
+ "contentHash": "fNGvKct2De8ghm0Bpfq0iWthtzIWabgOTi+gJhNOPhNJIowXNEUE2eZNW/zNCzrHVA3PXg2yZ+3cWZndC2IqYA=="
+ },
+ "Silk.NET.Core": {
+ "type": "Transitive",
+ "resolved": "2.23.0",
+ "contentHash": "D7AT/nnwlB+4RZ84XY8QNGBZMJI5z9l4CSSETIJ1wCfRJzRt/341y3MRZ4HbnFz4r/IGaWOEZr86iE+0/65yyQ==",
+ "dependencies": {
+ "Microsoft.DotNet.PlatformAbstractions": "3.1.6",
+ "Microsoft.Extensions.DependencyModel": "9.0.9"
+ }
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
new file mode 100755
index 0000000..ce54185
--- /dev/null
+++ b/scripts/bootstrap.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Optional local tool/dependency setup for Linux x64, tested on Ubuntu 24.04.
+# Downloads dependencies only. Does not install system packages or modify originals.
+set -euo pipefail
+source "$(dirname "$0")/env.sh"
+mkdir -p .tools/downloads .tools/dotnet .tools/native .tools/sdl-win
+fetch() { [[ -f "$2" ]] || curl --fail --location --retry 2 "$1" --output "$2"; }
+fetch https://builds.dotnet.microsoft.com/dotnet/Sdk/10.0.402/dotnet-sdk-10.0.402-linux-x64.tar.gz .tools/downloads/dotnet-sdk-10.0.402-linux-x64.tar.gz
+fetch https://www.libsdl.org/release/SDL3-3.4.2.tar.gz .tools/downloads/SDL3-3.4.2.tar.gz
+fetch https://www.libsdl.org/release/SDL3-3.4.2-win32-x64.zip .tools/downloads/SDL3-3.4.2-win32-x64.zip
+python3 - <<'PY'
+import hashlib,tarfile,zipfile
+from pathlib import Path
+hashes={
+ 'dotnet-sdk-10.0.402-linux-x64.tar.gz':'a131496fe7dac21dceea13354e50a3636126fac05d6e5ccf5fb250829c6e9b6a',
+ 'SDL3-3.4.2.tar.gz':'ef39a2e3f9a8a78296c40da701967dd1b0d0d6e267e483863ce70f8a03b4050c',
+ 'SDL3-3.4.2-win32-x64.zip':'7ae98570a42cfe964dbc44f7a26f1f19f8075599e32ef849eb11464bf624b8d3'}
+for name,expected in hashes.items():
+ p=Path('.tools/downloads')/name
+ if hashlib.sha256(p.read_bytes()).hexdigest()!=expected:raise SystemExit(f'Checksum mismatch: {p}')
+if not Path('.tools/dotnet/dotnet').exists():tarfile.open('.tools/downloads/dotnet-sdk-10.0.402-linux-x64.tar.gz').extractall('.tools/dotnet',filter='data')
+if not Path('.tools/SDL3-3.4.2').exists():tarfile.open('.tools/downloads/SDL3-3.4.2.tar.gz').extractall('.tools',filter='data')
+zipfile.ZipFile('.tools/downloads/SDL3-3.4.2-win32-x64.zip').extractall('.tools/sdl-win')
+PY
+if command -v apt-get >/dev/null && command -v dpkg-deb >/dev/null; then
+ (
+ cd .tools/downloads
+ apt-get download glslang-tools spirv-tools vulkan-validationlayers xvfb \
+ libx11-dev libxext-dev libxau-dev libxdmcp-dev x11proto-dev xtrans-dev \
+ libxcb1-dev libxrender-dev libxcursor-dev libxi-dev libxrandr-dev \
+ libxfixes-dev libxss-dev libasound2-dev
+ )
+ for package in .tools/downloads/*.deb; do dpkg-deb -x "$package" .tools/native; done
+ python3 - <<'PY'
+from pathlib import Path
+for p in Path('.tools/native/usr/lib/x86_64-linux-gnu').glob('*.so'):
+ if p.is_symlink() and not p.exists():
+ system=Path('/lib/x86_64-linux-gnu')/p.readlink().name
+ if system.exists():p.unlink();p.symlink_to(system)
+PY
+fi
+cmake -U '*_LIB' -S .tools/SDL3-3.4.2 -B .tools/sdl-build \
+ -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$NEUTRON_ROOT/.tools/sdl" \
+ -DCMAKE_PREFIX_PATH="$NEUTRON_ROOT/.tools/native/usr" \
+ -DSDL_X11_XTEST=OFF -DSDL_SHARED=ON -DSDL_STATIC=OFF \
+ -DSDL_TEST_LIBRARY=OFF -DSDL_TESTS=OFF -DSDL_EXAMPLES=OFF
+cmake --build .tools/sdl-build -j "${NEUTRON_BUILD_JOBS:-4}"
+cmake --install .tools/sdl-build
+source scripts/env.sh
+dotnet restore GamePort.csproj
+scripts/compile-shaders.sh
+printf '%s\n' 'Local SDK, SDL3 and shader tools ready. Source scripts/env.sh to use the local dotnet command.'
diff --git a/scripts/build-linux.sh b/scripts/build-linux.sh
new file mode 100755
index 0000000..5a8fa85
--- /dev/null
+++ b/scripts/build-linux.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "$0")/env.sh"
+if [[ ! -f .tools/sdl/lib/libSDL3.so.0 ]]; then
+ printf '%s\n' 'SDL3 missing: run scripts/bootstrap.sh or provide .tools/sdl/lib/libSDL3.so.0.' >&2
+ exit 1
+fi
+dotnet publish GamePort.csproj -c Release -r linux-x64 --self-contained true -o dist/linux-x64 "$@"
diff --git a/scripts/build-windows.sh b/scripts/build-windows.sh
new file mode 100755
index 0000000..a167b4e
--- /dev/null
+++ b/scripts/build-windows.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "$0")/env.sh"
+if [[ ! -f .tools/sdl-win/SDL3.dll ]]; then
+ printf '%s\n' 'SDL3.dll missing: run scripts/bootstrap.sh or provide .tools/sdl-win/SDL3.dll.' >&2
+ exit 1
+fi
+dotnet publish GamePort.csproj -c Release -r win-x64 --self-contained true -o dist/win-x64 "$@"
diff --git a/scripts/compile-shaders.sh b/scripts/compile-shaders.sh
new file mode 100755
index 0000000..f1df33e
--- /dev/null
+++ b/scripts/compile-shaders.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "$0")/env.sh"
+for shader in src/GamePort/Rendering/Shaders/mesh.vert src/GamePort/Rendering/Shaders/mesh.frag; do
+ glslangValidator -V --target-env vulkan1.3 "$shader" -o "$shader.spv"
+ spirv-val --target-env vulkan1.3 "$shader.spv"
+done
diff --git a/scripts/env.sh b/scripts/env.sh
new file mode 100755
index 0000000..bbff00a
--- /dev/null
+++ b/scripts/env.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Source from a project script; keeps SDK caches and downloaded tools local.
+NEUTRON_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+export DOTNET_CLI_HOME="$NEUTRON_ROOT/.dotnet-home"
+export DOTNET_CLI_TELEMETRY_OPTOUT=1
+export DOTNET_SKIP_FIRST_TIME_EXPERIENCE=1
+export NUGET_PACKAGES="$NEUTRON_ROOT/.nuget/packages"
+if [[ -x "$NEUTRON_ROOT/.tools/dotnet/dotnet" ]]; then
+ export DOTNET_ROOT="$NEUTRON_ROOT/.tools/dotnet"
+ export PATH="$DOTNET_ROOT:$PATH"
+fi
+if [[ -d "$NEUTRON_ROOT/.tools/native/usr/bin" ]]; then
+ export PATH="$NEUTRON_ROOT/.tools/native/usr/bin:$PATH"
+ export LD_LIBRARY_PATH="$NEUTRON_ROOT/.tools/native/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+ export VK_LAYER_PATH="$NEUTRON_ROOT/.tools/native/usr/share/vulkan/explicit_layer.d${VK_LAYER_PATH:+:$VK_LAYER_PATH}"
+fi
+cd "$NEUTRON_ROOT"
diff --git a/scripts/package.sh b/scripts/package.sh
new file mode 100755
index 0000000..9a0e7a5
--- /dev/null
+++ b/scripts/package.sh
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "$0")/env.sh"
+scripts/build-linux.sh
+scripts/build-windows.sh
+python3 tools/extractors/prepare.py --audio sounds musicsecretlab
+for rid in linux-x64 win-x64; do
+ out="dist/$rid"
+ mkdir -p "$out/assets" "$out/scenes/level1b" "$out/scenes/animations" "$out/audio/sounds" "$out/licenses" "$out/docs"
+ for directory in ASE png gam omt; do cp -a "../Original/$directory" "$out/assets/"; done
+ cp ../Original/fontsmall.png ../Original/green_font.png ../Original/NewGame.tsk ../Original/readme.txt "$out/assets/"
+ cp -a artifacts/extracted/level1b/. "$out/scenes/level1b/"
+ cp -a artifacts/extracted/animations/. "$out/scenes/animations/"
+ cp -a artifacts/extracted/musicsecretlab/. "$out/audio/"
+ cp -a artifacts/extracted/sounds/. "$out/audio/sounds/"
+ cp .tools/sdl-win/LICENSE.txt "$out/licenses/SDL3.txt"
+ cp docs/infrastructure.md "$out/BUILD-AND-LIMITATIONS.md"
+ cp docs/compatibility.md "$out/COMPATIBILITY.md"
+ cp docs/dependencies.md "$out/licenses/DEPENDENCIES.md"
+ cp -a docs/. "$out/docs/"
+ cp README.md "$out/SOURCE-README.md"
+ cat > "$out/README.md" <<'NOTES'
+# Neutron original-scene investigation package
+
+Linux: run ./launch-scene.sh. Windows: run launch-scene.cmd.
+Append --headless --frames 2 to render without a window, or --screenshot lab.ppm
+to save GPU readback. A Vulkan 1.3 graphics driver/loader is required.
+
+This package includes the .NET runtime, SDL3, shaders and local asset copies.
+The default shows the original lab and an animated Jimmy preview at its recorded
+startpoint. C switches stored/orbit camera; arrows/WASD orbit, +/- zoom, F11
+fullscreen, Escape quit. These are investigation controls.
+
+This is not the finished playable game. Original collision, controller, intro,
+interactions, progression, AI and saves remain incomplete. Animation loop/speed
+are preview policies. Native Windows execution has not been verified.
+
+See BUILD-AND-LIMITATIONS.md, COMPATIBILITY.md and docs/ for evidence and remaining
+work. SOURCE-README.md describes development from the separate source repository.
+NOTES
+done
+cat > dist/linux-x64/launch-scene.sh <<'LAUNCH'
+#!/usr/bin/env bash
+set -euo pipefail
+here="$(cd "$(dirname "$0")" && pwd)"
+exec "$here/GamePort" --assets "$here/assets" --scene "$here/scenes/level1b/scene.json" --level gam/level1b.gam --original-camera --with-player "$@"
+LAUNCH
+chmod +x dist/linux-x64/launch-scene.sh
+cat > dist/win-x64/launch-scene.cmd <<'LAUNCH'
+@echo off
+"%~dp0GamePort.exe" --assets "%~dp0assets" --scene "%~dp0scenes\level1b\scene.json" --level gam/level1b.gam --original-camera --with-player %*
+LAUNCH
+printf '%s\n' 'Local Linux and Windows investigation packages prepared in dist/.'
diff --git a/scripts/test.sh b/scripts/test.sh
new file mode 100755
index 0000000..20a823f
--- /dev/null
+++ b/scripts/test.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "$0")/env.sh"
+python3 -m unittest discover -s tests -p 'test_*.py' -v
+python3 tools/extractors/prepare.py --audio sounds musicsecretlab
+dotnet run --project tests/GamePort.DataTests -- ../Original
+dotnet build GamePort.csproj
+dotnet run --no-build -- --verify-assets --assets ../Original
+python3 tools/extractors/omt.py ../Original/omt/level1b.omt --scene --output artifacts/extracted/level1b
+dotnet run --no-build -- --headless --assets ../Original --scene artifacts/extracted/level1b/scene.json --level gam/level1b.gam --original-camera --screenshot artifacts/test-level1b.ppm
+dotnet run --no-build -- --headless --with-player --time 0.05 --screenshot artifacts/test-player.ppm
+SDL_AUDIODRIVER=dummy dotnet run --no-build -- --audio-smoke artifacts/extracted/sounds/Wave_00000001_save.wav
+python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
+if [[ "${NEUTRON_WINDOW_TEST:-0}" == 1 ]]; then
+ dotnet run --no-build -- --scene artifacts/extracted/level1b/scene.json --smoke-window --frames 6 --screenshot artifacts/test-window.ppm
+fi
diff --git a/src/GamePort/Assets/AseMesh.cs b/src/GamePort/Assets/AseMesh.cs
new file mode 100644
index 0000000..6c4ef1b
--- /dev/null
+++ b/src/GamePort/Assets/AseMesh.cs
@@ -0,0 +1,51 @@
+using System.Globalization;
+using System.Numerics;
+using System.Text.RegularExpressions;
+
+namespace GamePort.Assets;
+
+/// First base MESH only; animation frames remain preserved in original ASE.
+public static class AseMesh
+{
+ private static float F(string value) => float.Parse(value, CultureInfo.InvariantCulture);
+ private static int I(string value) => int.Parse(value, CultureInfo.InvariantCulture);
+
+ public static Mesh Load(string path)
+ {
+ var text = File.ReadAllText(path);
+ var start = text.IndexOf("*MESH {", StringComparison.Ordinal);
+ if (start < 0) throw new InvalidDataException("ASE has no mesh.");
+ var end = start + 7;
+ for (int depth = 1; depth > 0 && end < text.Length; end++)
+ {
+ if (text[end] == '{') depth++;
+ else if (text[end] == '}') depth--;
+ }
+ text = text[start..end];
+ const string number = @"([-+0-9.eE]+)";
+ var positions = Regex.Matches(text, @"\*MESH_VERTEX\s+(\d+)\s+" + number + @"\s+" + number + @"\s+" + number)
+ .ToDictionary(m => I(m.Groups[1].Value), m => new Vector3(F(m.Groups[2].Value), F(m.Groups[3].Value), F(m.Groups[4].Value)));
+ var uvs = Regex.Matches(text, @"\*MESH_TVERT\s+(\d+)\s+" + number + @"\s+" + number)
+ .ToDictionary(m => I(m.Groups[1].Value), m => new Vector2(F(m.Groups[2].Value), -F(m.Groups[3].Value)));
+ var uvFaces = Regex.Matches(text, @"\*MESH_TFACE\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)")
+ .ToDictionary(m => I(m.Groups[1].Value), m => new[] {I(m.Groups[2].Value), I(m.Groups[3].Value), I(m.Groups[4].Value)});
+ var vertices = new List();
+ foreach (Match m in Regex.Matches(text, @"\*MESH_FACE\s+(\d+):\s+A:\s+(\d+)\s+B:\s+(\d+)\s+C:\s+(\d+)"))
+ {
+ var face = I(m.Groups[1].Value);
+ var a = positions[I(m.Groups[2].Value)];
+ var b = positions[I(m.Groups[3].Value)];
+ var c = positions[I(m.Groups[4].Value)];
+ // Exact ASE/OMT shared mesh comparison establishes (x,y,z)->(x,z,y).
+ Vector3 Map(Vector3 p) => new(p.X, p.Z, p.Y);
+ for (var corner=0; corner<3; corner++)
+ {
+ var p = positions[I(m.Groups[corner+2].Value)];
+ var uv = uvFaces.TryGetValue(face, out var f) && uvs.TryGetValue(f[corner], out var t) ? t : Vector2.Zero;
+ vertices.Add(new MeshVertex(Map(p), uv, Vector3.One));
+ }
+ }
+ if (vertices.Count == 0) throw new InvalidDataException("ASE has no triangles.");
+ return new Mesh(vertices.ToArray(), Enumerable.Range(0, vertices.Count).Select(i => (uint)i).ToArray());
+ }
+}
diff --git a/src/GamePort/Assets/AssetPath.cs b/src/GamePort/Assets/AssetPath.cs
new file mode 100644
index 0000000..7ad409f
--- /dev/null
+++ b/src/GamePort/Assets/AssetPath.cs
@@ -0,0 +1,30 @@
+namespace GamePort.Assets;
+
+public static class AssetPath
+{
+ public static string Resolve(string root, string relative)
+ {
+ var current = Path.GetFullPath(root);
+ foreach (var part in relative.Replace('\\', '/').Split('/', StringSplitOptions.RemoveEmptyEntries))
+ {
+ if (part is "." or "..") throw new InvalidDataException("Asset paths must stay within their root.");
+ var direct = Path.Combine(current, part);
+ if (File.Exists(direct) || Directory.Exists(direct)) { current = direct; continue; }
+ var matches = Directory.EnumerateFileSystemEntries(current)
+ .Where(p => string.Equals(Path.GetFileName(p), part, StringComparison.OrdinalIgnoreCase)).ToArray();
+ if (matches.Length != 1) throw new FileNotFoundException($"Missing or ambiguous asset: {relative}");
+ current = matches[0];
+ }
+ return current;
+ }
+
+ public static string FindOriginal(string? requested)
+ {
+ if (requested != null) return Path.GetFullPath(requested);
+ foreach (var start in new[] { Directory.GetCurrentDirectory(), AppContext.BaseDirectory })
+ for (var dir = new DirectoryInfo(start); dir != null; dir = dir.Parent)
+ foreach (var name in new[] { "Original", "original", "assets" })
+ if (Directory.Exists(Path.Combine(dir.FullName, name, "ASE"))) return Path.Combine(dir.FullName, name);
+ throw new DirectoryNotFoundException("Original assets not found. Use --assets /path/to/Original.");
+ }
+}
diff --git a/src/GamePort/Assets/Mesh.cs b/src/GamePort/Assets/Mesh.cs
new file mode 100644
index 0000000..5f7d612
--- /dev/null
+++ b/src/GamePort/Assets/Mesh.cs
@@ -0,0 +1,78 @@
+using System.Numerics;
+using System.Runtime.InteropServices;
+using System.Text.Json;
+
+namespace GamePort.Assets;
+
+[StructLayout(LayoutKind.Sequential)]
+public struct MeshVertex(Vector3 position, Vector2 uv, Vector3 color)
+{
+ public Vector3 Position = position;
+ public Vector2 Uv = uv;
+ public Vector3 Color = color;
+}
+
+public sealed record Mesh(MeshVertex[] Vertices, uint[] Indices)
+{
+ public MeshDraw[] Draws { get; init; } = [];
+ public bool HasExplicitDraws { get; init; }
+ public Dictionary Textures { get; init; } = [];
+ public (Vector3 Min, Vector3 Max) Bounds()
+ {
+ var min = new Vector3(float.PositiveInfinity);
+ var max = new Vector3(float.NegativeInfinity);
+ foreach (var vertex in Vertices) { min = Vector3.Min(min, vertex.Position); max = Vector3.Max(max, vertex.Position); }
+ return (min, max);
+ }
+
+ public static Mesh LoadSceneJson(string path)
+ {
+ using var doc = JsonDocument.Parse(File.ReadAllText(path));
+ var root = doc.RootElement;
+ var positions = root.GetProperty("vertices").EnumerateArray().ToArray();
+ var uvs = root.TryGetProperty("uvs", out var uvElement) ? uvElement.EnumerateArray().ToArray() : [];
+ var vertices = positions.Select((p, i) => new MeshVertex(
+ new Vector3(p[0].GetSingle(), p[1].GetSingle(), p[2].GetSingle()),
+ i < uvs.Length ? new Vector2(uvs[i][0].GetSingle(), uvs[i][1].GetSingle()) : Vector2.Zero,
+ Vector3.One)).ToArray();
+ var indices = root.GetProperty("indices").EnumerateArray().Select(p => p.GetUInt32()).ToArray();
+ if (indices.Length % 3 != 0 || indices.Any(i => i >= vertices.Length)) throw new InvalidDataException("Invalid scene triangle indices.");
+ if (vertices.Length == 0 || indices.Length == 0) throw new InvalidDataException("Empty scene mesh.");
+ var textures = new Dictionary();
+ if(root.TryGetProperty("textures",out var textureList)) foreach(var t in textureList.EnumerateArray())
+ {
+ var id=t.GetProperty("id").GetInt32();
+ var w=t.GetProperty("width").GetUInt32(); var h=t.GetProperty("height").GetUInt32();
+ var bytes=File.ReadAllBytes(Path.Combine(Path.GetDirectoryName(path)!,t.GetProperty("path").GetString()!));
+ if(w>8192 || h>8192 || bytes.Length!=checked((int)(w*h*4)))throw new InvalidDataException("Invalid decoded texture size.");
+ textures[id]=new PngImage(w,h,bytes);
+ }
+ var materials=new Dictionary();
+ var hasMaterials = root.TryGetProperty("materials",out var materialList);
+ if(hasMaterials) foreach(var m in materialList.EnumerateArray())
+ {
+ var texture=-1;
+ if(m.TryGetProperty("texture",out var t) && t.ValueKind==JsonValueKind.Object && t.TryGetProperty("id",out var ti))texture=ti.GetInt32();
+ var diffuse=Vector3.One;
+ if(m.TryGetProperty("colours",out var colors) && colors.TryGetProperty("diffuse",out var d))diffuse=new(d[0].GetSingle(),d[1].GetSingle(),d[2].GetSingle());
+ materials[m.GetProperty("id").GetInt32()]=(texture,diffuse);
+ }
+ var draws=new List();
+ if(root.TryGetProperty("meshes",out var meshList))foreach(var m in meshList.EnumerateArray())
+ {
+ var first=m.GetProperty("firstIndex").GetUInt32();var count=m.GetProperty("indexCount").GetUInt32();
+ if((ulong)first+count>(ulong)indices.Length)throw new InvalidDataException("Scene draw exceeds indices.");
+ // Original DX draw_shape at DLL 0x1003756C skips null material
+ // pointers. Retain their geometry, but never invent white surfaces.
+ if (hasMaterials && (!m.TryGetProperty("material", out var materialId)
+ || materialId.ValueKind != JsonValueKind.Number
+ || !materials.ContainsKey(materialId.GetInt32()))) continue;
+ var material=m.TryGetProperty("material",out var mid) && mid.ValueKind==JsonValueKind.Number && materials.TryGetValue(mid.GetInt32(),out var mat)?mat:(-1,Vector3.One);
+ for(var i=first;iOriginal vertex samples and base topology, prepared by ase.py.
+public sealed class MorphAnimation
+{
+ public Mesh Base { get; }
+ public PngImage Texture { get; }
+ public double SampleInterval { get; }
+ private readonly Mesh[] frames;
+
+ public MorphAnimation(string manifestPath)
+ {
+ var directory = Path.GetDirectoryName(Path.GetFullPath(manifestPath))!;
+ using var document = JsonDocument.Parse(File.ReadAllText(manifestPath));
+ var root = document.RootElement;
+ var fps = root.GetProperty("framesPerSecond").GetDouble();
+ var ticks = root.GetProperty("ticksPerFrame").GetDouble();
+ if (!double.IsFinite(fps) || !double.IsFinite(ticks) || fps <= 0 || ticks <= 0)
+ throw new InvalidDataException("Invalid morph timing");
+ var samples = root.GetProperty("frames").EnumerateArray().ToArray();
+ if (samples.Length == 0) throw new InvalidDataException("No morph samples");
+ frames = samples.Select(s => Mesh.LoadSceneJson(Path.Combine(directory,
+ s.GetProperty("path").GetString()!))).ToArray();
+ Base = frames[0];
+ if (frames.Any(f => f.Vertices.Length != Base.Vertices.Length
+ || !f.Indices.SequenceEqual(Base.Indices)))
+ throw new InvalidDataException("Morph sample topology differs from base");
+ for (var i = 0; i < Base.Vertices.Length; i++)
+ if (frames.Any(f => f.Vertices[i].Uv != Base.Vertices[i].Uv))
+ throw new InvalidDataException("Morph sample UV differs from base");
+ SampleInterval = frames.Length > 1
+ ? (samples[1].GetProperty("time").GetDouble() - samples[0].GetProperty("time").GetDouble()) / ticks / fps
+ : 1 / fps;
+ if (!double.IsFinite(SampleInterval) || SampleInterval <= 0)
+ throw new InvalidDataException("Invalid morph sample interval");
+ for (var i = 1; i < samples.Length; i++)
+ {
+ var actual = (samples[i].GetProperty("time").GetDouble() - samples[0].GetProperty("time").GetDouble()) / ticks / fps;
+ if (Math.Abs(actual - i * SampleInterval) > 0.000001)
+ throw new NotSupportedException("Irregular sample times require original timing recovery");
+ }
+ var texture = root.GetProperty("texture");
+ var width = texture.GetProperty("width").GetUInt32();
+ var height = texture.GetProperty("height").GetUInt32();
+ var rgba = File.ReadAllBytes(Path.Combine(directory, texture.GetProperty("path").GetString()!));
+ if (width == 0 || height == 0 || width > 8192 || height > 8192
+ || rgba.Length != checked((int)(width * height * 4)))
+ throw new InvalidDataException("Invalid morph texture");
+ Texture = new PngImage(width, height, rgba);
+ }
+
+ public void Sample(double seconds, Span destination, Matrix4x4 model)
+ {
+ if (!double.IsFinite(seconds) || seconds < 0) throw new ArgumentOutOfRangeException(nameof(seconds));
+ if (destination.Length != Base.Vertices.Length) throw new ArgumentException("Morph target size differs");
+ // Linear interpolation is recovered from DLL 0x10002F9A. Loop closure
+ // and gameplay-specific speed remain preview policies until recovered.
+ var frame = seconds / SampleInterval;
+ var first = (int)(Math.Floor(frame) % frames.Length);
+ var next = (first + 1) % frames.Length;
+ var t = (float)(frame - Math.Floor(frame));
+ for (var i = 0; i < destination.Length; i++)
+ {
+ destination[i] = Base.Vertices[i];
+ destination[i].Position = Vector3.Transform(Vector3.Lerp(frames[first].Vertices[i].Position,
+ frames[next].Vertices[i].Position, t), model);
+ }
+ }
+
+ public Mesh AppendTo(Mesh scene)
+ {
+ var vertices = new MeshVertex[scene.Vertices.Length + Base.Vertices.Length];
+ scene.Vertices.CopyTo(vertices, 0);
+ Base.Vertices.CopyTo(vertices, scene.Vertices.Length);
+ var indices = scene.Indices.Concat(Base.Indices.Select(i => checked(i + (uint)scene.Vertices.Length))).ToArray();
+ var draws = scene.HasExplicitDraws ? scene.Draws : [new MeshDraw(0, (uint)scene.Indices.Length, -1)];
+ var textures = new Dictionary(scene.Textures) { [int.MinValue] = Texture };
+ return new Mesh(vertices, indices)
+ {
+ HasExplicitDraws = true,
+ Draws = [.. draws, new MeshDraw((uint)scene.Indices.Length, (uint)Base.Indices.Length, int.MinValue)],
+ Textures = textures
+ };
+ }
+}
diff --git a/src/GamePort/Assets/PngImage.cs b/src/GamePort/Assets/PngImage.cs
new file mode 100644
index 0000000..2dbda16
--- /dev/null
+++ b/src/GamePort/Assets/PngImage.cs
@@ -0,0 +1,89 @@
+using System.Buffers.Binary;
+using System.IO.Compression;
+
+namespace GamePort.Assets;
+
+public sealed record PngImage(uint Width, uint Height, byte[] Rgba)
+{
+ public static PngImage White => new(1, 1, [255,255,255,255]);
+
+ public static PngImage Load(string path)
+ {
+ using var file = File.OpenRead(path);
+ Span signature = stackalloc byte[8];
+ file.ReadExactly(signature);
+ if(signature[0]==(byte)'B' && signature[1]==(byte)'M')return LoadBmp(path);
+ if (!signature.SequenceEqual(new byte[] {137,80,78,71,13,10,26,10})) throw new InvalidDataException("Invalid PNG signature.");
+ uint width=0, height=0; byte color=0; byte[] palette=[], alpha=[];
+ using var compressed = new MemoryStream();
+ Span header = stackalloc byte[8];
+ Span crc = stackalloc byte[4];
+ while (true)
+ {
+ file.ReadExactly(header);
+ var size = BinaryPrimitives.ReadUInt32BigEndian(header);
+ if (size > 64*1024*1024) throw new InvalidDataException("PNG chunk exceeds limit.");
+ var data = new byte[(int)size]; file.ReadExactly(data);
+ file.ReadExactly(crc);
+ var kind = System.Text.Encoding.ASCII.GetString(header[4..]);
+ if (kind == "IHDR")
+ {
+ if (data.Length != 13) throw new InvalidDataException("Invalid PNG IHDR.");
+ width=BinaryPrimitives.ReadUInt32BigEndian(data); height=BinaryPrimitives.ReadUInt32BigEndian(data.AsSpan(4));
+ if (width==0 || height==0 || width>8192 || height>8192 || data[8]!=8 || data[10]!=0 || data[11]!=0 || data[12]!=0)
+ throw new NotSupportedException("Only non-interlaced 8-bit PNGs up to 8192 pixels are supported.");
+ color=data[9];
+ }
+ else if (kind == "PLTE") palette=data;
+ else if (kind == "tRNS") alpha=data;
+ else if (kind == "IDAT") compressed.Write(data);
+ else if (kind == "IEND") break;
+ }
+ var channels = color switch {0=>1,2=>3,3=>1,4=>2,6=>4,_=>throw new NotSupportedException($"PNG color type {color} unsupported.")};
+ var stride = checked((int)width*channels);
+ var scan = new byte[checked((stride+1)*(int)height)];
+ compressed.Position=0;
+ using (var z = new ZLibStream(compressed, CompressionMode.Decompress, true)) {z.ReadExactly(scan); if(z.ReadByte()!=-1)throw new InvalidDataException("Excess PNG data.");}
+ var pixels=new byte[checked(stride*(int)height)];
+ for(int y=0;y=channels?pixels[i-channels]:0; var b=y>0?pixels[i-stride]:0; var c=y>0&&x>=channels?pixels[i-stride-channels]:0;
+ var predictor=scan[y*(stride+1)] switch {0=>0,1=>a,2=>b,3=>(a+b)/2,4=>Paeth(a,b,c),_=>throw new InvalidDataException("Invalid PNG filter.")};
+ pixels[i]=unchecked((byte)(scan[y*(stride+1)+x+1]+predictor));
+ }
+ var rgba=new byte[checked((int)(width*height*4))];
+ for(int i=0;i=palette.Length)throw new InvalidDataException("PNG palette index out of bounds.");
+ rgba[d]=palette[p*3];rgba[d+1]=palette[p*3+1];rgba[d+2]=palette[p*3+2];rgba[d+3]=p8192 || h==0 || h< -8192 || h>8192 || compression!=0 || depth is not (8 or 24 or 32))throw new NotSupportedException("Only uncompressed 8/24/32-bit BMP is supported.");
+ var height=Math.Abs(h);var stride=checked((w*depth+31)/32*4);
+ if((ulong)offset+(ulong)stride*(uint)height>(ulong)bytes.Length)throw new InvalidDataException("Truncated BMP pixels.");
+ var palette=14+checked((int)BinaryPrimitives.ReadUInt32LittleEndian(bytes.AsSpan(14)));
+ var rgba=new byte[checked(w*height*4)];
+ for(var y=0;y0?height-1-y:y)*stride+x*(depth/8);
+ if(depth==8){src=palette+bytes[src]*4;if(src+4>offset)throw new InvalidDataException("BMP palette index out of range.");}
+ var dst=(y*w+x)*4;rgba[dst]=bytes[src+2];rgba[dst+1]=bytes[src+1];rgba[dst+2]=bytes[src];rgba[dst+3]=255;
+ }
+ return new PngImage((uint)w,(uint)height,rgba);
+ }
+ private static int Paeth(int a,int b,int c){var p=a+b-c;var pa=Math.Abs(p-a);var pb=Math.Abs(p-b);var pc=Math.Abs(p-c);return pa<=pb&&pa<=pc?a:pb<=pc?b:c;}
+}
diff --git a/src/GamePort/Audio/SdlAudio.cs b/src/GamePort/Audio/SdlAudio.cs
new file mode 100644
index 0000000..f6e2e77
--- /dev/null
+++ b/src/GamePort/Audio/SdlAudio.cs
@@ -0,0 +1,44 @@
+using GamePort.Platform;
+
+namespace GamePort.Audio;
+
+/// Plays recovered WAV unchanged through an SDL3 conversion/mixing stream.
+public sealed class SdlAudio : IDisposable
+{
+ private nint stream;
+ private nint data;
+ private int length;
+ private readonly bool loop;
+ public int QueuedBytes
+ {
+ get
+ {
+ var bytes = Sdl.SDL_GetAudioStreamQueued(stream);
+ return bytes >= 0 ? bytes : throw new InvalidOperationException(Sdl.Error);
+ }
+ }
+ public SdlAudio(string path,bool loop=false)
+ {
+ this.loop=loop;
+ if(!Sdl.SDL_InitSubSystem(Sdl.InitAudio))throw new InvalidOperationException(Sdl.Error);
+ try
+ {
+ if(!Sdl.SDL_LoadWAV(Path.GetFullPath(path),out var spec,out data,out var size))throw new InvalidOperationException(Sdl.Error);
+ length=checked((int)size);
+ stream=Sdl.SDL_OpenAudioDeviceStream(uint.MaxValue,ref spec,0,0);
+ if(stream==0)throw new InvalidOperationException(Sdl.Error);
+ Queue();
+ if(!Sdl.SDL_ResumeAudioStreamDevice(stream))throw new InvalidOperationException(Sdl.Error);
+ Console.WriteLine($"SDL3 WAV stream: {spec.Frequency} Hz, {spec.Channels} channel(s), {length} source bytes.");
+ }
+ catch{Dispose();throw;}
+ }
+ private void Queue(){if(!Sdl.SDL_PutAudioStreamData(stream,data,length))throw new InvalidOperationException(Sdl.Error);}
+ public void Pump(){if(loop && QueuedBytes
+/// Recovered arithmetic fragments, not a complete controller or collision system.
+/// Addresses and remaining call/gating questions are in docs/analysis/binary.md.
+///
+public static class RecoveredMotion
+{
+ public const float SpeedIncrement = 30f; // ctor +0x6BC; EXE 0x4392ED
+ public const float SpeedDecay = 35f; // ctor +0x6C0; EXE 0x439433
+ public const float MaximumSpeed = 600f; // ctor +0x6C4
+ public const float JumpImpulse = 550f; // EXE 0x4383B3, subject to original jump state gating
+ public static readonly Vector3 Gravity = new(0f, -800f, 0f); // EXE 0x44D414
+ public static readonly Vector3 CameraFollowOffset = new(0f, 200f, -350f);
+ public static readonly Vector3 CameraTargetOffset = new(0f, 80f, 0f);
+
+ // Deliberately per invocation: original increments omit dt. Call cadence is
+ // not yet verified. Rendering must not directly choose simulation cadence.
+ public static float AddSpeed(float speed) => MathF.Min(speed + SpeedIncrement, MaximumSpeed);
+ public static float ReleaseSpeed(float speed) => speed > 0
+ ? MathF.Max(0, speed - SpeedDecay) : MathF.Min(0, speed + SpeedDecay);
+
+ ///
+ /// EXE 0x479EBB..0x479FC0: consume impulse, acceleration, gravity, then
+ /// integrate displacement using updated velocity. Collision is applied later
+ /// by original code and must be supplied by the caller after recovery. Player
+ /// airborne states add their own acceleration, e.g. gravity*1.33-gravity in
+ /// states below 3 at EXE 0x438148; gravity alone is not the full jump model.
+ ///
+ public static Vector3 Integrate(ref Vector3 velocity, ref Vector3 impulse,
+ Vector3 acceleration, Vector3 gravity, float seconds)
+ {
+ if (!float.IsFinite(seconds) || seconds <= 0 || seconds >= 1)
+ throw new ArgumentOutOfRangeException(nameof(seconds), "Original frame accepts 0 < dt < 1");
+ velocity += impulse;
+ impulse = Vector3.Zero;
+ velocity += acceleration * seconds;
+ velocity += gravity * seconds;
+ return velocity * seconds;
+ }
+}
+
+/// Wrapping original LCG at EXE 0x438D52; unrelated to System.Random.
+public struct OriginalRandom(uint seed)
+{
+ public uint State { get; private set; } = seed;
+ public uint Next()
+ {
+ State = unchecked(State * 1664525u + 32767u);
+ return State >> 16;
+ }
+}
diff --git a/src/GamePort/Platform/Sdl.cs b/src/GamePort/Platform/Sdl.cs
new file mode 100644
index 0000000..158899b
--- /dev/null
+++ b/src/GamePort/Platform/Sdl.cs
@@ -0,0 +1,57 @@
+using System.Reflection;
+using System.Runtime.InteropServices;
+
+namespace GamePort.Platform;
+
+internal static unsafe class Sdl
+{
+ private const string Library="SDL3";
+ static Sdl()
+ {
+ NativeLibrary.SetDllImportResolver(typeof(Sdl).Assembly, (name, assembly, path) =>
+ {
+ if(name!=Library)return 0;
+ var filename=OperatingSystem.IsWindows()?"SDL3.dll":"libSDL3.so.0";
+ foreach(var candidate in new[]{Path.Combine(AppContext.BaseDirectory,filename),Path.Combine(Directory.GetCurrentDirectory(),".tools/sdl/lib",filename),filename})
+ if(NativeLibrary.TryLoad(candidate,out var handle))return handle;
+ return 0;
+ });
+ }
+ public const uint InitVideo=0x20, InitAudio=0x10;
+ public const ulong WindowVulkan=0x10000000, WindowResizable=0x20, WindowHighPixelDensity=0x2000;
+ public const uint Quit=0x100, KeyDown=0x300, KeyUp=0x301, WindowResized=0x206, WindowPixelSizeChanged=0x207, WindowFocusLost=0x20F;
+ [StructLayout(LayoutKind.Explicit,Size=128)] public struct Event
+ {
+ [FieldOffset(0)]public uint Type;
+ [FieldOffset(16)]public uint WindowId;
+ [FieldOffset(24)]public uint Scancode;
+ [FieldOffset(28)]public uint Key;
+ [FieldOffset(36)]public byte Down;
+ [FieldOffset(37)]public byte Repeat;
+ }
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)] public static extern bool SDL_Init(uint flags);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] public static extern void SDL_Quit();
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] private static extern nint SDL_GetError();
+ public static string Error=>Marshal.PtrToStringUTF8(SDL_GetError())??"SDL error";
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] public static extern nint SDL_CreateWindow([MarshalAs(UnmanagedType.LPUTF8Str)]string title,int w,int h,ulong flags);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)]public static extern void SDL_DestroyWindow(nint window);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_PollEvent(out Event e);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)]public static extern byte** SDL_Vulkan_GetInstanceExtensions(out uint count);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_Vulkan_CreateSurface(nint window,nint instance,void* allocator,out ulong surface);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_GetWindowSizeInPixels(nint window,out int w,out int h);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_SetWindowFullscreen(nint window,[MarshalAs(UnmanagedType.I1)]bool fullscreen);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_SetWindowRelativeMouseMode(nint window,[MarshalAs(UnmanagedType.I1)]bool enabled);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_SetWindowSize(nint window,int width,int height);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_PushEvent(ref Event e);
+ [StructLayout(LayoutKind.Sequential)]public struct AudioSpec {public uint Format;public int Channels;public int Frequency;}
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_InitSubSystem(uint flags);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)]public static extern void SDL_QuitSubSystem(uint flags);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_LoadWAV([MarshalAs(UnmanagedType.LPUTF8Str)]string path,out AudioSpec spec,out nint buffer,out uint length);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)]public static extern void SDL_free(nint buffer);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)]public static extern nint SDL_OpenAudioDeviceStream(uint device,ref AudioSpec spec,nint callback,nint user);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_ResumeAudioStreamDevice(nint stream);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)] [return:MarshalAs(UnmanagedType.I1)]public static extern bool SDL_PutAudioStreamData(nint stream,nint buffer,int length);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)]public static extern int SDL_GetAudioStreamQueued(nint stream);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)]public static extern void SDL_DestroyAudioStream(nint stream);
+ [DllImport(Library,CallingConvention=CallingConvention.Cdecl)]public static extern void SDL_Delay(uint ms);
+}
diff --git a/src/GamePort/Program.cs b/src/GamePort/Program.cs
new file mode 100644
index 0000000..d0074f3
--- /dev/null
+++ b/src/GamePort/Program.cs
@@ -0,0 +1,230 @@
+using System.Diagnostics;
+using System.Numerics;
+using GamePort.Assets;
+using GamePort.Audio;
+using GamePort.Platform;
+using GamePort.Rendering.Vulkan;
+
+namespace GamePort;
+
+internal static class Program
+{
+ public static int Main(string[] args)
+ {
+ try { return Run(args); }
+ catch (Exception error) { Console.Error.WriteLine(error); return 1; }
+ }
+
+ private static string? Option(string[] args, string name)
+ {
+ var i = Array.IndexOf(args, name);
+ if (i < 0) return null;
+ if (i + 1 >= args.Length || args[i + 1].StartsWith("--", StringComparison.Ordinal))
+ throw new ArgumentException($"{name} requires a value.");
+ return args[i + 1];
+ }
+
+ private static int Run(string[] args)
+ {
+ if (args.Contains("--help"))
+ {
+ Console.WriteLine("""
+ Neutron reconstruction investigation runtime
+ --assets PATH Original asset directory
+ --scene PATH Extracted OMT scene JSON (default: prepared LV1B)
+ --model RELPATH Original ASE model (default without scene: ASE/jimstop.ase)
+ --texture RELPATH PNG override (default: png/jimycarl.png)
+ --level RELPATH Original GAM (default with prepared LV1B: gam/level1b.gam)
+ --original-camera Stored GAM start camera and recovered projection
+ --animation PATH Prepared Jimmy animation.json; place at GAM startpoint
+ --with-player Use prepared jimstop animation in scene
+ --time SECONDS Fixed animation time for comparisons
+ --headless Render offscreen through Vulkan
+ --screenshot PATH Save actual GPU readback as PPM
+ --frames N Exit after N frames (headless default: 1)
+ --audio PATH Play recovered WAV; --loop-audio repeats it
+ --audio-smoke PATH Verify audio-stream consumption
+ --verify-assets Decode all original PNG/ASE files
+ --smoke-window Test keyboard event/resize (requires --frames 6 or more)
+ --no-validation Disable development validation
+ Viewer: C toggles stored/orbit camera, arrows/WASD orbit, +/- zoom,
+ F11 fullscreen, Escape quit.
+ Gameplay, original animation speed/state and cutscenes remain under reconstruction.
+ """);
+ return 0;
+ }
+ var root = AssetPath.FindOriginal(Option(args, "--assets"));
+ if (args.Contains("--verify-assets")) return VerifyAssets(root);
+ if (Option(args, "--audio-smoke") is { } audioSmoke)
+ {
+ using var sound = new SdlAudio(audioSmoke);
+ var before = sound.QueuedBytes;
+ Thread.Sleep(500);
+ var after = sound.QueuedBytes;
+ Console.WriteLine($"SDL3 audio stream consumed {before - after} source bytes in 500 ms; queued {after}.");
+ return after < before ? 0 : 2;
+ }
+
+ var scene = Option(args, "--scene");
+ var defaultScene = false;
+ if (scene == null && Option(args, "--model") == null)
+ {
+ scene = new[] { "artifacts/extracted/level1b/scene.json",
+ Path.Combine(AppContext.BaseDirectory, "scenes/level1b/scene.json") }.FirstOrDefault(File.Exists);
+ defaultScene = scene != null;
+ }
+ var levelPath = Option(args, "--level") ?? (defaultScene ? "gam/level1b.gam" : null);
+ GamLevel? level = levelPath == null ? null : GamLevel.Load(AssetPath.Resolve(root, levelPath));
+ var originalStart = level?.FindStart();
+ if (level != null) Console.WriteLine($"Decoded GAM {level.Code}: {level.Entities.Count} entities.");
+ var originalCamera = args.Contains("--original-camera") || defaultScene;
+ if (originalCamera && originalStart == null)
+ throw new ArgumentException("Original camera requires a GAM with a matching startpoint.");
+
+ var mesh = scene != null ? Mesh.LoadSceneJson(scene)
+ : AseMesh.Load(AssetPath.Resolve(root, Option(args, "--model") ?? "ASE/jimstop.ase"));
+ var texture = scene != null ? PngImage.White
+ : PngImage.Load(AssetPath.Resolve(root, Option(args, "--texture") ?? "png/jimycarl.png"));
+ var bounds = mesh.Bounds();
+ var target = (bounds.Min + bounds.Max) / 2;
+ var radius = Math.Max(Vector3.Distance(bounds.Min, bounds.Max) * 1.15f, 1);
+ var animationPath = Option(args, "--animation");
+ if (args.Contains("--with-player") && scene != null)
+ animationPath ??= Path.Combine(Path.GetDirectoryName(scene)!, "../animations/jimstop/animation.json");
+ MorphAnimation? animation = null;
+ var characterOffset = mesh.Vertices.Length;
+ var characterModel = Matrix4x4.Identity;
+ if (animationPath != null)
+ {
+ if (scene == null || originalStart == null)
+ throw new ArgumentException("A scene and matching GAM are required to place an animated player.");
+ animation = new MorphAnimation(animationPath);
+ mesh = animation.AppendTo(mesh);
+ characterModel = Matrix4x4.CreateRotationY(-originalStart.Rotation.Y * MathF.PI / 180)
+ * Matrix4x4.CreateTranslation(originalStart.Position);
+ Console.WriteLine("Original morph data loaded; playback looping/speed are preview policies.");
+ }
+ Console.WriteLine($"Loaded original geometry: {mesh.Vertices.Length} vertices, {mesh.Indices.Length / 3} triangles, {mesh.Textures.Count + (scene == null ? 1 : 0)} textures.");
+ var fixedTimeText = Option(args, "--time");
+ double? fixedTime = fixedTimeText == null ? null : double.Parse(fixedTimeText, System.Globalization.CultureInfo.InvariantCulture);
+ var headless = args.Contains("--headless");
+ var frames = int.Parse(Option(args, "--frames") ?? (headless ? "1" : "0"));
+ var smoke = args.Contains("--smoke-window");
+ if (frames < 0 || (smoke && (headless || frames < 6)))
+ throw new ArgumentException("Invalid frame count; window smoke requires at least six frames.");
+ nint window = 0;
+ if (!headless)
+ {
+ if (!Sdl.SDL_Init(Sdl.InitVideo)) throw new InvalidOperationException(Sdl.Error);
+ window = Sdl.SDL_CreateWindow("Jimmy Neutron reconstruction — scene investigation", 960, 720,
+ Sdl.WindowVulkan | Sdl.WindowResizable | Sdl.WindowHighPixelDensity);
+ if (window == 0) { Sdl.SDL_Quit(); throw new InvalidOperationException(Sdl.Error); }
+ }
+ try
+ {
+ using var renderer = new VulkanRenderer(mesh, texture, 960, 720, window, !args.Contains("--no-validation"));
+ using var audio = Option(args, "--audio") is { } audioFile
+ ? new SdlAudio(audioFile, args.Contains("--loop-audio")) : null;
+ var keys = new HashSet();
+ var running = true;
+ var fullscreen = false;
+ var sawKey = false;
+ var didResize = false;
+ var clock = Stopwatch.StartNew();
+ double last = clock.Elapsed.TotalSeconds;
+ float angle = 0.6f, elevation = 0.32f;
+ var count = 0;
+ while (running)
+ {
+ while (!headless && Sdl.SDL_PollEvent(out var e))
+ {
+ if (e.Type is Sdl.Quit or 0x210) running = false;
+ if (e.Type is Sdl.WindowResized or Sdl.WindowPixelSizeChanged) renderer.Resize();
+ if (e.Type == Sdl.WindowFocusLost) keys.Clear();
+ if (e.Type == Sdl.KeyDown)
+ {
+ keys.Add(e.Scancode);
+ if (smoke && e.Scancode == 79) sawKey = true;
+ if (e.Scancode == 41) running = false;
+ if (e.Scancode == 6 && e.Repeat == 0 && originalStart != null)
+ originalCamera = !originalCamera;
+ if (e.Scancode == 68 && e.Repeat == 0)
+ {
+ fullscreen = !fullscreen;
+ if (!Sdl.SDL_SetWindowFullscreen(window, fullscreen)) throw new InvalidOperationException(Sdl.Error);
+ }
+ }
+ if (e.Type == Sdl.KeyUp) keys.Remove(e.Scancode);
+ }
+ var now = clock.Elapsed.TotalSeconds;
+ var dt = (float)Math.Min(now - last, 0.1);
+ last = now;
+ if (keys.Contains(80) || keys.Contains(4)) angle -= dt;
+ if (keys.Contains(79) || keys.Contains(7)) angle += dt;
+ if (keys.Contains(82) || keys.Contains(26)) elevation = Math.Min(elevation + dt, 1.4f);
+ if (keys.Contains(81) || keys.Contains(22)) elevation = Math.Max(elevation - dt, -1.4f);
+ if (keys.Contains(46) || keys.Contains(87)) radius *= MathF.Exp(-dt);
+ if (keys.Contains(45) || keys.Contains(86)) radius *= MathF.Exp(dt);
+ radius = Math.Max(radius, 0.01f);
+ var eye = target + radius * new Vector3(MathF.Cos(elevation) * MathF.Sin(angle),
+ MathF.Sin(elevation), MathF.Cos(elevation) * MathF.Cos(angle));
+ var view = originalCamera
+ ? Matrix4x4.CreateLookAtLeftHanded(originalStart!.CameraPosition, originalStart.Position + new Vector3(0, 80, 0), Vector3.UnitY)
+ : Matrix4x4.CreateLookAt(eye, target, Vector3.UnitY);
+ var far = level?.Code == "LV1B" ? 10000 : 3200;
+ var projection = originalCamera
+ ? Matrix4x4.CreatePerspectiveFieldOfViewLeftHanded(0xAAA / 16384f * MathF.Tau, (float)renderer.Width / renderer.Height, 20, far)
+ : Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3, (float)renderer.Width / renderer.Height, Math.Max(radius / 10000, 0.01f), radius * 20);
+ projection.M22 *= -1;
+ if (animation != null)
+ {
+ animation.Sample(fixedTime ?? (headless ? count / 60.0 : now), mesh.Vertices.AsSpan(characterOffset), characterModel);
+ renderer.UpdateVertices(mesh.Vertices);
+ }
+ renderer.Render(view * projection);
+ count++;
+ audio?.Pump();
+ if (smoke && count == 1)
+ {
+ var key = new Sdl.Event { Type = Sdl.KeyDown, Scancode = 79, Down = 1 };
+ if (!Sdl.SDL_PushEvent(ref key) || !Sdl.SDL_SetWindowSize(window, 800, 600))
+ throw new InvalidOperationException(Sdl.Error);
+ }
+ if (smoke && renderer.Width == 800 && renderer.Height == 600) didResize = true;
+ if (frames > 0 && count >= frames) break;
+ }
+ if (Option(args, "--screenshot") is { } screenshot)
+ {
+ renderer.SavePpm(screenshot);
+ Console.WriteLine($"Saved Vulkan GPU readback: {screenshot}");
+ }
+ var pixels = renderer.ReadPixels();
+ var changed = 0;
+ for (var i = 0; i < pixels.Length; i += 4)
+ if (Math.Abs(pixels[i] - 31) + Math.Abs(pixels[i + 1] - 51) + Math.Abs(pixels[i + 2] - 76) > 6) changed++;
+ Console.WriteLine($"Rendered {count} frame(s), {changed} non-background pixels, {renderer.ValidationErrors} Vulkan validation error(s).");
+ if (smoke)
+ {
+ Console.WriteLine($"SDL3 injected keyboard event received: {sawKey}; swapchain resized to 800x600: {didResize}.");
+ if (!sawKey || !didResize) return 2;
+ }
+ return renderer.ValidationErrors > 0 || changed == 0 ? 2 : 0;
+ }
+ finally
+ {
+ if (window != 0) { Sdl.SDL_DestroyWindow(window); Sdl.SDL_Quit(); }
+ }
+ }
+
+ private static int VerifyAssets(string root)
+ {
+ var pngs = Directory.GetFiles(root, "*", SearchOption.AllDirectories)
+ .Where(p => p.EndsWith(".png", StringComparison.OrdinalIgnoreCase)).ToArray();
+ foreach (var path in pngs) PngImage.Load(path);
+ var models = Directory.GetFiles(AssetPath.Resolve(root, "ASE"), "*", SearchOption.AllDirectories)
+ .Where(p => p.EndsWith(".ase", StringComparison.OrdinalIgnoreCase)).ToArray();
+ foreach (var path in models) AseMesh.Load(path);
+ Console.WriteLine($"Verified runtime decoders: {pngs.Length} PNG textures and {models.Length} ASE base meshes.");
+ return 0;
+ }
+}
diff --git a/src/GamePort/Rendering/Shaders/mesh.frag b/src/GamePort/Rendering/Shaders/mesh.frag
new file mode 100644
index 0000000..41dc14e
--- /dev/null
+++ b/src/GamePort/Rendering/Shaders/mesh.frag
@@ -0,0 +1,10 @@
+#version 450
+layout(location=0) in vec2 texCoord;
+layout(location=1) in vec3 vertexColor;
+layout(binding=0) uniform sampler2D diffuseMap;
+layout(location=0) out vec4 outColor;
+void main() {
+ vec4 diffuse = texture(diffuseMap, texCoord);
+ if (diffuse.a < 0.5) discard;
+ outColor = vec4(diffuse.rgb * vertexColor, diffuse.a);
+}
diff --git a/src/GamePort/Rendering/Shaders/mesh.frag.spv b/src/GamePort/Rendering/Shaders/mesh.frag.spv
new file mode 100644
index 0000000..abb7064
Binary files /dev/null and b/src/GamePort/Rendering/Shaders/mesh.frag.spv differ
diff --git a/src/GamePort/Rendering/Shaders/mesh.vert b/src/GamePort/Rendering/Shaders/mesh.vert
new file mode 100644
index 0000000..75d5f2b
--- /dev/null
+++ b/src/GamePort/Rendering/Shaders/mesh.vert
@@ -0,0 +1,12 @@
+#version 450
+layout(location=0) in vec3 position;
+layout(location=1) in vec2 uv;
+layout(location=2) in vec3 color;
+layout(location=0) out vec2 texCoord;
+layout(location=1) out vec3 vertexColor;
+layout(push_constant) uniform Transform { mat4 mvp; } transform;
+void main() {
+ gl_Position = transform.mvp * vec4(position, 1.0);
+ texCoord = uv;
+ vertexColor = color;
+}
diff --git a/src/GamePort/Rendering/Shaders/mesh.vert.spv b/src/GamePort/Rendering/Shaders/mesh.vert.spv
new file mode 100644
index 0000000..a99c1ef
Binary files /dev/null and b/src/GamePort/Rendering/Shaders/mesh.vert.spv differ
diff --git a/src/GamePort/Rendering/Vulkan/VulkanRenderer.cs b/src/GamePort/Rendering/Vulkan/VulkanRenderer.cs
new file mode 100644
index 0000000..0024e35
--- /dev/null
+++ b/src/GamePort/Rendering/Vulkan/VulkanRenderer.cs
@@ -0,0 +1,431 @@
+using System.Numerics;
+using System.Runtime.InteropServices;
+using GamePort.Assets;
+using GamePort.Platform;
+using Silk.NET.Vulkan;
+using Silk.NET.Vulkan.Extensions.KHR;
+using Silk.NET.Vulkan.Extensions.EXT;
+using Buffer = Silk.NET.Vulkan.Buffer;
+using Image = Silk.NET.Vulkan.Image;
+using Semaphore = Silk.NET.Vulkan.Semaphore;
+
+namespace GamePort.Rendering.Vulkan;
+
+/// A deliberately small, synchronous renderer for recovering the original scenes.
+public sealed unsafe class VulkanRenderer : IDisposable
+{
+ private readonly Vk vk=Vk.GetApi();
+ private Instance instance;
+ private PhysicalDevice physical;
+ private Device device;
+ private Queue queue;
+ private uint queueFamily;
+ private CommandPool pool;
+ private CommandBuffer command;
+ private Buffer vertexBuffer,indexBuffer,readback;
+ private DeviceMemory vertexMemory,indexMemory,readbackMemory;
+ private Image color,depth;
+ private DeviceMemory colorMemory,depthMemory;
+ private ImageView colorView,depthView;
+ private RenderPass renderPass;
+ private Framebuffer framebuffer;
+ private Pipeline pipeline;
+ private PipelineLayout pipelineLayout;
+ private DescriptorSetLayout descriptorLayout;
+ private DescriptorPool descriptorPool;
+ private Sampler sampler;
+ private readonly List textures=[];
+ private readonly Dictionary descriptors=[];
+ private readonly Mesh mesh;
+ private readonly nint window;
+ private SurfaceKHR surface;
+ private KhrSurface? surfaceApi;
+ private KhrSwapchain? swapApi;
+ private SwapchainKHR swapchain;
+ private Image[] swapImages=[];
+ private ExtDebugUtils? debugApi;
+ private DebugUtilsMessengerEXT messenger;
+ private readonly DebugUtilsMessengerCallbackFunctionEXT debugCallback;
+ private Semaphore acquired,finished;
+ private uint width,height;
+ public string DeviceName { get; private set; }="";
+ public int ValidationErrors { get; private set; }
+ public uint Width=>width;
+ public uint Height=>height;
+
+ private sealed record Texture(Image Image,DeviceMemory Memory,ImageView View);
+ private static void Check(Result result,string operation)
+ {if(result!=Result.Success)throw new InvalidOperationException($"{operation}: {result}");}
+
+ public VulkanRenderer(Mesh mesh,PngImage texture,uint width=960,uint height=720,nint window=0,bool validation=true)
+ {
+ this.mesh=mesh;this.width=width;this.height=height;this.window=window;
+ debugCallback=OnValidation;
+ try
+ {
+ CreateInstance(validation);
+ if(window!=0)
+ {
+ if(!Sdl.SDL_Vulkan_CreateSurface(window,instance.Handle,null,out var handle))throw new InvalidOperationException(Sdl.Error);
+ surface=new SurfaceKHR(handle);
+ if(!vk.TryGetInstanceExtension(instance,out surfaceApi))throw new NotSupportedException("VK_KHR_surface unavailable.");
+ }
+ CreateDevice();
+ var poolInfo=new CommandPoolCreateInfo{SType=StructureType.CommandPoolCreateInfo,QueueFamilyIndex=queueFamily,Flags=CommandPoolCreateFlags.ResetCommandBufferBit};
+ Check(vk.CreateCommandPool(device,&poolInfo,null,out pool),"CreateCommandPool");
+ var allocation=new CommandBufferAllocateInfo{SType=StructureType.CommandBufferAllocateInfo,CommandPool=pool,Level=CommandBufferLevel.Primary,CommandBufferCount=1};
+ Check(vk.AllocateCommandBuffers(device,&allocation,out command),"AllocateCommandBuffers");
+ UploadBuffers();
+ CreateDescriptors(texture);
+ CreateRenderPass();
+ CreatePipeline();
+ if(window!=0)CreateSwapchain();
+ CreateTarget();
+ }
+ catch{Dispose();throw;}
+ }
+
+ private uint OnValidation(DebugUtilsMessageSeverityFlagsEXT severity,DebugUtilsMessageTypeFlagsEXT type,DebugUtilsMessengerCallbackDataEXT* data,void* user)
+ {
+ if((severity&DebugUtilsMessageSeverityFlagsEXT.ErrorBitExt)!=0)ValidationErrors++;
+ Console.Error.WriteLine($"Vulkan {severity}: {Marshal.PtrToStringUTF8((nint)data->PMessage)}");
+ return Vk.False;
+ }
+
+ private void CreateInstance(bool validation)
+ {
+ uint n=0;Check(vk.EnumerateInstanceLayerProperties(&n,null),"EnumerateInstanceLayers");
+ var layers=new LayerProperties[n];
+ fixed(LayerProperties* p=layers)Check(vk.EnumerateInstanceLayerProperties(&n,p),"EnumerateInstanceLayers");
+ bool hasLayer=false;
+ foreach(var layer in layers){var l=layer;if(Marshal.PtrToStringUTF8((nint)l.LayerName)=="VK_LAYER_KHRONOS_validation")hasLayer=true;}
+ var names=new List();
+ if(window!=0)
+ {
+ var extensions=Sdl.SDL_Vulkan_GetInstanceExtensions(out var count);
+ if(extensions==null)throw new InvalidOperationException(Sdl.Error);
+ for(var i=0;iMarshal.StringToCoTaskMemUTF8(s)).ToArray();
+ var layerName=Marshal.StringToCoTaskMemUTF8("VK_LAYER_KHRONOS_validation");
+ try
+ {
+ var app=new ApplicationInfo{SType=StructureType.ApplicationInfo,ApiVersion=Vk.Version13};
+ fixed(nint* p=native)
+ {
+ var info=new InstanceCreateInfo{SType=StructureType.InstanceCreateInfo,PApplicationInfo=&app,EnabledExtensionCount=(uint)native.Length,PpEnabledExtensionNames=(byte**)p,
+ EnabledLayerCount=validation?1u:0u,PpEnabledLayerNames=(byte**)&layerName};
+ Check(vk.CreateInstance(&info,null,out instance),"CreateInstance");
+ }
+ if(validation && vk.TryGetInstanceExtension(instance,out debugApi))
+ {
+ var debugInfo=new DebugUtilsMessengerCreateInfoEXT{SType=StructureType.DebugUtilsMessengerCreateInfoExt,
+ MessageSeverity=DebugUtilsMessageSeverityFlagsEXT.WarningBitExt|DebugUtilsMessageSeverityFlagsEXT.ErrorBitExt,
+ MessageType=DebugUtilsMessageTypeFlagsEXT.GeneralBitExt|DebugUtilsMessageTypeFlagsEXT.ValidationBitExt|DebugUtilsMessageTypeFlagsEXT.PerformanceBitExt,
+ PfnUserCallback=debugCallback};
+ Check(debugApi!.CreateDebugUtilsMessenger(instance,&debugInfo,null,out messenger),"CreateDebugMessenger");
+ }
+ }
+ finally{foreach(var p in native)Marshal.FreeCoTaskMem(p);Marshal.FreeCoTaskMem(layerName);}
+ }
+
+ private void CreateDevice()
+ {
+ foreach(var gpu in vk.GetPhysicalDevices(instance))
+ {
+ vk.GetPhysicalDeviceProperties(gpu,out var properties);
+ if(properties.ApiVersion vertices)
+ {
+ if(vertices.Length!=mesh.Vertices.Length)throw new ArgumentException("Vertex count must match the uploaded mesh.");
+ // Frames are completed synchronously; host coherent memory is safe to update here.
+ CopyToMemory(vertexMemory,MemoryMarshal.AsBytes(vertices));
+ }
+ private void CopyToMemory(DeviceMemory memory,ReadOnlySpan bytes)
+ {
+ void* data;Check(vk.MapMemory(device,memory,0,(ulong)bytes.Length,0,&data),"MapMemory");
+ bytes.CopyTo(new Span(data,bytes.Length));vk.UnmapMemory(device,memory);
+ }
+ private void MakeImage(uint w,uint h,Format format,ImageUsageFlags usage,ImageAspectFlags aspect,out Image image,out DeviceMemory memory,out ImageView view)
+ {
+ var info=new ImageCreateInfo{SType=StructureType.ImageCreateInfo,ImageType=ImageType.Type2D,Format=format,Extent=new Extent3D(w,h,1),MipLevels=1,ArrayLayers=1,Samples=SampleCountFlags.Count1Bit,Tiling=ImageTiling.Optimal,Usage=usage,SharingMode=SharingMode.Exclusive,InitialLayout=ImageLayout.Undefined};
+ Check(vk.CreateImage(device,&info,null,out image),"CreateImage");
+ vk.GetImageMemoryRequirements(device,image,out var req);
+ var alloc=new MemoryAllocateInfo{SType=StructureType.MemoryAllocateInfo,AllocationSize=req.Size,MemoryTypeIndex=MemoryType(req.MemoryTypeBits,MemoryPropertyFlags.DeviceLocalBit)};
+ Check(vk.AllocateMemory(device,&alloc,null,out memory),"AllocateImageMemory");Check(vk.BindImageMemory(device,image,memory,0),"BindImageMemory");
+ var vi=new ImageViewCreateInfo{SType=StructureType.ImageViewCreateInfo,Image=image,ViewType=ImageViewType.Type2D,Format=format,SubresourceRange=new ImageSubresourceRange(aspect,0,1,0,1)};
+ Check(vk.CreateImageView(device,&vi,null,out view),"CreateImageView");
+ }
+ private void Begin()
+ {
+ Check(vk.ResetCommandBuffer(command,0),"ResetCommandBuffer");
+ var info=new CommandBufferBeginInfo{SType=StructureType.CommandBufferBeginInfo,Flags=CommandBufferUsageFlags.OneTimeSubmitBit};
+ Check(vk.BeginCommandBuffer(command,&info),"BeginCommandBuffer");
+ }
+ private void Submit()
+ {
+ Check(vk.EndCommandBuffer(command),"EndCommandBuffer");var cmd=command;
+ var info=new SubmitInfo{SType=StructureType.SubmitInfo,CommandBufferCount=1,PCommandBuffers=&cmd};
+ Check(vk.QueueSubmit(queue,1,&info,default),"QueueSubmit");Check(vk.QueueWaitIdle(queue),"QueueWaitIdle");
+ }
+ private void Barrier(Image image,ImageLayout oldLayout,ImageLayout newLayout,AccessFlags source,AccessFlags destination,PipelineStageFlags srcStage,PipelineStageFlags dstStage)
+ {
+ var barrier=new ImageMemoryBarrier{SType=StructureType.ImageMemoryBarrier,OldLayout=oldLayout,NewLayout=newLayout,SrcAccessMask=source,DstAccessMask=destination,SrcQueueFamilyIndex=Vk.QueueFamilyIgnored,DstQueueFamilyIndex=Vk.QueueFamilyIgnored,Image=image,SubresourceRange=new ImageSubresourceRange(ImageAspectFlags.ColorBit,0,1,0,1)};
+ vk.CmdPipelineBarrier(command,srcStage,dstStage,0,0,null,0,null,1,&barrier);
+ }
+ private Texture UploadTexture(PngImage image)
+ {
+ MakeBuffer((ulong)image.Rgba.Length,BufferUsageFlags.TransferSrcBit,MemoryPropertyFlags.HostVisibleBit|MemoryPropertyFlags.HostCoherentBit,out var staging,out var memory);
+ CopyToMemory(memory,image.Rgba);
+ MakeImage(image.Width,image.Height,Format.R8G8B8A8Unorm,ImageUsageFlags.TransferDstBit|ImageUsageFlags.SampledBit,ImageAspectFlags.ColorBit,out var texture,out var textureMemory,out var view);
+ Begin();Barrier(texture,ImageLayout.Undefined,ImageLayout.TransferDstOptimal,0,AccessFlags.TransferWriteBit,PipelineStageFlags.TopOfPipeBit,PipelineStageFlags.TransferBit);
+ var copy=new BufferImageCopy{ImageSubresource=new ImageSubresourceLayers(ImageAspectFlags.ColorBit,0,0,1),ImageExtent=new Extent3D(image.Width,image.Height,1)};
+ vk.CmdCopyBufferToImage(command,staging,texture,ImageLayout.TransferDstOptimal,1,©);
+ Barrier(texture,ImageLayout.TransferDstOptimal,ImageLayout.ShaderReadOnlyOptimal,AccessFlags.TransferWriteBit,AccessFlags.ShaderReadBit,PipelineStageFlags.TransferBit,PipelineStageFlags.FragmentShaderBit);Submit();
+ vk.DestroyBuffer(device,staging,null);vk.FreeMemory(device,memory,null);
+ var result=new Texture(texture,textureMemory,view);textures.Add(result);return result;
+ }
+ private void CreateDescriptors(PngImage fallback)
+ {
+ var binding=new DescriptorSetLayoutBinding{Binding=0,DescriptorType=DescriptorType.CombinedImageSampler,DescriptorCount=1,StageFlags=ShaderStageFlags.FragmentBit};
+ var layout=new DescriptorSetLayoutCreateInfo{SType=StructureType.DescriptorSetLayoutCreateInfo,BindingCount=1,PBindings=&binding};
+ Check(vk.CreateDescriptorSetLayout(device,&layout,null,out descriptorLayout),"CreateDescriptorSetLayout");
+ var count=(uint)mesh.Textures.Count+1;
+ var size=new DescriptorPoolSize(DescriptorType.CombinedImageSampler,count);
+ var poolInfo=new DescriptorPoolCreateInfo{SType=StructureType.DescriptorPoolCreateInfo,MaxSets=count,PoolSizeCount=1,PPoolSizes=&size};
+ Check(vk.CreateDescriptorPool(device,&poolInfo,null,out descriptorPool),"CreateDescriptorPool");
+ var samplerInfo=new SamplerCreateInfo{SType=StructureType.SamplerCreateInfo,MagFilter=Filter.Linear,MinFilter=Filter.Linear,MipmapMode=SamplerMipmapMode.Nearest,AddressModeU=SamplerAddressMode.Repeat,AddressModeV=SamplerAddressMode.Repeat,AddressModeW=SamplerAddressMode.Repeat,MaxLod=0};
+ Check(vk.CreateSampler(device,&samplerInfo,null,out sampler),"CreateSampler");
+ var images=new Dictionary(mesh.Textures){[-1]=fallback};
+ foreach(var (id,image) in images)
+ {
+ var texture=UploadTexture(image);var descriptor=descriptorLayout;
+ var alloc=new DescriptorSetAllocateInfo{SType=StructureType.DescriptorSetAllocateInfo,DescriptorPool=descriptorPool,DescriptorSetCount=1,PSetLayouts=&descriptor};
+ Check(vk.AllocateDescriptorSets(device,&alloc,out var set),"AllocateDescriptorSets");
+ var imageInfo=new DescriptorImageInfo{Sampler=sampler,ImageView=texture.View,ImageLayout=ImageLayout.ShaderReadOnlyOptimal};
+ var write=new WriteDescriptorSet{SType=StructureType.WriteDescriptorSet,DstSet=set,DstBinding=0,DescriptorCount=1,DescriptorType=DescriptorType.CombinedImageSampler,PImageInfo=&imageInfo};
+ vk.UpdateDescriptorSets(device,1,&write,0,null);descriptors[id]=set;
+ }
+ }
+ private void CreateRenderPass()
+ {
+ var attachments=stackalloc AttachmentDescription[2];
+ attachments[0]=new AttachmentDescription{Format=Format.R8G8B8A8Unorm,Samples=SampleCountFlags.Count1Bit,LoadOp=AttachmentLoadOp.Clear,StoreOp=AttachmentStoreOp.Store,StencilLoadOp=AttachmentLoadOp.DontCare,StencilStoreOp=AttachmentStoreOp.DontCare,InitialLayout=ImageLayout.Undefined,FinalLayout=ImageLayout.TransferSrcOptimal};
+ attachments[1]=new AttachmentDescription{Format=Format.D32Sfloat,Samples=SampleCountFlags.Count1Bit,LoadOp=AttachmentLoadOp.Clear,StoreOp=AttachmentStoreOp.DontCare,StencilLoadOp=AttachmentLoadOp.DontCare,StencilStoreOp=AttachmentStoreOp.DontCare,InitialLayout=ImageLayout.Undefined,FinalLayout=ImageLayout.DepthStencilAttachmentOptimal};
+ var cr=new AttachmentReference(0,ImageLayout.ColorAttachmentOptimal);var dr=new AttachmentReference(1,ImageLayout.DepthStencilAttachmentOptimal);
+ var subpass=new SubpassDescription{PipelineBindPoint=PipelineBindPoint.Graphics,ColorAttachmentCount=1,PColorAttachments=&cr,PDepthStencilAttachment=&dr};
+ var dependencies=stackalloc SubpassDependency[2];
+ dependencies[0]=new SubpassDependency{SrcSubpass=Vk.SubpassExternal,DstSubpass=0,SrcStageMask=PipelineStageFlags.TopOfPipeBit,DstStageMask=PipelineStageFlags.ColorAttachmentOutputBit|PipelineStageFlags.EarlyFragmentTestsBit,DstAccessMask=AccessFlags.ColorAttachmentWriteBit|AccessFlags.DepthStencilAttachmentWriteBit};
+ dependencies[1]=new SubpassDependency{SrcSubpass=0,DstSubpass=Vk.SubpassExternal,SrcStageMask=PipelineStageFlags.ColorAttachmentOutputBit,DstStageMask=PipelineStageFlags.TransferBit,SrcAccessMask=AccessFlags.ColorAttachmentWriteBit,DstAccessMask=AccessFlags.TransferReadBit};
+ var info=new RenderPassCreateInfo{SType=StructureType.RenderPassCreateInfo,AttachmentCount=2,PAttachments=attachments,SubpassCount=1,PSubpasses=&subpass,DependencyCount=2,PDependencies=dependencies};
+ Check(vk.CreateRenderPass(device,&info,null,out renderPass),"CreateRenderPass");
+ }
+ private ShaderModule Shader(string name)
+ {
+ var bytes=File.ReadAllBytes(Path.Combine(AppContext.BaseDirectory,"Shaders",name));
+ fixed(byte* p=bytes){var info=new ShaderModuleCreateInfo{SType=StructureType.ShaderModuleCreateInfo,CodeSize=(nuint)bytes.Length,PCode=(uint*)p};Check(vk.CreateShaderModule(device,&info,null,out var shader),"CreateShaderModule");return shader;}
+ }
+ private void CreatePipeline()
+ {
+ var vertex=Shader("mesh.vert.spv");var fragment=Shader("mesh.frag.spv");var main=Marshal.StringToCoTaskMemUTF8("main");
+ try
+ {
+ var push=new PushConstantRange(ShaderStageFlags.VertexBit,0,64);var dl=descriptorLayout;
+ var layout=new PipelineLayoutCreateInfo{SType=StructureType.PipelineLayoutCreateInfo,SetLayoutCount=1,PSetLayouts=&dl,PushConstantRangeCount=1,PPushConstantRanges=&push};
+ Check(vk.CreatePipelineLayout(device,&layout,null,out pipelineLayout),"CreatePipelineLayout");
+ var stages=stackalloc PipelineShaderStageCreateInfo[2];
+ stages[0]=new PipelineShaderStageCreateInfo{SType=StructureType.PipelineShaderStageCreateInfo,Stage=ShaderStageFlags.VertexBit,Module=vertex,PName=(byte*)main};
+ stages[1]=new PipelineShaderStageCreateInfo{SType=StructureType.PipelineShaderStageCreateInfo,Stage=ShaderStageFlags.FragmentBit,Module=fragment,PName=(byte*)main};
+ var binding=new VertexInputBindingDescription(0,(uint)sizeof(MeshVertex),VertexInputRate.Vertex);
+ var attributes=stackalloc VertexInputAttributeDescription[3];
+ attributes[0]=new VertexInputAttributeDescription(0,0,Format.R32G32B32Sfloat,0);
+ attributes[1]=new VertexInputAttributeDescription(1,0,Format.R32G32Sfloat,12);
+ attributes[2]=new VertexInputAttributeDescription(2,0,Format.R32G32B32Sfloat,20);
+ var input=new PipelineVertexInputStateCreateInfo{SType=StructureType.PipelineVertexInputStateCreateInfo,VertexBindingDescriptionCount=1,PVertexBindingDescriptions=&binding,VertexAttributeDescriptionCount=3,PVertexAttributeDescriptions=attributes};
+ var assembly=new PipelineInputAssemblyStateCreateInfo{SType=StructureType.PipelineInputAssemblyStateCreateInfo,Topology=PrimitiveTopology.TriangleList};
+ var viewport=new PipelineViewportStateCreateInfo{SType=StructureType.PipelineViewportStateCreateInfo,ViewportCount=1,ScissorCount=1};
+ var raster=new PipelineRasterizationStateCreateInfo{SType=StructureType.PipelineRasterizationStateCreateInfo,PolygonMode=PolygonMode.Fill,CullMode=CullModeFlags.None,FrontFace=FrontFace.CounterClockwise,LineWidth=1};
+ var ms=new PipelineMultisampleStateCreateInfo{SType=StructureType.PipelineMultisampleStateCreateInfo,RasterizationSamples=SampleCountFlags.Count1Bit};
+ var ds=new PipelineDepthStencilStateCreateInfo{SType=StructureType.PipelineDepthStencilStateCreateInfo,DepthTestEnable=true,DepthWriteEnable=true,DepthCompareOp=CompareOp.LessOrEqual};
+ var blendAttachment=new PipelineColorBlendAttachmentState{ColorWriteMask=ColorComponentFlags.RBit|ColorComponentFlags.GBit|ColorComponentFlags.BBit|ColorComponentFlags.ABit};
+ var blend=new PipelineColorBlendStateCreateInfo{SType=StructureType.PipelineColorBlendStateCreateInfo,AttachmentCount=1,PAttachments=&blendAttachment};
+ var dynamicStates=stackalloc DynamicState[2]{DynamicState.Viewport,DynamicState.Scissor};
+ var dynamic=new PipelineDynamicStateCreateInfo{SType=StructureType.PipelineDynamicStateCreateInfo,DynamicStateCount=2,PDynamicStates=dynamicStates};
+ var info=new GraphicsPipelineCreateInfo{SType=StructureType.GraphicsPipelineCreateInfo,StageCount=2,PStages=stages,PVertexInputState=&input,PInputAssemblyState=&assembly,PViewportState=&viewport,PRasterizationState=&raster,PMultisampleState=&ms,PDepthStencilState=&ds,PColorBlendState=&blend,PDynamicState=&dynamic,Layout=pipelineLayout,RenderPass=renderPass,Subpass=0};
+ Check(vk.CreateGraphicsPipelines(device,default,1,&info,null,out pipeline),"CreateGraphicsPipeline");
+ }
+ finally{Marshal.FreeCoTaskMem(main);vk.DestroyShaderModule(device,vertex,null);vk.DestroyShaderModule(device,fragment,null);}
+ }
+ private void CreateTarget()
+ {
+ MakeImage(width,height,Format.R8G8B8A8Unorm,ImageUsageFlags.ColorAttachmentBit|ImageUsageFlags.TransferSrcBit,ImageAspectFlags.ColorBit,out color,out colorMemory,out colorView);
+ MakeImage(width,height,Format.D32Sfloat,ImageUsageFlags.DepthStencilAttachmentBit,ImageAspectFlags.DepthBit,out depth,out depthMemory,out depthView);
+ var views=stackalloc ImageView[2]{colorView,depthView};
+ var info=new FramebufferCreateInfo{SType=StructureType.FramebufferCreateInfo,RenderPass=renderPass,AttachmentCount=2,PAttachments=views,Width=width,Height=height,Layers=1};
+ Check(vk.CreateFramebuffer(device,&info,null,out framebuffer),"CreateFramebuffer");
+ MakeBuffer((ulong)width*height*4,BufferUsageFlags.TransferDstBit,MemoryPropertyFlags.HostVisibleBit|MemoryPropertyFlags.HostCoherentBit,out readback,out readbackMemory);
+ }
+ private void DestroyTarget()
+ {
+ vk.DestroyFramebuffer(device,framebuffer,null);vk.DestroyImageView(device,colorView,null);vk.DestroyImageView(device,depthView,null);
+ vk.DestroyImage(device,color,null);vk.DestroyImage(device,depth,null);vk.FreeMemory(device,colorMemory,null);vk.FreeMemory(device,depthMemory,null);
+ vk.DestroyBuffer(device,readback,null);vk.FreeMemory(device,readbackMemory,null);
+ }
+ private void CreateSwapchain()
+ {
+ Check(surfaceApi!.GetPhysicalDeviceSurfaceCapabilities(physical,surface,out var caps),"SurfaceCapabilities");
+ uint count=0;Check(surfaceApi.GetPhysicalDeviceSurfaceFormats(physical,surface,&count,null),"SurfaceFormats");
+ var formats=new SurfaceFormatKHR[count];fixed(SurfaceFormatKHR* p=formats)Check(surfaceApi.GetPhysicalDeviceSurfaceFormats(physical,surface,&count,p),"SurfaceFormats");
+ var format=formats.FirstOrDefault(f=>f.Format==Format.B8G8R8A8Unorm);if(format.Format==0)format=formats[0];
+ Sdl.SDL_GetWindowSizeInPixels(window,out var w,out var h);
+ width=caps.CurrentExtent.Width==uint.MaxValue?Math.Clamp((uint)Math.Max(1,w),caps.MinImageExtent.Width,caps.MaxImageExtent.Width):caps.CurrentExtent.Width;
+ height=caps.CurrentExtent.Height==uint.MaxValue?Math.Clamp((uint)Math.Max(1,h),caps.MinImageExtent.Height,caps.MaxImageExtent.Height):caps.CurrentExtent.Height;
+ if((caps.SupportedUsageFlags&ImageUsageFlags.TransferDstBit)==0)throw new NotSupportedException("Swapchain does not support transfer destinations.");
+ var imageCount=caps.MinImageCount+1;if(caps.MaxImageCount>0)imageCount=Math.Min(imageCount,caps.MaxImageCount);
+ var info=new SwapchainCreateInfoKHR{SType=StructureType.SwapchainCreateInfoKhr,Surface=surface,MinImageCount=imageCount,ImageFormat=format.Format,ImageColorSpace=format.ColorSpace,ImageExtent=new Extent2D(width,height),ImageArrayLayers=1,ImageUsage=ImageUsageFlags.TransferDstBit,ImageSharingMode=SharingMode.Exclusive,PreTransform=caps.CurrentTransform,CompositeAlpha=CompositeAlphaFlagsKHR.OpaqueBitKhr,PresentMode=PresentModeKHR.FifoKhr,Clipped=true};
+ Check(swapApi!.CreateSwapchain(device,&info,null,out swapchain),"CreateSwapchain");
+ count=0;Check(swapApi.GetSwapchainImages(device,swapchain,&count,null),"GetSwapchainImages");swapImages=new Image[count];
+ fixed(Image* p=swapImages)Check(swapApi.GetSwapchainImages(device,swapchain,&count,p),"GetSwapchainImages");
+ }
+ public void Resize()
+ {
+ if(window==0)return;
+ Sdl.SDL_GetWindowSizeInPixels(window,out var w,out var h);if(w<1||h<1)return;
+ Check(vk.DeviceWaitIdle(device),"ResizeWaitIdle");DestroyTarget();swapApi!.DestroySwapchain(device,swapchain,null);CreateSwapchain();CreateTarget();
+ }
+ public void Render(Matrix4x4 mvp)
+ {
+ uint imageIndex=0;
+ if(window!=0)
+ {
+ var result=swapApi!.AcquireNextImage(device,swapchain,ulong.MaxValue,acquired,default,&imageIndex);
+ if(result==Result.ErrorOutOfDateKhr){Resize();return;}
+ if(result!=Result.SuboptimalKhr)Check(result,"AcquireNextImage");
+ }
+ Begin();
+ var clear=stackalloc ClearValue[2];clear[0].Color=new ClearColorValue(0.12f,0.20f,0.30f,1);clear[1].DepthStencil=new ClearDepthStencilValue(1,0);
+ var begin=new RenderPassBeginInfo{SType=StructureType.RenderPassBeginInfo,RenderPass=renderPass,Framebuffer=framebuffer,RenderArea=new Rect2D(new Offset2D(0,0),new Extent2D(width,height)),ClearValueCount=2,PClearValues=clear};
+ vk.CmdBeginRenderPass(command,&begin,SubpassContents.Inline);vk.CmdBindPipeline(command,PipelineBindPoint.Graphics,pipeline);
+ var viewport=new Viewport(0,0,width,height,0,1);var scissor=new Rect2D(new Offset2D(0,0),new Extent2D(width,height));
+ vk.CmdSetViewport(command,0,1,&viewport);vk.CmdSetScissor(command,0,1,&scissor);
+ var vb=vertexBuffer;ulong offset=0;vk.CmdBindVertexBuffers(command,0,1,&vb,&offset);vk.CmdBindIndexBuffer(command,indexBuffer,0,IndexType.Uint32);
+ vk.CmdPushConstants(command,pipelineLayout,ShaderStageFlags.VertexBit,0,64,&mvp);
+ var draws=mesh.HasExplicitDraws?mesh.Draws:[new MeshDraw(0,(uint)mesh.Indices.Length,-1)];
+ foreach(var draw in draws)
+ {
+ var descriptor=descriptors.GetValueOrDefault(draw.TextureId,descriptors[-1]);
+ vk.CmdBindDescriptorSets(command,PipelineBindPoint.Graphics,pipelineLayout,0,1,&descriptor,0,null);
+ vk.CmdDrawIndexed(command,draw.IndexCount,1,draw.FirstIndex,0,0);
+ }
+ vk.CmdEndRenderPass(command);
+ if(window==0){Submit();return;}
+ var target=swapImages[imageIndex];Barrier(target,ImageLayout.Undefined,ImageLayout.TransferDstOptimal,0,AccessFlags.TransferWriteBit,PipelineStageFlags.TopOfPipeBit,PipelineStageFlags.TransferBit);
+ var blit=new ImageBlit{SrcSubresource=new ImageSubresourceLayers(ImageAspectFlags.ColorBit,0,0,1),DstSubresource=new ImageSubresourceLayers(ImageAspectFlags.ColorBit,0,0,1)};
+ blit.SrcOffsets[0]=new Offset3D(0,0,0);blit.SrcOffsets[1]=new Offset3D((int)width,(int)height,1);blit.DstOffsets[0]=new Offset3D(0,0,0);blit.DstOffsets[1]=new Offset3D((int)width,(int)height,1);
+ vk.CmdBlitImage(command,color,ImageLayout.TransferSrcOptimal,target,ImageLayout.TransferDstOptimal,1,&blit,Filter.Nearest);
+ Barrier(target,ImageLayout.TransferDstOptimal,ImageLayout.PresentSrcKhr,AccessFlags.TransferWriteBit,0,PipelineStageFlags.TransferBit,PipelineStageFlags.BottomOfPipeBit);
+ Check(vk.EndCommandBuffer(command),"EndCommandBuffer");var cmd=command;var wait=acquired;var signal=finished;var stage=PipelineStageFlags.TransferBit;
+ var submit=new SubmitInfo{SType=StructureType.SubmitInfo,WaitSemaphoreCount=1,PWaitSemaphores=&wait,PWaitDstStageMask=&stage,CommandBufferCount=1,PCommandBuffers=&cmd,SignalSemaphoreCount=1,PSignalSemaphores=&signal};
+ Check(vk.QueueSubmit(queue,1,&submit,default),"QueueSubmit");var swap=swapchain;
+ var present=new PresentInfoKHR{SType=StructureType.PresentInfoKhr,WaitSemaphoreCount=1,PWaitSemaphores=&signal,SwapchainCount=1,PSwapchains=&swap,PImageIndices=&imageIndex};
+ var presentation=swapApi!.QueuePresent(queue,&present);Check(vk.QueueWaitIdle(queue),"PresentWaitIdle");
+ if(presentation is Result.ErrorOutOfDateKhr or Result.SuboptimalKhr)Resize();else Check(presentation,"QueuePresent");
+ }
+ public byte[] ReadPixels()
+ {
+ Begin();var copy=new BufferImageCopy{ImageSubresource=new ImageSubresourceLayers(ImageAspectFlags.ColorBit,0,0,1),ImageExtent=new Extent3D(width,height,1)};
+ vk.CmdCopyImageToBuffer(command,color,ImageLayout.TransferSrcOptimal,readback,1,©);Submit();
+ var pixels=new byte[checked((int)(width*height*4))];void* data;
+ Check(vk.MapMemory(device,readbackMemory,0,(ulong)pixels.Length,0,&data),"ReadbackMap");new ReadOnlySpan(data,pixels.Length).CopyTo(pixels);vk.UnmapMemory(device,readbackMemory);return pixels;
+ }
+ public void SavePpm(string path)
+ {
+ var rgba=ReadPixels();Directory.CreateDirectory(Path.GetDirectoryName(Path.GetFullPath(path))!);
+ using var file=File.Create(path);file.Write(System.Text.Encoding.ASCII.GetBytes($"P6\n{width} {height}\n255\n"));
+ for(var i=0;i
+
+ Exe
+ net10.0
+ enable
+ enable
+ false
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/tests/GamePort.DataTests/Program.cs b/tests/GamePort.DataTests/Program.cs
new file mode 100644
index 0000000..2b8b00b
--- /dev/null
+++ b/tests/GamePort.DataTests/Program.cs
@@ -0,0 +1,91 @@
+using GamePort.Assets;
+using GamePort.Game;
+using System.Numerics;
+
+var root = args.Length == 1 ? Path.GetFullPath(args[0])
+ : Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../../../Original"));
+var files = Directory.GetFiles(Path.Combine(root, "gam"), "*.gam");
+Require(files.Length == 35, $"Expected all 35 original level files at {root}");
+var entities = 0;
+foreach (var file in files)
+{
+ var level = GamLevel.Load(file);
+ entities += level.Entities.Count;
+ Require(level.Player is not null, $"Missing player in {file}");
+ Require(level.FindStart() is not null, $"Missing matching player startpoint in {file}");
+}
+Require(entities == 3299, "Original entity total differs");
+var initial = GamLevel.Load(Path.Combine(root, "gam/level1b.gam"));
+Require(initial.Code == "LV1B" && initial.Entities.Count == 129, "Wrong initial scene");
+Require(initial.Player!.Position.X == 5071.93310546875f, "Original player X changed");
+Require(initial.FindStart()!.CameraPosition.Y == 235.64761352539062f, "Original camera Y changed");
+Require(initial.FindStart()!.Text("StartTrigger") == "LABEXP", "Initial trigger differs");
+Require(initial.FindStart()!.Text("MusicDatabase") == "musicsecretlab.omt", "Initial music differs");
+
+var sample = File.ReadAllBytes(Path.Combine(root, "gam/VR01.gam"));
+foreach (var length in new[] { 0, 3, 7, 8, 30, sample.Length - 1 })
+ Reject(sample[..length]);
+Reject([.. sample, 0]);
+var corruptCount = (byte[])sample.Clone();
+Array.Fill(corruptCount, (byte)0xff, 4, 4);
+Reject(corruptCount);
+var corruptString = (byte[])sample.Clone();
+corruptString[0x22] = 100; // first property's Pascal payload length
+Reject(corruptString);
+Console.WriteLine($"PASS: C# decoded {files.Length} original GAM files, {entities} entities; original startup and corruption checks passed.");
+
+var velocity = Vector3.Zero;
+var impulse = new Vector3(0, RecoveredMotion.JumpImpulse, 0);
+var displacement = RecoveredMotion.Integrate(ref velocity, ref impulse, Vector3.Zero, RecoveredMotion.Gravity, 0.125f);
+Require(velocity.Y == 450 && displacement.Y == 56.25f && impulse == Vector3.Zero,
+ "Recovered jump/gravity order or impulse consumption differs");
+displacement = RecoveredMotion.Integrate(ref velocity, ref impulse, Vector3.Zero, RecoveredMotion.Gravity, 0.125f);
+Require(velocity.Y == 350 && displacement.Y == 43.75f, "Impulse was incorrectly repeated");
+var speed = 0f;
+for (var i = 0; i < 30; i++) speed = RecoveredMotion.AddSpeed(speed);
+Require(speed == 600, "Original speed cap differs");
+for (var i = 0; i < 30; i++) speed = RecoveredMotion.ReleaseSpeed(speed);
+Require(speed == 0 && RecoveredMotion.ReleaseSpeed(-10) == 0, "Speed decay crossed zero");
+var rng = new OriginalRandom(uint.MaxValue);
+Require(rng.Next() == 65511 && rng.State == 4293335538u, "LCG uint32 overflow differs");
+Console.WriteLine("PASS: recovered impulse/gravity integration, speed limits and wrapping RNG regression checks.");
+
+var project = Path.GetFullPath(Path.Combine(root, "../GamePort"));
+var scene = Mesh.LoadSceneJson(Path.Combine(project, "artifacts/extracted/level1b/scene.json"));
+Require(scene.HasExplicitDraws && scene.Draws.Length > 0, "Missing original material draw ranges");
+Require(scene.Draws.Sum(d => (long)d.IndexCount) < scene.Indices.Length,
+ "Null-material collision proxy geometry was incorrectly rendered");
+var baseMesh = AseMesh.Load(AssetPath.Resolve(root, "ase/JIMSTOP.ASE"));
+Require(baseMesh.Indices.Length == 2442, "Original Jimmy topology differs");
+Require(baseMesh.Vertices.Any(v => v.Uv != Vector2.Zero), "Original base UVs missing");
+var animation = new MorphAnimation(Path.Combine(project, "artifacts/extracted/animations/jimrun/animation.json"));
+var a = new MeshVertex[animation.Base.Vertices.Length];
+var b = new MeshVertex[a.Length];
+var half = new MeshVertex[a.Length];
+animation.Sample(0, a, Matrix4x4.Identity);
+animation.Sample(animation.SampleInterval, b, Matrix4x4.Identity);
+animation.Sample(animation.SampleInterval / 2, half, Matrix4x4.Identity);
+Require(a.Where((v, i) => v.Position != b[i].Position).Any(), "Original animation samples do not change positions");
+for (var i = 0; i < a.Length; i++)
+{
+ Require(Vector3.Distance(half[i].Position, (a[i].Position + b[i].Position) / 2) < 0.0001f,
+ "Original morph interpolation differs");
+ Require(a[i].Uv == b[i].Uv && a[i].Uv == half[i].Uv, "Morph changed retained base UV");
+}
+var combined = animation.AppendTo(scene);
+Require(combined.Indices.Length == scene.Indices.Length + 2442 && combined.Textures.Count == 34,
+ "Original scene/character resource merge differs");
+Require(combined.Indices.All(i => i < combined.Vertices.Length), "Combined scene contains invalid index");
+Console.WriteLine("PASS: null-material visibility, case-insensitive ASE, original morph interpolation/base UV, and scene/character merge.");
+
+static void Require(bool condition, string message)
+{
+ if (!condition) throw new Exception(message);
+}
+
+static void Reject(byte[] data)
+{
+ try { GamLevel.Parse(data); }
+ catch (InvalidDataException) { return; }
+ throw new Exception("Malformed GAM was accepted");
+}
diff --git a/tools/recon/reference_capture.py b/tools/recon/reference_capture.py
new file mode 100644
index 0000000..4c20e51
--- /dev/null
+++ b/tools/recon/reference_capture.py
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Capture a COPIED original in a filesystem/network-isolated Wine environment.
+
+Requires project-local Wine and Xvfb plus bubblewrap and ImageMagick. Host mode
+does not execute Wine directly: only the game copy and generated prefix are
+writable inside the namespace, and the original directory is not mounted.
+"""
+import argparse
+import ctypes
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import time
+
+
+def enter_key():
+ x = ctypes.CDLL('libX11.so.6')
+ x.XOpenDisplay.argtypes = [ctypes.c_char_p]
+ x.XOpenDisplay.restype = ctypes.c_void_p
+ x.XKeysymToKeycode.argtypes = [ctypes.c_void_p, ctypes.c_ulong]
+ x.XKeysymToKeycode.restype = ctypes.c_uint
+ x.XFlush.argtypes = [ctypes.c_void_p]
+ x.XCloseDisplay.argtypes = [ctypes.c_void_p]
+ display = x.XOpenDisplay(None)
+ if not display:
+ return False
+ test = ctypes.CDLL('libXtst.so.6')
+ test.XTestFakeKeyEvent.argtypes = [ctypes.c_void_p, ctypes.c_uint, ctypes.c_int, ctypes.c_ulong]
+ key = x.XKeysymToKeycode(display, 0xff0d)
+ test.XTestFakeKeyEvent(display, key, 1, 0)
+ test.XTestFakeKeyEvent(display, key, 0, 0)
+ x.XFlush(display)
+ x.XCloseDisplay(display)
+ return True
+
+
+def inside(args):
+ work = Path('/work')
+ with (work/'xvfb.log').open('w') as xlog, (work/'wine.log').open('w') as wlog:
+ display = subprocess.Popen(['/native/usr/bin/Xvfb', ':89', '-screen', '0', '1024x768x24', '-nolisten', 'tcp'], stdout=xlog, stderr=xlog)
+ wine = None
+ try:
+ for _ in range(30):
+ if Path('/tmp/.X11-unix/X89').exists(): break
+ if display.poll() is not None: raise RuntimeError('Xvfb failed; see xvfb.log')
+ time.sleep(0.1)
+ wine_env = dict(os.environ, LIBGL_DRIVERS_PATH='/native/usr/lib/i386-linux-gnu/dri')
+ wine = subprocess.Popen(['/opt/wine-stable/bin/wine', args.game], cwd='/work/game', stdout=wlog, stderr=wlog, env=wine_env)
+ captures = []
+ for index in range(3):
+ time.sleep(args.seconds / 3)
+ target = f'/work/frame-{index:02d}.png'
+ image = subprocess.run(['import', '-display', ':89', '-window', 'root', target], timeout=10, capture_output=True)
+ captures.append({'file': target, 'captureExit': image.returncode, 'wineExit': wine.poll()})
+ if args.enter:
+ captures[-1]['sentReturn'] = enter_key()
+ tree = subprocess.run(['xwininfo', '-root', '-tree'], capture_output=True, text=True)
+ (work/'windows.txt').write_text(tree.stdout + tree.stderr)
+ processes = []
+ for path in Path('/proc').glob('[0-9]*/cmdline'):
+ try: processes.append(path.parent.name + ': ' + path.read_bytes().replace(b'\x00', b' ').decode('utf8', 'replace'))
+ except OSError: pass
+ (work/'processes.txt').write_text('\n'.join(processes)+'\n')
+ (work/'capture.json').write_text(json.dumps({'game': args.game, 'captures': captures}, indent=2)+'\n')
+ finally:
+ subprocess.run(['/opt/wine-stable/bin/wineserver', '-k'], timeout=10, check=False)
+ if wine and wine.poll() is None: wine.terminate()
+ display.terminate()
+ display.wait(timeout=5)
+
+
+def main():
+ p = argparse.ArgumentParser(description=__doc__)
+ p.add_argument('--inside', action='store_true', help=argparse.SUPPRESS)
+ p.add_argument('--game', choices=['Neutron.exe','NeutronNoCD.exe','NeutronSW.exe','NeutronHD.exe','NeutronHDnoCD.exe'], default='NeutronNoCD.exe')
+ p.add_argument('--seconds', type=int, default=24)
+ p.add_argument('--enter', action='store_true', help='Send Return after each screenshot')
+ p.add_argument('--debug', action='store_true', help='Record Wine process and exception diagnostics')
+ p.add_argument('--wine-renderer', choices=['gl','vulkan'], default='gl')
+ p.add_argument('--output', type=Path)
+ args = p.parse_args()
+ if not 3 <= args.seconds <= 120: p.error('--seconds must be 3..120')
+ if args.inside: return inside(args)
+ project = Path(__file__).resolve().parents[2]
+ source = project.parent/'Original'
+ work = (args.output or project/'artifacts/reference').resolve()
+ if work.is_relative_to(source.resolve()) or source.resolve().is_relative_to(work):
+ p.error('Output must be separate from originals')
+ work.mkdir(parents=True, exist_ok=True)
+ if not (work/'game').exists(): shutil.copytree(source, work/'game')
+ (work/'home').mkdir(exist_ok=True)
+ (work/'home/.asoundrc').write_text('pcm.!default { type null }\nctl.!default { type hw card 0 }\n')
+ (work/'alsa-null.conf').write_text('pcm.default { type null }\npcm.null { type null }\n')
+ cmd = ['bwrap', '--unshare-all', '--new-session', '--die-with-parent', '--clearenv',
+ '--ro-bind', '/usr', '/usr', '--ro-bind', '/lib', '/lib', '--ro-bind', '/lib64', '/lib64',
+ '--symlink', 'usr/bin', '/bin', '--symlink', 'usr/sbin', '/sbin',
+ '--ro-bind', '/etc', '/etc', '--ro-bind', '/sys', '/sys', '--proc', '/proc', '--dev', '/dev',
+ '--tmpfs', '/tmp', '--dir', '/tmp/.X11-unix', '--tmpfs', '/var', '--dir', '/var/tmp',
+ '--dir', '/run', '--dir', '/home', '--bind', str(work), '/work',
+ '--ro-bind', str(project/'.tools/wine/opt/wine-stable'), '/opt/wine-stable',
+ '--ro-bind', str(project/'.tools/native'), '/native',
+ '--ro-bind', str(Path(__file__).resolve()), '/capture.py']
+ for key,value in {'HOME':'/work/home', 'WINEPREFIX':'/work/prefix', 'WINEARCH':'win32',
+ 'DISPLAY':':89', 'PATH':'/opt/wine-stable/bin:/usr/bin:/bin', 'LANG':'C.UTF-8',
+ 'WINEDEBUG':'-all,err+all,warn+ddraw,warn+d3d,+seh' if args.debug else '-all',
+ 'ALSA_CONFIG_PATH':'/work/alsa-null.conf', 'WINEDLLOVERRIDES':'mscoree,mshtml=',
+ 'WINE_D3D_CONFIG':'renderer='+args.wine_renderer,
+ 'LD_LIBRARY_PATH':'/native/usr/lib/x86_64-linux-gnu:/native/usr/lib/i386-linux-gnu',
+ 'LIBGL_ALWAYS_SOFTWARE':'1', '__GLX_VENDOR_LIBRARY_NAME':'mesa',
+ '__EGL_VENDOR_LIBRARY_FILENAMES':'/usr/share/glvnd/egl_vendor.d/50_mesa.json'}.items():
+ cmd += ['--setenv', key, value]
+ if args.wine_renderer == 'vulkan':
+ cmd += ['--setenv', 'VK_DRIVER_FILES', '/native/usr/share/vulkan/icd.d/lvp_icd.json']
+ cmd += ['/usr/bin/python3', '/capture.py', '--inside', '--game', args.game, '--seconds', str(args.seconds)]
+ if args.enter: cmd += ['--enter']
+ print('Running copied original with no network and no original-directory mount:', work, flush=True)
+ subprocess.run(cmd, check=True, timeout=args.seconds + 40)
+ print('Capture metadata:', work/'capture.json')
+
+
+if __name__ == '__main__': main()