13 KiB
last_mapped_commit, last_mapped_at
| last_mapped_commit | last_mapped_at |
|---|---|
bdca29d3aa |
2026-11-12 |
Codebase Structure
Analysis Date: 2026-11-12
Directory Layout
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.csfixture 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.csandsrc/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.pyso 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
Originalwhere 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 withProgram.csand matching.csproj. - Keep root Python tests under
tests/and reusable retained references undertests/fixtures/or focused project folders. - Keep evidence-oriented reports in
docs/checkpoint/, source/live feature reports indocs/gameplay/.
Where to Add New Code
New Feature:
- Primary code:
src/GamePort/Game/; coordinate explicit composition and supported scene gates insrc/GamePort/Program.cs. - Presentation: Add a focused adapter under
src/GamePort/Application/; usesrc/GamePort/Application/UiViewport.csfor UI sizing/pointers. - Tests: Add focused
tests/GamePort.<Subject>Tests/numeric/state comparisons and source-evidence guards intests/test_<subject>.pywhere appropriate. - Evidence/status: Use
docs/gameplay/ordocs/checkpoint/and updatedocs/progress.md/docs/tasks.mdwhen 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 insrc/GamePort/Game/JimmyGroundMotion.cs. - Script preparation/control bridge:
src/GamePort/Game/PlayerSceneBinding.csandsrc/GamePort/Game/SceneDirector.cs; retain fresh/retained ordering. - New binary format reader:
src/GamePort/Assets/; forensic/extraction counterpart intools/extractors/ortools/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 insrc/GamePort/Audio/SdlAudio.cs. - New recovered collision callback: Focused
src/GamePort/Game/component plus fixture first; do not wireOriginalPairCollisionorOriginalNormalContactsinto 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 totools/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:
.spvfiles are generated;.vert/.fragare source. - Committed: Yes;
GamePort.csprojcopies 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