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

144 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.