Files
Neutron/docs/analysis/collision-checkpoint.md
T

144 lines
8.2 KiB
Markdown

# Controllable lab: provisional collision reconstruction
This checkpoint implements deterministic static geometric collision against the
extracted original scene. It is **not the recovered original collision solver**.
Remaining collision masks, class activation rules, tolerances,
step handling and controller state integration are still unresolved. No original
runtime comparison establishes collision fidelity.
## Source geometry and inclusion policy
`level1b.omt` SHA-256:
`5a33d11311fc222631eb8f7384d1863192cb1f55f7e67035caa0ae12fd9892ab`.
The existing read-only extractor produces
`artifacts/extracted/level1b/scene.json` in unchanged original Y-up world units:
8,607 expanded vertices and 2,869 triangles. Collision now excludes the18
triangles of shape94 ncwater, following the recovered NC shape-name gate at
44DD2F..44DD70. All2,851 other nondegenerate source triangles remain eligible,
independent of `Mesh.Draws`, texture or material resolution.
The actual lab has no degenerate triangles removed by this rule. Mesh vertex/index
arrays and original files are not modified.
The lab includes 45 draw ranges / 325 triangles referencing unresolved material18.
The renderer correctly skips those ranges under recovered null-material behavior
(see graphics.md). Names include `blockfan`, `blockfan01`, `blockfan02`,
`blockscreen`, `blockwaterthing`, `blockwindow`, `blockcrate*`, `phoneblock*`,
`doorblock*`, plus Box/Plane/Cylinder/Mesh objects. These names and simplified
surfaces support a proxy interpretation; they do not prove a complete original
collision mask. Rendering visibility alone is therefore not used to discard them.
The regression creates a mesh with no visible draws and proves its original
triangles still block movement.
The NC exclusion is a shape-name prefix rule, not a material heuristic. The shape
metadata already exists in prepared scene mesh records; vertex/index/render data
is preserved. Other activation/mask rules remain unresolved. See water-collision.md
and underground-route.md for source bytes and the actual passage regression.
Animated/dynamic scene entities are not added to this static mesh.
There is no invented room-sized collision box or coordinate clamp.
## Capsule coordinates and API
`src/GamePort/Game/SceneCollision.cs` accepts an extracted `Mesh` and provides:
- `Move(feetPosition, displacement, radius, height)` returns final feet `Position`,
final-support `Grounded`, and `HitCeiling`/`HitWall` impacts during the move.
- `GroundHeight(point, maxDrop, maxRise=0)` returns the highest triangle surface
inside the requested vertical interval at point.XZ. The default upper bound is
point.Y, so an overhead ceiling cannot replace the floor below a GAM root.
- `ClipCamera(target, desiredEye, radius=8)` sweeps a sphere from the camera target
toward the desired eye and stops at the first source surface.
The collision volume is a vertical capsule: its lower sphere center is feet.Y plus
radius, its upper center is feet.Y plus height minus radius. Height includes both
caps; all units retain original asset scale. Ground surfaces and ceiling undersides
are treated as two-sided geometry. The provisional walkable threshold is contact
normal.Y >=0.65 (about49.46 degrees); steeper contacts classify as walls. Skin is
0.05 world units; numerical tolerance is0.005. These constants are implementation
choices, not recovered original values.
The recovered standing Jimmy base bounds are Y=-64.6165..144.8196, height209.4361,
X width76.6604 (X=-34.1281..42.5323), and Z=-20.4173..49.0276. The collision code
does not assume a radius or a model-root offset. Callers supply dimensions and
render the base model with origin.Y=feet.Y-minBaseY. Regression radii24 and34.7
exercise both a narrower provisional torso volume and a larger standing volume;
neither is claimed as recovered. A base-mesh bounding radius can overestimate limbs
or underestimate a different animated pose, so it does not establish original
physics geometry.
At GAM root (5071.933105,26.661896,824.103943), the highest floor below root is
Y=0.5486332. Either tested radius stands at feet Y=0.59863245 after collision skin,
with no lateral spawn correction. GAM root data remains unchanged. The model's
negative base Y and the original actor-root offset remain separate from capsule
feet; the integrating controller is responsible for that transform.
## Algorithm and bounded behavior
Triangles are validated once; invalid indices/nonfinite positions are rejected,
and zero-area triangles are ignored. Per-triangle axis-aligned bounds only prune
queries; they are not solid collision volumes. Narrow-phase distance uses the
closest pair between the vertical capsule axis segment and a triangle: face
intersection, endpoint-to-triangle regions, and segment-to-each-edge distances.
This covers triangle edges and vertices that an axis-center ray would miss.
Movement first resolves initial overlaps, choosing the deepest contact for at most
12 passes. It then uses conservative advancement of capsule/triangle closest
features to find the earliest contact, with at most40 iterations per triangle.
The separating closest-pair plane supplies a safe advance; the finite-limit
fallback stops conservatively. Remaining motion is projected along the contact
plane and swept again, for at most8 slide passes. Support is queried at the final
position, so crossing a floor earlier does not keep the actor grounded after a
ledge. Falling/jumping actors are never snapped down by a ground-height query.
Face-region closest points use direct plane projection. When a closest contact
cannot be distinguished from that plane within0.005 units, its exact plane normal
is used. This avoids false horizontal normals from floating-point cancellation on
large coplanar triangle seams. Tests include far-apart vertices and original-scale
translated geometry. Float32 arithmetic is deterministic for the same input stream
on the tested .NET runtime; cross-architecture bit identity is not established.
Impossible spawn gaps, initially deeply intersecting solid volumes, more than8
successive slide constraints in one move, and extreme grazing feature sequences
can exhaust bounds and stop short. This is a bounded static checkpoint solver,
not a general rigid-body engine. There is no recovered stair step-up, moving
platform, entity collision, friction, original slope state, trigger or damage
behavior. Camera sweep does not depenetrate an initially embedded target.
## Verification
From GamePort, after normal asset preparation:
```bash
source scripts/env.sh
dotnet run --project tests/GamePort.CollisionTests/GamePort.CollisionTests.csproj
```
Eleven deterministic checks pass on local Linux .NET10. They compile linked
collision/Mesh/PNG sources without an additional NuGet test framework. Coverage:
flat support and bounded ground queries;10,000-unit floor/wall falls/sweeps;
wall sliding/departure; corner persistence; ceiling/underside; slope climbing and
landing; ledge departure; isolated triangle edges/vertices; camera sphere sweeps;
100,000-unit sweeps in a translated original-scale room;2,000 repeated floor-seam
moves; invisible proxy retention; malformed input; and actual lab data.
Actual lab tests use both radius24 and34.7, height209.4361. Two identical240-tick
traces at3 horizontal units/tick replay identically, stay finite/above the floor,
and travel720 units in the initial155-degree direction to approximately
(4767.5977,0.598948,171.56355). Six hundred eastward movement ticks encounter
original geometry and stop near these positions:
| Radius | X | Y | Z |
| --- | --- | --- | --- |
| 24 | 5405.448 | 0.601050 | 730.06195 |
| 34.7 | 5394.750 | 0.601352 | 724.18370 |
The small Z slide follows original source surfaces; no room boundary is supplied.
A synthetic jump trajectory using550 units/s initial speed and1064 units/s²
acceleration rises and lands back at (5071.933,0.598633,824.1037) for both radii.
Those trajectory inputs exercise the collision API and are not claimed as the
recovered complete jump state machine. Original-lab replay/wall/jump checks took
about0.5s combined locally, excluding scene loading/compilation.
These are algorithm and source-data tests. Controller/input/render integration,
GPU output and native Windows behavior require the primary checkpoint validation;
this report does not claim those tests ran as part of the isolated collision suite.