# Architecture Use a single .NET 10 C# executable, Silk.NET.Vulkan for Vulkan 1.3 rendering, SDL3 for platform windowing, input and audio. Linux x64 and Windows x64 are equally required. Source is `src/GamePort/`; root executable csproj allows `dotnet build` and `dotnet run` from GamePort. No runtime network dependencies. `Scooter` is a separate registered C3DJEEP in VR05/LEV1, owning body, wheels, steering/impact/jump clocks and camera state. Selection summons at the companion; strict contact transfers raw control. PlayerSceneBinding runs body, player/input, vehicle frame/passenger-copy, then wheel phase. OrdinaryBodyPhysics exposes the wall callback before floor/friction so contact speed writes affect the same pass. ScooterVisuals uses exact unit-scale body/wheels/rider morphs; SceneAudio maps source engine frequency to SDL stream ratio. Goddard follow is opt-in for these scenes. Scene-local lifetime, provisional moving doors and fixed cadence remain explicit boundaries. See gameplay/scooter-live.md. `BaseballGadget` keeps pending/saved/displayed aim, camera adjustments and20 owned `BaseballProjectile` entries distinct from equipped raw mode. Cleanup hides its UI/restores the companion but retains the latch and flying balls. `SceneBaseballs` steps bodies before controller input and target frame state afterward; six duplicate 3TAR tags retain source-instance identities. The source body has an explicit ball profile for delayed landing impulse, prevent-lowering=false and reflection/friction. Sphere-pair discovery remains a declared bounded adapter. `BaseballVisuals` and `BaseballAimOverlay` append source Canv2/253 and TIME16-pixel glyphs using the existing world/overlay pipelines and uniform viewport. See baseball-implementation.md. Bubble adds separate `BubbleMotion` input/apply, `BubbleEffect` owned clock and `BubbleVisuals` original canvas. LabSimulation keeps body factor, current maximum, movement mode and captured sprite root distinct. The source static factory also admits VR01; its retained support ID feeds bounded `Vr01FloorState` before the controller, independently of current support/control. `PlayerAppearance` stores material writes from Invisible alpha/blend requests and late lava RGBA, preserving source phase order instead of rebuilding one effect's alpha every render. See gameplay/bubble-implementation.md for coverage and remaining gates. The Invisible continuation adds `InvisibleGadget` in Jimmy's post-movement wrapper phase, separate from input identity. `PlayerSceneBinding` supplies raw-any-control, handles equip/companion flags and receives a named-Jimmy cleanup event from CAM/ initial MCA, distinct from raw-owner preparation. `PlayerGadgetMaterial` changes the existing atlas draw; `InvisibleMeterOverlay` loads original Canv21/22 and uses shared uniform viewport scaling. `PlayerEnergy` is application-session owned across scene rebuilds, preserving scalar/warning latch separately from TSK. See gameplay/invisible-implementation.md for exact coverage and remaining gates. The first gadget slice separates UI display selection from the equipped raw mode. `GadgetScreen` owns group0 panel state/hit regions; `GadgetMenuOverlay` loads54 original canvases and applies shared uniform640×480 viewport/pointer transforms. Closing precedes the inventory selection event. Practice captures the existing departure context and requests the selected VR01..08 without a pickup prompt. The panel gates new gameplay SFX; full simulation pause is a declared port policy. `SceneGadgets` subscribes to the player's existing input phase and owns ray sound, energy, actual3SOL targets and score callbacks to `SceneInteractions`/TSK. `ShrinkRay` isolates strict source heading/height/distance/wall gates and texture clock; `OriginalHeading` implements the copied-DLL numeric references. `ShrinkSoldier` separates authored/reset AI mode from prior dynamic mode, shrink timer/marker and provisional NPC body support. `ShrinkSoldierVisuals` samples original WALK/SHRINK morphs with nonloop hold rather than scaling the mesh. `ShrinkRayVisuals` captures the effect root/yaw and three source textures. Generic draw opacity and opaque/alpha/additive variants support the recovered half-opacity ray. Blended-world depth writes disabled is an explicit renderer policy. See gameplay/gadgets-implementation.md for evidence and remaining gates. Original assets stay in `../Original`. Python tools parse undocumented original formats into generated scene resources under `artifacts/`. The modern application loads these original-derived resources and big endian GAM entity data. Portable asset resolution must handle Windows-authored case differences. Extraction must retain material references, world coordinates, per-corner UVs and animation data; triangulation/render-state approximations require explicit documentation. `Assets/GamLevel.cs` independently decodes original gameplay records and exposes player/startpoint/camera and other typed properties. Exact record bytes/unknown types remain accessible; do not normalize unknown flags into invented semantics. `tools/levels/gam.py` provides a lossless forensic reference and JSON export. Renderer design follows original fixed-function needs, without PBR or invented visual effects. A headless offscreen rendering path makes actual Vulkan image verification possible without a desktop; this is distinct from SDL presentation. Simulation implementation must follow recovered algorithms and timing. A generic fly camera or rendered model alone does not satisfy the playable-scene requirement. Collision continuation separates the recovered one-triangle47BD80 kernel (`OriginalSphereResponse`) from the live capsule adapter. Its explicit nearest state is caller-owned. `OriginalStaticCollision` composes source FIFO cell visits, retry and support-grid reduction. Its caller owns body integration, terminal callbacks and shared nearest/last-polygon reset timing. Prepared collision metadata retains signed material archive identities and an explicit completeness flag; source body callers must account for special contacts. Seven original dispatcher comparisons and ten original ordinary-body reference observations are in checkpoint/collision-body-probe.md. `OriginalBodyPhysics` composes that static path for ordinary Jimmy flags/contacts and is used in VR04; the live bridge supplies zero angular velocity, variable source radius60/100 and separate published160 speed. Lab/outside retain the capsule. Special callbacks, other original actor pair eligibility and shared dynamic reclipping remain gated. Source root and modern feet/sole rendering are distinct adapters; F3 exit still uses modern capsule occupancy. See checkpoint/collision-body-implementation.md. The source-root upward ray is supplied separately from the camera debug query: Jimmy's wrapper reflects upward velocity/cancels mode1 jump/fire before movement, including while uncontrolled. Fresh input precedes this wrapper; retained input follows Jimmy/fire. See checkpoint/collision-response.md and ceiling-wrapper.md. The completed foundation includes a single synchronous Vulkan renderer supporting offscreen and SDL surface presentation, an independent SDL WAV stream, bounded GAM/PNG/scene readers, and a retained-topology morph sampler. Prepared scene JSON avoids a Python runtime dependency in native packages. Mesh draw ranges omit null materials following the original renderer, while retaining their geometry. Default normal atlas and morph transforms are supported by binary/duplicate-asset evidence. `OriginalBodyPhysics` now retains current/previous Vec4, anchor and independent integration/support/collision/world-response/alternate modes. World callbacks see live state; fresh full-point equality controls candidate publication. Landing publishes floor root/anchor/acceleration before37C, then restores cached velocity and supported=true. Inactive paths preserve the prior per-body collision context. This is a bounded foundation for special callbacks, not automatic scene admission; see [body contact implementation](checkpoint/body-contact-implementation.md). `Game/LabSimulation` supplies the no-gadget walking/jump checkpoint, using recovered speed/yaw/impulse/airborne/camera formulas. `FixedStepClock` supplies a deliberate 60Hz port policy independent of rendering; original invocation cadence remains unverified. SDL events feed held keyboard/mouse state; focus/minimize clear input and pause simulation, while C pauses for inspection and R resets the start area. The Jimmy movement checkpoint uses `JimmyGroundMotion`/`JimmyAirMotion` for source input and velocity publication, `JimmyOrientation` in the base phase before control gating, and `JetpackBurst` for the controller/effect state tables. Keyboard-turn latch and destination Euler/dirty are retained independently of current Euler. Init clears the target/dirty while apply-owned air pitch seeds survive bounded route loads. Ground pressure requires a real source-body support polygon; the capsule does not manufacture one. JimmyRenderTransform now supplies the full Euler hierarchical basis, source degree quantization and a modern local sole correction around the logical root. Final OMT model decomposition remains a separate precision gate. See [movement stabilization](gameplay/jimmy-movement-stabilization.md). `SceneCollision` sweeps/slides a vertical capsule against retained original scene triangles, including invisible proxies, and clips the chase camera with a sphere sweep. Solver/masks/radius/pivot are explicit approximations. The physical position is feet; a separate original-root height feeds camera math and standing mesh minimum Y feeds visual placement. GAM/ASE data is preserved. SceneDirector supplies the separate task/trigger interpreter. Application/PreviewCharacterPlacement and PreviewAnimationLibrary keep inspection policies available alongside the walking checkpoint. Inspector ground contact is a model-only offset derived once from visible surfaces and the standing bind pose, with raw source placement preserved. Clip selection displays actual still/moving state and does not simulate walking/jumping actions. In walking mode, original idle/run/backpedal/ jump/fall clips follow simulation state. Looping, timing, transitions and the visual floor-derived pivot still require original comparison and further recovery. Subsystem implementation and validated ownership are documented in `infrastructure.md`, `analysis/graphics.md` and `rendering.md` as they become available. Persistent docs distinguish planned architecture from verified behavior. SceneDirector interprets original synchronous AI actions and CAM/MCA speech/camera sequences from mutable copies of GAM actors. PreparedEntityResources retains archive/type/id identities and PCM durations; SceneAudio independently streams music and speech. SceneActorVisuals and SceneSpriteVisuals append original morphs and source-sized Canv quads to a combined mesh. Shared draw visibility changes before synchronous rendering; vertex ranges remain independent after composition. SpriteSequence implements recovered per-call timing/stop/hide modes. Billboard orientation, some actor aliases, pivots and actual playback-end synchronization remain provisional. TaskStates and TaskActivation retain original case/sentinel/numeric gates. OriginalSave accounts for every TSK byte and preserves unknown data. SceneInteractions implements star/trophy/lab jetpack contacts, Carl dialogue dispatch and LOAD requests, tracking contact entry by source offset (duplicate tags remain distinct). Main owns a RenderSession across loads, replacing scene resources and per-level audio while preserving the window/Vulkan core and carrying task/items/score. Checkpoint CLI saves use atomic replacement outside asset directories; complete runtime saves, menus and configuration are not yet implemented. ActorPatrol implements the recovered common patrol phases and actor-specific profiles. OriginalScenePhysics uses recovered support/trace/magnitude and source wall-mask metadata, with a provisional modern wall solver. LabSimulation retains its provisional feet capsule, recovered normal root clearance75.9 and visual sole placement. DynamicSceneCollision builds source3DUD box triangles/broadphase; DynamicBodyResponse supplies the modern narrowphase. Keep these evidence boundaries explicit rather than presenting the complete original solver as recovered. SceneMechanisms consumes button contacts and explicit door toggle requests, maintains vertical-door movement/hold/reversal and emits sound/stop events. StaticSceneVisuals transforms original model actors into the final combined buffer, preserving source local bounds separately from visible material geometry. Collision uses source flags and transforms rather than draw visibility. JetpackBurst exposes controller/effect phases independently; LabSimulation currently orders controller -> collision -> effect at60Hz. Inventory slot0/3, current energy, level exceptions, effect radius and original FLY/fire morph consumers are connected. The complete original global object update order is unverified. SceneInteractions snapshots live energy, tasks, inventory, objective selector and RETURN strings. PracticePrompt implements source strict Yes/No regions and keyboard dispatch; Program pauses simulation while modal, clears held input and rebuilds VR04 on Yes. SceneHud appends source640x480 screen quads; the Vulkan overlay pipeline disables depth and draws after world geometry using identity transforms. Full HUD state and practice highlighting remain incomplete. UiViewport applies uniform art scale and explicit anchors; input maps logical coordinates into actual drawable pixels before inverse modal mapping. Prepared effects/effects.json preserves251 original SoundEffects.omt identities and RIFF payloads, including one MPEG-in-RIFF resource whose playback is unverified. PreparedEntityResources merges this explicit bank with per-scene named resources. SceneAudio mixes independent SDL streams for music/speech/one-shots and owner-keyed effect loops. Pickup and mechanism events are connected, including loop stop on bar movement completion/reset. Original positional/channel/volume policies and jetpack sound callbacks remain open; no online audio or services are used. Original CAM music stop and DEFAULT restart are director events subscribed by SceneAudio. Stopping disposes the loop and retains its selected resource identity; return starts the selected track again. Standalone speech streams do not decide music policy. Tests distinguish source CAM lifecycle from generic music/speech mixing and cover natural completion, reset and skip. AirSteering provides439900's normal airborne keyboard subset independently of walking input. Mode1 logs then falls through to its real handler; it is not a no-input state. LabSimulation preserves the turn-rate field, uses recovered air coasting/braking and applies the distinct ground/air lateral formulas. Mouse, analog, full lean/camera and original global phase order remain incomplete. MCA PlayerControlled is a completion target. Valid multi-camera shots clear active control; the player simulation is gated until completion/skip restores it. The normal grounded/released controller reset clears the air turn field before ground steering, preventing prior air turns from cancelling keyboard turns after landing. ObjectivePanel owns source elapsed time, entry/stationary/exit phases and O edge latching; SceneHud renders its pad and text/digit visibility independently. Practice hides the popup and No resets timing. UI clock remains explicit across control loss, focus/inspection and fixed simulation ticks. SceneProjection maps all35 original level geometry-layer far overrides instead of a universal3200. The merged renderer uses the larger layer limit; per-layer masks and dynamic LV4B fog/clipping remain open. RuntimeCheckpoint stages the departure root independently of pickup42AF00's checkpoint. LevelTransition retains RETURN identity after resolving its filename. Program captures the live root when a normal transition is requested, preserves it for RETURN, carries the pending flag only in memory and stores the root in TSK StoredVector. Destination initialization retains STRT yaw, restores Jimmy and Goddard position and suppresses the initial trigger once. Fresh TSK loading does not imply pending RETURN. Full actor-state/camera/fade restoration is separate. MeshPolygonSource obtains shape names from prepared mesh records. Its recovered NC-prefix terrain eligibility is consumed by SceneCollision and OriginalScenePhysics support/wall queries; rendering and raw source triangles remain unchanged. Other collision masks and the modern narrowphase remain explicit fidelity limits. DebugMenu is an intentional modern tool, separate from original UI/gameplay. Its staged selection emits commands into the existing task/inventory/director/ transition consumers. DebugMenuOverlay appends fixed glyph/batch ranges last; all composers still update the final mesh and the renderer uploads the changed vertices even in static inspection. F1 owns input before practice/gameplay, pauses simulation and all audio streams, resets the clock at both boundaries and retains captured keys until release. Audio streams created during pause inherit that state. SceneDirector keeps authored controlledTag separate from DebugForceControl. Effective control/tag queries expose Jimmy while forced; source shot assignments still update the authored tag. DEFAULT uses authored ownership for its music handoff. Disabling force reveals current script state; Begin clears the override. The debug flag is never serialized into original saves. DebugDiagnostics is session-owned timing/visibility state passed into each Run. It reads DebugStatus/DebugMotion snapshots and formats bounded live text; its wall-frame timer is independent of the simulation clock. F2 handles only its own key and never enters the menu's pause/input-reset boundary. F1 selects the full menu layout while open, otherwise the same overlay ranges display compact live diagnostics. The source viewport/projection decision supplies actual camera/far data. No debug visibility state is written into the original TSK wire format. RenderSession owns presentation until exit. Renderer replacement stages scene buffers/textures/descriptors, preserving device/surface/swapchain/layouts/pipelines and current targets. Resize/fullscreen replace size-dependent resources. Revision and native identities support checks. See presentation-and-ui.md for rollback, widescreen policy and runtime verification boundaries. ## Bounded ordinary-load character state PlayerLevelState is separate from OriginalSave: it carries only mode, jump-hold and owned-fire timer across proven LV1B/VR04/LEV1 no-gadget/jetpack transitions. Run reconstructs destination resources/body and applies these scalars before playback. Source jump state resets independently; TSK/debug checkpoint loads get no transient carry container. Source retained identity does not justify persisting all physics/AI/render fields. The detailed contract, phase limits and original component probe are in checkpoint/retained-player-body.md; companion/shadow resets and full availability tails have separate reports. Uncontrolled physics and exact appended-helper traversal remain next scheduler boundaries. ## Player control versus frame ownership PlayerSceneBinding connects authored preparation/transform events to the player adapter. Body integration and owned fire run without player control; only input and movement math are gated. CAM/MCA/AI preparation has distinct order and operates on the prior raw owner, while Force Control affects effective input. Ordinary frame/modal/debug pauses stop all these phases. Scripted AI roots/yaw flow into physics, and physical roots flow back to director/camera targets. Destination yaw and queued work are not cleared by a transform setter. The original full wrapper, registry, body response and morph clock are still not reconstructed by this bridge. See checkpoint/control-phase-implementation.md. REA tooling is separate from runtime architecture; setup/provenance are in rea.md. ## Owned aircraft Rocketship composes RocketFlight, RocketMotion, RocketOrientation and the source static-body/camera adapters in boundedVR02. PlayerSceneBinding schedules ship and Jimmy bodies before the fresh/retained input/normal boundary, transfers control to the registered3ROC and synchronizes the still-physical passenger afterward. Raw control and inventory permission remain distinct from named-Jimmy scripted cleanup. Release disables ship integration, stops engine/fire, retains rider root and shared eye, and returns Jimmy to FALL. Four dedicated source-pivot morphs replace the standing player draw while mounted. Source/probe/port validation and unresolved lifetime/pair/camera boundaries are in gameplay/rocketship-live.md. Grappler's distinct source ownership and geometry/material/swing contract is in gameplay/grappler.md; it is not a simple player movement mode or nearest-tag interaction. GrapplerMotion implements the isolated attachment/reel/damping arithmetic and independent fire/jump detach predicate, compared with30 copied-original cases. It owns no body/ray/camera/helper lifetime and is not called by live simulation; integration gates and retained source/REA findings are in gameplay/grappler-component.md. GrapplerGeometry adds source aim early-return/rope-constraint/post-base contact rules. GrapplerRay binds the verifiedVR08 static profile and captures selected polygon/material with the hit via OriginalCameraRay.TraceSelectedGeometry, which is independent of camera debug disabling. No live simulation calls these yet. The active-input return must gate later primary dispatch while normal Jimmy frame publication continues. Shared collision context/base contact and helper/camera ownership remain integration work; see gameplay/grappler-query.md. ## Live bounded VR08 Grappler (2026-11-04) The component-only gates described above are now integrated for VR08. Main owns GrapplerMemory across Run/scene reconstruction; LabSimulation owns the scene's GrapplerGadget and body/camera state. Normal physics retains its sphere context, then fresh controlled input runs camera followed by attached movement/aim/fire; ordinary player apply still runs after an input early return. Retained entry moves input after ordinary apply, preserving the existing registration boundary. Attached Move reuses the preceding physics context, including stale last polygon; support/ray metadata is separate. Both normal and attached wall callbacks reach the recovered post-base detach rule. No new body integrator or direct-pull path. Camera locals retain their source writers; GrapplerCamera consumes them through movement-mode-specific follow branches, obstruction and old shared-eye aim. GrapplerVisuals appends exact prepared rope/SWING/target resources and draws at source pivots. It applies the retained first-length scale to base rope geometry, uses pre-collision desired root and replaces the standing draw only during SWING. The existing generic sprite-facing bridge remains a documented rendering policy. PlayerSceneBinding handles selection, companion eligibility and authored cleanup. RETURN explicitly releases selected Jimmy before staging; ordinary scene teardown releases scene-local helpers/sound before SceneAudio disposal as a modern safety boundary. Scalar memory survives; original TSK serialization is not expanded. F3/R debug cleanup is separate from source ownership semantics. See [coverage and verification](gameplay/grappler-live.md) for113 component observations, 13 live managed groups, native replay and excluded shared/special-level behavior.