--- last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 last_mapped_at: 2026-11-12 --- # Codebase Structure **Analysis Date:** 2026-11-12 ## Directory Layout ```text GamePort/ ├── GamePort.csproj / GamePort.slnx # Single runtime executable and solution ├── global.json / NuGet.Config # SDK/package configuration ├── src/GamePort/ │ ├── Program.cs # Composition, CLI, scheduling and transitions │ ├── Application/ # Presentation session, visuals, UI, debug and fixtures │ ├── Assets/ # Original/prepared readers and CPU resources │ ├── Audio/ # Scene mixer policy and owned SDL streams │ ├── Game/ # Simulation, scripts, progression, recovered kernels │ ├── Platform/ # SDL3 native interop │ └── Rendering/ │ ├── Vulkan/ # GPU backend │ └── Shaders/ # GLSL and committed SPIR-V ├── tests/ # Python evidence/parser tests and C# executables ├── tools/ │ ├── binary/ # Static evidence extractors and component probes │ ├── extractors/ # Archive/model/audio/UI preparation │ ├── levels/ # GAM forensic parser │ └── recon/ # Inventory and reference observation tools ├── scripts/ # Local dependency/build/test/package scripts ├── docs/ │ ├── analysis/ # Format, binary, graphics and gameplay findings │ ├── checkpoint/ # Reconstruction gates, ledgers and continuation plan │ ├── gameplay/ # Focused source contracts and live implementation evidence │ └── reviews/ # Reference project reviews └── .planning/codebase/ # GSD codebase maps ``` `../Original/` is a separate immutable evidence tree, not a source directory. The sibling JN-Engine reference is discussed in `docs/reviews/jn-engine-survey.md`; it is not linked into the runtime. Workspace `.git` is reserved; GamePort has the actual project repository (`AGENTS.md`). ## Directory Purposes **`src/GamePort/Application/`:** - Purpose: Translate game state into scene meshes, camera views, HUD/debug interfaces and native presentation lifetime. - Contains: `*Visuals.cs`, overlays, preview helpers, explicit `*Smoke.cs` fixture drivers. - Key files: `src/GamePort/Application/RenderSession.cs`, `src/GamePort/Application/SceneActorVisuals.cs`, `src/GamePort/Application/SceneHud.cs`, `src/GamePort/Application/UiViewport.cs`. - Keep Vulkan device ownership in `RenderSession`/backend and expose mutable CPU scene data to visual adapters. **`src/GamePort/Game/`:** - Purpose: Stateful gameplay and focused recovered mathematical/source contracts. - Contains: Player simulation, script director, tasks/inventory, collision, gadget/vehicle systems and route checkpoints. These are currently flat files, not speculative Entities/Physics/AI subtrees. - Key files: `src/GamePort/Game/LabSimulation.cs`, `src/GamePort/Game/PlayerSceneBinding.cs`, `src/GamePort/Game/SceneDirector.cs`, `src/GamePort/Game/SceneInteractions.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`. - Keep source arithmetic in small named modules such as `src/GamePort/Game/JimmyGroundMotion.cs` and `src/GamePort/Game/JimmyOrientation.cs`. **`src/GamePort/Assets/`:** - Purpose: Bounded decoding and CPU representation; no native device lifetime. - Contains: GAM/TSK, ASE/PNG, prepared JSON/buffers, morphs and portable lookup. - Key files: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/OriginalSave.cs`, `src/GamePort/Assets/Mesh.cs`, `src/GamePort/Assets/PreparedEntityResources.cs`, `src/GamePort/Assets/AssetPath.cs`. **`src/GamePort/Rendering/`, `src/GamePort/Platform/`, `src/GamePort/Audio/`:** - Purpose: Native rendering, platform and audio boundaries. - Contains: One Vulkan backend, shaders, SDL3 imports and independent WAV streams. - Key files: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`, `src/GamePort/Rendering/Shaders/mesh.vert`, `src/GamePort/Rendering/Shaders/mesh.frag`, `src/GamePort/Platform/Sdl.cs`, `src/GamePort/Audio/SceneAudio.cs`, `src/GamePort/Audio/SdlAudio.cs`. **`tools/extractors/` and `tools/levels/`:** - Purpose: Read-only source data interpretation and generated resource production. - Contains: OMT, ASE, PNG, entity/model/UI/audio and gadget-specific extractors; lossless GAM reference parsing. - Key files: `tools/extractors/prepare.py`, `tools/extractors/omt.py`, `tools/extractors/ase.py`, `tools/extractors/entities.py`, `tools/extractors/models.py`, `tools/levels/gam.py`. - Route new resource preparation through `tools/extractors/prepare.py` so local package preparation uses the same path. **`tools/binary/` and `tools/recon/`:** - Purpose: Preserve reproducible source-contract evidence and original/reference observation tooling. - Contains: Python instruction/structure guards, C copied-component probes, inventory and observation utilities. - Key files: `tools/binary/physical_registration.py`, `tools/binary/dynamic_reclip.py`, `tools/binary/actor_contact.py`, `tools/recon/inventory.py`, `tools/recon/reference_capture.py`. - These tools are research/test infrastructure, not executable game dependencies (`GamePort.csproj`). **`docs/`:** - Purpose: Evidence, confidence boundaries, implementation status and continuation instructions. - Contains: `docs/analysis/`, `docs/gameplay/`, `docs/checkpoint/`, `docs/reviews/` and root status documents. - Key files: `docs/progress.md`, `docs/tasks.md`, `docs/decisions.md`, `docs/compatibility.md`, `docs/architecture.md`, `docs/checkpoint/coverage.md`, `docs/checkpoint/next-work-plan.md`. - Keep addresses/offsets, recovered versus inferred behavior and actual validation scope in the relevant report. ## Key File Locations **Entry Points:** - `src/GamePort/Program.cs`: Runtime CLI, scene composition, input loop, transitions and fixture invocation. - `tools/extractors/prepare.py`: Original-to-prepared-assets pipeline. - `tools/recon/inventory.py`: Original file inventory/hash verification. - `scripts/test.sh`: Local consolidated regression/GPU checks. - `scripts/package.sh`: Local self-contained package assembly and launchers. **Configuration:** - `GamePort.csproj`: net10.0, Linux/Windows x64, explicit production source glob, Silk.NET references and shader/native content. - `GamePort.slnx`: Solution entry. - `global.json`: SDK selection. - `NuGet.Config`, `packages.lock.json`: Package configuration and dependency lock. - `scripts/env.sh`: Local toolchain environment setup. - `.gitignore`: Generated output/cache exclusions. - `AGENTS.md`: Movement priority, recovery gates, platform requirements and coordination. **Core Logic:** - `src/GamePort/Game/LabSimulation.cs`: Player state and body/input/wrapper/apply/effect phase order. - `src/GamePort/Game/PlayerSceneBinding.cs`: Director/actor/player control and preparation bridge; vehicle sequencing. - `src/GamePort/Game/PlayerLevelState.cs`: Explicit retained route scalars outside TSK. - `src/GamePort/Game/SceneDirector.cs`: Authored script/camera chains and live actor state. - `src/GamePort/Game/RuntimeCheckpoint.cs`: Departure/RETURN context. - `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`: Bounded source static/body path. - `src/GamePort/Game/SceneCollision.cs`: Capsule compatibility geometry. - `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`: Isolated recovered components, not live scene admission. - `src/GamePort/Application/RenderSession.cs`: Persistent application-owned SDL/Vulkan lifetime. **Testing:** - `tests/test_extractors.py`, `tests/test_levels.py`, `tests/test_models.py`: Python format/preparation coverage. - `tests/test_checkpoint_*.py`, `tests/test_jimmy_*.py`: Source-contract and lifecycle evidence guards. - `tests/GamePort.DirectorTests/Program.cs`: Script/control regressions. - `tests/GamePort.BodyOwnershipTests/Program.cs`: Body/control ownership checks. - `tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.JimmyAirTests/Program.cs`: Focused managed movement comparisons. - `tests/GamePort.PairLifecycleTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`: Isolated component fixtures. - `src/GamePort/Application/CutsceneIdleSmoke.cs`, `src/GamePort/Application/WindowTransitionSmoke.cs`: Native runtime fixture drivers, distinct from isolated numeric tests. ## Naming Conventions **Files:** - Use PascalCase C# files matching primary types: `src/GamePort/Game/JimmyAirMotion.cs`. - Use feature-specific suffixes for roles: `src/GamePort/Application/ScooterVisuals.cs`, `src/GamePort/Game/ScooterMotion.cs`, `src/GamePort/Application/ScooterSmoke.cs`. - Prefix recovered source contracts with `Original` where established: `src/GamePort/Game/OriginalNormalContacts.cs`; the prefix does not assert live integration. - Use snake_case Python modules and tests: `tools/binary/dynamic_reclip.py`, `tests/test_dynamic_reclip.py`. - Use kebab-case documentation topics: `docs/checkpoint/actor-normal-contacts.md`. **Directories:** - Keep runtime namespaces grouped by concrete responsibility under `src/GamePort/`. - Use `tests/GamePort.Tests/` for executable managed test projects with `Program.cs` and matching `.csproj`. - Keep root Python tests under `tests/` and reusable retained references under `tests/fixtures/` or focused project folders. - Keep evidence-oriented reports in `docs/checkpoint/`, source/live feature reports in `docs/gameplay/`. ## Where to Add New Code **New Feature:** - Primary code: `src/GamePort/Game/`; coordinate explicit composition and supported scene gates in `src/GamePort/Program.cs`. - Presentation: Add a focused adapter under `src/GamePort/Application/`; use `src/GamePort/Application/UiViewport.cs` for UI sizing/pointers. - Tests: Add focused `tests/GamePort.Tests/` numeric/state comparisons and source-evidence guards in `tests/test_.py` where appropriate. - Evidence/status: Use `docs/gameplay/` or `docs/checkpoint/` and update `docs/progress.md`/`docs/tasks.md` when authorized gameplay work changes state. - Preserve the current Jimmy stabilization priority and lab/outside capsule versus bounded source-body distinction (`AGENTS.md`, `src/GamePort/Program.cs`). **New Component/Module:** - Recovered arithmetic: `src/GamePort/Game/`, with explicit input/output state as in `src/GamePort/Game/JimmyGroundMotion.cs`. - Script preparation/control bridge: `src/GamePort/Game/PlayerSceneBinding.cs` and `src/GamePort/Game/SceneDirector.cs`; retain fresh/retained ordering. - New binary format reader: `src/GamePort/Assets/`; forensic/extraction counterpart in `tools/extractors/` or `tools/levels/`. - New visual: `src/GamePort/Application/`; extend backend only when required by source rendering behavior (`src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). - New native interop: `src/GamePort/Platform/Sdl.cs`; keep allocation/release in the owning subsystem. - New audio policy: `src/GamePort/Audio/SceneAudio.cs`; SDL stream mechanics belong in `src/GamePort/Audio/SdlAudio.cs`. - New recovered collision callback: Focused `src/GamePort/Game/` component plus fixture first; do not wire `OriginalPairCollision` or `OriginalNormalContacts` into runtime without activation/order/derived-response evidence (`docs/checkpoint/next-work-plan.md`). **Utilities:** - Asset path handling: `src/GamePort/Assets/AssetPath.cs`; preserve case-insensitive lookup and root containment. - Offline source guards/probes: `tools/binary/`; use documented REA evidence for original-binary investigation (`AGENTS.md`). - Shared extraction helpers: `tools/extractors/` next to the owning format; connect to `tools/extractors/prepare.py`. - Build/package operations: `scripts/`; use local output and existing Linux/Windows entry scripts. ## Special Directories **`artifacts/`:** - Purpose: Prepared resources, generated evidence and local fixture output; default preparation root is `artifacts/extracted/` (`tools/extractors/prepare.py`). - Generated: Yes. - Committed: No (`.gitignore`). **`dist/`, `bin/`, `obj/`:** - Purpose: Local self-contained packages and .NET build output (`scripts/package.sh`, `GamePort.csproj`). - Generated: Yes. - Committed: No (`.gitignore`). **`.tools/`, `.nuget/`, `.dotnet-home/`:** - Purpose: Local toolchain, native dependencies and caches (`scripts/env.sh`, `GamePort.csproj`). - Generated: Yes/local provisioned. - Committed: No (`.gitignore`). **`src/GamePort/Rendering/Shaders/`:** - Purpose: Source GLSL and packaged SPIR-V, compiled by `scripts/compile-shaders.sh`. - Generated: `.spv` files are generated; `.vert`/`.frag` are source. - Committed: Yes; `GamePort.csproj` copies SPIR-V to executable output. **`../Original/`:** - Purpose: Immutable evidence and runtime asset source (`AGENTS.md`, `tools/recon/inventory.py`). - Generated: No. - Committed: Outside this repository; never modify or execute in place. **`.planning/codebase/`:** - Purpose: Generated analysis maps for planning; current files are distinct from persistent authored `docs/architecture.md`. - Generated: Yes, from tracked source/config/documentation inspection. - Committed: Controlled by the mapping orchestrator; not excluded by `.gitignore`. --- *Structure analysis: 2026-11-12*