feat(core): Phase B.3 — PhysicsEngine (top-level collision resolver)

Combines TerrainSurface + CellSurface into a single Resolve() API
that handles outdoor terrain walking, indoor floor walking,
outdoor<->indoor cell transitions, step-height enforcement, and
ground detection.

Step-height blocks upward Z deltas exceeding the limit (walls,
cliffs); downhill movement is always accepted. Indoor transitions
pick the cell whose floor Z is closest to the entity's current Z
(handles multi-story buildings). Reports IsOnGround=false when
no landblock or surface covers the entity's position (gravity
applied by the caller).

One API mismatch fixed vs plan: plan encoded the upper 16 landblock
bits into the returned cell ID, but the tests assert the raw cell ID
(0x0100, <0x0100) — so Resolve returns targetCellId directly.

6 new tests covering flat terrain, slopes, step-height rejection,
indoor entry/exit, and void detection. 243 total, all green.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

tests/AcDream.Core.Tests/Physics/PhysicsEngineTests.cs

@@ -0,0 +1,166 @@
+using System;
+using System.Collections.Generic;
+using System.Numerics;
+using AcDream.Core.Physics;
+using Xunit;
+
+namespace AcDream.Core.Tests.Physics;
+
+public class PhysicsEngineTests
+{
+    private static float[] LinearHeightTable()
+    {
+        var table = new float[256];
+        for (int i = 0; i < 256; i++) table[i] = i * 1.0f;
+        return table;
+    }
+
+    private static byte[] FlatHeightmap(byte value = 50)
+    {
+        var heights = new byte[81];
+        Array.Fill(heights, value);
+        return heights;
+    }
+
+    private PhysicsEngine MakeFlatEngine(float terrainZ = 50f)
+    {
+        var engine = new PhysicsEngine();
+        var terrain = new TerrainSurface(FlatHeightmap((byte)terrainZ), LinearHeightTable());
+        engine.AddLandblock(0xA9B4FFFFu, terrain, Array.Empty<CellSurface>(),
+            worldOffsetX: 0f, worldOffsetY: 0f);
+        return engine;
+    }
+
+    [Fact]
+    public void Resolve_FlatTerrain_ZMatchesTerrain()
+    {
+        var engine = MakeFlatEngine(terrainZ: 50f);
+
+        var result = engine.Resolve(
+            new Vector3(96f, 96f, 50f), cellId: 0x0001, delta: new Vector3(1f, 0f, 0f),
+            stepUpHeight: 2f);
+
+        Assert.Equal(50f, result.Position.Z, precision: 1);
+        Assert.True(result.IsOnGround);
+    }
+
+    [Fact]
+    public void Resolve_WalkUpSmallSlope_Accepted()
+    {
+        // Heights slope from 50 to 52 across X — small enough for step height.
+        var heights = new byte[81];
+        for (int x = 0; x < 9; x++)
+            for (int y = 0; y < 9; y++)
+                heights[x * 9 + y] = (byte)(50 + x / 4);  // gentle slope
+
+        var engine = new PhysicsEngine();
+        var terrain = new TerrainSurface(heights, LinearHeightTable());
+        engine.AddLandblock(0xA9B4FFFFu, terrain, Array.Empty<CellSurface>(),
+            worldOffsetX: 0f, worldOffsetY: 0f);
+
+        var result = engine.Resolve(
+            new Vector3(48f, 96f, 50f), cellId: 0x0001, delta: new Vector3(48f, 0f, 0f),
+            stepUpHeight: 5f);
+
+        Assert.True(result.IsOnGround);
+        Assert.True(result.Position.Z >= 50f);  // moved uphill
+    }
+
+    [Fact]
+    public void Resolve_StepUpExceedsHeight_MovementBlocked()
+    {
+        // Heights jump sharply: left half = 50, right half = 100.
+        var heights = new byte[81];
+        for (int x = 0; x < 9; x++)
+            for (int y = 0; y < 9; y++)
+                heights[x * 9 + y] = (byte)(x < 5 ? 50 : 100);
+
+        var engine = new PhysicsEngine();
+        var terrain = new TerrainSurface(heights, LinearHeightTable());
+        engine.AddLandblock(0xA9B4FFFFu, terrain, Array.Empty<CellSurface>(),
+            worldOffsetX: 0f, worldOffsetY: 0f);
+
+        // Try to walk from the low side to the high side.
+        var result = engine.Resolve(
+            new Vector3(96f, 96f, 50f), cellId: 0x0001, delta: new Vector3(48f, 0f, 0f),
+            stepUpHeight: 2f);
+
+        // Movement should be blocked — Z delta (50→100) exceeds step height (2).
+        Assert.Equal(96f, result.Position.X, precision: 1);  // didn't move
+        Assert.True(result.IsOnGround);
+    }
+
+    [Fact]
+    public void Resolve_EnterIndoorCell_TransitionsToCell()
+    {
+        var engine = new PhysicsEngine();
+        var terrain = new TerrainSurface(FlatHeightmap(50), LinearHeightTable());
+
+        // Indoor cell with a floor at Z=55 covering (40..60, 40..60).
+        var cellVerts = new Dictionary<ushort, Vector3>
+        {
+            [0] = new(40f, 40f, 55f),
+            [1] = new(60f, 40f, 55f),
+            [2] = new(60f, 60f, 55f),
+            [3] = new(40f, 60f, 55f),
+        };
+        var cellPolys = new List<List<short>> { new() { 0, 1, 2, 3 } };
+        var cell = new CellSurface(0x0100, cellVerts, cellPolys);
+
+        engine.AddLandblock(0xA9B4FFFFu, terrain, new[] { cell },
+            worldOffsetX: 0f, worldOffsetY: 0f);
+
+        // Walk from outdoor (30, 50) into the cell's floor area (50, 50).
+        var result = engine.Resolve(
+            new Vector3(30f, 50f, 50f), cellId: 0x0001, delta: new Vector3(20f, 0f, 0f),
+            stepUpHeight: 10f);
+
+        // Should transition to the indoor cell and snap to its floor Z.
+        Assert.Equal(0x0100u, result.CellId);
+        Assert.Equal(55f, result.Position.Z, precision: 1);
+        Assert.True(result.IsOnGround);
+    }
+
+    [Fact]
+    public void Resolve_LeaveIndoorCell_TransitionsToOutdoor()
+    {
+        var engine = new PhysicsEngine();
+        var terrain = new TerrainSurface(FlatHeightmap(50), LinearHeightTable());
+
+        var cellVerts = new Dictionary<ushort, Vector3>
+        {
+            [0] = new(40f, 40f, 55f),
+            [1] = new(60f, 40f, 55f),
+            [2] = new(60f, 60f, 55f),
+            [3] = new(40f, 60f, 55f),
+        };
+        var cellPolys = new List<List<short>> { new() { 0, 1, 2, 3 } };
+        var cell = new CellSurface(0x0100, cellVerts, cellPolys);
+
+        engine.AddLandblock(0xA9B4FFFFu, terrain, new[] { cell },
+            worldOffsetX: 0f, worldOffsetY: 0f);
+
+        // Start inside the cell, walk out.
+        var result = engine.Resolve(
+            new Vector3(50f, 50f, 55f), cellId: 0x0100, delta: new Vector3(-20f, 0f, 0f),
+            stepUpHeight: 10f);
+
+        // Should transition back to outdoor.
+        Assert.True(result.CellId < 0x0100u);
+        Assert.Equal(50f, result.Position.Z, precision: 1);
+        Assert.True(result.IsOnGround);
+    }
+
+    [Fact]
+    public void Resolve_NoSurfaceUnderEntity_NotOnGround()
+    {
+        var engine = new PhysicsEngine();
+        // No landblocks loaded — entity is floating in void.
+
+        var result = engine.Resolve(
+            new Vector3(0f, 0f, 100f), cellId: 0x0001, delta: Vector3.Zero,
+            stepUpHeight: 2f);
+
+        Assert.False(result.IsOnGround);
+    }
+}