docs: map existing codebase

This commit is contained in:
UnixNight committed 2026-11-12 11:06:58 -05:00
1 parent bdca29d3aa
commit f2f3a805cd
7 files changed
+1012

No files matched your search

+199
View File
@@ -0,0 +1,199 @@
---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
<!-- refreshed: 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*
+143
View File
@@ -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*
+121
View File
@@ -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_<behavior>`; `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<byte> 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# `/// <summary>` 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*
+92
View File
@@ -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*
+91
View File
@@ -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*
+195
View File
@@ -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.<Subject>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.<Subject>Tests/` numeric/state comparisons and source-evidence guards in `tests/test_<subject>.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*
+171
View File
@@ -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_<domain>.py`, `tests/GamePort.<Domain>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 <observations.json>` 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*