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

8.2 KiB

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:

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.