feat(render): Phase A8.F — PhysicsCameraCollisionProbe (swept-sphere eye via ResolveWithTransition)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/AcDream.App/Rendering/ICameraCollisionProbe.cs

@@ -0,0 +1,20 @@
+using System.Numerics;
+
+namespace AcDream.App.Rendering;
+
+/// <summary>
+/// Sweeps a small sphere from the camera pivot (player head) toward the
+/// desired eye and returns the stopped (non-penetrating) eye. The seam that
+/// lets <see cref="RetailChaseCamera"/> collide its eye without depending on
+/// the physics engine directly (and stay unit-testable with a fake).
+/// </summary>
+public interface ICameraCollisionProbe
+{
+    /// <summary>
+    /// Roll a collision sphere from <paramref name="pivot"/> to
+    /// <paramref name="desiredEye"/>; return the position it reaches without
+    /// penetrating geometry. Returns <paramref name="desiredEye"/> unchanged
+    /// when nothing blocks the path or when <paramref name="cellId"/> is 0.
+    /// </summary>
+    Vector3 SweepEye(Vector3 pivot, Vector3 desiredEye, uint cellId, uint selfEntityId);
+}

src/AcDream.App/Rendering/PhysicsCameraCollisionProbe.cs

@@ -0,0 +1,61 @@
+using System.Numerics;
+using AcDream.Core.Physics;
+
+namespace AcDream.App.Rendering;
+
+/// <summary>
+/// <see cref="ICameraCollisionProbe"/> backed by the player's swept-sphere
+/// engine. Ports retail's <c>SmartBox::update_viewer</c> (0x00453ce0): sweep
+/// the 0.3 m <c>viewer_sphere</c> from the head-pivot to the desired eye via a
+/// <c>CTransition</c> and use the stopped position. Reusing
+/// <see cref="PhysicsEngine.ResolveWithTransition"/> collides against indoor
+/// cell walls (<c>FindEnvCollisions</c>) AND outdoor/baked GfxObj shells
+/// (<c>FindObjCollisions</c>) in one faithful path.
+/// </summary>
+public sealed class PhysicsCameraCollisionProbe : ICameraCollisionProbe
+{
+    /// <summary>Retail <c>viewer_sphere</c> radius (acclient :93314).</summary>
+    public const float ViewerSphereRadius = 0.3f;
+
+    private readonly PhysicsEngine _physics;
+
+    public PhysicsCameraCollisionProbe(PhysicsEngine physics) => _physics = physics;
+
+    public Vector3 SweepEye(Vector3 pivot, Vector3 desiredEye, uint cellId, uint selfEntityId)
+    {
+        // No starting cell → nothing to sweep against; keep the desired eye.
+        if (cellId == 0) return desiredEye;
+
+        // SpherePath.InitPath puts sphere0's center at pathPos + (0,0,radius)
+        // (the player foot-capsule convention). Retail's viewer_sphere center is
+        // (0,0,0), so shift the path DOWN by the radius to make the SPHERE CENTER
+        // travel pivot→eye, then add it back to the swept stop position.
+        Vector3 begin = ToSpherePath(pivot,      ViewerSphereRadius);
+        Vector3 end   = ToSpherePath(desiredEye, ViewerSphereRadius);
+
+        var r = _physics.ResolveWithTransition(
+            currentPos:     begin,
+            targetPos:      end,
+            cellId:         cellId,
+            sphereRadius:   ViewerSphereRadius,
+            sphereHeight:   0f,                    // single sphere (no head sphere)
+            stepUpHeight:   0f,                    // no step-up for a camera
+            stepDownHeight: 0f,                    // no step-down / ground snap
+            isOnGround:     false,                 // no contact-plane / walkable semantics
+            body:           null,                  // no cross-frame persistence
+            moverFlags:     ObjectInfoState.None,  // all targets collide; also keeps
+                                                   // camera sweeps out of the #98
+                                                   // IsPlayer capture filter
+            movingEntityId: selfEntityId);         // skip the player's own ShadowEntry
+
+        return FromSpherePath(r.Position, ViewerSphereRadius);
+    }
+
+    /// <summary>Eye/pivot point → InitPath path point (subtract the sphere-center offset).</summary>
+    internal static Vector3 ToSpherePath(Vector3 spherePoint, float radius)
+        => spherePoint - new Vector3(0f, 0f, radius);
+
+    /// <summary>InitPath path point → eye point (add the sphere-center offset back).</summary>
+    internal static Vector3 FromSpherePath(Vector3 pathPoint, float radius)
+        => pathPoint + new Vector3(0f, 0f, radius);
+}

tests/AcDream.App.Tests/Rendering/PhysicsCameraCollisionProbeTests.cs

@@ -0,0 +1,43 @@
+using System.Numerics;
+using AcDream.App.Rendering;
+using AcDream.Core.Physics;
+using Xunit;
+
+namespace AcDream.App.Tests.Rendering;
+
+public class PhysicsCameraCollisionProbeTests
+{
+    // The probe must convert the desired eye path (where the SPHERE CENTER
+    // should travel) into the foot-capsule path InitPath expects (which offsets
+    // sphere0 up by radius), then invert it on the result. Verify the round trip.
+    [Fact]
+    public void SpherePathOffset_RoundTrips()
+    {
+        var p = new Vector3(10f, 20f, 30f);
+        const float r = 0.3f;
+
+        var path = PhysicsCameraCollisionProbe.ToSpherePath(p, r);
+        Assert.Equal(p.Z - r, path.Z, 5);
+        Assert.Equal(p.X, path.X, 5);
+        Assert.Equal(p.Y, path.Y, 5);
+
+        var back = PhysicsCameraCollisionProbe.FromSpherePath(path, r);
+        Assert.Equal(p.X, back.X, 5);
+        Assert.Equal(p.Y, back.Y, 5);
+        Assert.Equal(p.Z, back.Z, 5);
+    }
+
+    // cellId == 0 means "no starting cell" — the probe must short-circuit and
+    // return the desired eye without touching the engine.
+    [Fact]
+    public void SweepEye_NoStartingCell_ReturnsDesiredEyeUnchanged()
+    {
+        var probe = new PhysicsCameraCollisionProbe(new PhysicsEngine());
+        var pivot = new Vector3(0f, 0f, 1.5f);
+        var eye   = new Vector3(-2f, 0f, 2.2f);
+
+        var result = probe.SweepEye(pivot, eye, cellId: 0, selfEntityId: 0);
+
+        Assert.Equal(eye, result);
+    }
+}