Files
Neutron/docs/analysis/dynamic-collision.md

152 lines
8.2 KiB
Markdown

# Moving vertical-door collision
Read-only static recovery and bounded managed component,2026-10-24. Original
Neutron.exe SHA-256 f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8.
EXE text file offsets below are VA minus0x400000. No original code was executed
for this investigation. Source geometry/defaults are recovered; full response is
still injected and must not be called the original collision solver.
## Door defaults and activation
C3DDoorUpDown complete constructor4174F0 installs interface+C0 vtable4993AC.
| Evidence | Result |
| --- | --- |
|4175B0 ->4710C0 ->iface224/471A40|Entity pair collision enabled; current byte+140=true|
|4175C6/4175CA ->471730|Collision mode178/field124=2|
|4175CF/4175D2 ->471030 ->iface214/471A00|Own physics integration disabled; byte13E=false|
|417CAB/417CB2 ->iface110|PostLoad radius40, overriding automatically copied shape radius|
|40E410/40E413|HasCollision-1 retains constructor flags|
|40E427/40E433|Explicit HasCollision nonzero enables pairs and own integration|
|40E44B/40E457|Explicit HasCollision0 disables pairs and own integration|
Do not interpret own integration=false as a noncolliding door. Its entity pairs
remain enabled. Render visibility, current pair permission, world geometry checks,
own integration and authored CanMove are different flags. On HasCollision-1,
task visibility changes do not themselves execute the explicit pair-disable path;
the caller must track source activation flags without equating visible and solid.
CanMove is read at base40E0F0. After physical update462520, zero restores the
serialized origin through position/Euler setters40E103..40E15C. Nonzero permits
the current position to remain, allowing the door state machine's vertical motion.
It does not replace collision mode2 with a static world mesh.
## What the box actually uses
Shape-change hook462270 reads the current OMT shape's find_cube method through
complete slot44 at4622D4. This is the min/max of its local source vertex positions,
not a world-aligned bound of an already transformed rendered model. It forwards
min to iface2E8 at4622FB (storage1D4..1E0), max to iface2E0 at462325
(storage1C4..1D0). OMT find_cube1000AA80 computes all six values from shape vectors.
This justifies original local shape bounds; unrelated editor icons or a guessed
full-model world AABB are not substitutes.
47A776/47A7A5 retrieve these bounds.47A7EC..47A99B transforms all eight corners
through iface384=472980, using current Euler angles and root position. The point
method quantizes angles through the original trigonometric table. The bounded
component accepts a supplied local-to-world matrix; correctness of that matrix
for every nonzero authored Euler rotation remains the caller's responsibility.
The actual lab bars have zero rotation, so translation is unambiguous.
Corner bits:4 selects maxX,2 maxY,1 maxZ. The switch at47B3AC then emits these
twelve triangles, with the original diagonal choice/order preserved:
```text
0,1,2 1,3,2 0,2,4 2,6,4
4,6,5 6,7,5 5,7,3 5,3,1
0,4,1 4,5,1 2,3,7 7,6,2
```
The pure component rebuilds these triangles from the current door transform.
There is no persistent collider left at its closed root and no invented relative
door-motion sweep. Original47A5E0 similarly constructs the box at its current
pose, then obtains the other body's previous/current roots47AAD4/47AB0D.
## Dispatch, gates and response boundary
Global entity-pair loop47A430 requires both slot220 flags and mutual slot3A0
class/permission gates. At47A4CF/47A4E7 it checks collision mode178. If either
actor has mode2, it calls47A5E0 with that actor first; otherwise it calls the
ordinary root-sphere path47B3E0. Exclusions/class gates are inputs to the bounded
component; their complete class-specific behavior is not silently invented.
47A5F5 additionally requires the **other** actor's world-geometry flag1D0.
Root broadphase then uses quick_magnitude and these inclusive comparisons:
- Other actor mode2: distance<=boxRadius+otherRadius, then return contact directly
at47A712..47A72C/47B39F without the twelve-triangle response.
- Other modes: distance<=2*boxRadius+otherRadius, at47A73F..47A75B. Only candidates
passing this gate construct/sweep the oriented cube.
The second rule is a source quirk. Normal Jimmy radius60 and door radius40 give
**140 units**, despite the bars' much larger shape bounds. Do not enlarge it to
the graphic cube's bounding sphere while calling the result recovered behavior.
For every cube triangle,47B277 invokes shared sphere/triangle kernel47BD80 and
can invoke the other actor's normal response callback374 at47B29B. After all
twelve, box iface1E0 inhibits ordinary position response when true47B2EF..47B2F7.
Otherwise the candidate displacement is clipped against static world through
47B4B0 at47B364 before assigning the sphere root via314 at47B399. Thus a generic
sphere-vs-AABB overlap/push is not an exact translation of the original response.
## Implemented interface and tests
Game/DynamicSceneCollision.cs is deliberately bounded: source defaults and
HasCollision sentinel handling; pair/world-geometry gates; exact broadphase;
current oriented corners; exact twelve-triangle order; injected narrowphase;
contact-preserving response inhibition and second-mode2 shortcut.
DynamicBoxCollider takes identity, source root, local min/max, local-to-world
matrix, current radius, pair flag and response-inhibition flag. DynamicSphereMotion
takes previous/current root, radius and the relevant flags/mode. Resolve invokes
a supplied Func<DynamicBoxSweep,DynamicCollisionResponse>, or returns unchanged
when a recovered gate rejects it. The sweep contains all twelve SupportTriangles.
The callback must provide the still-unrecovered47BD80/static clipping response.
Source lab fixture: bars GAM offsetA29C, root(3810.1970,-1076.0883,-1180.4956),
HasCollision-1,CanMove1,OpenAmount500,rotation0. Its42 ASE source points convert
to local min(-223.8069,-18.7273,-16.8051),max(228.7926,391.2706,16.8051).
All raw points, including any nonvisible faces, contribute to these shape bounds.
Run from GamePort:
```sh
python3 tools/binary/dynamic_collision_evidence.py
source scripts/env.sh
dotnet run --project tests/GamePort.DynamicCollisionTests
```
The script checks26 original instruction sequences, all12 jump targets and all36
corner indices extracted directly from the bounded switch-case machine bytes.
It verifies the source class table, lab entity flags and ASE bound facts.
JSON evidence is artifacts/binary/dynamic-collision-evidence.json.
All10 managed groups pass: defaults/sentinel; inclusive140 broadphase and its
large-cube quirk; permission/geometry gates; oriented corners; source cube topology;
injected response/inhibition; mode2 shortcut; moving geometry; invalid inputs;
actual lab bars closed/open passage using the existing provisional swept-sphere
SceneCollision adapter. The latter verifies port integration, not original47BD80
or original runtime behavior. Full edge/vertex sphere response, static reclipping,
door pushing/crushing and native original comparison remain unresolved.
## Shared response continuation — 2026-11-07
[Dynamic context](../checkpoint/dynamic-context.md) now supplies17 complete
original mode2/static-reclip observations and a test-only C# composition. Twelve
captured kernel calls establish A,C,B argument winding relative to the construction
topology above, with the construction normal retained. Do not reverse live
construction topology indiscriminately. The injected live adapter is unchanged.
The original retains hit/last polygon, can invoke a stale static callback after
the dynamic hit, and publishes its local root after callbacks unless inhibited.
Empty-grid tests close that finite ownership contract, not nonempty shared-world
behavior, real actor responses or broad live admission. The source kernel itself
has since been recovered in collision-response/body reports; the older unresolved
wording above describes this report's original implementation checkpoint.
The [populated follow-up](../checkpoint/dynamic-reclip.md) adds14 exact full
observations and12 kernel-step matches, with source-store corrections in shared
edge/ray arithmetic. This closes the populated synthetic reclip contract without
replacing the live injected adapter. Real callbacks, live getter timing and
retained physical/helper order remain the admission boundary.