Files

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