Files
Neutron/docs/checkpoint/collision-grid-traversal.md

8.2 KiB
Raw Permalink Blame History

C4: static grid traversal and retry ownership

2026-10-26. Recovered from EXE SHA256 f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8. These are source facts, with local algorithm fixtures; this investigation did not execute the original grid dispatcher. VAs below map to EXE offsets by subtracting 400000; uninitialized globals have no file-backed offset. The helper reports PE mapped offsets and raw bytes independently.

Dispatcher contract

47B4B0(actor interface, mutable previous-root Vec4 pointer, delta Vec4 by value, edge-enable byte) computes quick_magnitude(delta) at47B4BB. Actor member byte +42C, not a virtual method, forces processing. Otherwise magnitude below FLT_EPSILON(1.1920928955078125e-7;4D5E40) returns without moving the root. Equality processes. Candidate XYZ starts as previous+delta, W=1. Actor virtual260 returns radius. Bounds use extent E=radius+quick_magnitude(delta).

For C(v)=signed16(truncate(v*float(0.002)+130)), the frozen bounds are:

Bound Source expression
xmin min(C(previousX−E), C(candidateX−E))
xmax max(C(previousX+E), C(candidateX+E))
zmin min(C(previousZ−E), C(candidateZ−E))
zmax min(C(previousZ+E), C(candidateZ+E))

The asymmetric zmax is explicit:47B61B cmp di,ax;47B61E stores DI; 47B624 jl keeps DI if smaller, otherwise47B626 stores AX. xmax uses the opposite comparison at47B59B. Do not substitute a conventional swept-AABB union. Scale4D6A04 is float0.0020000000949949026; origin49B1FC is130.

X increases in the outer loop, Z in the inner, both inclusive. Coordinates outside 0..259 are skipped. Wall grid509B24 cell record is12bytes at grid+12*(260*x+z). Its pointer is the circular-list sentinel. Nodes contain next0, previous4, registration8. Registration contains polygon pointer0 and shape pointer4. Traversal follows next pointers in insertion order; the same polygon in several cells is visited repeatedly. Bounds stay frozen while the candidate mutates.

47B6B2 checks global collision-enable4F69E5 per node. A disabled visit still increments counters and advances the node; dispatcher position publication still occurs. Before47BBB0, member42C sets695D74=1 when nonzero;47B742 unconditionally clears it after the wrapper. This is the primitive's lower-edge override, separate from the caller's edge-enable flag, forwarded unchanged at47B6FE.

47BBB0 receives the previous root by value, the shared mutable candidate pointer, radius, stored polygon normal and edge flag. The first three source corners are fetched by477F10. A successful47BD80 result stores this polygon in 695D4C and writes the caller's local retry byte at47BD65..47BD6B. Nearest face 695D5C, nearest edge5CFBE0, hit point5CFBE8..5CFBF4 and695D4C persist across all visits; dispatcher entry does not clear them.

Retry, publication and callbacks

REA/Ghidra00.pseudo.txt incorrectly reports47B83C unreachable. Missing output parameter types hide47BBB0's retry-byte mutation. Instruction evidence is decisive: 47B535 clears local byte;47B799 tests it and47B79F branches to47B83C after a hit. 47B83C..47B867 replaces the by-value delta with candidate−*previousRoot. 47B877 pushes the same previous-root pointer, then actor, and47B879 recursively calls47B4B0 with the same edge flag. This body has no explicit recursion-depth guard;695D78 is an incremented statistic, not a limit. Do not infer dead code or a depth cap from decompiler output.

The previous-root pointer is not overwritten before retry. Only the deepest pass with no newly accepted contact writes candidate XYZ and W=1 to it (47B7A5..47B7BD). If695D4C is nonnull, that final pass reads the last accepted polygon normal+8/+C/+10/+14, even if this pass accepted no contact. It invokes actor virtual374 when normal.Y>−0.7, otherwise370; equality selects370. Both callbacks receive normal Vec4 and polygon pointer. Actor logical position is written later by the enclosing movement caller's virtual314, so publication through a stack vector does not itself prove the actor transform has changed.

The body integrator479D20 clears last polygon at47A038, initializes face distance to 130000 at47A03E (bits47FDE800), and edge distance to radius at47A062. The isolated primitive's −1 face sentinel is not the body-entry initialization. Dynamic reclip47B364 calls this same dispatcher with edges=false (47B30B), then publishes actor root through314 at47B399. It inherits nearest state: dynamic entry separately sets edge=radius at47AB3F and face=−1 at47AB4B. No dynamic clear of695D4C was found; identified absolute writes are47A038 and47BD65. Its caller schedule remains relevant when interpreting retained last-polygon callbacks.

Registration and source layout

479140 walks shape polygon array begin+88/end+8C in48byte strides; it applies checkpoint4794C0 and game-specific4797A0 filters before registration. Existing camera-ray evidence establishes scene44DBF0's ascending shape resource-index traversal. No new decorative/material rule is inferred here. Game filter4797A0 calls the game's virtual134 at4797EC.

Each polygon's all-corner X/Z extrema determine registration cells using the same conversion and inclusive X-outer/Z-inner order. Registration upper Z is a conventional maximum, unlike query zmax. A28byte registration allocation stores polygon0, shape4, centerXYZ8/C/10, W14 and radius18; bounds/candidate traversal do not use this center/radius as a per-visit cull. Record is shared across its cells. 479800 rejects a duplicate polygon pointer within one cell (47985E..479866), irrespective of shape pointer. New nodes append FIFO to all-grid5CFC7C (47989F..4798A8), and wall-grid509B24 only when stored normal.Y<0.7 (4798B3..4798CF); equality is excluded. There is no query-wide deduplication.

477F10(out,shape,polygon,signed-short corner) reads polygon+24 corner records, 20bytes each. Their first DWORD is a vertex index into shape+68 Vec4 vertices, 16bytes each. It copies the selected Vec4 without transforming it. The wrapper uses corners0/1/2 even though registration bounds use all corners.

Evidence and implementation boundary

Owned REA CLI session used a generated copy, closed normally and retained complete replies/export/snapshot in artifacts/collision-integration/grid/rea/:

Procedure Evidence ID
47B4B0 ev_f39128dafc2a3a20b5768613ce22b3c3168fe8653908837d92ad9a69ef5f2ad8
479140 ev_c6bffe721e0751327ecdb5e62c27137752574be6624c190a833c5b2c0f5be7b0
4797A0 ev_277ddc7e6b8383ea4245072e395a3dda51cd530c56fb160b917823803f55d33f

dispatcher.instructions.txt retains the reachable retry instructions; source-anchors.json records raw anchors, offsets, constants and four function-body hashes. tests/test_collision_grid_traversal.py guards source bytes plus five fixture groups: asymmetric bounds, clipped/inclusive order, per-cell duplicate rules, mutable candidate and retained nearest/last-polygon across passes.

Minimal integration: build source-order wall cells; pass an explicit shared nearest state into existing OriginalSphereResponse; scan frozen bounds with a mutable candidate; retry revised displacement against unchanged previous root; then publish and dispatch the last-polygon normal callback once. Reuse this dispatcher for dynamic reclip without adding implicit state resets. A defensive port recursion limit would be a documented implementation deviation, not recovered behavior.

Follow-up original dispatcher execution completed seven synthetic grid cases; see collision-body-probe.md for outputs, fixture boundaries and managed comparison. OriginalStaticCollision implements the bounded traversal as an isolated component; it is not yet the live player solver. Geometry-disabled traversal preserves terminal publication and retained callback; it skips primitive calls per visit. TraceSupport initializes its strict nearest limit to quick_magnitude(end−start). Prepared route geometry carries signed archive material IDs and rejects missing identity metadata before special-contact coverage is assessed.

Unresolved: x87 cell conversion at integer boundaries and extreme signed-short wrap; full scheduler ownership of global collision toggles and retained dynamic last-polygon state. The local projection does not establish numerical identity at those boundaries or runtime correctness of the integrated port.