docs: map existing codebase

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

No files matched your search

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