Files
Neutron/docs/gameplay/gadget-controls.md
T

8.4 KiB
Raw Blame History

Gadget selection and control contracts

2026-10-27. Original EXE SHA256 f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8. Preferred VAs below have PE-mapped offsets in artifacts/gadget-controls/source-contract.json. Tools guard the whole identity, nine bounded source spans,40 instruction slices and10 virtual targets. Text offsets equal VA−400000 for the supplied EXE. This is static recovery, not an original gameplay capture or proof that every gadget is implemented in the port.

REA evidence and limitations

Own generated-copy REA/Ghidra sessions are exported and closed in artifacts/gadget-controls/rea-core/, rea-panel/ and rea-hit/.

Procedure Evidence
405FB0 display selection ev_b740d70cfab21827d697151221a5cbcc0294c5d4b5742a2d3b94b10e62a08e1c
406590 selected HUD collapse ev_c792af0532d5a11ecb3a602d31e3179a95b0c4b9e5242fbfe8390558b3a5c55a
406650 selected HUD expand ev_dc23fb856bd21025fbfb4fb2389fae63431659f914d37475014d00dcc461fb6d
425870 menu-key dispatcher ev_c2c664c7632af150fb70ecb3aaa13d8fb46c5493210a0c9af0b54a274f656ec2
403A20 menu group setter ev_823efd8fa897c27a672c43a5e1859b0a4dbc8ba866593b6ab4e5db7d03b58944
404DE0 group/resource initialization ev_bfded79da490ec9bc615e403ba00f4a006fe37d0f88b69fbf3a92ce433df17dc

Queries404080,428D50,425B20,425EF0,403C50,403700,427370,403A30 and402F60 did not return pseudocode. Complete provider errors are retained; several say the numeric input was interpreted as an unmapped file offset after no procedure match. No successful pseudocode is attributed to those queries. Their contracts below use reviewed instructions and fixed identity/span/virtual guards. No unchanged failed calls were repeated. No original code was executed by this task.

Owners and open/close transitions

Jimmy complete-object table4A3BDC maps184→425870 menu-key input, 1AC→427370 panel interaction,1F8→425EF0 open,1FC→425B20 close, 174→428D50 gadget selection.188 is429D00, not panel interaction. Menu object is Jimmy complete+A18; global4F8181 is panel-open. Menu4D4 is group, 4C8 accepted item,4D8 selected HUD/display item. Global signed WORD4F0588 is a different equipped movement/gadget mode. Menu display4D8 initializes3 at401F93; Jimmy equipped mode initializes−1 at42225F.

425870 reads Tab at509841 and Space509858 (keyboard array509838+virtual-key), plus controller509AC6. Shared edge latch Jimmy+1E00 suppresses repeats. With an open panel,425AA6 calls close1FC. With panel closed and equipped mode!=-1, 425ABC calls cleanup178, writes mode−1, resets menu selection state and returns. Only no-selection invokes open1F8(0) at425ADB..AF1. Thus equipped special gadget requires one Tab to unequip and another to open; Tab is not a universal toggle. The dispatcher also gates menu pointer, an elapsed/action field1E6C and competing keys. Raw ownership/caller scheduling must remain distinct from this leaf branch.

Open425EF0 requires gameplay-enable4EC494 and closed panel. It collapses HUD, sets group through menu4AC, invokes game168(1), marks panel-open, shows cursor for groups except2 and disables Jimmy integration through interface214(false). It also calls47D850 and clears sound-default gate4F8434. Close425B20 reverses panel/game pause, cursor, integration and sound gate; root group0/previous-menu−1 Return simply closes. Source214 is body-enable, not raw controlled-pointer118. Global control remains available to drive panel input while physics is disabled. Full actor/fire/morph/music/software-clock pause ownership is not closed here; pausing all port simulation is a broader declared policy, not this leaf proof.

Escape uses VK_ESCAPE509853 in425870 then complete1F0→42AB60. When panel is open,42AB76 invokes close1FC and returns; it does not quit the application. When closed it opens the separate main-menu group3, outside this gadget subset.

Original group0 layout and rendering

404E97..404F8B constructs the eight gadget buttons in inventory-index order. Their141×141 rectangles use strict interior comparisons in403A30:

Item / original tile text Top-left Idle / hover canvases
0 BUBBLE (12,182) 52 /11
1 ROCKET SHIP (158,182) 46 /12
2 INVISIBLE (12,327) 47 /13
3 SHRINK RAY (157,327) 48 /14
4 SCOOTER (342,182) 49 /15
5 REMOTE (487,182) 50 /16
6 BASEBALL (342,327) 51 /17
7 GRAPPLER (487,327) 45 /18

Canv20 is the640×480 base and already contains grey/unowned tiles. For current route state1,402F60 creates both b/white and normal/green sprites.403A30 hides green outside hover and shows it inside, leaving white idle. State0 and4 hide both, exposing the base grey tile. Blue c assets are not bound by this group0 constructor; do not use them as an invented unavailable-state overlay. Hit filtering skips state0/4 and missing green sprite, not every state!=1. State3 can hit but forcibly hides green; state2/3 initial render visibility is inherited (the initializer has no explicit show/hide branch for them). Do not claim complete raw-state2/3 rendering from state1 behavior. Unknown states should remain raw values, not be normalized into owned/available booleans.

403A30 scans29 entries in40-byte steps and returns the last overlapping eligible hit. The state is menu-base+item*40+24; source sprite positions/dimensions determine the hit rectangle. Boundaries x==left/right and y==top/bottom do not hit.

Return slot10 uses canvases182/181 at(12,95),141×78. Practice slot9 uses180/179 at(487,95),141×78. Jimmy construction4223BE..CD initializes both raw states1; these runtime-only slots are outside the nine group0 entries serialized by TSK. Slot8 is the separate backpack/inventory function, not a ninth ordinary gadget.

Activation, practice and the combined default device

427370 samples the pointer and calls menu4A4→403A30. Primary activation includes 42A7A0 (left mouse, Enter, Ctrl, controller; a separate global suppressor can veto), 42A730 jump-input helper, and Enter polling46A3E0(13). It stores the accepted item through menu478. Jimmy+1E25 is an action latch; releasing all accepted controls clears it. This is source pointer selection; arrows/analog steer the OS pointer in404080 using accumulated offsets±80*dt, not direct tile focus cycling.

For group0 gadget activation,4278D7 closes the panel, calls cleanup178, passes menu4C8 to gadget174 and then re-enables body integration. Requested item3 and−1 share428DE0. That branch does not set global4F0588 to3: UI highlight becomes3, while the normal equipped mode after cleanup remains−1. Ownership(0,3), HUD highlight3, source mode−1 and the primary/jetpack action state are independent. This agrees with the primary-fire investigation's default device path. The tile name SHRINK RAY is authoritative art; its description113 includes both SHRINK and JUMP/JETPACK actions. The old lab tag/internal-name explanation was too broad if interpreted to mean no shrink-ray weapon exists.

Practice click427773..427802 toggles runtime group0/item9 between2(armed) and3, rejecting SCENE>=500 and all VR01..08 levels. Item9 initially1 is also unarmed. Choosing a gadget while armed invokes its direct tutorial LOAD, not Yes/No modal. Bounded pushes/string offsets in the helper verify item0..7→vr01..08.gam. Item3 loads vr04.gam/PHONEBOOTH with authored return strings. The174 branch changes item9 from2 to1 before loading; menu caller427903 subsequently writes3 when it continues. The helper's default_device_selection models that174 branch, not the entire caller's final state. Returning via slot10 also disarms practice to3.

Description records4F7EF0 stride24 map item0..7 to canvases 109,115,111,113,116,114,118,110.405FB0 and406590/6650 connect them to selected-gadget HUD layout. No panel-hover description caller is proven; displaying BmenuL as full-panel hover text would be a new policy. Viewport scaling/cursor placement in the modern port remains separate from the original stretched640×480 coordinates.

Verification and remaining scope

Seven Python groups pass in artifacts/gadget-controls/tests.log: original identity, span/site/virtual guards; Tab states/latch; exact tile interiors and boundaries; raw state filtering; highlight/equipped distinction; practice toggle gates; all eight guarded tutorial destinations and initial runtime button states. The functions are explicit source projections, not original execution or port UI runtime verification. Primary owns integration, tests, widescreen policy and unsupported gadget effects; this investigator changed only the three owned files.