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,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*
|
||||
Reference in new issue
Block a user