144 lines
8.4 KiB
Markdown
144 lines
8.4 KiB
Markdown
# 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.
|