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

16 KiB

last_mapped_commit, last_mapped_at
last_mapped_commit last_mapped_at
bdca29d3aa 2026-11-12

Architecture

Analysis Date: 2026-11-12

System Overview

Read-only ../Original assets
  -> tools/extractors/prepare.py -> artifacts/extracted manifests/buffers/WAV
  -> src/GamePort/Assets + original GAM/TSK/ASE/PNG readers
  -> Program.Run scene composition
       Game simulation/scripts -> Application visuals/HUD -> VulkanRenderer
       Game events -> SceneAudio -> SdlAudio -> SDL3
Program.Main -> persistent RenderSession -> SDL window + Vulkan instance/device

The desktop application is a single shared Linux/Windows C# executable (GamePort.csproj). src/GamePort/Program.cs composes concrete systems and owns scheduling. There is no runtime server, database, dependency-injection container, or external game engine.

Component Responsibilities

Component Responsibility File
Application entry CLI, resource composition, input dispatch, fixed ticks, scene continuation src/GamePort/Program.cs
Presentation session Application lifetime window and renderer; replace scene resources src/GamePort/Application/RenderSession.cs
Player simulation Physics, input/apply order, facing, jump/effects, player camera src/GamePort/Game/LabSimulation.cs
Script bridge Raw control owner, authored transforms, gadget cleanup, vehicle/passenger phases src/GamePort/Game/PlayerSceneBinding.cs
Scene director GAM actors, CAM/MCA/AI chains, cutscene camera, control and issue reporting src/GamePort/Game/SceneDirector.cs
Progression Contacts, inventory, tasks, transitions and save snapshots src/GamePort/Game/SceneInteractions.cs, src/GamePort/Game/TaskStates.cs
Resource readers Original and prepared data decoding src/GamePort/Assets/
Presentation adapters Mutable geometry, morphs, sprites, UI and camera projection src/GamePort/Application/
GPU backend Vulkan resources, rendering, resizing, readback and disposal src/GamePort/Rendering/Vulkan/VulkanRenderer.cs
Audio Independent music/speech/effects and SDL WAV stream ownership src/GamePort/Audio/SceneAudio.cs, src/GamePort/Audio/SdlAudio.cs

Pattern Overview

Overall: Explicit application composition with scene-local state, event-connected gameplay systems and a persistent native presentation owner.

Key Characteristics:

  • Keep scheduling visible in src/GamePort/Program.cs; source ordering is behavior, not interchangeable service invocation order.
  • Keep recovered arithmetic in focused src/GamePort/Game/ modules and presentation in src/GamePort/Application/.
  • Preserve the distinction between isolated recovered components and admitted live scene adapters (src/GamePort/Game/OriginalPairCollision.cs, src/GamePort/Game/OriginalNormalContacts.cs).
  • Use local original-derived assets; Python preparation is a development/package stage (tools/extractors/prepare.py, scripts/package.sh).

Layers

Application composition and presentation:

  • Purpose: Connect input, simulation, scripts, visuals, audio and GPU submission.
  • Location: src/GamePort/Program.cs, src/GamePort/Application/.
  • Contains: RenderSession, debug interfaces, SceneHud, visual adapters and smoke fixtures.
  • Depends on: Game, Assets, Audio, Platform and Rendering namespaces.
  • Used by: Executable entry and managed regression projects.

Game state and recovered algorithms:

  • Purpose: Own simulation and script/progression semantics.
  • Location: src/GamePort/Game/.
  • Contains: LabSimulation, SceneDirector, inventory/tasks, gadgets, vehicles, collision and numeric kernels.
  • Depends on: System.Numerics and decoded asset types in src/GamePort/Assets/.
  • Used by: Application orchestration and focused tests/GamePort.*Tests/ executables.

Asset decoding:

  • Purpose: Convert bounded original/prepared files into typed CPU resources.
  • Location: src/GamePort/Assets/.
  • Contains: GamLevel, OriginalSave, Mesh, MorphAnimation, PngImage, resource identities and path resolution.
  • Depends on: Filesystem, binary primitives, JSON and numerics; no renderer ownership.
  • Used by: Game systems and application/renderer initialization.

Native platform, GPU and audio:

  • Purpose: Own unmanaged interoperability and device resources.
  • Location: src/GamePort/Platform/Sdl.cs, src/GamePort/Rendering/Vulkan/VulkanRenderer.cs, src/GamePort/Audio/.
  • Contains: SDL3 imports, Vulkan offscreen/present paths, WAV streams and scene audio orchestration.
  • Depends on: SDL3, Silk.NET.Vulkan, shaders and decoded meshes/textures.
  • Used by: src/GamePort/Application/RenderSession.cs and src/GamePort/Program.cs.

Offline evidence and preparation:

  • Purpose: Inspect source evidence and create reusable resources without modifying originals.
  • Location: tools/binary/, tools/extractors/, tools/levels/, tools/recon/.
  • Contains: Python parsers, extraction manifests, C component probes and observation tools.
  • Depends on: Local original files and explicit analysis tooling; not part of the native runtime dependency graph.
  • Used by: Tests, local preparation, research and scripts/package.sh.

Data Flow

Primary Request Path

  1. Program.Main creates persistent presentation, energy, grappler memory and diagnostics, then invokes the scene runner (src/GamePort/Program.cs:14).
  2. Run resolves originals, loads prepared geometry and original GAM/save data, constructs scene systems and binds the player (src/GamePort/Program.cs:46).
  3. SDL polling updates held input; unpaused gameplay advances through a 60 Hz accumulator, while bounded fixtures use explicit steps (src/GamePort/Program.cs:1057, src/GamePort/Game/FixedStepClock.cs).
  4. Each tick advances gadget/projectile bodies, player/vehicle binding, timers/targets, interactions/mechanisms, patrols, director and animation state (src/GamePort/Program.cs:1271).
  5. Application visuals mutate mesh vertices/draw properties, update HUD and select gameplay/script/orbit camera; renderer uploads and renders (src/GamePort/Program.cs:1371, src/GamePort/Rendering/Vulkan/VulkanRenderer.cs).

Player and cutscene phase ordering

  1. LabSimulation.Step runs body physics before registry-style callbacks (src/GamePort/Game/LabSimulation.cs:265).
  2. Fresh direct-scene input runs before ceiling/floor/facing and player apply. Retained input runs after player/effect updates. Program sets InputAfterPlayerUpdate for story entry or carried saves (src/GamePort/Program.cs:361).
  3. Lack of Jimmy control gates input/player apply, not body, facing or owned effect clocks. PlayerSceneBinding receives director preparation/transform events and preserves vehicle control ordering (src/GamePort/Game/PlayerSceneBinding.cs).
  4. Script preparation separates stop-motion, orientation flattening, gadget release and authored transforms; do not replace these with a generic player reset (src/GamePort/Game/PlayerSceneBinding.cs, src/GamePort/Game/SceneDirector.cs).

Scene loading and retained state

  1. Contact or practice logic requests a LevelTransition; application stages a departure/RETURN root through RuntimeCheckpoint (src/GamePort/Program.cs:339, src/GamePort/Game/RuntimeCheckpoint.cs).
  2. Scene runner returns a continuation with destination arguments, original-format save snapshot and optional bounded PlayerLevelState (src/GamePort/Program.cs, src/GamePort/Game/PlayerLevelState.cs).
  3. Main invokes a new scene run. GAM actors, bindings, visual resources and scene audio are rebuilt; RenderSession.LoadScene calls ReplaceScene on the existing renderer (src/GamePort/Application/RenderSession.cs).
  4. Vulkan scene replacement waits for device idle and replaces scene GPU resources while retaining presentation identity (src/GamePort/Rendering/Vulkan/VulkanRenderer.cs:101).

Source-to-extracted-assets pipeline

  1. tools/recon/inventory.py provides original manifest verification against docs/original-manifest.json.
  2. tools/extractors/prepare.py reads OMT/GAM/ASE/PNG and dispatches scene, entity, model, UI, effect and gadget resource extraction. tools/extractors/omt.py and tools/levels/gam.py retain format-specific parsing.
  3. Generated artifacts/extracted/ contains scene JSON, textures, animation buffers/manifests, entity/model resources, WAV and a scene catalog. Missing scene archives are reported rather than substituted (tools/extractors/prepare.py).
  4. Runtime readers load prepared resources and original GAM/TSK/base assets; scripts/package.sh copies those into local package scenes/ and assets/ trees. Runtime packages do not need Python.

State Management:

  • Application session: presentation, diagnostics preference, PlayerEnergy and GrapplerMemory are created outside the scene loop (src/GamePort/Program.cs).
  • Scene: simulation, actors, tasks/inventory, mechanisms, animation meshes, audio and bindings are concrete objects recreated by Run (src/GamePort/Program.cs).
  • Retained route scalars: PlayerLevelState supports LV1B/VR04/LEV1 with selected gadget -1 or 3; this is in-memory state, not an extension of TSK (src/GamePort/Game/PlayerLevelState.cs).
  • Original save persistence: OriginalSave encodes TSK tasks/items/checkpoint state; save output uses a temporary file and move outside original assets (src/GamePort/Assets/OriginalSave.cs, src/GamePort/Program.cs).

Key Abstractions

Mesh and MeshDraw:

  • Purpose: CPU geometry, source collision polygons, textures and per-range material/presentation state.
  • Examples: src/GamePort/Assets/Mesh.cs, src/GamePort/Application/SceneActorVisuals.cs.
  • Pattern: Arrays plus mutable draw state; visual adapters append/update shared scene data rather than owning Vulkan objects.

GamEntity and DirectorActor:

  • Purpose: Preserve serialized properties separately from live authored actor state.
  • Examples: src/GamePort/Assets/GamLevel.cs, src/GamePort/Game/SceneDirector.cs.
  • Pattern: Bounded typed decoding followed by scene-specific actor/script execution; unknown behavior produces issues.

Original collision components and live adapters:

  • Purpose: Express bounded source contracts without assuming a complete recovered physical registry.
  • Examples: src/GamePort/Game/OriginalBodyPhysics.cs, src/GamePort/Game/OriginalStaticCollision.cs, src/GamePort/Game/OriginalPairCollision.cs, src/GamePort/Game/OriginalNormalContacts.cs.
  • Pattern: Caller-owned state/accessors and explicit profiles. Pair callbacks and generic normal responses do not establish scene membership or Jimmy's override policy.

Entry Points

Native executable:

  • Location: src/GamePort/Program.cs.
  • Triggers: dotnet run, local published executable or package launchers.
  • Responsibilities: Scene/model preview, playable story, asset verification, audio/GPU/SDL fixtures and explicit CLI validation.

Offline preparation:

  • Location: tools/extractors/prepare.py.
  • Triggers: Local developer invocation and scripts/package.sh.
  • Responsibilities: Original-derived resource production outside the source installation.

Regression and build entry points:

  • Location: scripts/test.sh, scripts/build-linux.sh, scripts/build-windows.sh, tests/GamePort.*Tests/Program.cs, tests/test_*.py.
  • Triggers: Local scripts or direct test projects.
  • Responsibilities: Bounded source/algorithm/parser checks, GPU fixtures and native packaging inputs. A cross-publish is not native Windows runtime evidence.

Architectural Constraints

  • Threading: Gameplay and rendering are explicitly scheduled on the application loop; Vulkan submission/presentation waits synchronously (src/GamePort/Program.cs, src/GamePort/Rendering/Vulkan/VulkanRenderer.cs). SDL manages audio stream transport (src/GamePort/Audio/SdlAudio.cs).
  • Global state: Native SDL state is process-level; managed session state is explicitly passed. Keep native resource disposal scoped through RenderSession and SdlAudio (src/GamePort/Application/RenderSession.cs, src/GamePort/Audio/SdlAudio.cs).
  • Circular imports: No project-layer circular project-reference chain is detected: production source is compiled into one executable (GamePort.csproj). Events intentionally connect director/player/inventory lifetimes (src/GamePort/Game/PlayerSceneBinding.cs).
  • Live solver boundaries: Lab/outside retain capsule compatibility. Original static body is admitted by explicit scene gates including VR01/VR02/VR04/VR07/VR08; VR04 is a bounded source-body scene, not a full dynamic registry (src/GamePort/Program.cs:361, src/GamePort/Game/LabSimulation.cs).
  • Recovery gates: OriginalPairCollision and OriginalNormalContacts are isolated components, not live admission. Physical activation/helper lifetime, actual derived callbacks and shared reclip remain separate obligations (src/GamePort/Game/OriginalPairCollision.cs, src/GamePort/Game/OriginalNormalContacts.cs, docs/checkpoint/next-work-plan.md).
  • Movement priority: Preserve Jimmy movement and caller-dependent retained cutscene state before gameplay expansion (AGENTS.md, docs/gameplay/jimmy-movement-stabilization.md).
  • References: ../Original/ is immutable authoritative evidence; sibling JN-Engine research is a source lead, not a runtime service or replacement movement implementation (AGENTS.md, docs/reviews/jn-engine-survey.md).

Anti-Patterns

Treating component recovery as live scene coverage

What happens: Bounded pair/contact components coexist with separately gated runtime solvers (src/GamePort/Game/OriginalPairCollision.cs, src/GamePort/Program.cs). Why it's wrong: Substituting them solely because component tests pass loses physical registration, activation and real derived callback policies. Do this instead: Preserve explicit scene admission in src/GamePort/Program.cs and require the dependencies recorded in docs/checkpoint/next-work-plan.md before wiring new actors.

Collapsing input, control and body phases

What happens: LabSimulation exposes both fresh and retained callback orders, while scripts independently gate raw control (src/GamePort/Game/LabSimulation.cs, src/GamePort/Game/PlayerSceneBinding.cs). Why it's wrong: A generic reset or input-first rewrite changes neutral cutscene return, facing and effect behavior. Do this instead: Preserve named preparation events, retained scalar state and InputAfterPlayerUpdate; extend focused lifecycle regressions (tests/GamePort.BodyOwnershipTests/Program.cs, tests/GamePort.DirectorTests/Program.cs).

Error Handling

Strategy: Reject invalid data and native failures explicitly; report unrecovered script behavior without inventing execution (src/GamePort/Assets/GamLevel.cs, src/GamePort/Game/SceneDirector.cs).

Patterns:

  • Top-level exception handling prints to stderr and returns 1; validation/fixture failures return 2 (src/GamePort/Program.cs).
  • Bounded readers throw InvalidDataException; missing resources use explicit missing/ambiguous errors (src/GamePort/Assets/AssetPath.cs, src/GamePort/Assets/PreparedEntityResources.cs).
  • SDL/Vulkan failure checks throw with native operation context; cleanup uses IDisposable/finally (src/GamePort/Application/RenderSession.cs, src/GamePort/Rendering/Vulkan/VulkanRenderer.cs).
  • Director bounded dispatch records unsupported behavior and blocks problematic chains (src/GamePort/Game/SceneDirector.cs).

Cross-Cutting Concerns

Logging: Console diagnostics, unrecovered behavior lists and live debug overlays (src/GamePort/Program.cs, src/GamePort/Application/DebugDiagnostics.cs). Validation: Explicit endian parsing, finite/count/size checks, resource identity validation and Vulkan validation/error counts (src/GamePort/Assets/GamLevel.cs, src/GamePort/Assets/PreparedEntityResources.cs, src/GamePort/Rendering/Vulkan/VulkanRenderer.cs). Authentication: Not applicable; local desktop runtime with no online identity service (GamePort.csproj, src/GamePort/Program.cs).


Architecture analysis: 2026-11-12