Document architecture checkpoint and restore original task callback order

This commit is contained in:
UnixNight committed 2026-10-25 12:56:17 -04:00
1 parent 69d0187a21
commit 531883aaac
45 files changed
+2935 -43

No files matched your search

+211
View File
@@ -0,0 +1,211 @@
# C5 gate: source camera obstruction predicate
This is a bounded static continuation of `camera-audio-ui.md`, against the
unchanged Neutron.exe SHA-256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Originals were read only; no original instructions were executed. Modern runtime
code is unchanged. Preferred EXE VA → file offset is VA−0x400000 for all code,
vtable and initialized constants below. Zero-fill grid/output globals have no
physical file offset.
**Decision:** enough source evidence now exists to construct a separate static
camera segment-query adapter. It must preserve wall-grid priority, source cell
and insertion order, one-sided winding and first-hit return. Reusing the existing
nearest-hit support query or swept camera sphere would produce a different
algorithm. Full follow-camera integration still requires camera state continuity,
source angle/previous-eye handling and the remaining input-mode branches.
## Actual caller arguments and unused actor getter
Jimmy complete vtable4A3BDC, slot16C at4A3D48 (fileA3D48), resolves43B820.
Its caller439702..439714 (files39702..39714) supplies computed look target by
value and a pointer to computed desired eye. At43B820 entry let stack pointer beS:
| Entry address | Argument / location |
| --- | --- |
| S+4..S+13 |16-byte input look-target vector |
| S+14 | Desired-eye pointer |
| S−18 | Stack pointer after `sub14; push esi` |
| S−10..S−1 | Local16-byte actor-position getter output |
| S−14 | Local float return gain initialized1.0 |
Hex numbers in this table are offsets, e.g. S+14 means20 decimal bytes.
Both virtual310 calls43B83F and43B84E (files3B83F/3B84E) write local scratch.
Jimmy interface vtable4A373C slot310 at4A3A4C (fileA3A4C) is472300
(file71300), which copies interface fields214/218/21C/220 to its output and
returns with `ret4`; it has no callback or mutation side effect. The local
position vector is not copied to the ray arguments.
After loading end pointer `[esp+2C]` at43B854, caller pushes0 then copies the
desired eye to a16-byte argument. It reserves another16 and uses
`lea edx,[esp+40]` at43B868: this is exactlyS+4, the **incoming look target**,
not the getter output.43B874 calls47C210 with
`(lookPoint, desiredEye, twoSided=false)` and cleans24 hex bytes. The source
therefore has no actor-root ray origin or actor exclusion pointer here.
On hit43B884..43B8F4 reads shared hitXYZ5CFC60/64/68 and changes the pointed eye
to `lookPoint−.75*(lookPoint−hit)`. It returns1.5; miss returns initial1.0.
This caller-level fact corrects any description of25% movement toward actor root.
## Query priority: first wall hit, then first general hit
| Function | File offset | Contract |
| --- | --- | --- |
|47C210..47C279 |7C210..7C279 | Global enable gate; call wall query; immediate return on hit; otherwise all query |
|47C280..47C4A4 |7C280..7C4A4 | Rectangle scan of wall/ceiling static grid509B24 |
|47C4B0..47C6D4 |7C4B0..7C6D4 | Same scan of all-polygon static grid5CFC7C |
|469530..4695A9 |69530..695A9 | Build48-byte segment: start+0, delta+10, end/hit+20 |
|469A10..469B66 |69A10..69B66 | Fetch first three polygon corners, add supplied translation, call triangle kernel |
|469B70..469E26 |69B70..69E26 | Source-winding segment/triangle kernel; recovered earlier for support |
47C210 passes unchanged start/end and sidedness to both queries; the second is
**not a reverse-direction retry**. Wall call47C23D (file7C23D) returns immediately
47C249..47C24C on success; all-grid fallback is47C26C. Both scan functions reset
shared hit polygon/shape identity695D54/695D58 at entry and rebuild global segment
5CFC40. Camera hit output5CFC60 is that segment's+20 vector.
Within each scan,469A10 returns a bool and shared hit point. A true branch at
47C44C or47C67C immediately stores current polygon and shape pointers to
695D54/695D58 then returns true. There is **no nearest-distance comparison**.
Thus a farther wall polygon in the first eligible cell can win over a nearer wall
later in that list, or a nearer floor in the second grid. A successful wall pass
prevents the all-grid pass entirely. This is materially different from47C6E0
used by body support, which retains strictly nearer hits.
Global enable byte4F69E5 is initialized1 at physical fileF69E5, unlike the
zero-fill grids.47C210/280/4B0 independently test it; zero returns false. No
entity-radius, dynamic actor-pair query, visibility, renderer-layer mask, camera
near/far, or material-alpha test appears in the predicate or triangle-call path.
Those static lists were filtered at registration instead.
## Grid coordinates, traversal and insertion order
Float cell scale4D6A04 (fileD6A04) is exactly
`0.0020000000949949026f`, origin49B1FC (file9B1FC) is130.0f. Nominal cell width
is500 world units; use the stored float rather than exact decimal1/500 when
testing source boundaries. For X and Z independently:
```
index = int16(truncate_toward_zero(worldComponent * storedScale + 130))
```
47F940 (file7F940) changes x87 control rounding to truncation, converts through
signed64 and returns low32; query comparisons retain low signed16. Multiplication
and addition remain x87 intermediates before conversion. This matters for exact
cell boundaries and extreme coordinates; Python's double order oracle below is
not an original x87 execution probe. Normal route coordinates fit the grid.
47C2E2..47C386 converts both endpointX/Z values, takes componentwise minima and
maxima, and scans the full inclusive **axis-aligned endpoint-cell rectangle**,
not a DDA path or intersecting-cell distance order. Outer indexX increases;
inner indexZ increases.47C3A4..47C3C6 rejects index<0 or>=260. Cell record stride
is12 bytes; list-pointer address is `gridBase+12*(260*x+z)` with gridBase509B24
or5CFC7C. Record pointer addresses differ from their structure starts by4 bytes.
47C3DF..47C3EA fetches cell sentinel then first node. Node layout is next+0,
previous+4, polygon-registration pointer+8. Each polygon registration record
has polygon pointer+0 and shape pointer+4. Traversal follows next until sentinel;
47C44E..47C459 and47C67E..47C689 continue only after miss. A polygon spanning
multiple cells can be tested multiple times; there is no per-query visited set.
479800..47991B (file79800..7991B) registers into the general grid, rejects
duplicate polygon pointers **within that cell**, and appends new nodes at the
tail.479897..4798A8 sets new.next=sentinel/new.previous=oldTail then links it;
the query therefore visits FIFO registration order, not reversed insertion.
It also appends to the wall grid when **stored polygon normal.Y<0.7f** at
4798B3..4798CF; equality is excluded. Threshold48D974 (file8D974) is the same
float used elsewhere for objective timing, which does not establish shared logic.
479140 (file79140) iterates the source shape polygon array in48-byte increments
at479473..479482. It calculates each polygon's XZ vertex bounds, converts extrema
with the same scale/origin/truncation, and registers the polygon in every cell of
that inclusive rectangle479336..479400. Centroid/radius data are retained in the
registration record, but this camera scan does not consult them for nearestness.
Shared scene loader44DBF0 uses shape resource ID/index initialized0 at44DC21,
fetches with477BA0, increments at44DEAF and tests existence through477C10. For
the three route archives shape IDs are ascending; current file enumeration order
also happens to be ascending, but an adapter should use source shape IDs and
polygon array indices explicitly. Port merged render-draw order is not evidence
for source registration order. The source's behavior at a missing intermediate
shape ID should be preserved or separately investigated before generic reuse.
## Registration filters and route asset coverage
Shared loader lowercases the first two shape-name characters and skips terrain
InitPhysics for NC prefix:44DD2F/44DD64/44DD67 (files4DD2F/4DD64/4DD67).
The ordinary path calls terrain interface2C at44DD6D →464B00 →479140 at464B18.
This excludes a complete NC shape from **both** grids, without removing its draw
geometry. Details and exact source shape payload offsets are in
`../analysis/water-collision.md`.
For remaining shapes4791C7..4791E5 first excludes checkpoint materials via
4794C0 then calls game polygon callback4797A0/virtual134. Null material causes
checkpoint filter false at4794E8; retain such polygons. Route game complete
vtables CLevel01BGame4C3CD0, CLevelVR044CE910 and CLevel01Game4C5A80 all have
slot134→475CD0, which returns false. These three scenes add no exclusion through
that hook. Do not generalize to every level callback.
Fresh decoded data from originals, after NC/checkpoint gates:
| Archive | Registered polygons | Wall-grid eligible | NC excluded | Checkpoint excluded |
| --- | --- | --- | --- | --- |
|level1b.omt |2851 |2483 |18 |0 |
|VR04.omt |508 |420 |0 |0 |
|level1.omt |5231 |3860 |24 |0 |
All remaining route polygons have exactly3 corners.469A10 fetches only first
three corners through477F10 (file77F10); registration bounds use all corners.
This distinction is immaterial for these archives, but cannot justify blindly
fan-triangulating larger original polygons for a future source camera query.
477F10 indexes polygon corner data then raw shape vertices+68; it applies no
terrain transform.469A10 adds supplied translation, which these grid queries
pass as identity vector(0,0,0,1). Runtime moving-body collision is separate.
Route OMT hashes and counts are printed by the new helper; source files remain
untouched. Layer509A30 versus509A3C far masks belong to rendering, not these
camera-obstruction grids.
## Triangle acceptance and offset84C clarification
Camera passesfalse sidedness.469B70 normalizes segment direction using the
recovered OMT quick magnitude, accepts source determinant<=−epsilon, barycentric
u/v edges inclusive, t>=0 but **t<segmentLength**. Constants4D5E40/44 are
±1.1920928955078125e−7. Source endpoint rejection469DDF..469DEE is strict;
do not invent a camera-radius skin or reject t=0. Full kernel/math evidence is
in `../analysis/original-collision.md`; its managed support implementation already
contains the winding/quick-magnitude algorithm, but its nearest-hit reducer must
not be reused unchanged for this query.
Offset84C is a camera-input adjustment, not recovered ground clearance. It is
initialized10 in Player437602 and Jimmy4228DE (files37602/228DE); walking resets
10 at438CC6 when complete virtual15C is false and controller mode4F0588!=6.
When virtual15C is true and mode6,438C64..438C7E adds mouse-relative vertical
delta*dt (mouse delta reader46A460); analog/forward/back paths438C86..438CB4
adjust by ±20*dt (constant495324,file95324). Other state/reset writers exist
428723 and class-specific4083A2/408685; do not rename the flag15C or claim the
whole camera-input mode recovered. At default10, source formulas produce
eye200−2*10=180 and look80+1.9*10=99, explaining the port's fixed offsets.
## Verification, remaining gates and implementation boundary
`tools/binary/checkpoint_camera_ray.py ../Original` verifies33 source anchors,
prints mapped constants/hashes/counts and exposes a bounded order reference.
`python3 -m unittest discover -s tests -p 'test_checkpoint_camera_ray.py' -v`
passes4 tests: source+route data, inclusive X/Z ordering/truncation, deliberately
farther wall-first result, and duplicate-cell tests/fallback/disabled gate.
Synthetic acceptance callbacks test query ownership/order, not original ray
arithmetic execution. No GPU/runtime/original timing fidelity is claimed.
A coherent adapter can now preserve source registration IDs, stored normals and
filters; construct sparse12-byte-equivalent cell lists in FIFO order; reuse the
source segment kernel with first-hit reduction; and expose source-enabled flag,
hit identity/point and gain. Verify synthetic farther-before-nearer, wall-before-
floor, winding/endpoint, repeated cells, negative coordinate and NC cases before
camera integration. Test route against the current playable baseline separately.
Still open: source x87 boundary equality on exact grid thresholds; negative/extreme
integer conversion overflow; missing intermediate shape IDs; explicit nonidentity
terrain transform consumers; further84C/input modes; and shared viewport/previous
camera update phase during control handoff. These limit whole-camera fidelity,
but do not justify retaining nearest-sphere behavior as the source static query.