Files
Neutron/docs/gameplay/invisible.md
T

173 lines
10 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.
# Invisible gadget source contract
2026-11-01. Original item2/raw mode2. This report records static recovery and
bounded source projections; it does not claim original gameplay execution, port
integration or native platform verification. Original files were read only.
## Evidence and addresses
EXE SHA256 is `f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
`tools/binary/invisible.py ../Original` guards seven complete bounded spans,
50 decisive instruction slices, eight virtual bindings and six constants. Its
`artifacts/invisible/source-contract.json` records preferred VAs, PE-mapped file
offsets, bytes and hashes. All code addresses below map to file offset VA−400000;
the helper computes rather than assumes that mapping. Main source callers and
state fields are distinct from the display item index documented in
[gadget-controls.md](gadget-controls.md).
REA/Ghidra12.1.4 inspected a generated hashed EXE copy. Complete replies,
Evidence export and closed-session snapshot are retained in
`artifacts/invisible/rea-invisible-ipc/`:
| Procedure | REA Evidence |
| --- | --- |
|40E4A0 linked-model alpha/material setter|`ev_615030aa60b2346083853c40aa719ebc466e9f393fd870ea9722536a4f64cfac`|
|409CC0 generic enemy target predicate|`ev_1c4fe58878638158ea6f33db1474848910256873c00f266968debbf2ea35bf3f`|
|4037F0 meter size setter|`ev_525ca303ce70c16f524063053ebdd9fecd82054cf480d8f2f30f1ec0d7e08333`|
424E80 and427FF0 entry queries were unrecognized and returned input/mapping
errors; no pseudocode is attributed to them. Their bounded instructions, vtable
targets, branches and exact source identity supply the contracts below. The
earlier default-sandbox batch (`rea-update/`) failed Ghidra's Unix-socket bind;
its diagnostics and closed snapshot are retained, and `doctor.json` records the
diagnostic follow-up. Local IPC permission fixed that host restriction without
changing REA/client configuration or executing the target. Both sessions closed.
## State owners and update order — recovered
Jimmy complete-object vtable4A3BDC has1C8→424E80,178→427FF0,
FC→40DD40(indexed material blend) and114→40E4A0(all linked materials alpha).
Global signed WORD4F0588 is equipped mode. Menu display2 is separate.
| Jimmy complete field | Meaning established by this path |
| --- | --- |
|1E1C float|Remaining Invisible duration; constructor/equip zero, activation7|
|1E20 float|Recharge; constructor/equip/activation zero, ready exactly7|
|55D byte (=game-interface49D)|AI target visibility/eligibility flag; false while effect active|
|9F8 byte (=game-interface938)|Energy override; constructor false, PostLoad true for VR01..08|
|A18 pointer|Menu/UI owner|
|A1C pointer|Goddard/companion owner|
Jimmy game-interface frame424600 calls base movement437940 at424C34, then
complete slot1C8 at424C3F, then later complete1B4/1B0. Thus Invisible is a Jimmy
wrapper phase after movement, distinct from the controlled-input callback and
the ordinary ray's input phase. Existing full registry/fixed-step approximation
remains separate.
At424E80 a null controlled pointer5099E4 hides both meter sprites and returns,
freezing Invisible timers. Any nonnull controlled pointer passes; the leaf does
not compare it with Jimmy's identity. Mode!=2 then returns. Mode2 shows both
meter sprites before the remaining activation/timer branches. Menu modal/frame
eligibility can stop the enclosing frame before this leaf; do not treat this
as proof all menu/audio clocks follow this routine.
## Equip and activation — recovered
Selecting item2 reaches428E51 after the menu caller's close/old-gadget cleanup.
The display-selection callback already ran at428D97. With energy<=0 and9F8 false,
the branch writes raw mode−1 and skips companion/timer/target-flag/meter setup.
It still reaches Practice-state handling and may load VR03. Do not restore the
old special mode or normalize display2 into raw2 after a rejected equip.
With energy>0 or9F8 true, equip hides Goddard immediately through complete58(1),
sets Goddard gameD0(0) and214(false), writes raw mode2, zeroes both timers, sets
Jimmy55D=true and colors/shows the meter red. Goddard stays hidden for the entire
equipped mode, including recharge; this is not a shared fade with Jimmy.
Activation in424EBA..424F68 requires primary helper42A7A0 true and jump helper
42A730 false. If global4F8182 is true on that branch, the function returns before
either timer advances. Suppression does not freeze a call with primary false or
jump true. Otherwise activation requires remaining exactly0, recharge bits
exactly float7, and energy **strictly>2** or9F8 true. Failed energy at this ready
branch returns. Held primary has no separate edge latch here and can activate
again after another completed recharge.
Success calls42A920 with fixed delta−2, sets remaining7, writes indexed material0
blend6/1, applies alpha0.7 to all linked Jimmy materials, clears target flag55D
and resets recharge0. The same invocation then decrements remaining bydt. There
is no continuous Invisible energy drain, invented fire cooldown or activation
sound in this leaf. Shared42A920 may emit its own energy warnings; primary owns
that lifecycle. Ordinary jumps are allowed: mode2 is accepted in42A759; no
Invisible-specific pose, new model or forced grounded requirement appears here.
## Timers, meter and material — recovered
After activation attempt, only remaining==0 and(energy>0 or9F8) grows recharge
bydt. The meter receives recharge×stored-float(1/7)×100. At recharge>=7 the fill
is colored white, then recharge is clamped to exactly7. Reaching ready during
this call permits activation on the **next** invocation.
Independently, remaining>0 subtractsdt, writes meter percentage
max(remaining×stored-float(1/7)×100,0), then expires at remaining<=0. Expiry sets
remaining0, indexed blend6/7, alpha-reset argument0, target flagtrue and red meter.
It does not grow recharge in that call; recharge resumes on the next invocation.
If remaining is still positive and<=3, trunc(remaining×5)%2 selects indexed
material0 dest7 when odd, dest1 when even; source factor remains6. This is a
blend flash, not alpha on/off, uniform transparency ramp or mesh hiding.
40DD40(index,source,destination) writes the indexed material30/34 fields.
40E4A0(alpha>0) walks the linked model57C material array88..8C, writes diffuse
RGBA(1,1,1,alpha), enables blend flag38 bit0 and selects source6/dest1 when graphics
flag509A13 is false, dest7 when true. For alpha<=0 it clears the blend bit, restores
RGBA1 and6/7. Therefore expiry/cleanup mean opaque alpha1, not invisible alpha0.
6/1 is SrcAlpha/One additive,6/7 SrcAlpha/InvSrcAlpha conventional alpha per
[gadget-blending.md](gadget-blending.md). The graphics-option predicate remains
unclosed. An upright current-Jimmy renderer can use the existing material variants;
do not claim complete original material/LOD/depth-state equivalence.
Menu48D414 binds484→4036C0(show both),488→403700(hide both),
48C→403730(red fill(1,.2,.2,1), show),490→4037A0(white fill).
4037F0 sets fill width27×(windowWidth/640), height
max(percent,0)×1.04×(windowHeight/480). Source meter sprite pointers are
4F7CB0/4F8028. [Follow-up asset report](gadget-followup-assets.md) owns exact
Canv21/22 bindings/layout and modern uniform-widescreen adaptation. Arithmetic
uses x87 intermediates and float stores; exhaustive boundary equivalence is not
claimed by the Python projection.
## Cleanup, control and AI consumers — recovered boundaries
427FF0 dispatches the mode table428844; entry2 reaches42810C. It writes material0
blend6/7, remaining7 (not0), target flagtrue, recharge0 and hides both meter sprites.
If Goddard exists and its complete9E8 flag is false, it shows Goddard and re-enables
gameD0/214. It resets Jimmy alpha through114(0) and raw mode−1. Selecting Invisible
again resets both timers0. Source constructor4227BE/C7 also starts both0.
CAM and initial MCA can explicitly clean inventions. CAM constructor415C09/D5
defaults DeactivateInv to1 at complete9C0; property415F74 binds game-interface8F8
(interface offsetC8 proven415A60). Activation4165B7 checks the field before JIM1
lookup/cleanup178. MCA constructor430AA0 defaults completeEB8=1; property430D82
binds interfaceDF0 (offsetC8 at430930), activation43129A/CC checks then cleans.
Both use exact string `DeactivateInv` at4EDF10. Omitted GAM property therefore
keeps defaulttrue; an explicit0 can suppress that prelude. Ordered raw-owner438
preparation also calls cleanup178 at42AE14. AI-null40C4AD..527 calls410, STOP/
sound148 and clears raw control, but that inspected block does **not** call438/
178. Do not blanket-cancel Invisible on every control loss: timers can freeze
with the effect retained while raw control is null. Reset/ordinary-load behavior
must respect proven Init/PostLoad and callback boundaries, not one broad reset.
Generic enemy reads target game-interface49D at40847C,408788,4087FC to gate
chase/acquisition/lost-target branches. REA409CC0 confirms a target pointer is
required and the eligibility test permits49D=true **or** positive enemy934;
Invisible is not proof universal enemy immunity. Later enemy modes/reaction
consumers, attacks already underway and class-specific overrides remain open.
The port can retain the flag and report its state without claiming enemies avoid
Jimmy until the corresponding AI consumers are implemented.
## Verification and recommended bounded implementation
Nine deterministic Python groups pass in `artifacts/invisible/tests.log`:
source identity/spans/sites/vtables/constants, equip/activation threshold split,
first recharge/next-call activation, fixed cost/same-call decrement, jump and
suppressor/control gates, zero-energy clocks, blend flash/exact-zero expiry,
cleanup and source graphics branch. These are independently transcribed static
projections, not original execution or modern runtime verification.
Implement mode2 in the existing post-movement Jimmy wrapper phase with separate
raw-any-control and Jimmy-input ownership. Preserve exact timers/strict gates,
original material/meter resources, Goddard hide/restore and evidence-backed
cleanup points. Verify initial recharge, held activation, ordinary jump, last3s
blend flash, expiry/recharge, low-energy rejection, VR exemption, modal pause,
explicit/implicit cutscene cleanup and AI-null freeze. Keep full enemy AI,
original graphics-option choice, exact scheduler/x87 boundaries and native
Windows/original whole-game comparison explicitly unresolved.