Files

7.1 KiB
Raw Permalink Blame History

Shrink-ray heading recovery

This closes the heading dependency of the held shrink-ray scan in 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:

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:

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/:

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.