docs: map existing codebase
This commit is contained in:
1 parent
bdca29d3aa
commit
f2f3a805cd
7 files changed
+1012
No files matched your search
@@ -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*
|
||||||
@@ -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*
|
||||||
@@ -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*
|
||||||
@@ -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*
|
||||||
@@ -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*
|
||||||
@@ -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*
|
||||||
@@ -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*
|
||||||
Reference in new issue
Block a user