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

13 KiB

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/level1, SCENE60/radius200. The destination start tag is level1; the earlier startlevel1 spelling was a documentation error. Checkpoint helper re-reads the original GAM field directly. 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.