Files
2026-11-12 11:06:58 -05:00

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.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