Files
Neutron/docs/architecture.md
T

358 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.