364 lines
24 KiB
Markdown
364 lines
24 KiB
Markdown
# 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.
|
||
`OriginalPairCollision` now expresses47A430's ordered physical-list pass and
|
||
47B3E0's sphere/exclusion query. It takes live actor callbacks and an explicit
|
||
mode2 solver, and preserves contacts when eligibility skips a pair.28 complete
|
||
original-component comparisons support it. It is not connected to the grouped
|
||
SceneInteractions loop: full registration/activation, real actor responses and
|
||
shared dynamic reclip state remain prerequisites. See checkpoint/pair-lifecycle.md.
|
||
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.
|