149 lines
7.1 KiB
Markdown
149 lines
7.1 KiB
Markdown
# 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.
|