Files

172 lines
10 KiB
Markdown
Raw Permalink 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.
# Bubble gadget source contract
2026-11-01. Recovered static contract for the next gadget; **no Bubble runtime
implementation or original-game execution is claimed by this investigation**.
Original EXE SHA-256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Preferred VAs below map to file offsets VA−400000 in the supplied text section;
`tools/binary/bubble.py` independently PE-maps and exports every retained site.
Output is `artifacts/bubble/source-contract.json`:12 bounded span hashes,37
instruction sites and6 virtual bindings. Originals were read only.
## REA evidence and scope
Two local REA/Ghidra sessions inspected the generated
`artifacts/uncontrolled-phases/rea/Neutron.exe` copy, exported complete Evidence
and closed/snapshotted under `artifacts/bubble/`.
| Procedure | Evidence / saved reply |
| --- | --- |
| Bubble constructor410840 | `ev_a0c9ee6d5757a741190f3dfcc093bdc7d7b802bcdcd2cbc029422550d34e7cb2`, `rea-effect/00.json` |
| Start410CA0 | `ev_097f43eb24a762785dd495220c26a8995d541c69de3e9a88d4c195e24a04b1ce`, `rea-effect/02.json` |
| Stop410D00 | `ev_d88f2e5a0b0b2ea4f47758084f3c2a6c605f18a1b8c7c4aa3b7cff0e9465b2e7`, `rea-effect/03.json` |
427FF0,4299B0,429A30 (`rea-core/`) and410AE0 (`rea-effect/01.json`) were not
recognized as procedures by the native profile. Numeric VA queries fell back to
unmapped file-offset errors; the complete diagnostics remain on disk. These are
not successful decompilations. Contracts below use reviewed fixed instruction
ranges/virtual bindings, supported by the successful constructor/start/stop
Evidence. No unchanged failed query was repeated. Supplementary objdump output
is retained as `equip.asm`, `cleanup.asm`, `class.asm`, `position.asm` and
`exe.asm`; source hashes and mapping keep this independently reviewable.
## Owners and layout — recovered
The [group0 menu](gadget-controls.md) names item0 **BUBBLE** and maps its practice
to VR01. Global signed WORD4F0588 is equipped raw mode; source movement mode is
a separate WORD at Jimmy complete7C4/interface704. The Bubble is owned at Jimmy
completeA14/interface954. Constructor42232C calls410840, stores the result42233C
and initially hides it at42236E. It is not a free-moving projectile or Jimmy's
physical body.
Bubble complete vtable492970; game interface is complete+C8 with table49250C.
Game slot3C4 binds410AE0 update; generic1C binds464130. Constructor4108F7 registers
FourCC `3BUB`; class name is `C3DBUBBLE`. Constructor4352F0 supplies the sprite
base. Own body integration/triangle collision is disabled through471030(0) and
4710C0(0); Jimmy's body instead changes radius/factor when equipped.
| Bubble complete field | Purpose established here |
| --- | --- |
|90..9C|RGBA sprite color; expanding/collapsing writes all four components|
|AC/B0|Sprite width/height; initially200/200 via4645F0(200)|
|B4/B8|Source/destination blend enums6 /1 or7|
|57C|Integer base pulse size240, initialized410935|
|584|Copied archive name `RetainedSprites.omt`|
|5E8|Loaded original canvas resource; constructor477890(archive,1)|
|600|Float visual timer, incremented each effect update|
|604|Float pulse `sin(timer*10)*30` while active|
|610|Float fade scalar|
|614/615/616|Active / expanding / collapsing flags respectively|
The retained resource is Canv1 of RetainedSprites.omt, not an ASE sphere. Exact
archive/pixels/tutorial inventory is independently documented by the asset
investigator. The sprite's full camera-facing transform remains a rendering
adapter dependency; the ellipse/pulse does not justify inventing sphere geometry.
## Equip and cleanup — recovered
Complete Jimmy174→428D50 dispatches item0 to428F61. The common menu caller closes
and invokes cleanup178 first; arbitrary calls to174 without that caller are not
equivalent. Bubble branch order:
1. Require the owned Bubble pointer. If absent, return without a new effect.
2. If runtime Practice state(0,9)==2, reset that state and load `vr01.gam` at
428FCA using existing return strings. This precedes energy and visual-state tests.
3. At428FDA require energy4F83D4>0 or Jimmy complete9F8 nonzero. The latter is
retained here as an unnamed exemption flag; its complete ownership is open.
Failure writes raw mode−1 at428FFA and returns.
4. Reject Bubble active614, collapsing616 or expanding615 before starting another
transition. These flags are not a generic cooldown invented by the port.
5. At429049/429058 invoke game110/100 for **radius160/factor0.415**; write raw mode0
at429065, movement mode2 at429072 and max controller speed1350 at42907B.
6. Call410CA0 at429085. Start sets expanding615, timer600=0, unhides the sprite
if necessary and chooses blend6/1 (additive) or6/7 (conventional alpha) from
graphics flag509A13. It does not clear other transition flags itself.
7. Start loop SFX2 at429093..4290A1 only if Jimmy completeA40 handle is−1, then
animation refresh148. Source animation selection also depends on movement/body.
Cleanup178→427FF0 dispatches raw mode0 to428037. With the owned Bubble it sets
Jimmy A20=0.5, movement mode0, **max controller speed650**, calls410D00 to begin
collapse, then **separately clears expanding615** at42806B. It stops the A40 loop
and resets handle−1; invokes radius60/factor1.265; writes raw mode−1 at4280BB.
The source's explicit650 cleanup value must not silently be replaced by the
constructor's600 or by generic authored-state restoration. The A20 consumer is
not closed here. Missing-pointer cleanup falls to the shared raw−1 tail without
these body/effect changes. Cleanup also restores selected-device HUD3 via the
common prelude. It does not directly transfer raw controlled-pointer ownership.
## Active input, movement and interactions — recovered boundary
426030's input callback retains its existing global/game/control predicates.
Within it426264 tests **movement mode2**, not raw mode0, then426272..426280 calls
42A920 with `−0.5*dt`. The common energy helper owns VR exemption, clamp and warning
sounds; no duplicate exemption is implied by the Bubble branch. After adjustment,
426285..42629F invokes cleanup178 if energy<=0. Consequently controlled Bubble
input drains0.5 energy/second outside exempt tutorial handling. Loss of input
ownership can stop this branch while the independently registered effect still
updates. This is not permission to pause every clock on raw-control loss.
The same branch positions the sprite using current camera eye509A50+44..4C:
`direction=normalize(JimmyRoot+(0,100,0)−eye)`;
`BubbleRoot=JimmyRoot+(0,50,0)−direction*80` (4262A5..4263DA).
This is camera-relative and differs from simply drawing a sphere centered at
JimmyRoot. Zero-length normalization/imported-vector rounding remains open.
Generic input438B1E..438B98 maps movement modes1 **and2** to shared439900, while
mode0 maps438BC0 and3 maps43A120. The prior air-steering recovery of439900 is useful,
but does not close Bubble's complete jumping/body/mode transition behavior.
Supported Jimmy wrapper4246A9..4246E3 explicitly restores live radius160/raw mode0
or60 otherwise, before the later movement/fire phases. A live Bubble integration
must preserve source authored/live radii and movementmode2, including support.
Ordinary primary fire4266AC rejects raw mode0 before controller-speed-zero,
SHOOT and the ray scan. Jetpack dispatch also skips raw mode0 at4260D3. Bubble
must not keep the ordinary beam or powered-jump path active merely because item3
is owned. Other generic movement/jump paths still need caller-complete recovery.
Source callbacks42A870 and42A8D0 return early for raw mode0 before their energy/
score/flash effects, and42AB0E skips an additional SFX190. Their complete callers/
meaning are not traced here; this establishes specific bypasses, **not** universal
invulnerability against every hazard, actor or script.
## Sprite transitions — recovered, with numeric projection limits
410AE0 first increments float timer600 bydt, then processes flags in priority
order active614, expanding615, collapsing616:
- **Active:** pulse=sin(timer*10)*30; width=(float)integer57C=240 and height=240+pulse.
If509A13 is true, RGBA becomes(1,1,1,0.5); otherwise existing RGBA is retained.
This does not geometrically scale Jimmy or the sprite during fade.
- **Expanding:** scalar610=timer; strictly `timer>double1` clamps scalar1, sets
active614 and clears expanding615. RGBA=(scalar,scalar,scalar,scalar).
At exactly1 it remains expanding until a later update.
- **Collapsing:** scalar610=1−timer; strictly scalar<0 clamps0, clears collapsing616
and hides the sprite. RGBA=(scalar,scalar,scalar,scalar). Exactly0 retains collapse
until a later update. Stop410D00 sets collapsing616, clears active614 and timer0;
Jimmy cleanup must additionally clear expanding615 or expansion retains priority.
The Python projection retains these state/strict-boundary distinctions and
single-precision stored values. It does not claim x87 intermediate/fsin bit parity
or original runtime observations. Blending both RGB and alpha during fade can
change perceived brightness; replacing it with alpha-only is a behavior change.
## Validation, current implementation and next action
Six Python source-contract groups pass in `artifacts/bubble/tests.log`: original
identity/span/site/virtual guards and offsets, equip order/flags, movement2 drain,
strict expand boundary/color without size scaling, active pulse/graphics alpha,
and cleanup priority/strict-negative collapse. This is static/source-projection
validation, not native Bubble gameplay or an original game capture.
The port's group0 selection/practice already exposes Bubble, but **this agent made
no runtime changes**. Raw mode0 radius160 is a named future case; the existing
ordinary static Jimmy body subset must not be advertised as complete Bubble
physics. Recommended next coherent implementation: retain an owned sprite with
original Canv1, source transition flags and camera-relative placement; integrate
source radius/factor/maxspeed/movement2/ordinary-fire cancellation together,
including source cleanup650, controlled−0.5dt and independent visual clock.
First recover the generic mode2 jump/body transitions and actual VR01 support/
collision class coverage, then test equip→expand→move/jump→empty/Tab cleanup→fade
and tutorial/RETURN persistence. Full hazard/AI immunity and renderer orientation
remain explicit gates. Invisible is the primary's selected next playable slice;
this Bubble contract is ready for that later chunk without speculative physics.