From 9cb15710bee190640b627dc5c7b9bc43dd6e30f2 Mon Sep 17 00:00:00 2001
From: Erik <erik.nihlen@gmail.com>
Date: Tue, 2 Jun 2026 08:51:55 +0200
Subject: [PATCH] =?UTF-8?q?feat(core):=20UCG=20Stage=201=20=E2=80=94=20Obj?=
 =?UTF-8?q?Cell=20base=20+=20CellPortal?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces AcDream.Core.World.Cells namespace with the two foundational
types for the Unified Cell Graph. CellPortal is a readonly struct
unifying the three legacy portal representations; ObjCell is the abstract
base for all traversable cells with the retail id-magnitude IsEnv
discriminator (CObjCell::GetVisible, pseudo_c:308215). Zero consumers;
zero behavior change. 5/5 tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/AcDream.Core/World/Cells/CellPortal.cs    | 32 ++++++++++++++
 src/AcDream.Core/World/Cells/ObjCell.cs       | 43 +++++++++++++++++++
 .../World/Cells/ObjCellBaseTests.cs           | 36 ++++++++++++++++
 3 files changed, 111 insertions(+)
 create mode 100644 src/AcDream.Core/World/Cells/CellPortal.cs
 create mode 100644 src/AcDream.Core/World/Cells/ObjCell.cs
 create mode 100644 tests/AcDream.Core.Tests/World/Cells/ObjCellBaseTests.cs

diff --git a/src/AcDream.Core/World/Cells/CellPortal.cs b/src/AcDream.Core/World/Cells/CellPortal.cs
new file mode 100644
index 0000000..456c5bd
--- /dev/null
+++ b/src/AcDream.Core/World/Cells/CellPortal.cs
@@ -0,0 +1,32 @@
+using System;
+using System.Collections.Generic;
+using System.Numerics;
+
+namespace AcDream.Core.World.Cells;
+
+/// <summary>
+/// Unified cell-to-cell portal edge. Superset of the three legacy portal types
+/// (render <c>CellPortalInfo</c>, physics <c>PortalInfo</c>, <c>PortalPlane</c>).
+/// Retail anchor: CCellPortal (acclient.h:32300).
+/// </summary>
+public readonly struct CellPortal
+{
+    public uint OtherCellId { get; }
+    public ushort OtherPortalId { get; }
+    public ushort PolygonId { get; }
+    public ushort Flags { get; }
+    /// <summary>Matches the physics <c>PortalInfo.PortalSide</c> convention (PortalInfo.cs:44).</summary>
+    public bool PortalSide => (Flags & 0x2) == 0;
+    /// <summary>Cell-local portal polygon vertices. Carried now; consumed by PView at Stage 3.</summary>
+    public IReadOnlyList<Vector3> PolygonLocal { get; }
+
+    public CellPortal(uint otherCellId, ushort otherPortalId, ushort polygonId, ushort flags,
+                      IReadOnlyList<Vector3>? polygonLocal = null)
+    {
+        OtherCellId = otherCellId;
+        OtherPortalId = otherPortalId;
+        PolygonId = polygonId;
+        Flags = flags;
+        PolygonLocal = polygonLocal ?? Array.Empty<Vector3>();
+    }
+}
diff --git a/src/AcDream.Core/World/Cells/ObjCell.cs b/src/AcDream.Core/World/Cells/ObjCell.cs
new file mode 100644
index 0000000..7fdb619
--- /dev/null
+++ b/src/AcDream.Core/World/Cells/ObjCell.cs
@@ -0,0 +1,43 @@
+using System.Collections.Generic;
+using System.Numerics;
+
+namespace AcDream.Core.World.Cells;
+
+/// <summary>
+/// Base for every cell the player can stand in. Retail anchor: CObjCell
+/// (acclient.h:30915). The id magnitude is the type discriminator
+/// (<see cref="IsEnv"/>): low-16 &gt;= 0x100 =&gt; indoor <see cref="EnvCell"/>,
+/// else outdoor <see cref="LandCell"/>.
+/// </summary>
+public abstract class ObjCell
+{
+    public uint Id { get; }
+    public Matrix4x4 WorldTransform { get; }
+    public Matrix4x4 InverseWorldTransform { get; }
+    public Vector3 LocalBoundsMin { get; }
+    public Vector3 LocalBoundsMax { get; }
+    public IReadOnlyList<CellPortal> Portals { get; }
+    public IReadOnlyList<uint> StabList { get; }
+    public bool SeenOutside { get; }
+
+    /// <summary>Retail magnitude dispatch (CObjCell::GetVisible, pseudo_c:308215).</summary>
+    public bool IsEnv => (Id & 0xFFFFu) >= 0x100u;
+
+    protected ObjCell(uint id, Matrix4x4 worldTransform, Matrix4x4 inverseWorldTransform,
+                      Vector3 localBoundsMin, Vector3 localBoundsMax,
+                      IReadOnlyList<CellPortal> portals, IReadOnlyList<uint> stabList,
+                      bool seenOutside)
+    {
+        Id = id;
+        WorldTransform = worldTransform;
+        InverseWorldTransform = inverseWorldTransform;
+        LocalBoundsMin = localBoundsMin;
+        LocalBoundsMax = localBoundsMax;
+        Portals = portals;
+        StabList = stabList;
+        SeenOutside = seenOutside;
+    }
+
+    /// <summary>Retail CObjCell::point_in_cell (vtable +0x84). Is a world point inside this cell?</summary>
+    public abstract bool PointInCell(Vector3 worldPoint);
+}
diff --git a/tests/AcDream.Core.Tests/World/Cells/ObjCellBaseTests.cs b/tests/AcDream.Core.Tests/World/Cells/ObjCellBaseTests.cs
new file mode 100644
index 0000000..8dbb5a2
--- /dev/null
+++ b/tests/AcDream.Core.Tests/World/Cells/ObjCellBaseTests.cs
@@ -0,0 +1,36 @@
+using System.Numerics;
+using AcDream.Core.World.Cells;
+using Xunit;
+
+namespace AcDream.Core.Tests.World.Cells;
+
+public class ObjCellBaseTests
+{
+    private sealed class StubCell : ObjCell
+    {
+        public StubCell(uint id)
+            : base(id, Matrix4x4.Identity, Matrix4x4.Identity,
+                   Vector3.Zero, Vector3.One,
+                   System.Array.Empty<CellPortal>(), System.Array.Empty<uint>(), false) { }
+        public override bool PointInCell(Vector3 worldPoint) => false;
+    }
+
+    [Theory]
+    [InlineData(0xA9B40174u, true)]
+    [InlineData(0xA9B40005u, false)]
+    [InlineData(0xA9B40100u, true)]
+    [InlineData(0xA9B400FFu, false)]
+    public void IsEnv_DispatchesByLow16Magnitude(uint id, bool expected)
+        => Assert.Equal(expected, new StubCell(id).IsEnv);
+
+    [Fact]
+    public void Ctor_StoresBaseProperties()
+    {
+        var c = new StubCell(0xA9B40174u);
+        Assert.Equal(0xA9B40174u, c.Id);
+        Assert.Equal(Vector3.One, c.LocalBoundsMax);
+        Assert.Empty(c.Portals);
+        Assert.Empty(c.StabList);
+        Assert.False(c.SeenOutside);
+    }
+}