Files
Neutron/docs/architecture.md
T

221 lines
14 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.
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 as an isolated component. 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. Live body composition,
special callbacks and dynamic reclipping remain gated.
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.
`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.
`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.