Files
Neutron/docs/analysis/lab-progression.md
T

219 lines
13 KiB
Markdown

# Original lab trigger and camera sequence
Static executable/GAM investigation, 2026-10-24. VAs are preferred-base
Neutron.exe addresses (these text offsets are VA-0x400000). Port runtime
verification is separate; no original gameplay comparison has succeeded.
## Recovered sequence
LV1B STRT STARTEXP at GAM0x5B0E starts LABEXP. AITrigger labexp at0x18FAD
selects labexp1 when SCENE30; original NewGame starts with SCENE30. Chain:
LABEXP1 -> SITGODDARD -> LABEXP2a -> LABEXP2 -> labexp2b -> LABEXP3A ->
LABEXP3 -> labexp3b -> GOCARL -> GOGODDARD -> WATCHGODDARD -> TELGODDARD ->
GODDARDDIS -> TELFX1OFF -> TELGODDARD2 -> end -> jimend -> default.
CAM/MCA nodes supply16 speech cues in this sequence. Speech end, not a guessed
fixed cutscene duration, advances the nodes.
STRT deferred dispatch0x4426A7 validates a C3DTriggerType target, then clears
player control through game slot0x118 before dispatch0x4426B7..C1. CAM activation
0x4165E2 PlayerControlled='none' preserves control, 'NULL' clears it, named existing
objects receive control. DEFAULT0x447CF0 restores Jimmy, enables inventory, and
clears the global skip flag at0x447F89. SCENE30 calls Jimmy help/inventory callback
0x42AB60; it does not unlock the exit or simply advance the task to60.
AI trigger actions0x40C300 execute synchronously: actor animation/state/speed,
patrol, hide/show, named-marker teleport, yaw; then conditional child selection
0x40C230 exact-matches current TaskName state to ActivateStateN and selects first
existing ActivateObjectN. 0x40C9BF/0x40CA26/58 dispatch child or NextTrigger.
SITGODDARD does not wait for SIT animation. GOGODDARD sets actor state3/speed260/
patrolGODDARDPAT1 and starts WATCHGODDARD immediately. Patrol movement is concurrent
and is now consumed by ActorPatrol with recovered support and provisional wall response.
## Camera formulas and timing
CAM0x415FC2 checks sound handle through0x47D890; finished sound deactivates target
animation then dispatches NextTrigger0x4160A4..E2. MCA0x430DD2 waits similarly,
advances to next non-none target, then finisher0x4311F0 dispatches NextTrigger.
Port uses exact prepared PCM sample duration for deterministic stepping; actual
hardware playback latency/end state is not yet matched to the original handle.
CAM0x4161CD..585: CameraType2 eye=authored camera position, look=target root.
Otherwise D=clamp(InitialDist-ZoomSpeed*t,MinDist,MaxDist). ViewFromCamera0 uses
eye=targetLocalToWorld(TargOffsetX,TargOffsetY,D), look=root+(0,LookVoffset,0).
Nonzero ViewFromCamera (including1/3) uses A=targetLocalToWorld(TargOffsetXYZ),
eye=A+normalize(cameraPosition-A)*D, look=A; LookVoffset unused in that branch.
MCA0x431027..11C1 resets per-shot elapsed time0x43190F. Local eyes:
|Type|Local eye|
|---|---|
|0|(0,40,200)|
|1|(0,140,max(100,300-15t))|
|2|(0,240,max(100,500-35t))|
|3|(200,240,max(100,700-55t))|
|4|(-200,190,max(100,700-55t))|
Transform eye by target Euler/root; look=root+(0,LookatVOffsetN-60,0), constant60
at0x49D5B4/handler0x43116A. Both handlers write exact eye/look via0x431670.
Port uses quantized modern trigonometry; x87 table/rotation-bit identity unverified.
CAM skip0x4160F1 and MCA0x430EED accept Escape/Space/controller/global flag, set
0x4F83E4, stop speech, preserve deactivation/actions and fast-forward the remaining
chain until DEFAULT. Port suppresses newly queued speech while skipping.
## Progression after intro
Teleport explanation AI special0x40CB43..6B changes SCENE30/31->35. Pickup special
0x4365D0..639 changes SCENE35->50 for shrinkray, with additional inventory effects.
Carl callback0x413E50..9D changes50->60,65->70,270->280 after base0x41B810.
The follow-up below recovers and implements the actual contact/talk dispatcher
and the internally named shrinkray jet pack checkpoint/inventory/practice/gadget effects. General AI sensing,
weapon behavior and all special pickups remain incomplete.
LOAD LABTONEIGH GAM0xA43 goes tolevel1.gam/startlevel1, SCENE60/radius200.
Underground LOAD0x8360 requires scene65, start riverlab. Binary0x457F32..7F5F:
none requiredtask bypasses; taskvalue-1 bypasses; otherwise >=RequiredLevel and
ExactLevel!=-1 additionally requires equality to that numeric ExactLevel.
Original LOAD contact uses the independent RequiredTask gate. Its interface+C8
vtable0x4D025C has task callback+0x424=0x458880, which only stores the supplied
TaskState at interface+0x494; it does not apply animated-entity activation rules.
Applying generic Animated.RequiredLevel to LABTONEIGH incorrectly disables it
because its TaskName is none while its RequiredTask is SCENE. The director now
leaves LOAD activation alone and SceneInteractions checks its real task gate.
## Implementation and remaining limits
Game/SceneDirector is bounded synchronous dispatch plus stateful CAM/MCA timing.
It preserves original GAM values, task gates, skip actions and reports unknown
classes/cycles/missing targets. Source-authored actor states are mutable copies.
Jimmy creates Goddard at0x423C98->0x41C810 (tag at0x41C88C); initial port position
uses gstart as a placement inference, then the authored SITGODDARD action positions
him before his first shot. Source visibility/collision masks are not fully ported.
Carl/Goddard rendering, speech/music and camera integration run in default lab play;
--story-time N gives a headless comparison point, --skip-intro executes skip actions.
Sprite/OMT props, common patrol, lab interactions and the practice modal are integrated.
Fades, complete collision/sensing, animation timing and full inventory remain incomplete. Model pivot/grounding remains provisional. Tests exercise original
sequence/control restoration, all five MCA formulas, CAM modes, task gates,
bounded cycles and actual decoded sound durations; GPU story12s render is verified
under Linux llvmpipe with zero validation errors. This does not prove original fidelity.
## Lab jet pack (internal tag SHRINKRAY) and Carl interaction follow-up
Read-only static source investigation plus managed regression execution. Original
source EXE SHA-256 is f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8.
Source GAM level1b SHA remains recorded in original-manifest.json. No original
binary was executed for this follow-up.
### Lab jet pack: ordinary collection and the exact special gate
GAM0x1799 is3PIC tagshrinkray, PickupIndex301, PointValue50, Radius125,
SoundIndex116, noPIC_NUMBER/RequiredPicNum/PickedUpIndex. Its generic contact
0x435CE0 accepts the active player, rejects an already acquired index, runs the
prerequisite virtual complete+0xD8, marks ordinary acquired state1 at0x435E11,
hides and disables contact. It invokes special hook0x4365D0 at0x435FCB before
positive score0x435FED.
The special hook compares ObjectTag to SHRINKRAY at0x4365D7..E7 (literal0x4F050C)
and SCENE exactly35 at0x4365ED..FD. Only that gate performs:
1. Active Jimmy complete+0x1E8 at0x43662C, resolved through complete vtable
0x4A3BDC to0x42AF00: capture current level code and physics root at complete
+0x1E48/+0x1E38. The port emits CheckpointCaptured(root); it does not guess
that this is TSK StoredVector or change a STRT checkpoint. Follow-up recovery
identifies StoredVector as the separate departure root at+9A8; see
runtime-checkpoint.md.
2. SCENE50 assignment0x436632..639.
3. Inventory setter0x4038C0(group0,item3,state1) at0x43663E..644.
4. Help/item-information page0 via0x406F90(0), call0x43664B.
5. Jimmy complete+0x174(3) at0x43667C..67E, resolved to0x428D50 gadget selection.
Collecting this tag outside SCENE35 still performs ordinary acquired/score behavior,
but does not receive these special side effects. The port preserves this boundary
rather than adding a minimum-level restriction. It emits HelpRequested(0) and
Inventory.GadgetSelected(3); presentation, modal pause and the jetpack motion/effect
consumer are separate integration work.
### Carl: entering talk precedes dialogue, rather than following its end
Carl interface is complete+0xC0, vtable0x495364; complete vtable0x495804.
InitObject0x413D60 sets radius100 through interface+0x110 at0x413E2F..36 and
support factor0.75 via+0x100 at0x413E3E..45. This supports a100-unit root
contact radius, not a model-sized capsule assumption.
Inherited contact-enter0x40A3C0 first handles base collision.0x40A44C..45C checks
that the contacted entity is the actor's resolved TargetName (complete+0x6C0,
interface+0x600; resolved at0x40948B..49A). If actor AIState6,
0x40A676..68D calls complete+0x124(0). C3DFriend update0x41B950 runs general
AI0x408000 first and, whenever resulting AIState0, calls complete+0x140 at
0x41B972..988. Carl's complete+0x140 is0x41B7B0.
That dispatcher obtains complete+0x17C=0x41BB20. This searches five TalkTriggerN
names in source order, requiring an existing target, TalkState!=-1 and either
exact actor TaskState or wildcard-2. It retains the selected object before any
task mutation. With a match, it invokes complete+0x180=0x413E50 FIRST, then
dispatches the chosen object's interface+0x5C with that object itself as caller
at0x41B7D3..D8. It increments the conversation counter, sets AIState9 at
0x41B7F0..F7, and invokes desired-facing hook+0x148=0x4093E0. Without a match,
it leaves state0 and retries on later updates without awarding points.
Carl0x413E50 calls base0x41B810 (+100 score, zero velocity through interface+0x410)
and then maps SCENE50->60,65->70 or270->280. Thus the normal lab route changes
to60 BEFORE starting neutron1a, and the exit may pass its gate while the dialogue
is running. The port does not award or advance on conversation end. General
state6 visibility/FOV sensing0x409CC0 and desired-facing smoothing are not yet
implemented by this contact subset; entering the recovered100+60 root-sphere
contact path is supported. Other friend classes do not reuse Carl's derived hook.
Carl TaskState override0x413F30 invokes generic activation, then LV1B branch
0x414068..118: SCENE outside0..60 deactivates;31..60 resolves CARLESC3 and sets
state6/position; states below60 activate;60 leaves generic activation unchanged.
This runs on every assignment, including repeated values. On scene initialization
or reset, call SceneInteractions.Reset AFTER SceneDirector.Begin to restore the
class callback and acquired-item visibility after actor reset.
### Inventory and objective persistence
SceneInventory preserves the19 signed TSK inventory values (9 group0,10 group1)
with owned arrays and bounded indices. Source0x4038C0 writes an item state at
group pointer0x4F8164[group]+40*item+0x24;0x403950 reads a signed short from
the same location. Unknown existing wire values remain unchanged unless the port
performs a recovered assignment. The separate29-item consumable group/counts are
not silently conflated with these two groups.
The TSK OtherCounter global0x4F8194 is now identified as the current objective
selector. SCENE setter0x45F990 uses byte/target jump tables0x45FC48/0x45FBF0 and
0x45FD98/0x45FD40 to call0x406F50(objective,1). That helper clears44 transient
flags at0x4F7D00, stores the selector0x4F8194 and sets flag[objective]=1. Relevant
lab milestones35/50/60 select1/2/3;65 does not replace the selector. The port
maps all44 supplied milestone states (including140/141 selecting8), exposes
CurrentObjective/ObjectiveChanged, and saves the selector in OtherCounter.
The objective timer/slide/O behavior and practice modal are integrated;
practice highlights and remaining objective consumers are separate work.
### Verification and boundaries
Run source scripts/env.sh, then dotnet run --project tests/GamePort.InteractionTests
-- ../Original. Managed checks cover the actual authored intro/skip/explanation,
task35->50 shrinkray with exact event order and+50, Carl task-position/contact/
talk with pre-dialogue60/+100, original LABTONEIGH destination, TSK write/reload,
no repeated acquisition or talk, outside35 behavior, first-existing/wildcard talk
selection, no-match/no-award, strict160 contact threshold, controlled-player gate,
inventory bounds/array ownership and every objective mapping against the original
EXE dispatch tables. Eleven exact instruction sequences support the decisive
call sites/constants. These are implementation/data checks, not original gameplay
comparison or native Windows validation.
Contacts now call OriginalBodySupport.QuickMagnitude, which translates the original
lookup algorithm with generated sine/acos tables; eight float-bit outputs now
match isolated original DLL probes. Full table bit identity, exclusion lists,
specialized contacts, body resolution and general AI sensing remain incomplete. Other special pickups remain reported unsupported.
## Corrected pickup identity and modal
The source tag SHRINKRAY is a prototype name. screens.omt Canv120 explicitly
says GET JET PACK; inventorygroup0/item3 also gates powered jumping. User-facing
notes must call this the lab jetpack.406F90(0) opens PracticeYesNo169 and pauses
the game; it is not a generic help page. Yes enters VR04/PHONEBOOTH with current
level/current STRT return context, while No resumes. See ui.md and jetpack.md.