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 insrc/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.Numericsand decoded asset types insrc/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.csandsrc/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
Program.Maincreates persistent presentation, energy, grappler memory and diagnostics, then invokes the scene runner (src/GamePort/Program.cs:14).Runresolves originals, loads prepared geometry and original GAM/save data, constructs scene systems and binds the player (src/GamePort/Program.cs:46).- 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). - Each tick advances gadget/projectile bodies, player/vehicle binding, timers/targets, interactions/mechanisms, patrols, director and animation state (
src/GamePort/Program.cs:1271). - 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
LabSimulation.Stepruns body physics before registry-style callbacks (src/GamePort/Game/LabSimulation.cs:265).- Fresh direct-scene input runs before ceiling/floor/facing and player apply. Retained input runs after player/effect updates.
ProgramsetsInputAfterPlayerUpdatefor story entry or carried saves (src/GamePort/Program.cs:361). - Lack of Jimmy control gates input/player apply, not body, facing or owned effect clocks.
PlayerSceneBindingreceives director preparation/transform events and preserves vehicle control ordering (src/GamePort/Game/PlayerSceneBinding.cs). - 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
- Contact or practice logic requests a
LevelTransition; application stages a departure/RETURN root throughRuntimeCheckpoint(src/GamePort/Program.cs:339,src/GamePort/Game/RuntimeCheckpoint.cs). - 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). Maininvokes a new scene run. GAM actors, bindings, visual resources and scene audio are rebuilt;RenderSession.LoadScenecallsReplaceSceneon the existing renderer (src/GamePort/Application/RenderSession.cs).- 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
tools/recon/inventory.pyprovides original manifest verification againstdocs/original-manifest.json.tools/extractors/prepare.pyreads OMT/GAM/ASE/PNG and dispatches scene, entity, model, UI, effect and gadget resource extraction.tools/extractors/omt.pyandtools/levels/gam.pyretain format-specific parsing.- 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). - Runtime readers load prepared resources and original GAM/TSK/base assets;
scripts/package.shcopies those into local packagescenes/andassets/trees. Runtime packages do not need Python.
State Management:
- Application session: presentation, diagnostics preference,
PlayerEnergyandGrapplerMemoryare 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:
PlayerLevelStatesupports 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:
OriginalSaveencodes 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
RenderSessionandSdlAudio(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:
OriginalPairCollisionandOriginalNormalContactsare 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