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

+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.