From f2f3a805cdb3936c970714f400264141c51dd4dc Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Thu, 12 Nov 2026 11:06:58 -0500 Subject: [PATCH] docs: map existing codebase --- .planning/codebase/ARCHITECTURE.md | 199 +++++++++++++++++++++++++++++ .planning/codebase/CONCERNS.md | 143 +++++++++++++++++++++ .planning/codebase/CONVENTIONS.md | 121 ++++++++++++++++++ .planning/codebase/INTEGRATIONS.md | 92 +++++++++++++ .planning/codebase/STACK.md | 91 +++++++++++++ .planning/codebase/STRUCTURE.md | 195 ++++++++++++++++++++++++++++ .planning/codebase/TESTING.md | 171 +++++++++++++++++++++++++ 7 files changed, 1012 insertions(+) create mode 100644 .planning/codebase/ARCHITECTURE.md create mode 100644 .planning/codebase/CONCERNS.md create mode 100644 .planning/codebase/CONVENTIONS.md create mode 100644 .planning/codebase/INTEGRATIONS.md create mode 100644 .planning/codebase/STACK.md create mode 100644 .planning/codebase/STRUCTURE.md create mode 100644 .planning/codebase/TESTING.md diff --git a/.planning/codebase/ARCHITECTURE.md b/.planning/codebase/ARCHITECTURE.md new file mode 100644 index 0000000..4869aca --- /dev/null +++ b/.planning/codebase/ARCHITECTURE.md @@ -0,0 +1,199 @@ +--- +last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 +last_mapped_at: 2026-11-12 +--- + +# Architecture + +**Analysis Date:** 2026-11-12 + +## System Overview + +```text +Read-only ../Original assets + -> tools/extractors/prepare.py -> artifacts/extracted manifests/buffers/WAV + -> src/GamePort/Assets + original GAM/TSK/ASE/PNG readers + -> Program.Run scene composition + Game simulation/scripts -> Application visuals/HUD -> VulkanRenderer + Game events -> SceneAudio -> SdlAudio -> SDL3 +Program.Main -> persistent RenderSession -> SDL window + Vulkan instance/device +``` + +The desktop application is a single shared Linux/Windows C# executable (`GamePort.csproj`). `src/GamePort/Program.cs` composes concrete systems and owns scheduling. There is no runtime server, database, dependency-injection container, or external game engine. + +## Component Responsibilities + +| Component | Responsibility | File | +|-----------|----------------|------| +| Application entry | CLI, resource composition, input dispatch, fixed ticks, scene continuation | `src/GamePort/Program.cs` | +| Presentation session | Application lifetime window and renderer; replace scene resources | `src/GamePort/Application/RenderSession.cs` | +| Player simulation | Physics, input/apply order, facing, jump/effects, player camera | `src/GamePort/Game/LabSimulation.cs` | +| Script bridge | Raw control owner, authored transforms, gadget cleanup, vehicle/passenger phases | `src/GamePort/Game/PlayerSceneBinding.cs` | +| Scene director | GAM actors, CAM/MCA/AI chains, cutscene camera, control and issue reporting | `src/GamePort/Game/SceneDirector.cs` | +| Progression | Contacts, inventory, tasks, transitions and save snapshots | `src/GamePort/Game/SceneInteractions.cs`, `src/GamePort/Game/TaskStates.cs` | +| Resource readers | Original and prepared data decoding | `src/GamePort/Assets/` | +| Presentation adapters | Mutable geometry, morphs, sprites, UI and camera projection | `src/GamePort/Application/` | +| GPU backend | Vulkan resources, rendering, resizing, readback and disposal | `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs` | +| Audio | Independent music/speech/effects and SDL WAV stream ownership | `src/GamePort/Audio/SceneAudio.cs`, `src/GamePort/Audio/SdlAudio.cs` | + +## Pattern Overview + +**Overall:** Explicit application composition with scene-local state, event-connected gameplay systems and a persistent native presentation owner. + +**Key Characteristics:** +- Keep scheduling visible in `src/GamePort/Program.cs`; source ordering is behavior, not interchangeable service invocation order. +- Keep recovered arithmetic in focused `src/GamePort/Game/` modules and presentation in `src/GamePort/Application/`. +- Preserve the distinction between isolated recovered components and admitted live scene adapters (`src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`). +- Use local original-derived assets; Python preparation is a development/package stage (`tools/extractors/prepare.py`, `scripts/package.sh`). + +## Layers + +**Application composition and presentation:** +- Purpose: Connect input, simulation, scripts, visuals, audio and GPU submission. +- Location: `src/GamePort/Program.cs`, `src/GamePort/Application/`. +- Contains: `RenderSession`, debug interfaces, `SceneHud`, visual adapters and smoke fixtures. +- Depends on: Game, Assets, Audio, Platform and Rendering namespaces. +- Used by: Executable entry and managed regression projects. + +**Game state and recovered algorithms:** +- Purpose: Own simulation and script/progression semantics. +- Location: `src/GamePort/Game/`. +- Contains: `LabSimulation`, `SceneDirector`, inventory/tasks, gadgets, vehicles, collision and numeric kernels. +- Depends on: `System.Numerics` and decoded asset types in `src/GamePort/Assets/`. +- Used by: Application orchestration and focused `tests/GamePort.*Tests/` executables. + +**Asset decoding:** +- Purpose: Convert bounded original/prepared files into typed CPU resources. +- Location: `src/GamePort/Assets/`. +- Contains: `GamLevel`, `OriginalSave`, `Mesh`, `MorphAnimation`, `PngImage`, resource identities and path resolution. +- Depends on: Filesystem, binary primitives, JSON and numerics; no renderer ownership. +- Used by: Game systems and application/renderer initialization. + +**Native platform, GPU and audio:** +- Purpose: Own unmanaged interoperability and device resources. +- Location: `src/GamePort/Platform/Sdl.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`, `src/GamePort/Audio/`. +- Contains: SDL3 imports, Vulkan offscreen/present paths, WAV streams and scene audio orchestration. +- Depends on: SDL3, Silk.NET.Vulkan, shaders and decoded meshes/textures. +- Used by: `src/GamePort/Application/RenderSession.cs` and `src/GamePort/Program.cs`. + +**Offline evidence and preparation:** +- Purpose: Inspect source evidence and create reusable resources without modifying originals. +- Location: `tools/binary/`, `tools/extractors/`, `tools/levels/`, `tools/recon/`. +- Contains: Python parsers, extraction manifests, C component probes and observation tools. +- Depends on: Local original files and explicit analysis tooling; not part of the native runtime dependency graph. +- Used by: Tests, local preparation, research and `scripts/package.sh`. + +## Data Flow + +### Primary Request Path + +1. `Program.Main` creates persistent presentation, energy, grappler memory and diagnostics, then invokes the scene runner (`src/GamePort/Program.cs:14`). +2. `Run` resolves originals, loads prepared geometry and original GAM/save data, constructs scene systems and binds the player (`src/GamePort/Program.cs:46`). +3. SDL polling updates held input; unpaused gameplay advances through a 60 Hz accumulator, while bounded fixtures use explicit steps (`src/GamePort/Program.cs:1057`, `src/GamePort/Game/FixedStepClock.cs`). +4. Each tick advances gadget/projectile bodies, player/vehicle binding, timers/targets, interactions/mechanisms, patrols, director and animation state (`src/GamePort/Program.cs:1271`). +5. Application visuals mutate mesh vertices/draw properties, update HUD and select gameplay/script/orbit camera; renderer uploads and renders (`src/GamePort/Program.cs:1371`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). + +### Player and cutscene phase ordering + +1. `LabSimulation.Step` runs body physics before registry-style callbacks (`src/GamePort/Game/LabSimulation.cs:265`). +2. Fresh direct-scene input runs before ceiling/floor/facing and player apply. Retained input runs after player/effect updates. `Program` sets `InputAfterPlayerUpdate` for story entry or carried saves (`src/GamePort/Program.cs:361`). +3. Lack of Jimmy control gates input/player apply, not body, facing or owned effect clocks. `PlayerSceneBinding` receives director preparation/transform events and preserves vehicle control ordering (`src/GamePort/Game/PlayerSceneBinding.cs`). +4. Script preparation separates stop-motion, orientation flattening, gadget release and authored transforms; do not replace these with a generic player reset (`src/GamePort/Game/PlayerSceneBinding.cs`, `src/GamePort/Game/SceneDirector.cs`). + +### Scene loading and retained state + +1. Contact or practice logic requests a `LevelTransition`; application stages a departure/RETURN root through `RuntimeCheckpoint` (`src/GamePort/Program.cs:339`, `src/GamePort/Game/RuntimeCheckpoint.cs`). +2. Scene runner returns a continuation with destination arguments, original-format save snapshot and optional bounded `PlayerLevelState` (`src/GamePort/Program.cs`, `src/GamePort/Game/PlayerLevelState.cs`). +3. `Main` invokes a new scene run. GAM actors, bindings, visual resources and scene audio are rebuilt; `RenderSession.LoadScene` calls `ReplaceScene` on the existing renderer (`src/GamePort/Application/RenderSession.cs`). +4. Vulkan scene replacement waits for device idle and replaces scene GPU resources while retaining presentation identity (`src/GamePort/Rendering/Vulkan/VulkanRenderer.cs:101`). + +### Source-to-extracted-assets pipeline + +1. `tools/recon/inventory.py` provides original manifest verification against `docs/original-manifest.json`. +2. `tools/extractors/prepare.py` reads OMT/GAM/ASE/PNG and dispatches scene, entity, model, UI, effect and gadget resource extraction. `tools/extractors/omt.py` and `tools/levels/gam.py` retain format-specific parsing. +3. Generated `artifacts/extracted/` contains scene JSON, textures, animation buffers/manifests, entity/model resources, WAV and a scene catalog. Missing scene archives are reported rather than substituted (`tools/extractors/prepare.py`). +4. Runtime readers load prepared resources and original GAM/TSK/base assets; `scripts/package.sh` copies those into local package `scenes/` and `assets/` trees. Runtime packages do not need Python. + +**State Management:** +- Application session: presentation, diagnostics preference, `PlayerEnergy` and `GrapplerMemory` are created outside the scene loop (`src/GamePort/Program.cs`). +- Scene: simulation, actors, tasks/inventory, mechanisms, animation meshes, audio and bindings are concrete objects recreated by `Run` (`src/GamePort/Program.cs`). +- Retained route scalars: `PlayerLevelState` supports LV1B/VR04/LEV1 with selected gadget -1 or 3; this is in-memory state, not an extension of TSK (`src/GamePort/Game/PlayerLevelState.cs`). +- Original save persistence: `OriginalSave` encodes TSK tasks/items/checkpoint state; save output uses a temporary file and move outside original assets (`src/GamePort/Assets/OriginalSave.cs`, `src/GamePort/Program.cs`). + +## Key Abstractions + +**Mesh and MeshDraw:** +- Purpose: CPU geometry, source collision polygons, textures and per-range material/presentation state. +- Examples: `src/GamePort/Assets/Mesh.cs`, `src/GamePort/Application/SceneActorVisuals.cs`. +- Pattern: Arrays plus mutable draw state; visual adapters append/update shared scene data rather than owning Vulkan objects. + +**GamEntity and DirectorActor:** +- Purpose: Preserve serialized properties separately from live authored actor state. +- Examples: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/SceneDirector.cs`. +- Pattern: Bounded typed decoding followed by scene-specific actor/script execution; unknown behavior produces issues. + +**Original collision components and live adapters:** +- Purpose: Express bounded source contracts without assuming a complete recovered physical registry. +- Examples: `src/GamePort/Game/OriginalBodyPhysics.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`. +- Pattern: Caller-owned state/accessors and explicit profiles. Pair callbacks and generic normal responses do not establish scene membership or Jimmy's override policy. + +## Entry Points + +**Native executable:** +- Location: `src/GamePort/Program.cs`. +- Triggers: `dotnet run`, local published executable or package launchers. +- Responsibilities: Scene/model preview, playable story, asset verification, audio/GPU/SDL fixtures and explicit CLI validation. + +**Offline preparation:** +- Location: `tools/extractors/prepare.py`. +- Triggers: Local developer invocation and `scripts/package.sh`. +- Responsibilities: Original-derived resource production outside the source installation. + +**Regression and build entry points:** +- Location: `scripts/test.sh`, `scripts/build-linux.sh`, `scripts/build-windows.sh`, `tests/GamePort.*Tests/Program.cs`, `tests/test_*.py`. +- Triggers: Local scripts or direct test projects. +- Responsibilities: Bounded source/algorithm/parser checks, GPU fixtures and native packaging inputs. A cross-publish is not native Windows runtime evidence. + +## Architectural Constraints + +- **Threading:** Gameplay and rendering are explicitly scheduled on the application loop; Vulkan submission/presentation waits synchronously (`src/GamePort/Program.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). SDL manages audio stream transport (`src/GamePort/Audio/SdlAudio.cs`). +- **Global state:** Native SDL state is process-level; managed session state is explicitly passed. Keep native resource disposal scoped through `RenderSession` and `SdlAudio` (`src/GamePort/Application/RenderSession.cs`, `src/GamePort/Audio/SdlAudio.cs`). +- **Circular imports:** No project-layer circular project-reference chain is detected: production source is compiled into one executable (`GamePort.csproj`). Events intentionally connect director/player/inventory lifetimes (`src/GamePort/Game/PlayerSceneBinding.cs`). +- **Live solver boundaries:** Lab/outside retain capsule compatibility. Original static body is admitted by explicit scene gates including VR01/VR02/VR04/VR07/VR08; VR04 is a bounded source-body scene, not a full dynamic registry (`src/GamePort/Program.cs:361`, `src/GamePort/Game/LabSimulation.cs`). +- **Recovery gates:** `OriginalPairCollision` and `OriginalNormalContacts` are isolated components, not live admission. Physical activation/helper lifetime, actual derived callbacks and shared reclip remain separate obligations (`src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`, `docs/checkpoint/next-work-plan.md`). +- **Movement priority:** Preserve Jimmy movement and caller-dependent retained cutscene state before gameplay expansion (`AGENTS.md`, `docs/gameplay/jimmy-movement-stabilization.md`). +- **References:** `../Original/` is immutable authoritative evidence; sibling JN-Engine research is a source lead, not a runtime service or replacement movement implementation (`AGENTS.md`, `docs/reviews/jn-engine-survey.md`). + +## Anti-Patterns + +### Treating component recovery as live scene coverage + +**What happens:** Bounded pair/contact components coexist with separately gated runtime solvers (`src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Program.cs`). +**Why it's wrong:** Substituting them solely because component tests pass loses physical registration, activation and real derived callback policies. +**Do this instead:** Preserve explicit scene admission in `src/GamePort/Program.cs` and require the dependencies recorded in `docs/checkpoint/next-work-plan.md` before wiring new actors. + +### Collapsing input, control and body phases + +**What happens:** `LabSimulation` exposes both fresh and retained callback orders, while scripts independently gate raw control (`src/GamePort/Game/LabSimulation.cs`, `src/GamePort/Game/PlayerSceneBinding.cs`). +**Why it's wrong:** A generic reset or input-first rewrite changes neutral cutscene return, facing and effect behavior. +**Do this instead:** Preserve named preparation events, retained scalar state and `InputAfterPlayerUpdate`; extend focused lifecycle regressions (`tests/GamePort.BodyOwnershipTests/Program.cs`, `tests/GamePort.DirectorTests/Program.cs`). + +## Error Handling + +**Strategy:** Reject invalid data and native failures explicitly; report unrecovered script behavior without inventing execution (`src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/SceneDirector.cs`). + +**Patterns:** +- Top-level exception handling prints to stderr and returns 1; validation/fixture failures return 2 (`src/GamePort/Program.cs`). +- Bounded readers throw `InvalidDataException`; missing resources use explicit missing/ambiguous errors (`src/GamePort/Assets/AssetPath.cs`, `src/GamePort/Assets/PreparedEntityResources.cs`). +- SDL/Vulkan failure checks throw with native operation context; cleanup uses `IDisposable`/`finally` (`src/GamePort/Application/RenderSession.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). +- Director bounded dispatch records unsupported behavior and blocks problematic chains (`src/GamePort/Game/SceneDirector.cs`). + +## Cross-Cutting Concerns + +**Logging:** Console diagnostics, unrecovered behavior lists and live debug overlays (`src/GamePort/Program.cs`, `src/GamePort/Application/DebugDiagnostics.cs`). +**Validation:** Explicit endian parsing, finite/count/size checks, resource identity validation and Vulkan validation/error counts (`src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/PreparedEntityResources.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). +**Authentication:** Not applicable; local desktop runtime with no online identity service (`GamePort.csproj`, `src/GamePort/Program.cs`). + +--- + +*Architecture analysis: 2026-11-12* diff --git a/.planning/codebase/CONCERNS.md b/.planning/codebase/CONCERNS.md new file mode 100644 index 0000000..93efba9 --- /dev/null +++ b/.planning/codebase/CONCERNS.md @@ -0,0 +1,143 @@ +--- +last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 +last_mapped_at: 2026-11-12 +--- +# Codebase Concerns + +**Analysis Date:** 2026-11-12 + +Scope: tracked GamePort source and documented findings. Source HEAD is `bdca29d`; integrated SDL/GPU evidence belongs to `bf876e9`, while distributed local packages identify `924ad2f`. These are distinct validation targets, as recorded in `docs/progress.md` and `docs/compatibility.md`. This mapping performs no new builds, tests, binary execution or runtime comparison. + +## Tech Debt + +**Standalone collision contracts await supported live admission:** +- Issue: `OriginalPairCollision` requires caller-owned physical order and real callbacks; `OriginalNormalContacts` implements inherited response without providing Jimmy's override or scene admission. Dynamic/static composition remains test-only. +- Files: `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/DynamicSceneCollision.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/actor-normal-contacts.md`. +- Impact: passing component snapshots cannot establish general NPC interaction, live dynamic collision or game/task side effects. Replacing existing collision directly would skip unresolved owners. +- Fix approach: recover soldier complete174 and helper membership/order first; then bind a bounded response adapter to explicitly supported actor states. Preserve late inhibition, radius, geometry and42C reads. Do not cache pre-callback fields or apply inherited reflection to Jimmy ordinary374. + +**Physical registration and retained helper lifecycle are incomplete:** +- Issue:72 serialized VR04 records/13 interfaces and21 helper edges establish source construction/registration contracts, not a full active body list. Common append permits duplicate pointers, Jimmy49E guards its whole bridge, and per-object Init/PostLoad visits newly appended tails. +- Files: `docs/checkpoint/physical-registration.md`, `docs/checkpoint/vr04-generated-bodies.md`, `docs/checkpoint/dynamic-context.md`, `tools/binary/physical_registration.py`, `tools/binary/helper_teardown.py`. +- Impact: constructor-only helpers, Jeep child cleanup, activation and LOAD/RETURN reuse can change physical order and contact effects. Counting serialized records or deduplicating registration would misrepresent the original. +- Fix approach: trace actual helper removal/re-entry/activation and cleanup mutations across fresh load, retained load and RETURN. Compare complete ordered registry snapshots before enabling additional physical members. + +**Compatibility adapters remain explicit movement boundaries:** +- Issue: the lab/outside capsule, floor-derived visual sole correction and fixed60Hz scheduling are port policies. Bounded source-body integration does not cover every special material or dynamic actor path. +- Files: `src/GamePort/Game/LabSimulation.cs`, `src/GamePort/Game/SceneCollision.cs`, `src/GamePort/Game/FixedStepClock.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`, `docs/gameplay/jimmy-movement-stabilization.md`, `docs/checkpoint/body-contact-implementation.md`. +- Impact: existing navigation/playability and recovered scalar motion are not full original-body or scheduler parity. +- Fix approach: retain the current Jimmy baseline while recovering successful hazard/FENCE/LADDER paths, support ownership, actor mode/facing and real callback publication. Use original evidence to replace one named adapter at a time; JN-Engine replacement movement is not authoritative. + +**Partial camera/audio/UI/save ownership:** +- Issue: the coverage ledger identifies separate scripted/chase eyes, merged clip policy, independent file-based audio streams, a subset of objective/UI dispatch and a fresh-director save-load path that differs from original repeated task/entity callbacks. +- Files: `docs/checkpoint/coverage.md`, `src/GamePort/Application/OrbitCamera.cs`, `src/GamePort/Audio/SceneAudio.cs`, `src/GamePort/Game/ObjectivePanel.cs`, `src/GamePort/Game/SceneDirector.cs`, `src/GamePort/Assets/OriginalSave.cs`. +- Impact: recovered route behavior does not establish arbitrary save/load, full camera handoff, audio bank/clock lifecycle or all UI flags. +- Fix approach: follow the ownership/probe gates in `docs/checkpoint/next-work-plan.md`; recover dispatcher transitions and repeated callbacks before expanding UI, progression or gadget behavior. + +## Known Bugs + +**No newly reproduced runtime bug in this source-only mapping:** +- Symptoms: current docs retain earlier failure narratives alongside resolved checkpoint entries. The post-Carl neutral-bank failure has a supported TSK startup ordering correction and documented first-input/300-idle regression results; it must not be listed as an unfixed current bug. +- Files: `docs/progress.md`, `docs/tasks.md`, `docs/compatibility.md`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/checkpoint/coverage.md`. +- Trigger: the corrected path is successful TSK story entry, whose retained background Jimmy precedes new level input; direct fresh-GAM ordering is a separate case. +- Workaround: preserve the correction and fresh/retained distinction. Ordinary landing residual bank is user-confirmed original behavior; do not add a universal leveling/reset workaround. Whole-original Carl comparison remains unverified. + +## Security Considerations + +**Preservation and generated-probe isolation:** +- Risk: extraction or instrumentation directed into originals could destroy authoritative evidence; incorrect relocation operands can invalidate a copied-code experiment. +- Files: `AGENTS.md`, `tools/binary/actor_contact.py`, `tools/recon/inventory.py`, `docs/original-manifest.json`, `docs/checkpoint/actor-normal-contacts.md`. +- Current mitigation: the actor-contact generator rejects overlapping original/output directories and generated symlinks; reviewed operands, complete source/probe identities and completion markers guard capture acceptance. The documented cross-instruction relocation failure affects an invalid private probe, not original behavior. +- Recommendations: retain operand-specific regression guards and hash verification; keep invalid partial captures excluded. Never execute or patch original files in place. + +**Local asset parsing and path boundary:** +- Risk: malformed local assets require bounded decoding, and portable case lookup must reject ambiguous names rather than silently load another file. +- Files: `src/GamePort/Assets/AssetPath.cs`, `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/PngImage.cs`, `tests/GamePort.DataTests/Program.cs`, `tests/test_extractors.py`. +- Current mitigation: paths reject dot/parent components and require one case-insensitive match; GAM validates counts, remaining spans, finite scalars and duplicate properties; image parsing enforces supported formats and size limits. +- Recommendations: preserve these checks when adding formats and test malformed/truncated inputs. This source review identifies no reproduced exploit and makes no claim that these checks constitute a general filesystem sandbox. + +## Performance Bottlenecks + +**No measured bottleneck established by this mapping:** +- Problem: pair enumeration and source cell/FIFO traversal have scaling costs, but there is no new timing measurement here. +- Files: `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Application/DebugDiagnostics.cs`. +- Cause: `Step` enumerates an upper triangular body list, giving quadratic candidate growth; static traversal deliberately retains cell duplicates and retries. This is source complexity evidence, not a measured live slowdown; the pair component is not live. +- Improvement path: measure candidate counts, NodeVisits, TriangleTests and frame timings on supported scenes before optimizing. Preserve asymmetric exclusions, duplicate visits, tie order and callback timing; do not introduce an order-changing broadphase without equivalence evidence. + +## Fragile Areas + +**Callback-mutated context and late getters:** +- Files: `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/dynamic-reclip.md`, `docs/checkpoint/actor-normal-contacts.md`. +- Why fragile: callbacks can alter inhibition/radius/geometry/force state before reclip; retained last polygon can issue another callback; final local-root publication can overwrite callback root edits. Getter timing is observable behavior. +- Safe modification: retain accessor order, independent state channels, XYZ/full-Vec4 setter distinctions and explicit context ownership. Test full snapshots/event order rather than final root alone. +- Test coverage:30 normal-contact fixtures include synthetic mutations. They do not execute real soldier174/Jimmy204 policy or establish reentrant linked-list mutation. + +**Source arithmetic and finite-domain boundaries:** +- Files: `src/GamePort/Game/OriginalSphereResponse.cs`, `src/GamePort/Game/OriginalHeading.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `docs/checkpoint/dynamic-reclip.md`. +- Why fragile: float-store boundaries, source triangle winding, heading wrap and strict comparisons affect complete state even where final positions agree. Double intermediates are not a universal x87 emulator. +- Safe modification: require original instruction/store evidence and exact fixture comparisons for arithmetic changes. Keep unsupported zero-horizontal normalization explicit instead of silently inventing a policy. +- Test coverage: populated reclip has14 complete observations/12 kernel steps; inherited normal response has30 bounded snapshots. Degenerate inputs, arbitrary normals and broad x87 equivalence are not certified. + +**Story entry and ordinary landing:** +- Files: `src/GamePort/Program.cs`, `src/GamePort/Game/LabSimulation.cs`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/gameplay/jimmy-landing-rotation-source.md`. +- Why fragile: TSK-backed retained order and fresh direct-scene order differ; a generic neutral-angle reset would erase legitimate landing bank while masking scheduler errors. +- Safe modification: preserve first-story retained player-before-input classification and baseline movement algorithms. Recheck first resumed neutral frame, sustained idle, held input, Left/Right bank, natural completion/skip and repeated scenes after lifecycle changes. +- Test coverage: eight managed trajectories and integrated Linux evidence are documented; original full Carl runtime and current native Windows comparison remain separate gaps. + +## Scaling Limits + +**Bounded solver contracts:** +- Current capacity: `OriginalStaticCollision.Move` permits256 retries and throws beyond its verified finite-motion domain; `OriginalPairCollision.Step` requires a stable input list during the pass. +- Files: `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Game/OriginalPairCollision.cs`. +- Limit: source recursive retry behavior and callback-driven linked-list insertion/deletion are not fully represented by these bounded APIs. The256 guard is an implementation boundary, not measured original capacity. +- Scaling path: recover problematic repeated-contact cases and list-mutation semantics before widening the contract; preserve explicit failure rather than return an invented final position. + +**Scene admission is deliberately restricted:** +- Current capacity: static route construction admits LV1B, VR01, VR02, VR04, VR05, VR07, VR08 and LEV1; this is not a claim of complete gameplay in those eight scenes. Prepared resources cover33 available scenes according to the project ledger. +- Files: `src/GamePort/Game/OriginalStaticCollision.cs`, `docs/tasks.md`, `docs/checkpoint/coverage.md`. +- Limit: asset availability and class binding do not establish live physics, AI or progression coverage in other scenes. +- Scaling path: recover scene-specific consumers and ownership before broadening admission; keep unsupported scenes on their documented compatibility path. + +## Dependencies at Risk + +**No package-specific obsolescence or migration risk established:** +- Risk: this mapping provides no evidence that .NET10, SDL3 or Silk.NET.Vulkan requires replacement. The material dependency is runtime/platform validation, not a speculative package migration. +- Files: `GamePort.csproj`, `scripts/build-windows.sh`, `scripts/package.sh`, `docs/compatibility.md`. +- Impact: a successful Windows cross-publish and resource match do not establish current native Windows execution, audible behavior or driver compatibility. +- Migration plan: not applicable. Run the same route/control/window/audio scenarios on native Windows and record exact source/package identity before claiming platform equivalence. + +## Missing Critical Features + +**Real derived actor response and game/task contact consumers:** +- Problem: soldier409590 mode10 calls complete174→4098C0, whose RNG/target/action policy is not executed by the bounded fixture; Jimmy204 is likewise a record-only endpoint. Enter/stay/leave gameplay consumers remain separate from normal response. +- Files: `docs/checkpoint/actor-normal-contacts.md`, `tools/binary/actor_contact.py`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/tasks.md`. +- Blocks: general dynamic actor admission and faithful enemy/contact behavior. Recover complete caller/callee state and RNG progression before wiring supported adapters. + +**Full reconstruction beyond bounded playable routes:** +- Problem: animation playback/completion/interrupt timing, shared camera/input ownership, full audio bank lifecycle, arbitrary retained LOAD/save and broader progression remain open in the coverage ledger. New gadget expansion is paused behind movement/core-system gates. +- Files: `docs/checkpoint/coverage.md`, `docs/checkpoint/next-work-plan.md`, `docs/tasks.md`, `docs/gameplay/jimmy-movement-stabilization.md`. +- Blocks: full-game completion and blanket fidelity claims. Prioritize the interacting lab→VR04→lab→outside route and remove specific documented assumptions with original evidence. + +## Test Coverage Gaps + +**Whole-original gameplay comparison and native Windows:** +- What's not tested: current source as a complete original-game Carl sequence and native Windows equivalent of the integrated Linux route. Black-frame original Wine startup/allocation observations do not supply visual gameplay comparison; earlier Wine64 port evidence belongs to `ea04210`. +- Files: `docs/compatibility.md`, `docs/gameplay/original-startup-diagnostic.md`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/reference-testing.md`. +- Risk: component correctness and Linux replay success can coexist with differences in original timing, visuals, audio and Windows behavior. +- Priority: High. Capture a working copied-original banked-entry/skip/neutral-return interval and native Windows route evidence, identifying exact binaries and limitations. + +**Real helper lifecycle and reentrant collision integration:** +- What's not tested: full fresh/retained active physical lists, helper cleanup/re-entry during LOAD/RETURN, real soldier RNG response, actual contact-driven task mutations and callback list mutation during a pair pass. +- Files: `tests/GamePort.PairLifecycleTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/physical-registration.md`, `docs/checkpoint/vr04-generated-bodies.md`, `docs/checkpoint/actor-normal-contacts.md`. +- Risk: synthetic endpoint and stable-list tests can pass while real admission produces incorrect order or side effects. +- Priority: High. Add original-supported complete ordered-state fixtures, then bounded integration regressions before enabling actors. + +**Source/package evidence divergence:** +- What's not tested: latest standalone normal-contact source changes as a new SDL/GPU/native Windows package checkpoint. Current source `bdca29d`, integrated runtime `bf876e9` and packaged `924ad2f` must remain separately identified. +- Files: `docs/progress.md`, `docs/compatibility.md`, `scripts/package.sh`. +- Risk: citing earlier package readbacks as verification of later source overstates coverage. +- Priority: Medium. At the next authorized integration checkpoint, validate the complete intended source, rebuild clean packages and record identities, resource hashes and platform-specific execution receipts. + +--- + +*Concerns audit: 2026-11-12* diff --git a/.planning/codebase/CONVENTIONS.md b/.planning/codebase/CONVENTIONS.md new file mode 100644 index 0000000..4e5b569 --- /dev/null +++ b/.planning/codebase/CONVENTIONS.md @@ -0,0 +1,121 @@ +--- +last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 +last_mapped_at: 2026-11-12 +--- +# Coding Conventions + +**Analysis Date:** 2026-11-12 + +## Naming Patterns + +**Files:** +- Use PascalCase C# filenames matching the principal type: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`. +- Use snake_case Python modules and `test_*.py` regressions: `tools/extractors/sound_bank.py`, `tests/test_actor_contact.py`. +- Keep shell entry points under `scripts/`, using descriptive hyphenated names such as `scripts/test-window-transitions.sh`. + +**Functions:** +- Use PascalCase C# methods (`ReadVelocity`, `GenericWall`) as in `src/GamePort/Game/OriginalNormalContacts.cs`. +- Use snake_case Python functions (`export_sound_bank`, `validate_output`) as in `tools/extractors/sound_bank.py` and `tools/extractors/omt.py`. +- Name Python test methods `test_`; `tests/test_extractors.py` names invalid-input cases explicitly. + +**Variables:** +- Use camelCase C# parameters and locals, with explicit role names such as `headingUnits`, `oldHeading`, `carriedPlayer` in `src/GamePort/Game/OriginalNormalContacts.cs` and `src/GamePort/Program.cs`. +- Private C# fields do not uniformly use underscore prefixes; match the surrounding module (`src/GamePort/Assets/GamLevel.cs`). +- Python locals use snake_case; module constants use uppercase (`ROOT`, `ORIGINAL`, `CALLBACK_OPERANDS` in `tests/test_actor_contact.py`). + +**Types:** +- Use PascalCase C# classes/records and `I`-prefixed interfaces, exemplified by `OriginalNormalContacts` and `IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`. +- Python uses PascalCase classes and frozen dataclasses for resource identity (`Reader`, `Entry`, `FormatError` in `tools/extractors/omt.py`). + +## Code Style + +**Formatting:** +- No tracked formatter or `.editorconfig` is detected in the mapped repository. Follow each file's existing style rather than assuming an enforced formatter (`GamePort.csproj`, `src/GamePort/Assets/GamLevel.cs`). +- C# generally uses four spaces, file-scoped namespaces and braces on separate lines; short guards and expression-bodied helpers are common. Some numerical modules and console tests use compact spacing (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`). +- Python uses four spaces, type annotations where useful, and compact reader helpers; quotation style varies (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`). + +**Linting:** +- Dedicated C#/Python lint configurations are Not detected. `GamePort.csproj` enables nullable references, implicit usings and unsafe blocks; it does not declare warnings-as-errors or a separate analyzer package. +- Preserve explicit compile globs and shader copy rules in `GamePort.csproj`; test projects can compile production source directly, as in `tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`. + +## Import Organization + +**Order:** +1. C# explicit `System` namespaces precede project namespaces in `src/GamePort/Program.cs` and `tests/GamePort.ActorContactTests/Program.cs`. +2. Group runtime dependencies by namespace; implicit usings supply common base namespaces (`GamePort.csproj`). +3. Python standard library imports precede local tool imports. Tests insert the relevant tools directory into `sys.path` (`tests/test_extractors.py`, `tests/test_actor_contact.py`). + +**Path Aliases:** +- No frontend-style aliases are applicable. Use `GamePort.Assets`, `GamePort.Game` and related C# namespaces; Python tool imports resolve from explicit local paths (`src/GamePort/Program.cs`, `tests/test_actor_contact.py`). + +## Error Handling + +**Patterns:** +- Fail malformed assets with contextual format exceptions, including offsets. Do not silently truncate or accept trailing bytes (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`). +- Reject unsupported recovered behavior explicitly with `NotSupportedException`; validate nonfinite values separately with argument exceptions (`src/GamePort/Game/OriginalNormalContacts.cs`). +- Keep entry-point failure reporting centralized: `src/GamePort/Program.cs` catches exceptions, writes to stderr and returns status 1. +- Resolve original asset names case-insensitively after direct lookup, reject `.`/`..`, and reject missing/ambiguous matches (`src/GamePort/Assets/AssetPath.cs`). +- Reject extraction output overlapping originals; preserve source hashes and archive identities in generated metadata (`tools/extractors/sound_bank.py`). + +Representative bounded C# reader from `src/GamePort/Assets/GamLevel.cs`: + +```csharp +public ReadOnlySpan Take(int length) +{ + if (length < 0 || length > Remaining) + throw new InvalidDataException($"Truncated GAM at {Offset:x}"); + var result = data.Slice(Offset, length); + Offset += length; + return result; +} +public uint U32() => BinaryPrimitives.ReadUInt32BigEndian(Take(4)); +``` + +## Logging + +**Framework:** Console output, with explicit application diagnostics; no hosted logging service is detected (`src/GamePort/Program.cs`, `src/GamePort/Application/DebugDiagnostics.cs`). + +**Patterns:** +- Report fatal errors to `Console.Error`; expose inspection/smoke commands and readback paths through CLI options (`src/GamePort/Program.cs`). +- Tests print descriptive `PASS` messages and throw on failure (`tests/GamePort.ActorContactTests/Program.cs`). +- Persist verification scope and limitations in `docs/progress.md`, `docs/compatibility.md` and subsystem reports; console success alone does not establish whole-game equivalence. + +## Comments + +**When to Comment:** +- Explain original addresses, ownership, sampled field order and excluded behavior rather than restating arithmetic (`src/GamePort/Game/OriginalNormalContacts.cs`). +- Preserve concrete resource semantics: effect IDs are archive identities, and encoded audio preservation is separate from decoder support (`tools/extractors/sound_bank.py`). +- Keep recovered contracts distinct from approximations and runtime admission; `AGENTS.md` and `docs/checkpoint/actor-normal-contacts.md` make these evidence boundaries explicit. + +**XML documentation / Python docstrings:** +- Use C# `/// ` for bounded public contracts and interfaces (`src/GamePort/Game/OriginalNormalContacts.cs`). +- Use Python module/class docstrings for recovery purpose and failure semantics (`tools/extractors/omt.py`). JSDoc/TSDoc is Not applicable. + +## Function Design + +**Size:** +- Prefer focused components such as the ceiling/reflection helpers in `src/GamePort/Game/OriginalNormalContacts.cs`; no numerical line-count rule is detected. `src/GamePort/Program.cs` remains a substantial orchestration entry point. + +**Parameters:** +- Use explicit vectors, typed state and named flags rather than hidden scene state in recovered algorithms (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`). +- Inject actor-owned accessors through interfaces where read order matters; do not cache values across callbacks without evidence (`IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`). +- Keep bounded readers over spans/bytes and explicitly choose endianness (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`). + +**Return Values:** +- Return parsed records, typed state, or explicit metadata; throw for malformed/unsupported input (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/sound_bank.py`). +- Preserve float-store boundaries and intentional double intermediates in recovered math. Do not simplify formulas or clamp source values without evidence (`src/GamePort/Game/OriginalNormalContacts.cs`, `docs/checkpoint/dynamic-reclip.md`). + +## Module Design + +**Exports:** +- Keep asset decoding in `src/GamePort/Assets/`, recovered algorithms in `src/GamePort/Game/`, SDL interop in `src/GamePort/Platform/Sdl.cs`, and presentation in `src/GamePort/Application/`. +- Python tools expose importable parser/export functions as well as CLI-oriented modules (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`). +- Use `using`/disposal and explicit native ownership at runtime boundaries (`src/GamePort/Program.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`); follow the project requirement in `AGENTS.md`. + +**Barrel Files:** +- Not detected / Not applicable. C# namespaces and project compile includes provide organization (`GamePort.csproj`). +- Project-local agent skill constraints: the configured agent-skill query is empty; the applicable project constraints are in `AGENTS.md`. + +--- + +*Convention analysis: 2026-11-12* diff --git a/.planning/codebase/INTEGRATIONS.md b/.planning/codebase/INTEGRATIONS.md new file mode 100644 index 0000000..b5fa14d --- /dev/null +++ b/.planning/codebase/INTEGRATIONS.md @@ -0,0 +1,92 @@ +--- +last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 +last_mapped_at: 2026-11-12 +--- +# External Integrations + +**Analysis Date:** 2026-11-12 + +## APIs & External Services + +**Game runtime:** +- No hosted runtime service is required; offline operation and no telemetry are requirements in `AGENTS.md`. Runtime entry/configuration and resource loading reside in `src/GamePort/Program.cs`. +- Vulkan is a local native graphics API, accessed through Silk.NET.Vulkan/KHR/EXT `2.23.0` (`GamePort.csproj`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). Authentication: not applicable. +- SDL3 is a local native window/input/audio API, accessed through project P/Invoke (`src/GamePort/Platform/Sdl.cs`, `src/GamePort/Audio/SdlAudio.cs`). Authentication: not applicable. + +**Dependency acquisition (development only):** +- Microsoft SDK archives, SDL release archives and optional Ubuntu packages are downloaded by `scripts/bootstrap.sh`; the SDK and SDL archive hashes are pinned there. +- NuGet resolves managed packages through `dotnet restore` in `scripts/bootstrap.sh`, with direct versions in `GamePort.csproj` and resolved dependencies in `packages.lock.json`. +- These download sources are build-time inputs, not runtime asset storage or telemetry destinations (`scripts/bootstrap.sh`, `AGENTS.md`). + +**Local reverse-engineering tools:** +- `scripts/rea.sh` launches local REA with Ghidra/full JDK prerequisites. `tools/binary/rea_decompile_batch.py` communicates using local stdio JSON-RPC and saves complete replies/Evidence separately from originals. +- Use generated target copies; the batch wrapper rejects original-directory targets and output (`tools/binary/rea_decompile_batch.py`). This is developer analysis infrastructure, not game networking. + +## Data Storage + +**Databases:** +- No database server, ORM or connection-string configuration is detected in the runtime/project manifest; assets and game data are read through local readers (`GamePort.csproj`, `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/OriginalSave.cs`). + +**File Storage:** +- Local filesystem only: source assets are selected by `--assets` or discovery of `Original`/`original`/`assets` directories; use case-insensitive bounded path resolution in `src/GamePort/Assets/AssetPath.cs`. +- Local prepared scene/animation/entity JSON, binary mesh/texture data and WAV files are emitted by `tools/extractors/prepare.py`; its default output is `artifacts/extracted`. +- `scripts/package.sh` copies required original assets and prepared resources into local package `assets/`, `scenes/` and `audio/` directories. Original files remain separate and byte-identical (`AGENTS.md`). +- Original-format TSK checkpoint reads/writes are exposed through `--load-save` and `--write-save`; output is kept outside assets, with temporary-file replacement in `src/GamePort/Program.cs` and encoding in `src/GamePort/Assets/OriginalSave.cs`. +- Debug checkpoint defaults to `debug-checkpoint.tsk` beside the executable; the debug smoke path is separate in `src/GamePort/Program.cs`. These are checkpoint/progression snapshots, not arbitrary full live-game saves (`README.md`). + +**Caching:** +- Local generated SDK/dependency/prepared-resource caches only: `scripts/env.sh` configures `.nuget/packages` and local SDK paths; `tools/extractors/prepare.py` manages prepared output. +- No distributed cache or hosted asset cache is declared in `GamePort.csproj` or `scripts/package.sh`. + +## Authentication & Identity + +**Auth Provider:** +- None for the game runtime; no account/login integration is configured in `src/GamePort/Program.cs` or `GamePort.csproj`. +- Gitea source-control authentication is outside runtime configuration. `AGENTS.md` authorizes pushing completed, verified source commits to existing `Gitea`, with `main` tracking `Gitea/main`; do not embed credentials in documentation. + +## Monitoring & Observability + +**Error Tracking:** +- No external error-tracking service is declared in `GamePort.csproj`. Top-level exceptions print to stderr and exit unsuccessfully in `src/GamePort/Program.cs`. +- Optional local Khronos validation output uses `VK_LAYER_KHRONOS_validation` and EXT debug utils; errors increment a renderer counter and messages print to stderr in `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`. + +**Logs:** +- Console runtime/resource/audio/smoke diagnostics in `src/GamePort/Program.cs` and `src/GamePort/Audio/SdlAudio.cs`. +- In-process live diagnostics/debug overlay in `src/GamePort/Application/DebugDiagnostics.cs` and `src/GamePort/Application/DebugMenuOverlay.cs`; GPU readback screenshots are local outputs exposed by `src/GamePort/Program.cs`. +- Analysis evidence is written locally by `tools/binary/rea_decompile_batch.py`; current validation scope and provenance are recorded in `docs/compatibility.md` and `docs/progress.md`. + +## CI/CD & Deployment + +**Hosting:** +- Native local executables, not a hosted application: `scripts/build-linux.sh` and `scripts/build-windows.sh` publish self-contained platform binaries; `scripts/package.sh` assembles local packages and launchers. +- Native SDL is bundled; the host supplies a Vulkan 1.3 graphics loader/driver (`GamePort.csproj`, `scripts/package.sh`). +- Existing Gitea remote is for verified source commits only; original assets and generated packages must not be uploaded (`AGENTS.md`). Workspace `../.git` is reserved; project Git operations belong to `GamePort/` (`../AGENTS.md`). + +**CI Pipeline:** +- Local scripts only: `scripts/test.sh`, `scripts/test-window-transitions.sh`, `scripts/build-linux.sh`, `scripts/build-windows.sh`, `scripts/package.sh`. +- No cloud CI is desired or authorized (`AGENTS.md`, `../prompt.MD`). This absence is intentional. +- Cross-publish success does not establish native Windows runtime behavior; retain the scope distinctions in `docs/compatibility.md`. + +## Environment Configuration + +**Required env vars:** +- No runtime service keys or credentials required (`AGENTS.md`, `src/GamePort/Program.cs`). +- Development shell setup exports `DOTNET_CLI_HOME`, `DOTNET_CLI_TELEMETRY_OPTOUT`, `DOTNET_SKIP_FIRST_TIME_EXPERIENCE` and `NUGET_PACKAGES`; conditionally sets `DOTNET_ROOT`, `PATH`, `LD_LIBRARY_PATH`, `VK_LAYER_PATH` (`scripts/env.sh`). +- Test audio can use `SDL_AUDIODRIVER=dummy` (`scripts/test.sh`). +- Local analysis launcher uses `GHIDRA_INSTALL_DIR`, `JAVA_HOME`, `NEUTRON_REA_JAVA_HOME`, `NEUTRON_REA_NODE` and `NEUTRON_REA_LAUNCHER` (`scripts/rea.sh`). These are developer tool selectors, not game configuration. + +**Secrets location:** +- No runtime secret store is required (`AGENTS.md`). Source-control credentials remain external to runtime and this map. +- `scripts/rea.sh` optionally sources ignored `.tools/rea.env`; only the launcher reference is inspected, not the environment file contents. + +## Webhooks & Callbacks + +**Incoming:** +- No HTTP webhook endpoints are declared in `GamePort.csproj` or `src/GamePort/Program.cs`. SDL events and Vulkan validation callbacks are local API callbacks (`src/GamePort/Platform/Sdl.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). + +**Outgoing:** +- No runtime webhooks are declared in `src/GamePort/Program.cs` or `GamePort.csproj`. Development dependency downloads and source pushes are separate workflows (`scripts/bootstrap.sh`, `AGENTS.md`). + +--- + +*Integration audit: 2026-11-12* diff --git a/.planning/codebase/STACK.md b/.planning/codebase/STACK.md new file mode 100644 index 0000000..664d7ba --- /dev/null +++ b/.planning/codebase/STACK.md @@ -0,0 +1,91 @@ +--- +last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 +last_mapped_at: 2026-11-12 +--- +# Technology Stack + +**Analysis Date:** 2026-11-12 + +## Languages + +**Primary:** +- C# targeting `net10.0` for the shared executable and managed regression programs; no explicit `LangVersion` override is declared in `GamePort.csproj` or `tests/GamePort.DataTests/GamePort.DataTests.csproj`. + +**Secondary:** +- Python 3 for local asset preparation, binary evidence tooling and unittest regressions in `tools/` and `tests/`; `docs/dependencies.md` records Python 3.12. These tools are not runtime requirements. +- Bash for local dependency setup, builds, tests and packaging in `scripts/`. +- GLSL vertex/fragment shaders compiled to SPIR-V in `src/GamePort/Rendering/Shaders/mesh.vert` and `src/GamePort/Rendering/Shaders/mesh.frag`. +- C for isolated original-component probes such as `tools/binary/actor_contact_probe.c`; do not treat probe code as the game runtime. + +## Runtime + +**Environment:** +- .NET 10 executable, with invariant globalization, nullable analysis, implicit usings and unsafe interop enabled in `GamePort.csproj`. +- SDK selection: `global.json` requests `10.0.100`, permits `latestFeature` roll-forward and disables prerelease SDKs. `scripts/bootstrap.sh` downloads SDK `10.0.402` with a pinned SHA-256. +- `docs/dependencies.md` records self-contained runtime pack `10.0.13`; verify generated publish metadata when establishing package provenance rather than equating SDK and runtime versions. +- Native Vulkan 1.3 minimum: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs` requests `Vk.Version13` and filters physical devices below it. + +**Package Manager:** +- NuGet through the .NET SDK (`dotnet restore` in `scripts/bootstrap.sh`); no separately pinned NuGet client version. +- Lockfile present: `packages.lock.json`; `GamePort.csproj` enables `RestorePackagesWithLockFile`. +- Use `scripts/env.sh` to select the project-local SDK and `.nuget/packages` cache and disable .NET CLI telemetry. + +## Frameworks + +**Core:** +- Silk.NET.Vulkan, Silk.NET.Vulkan.Extensions.KHR and Silk.NET.Vulkan.Extensions.EXT `2.23.0` provide Vulkan bindings and extensions in `GamePort.csproj`. +- SDL3 `3.4.2` is provisioned by `scripts/bootstrap.sh`; window/input/Vulkan-surface and audio bindings are handwritten P/Invoke in `src/GamePort/Platform/Sdl.cs`. +- Game logic, binary formats, asset readers and UI are project C# modules under `src/GamePort/`; no general game engine is declared in `GamePort.csproj`. + +**Testing:** +- Python standard-library `unittest`, invoked by `scripts/test.sh` against `tests/test_*.py` and the HUD checks. +- Standalone .NET 10 executable test projects, rather than a declared xUnit/NUnit dependency; `tests/GamePort.DataTests/GamePort.DataTests.csproj` links production source directly. +- `scripts/test.sh` also runs real Vulkan rendering checks and SDL dummy-audio checks; read `docs/compatibility.md` for recorded platform scope. + +**Build/Dev:** +- MSBuild/.NET CLI solution and executable configuration: `GamePort.slnx`, `GamePort.csproj`, `global.json`. +- `glslangValidator` and `spirv-val` compile/validate Vulkan 1.3 shaders in `scripts/compile-shaders.sh`; distro package versions are not pinned there. +- CMake builds SDL locally in `scripts/bootstrap.sh`; curl, Python, and optional apt-get/dpkg-deb provision local dependencies without system installation. +- REA/Ghidra/JDK/Node are analysis-only tools selected by `scripts/rea.sh`; defaults reference Ghidra `12.1.4_PUBLIC` and a Java 21 JDK directory. Node and REA versions are not pinned in that launcher. +- Wine is an original-reference/preliminary compatibility tool, not a production dependency; `docs/dependencies.md` records Wine `11.0`. + +## Key Dependencies + +**Critical:** +- Silk.NET Vulkan/KHR/EXT `2.23.0`: native renderer access, swapchain/surface handling and validation messaging in `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`; direct pins in `GamePort.csproj`. +- SDL3 `3.4.2`: native window, input and audio backend, provisioned in `scripts/bootstrap.sh` and consumed through `src/GamePort/Platform/Sdl.cs` and `src/GamePort/Audio/SdlAudio.cs`. +- Host Vulkan loader and graphics ICD: required even for packaged self-contained builds; `scripts/package.sh` documents the Vulkan 1.3 prerequisite. + +**Infrastructure:** +- Locked transitives in `packages.lock.json`: Silk.NET.Core `2.23.0`, Microsoft.DotNet.PlatformAbstractions `3.1.6`, Microsoft.Extensions.DependencyModel `9.0.9`. +- .NET built-ins supply numerics, compression, JSON and filesystem operations; examples are `src/GamePort/Game/RuntimeCheckpoint.cs`, `src/GamePort/Assets/PngImage.cs` and `src/GamePort/Assets/AssetPath.cs`. +- Local asset converters are project modules, such as `tools/extractors/prepare.py`, `tools/extractors/omt.py` and `tools/extractors/sound_bank.py`, not a hosted conversion service. + +## Configuration + +**Environment:** +- Runtime configuration uses CLI options in `src/GamePort/Program.cs`, including `--assets`, `--scene`, `--level`, `--load-save`, `--write-save`, dimensions, headless rendering and mute/debug switches. +- Native SDL lookup checks the executable directory, project-local native library directory and platform loader in `src/GamePort/Platform/Sdl.cs`. +- `scripts/env.sh` configures SDK/cache paths, optional native-tool paths, `LD_LIBRARY_PATH` and `VK_LAYER_PATH`; no runtime service credentials are required. +- Preserve originals and write prepared assets outside their root; `tools/extractors/prepare.py` rejects output inside the original installation. + +**Build:** +- `GamePort.csproj` explicitly includes `src/GamePort/**/*.cs`, copies SPIR-V shaders and conditionally includes platform SDL binaries. +- `scripts/build-linux.sh` and `scripts/build-windows.sh` self-contained publish to `dist/linux-x64` and `dist/win-x64` and require the corresponding SDL library. +- `scripts/package.sh` assembles local assets/scenes/audio, runtime libraries, licenses, documentation and source provenance into both packages; generated packages are not source-control upload artifacts (`AGENTS.md`). + +## Platform Requirements + +**Development:** +- .NET 10 SDK; Python 3 for preparation/regressions; Vulkan-capable driver/loader and SDL backend dependencies for native checks (`README.md`, `scripts/test.sh`). +- Linux bootstrap additionally uses CMake and native build tooling for SDL and optional Ubuntu package extraction for shader/X11/audio/validation tools (`scripts/bootstrap.sh`). +- Read-only evidence work uses separate generated targets and local analysis tools (`tools/binary/rea_decompile_batch.py`, `scripts/rea.sh`); never execute or modify originals in place (`AGENTS.md`). + +**Production:** +- Shared `linux-x64` and `win-x64` source implementation, with self-contained .NET and native SDL packaging declared in `GamePort.csproj` and `scripts/package.sh`. +- Native Linux and Windows 10/11 x64 are required by `../prompt.MD`; host Vulkan 1.3+ driver/loader remains necessary. +- Offline operation is intentional (`AGENTS.md`). Native Linux scene evidence, Windows cross-publish, Wine runs and native Windows gameplay are separate claims; `docs/progress.md` and `docs/compatibility.md` retain bounded verification and outstanding broader/native Windows comparisons. + +--- + +*Stack analysis: 2026-11-12* diff --git a/.planning/codebase/STRUCTURE.md b/.planning/codebase/STRUCTURE.md new file mode 100644 index 0000000..a07f591 --- /dev/null +++ b/.planning/codebase/STRUCTURE.md @@ -0,0 +1,195 @@ +--- +last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 +last_mapped_at: 2026-11-12 +--- +# Codebase Structure + +**Analysis Date:** 2026-11-12 + +## Directory Layout + +```text +GamePort/ +├── GamePort.csproj / GamePort.slnx # Single runtime executable and solution +├── global.json / NuGet.Config # SDK/package configuration +├── src/GamePort/ +│ ├── Program.cs # Composition, CLI, scheduling and transitions +│ ├── Application/ # Presentation session, visuals, UI, debug and fixtures +│ ├── Assets/ # Original/prepared readers and CPU resources +│ ├── Audio/ # Scene mixer policy and owned SDL streams +│ ├── Game/ # Simulation, scripts, progression, recovered kernels +│ ├── Platform/ # SDL3 native interop +│ └── Rendering/ +│ ├── Vulkan/ # GPU backend +│ └── Shaders/ # GLSL and committed SPIR-V +├── tests/ # Python evidence/parser tests and C# executables +├── tools/ +│ ├── binary/ # Static evidence extractors and component probes +│ ├── extractors/ # Archive/model/audio/UI preparation +│ ├── levels/ # GAM forensic parser +│ └── recon/ # Inventory and reference observation tools +├── scripts/ # Local dependency/build/test/package scripts +├── docs/ +│ ├── analysis/ # Format, binary, graphics and gameplay findings +│ ├── checkpoint/ # Reconstruction gates, ledgers and continuation plan +│ ├── gameplay/ # Focused source contracts and live implementation evidence +│ └── reviews/ # Reference project reviews +└── .planning/codebase/ # GSD codebase maps +``` + +`../Original/` is a separate immutable evidence tree, not a source directory. The sibling JN-Engine reference is discussed in `docs/reviews/jn-engine-survey.md`; it is not linked into the runtime. Workspace `.git` is reserved; GamePort has the actual project repository (`AGENTS.md`). + +## Directory Purposes + +**`src/GamePort/Application/`:** +- Purpose: Translate game state into scene meshes, camera views, HUD/debug interfaces and native presentation lifetime. +- Contains: `*Visuals.cs`, overlays, preview helpers, explicit `*Smoke.cs` fixture drivers. +- Key files: `src/GamePort/Application/RenderSession.cs`, `src/GamePort/Application/SceneActorVisuals.cs`, `src/GamePort/Application/SceneHud.cs`, `src/GamePort/Application/UiViewport.cs`. +- Keep Vulkan device ownership in `RenderSession`/backend and expose mutable CPU scene data to visual adapters. + +**`src/GamePort/Game/`:** +- Purpose: Stateful gameplay and focused recovered mathematical/source contracts. +- Contains: Player simulation, script director, tasks/inventory, collision, gadget/vehicle systems and route checkpoints. These are currently flat files, not speculative Entities/Physics/AI subtrees. +- Key files: `src/GamePort/Game/LabSimulation.cs`, `src/GamePort/Game/PlayerSceneBinding.cs`, `src/GamePort/Game/SceneDirector.cs`, `src/GamePort/Game/SceneInteractions.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`. +- Keep source arithmetic in small named modules such as `src/GamePort/Game/JimmyGroundMotion.cs` and `src/GamePort/Game/JimmyOrientation.cs`. + +**`src/GamePort/Assets/`:** +- Purpose: Bounded decoding and CPU representation; no native device lifetime. +- Contains: GAM/TSK, ASE/PNG, prepared JSON/buffers, morphs and portable lookup. +- Key files: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/OriginalSave.cs`, `src/GamePort/Assets/Mesh.cs`, `src/GamePort/Assets/PreparedEntityResources.cs`, `src/GamePort/Assets/AssetPath.cs`. + +**`src/GamePort/Rendering/`, `src/GamePort/Platform/`, `src/GamePort/Audio/`:** +- Purpose: Native rendering, platform and audio boundaries. +- Contains: One Vulkan backend, shaders, SDL3 imports and independent WAV streams. +- Key files: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`, `src/GamePort/Rendering/Shaders/mesh.vert`, `src/GamePort/Rendering/Shaders/mesh.frag`, `src/GamePort/Platform/Sdl.cs`, `src/GamePort/Audio/SceneAudio.cs`, `src/GamePort/Audio/SdlAudio.cs`. + +**`tools/extractors/` and `tools/levels/`:** +- Purpose: Read-only source data interpretation and generated resource production. +- Contains: OMT, ASE, PNG, entity/model/UI/audio and gadget-specific extractors; lossless GAM reference parsing. +- Key files: `tools/extractors/prepare.py`, `tools/extractors/omt.py`, `tools/extractors/ase.py`, `tools/extractors/entities.py`, `tools/extractors/models.py`, `tools/levels/gam.py`. +- Route new resource preparation through `tools/extractors/prepare.py` so local package preparation uses the same path. + +**`tools/binary/` and `tools/recon/`:** +- Purpose: Preserve reproducible source-contract evidence and original/reference observation tooling. +- Contains: Python instruction/structure guards, C copied-component probes, inventory and observation utilities. +- Key files: `tools/binary/physical_registration.py`, `tools/binary/dynamic_reclip.py`, `tools/binary/actor_contact.py`, `tools/recon/inventory.py`, `tools/recon/reference_capture.py`. +- These tools are research/test infrastructure, not executable game dependencies (`GamePort.csproj`). + +**`docs/`:** +- Purpose: Evidence, confidence boundaries, implementation status and continuation instructions. +- Contains: `docs/analysis/`, `docs/gameplay/`, `docs/checkpoint/`, `docs/reviews/` and root status documents. +- Key files: `docs/progress.md`, `docs/tasks.md`, `docs/decisions.md`, `docs/compatibility.md`, `docs/architecture.md`, `docs/checkpoint/coverage.md`, `docs/checkpoint/next-work-plan.md`. +- Keep addresses/offsets, recovered versus inferred behavior and actual validation scope in the relevant report. + +## Key File Locations + +**Entry Points:** +- `src/GamePort/Program.cs`: Runtime CLI, scene composition, input loop, transitions and fixture invocation. +- `tools/extractors/prepare.py`: Original-to-prepared-assets pipeline. +- `tools/recon/inventory.py`: Original file inventory/hash verification. +- `scripts/test.sh`: Local consolidated regression/GPU checks. +- `scripts/package.sh`: Local self-contained package assembly and launchers. + +**Configuration:** +- `GamePort.csproj`: net10.0, Linux/Windows x64, explicit production source glob, Silk.NET references and shader/native content. +- `GamePort.slnx`: Solution entry. +- `global.json`: SDK selection. +- `NuGet.Config`, `packages.lock.json`: Package configuration and dependency lock. +- `scripts/env.sh`: Local toolchain environment setup. +- `.gitignore`: Generated output/cache exclusions. +- `AGENTS.md`: Movement priority, recovery gates, platform requirements and coordination. + +**Core Logic:** +- `src/GamePort/Game/LabSimulation.cs`: Player state and body/input/wrapper/apply/effect phase order. +- `src/GamePort/Game/PlayerSceneBinding.cs`: Director/actor/player control and preparation bridge; vehicle sequencing. +- `src/GamePort/Game/PlayerLevelState.cs`: Explicit retained route scalars outside TSK. +- `src/GamePort/Game/SceneDirector.cs`: Authored script/camera chains and live actor state. +- `src/GamePort/Game/RuntimeCheckpoint.cs`: Departure/RETURN context. +- `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`: Bounded source static/body path. +- `src/GamePort/Game/SceneCollision.cs`: Capsule compatibility geometry. +- `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`: Isolated recovered components, not live scene admission. +- `src/GamePort/Application/RenderSession.cs`: Persistent application-owned SDL/Vulkan lifetime. + +**Testing:** +- `tests/test_extractors.py`, `tests/test_levels.py`, `tests/test_models.py`: Python format/preparation coverage. +- `tests/test_checkpoint_*.py`, `tests/test_jimmy_*.py`: Source-contract and lifecycle evidence guards. +- `tests/GamePort.DirectorTests/Program.cs`: Script/control regressions. +- `tests/GamePort.BodyOwnershipTests/Program.cs`: Body/control ownership checks. +- `tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.JimmyAirTests/Program.cs`: Focused managed movement comparisons. +- `tests/GamePort.PairLifecycleTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`: Isolated component fixtures. +- `src/GamePort/Application/CutsceneIdleSmoke.cs`, `src/GamePort/Application/WindowTransitionSmoke.cs`: Native runtime fixture drivers, distinct from isolated numeric tests. + +## Naming Conventions + +**Files:** +- Use PascalCase C# files matching primary types: `src/GamePort/Game/JimmyAirMotion.cs`. +- Use feature-specific suffixes for roles: `src/GamePort/Application/ScooterVisuals.cs`, `src/GamePort/Game/ScooterMotion.cs`, `src/GamePort/Application/ScooterSmoke.cs`. +- Prefix recovered source contracts with `Original` where established: `src/GamePort/Game/OriginalNormalContacts.cs`; the prefix does not assert live integration. +- Use snake_case Python modules and tests: `tools/binary/dynamic_reclip.py`, `tests/test_dynamic_reclip.py`. +- Use kebab-case documentation topics: `docs/checkpoint/actor-normal-contacts.md`. + +**Directories:** +- Keep runtime namespaces grouped by concrete responsibility under `src/GamePort/`. +- Use `tests/GamePort.Tests/` for executable managed test projects with `Program.cs` and matching `.csproj`. +- Keep root Python tests under `tests/` and reusable retained references under `tests/fixtures/` or focused project folders. +- Keep evidence-oriented reports in `docs/checkpoint/`, source/live feature reports in `docs/gameplay/`. + +## Where to Add New Code + +**New Feature:** +- Primary code: `src/GamePort/Game/`; coordinate explicit composition and supported scene gates in `src/GamePort/Program.cs`. +- Presentation: Add a focused adapter under `src/GamePort/Application/`; use `src/GamePort/Application/UiViewport.cs` for UI sizing/pointers. +- Tests: Add focused `tests/GamePort.Tests/` numeric/state comparisons and source-evidence guards in `tests/test_.py` where appropriate. +- Evidence/status: Use `docs/gameplay/` or `docs/checkpoint/` and update `docs/progress.md`/`docs/tasks.md` when authorized gameplay work changes state. +- Preserve the current Jimmy stabilization priority and lab/outside capsule versus bounded source-body distinction (`AGENTS.md`, `src/GamePort/Program.cs`). + +**New Component/Module:** +- Recovered arithmetic: `src/GamePort/Game/`, with explicit input/output state as in `src/GamePort/Game/JimmyGroundMotion.cs`. +- Script preparation/control bridge: `src/GamePort/Game/PlayerSceneBinding.cs` and `src/GamePort/Game/SceneDirector.cs`; retain fresh/retained ordering. +- New binary format reader: `src/GamePort/Assets/`; forensic/extraction counterpart in `tools/extractors/` or `tools/levels/`. +- New visual: `src/GamePort/Application/`; extend backend only when required by source rendering behavior (`src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). +- New native interop: `src/GamePort/Platform/Sdl.cs`; keep allocation/release in the owning subsystem. +- New audio policy: `src/GamePort/Audio/SceneAudio.cs`; SDL stream mechanics belong in `src/GamePort/Audio/SdlAudio.cs`. +- New recovered collision callback: Focused `src/GamePort/Game/` component plus fixture first; do not wire `OriginalPairCollision` or `OriginalNormalContacts` into runtime without activation/order/derived-response evidence (`docs/checkpoint/next-work-plan.md`). + +**Utilities:** +- Asset path handling: `src/GamePort/Assets/AssetPath.cs`; preserve case-insensitive lookup and root containment. +- Offline source guards/probes: `tools/binary/`; use documented REA evidence for original-binary investigation (`AGENTS.md`). +- Shared extraction helpers: `tools/extractors/` next to the owning format; connect to `tools/extractors/prepare.py`. +- Build/package operations: `scripts/`; use local output and existing Linux/Windows entry scripts. + +## Special Directories + +**`artifacts/`:** +- Purpose: Prepared resources, generated evidence and local fixture output; default preparation root is `artifacts/extracted/` (`tools/extractors/prepare.py`). +- Generated: Yes. +- Committed: No (`.gitignore`). + +**`dist/`, `bin/`, `obj/`:** +- Purpose: Local self-contained packages and .NET build output (`scripts/package.sh`, `GamePort.csproj`). +- Generated: Yes. +- Committed: No (`.gitignore`). + +**`.tools/`, `.nuget/`, `.dotnet-home/`:** +- Purpose: Local toolchain, native dependencies and caches (`scripts/env.sh`, `GamePort.csproj`). +- Generated: Yes/local provisioned. +- Committed: No (`.gitignore`). + +**`src/GamePort/Rendering/Shaders/`:** +- Purpose: Source GLSL and packaged SPIR-V, compiled by `scripts/compile-shaders.sh`. +- Generated: `.spv` files are generated; `.vert`/`.frag` are source. +- Committed: Yes; `GamePort.csproj` copies SPIR-V to executable output. + +**`../Original/`:** +- Purpose: Immutable evidence and runtime asset source (`AGENTS.md`, `tools/recon/inventory.py`). +- Generated: No. +- Committed: Outside this repository; never modify or execute in place. + +**`.planning/codebase/`:** +- Purpose: Generated analysis maps for planning; current files are distinct from persistent authored `docs/architecture.md`. +- Generated: Yes, from tracked source/config/documentation inspection. +- Committed: Controlled by the mapping orchestrator; not excluded by `.gitignore`. + +--- + +*Structure analysis: 2026-11-12* diff --git a/.planning/codebase/TESTING.md b/.planning/codebase/TESTING.md new file mode 100644 index 0000000..16c4181 --- /dev/null +++ b/.planning/codebase/TESTING.md @@ -0,0 +1,171 @@ +--- +last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 +last_mapped_at: 2026-11-12 +--- +# Testing Patterns + +**Analysis Date:** 2026-11-12 + +## Test Framework + +**Runner:** +- Python standard-library `unittest`; no pinned Python test framework package is detected (`tests/test_extractors.py`, `scripts/test.sh`). +- Standalone C# `net10.0` console applications, invoked using `dotnet run`, rather than xUnit/NUnit/MSTest (`tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`, `scripts/test.sh`). +- The comprehensive local sequence is `scripts/test.sh`; it sources `scripts/env.sh`, prepares assets and runs managed, Python, rendering, audio and hash checks. + +**Assertion Library:** +- `unittest.TestCase` assertions and context managers (`tests/test_extractors.py`). +- C# local `Check`/`Near` functions or recursive JSON comparisons that throw exceptions (`tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`). + +**Run Commands:** +Run from the GamePort repository root; these are recorded commands, not checks executed by this mapping. + +```bash +source scripts/env.sh +python3 -m unittest discover -s tests -p 'test_*.py' -v +scripts/test.sh +dotnet run --project tests/GamePort.ActorContactTests +dotnet run --project tests/GamePort.JimmyGroundTests +dotnet run --project tests/GamePort.DataTests -- ../Original +python3 tests/GamePort.HudTests/test_ui.py +SDL_AUDIODRIVER=dummy dotnet run --project tests/GamePort.AudioPauseTests +NEUTRON_WINDOW_TEST=1 scripts/test.sh +scripts/test-window-transitions.sh +``` + +- No dedicated watch or coverage command is detected in `scripts/test.sh` or the inspected test projects. `scripts/test-window-transitions.sh` requires a prior build plus local Xvfb/Xfwm/session tools. + +## Test File Organization + +**Location:** +- Separate `tests/` directory; Python discovery sees root `test_*.py`, while HUD Python tests are invoked explicitly (`scripts/test.sh`). +- Each managed group has a project directory, `Program.cs` and optional JSON references (`tests/GamePort.ActorContactTests/`, `tests/GamePort.JimmyGroundTests/`). + +**Naming:** +- `tests/test_.py`, `tests/GamePort.Tests/Program.cs`, and descriptive `original-*-reference.json` or `expected.json` fixtures (`tests/test_actor_contact.py`, `tests/GamePort.DirectorTests/original-camera-rotation-reference.json`). + +**Structure:** +```text +tests/ + test_extractors.py + test_actor_contact.py + GamePort.ActorContactTests/ + GamePort.ActorContactTests.csproj + Program.cs + expected.json + GamePort.JimmyGroundTests/ + Program.cs + original-ground-reference.json +``` + +## Test Structure + +**Suite Organization:** +Use deterministic inputs and assertions with descriptive failures. Actual Python pattern from `tests/test_extractors.py`: + +```python +class BoundedReaders(unittest.TestCase): + def test_read_bounds_and_negative_size(self): + for size in (-1, 2): + with self.assertRaises(FormatError): Reader(b'x').take(size) +``` + +Actual C# comparison helper from `tests/GamePort.JimmyGroundTests/Program.cs`: + +```csharp +static void Check(bool condition,string name) +{ if(!condition)throw new Exception(name); } +static void Near(float value,float expected,string name) => + Check(float.IsFinite(value)&&Math.Abs(value-expected)<.02f, + $"{name}: {value} != {expected}"); +``` + +**Patterns:** +- Top-level managed programs load JSON using `AppContext.BaseDirectory`, enumerate cases, compare every relevant field, check case counts and print `PASS` (`tests/GamePort.JimmyGroundTests/Program.cs`). +- Test projects copy saved fixtures into output and compile production files directly with explicit globs (`tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`). +- Some fixture filenames are output links rather than colocated tracked files: `tests/GamePort.JimmyGroundTests/GamePort.JimmyGroundTests.csproj` links `tools/binary/jimmy_landing_rotation_reference.json` as `original-landing-rotation-reference.json`. Check source availability when reproducing a suite. +- Use `TemporaryDirectory` for exports and symlink rejection fixtures; local-original integration cases can use `skipUnless(ORIGINAL.exists())` (`tests/test_extractors.py`, `tests/test_actor_contact.py`). Do not assume every original-dependent suite has a skip guard. + +## Mocking + +**Framework:** No general mocking library is detected in the inspected projects. Use explicit fixtures, interfaces and callbacks (`tests/GamePort.ActorContactTests/Program.cs`). + +**Patterns:** +The actor-contact fixture implements `IOriginalNormalBody`, logs each accessor and deliberately changes state on a later read (`tests/GamePort.ActorContactTests/Program.cs`): + +```csharp +public Vector4 ReadVelocity() +{ + events.Add("Gv"); velocityGets++; + if(FreshY && velocityGets == 2) Velocity.Y = 99; + return Velocity; +} +``` + +**What to Mock:** +- Synthetic actor state, bounded callback endpoints, geometry and controlled getter mutations isolate original component behavior (`tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/actor-normal-contacts.md`). +- Dummy SDL audio drivers isolate lifecycle/consumption checks; they do not establish audible output (`scripts/test.sh`, `docs/compatibility.md`). + +**What NOT to Mock:** +- Preserve real parser byte boundaries, production algorithms, archive identities and saved original observations; compare through the production implementation (`tests/test_extractors.py`, `tests/GamePort.ActorContactTests/Program.cs`). +- Do not replace live GPU validation with a managed-only assertion; real headless Vulkan paths write readbacks (`scripts/test.sh`, `src/GamePort/Program.cs`). + +## Fixtures and Factories + +**Test Data:** +- Build minimal byte fixtures with explicit endian packing, e.g. the RGB555 canvas case in `tests/test_extractors.py` uses `struct.pack('>H', len(row))` and a synthetic `OmCv`/`OmGW` header. +- Use `Fixture.Reset(kind)` to seed reproducible body state and clear event logs before each named observation (`tests/GamePort.ActorContactTests/Program.cs`). +- Preserve source-executed references rather than deriving all expectations from the port. `tests/GamePort.ActorContactTests/expected.json` contains complete saved observations; `--native ` permits a fresh external observation comparison and `--dump` emits port states (`tests/GamePort.ActorContactTests/Program.cs`). + +**Location:** +- Saved component references live beside managed projects (`tests/GamePort.DynamicReclipTests/expected.json`, `tests/GamePort.GrapplerTests/original-query-reference.json`). +- Original integration fixtures are external local `../Original`; never modify them (`AGENTS.md`, `tests/test_extractors.py`). Generated extraction/replay outputs belong under ignored `artifacts/`, as specified by `scripts/test.sh`; this map does not inspect those outputs. +- Binary tools validate complete original bodies, relocation operands, table bindings and generated-probe output separation (`tests/test_actor_contact.py`, `tools/binary/actor_contact.py`). + +## Coverage + +**Requirements:** +- No enforced percentage threshold or coverage collector is detected in `scripts/test.sh` or `tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`. +- Use behavioral coverage: malformed lengths/counts/trailing bytes, coordinate/winding/UV identities, positive recovered behavior, explicit unsupported contracts, case completeness and callback read order (`tests/test_extractors.py`, `tests/GamePort.ActorContactTests/Program.cs`). +- `docs/progress.md` and `docs/compatibility.md` record 352 Python checks for the documented source checkpoint identified as `bdca29d` by the mapping task. This is an existing receipt, not a fresh run or independently recounted total. +- The same records distinguish integrated SDL/GPU evidence at `bf876e9` and unchanged packages at `924ad2f`. Do not attach the newest component counts to an older package or imply the latest component work reran graphics. + +**View Coverage:** Not detected. Consult `docs/compatibility.md` and subsystem reports for evidence scope rather than treating test count as gameplay completeness. + +## Test Types + +**Unit Tests:** +- Bounded readers, PackBits/PNG operations, numerical movement/orientation, task transitions, UI and standalone collision components (`tests/test_extractors.py`, `tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`). +- Explicit unsupported-path checks require exceptions instead of silent admission; zero-horizontal reflection is rejected in `tests/GamePort.ActorContactTests/Program.cs`. + +**Integration Tests:** +- Decode actual local archives and compare counts, models, materials, textures and exported references (`tests/test_extractors.py`, `tests/GamePort.DataTests/Program.cs`). +- `scripts/test.sh` prepares scenes/audio, verifies assets, runs save/load checks, SDL dummy audio lifecycle checks, Vulkan renders and original manifest verification. +- Differential component probes execute copied original instructions with synthetic state under Wine32, then compare port snapshots; complete-body/operand guards and provenance are described in `docs/checkpoint/actor-normal-contacts.md`. This is stronger than a port self-comparison but remains a bounded component experiment. + +**E2E Tests:** +- Port smoke flows cover story/practice/RETURN routes, cutscenes, gadgets, input, windows and real GPU readbacks (`scripts/test.sh`, `src/GamePort/Application/WindowTransitionSmoke.cs`). +- Optional window checks are gated by `NEUTRON_WINDOW_TEST=1`; `scripts/test-window-transitions.sh` creates a private Xvfb session with Xfwm to support asynchronous fullscreen requests. +- Whole-original gameplay equivalence and native Windows runtime are separate open evidence gates (`docs/compatibility.md`). Windows cross-publishing is compiler/package evidence; Wine execution is preliminary compatibility evidence. + +## Common Patterns + +**Async Testing:** +- No general async test runner pattern is detected in the inspected console/Python suites. SDL/window progression is exercised through frame-driven smoke state and real window-manager acknowledgements (`src/GamePort/Application/WindowTransitionSmoke.cs`, `scripts/test-window-transitions.sh`). + +**Error Testing:** +- Python uses `assertRaises` / `assertRaisesRegex`, including rejection of original-directory and symlink output (`tests/test_extractors.py`, `tests/test_actor_contact.py`). +- Managed tests call unsupported paths inside `try`, throw if accepted, and catch only the expected `NotSupportedException` (`tests/GamePort.ActorContactTests/Program.cs`). + +**Numerical comparisons:** +- Use tolerances appropriate to the specific observed contract: `.02f` and finite checks for ground motion; decimal-place comparisons for exported ASE positions/UVs (`tests/GamePort.JimmyGroundTests/Program.cs`, `tests/test_extractors.py`). +- Actor-contact snapshots compare JSON field shapes, array counts, event order and `GetSingle()` values exactly; do not weaken exact float32 checks by borrowing another suite's tolerance (`tests/GamePort.ActorContactTests/Program.cs`). +- Preserve source float-store boundaries rather than declaring all double intermediates a universal x87 equivalent (`docs/checkpoint/dynamic-reclip.md`). + +**Verification reporting:** +- State separately: compiler success, managed/Python assertions, copied-original component execution, port rendering/native SDL input, package provenance, whole-original comparison, and native Windows gameplay (`AGENTS.md`, `docs/progress.md`, `docs/compatibility.md`). +- No builds or tests are executed for this mapping; commands and evidence above describe the checked-in source and documented receipts. + +--- + +*Testing analysis: 2026-11-12*