Files
Neutron/docs/architecture.md
T

151 lines
9.6 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.
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 disposes
renderer/window/audio before rebuilding the next scene, 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. Fixed-size authored art
is scaled with the viewport; input uses matching logical-window coordinates.
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.