Implement original gadget panel and playable shrink ray

This commit is contained in:
UnixNight committed 2026-10-27 12:18:45 -04:00
1 parent 0272f7bef7
commit 7b5230ceb8
57 files changed
+3545 -48

No files matched your search

+134
View File
@@ -0,0 +1,134 @@
# Gadget resource inventory
2026-10-27. Read-only asset investigation; no original file was modified or
executed. This report describes serialized resources and inspected pixels.
It does not infer gadget timing, collision, selection policy or model attachment
from filenames. Binary/input contracts belong in [gadget-controls.md](gadget-controls.md).
## Selection screen and original labels
All following Canv IDs are from Original/omt/screens.omt, SHA256
`e8e95231f5d302b41f4fbf33df1c5a08ce4645370f9f519527ff1727b73b7a5e`.
Canvas20 (`menu`) is640×480 and already contains the dim gadget tiles and Return/
Practice labels. Unsuffixed, suffix-b and suffix-c tile art are141×141. Their inspected
appearances are green, white and blue respectively; which state selects a variant
must come from the dispatcher, not the colour. The independent controls investigation
reports constructor404E97..404F8B's inventory0..7-to-tile association; the displayed
labels below are independently visible in the original pixels.
| Group0 item | Original tile label | Unsuffixed / b / c Canv | HUD Canv/name | Control strip |
|---:|---|---|---|---|
|0|BUBBLE|11 /52 /178|94 `1bubble`|109 `BmenuLBubble`|
|1|ROCKETSHIP|12 /46 /171|87 `2rocket`|115 `BmenuLRocketship`|
|2|INVISIBLE|13 /47 /172|88 `3invisible`|111 `BmenuLInvisible`|
|3|SHRINK RAY|14 /48 /173|89 `4raygun`|113 `BmenuLRayGun`|
|4|SCOOTER|15 /49 /174|90 `5scooter`|116 `BmenuLScooter`|
|5|REMOTE|16 /50 /175|91 `6remote`|114 `BmenuLRemote`|
|6|BASEBALL|17 /51 /176|92 `7baseball`|118 `BmenuLBaseball`|
|7|GRAPPLER|18 /45 /177|93 `8grappler`|110 `BmenuLGrappler`|
Do not rename tile3 to Jetpack. The separate jetpack HUD canvas119 is named
`9jetpack`, and control strip112 is `BmenuLJetPack`; strip113 visibly describes
both SHRINK firing and JUMP/JETPACK. This agrees with the port's recovered
item3-powered-jump association, but the art itself does not establish firing logic.
The rendered selection background places bubble/rocket/scooter/remote across its
first row and invisible/shrink/baseball/grappler across its second. Exact hit
rectangles and hover/selected state are source-controller evidence, separate
from this visual layout observation.
The controls investigator specifically recovers white suffix-b as owned idle and
green unsuffixed as mouseover; group0 state0/4 hide both to expose the dim background.
The blue suffix-c resources are available assets but are not part of those current
group0 bindings. Their existence does not justify inventing an unavailable overlay.
Other useful screens.omt resources:
| IDs / names | Dimensions | Asset role |
|---|---|---|
|109..116 plus118 `BmenuL*`|393×69|Nine left-side gadget control strips.|
|108 `BmenuR2`,117 `BmenuR1`|247×69|Right-side instructions with SELECT/DESELECT INVENTIONS text.|
|24/181/182 `return`/`return2`/`return3`|141×78|Return button variants.|
|170/179/180 `practice`/`practice2`/`practice3`|141×78|Practice button variants.|
|87..94 plus119|80×70|Eight gadget HUD icons and separate jetpack icon.|
|84/85 `backpack`/`backpack2`|141×141|Backpack variants.|
|253 `CrossHairs`|15×210|Vertical strip;14 square15×15 frames arithmetically fit. Frame meaning/timing is not inferred.|
## Export and integration
tools/extractors/gadget_resources.py exports54 exact decoded canvases into a
separate directory. It checks original IDs/names/dimensions before writing, uses
the existing bounded OMT/RGB555/colour-key decoder, preserves alpha and records
archive/payload/RGBA SHA256 plus source offsets/sizes. It protects the entire
source asset root, including sibling ASE/png/gam directories when the archive is
under omt/. No image generation or replacement art is used.
```
python3 tools/extractors/gadget_resources.py ../Original/omt/screens.omt --output artifacts/extracted/gadgets
```
The generated gadgets.json uses schema1, referenceWidth640/referenceHeight480 and
textures with id/name/role/width/height/path/png/sourceOffset/sourceBytes/
sourceSha256/rgbaSha256. File paths are local `canvas_ID.rgba` and `.png`.
`tiles` records artItem1..8, literal labels and normal/b/c IDs; suffix roles remain
neutral so the source controller owns availability/highlight interpretation.
This separate manifest leaves the existing eight HUD/practice resources unchanged.
Primary owns prepare.py/package/runtime integration; this investigator did not
edit those files. Runtime should reuse UiViewport scaling and pointer conversion.
Generated inspection images are in artifacts/gadget-assets/: selection-sheet.png
and canvas_20.png. ase-inventory.json records exact hashes/counts for the model
files below. The fixture exporter wrote artifacts/extracted/gadgets/gadgets.json.
Three regression groups pass in artifacts/gadget-assets/tests.log: exact original
resource/pixel/dimension round-trip, rejection of all original asset subtrees, and
rejecting changed dimensions before producing partial output.
## Shipped model and animation candidates
These are file/content observations, not proof that a given runtime action uses
every candidate. The ASE parser maps original coordinates using the existing
verified `(x,z,y)` conversion. Jimmy clips share426 vertices/814 faces with the
prepared standing mesh, so existing morph preparation can preserve its topology.
| Source ASE | Samples / fps | Geometry and bounded use |
|---|---|---|
|jimshoot.ASE|2 /10|426 vertices/814 faces; original shooting pose candidate. Not in current default prepared animation list.|
|jimfly.ASE|2 /10|426/814; already prepared for powered jumping.|
|jimswing.ASE|2 /10|426/814; swing pose candidate.|
|jimscooter.ASE, jimscooterstop.ASE|2 each /10|426/814; scooter poses.|
|jimdrive.ASE|2 /10|426/814; driving pose.|
|jimheadshrink.ASE|7 /5|426/814; distinct authored morph sequence, not an inferred uniform scale.|
|godscooter.ASE, godscooter2.ASE|2 each /30|195 vertices/370 faces; reference `goddard02.png`.|
|godrocket.ASE|3 /5|222 vertices/411 faces; rocket-form candidate.|
|ray.ASE|2 /10|5 vertices/3 faces. Material text references `ray0002.ifl`; supplied PNGs ray0000..ray0003 exist. Sequence binding/cadence remains source work.|
|hook.ASE|1 /10|40 vertices/68 faces; material references hook.bmp, supplied hook.png exists.|
|rope01.ASE,rope02.ASE|1 each /30|6 vertices/6 faces and4 vertices/2 faces.|
|laser02.ASE,missile.ASE|1 each /30|8 vertices/8 faces and7 vertices/10 faces; missile's goo.bmp reference is not a verified gadget attachment.|
scooter.omt contains shape0 `goddard01`, shape1 `wheel`, matching material/canvas
resources0 `goddard128` and1 `scooterwheel2`; archive SHA256
`8d4ffdafee5fd819c5220ee4f608c901a5988fe6b8b13316e15618f5eec75e81`.
inventory.omt is an older-looking icon set with BUBBLE/GODJEEP/SCOOTER/jetpack etc;
its names alone do not justify replacing screens.omt menu art or IDs.
No explicit bubble-named ASE exists in the supplied directory; that bounded
filename search does not prove the original bubble geometry was absent/generated.
## Already prepared sounds
artifacts/extracted/effects/effects.json already preserves original SoundEffects.omt
waves, paths and source byte ranges. Bank SHA256 is
`c71e06d93b8a5ef4f4522a5c40220bc8aeaecb889b5de69445db44817fb9acb1`.
Useful identities are0 `shrinkray`,1 `jetpack`,2 `gravitybubble`,3 `gravitybubbleoff`,
10 `goddard baseballs`,18 `pickupbaseball`,45 `rocketship`,46 `Scooter`,106
`bubble boing` and117 `click shrink ray`. These are archive identity/name facts;
actual activation, repeat, ownership, volume and cancellation still need callers.
The existing resource export is sufficient; no duplicate sound extraction is needed.
## Practical next addition and limits
Original selection art and control labels are complete enough to implement a
source-driven gadget screen without invented icons. For a usable gadget beyond
the current powered jump, shrink firing has original pose, beam geometry/PNG frames
and both successful-fire/click sounds available; it still needs recovered target,
range, timing, energy and interruption policy. The selection3 naming overlap is
an explicit reason to implement the combined shrink/jetpack controls coherently.
Other gadget assets are candidates for later behavior recovery, not evidence that
all eight gadget behaviors are currently implemented.
+83
View File
@@ -0,0 +1,83 @@
# Gadget material opacity and blending
Implemented 2026-10-27. Scope: Vulkan support needed by the recovered shrink-ray
effect. This is a renderer capability, not a claim of complete original material
or fixed-function rendering fidelity.
## Recovered facts
[Shrink-ray investigation](shrink-ray.md) records the underlying REA evidence.
Original EXE SHA256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Original engine DLL SHA256:
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
| Original location | Fact and dependency |
| --- | --- |
| EXE VA40E4A0 / raw0E4A0, complete-object virtual offset114 | Positive opacity walks shape polygons and nonnull materials; writes material RGB1, alpha=parameter at +4C..58, source blend enum6 at +30, destination enum7 or1 at +34, and sets flag38 bit0. It does not multiply a previous alpha or scale geometry. |
| EXE VA440000 / raw40000, Init; VA440180 / raw40180, update | Effect initialization and texture changes invoke that setter with0.5. The material opacity applies to all three animated ray textures. |
| EXE global509A13; store VA476BBE / raw76BBE | False selects destination enum1; true selects enum7. Store comes from graphics setup. Complete hardware/settings fallback semantics remain unresolved. |
| DLL VA10036AB0 / raw36AB0; table VA1013667C / raw13667C | Adapter maps blend enums to Direct3D states19/20. Enum6→SRC_ALPHA, enum1→ONE, enum7→INV_SRC_ALPHA. False global therefore means additive SrcAlpha/One; true means conventional SrcAlpha/OneMinusSrcAlpha. |
The DLL REA evidence is
`ev_f5a914ee9eae593b02a04149b6651b2d783151df046bbb417624bf94f23bb96c`,
closed/exported in `artifacts/shrink-ray/rea-blend/00.json`. The parent report
links retained EXE evidence and byte-guard utility. No originals were modified
or executed for this implementation.
## Implementation and explicit policies
`MeshDraw.Opacity` defaults to1; `MeshDraw.Blend` defaults to `MeshBlend.Opaque`.
The other modes are `Alpha` and `Additive`, using exactly the source/destination
factors above for both RGB and alpha. The caller chooses the mode; opacity alone
does not enable blending. The source effect should use opacity0.5 with its chosen
graphics branch. Texture alpha is not pre-halved.
The fragment shader retains the existing texture-alpha cutout test (<0.5) and
then multiplies texture alpha by material opacity. Keeping this test and threshold
is existing port behavior; source alpha-test interaction is still unverified.
The push constant is float opacity at byte64 after the existing64-byte transform;
the68-byte range covers vertex and fragment stages. The vertex shader is
unchanged. Opaque world and opaque UI blend/depth pipeline states are unchanged.
Blended world draws test opaque depth without writing depth. This is an explicit
modern implementation policy: original shrink-ray depth-write state has not been
recovered in this bounded investigation. Rendering order is opaque world,
blended world, then UI; each pass preserves mesh draw order. There is no distance
sorting. UI modes use the same blend factors with depth testing/writing disabled
and the existing identity transform. This supports opacity without disturbing
ordinary HUD composition; it is not a recovered universal original UI contract.
All explicit draw opacities must be finite within0..1 and blend modes must be
valid, including invisible draws. Scene creation/replacement and every render
validate these properties. Per-frame validation runs before swapchain acquisition
or command-buffer recording so a rejected mutable material leaves rendering
usable after correction. All six pipelines are destroyed before their layout.
## Verification
`scripts/compile-shaders.sh` compiled both shaders for Vulkan1.3 and validated
both SPIR-V modules. Vertex SPIR-V remained unchanged. The isolated source-linked
test project builds without compiling the main runtime:
```sh
source scripts/env.sh
dotnet restore tests/GamePort.BlendTests/GamePort.BlendTests.csproj --ignore-failed-sources --source .nuget/packages
dotnet build tests/GamePort.BlendTests/GamePort.BlendTests.csproj --no-restore
dotnet tests/GamePort.BlendTests/bin/Debug/net10.0/GamePort.BlendTests.dll artifacts/gadget-blending/final-frame.ppm
```
Build: zero warnings/errors. Linux headless Vulkan runtime: llvmpipe
(LLVM20.1.2,256bits), Khronos validation enabled, **17 checks passed, zero
validation errors**. GPU RGBA readback checks exercise default opaque color,
half-opacity alpha/additive RGB equations, opaque occlusion, disabled blended
depth writes, UI ordering and depth bypass for both blend modes, zero opacity,
unchanged texture cutout, invalid opacity/enum rejection, and successful rendering
after correction. Numeric color tolerance is2/255 for attachment quantization.
Logs and a final opaque reference frame remain in `artifacts/gadget-blending/`.
These are real port GPU checks, not original-game comparisons. Windows runtime,
the selected graphics-option branch, original depth-write behavior, mixed
transparent scene ordering, and original alpha-test policy remain unverified.
Main-runtime integration and gameplay visual comparison belong to the primary
agent's integration checks.
+143
View File
@@ -0,0 +1,143 @@
# 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.
+134
View File
@@ -0,0 +1,134 @@
# First playable gadget implementation
2026-10-27. User-directed gameplay continuation; collision checkpoint35a2a66/
0272f7b remains parked. This implements the original gadget screen and the combined
shrink-ray/jetpack device, with a bounded3SOL target consumer. It does not complete
the other seven special gadget modes, enemy combat/AI or original runtime comparison.
## Evidence and state ownership
The independent reports retain hashes, preferred VAs, mapped file offsets,
structures, callers, resource identities, REA Evidence and provider limitations:
- [Controls](gadget-controls.md):425870 keys/latch,425EF0/425B20 panel ownership,
427370 selection, exact rectangles/availability and eight practice destinations.
- [Assets](gadget-assets.md):54 exact screens.omt canvases; original tile labels,
models, morphs and sound resources. Blue c tiles are unused by recovered group0.
- [Primary fire](shrink-ray.md):426030/426E40 continuous scan, owned item3/raw
mode−1, energy−dt, strict target/obstruction gates,42AC10 callback and owned beam.
- [Heading](shrink-heading.md): original quantized heading;15 copied-DLL numeric
references and65,540 bin/quadrant cases match managed code, fingerprint24e64f91.
- [Targets](shrink-targets.md): actual3SOL constructor/load, radius90/factor1,
WALK/SHRINK clips, nonloop endpoint, authored/reset versus previous dynamic mode.
- [Blending](gadget-blending.md): source half opacity and blend enum conversion;
opaque/alpha/additive rendering implementation and explicit depth-write policy.
- [Review](gadgets-review.md): independent code/evidence review; missing ordinary
+10 callback corrected, eligibility defaults and remaining limits recorded.
Menu display item3 and equipped-mode word are separate. Selecting SHRINK RAY
closes the panel, cleans old special mode and leaves normal raw mode−1; item3
ownership also gates jetpack. SceneInventory.SelectedGadget remains the port's
display/request index; PlayerSceneBinding normalizes3 to raw mode−1. Existing
retained route state remains bounded to default device display−1/3.
## Implemented behavior
GadgetScreen/GadgetMenuOverlay use the original640×480 background, owned idle/
hover tiles and buttons, with uniform centered widescreen scale and inverse
pointer mapping. Tab/Space shares a held-key latch. First Tab unequips a special
mode, next opens. Escape/Return closes; mouse or Enter/Ctrl/jump buttons activates.
Arrows steer the pointer through the recovered accumulated80×dt offsets. Raw0/4
cannot hit; raw3 suppresses green hover. Current route0/1/4 rendering is recovered;
inherited raw2/3 idle visibility uses a declared owned-white port fallback.
Practice arm/choose loads the selected original tutorial directly, independently
of the pickup's Yes/No prompt. It rejects VR01..08 and SCENE>=500; runtime practice/
Return slots are not serialized in TSK. Selection observers see the panel closed.
Input capture clears held movement/jump/fire and preserves Space cutscene skip
when the panel cannot open. New SFX requests use the source panel gate; music
continues. Pausing all port gameplay/morph timers during the panel is broader than
the recovered body-enable/game168 leaves, and remains an explicit modern policy.
LabSimulation invokes gadget input in its existing fresh/retained input phase.
Grounded fire clears controller speed before movement apply and selects original
SHOOT. The ordinary FALL branch hides/stops the ray. Ray ownership requires
inventory(0,3)==1/raw mode−1; invalid ownership clicks117 once until release.
Held ordinary ray uses looping SFX0, spendsdt energy even without a hit and is
energy-exempt in VR01..08. Existing powered jump/fire remains independent.
ShrinkRay implements the continuous registry-order multi-target scan: body and
shrink-enable flags, not already shrunk, strict1500 distance, strict Y−150/+60,
strict quantized heading within yaw±5 with no added seam wrapping, and no accepted
source47C210 static-wall hit. The caller currently supplies only original3SOL
soldiers in LV1B/VR04/LEV1; only VR04 actually contains those actors.
Each ordinary hit requests SHRINK, sets mode5, timer30 and shrunk flag, awards10
through SceneInteractions and then writes the reaction marker. Score persists in
original-format snapshots. Already-shrunk targets do not receive repeated awards.
LIBBYPLANT/C3DDINO quest branches remain outside this3SOL consumer. Timer updates
preserve the source >0 decrement/<0 expiry edge, including exact-zero retention.
Expiry restores authored/reset AIState (VR04=2), not the pre-hit dynamic mode,
clears the marker and selects looping WALK/speed200.
Original soldier WALK/SHRINK geometry uses soldatak's matching original UV topology;
walk/shrink ASE files contain no UVs. Source SHRINK holds its last authored frame
(55.1186 high), without invented uniform scaling. The transition preserves frame
ordinal; exact within-frame clock preservation remains open. Source roots and
units are retained. Soldier body settling uses the existing provisional NPC
support/wall adapter with recovered90/1, not a claim of complete enemy physics.
The owned RAY mesh follows the captured player root/upright Euler without invented
muzzle offsets, lifetime or cooldown. Three source textures switch at the recovered
float-accumulator >double0.1 boundary, discarding overshoot. Source alpha0.5 is
applied once, not as geometric scale. Additive SrcAlpha/One is the chosen recovered
graphics branch; the source graphics-option predicate is still open. Generic alpha
SrcAlpha/OneMinusSrcAlpha is also implemented. Blended world depth-write disabled
and inherited cutout behavior are explicit rendering policies, not full legacy
material-state recovery. Opaque defaults and UI ordering are regression checked.
## Verification
Full scripts/test.sh passes157 Python checks,2 HUD tests, all managed suites,
29 game GPU completions and17 isolated Vulkan blend/readback checks with zero
enabled validation errors. Fifteen gadget groups cover menu/state/viewport,
source target gates, phase clock, held/release/energy/sound, authored morph hold,
score callback order and TSK persistence. Heading covers the65,540 original-DLL
references separately.539 original files remain unchanged.
Final source close-before-selection and authored-mode corrections pass the
complete final suite in integration-final.log; the latter distinguishes pre-hit
dynamic7 from restored authored2. No old numeric body/controller result changed.
Native Linux GTX1070/private Xvfb passes gadget-menu input at1920×1080 and ray
input at1280×720, with zero validation errors. Menu24 frames verify shared
Tab/Space edge, pause, Escape, select without leaking fire, Practice, Return and
stable root. Ray90 frames hits an actual VR04 yoke1 once, holds its authored small
pose, cycles all three textures and retains VR energy20.
Final source replay logs are native/menu-final.log and native/shrink-final.log.
The ray smoke explicitly moves the player near an actual authored soldier after
body settling. It does not invent/relocate targets or claim input navigation to
their high platforms, patrol/combat AI, or original visual parity. Saved mesh
height is a port animation observation; GPU readbacks verify rendered output and
material behavior. Logs/readbacks are in artifacts/gadget-implementation/ and
artifacts/gadget-blending/. Windows cross-publish/native runtime remain distinct.
## Remaining work
| System | Recovered contract | Current port / remaining boundary |
| --- | --- | --- |
| Selection | Group0, eight cards, display3 versus raw−1, close before select | Implemented; inherited raw2/3 art visibility is a declared fallback |
| Practice | Selected item→VR01..08, disabled in tutorials/SCENE>=500 | Implemented through existing departure/RETURN state |
| Primary ray | Owned item3==1, continuous held scan, FALL interruption | Implemented in first-route scenes; full Euler/retained owned-effect lifecycle open |
| Energy/audio | Energy−dt, VR exemption, loop0, invalid117, warning80/182 | Scalar/loop/invalid implemented; warning latch and broader sound lifecycle open |
| Soldier hit | Strict target gates, SHRINK/mode5/timer30, +10 then marker | Actual VR04 3SOL implemented; later eligibility setters/AI and special quest classes open |
| Restore/animation | Strict-negative expiry, authored AI mode, WALK200, nonloop SHRINK | Implemented; exact fractional morph clock and full NPC physics remain provisional |
| Rendering | Original mesh/textures, opacity.5, two blend branches | Tested additive choice; graphics-option predicate/full material state open |
| Timing/ownership | Body enable and SFX gate on menu, original input phase | Existing phase bridge used; full-panel pause is modern policy, complete scheduler open |
Other gadget effects/equip cleanup, full soldier AI/reaction consumers and
dynamic collision; score popup and other quest targets; low/empty energy audio
latches; owned-ray retention across loads; exact full-Euler/render root and morph
phase; complete menu/music/software-clock lifecycle; original whole-game and
native Windows verification. These are bounded follow-ups, not reasons to replace
recovered source rules with invented cooldowns, damage, colliders or uniform shrink.
+117
View File
@@ -0,0 +1,117 @@
# First gadget integration review
Review of `SceneGadgets`, `ShrinkRay`, `LabSimulation`, `ShrinkRayVisuals`,
`ShrinkSoldierVisuals` and their `Program` wiring against
[shrink-ray.md](shrink-ray.md), [shrink-heading.md](shrink-heading.md) and
[shrink-targets.md](shrink-targets.md). This is a read-only source/evidence review,
not new gameplay runtime verification. It records the snapshot before the
primary's review fixes; subsequent implementation/tests must mark fixes verified.
Update during review: the primary added `ScoreAwarded`→`ChangeScore` wiring and
the source hit marker. Reading the updated code confirms ordinary +10 reaches
the score/save owner and the marker is set after the event; build/runtime checks
belong to the primary. The initial finding remains below as the reason for that fix.
## Directly evidenced callback omission
**Resolved: the initial implementation omitted the original +10 score callback.**
The initial `SceneGadgets.Input` applied `ShrinkSoldier.Shrink()` and incremented a diagnostic
hit counter without awarding persistent `SceneInteractions.Score`. Primary now
awards/persists10 and sets the reaction marker after the score event; its managed
test verifies ordering and the original-format save round-trip. Original
`42AC10..42ADB5` (raw `2AC10..2ADB5`, same guarded source identity as the ray
report) performs action/mode/timer/flag writes, then branches on the target's
ObjectTag at interface+3A0:
| Tag comparison / address | Recovered effect |
| --- | --- |
| `LIBBYPLANT`, 42AC84–42AC9B | Find `C3DLIBBY`; if found, award 100, mode 0, write 160 to complete6C4, set two action strings to WALK, and change SCENE 250→255 if currently 250. |
| `C3DDINO`, 42AD3F–42AD7E | If task DINO <10, set DINO=10 and award 300; otherwise return without those effects. |
| Every other tag, 42AD81–42ADA1 | Award 10 through42ADC0; write target complete94C/interface88C=1.0. |
`42ADC0..42ADF9` (raw `2ADC0..2ADF9`) adds with signed 32 arithmetic, clamps
negative total to 0, and for positive awards records the amount at 4F83C4 with
1.2s at 4F83C8. Existing score/save ownership belongs to `SceneInteractions`;
the shrink hit diagnostic is not a substitute. Preserve the reaction field as
an explicitly identified dependency of the still-unported enemy base/AI update;
its complete consumer semantics have not been recovered by this review.
Read-only GAM parsing confirms first-route scope:
- `level1b.gam` (lab): zero 3SOL actors.
- `VR04.gam`: three 3SOL, tags `yoke1`, `C3DYOKIANSOLDIER`, `yoke2`.
- `Level1.gam` (outside): zero 3SOL actors.
Thus all currently supported real target hits use the ordinary +10 branch,
including VR04. The callback has **no VR score exemption**. Do not apply the
energy exemption to score, invent a generic quest/objective update, or award
the special branches for every enemy of a matching class. Earlier vague
Humphrey descriptions do not identify this branch: the exact shipped string is
`C3DLIBBY` at4EF710. The apparent SE9 call at 42AC17 reaches `472970`, whose body
is `C3`/return; it is not evidence for another hit sound.
The primary's regression now checks the +10 save effect once per accepted
unshrunk target, simultaneous targets and later re-shrink after restoration,
while VR energy stays unchanged. The reaction-field consumers and unsupported
quest classes remain named limits rather than inferred combat behavior.
## Confirmed source alignment
- Owned item 3 must equal 1; equipped mode is −1 even when UI display item 3 is
highlighted. There is no positive-energy gate or projectile cadence in the scan.
- The scan is continuous while held. Current strict root height, distance<1500,
quantized original heading, no added heading seam wrap, geometry-query rejection
and multiple-hit behavior agree with the bounded source contract.
- The corrected FALL logic is sound: at 42692A an absent loop branches to426937;
`strcmp(FALL)==0` at 426948 skips the scan. With a loop present, equality at
42695F falls through stopping its handle, setting−1 and hiding the beam at
426963..426989. Other airborne actions can start/retain the loop and scan.
The port correctly blocks FALL, not all airborne poses, and reserves SHOOT for
grounded fire. Source speed608 is zeroed before this branch, including air.
- Beam position/yaw are captured when firing and rendered from that snapshot;
they should not be replaced with the player's later render-frame root. Source
copies root and full Euler at 426EF1/426F47, with no caller muzzle offset.
- Texture phases 0/1/2 use a float timer compared strictly with double0.1, advance
at most once and discard overshoot. Opacity .5 and additive drawing implement the
known global509A13=false branch. Conventional alpha is the other recovered
branch; the original settings/hardware choice is unresolved, so additive is
an explicit port policy, not a universally recovered default.
- Soldier geometry uses original WALK/SHRINK topology, actual GAM roots and an
authored nonlooping shrink morph. False selector preserves a clamped frame
ordinal; modern within-frame clock is explicitly approximate. There is no
invented uniform scale. Strict-negative expiry, WALK restart and restored
speed 200 follow the source. Radius 90/factor 1 are source defaults; reuse of the
existing scene-physics adapter remains provisional collision behavior.
## Material bounded differences and next checks
1. **Energy audio:** direct subtraction/clamp in `SceneGadgets.Input` matches the
scalar part of42A920, but omits its empty-crossing SFX80 and low-energy SFX182
latch/hysteresis (<19 to set, >20 to clear). VR04 masks this omission through
its energy exemption. Share the energy-adjust lifecycle before claiming source
fidelity outside VR04; do not add an unsupported energy>0 firing restriction.
2. **Full Euler:** the effect and wall endpoint use only yaw. Source copies all
Euler components. This is bounded by the present upright controlled-player
model; source pitch/roll behavior and generic Euler normalization remain a
dependency. Preserve full snapshots when that orientation model is implemented.
3. **Eligibility:** both source defaults are now confirmed. Generic constructor
46FDDF (raw 6FDDF) pushes 1, then46FDE3 calls471030. That setter writes authored
+16 at471037 and dispatches slot 214 at47103A; soldier game vtable4C19C4+214
contains471A00, whose471A04 writes live interface13E. Yokian constructor44A94F
(raw 4A94F) writes complete958/interface898=true;44A905 clears shrunk. Actual
soldier constructor44BF32 calls shared44A730; loader44C0B0 does not override
these flags. This agrees with the prior guarded body-composition finding
integration210/live13E=true. The current default-true candidates cover these
initialized actors under the no-AI boundary, but do not mirror later setters.
Actual VR04 GAM CanMove1 is the separate animated-object58C field; do not
equate it, generic `Actor.Active`, or visibility to the source body/shrink gates.
4. **Scope/ordering:** soldier AI, shared enemy reaction-field consumers, full
registry scheduling and hidden-owned-effect initialization remain outside this
first interaction. The modern step order is an implementation partial order;
standalone or rendered smoke success does not verify the original game's
complete update order. A native Windows walkthrough still needs hold/release,
jumping/FALL interruption, a wall-blocked target and 30s restoration checks.
No additional runtime changes were made by this review. Existing complete REA
Evidence/source guards are reused; unavailable source42AC10 decompilation was
not retried. Exact callback branches above were cross-checked against the guarded
original instruction range and source string bytes.
+148
View File
@@ -0,0 +1,148 @@
# Shrink-ray heading recovery
This closes the heading dependency of the held shrink-ray scan in
[shrink-ray.md](shrink-ray.md). Facts below come from immutable original bytes,
REA/Ghidra 12.1.4, and an isolated component call to a generated DLL copy.
The managed implementation is `src/GamePort/Game/OriginalHeading.cs`;
`OriginalHeading.Degrees(targetRoot - jimmyRoot)` returns the quantized source
heading. The caller must retain the original strict EulerY±5 comparison without
adding seam wrapping. Whole-game target selection remains a separate integration
and runtime check.
## Source identity and ownership
Original EXE SHA256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
OMT2.dll SHA256:
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
Generated targets were `artifacts/uncontrolled-phases/rea/Neutron.exe` and
`artifacts/asset-probe/game/OMT2.dll`. No original was modified or executed in
place. The focused helper checks both complete hashes, the import/export mapping,
13 instruction sites, six constants, and the regenerated lookup fingerprint.
| Owner/location | File offset | Recovered role |
| --- | --- | --- |
| EXE IAT0048D108 | `8D108` | OMT2 import `?angles@OMedia3DVector@@QAEXAAF0@Z` |
| EXE 00426FE4–00427011 | `26FE4` | Stores float32 target-root minus Jimmy-root vector |
| EXE 004270B1–004270C5 | `270B1` | Calls vector::angles with two signed-short references |
| EXE 004270D7–0042713B | `270D7` | Reads second output; strict heading-window comparisons |
| DLL 1001FDA0–1001FF6E | `1FDA0` | Export 278, `OMedia3DVector::angles(short&,short&)` |
| DLL 1001FDCB–1001FE3D | `1FDCB` | Computes horizontal lookup/quadrants; stores second output |
| DLL 100EDC00–100EDD2A | `EDC00` | `OMediaCosSinTable::init_table`; table generation |
| DLL 10104E04–10104E2B | `104E04` | Integer conversion explicitly switches x87 to truncation |
| DLL 10161E38 | runtime-initialized table | Half-acos unsigned-short table, global object+20008 |
Ranges above end exclusively. EXE addresses use base00400000, DLL addresses
base10000000; these source ranges have raw offset=RVA. Full range hashes and
checks are in generated `artifacts/shrink-ray/heading-source.json`.
## Recovered algorithm
Only vectorX and vectorZ affect the second output. It is always in 0..16383,
although the caller reads it with sign extension. One unit is exactly
`360/16384 = 0.02197265625` degrees (EXE float0048E5B4).
For finite float32 components, with extended intermediates in the original:
```text
if x == 0 and z == 0: return 0
i = trunc(16384 * z*z / (x*x + z*z))
a = halfAcos[i]
if z < 0:
a = (x < 0) ? 8192+a : 8192-a
else if x < 0:
a = 16384-a
return (-a) & 16383
```
The original actually truncates the negative ratio multiplied by−16384 and
subtracts that integer from the combined-table base index10004. The positive
index formulation above is equivalent on finite inputs. There is no atan2 call.
The table contains truncated integers:
```text
halfAcos[i] = trunc(acos(i * .0001220703125 - 1)
* 2607.5945876921437 * .5) # i=0..16383
halfAcos[16384] = 0 # explicit final endpoint
```
The stored constants and truncation are significant. The first 16384 words match
the previously observed copied-DLL FNV32 `4f800433`. The 16385-word little-endian
table SHA256 is `292eaae8707bcbc0e760280eca51ecb760914dbac81e943428219713e9065744`.
| Direction | Heading units | Degrees |
| --- | ---: | ---: |
| +Z | 0 | 0 |
| −X | 4096 | 90 |
| −Z | 8192 | 180 |
| +X | 12288 | 270 |
| X=−1,Z=+1 | 2048 | 45 |
| X=+1,Z=+1 | 14336 | 315 |
| X=+1,Z=1000 | 16364 | 359.560546875 |
| X=−1,Z=1000 | 20 | .439453125 |
| X=1000,Z=1 | 12288 | 270 |
This orientation matches the port's forward vector `(−sin(yaw),0,cos(yaw))`.
The coarse ratio table near cardinal axes is part of recovered behavior;
replacing it with rounded atan2 would change target acceptance near the 5° edge.
The scan calls this after its root-height and distance filters. The first
reference receives pitch and is unused here. For the zero vector the copied DLL
returns pitch 4096/yaw 0; this utility intentionally implements only yaw.
## Window and state interaction
At004270D7 the scan reads the second output from stack +16. It multiplies by the
stored degrees factor, compares strictly greater than JimmyEulerY−5, then at
00427112 compares strictly less than JimmyEulerY+5. The 5 is stored at0048D950.
Rejected targets branch to00427310, the next registry entry. These instructions
perform no modulo normalization, shortest-angle difference, nearest-target
selection, cooldown, or heading hysteresis.
Consequently a tiny positiveX target can yield359.56° and fail when JimmyY=0,
while its mirrored negativeX target yields .44° and passes. Do not repair this
asymmetry speculatively. Original Euler normalization outside this caller is a
separate system dependency.
## Evidence and verification
REA Evidence
`ev_944c7a8e63e2c332ecaabe01ddb6587f0c4b25ee087124e15394d617a94b2633`
is retained completely in `artifacts/shrink-ray/rea-heading/evidence.json` and
`analysis.snapshot.json`; extracted pseudocode is `heading.pseudo.c`.
The Ghidra call completed in 254.6s, beyond the existing batch client's 180s wait.
The client then closed its owned session successfully. The complete result was
recovered from that closed snapshot; no unchanged request was repeated. Ghidra's
x87 pseudocode omits portions of the ratio expression and misnames some stack
values; the instruction stream, not those temporary names, establishes the
formula above. `heading-source.json` records source offsets and range hashes.
`tools/binary/shrink_heading.py --emit-probe <generated.c>` emits a bounded probe
using only LoadLibrary/GetProcAddress on the generated OMT2 copy. It calls the
export with synthetic vectors; no game entry point is run. The existing
`tools/recon/reference_capture.py` harness isolates its filesystem/network and
does not mount Original/. Retained output is
`artifacts/shrink-ray/heading-probe/wine.log` and `capture.json` (exit 0). The first
six-second attempt ended during cold Wine initialization; its capture/log were
retained separately. The changed thirty-second run completed normally.
Observed: 15 explicit vector results and 65,540 generated bin/quadrant cases.
The sweep's word-wise FNV32 is `24e64f91`; both Python and managed implementations
match. This verifies the component under Wine, not full gameplay or native
Windows behavior. The source uses x87 extended intermediates; the managed/Python
projection uses double. Arbitrary float32 inputs exactly at ratio-bin boundaries
remain a precision risk beyond the observed sweep. Nonfinite vectors are rejected
explicitly by the modern utility; original invalid-input behavior is not claimed.
Reproduce from GamePort/:
```sh
python3 tools/binary/shrink_heading.py
python3 -m unittest discover -s tests -p test_shrink_heading.py -v
source scripts/env.sh
dotnet run --project tests/GamePort.HeadingTests
```
Remaining: integrate the utility with the scan's eligibility/raycast/callback
contract and compare actual target acceptance in gameplay. No unresolved heading
quadrant or table dependency blocks that integration.
+147
View File
@@ -0,0 +1,147 @@
# Shrink ray primary fire and owned effect
2026-10-27. Read-only static recovery from supplied EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Preferred VAs below map to raw file offset VA−400000 for this image's text;
shrink_ray.py independently PE-maps all locations and guards eight bounded
function ranges plus44 source sites. No original code was executed by this task.
## Important identity correction
The inventory/menu highlight is not the raw equipped-mode word4F0588. The
[gadget control investigation](gadget-controls.md) proves selecting group0/item3
cleans current mode to−1, then calls equip174(3); cases3 and−1 leave that mode
unchanged.426E40's shrink scan requires owned item3==1 **and mode−1**. The same
item owns the recovered jetpack ability. Earlier jetpack-only descriptions that
treat SHRINKRAY as an unrelated internal label are superseded by this combined
source path and the original item's SHRINK/JUMP art. Do not implement selected
mode3 as a separate shrink-ray state merely because the menu highlights item3.
## Primary input and animation ownership
| VA / raw | Recovered contract |
|---|---|
|426030 /26030|Input callback first requires407060 false,475CA0 true, controlled5099E4 nonnull, global4F8430 false and interface1D2D false. Movement438A60 and gadget subhandlers run before the ordinary fire tail.|
|42A7A0 /2A7A0|Primary helper is false while4F83E0 is set; otherwise OR of509834,509845,509849,509AC4. Readme maps Enter/Ctrl/left mouse; pad input remains separate.|
|426566..42657F /26566|Held primary helper OR keyboard13 invokes the held-fire branch. Release stops the owned sound loop and hides the ray.|
|42668F..4266BD /2668F|Busy1D65 or modal4F8182 rejects; raw mode0 rejects; otherwise controller speed608 is set0.|
|4266C8..4266F1 /266C8|Grappler/energy subhandlers run; mode4 exits; ordinary mode−1 continues.|
|4266F7..42672B /266F7|Supported body requests SHOOT, then animation148. The caller's grounded shooting pose, not the collision support routine, owns this action.|
|4268BE..4268F7 /268BE|Owned item3 must equal1. If sound handle interface974==−1, start SFX0 looping and retain its handle. Invalid availability emits SFX117 and latches busy1D65 until release.|
|426902..42698C /26902|Airborne branch permits the ordinary fire path around the FALL action and owns its own loop interruption; do not force all airborne frames to grounded SHOOT.|
|4269BD /269BD|Complete virtual1B8 invokes426E40 after these gates. No one-shot cooldown or projectile spawn is present in426E40. It is a held, per-input-invocation scan.|
Raw primary callback physics/control predicates are separate from the modern F1,
inspection, focus and practice modal policies. New primary input must be cleared
at modern capture boundaries and must not leak into cutscene skip/menu selection.
## Target scan and hit order
426E40..427334:
1. Require403950(group0,item3)==1 and signed4F0588==−1.
2. Show Jimmy-owned complete object+A10 (interface+950) if present. Copy Jimmy's
current root exactly via318 and current Euler exactly via330. There is no
muzzle offset in this caller; the original ASE supplies the effect geometry.
3. Call42A920(−dt) once **before target traversal**, even if there is no hit.
There is no positive-energy test in this ordinary scan.42A920 exempts original
VR01..VR08, otherwise clamps energy0..100 and owns low/empty sounds/latches.
4. Traverse object registry50999C in linked order. Payload is the game interface.
Require interface13E nonzero, class-name check18(`C3DENEMY`), interface898
nonzero and interface8B0 false (already-shrunk flag).
5. Require enemy rootY strictly greater than JimmyY−150 and strictly less than
JimmyY+60. Full root-to-root Euclidean distance must be strictly below1500.
6. Call imported vector calculate_angles48D108; convert its signed-short heading
to degrees with stored float0.02197265625. Require heading strictly inside
JimmyEulerY−5 .. JimmyEulerY+5. These instructions add no seam wrapping; exact
angle production/convention and generic Euler normalization remain a separate
numeric contract. The helper projection accepts the recovered heading as input.
7. Build a source ray from Jimmy root+(0,150,0) to offset384(0,150,distance).
Call47C210 and reject on **any accepted wall-query hit**. This is the original
static grid/winding query, not nearest sphere sweep or a pixel/crosshair test.
8. For each accepted enemy invoke Jimmy complete1DC→42AC10(target interface).
There is no break/nearest-target reduction: multiple eligible enemies may be
hit in a single invocation. Registry order and source wall query are dependencies.
42AC10 requests exact action string `SHRINK` at4EF71C with argument0 through
enemy completeE0, sets enemy complete124(5), then complete974=30.0 and
complete970=true. Those fields are interface8B4 timer and8B0 flag. It also owns
class/tag-specific objective, score and Humphrey policy, so generic shrinking
must not invent a universal score or destruction event.
The independent [target investigation](shrink-targets.md) owns actual3SOL class,
SHRINK morph, timer expiry and restored action. Its source check corrects an
initial label:44AEC6 requests `WALK` (4ECA54), not STOP. Visual shrink is driven
by the original morph/action; do not substitute an invented uniform scale.
## Beam effect is an owned object, not a ballistic projectile
Jimmy constructor4222AB allocates6D0 bytes;4222C9 calls43FE20 and4222D9 stores
the resulting complete object at Jimmy+A10.43FE20 establishes C3DShrinkRay
interface table4B4350, invokes440000 Init and disables its physical collision
through220 setter4710C0. Phase complete6BC starts0 (interface5FC).
440000 Init binds `HIRAY`→`ray.ase` at440037, then texture slots0/1/2 to
ray0000.png/ray0001.png/ray0002.png. It sets action `RAY`, radius40 and source
factor0.3; these physical values do not imply a moving projectile. The caller
keeps the owned effect at Jimmy's root/Euler while held and hides it on release.
**Opacity, not scale:** C3DShrinkRay complete114 resolves40E4A0. Positive param
walks shape polygons and each nonnull material, writes RGB1 and alpha=param to
material+4C..58, source blend field+30=6, destination+34=7 when global509A13 is
true or1 otherwise, and ORs material flag38 with1. Init and every texture switch
call114(0.5). The earlier per-texture RGBA writes also set0.5; this setter
replaces the alpha rather than multiplying it again. No geometric half-scale is
justified.
The engine adapter10036AB0 (raw36AB0) uses table1013667C (raw13667C) to map both
material enums into D3D render states19/20. Selected entries are6→D3D5 SRC_ALPHA,
1→D3D2 ONE,7→D3D6 INV_SRC_ALPHA. Thus global509A13=false selects alpha-weighted
**additive** blending (SrcAlpha,One), while true selects conventional alpha
(SrcAlpha,OneMinusSrcAlpha). The flag is loaded from a graphics-setup option and
stored476BBE; its complete settings/hardware fallback semantics remain open.
Do not silently treat both branches as conventional alpha. The DLL SHA256 is
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
440180 interface3C4 update first invokes base40E050. On its first pass a flag
interface604 causes Init through1C; then float timer600 adds dt. When strictly
greater than **stored double0.1**, phase5FC increments, wraps after2 back0,
swaps the bound texture, reasserts opacity0.5, and resets timer0. It advances at
most once per invocation and discards overshoot. Since float0.1 is slightly above
double0.1, passing an exact float0.1 triggers the switch. No independent finite
beam lifetime is present; hold/release and object visibility own it.
## REA evidence, gaps and checks
The three owned EXE REA sessions used the generated hashed
artifacts/uncontrolled-phases/rea/Neutron.exe and closed/exported normally.
A fourth session used the generated artifacts/asset-probe/game/OMT2.dll copy for
the blend adapter, also closed/exported under artifacts/shrink-ray/rea-blend/.
| Retained path | Successful Evidence |
|---|---|
|artifacts/shrink-ray/rea-primary-followup/03.json|42A7A0 ev_3ff9cde0cab7a1e7ed456591becfcc4c4f4db3796aa6ab5e76a1dd124f9dac47|
|rea-primary-followup/04.json|42A920 ev_71897af12f4bfa1de946c6f17f3bbed34764fdc84258ce64516c8f1f904b465d|
|rea-effect/00.json|440000 ev_875816ebeb0d690c83518f14f36a13d646009d3530c0ad1f27efbd3a2342aeff|
|rea-effect/03.json|43FE20 ev_3ae9cf6456693b674f937b0e4c86392b88f0d80f8eb416e5b7585f08f790e7f9|
|rea-blend/00.json|10036AB0 ev_f5a914ee9eae593b02a04149b6651b2d783151df046bbb417624bf94f23bb96c|
426030/426E40/429D00 VA queries were unrecognized; corrected raw-offset selectors
were tried once and also failed.440180 and42AC10 likewise have no recognized
procedure in this profile. Errors/complete diagnostics remain beside successful
Evidence; their conclusions use fixed source instruction/body guards and the
matching class/vtable/asset chain, not invented successful decompilation.
`python3 -m unittest discover -s tests -p test_shrink_ray.py -v` passes seven groups:
source bodies/constants/assets/opacity anchors; owned3/mode−1; independent target
gates; strict range/height; strict quantized-heading/no-added-wrap; texture float/
double threshold, wrap and discarded overshoot; DLL body/table identity and
additive/conventional-alpha factor distinction. These are source projections,
not original execution or managed/native gameplay verification. Complete source
report can be generated with shrink_ray.py ../Original; originals remain read-only.
Remaining: exact imported heading production/Euler normalization, full airborne
SHOOT interruption, graphics-option/depth order, full enemy class/
script/score policies and original whole-game runtime comparison. The source
device's held geometry, textures, ownership gates and target callbacks support a
bounded first implementation; a synthetic projectile cadence is not supported.
+198
View File
@@ -0,0 +1,198 @@
# Original 3SOL shrink targets
Status: recovered static binary/asset contract for a bounded first shrink interaction.
Original runtime verification, full soldier AI, and exact collision integration remain open.
Originals were read only; REA inspected generated hashed copies, never executed originals.
Run `python3 tools/binary/shrink_targets.py ../Original` to produce the guarded contract,
including PE-mapped **file offsets** for every address below. Saved output:
`artifacts/shrink-targets/source-contract.json`. Addresses in this note are preferred-base VAs.
## Evidence ledger
REA results, complete evidence, snapshots, and closed-session records are retained under
`artifacts/shrink-targets/`. REA observations are static analysis, not runtime traces.
| Question | REA Evidence ID | Saved directory |
|---|---|---|
| Shared Yokian construction | `ev_19d3441021faa1f39087a8e65e3b04df57315de2ee53f75b2e70fce2dc8a432d` | `rea-soldier/` |
| Shared Yokian update | `ev_c7d9d0bd6ea80f021689545e79baca422ca5b526d69c89d7ccf54c4ea2142a18` | `rea-soldier/` |
| Actual soldier construction | `ev_64b0152bae4f3a51a80c70f6470212b5c5cb9036e449d5eefe6129b35ace70c2` | `rea-soldier-bindings/` |
| Soldier model/texture loading | `ev_4e46100718fc9d13d99409941d2494de216d281317a04fd9e56ad33e1aa3e6ec` | `rea-soldier-bindings/` |
| Generic load caller | `ev_efdc2d429180a0cd692326a261bc274ac5cb0daf45ab167c0627a858acabf041` | `rea-soldier-bindings/` |
| Engine sequence selection | `ev_67aff8ee9529fa39014ae438e22e3dc52ecd2ce71d0886974d0682d6eea58f8b` | `rea-sequence/` |
| Engine endpoint/loop handling | `ev_e0d4f2ee9131d62ea289ea1aeb0f24b7de4a2bd696149309e9dfb2e3d14614df` | `rea-loop/` |
| Dynamic mode setter | `ev_8286c3d9b13f47f1e6fbf211d85636b54fb5ccb7cc7e55dd1e0f0366a7170b84` | `rea-mode-local-ipc/` |
| AIState property registration | `ev_aa47a422ce39fc5bf5bbca319fe3c37e27526299abeb9f6cdb9d065d46de9f50` | `rea-mode-local-ipc/` |
| Generic load/reset state | `ev_c448bb4062e760eb4bf3b09d39e630b130a8eafd377a27625a25b69ab7679a27` | `rea-mode-local-ipc/` |
The first mode-closure attempt (`rea-mode/00.json`) failed because the sandbox
blocked Ghidra's local Unix-socket bind. The successful invocation above used
local IPC permission; no provider/client configuration was changed. Its complete
Evidence and close/snapshot records are retained. The failed call is not used
as evidence for source behavior.
`Neutron.exe` SHA-256: `f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
`OMT2.dll` SHA-256: `3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
The helper guards eight bounded code ranges, decisive byte sites, vtable targets,
resource strings, and all three ASE hashes; it fails on an unexpected identity.
## Class ownership and initialization — recovered
`44A730` constructs shared **C3DYokian**, not the final soldier. Actual soldier
constructor `44BEE0..44C028` calls it at `44BF32`, then registers FourCC `3SOL`
at `44BFF5`. Soldier complete-object vtable is `4C1E64`, game-interface vtable
`4C19C4` at complete object `+C0`, and embedded morph vtable `4C1E14` at `+90`.
The generic model loader `40E270` dispatches complete slot `10C` at `40E331`,
reaching soldier loader `44C0B0..44C1BB`. Derived update `44C1C0` calls shared
Yokian update `44AA00` at `44C1C9`.
| Complete slot / callsite | Recovered binding |
|---|---|
| `D8` / `40D4A0` | Register model animation definition |
| `E0` / `40DD90` | Select named action; chooses HI/LO family |
| `E4` / `40DA30` | Select underlying sequence and copy loop flag |
| `10C` / `44C0B0` | Soldier model load |
At `44C19D` the soldier pushes float **90** into game-interface slot `110`
(`471240`, authored radius setter; live setter slot `264`). At `44C1AC` it
pushes float **1** into game-interface slot `100` (`4711E0`, authored factor;
live setter slot `254`). Live read slots `260`/`250` reach `471B30`/`471AF0`.
These are soldier body defaults; they do not establish the full collision solver.
## Model, texture, and authored shrink geometry — recovered
| Registration site | Action | Original ASE |
|---|---|---|
| `44C0C3/44C0C8` | `HIWALK` | `ASE/soldwalk.ASE` |
| `44C0DC/44C0E1` | `HISHRINK` | `ASE/soldshrink.ASE` |
| `44C0F0/44C0F5` | `HITALK` | `ASE/soldatak.ASE` |
| `44C104/44C109` | `HISTOP` | `ASE/soldatak.ASE` |
The loader compares scene FourCC against `VR01..VR08` at `44C121/44C128`.
For those scenes both texture indices 0 and 1 use `vryoksoldier.png`
(`44C133/44C144`, string `4F1950`). Supplied filename is
`png/VRyoksoldier.png`; portable lookup must ignore case. Other scenes bind
index 0 to `png/yoksold.png` (`44C14F`) and index 1 to `png/yoksoldtalk.png`
(`44C160`). Loader selects `WALK` with second argument 1 at `44C184`.
All three ASE clips have 190 vertices and 377 faces. `soldwalk` and
`soldshrink` have five samples at ticks `0,960,1920,2880,3840` (5 fps,
960 ticks/frame); `soldatak` has two samples (10 fps, 480 ticks/frame).
In existing ASE→OMT coordinates, shrinking sample Y bounds are:
| Tick | Minimum Y | Maximum Y | Height |
|---|---:|---:|---:|
| 0 | -55.6508 | 260.1789 | 315.8297 |
| 960 | -19.5291 | 208.5813 | 228.1104 |
| 1920 | -28.4904 | 156.9837 | 185.4741 |
| 2880 | -4.0918 | 105.3861 | 109.4779 |
| 3840 | -1.3301 | 53.7885 | 55.1186 |
This is actual morph deformation. A uniform quarter-scale soldier would be an
unsupported replacement. No extra uniform render scale was established in the
inspected source. The visual can retain original vertex units and authored root.
## Shrink, animation ownership, and expiry — recovered
Jimmy callback `42AC10` (investigated separately in `shrink-ray.md`) receives an
enemy game interface and subtracts `C0` to obtain the complete object. It selects
`SHRINK` with argument 0 at `42AC33`, selects mode 5 at `42AC50`, writes timer
complete `974 = 30` at `42AC68`, and writes flag complete `970 = true` at
`42AC8A`. The shared constructor initializes that flag false at `44A905` and
timer zero at `44A7EA`. Game-interface-relative offsets are timer `8B4` and flag
`8B0`; authored/reset mode is interface `87C`, complete `93C`.
### Mode setter and restoration ownership — closure
Soldier complete vtable `4C1E64` slot `124` points to generic enemy setter
`4089B0`. At `4089E5..4089FE` it copies **current complete `6C8` into previous
`6CC`**, then stores the requested mode in `6C8`. Requested mode 5 takes jump
table entry `408BA8` directly to the return at `408B8E`; there is no further
mode-5 callback or copy into `93C`. Thus SHRINK selection does **not** snapshot
the dynamic prior mode into the expiry field.
Interface `87C` is registered as the GAM **AIState** property at
`407F67..407F77` (name string `4ECA90`). Shared Yokian construction initializes
both complete `6C8` and `93C` to 2 at `44A7D3/44A7F7/44A7FD`. Generic load/reset
`409480`, at `409503..40951E`, copies interface `608` back to `87C` and passes
it to complete slot `124`; the separate initialization path `409460` copies
`87C` into `608`. The expiry body reads `87C`, not previous dynamic mode `6CC`.
For the three authored VR04 soldiers this restores GAM AIState **2**. A port
which snapshots its dynamic current AI state when shrinking would diverge once
AI begins changing modes; preserve a separate authored/reset AIState field.
Its value is 2 by constructor default, rather than an uninitialized zero.
Named selector `40DD90` forwards the caller's second argument through slot `E4`
at `40DF4C..40DF5E`. Wrapper `40DA30` calls embedded engine sequence selection
at `40DA61`, then explicitly writes the argument byte to complete `AD` at
`40DA64`. Since the embedded animation starts at `90`, this is engine animation
offset `1D`. Engine `find_next_frame` (`OMT2.dll:10021000`) reads `+1D` at
`10021079`: false holds the current endpoint (`100210B4`), true wraps to first
frame (`10021080`). Therefore source `SHRINK(...,0)` **does not loop**; source
`WALK(...,1)` does loop.
The engine sequence-selection boolean also controls restart: `100209F0`,
especially `10020A3A..10020A78`, restarts at first frame when true; when false
and an old frame exists it walks old/new lists to preserve the frame ordinal.
Thus changing WALK→SHRINK need not begin at shrink frame 0. Both have five
samples. Exact within-frame clock preservation remains open; any time-zero
transition in the port is an explicit approximation until closed.
Shared update `44AA00` decrements timer only when it is **strictly positive**
(`44AE5E..44AE6F`), subtracting delta at `44AE75..44AE7F`. It expires only when
the resulting value is **strictly negative** (`44AE85..44AE90`). Exact zero does
not expire in this body and is skipped next tick: preserve/document this source
edge case instead of silently substituting `<= 0`.
Expiry zeros timer (`44AE96`), clears flag (`44AE9C`), clears interface `88C`,
reads authored/reset mode `87C` (`44AEA8`), invokes complete mode slot `124` (`44AEBD`),
and requests **WALK** with argument 1 (`44AEC6`). String `4ECA54` is `WALK`,
not STOP. It restores interface `604` speed 200 (`44AED3`). While shrunk the
inspected branch can move current mode 0 to mode 5, set interface-related value
1500, and speed 400 (`44AE42..44AE54`). Full AI meaning of those transitions is
not closed here.
Calls `43F870(40,15)` while shrunk and `(140,50)` on expiry operate on owned
effect interface `8EC`. They are **effect sizes**, not soldier body radius.
No body-radius setter was found in this bounded shrink/expiry branch; that
negative observation does not prove no other mode/base update changes physics.
## First real targets: VR04 — original level data
`gam/VR04.gam` contains three `3SOL` actors; all set `AIState=2`, `CanMove=1`,
and `HasCollision=1`. Values below come directly from the bounded GAM parser.
| GAM offset | ObjectTag | Position X,Y,Z | PatrolPoint | VisibleRange / FOV |
|---|---|---|---|---|
| `4431` | `yoke1` | `-2463.1035,6327.9810,-7001.6870` | `dyok1` | 1000 / 259 |
| `582C` | `C3DYOKIANSOLDIER` | `1677.5118,6422.5869,-4131.2129` | `eyok1` | 2500 / 259 |
| `67C5` | `yoke2` | `-529.4881,6378.4834,1319.0276` | `fyok1` | 1000 / 359 |
These are authored actors high in the scene, not entrance test dummies. A bounded
interaction test can move the player near one as an explicit test fixture; it
must not relocate original actors or claim their AI has been reconstructed.
## Implementation boundary and unresolved work
At investigation start the runtime's `SceneActorVisuals` supported Carl,
Goddard, and trophy families; it did not render `3SOL`. `MorphAnimation.Sample`
looped all clips. The supported next chunk is to export these real soldier
clips/textures, render authored actors, support a nonlooping last-frame hold,
and apply the recovered SHRINK/timer/WALK transition. Parent owns runtime work;
this report does not assert those changes have shipped or run.
Existing `OriginalScenePhysics` can provide provisional radius-90/factor-1
settling for that bounded interaction. Reusing it is an implementation choice,
not proof of original soldier physics. The following remain explicitly open:
- Full soldier patrol, targeting, attack, damage, death, shadow/effect and sound updates.
- Exact collision/support/root defaults and all dynamic radius changes through base/AI modes.
- Other script/load/reset callers that can modify authored AIState independently of dynamic mode.
- Exact sequence-switch subframe timing and special empty/mismatched sequence cases.
- Non-VR texture-index animation switching and low-detail action availability.
- Original runtime comparison of shrink geometry, 30-second restoration, targeting,
and actor placement; native Windows gameplay verification remains required.
Regression checks validate original identities/dispatch, clip topology and shrink
geometry, authored VR04 actors, and a bounded timer control-flow projection.
They do not execute original code or establish original runtime equivalence.