Files
Neutron/docs/checkpoint/camera-ray-predicate.md
T

212 lines
12 KiB
Markdown
Raw 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.
# 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.