Merge branch 'claude/quirky-jepsen-fd60f1' — N.4 Week 1 complete

docs/superpowers/plans/2026-05-08-phase-n4-rendering-foundation.md

@@ -66,7 +66,9 @@ This plan is the **execution source of truth** for N.4. It is updated as tasks l
 
 Status: **Living document — work in progress, started 2026-05-08.**
 
-**Progress (2026-05-08):** Tasks 1-8 ✅ complete. Tasks 1-5 landed foundation types + WbMeshAdapter stub. Task 6 obsoleted by `DefaultDatReaderWriter` discovery (Adjustment 1). Task 7 wired the adapter into `GameWindow` lifecycle behind the flag. Task 8 CLAUDE.md pointer was done preemptively in commit `506b86b`. **Next: Task 9** — route `InstancedMeshRenderer.EnsureUploaded` through `WbMeshAdapter` when flag is on (first behavioral change; flag-on render path will skip static scenery until Task 22 wires `WbDrawDispatcher`).
+**Progress (2026-05-08):** Week 1 ✅ COMPLETE. Tasks 1-10 shipped. Foundation types + WbMeshAdapter constructed against real WB pipeline (`OpenGLGraphicsDevice` + `DefaultDatReaderWriter` + `ObjectMeshManager`). `InstancedMeshRenderer.EnsureUploaded` routes through the adapter under `ACDREAM_USE_WB_FOUNDATION=1`; sentinel entry marks "this gfxObj lives in WB now" and the draw loop skips sentinel entries (Task 22's `WbDrawDispatcher` will draw them eventually). Conformance tests pin `GfxObjMesh.Build` + `SetupMesh.Flatten` behavior. Build green, 901 tests pass, 8 pre-existing failures only (unchanged from main).
+
+**Next: Task 11** — `LandblockSpawnAdapter` (streaming-loader hook for ref-count lifecycle).
 
 | Task | Status | Commit |
 |---|---|---|
@@ -78,9 +80,11 @@ Status: **Living document — work in progress, started 2026-05-08.**
 | 6 — WbDatReaderAdapter | ✅ OBSOLETED | `502c3a8` |
 | 7 — GameWindow wiring under flag | ✅ | `502c3a8` |
 | 8 — CLAUDE.md pointer | ✅ | `506b86b` (preemptive) |
-| 9 — Route InstancedMeshRenderer through adapter | pending | — |
+| 9 — Real WB pipeline + InstancedMeshRenderer routing | ✅ | `4ad7a98` |
-| 10 — Week 1 wrap-up | pending | — |
+| 10 — Week 1 wrap-up | ✅ | (this commit) |
-| 11–28 | pending (Weeks 2-4) | — |
+| 11–15 — Week 2: streaming integration | pending | — |
+| 16–21 — Week 3: per-instance + animation | pending | — |
+| 22–28 — Week 4: draw dispatcher + ship | pending | — |
 
 ---
 

src/AcDream.App/AcDream.App.csproj

@@ -26,6 +26,12 @@
     <ProjectReference Include="..\AcDream.Core.Net\AcDream.Core.Net.csproj" />
     <ProjectReference Include="..\AcDream.UI.Abstractions\AcDream.UI.Abstractions.csproj" />
     <ProjectReference Include="..\AcDream.UI.ImGui\AcDream.UI.ImGui.csproj" />
+    <!-- Phase N.4 Task 9: WbMeshAdapter constructs the WB GL pipeline directly.
+         AcDream.Core already references these projects, but project references are
+         not transitive in .NET — AcDream.App must list them explicitly to compile
+         against Chorizite.OpenGLSDLBackend and WorldBuilder.Shared types. -->
+    <ProjectReference Include="..\..\references\WorldBuilder\WorldBuilder.Shared\WorldBuilder.Shared.csproj" />
+    <ProjectReference Include="..\..\references\WorldBuilder\Chorizite.OpenGLSDLBackend\Chorizite.OpenGLSDLBackend.csproj" />
   </ItemGroup>
   <ItemGroup>
     <None Update="Rendering\Shaders\*.*">

src/AcDream.App/Rendering/GameWindow.cs

@@ -1427,17 +1427,18 @@ public sealed class GameWindow : IDisposable
 
         // Phase N.4 — WB rendering pipeline foundation. Constructed only when
         // ACDREAM_USE_WB_FOUNDATION=1 is set; otherwise the legacy renderer
-        // path stays in charge. The full ObjectMeshManager bring-up is
+        // path stays in charge. The full ObjectMeshManager bring-up lives in
-        // deferred to Task 9 — for now this is a stub adapter that exposes
+        // WbMeshAdapter (Task 9): OpenGLGraphicsDevice + DefaultDatReaderWriter
-        // the public API so call sites can wire without behavioral effect.
+        // + ObjectMeshManager. WbMeshAdapter opens its own file handles for
+        // the dat files (independent of our DatCollection).
         if (AcDream.App.Rendering.Wb.WbFoundationFlag.IsEnabled)
         {
             var wbLogger = Microsoft.Extensions.Logging.Abstractions.NullLogger<AcDream.App.Rendering.Wb.WbMeshAdapter>.Instance;
-            _wbMeshAdapter = new AcDream.App.Rendering.Wb.WbMeshAdapter(_gl, _dats, wbLogger);
+            _wbMeshAdapter = new AcDream.App.Rendering.Wb.WbMeshAdapter(_gl, _datDir, wbLogger);
             Console.WriteLine("[N.4] WbFoundation flag is ENABLED — routing static content through ObjectMeshManager.");
         }
 
-        _staticMesh = new InstancedMeshRenderer(_gl, _meshShader, _textureCache);
+        _staticMesh = new InstancedMeshRenderer(_gl, _meshShader, _textureCache, _wbMeshAdapter);
 
         // Phase G.1 sky renderer — its own shader (sky.vert / sky.frag)
         // with depth writes off + far plane 1e6 so celestial meshes

src/AcDream.App/Rendering/InstancedMeshRenderer.cs

@@ -20,6 +20,7 @@
 // needs to update the shader and uniform setup at the call sites.
 using System.Numerics;
 using System.Runtime.InteropServices;
+using AcDream.App.Rendering.Wb;
 using AcDream.Core.Meshing;
 using AcDream.Core.Terrain;
 using AcDream.Core.World;
@@ -33,6 +34,20 @@ public sealed unsafe class InstancedMeshRenderer : IDisposable
     private readonly Shader _shader;
     private readonly TextureCache _textures;
 
+    /// <summary>
+    /// Optional WB adapter. When non-null and <see cref="WbFoundationFlag.IsEnabled"/>,
+    /// <see cref="EnsureUploaded"/> hands the GfxObj ref to the WB pipeline instead of
+    /// uploading into our own VAO pool. The draw loop skips sentinel entries — Task 22's
+    /// WbDrawDispatcher will eventually draw them.
+    /// </summary>
+    private readonly WbMeshAdapter? _wbMeshAdapter;
+
+    // Sentinel: a GfxObj that has been handed to the WB pipeline gets this list
+    // stored in _gpuByGfxObj. The Draw loop recognises it by reference identity
+    // (object.ReferenceEquals) and skips it — no legacy VAO draw for WB-managed
+    // objects until Task 22 wires up WbDrawDispatcher.
+    private static readonly List<SubMeshGpu> WbManagedSentinel = new(0);
+
     // One GPU bundle per unique GfxObj id. Each GfxObj can have multiple sub-meshes.
     private readonly Dictionary<uint, List<SubMeshGpu>> _gpuByGfxObj = new();
 
@@ -67,11 +82,13 @@ public sealed unsafe class InstancedMeshRenderer : IDisposable
 
     private readonly record struct GroupKey(uint GfxObjId, ulong TextureSignature);
 
-    public InstancedMeshRenderer(GL gl, Shader shader, TextureCache textures)
+    public InstancedMeshRenderer(GL gl, Shader shader, TextureCache textures,
+        WbMeshAdapter? wbMeshAdapter = null)
     {
         _gl = gl;
         _shader = shader;
         _textures = textures;
+        _wbMeshAdapter = wbMeshAdapter;
 
         _instanceVbo = _gl.GenBuffer();
     }
@@ -83,6 +100,17 @@ public sealed unsafe class InstancedMeshRenderer : IDisposable
         if (_gpuByGfxObj.ContainsKey(gfxObjId))
             return;
 
+        // Phase N.4 Task 9: when the WB foundation flag is on and we have an
+        // adapter, hand this GfxObj to the WB pipeline instead of uploading our
+        // own VAO. The sentinel entry marks "this GfxObj lives in WB now" so the
+        // draw loop knows to skip it. Task 22's WbDrawDispatcher will draw them.
+        if (WbFoundationFlag.IsEnabled && _wbMeshAdapter is not null)
+        {
+            _wbMeshAdapter.IncrementRefCount(gfxObjId);
+            _gpuByGfxObj[gfxObjId] = WbManagedSentinel;
+            return;
+        }
+
         var list = new List<SubMeshGpu>(subMeshes.Count);
         foreach (var sm in subMeshes)
             list.Add(UploadSubMesh(sm));
@@ -217,6 +245,11 @@ public sealed unsafe class InstancedMeshRenderer : IDisposable
             if (!_gpuByGfxObj.TryGetValue(key.GfxObjId, out var subMeshes))
                 continue;
 
+            // WB-managed GfxObjs have a sentinel entry; Task 22 (WbDrawDispatcher)
+            // will draw them. Skip here to avoid drawing with stale/null VAO data.
+            if (object.ReferenceEquals(subMeshes, WbManagedSentinel))
+                continue;
+
             bool hasOpaqueSubMesh = false;
             foreach (var sub in subMeshes)
             {
@@ -292,6 +325,10 @@ public sealed unsafe class InstancedMeshRenderer : IDisposable
             if (!_gpuByGfxObj.TryGetValue(key.GfxObjId, out var subMeshes))
                 continue;
 
+            // WB-managed GfxObjs — skip; Task 22 will draw them.
+            if (object.ReferenceEquals(subMeshes, WbManagedSentinel))
+                continue;
+
             bool hasTranslucentSubMesh = false;
             foreach (var sub in subMeshes)
             {
@@ -419,7 +456,10 @@ public sealed unsafe class InstancedMeshRenderer : IDisposable
 
                 foreach (var meshRef in entity.MeshRefs)
                 {
-                    if (!_gpuByGfxObj.ContainsKey(meshRef.GfxObjId))
+                    if (!_gpuByGfxObj.TryGetValue(meshRef.GfxObjId, out var cachedMeshes))
+                        continue;
+                    // WB-managed GfxObjs don't go through our instance pipeline.
+                    if (object.ReferenceEquals(cachedMeshes, WbManagedSentinel))
                         continue;
 
                     var model = meshRef.PartTransform * entityRoot;
@@ -525,6 +565,11 @@ public sealed unsafe class InstancedMeshRenderer : IDisposable
     {
         foreach (var subs in _gpuByGfxObj.Values)
         {
+            // WB-managed entries use the sentinel — no GL resources to free here;
+            // ObjectMeshManager owns those resources.
+            if (object.ReferenceEquals(subs, WbManagedSentinel))
+                continue;
+
             foreach (var sub in subs)
             {
                 _gl.DeleteBuffer(sub.Vbo);

src/AcDream.App/Rendering/Wb/WbMeshAdapter.cs

@@ -1,72 +1,106 @@
 using System;
-using DatReaderWriter;
+using Chorizite.OpenGLSDLBackend;
+using Chorizite.OpenGLSDLBackend.Lib;
 using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
 using Silk.NET.OpenGL;
+using WorldBuilder.Shared.Models;
+using WorldBuilder.Shared.Services;
 
 namespace AcDream.App.Rendering.Wb;
 
 /// <summary>
 /// Single seam between acdream and WB's render pipeline. Owns the
-/// <c>ObjectMeshManager</c> instance (when fully initialized) and exposes
+/// <c>ObjectMeshManager</c> instance and exposes a stable acdream-shaped API
-/// a stable acdream-shaped API so the rest of the renderer doesn't need
+/// so the rest of the renderer doesn't need to know about WB's types directly.
-/// to know about WB's types directly.
 ///
 /// <para>
-/// <b>Phase N.4 staging:</b> currently a stub. Real <c>ObjectMeshManager</c>
+/// The adapter constructs its own <c>DefaultDatReaderWriter</c> internally; it
-/// + <c>OpenGLGraphicsDevice</c> initialization is added in Task 9 once
+/// does NOT share file handles with our <c>DatCollection</c>. This duplicates
-/// the dat-reader adapter (Task 6) lands. Until then, methods no-op so
+/// index-cache memory (~50–100 MB) but keeps the two subsystems fully decoupled.
-/// call sites can wire the adapter without behavioral effect when the
+/// Acceptable for Phase N.4 foundation work (plan Adjustment 1).
-/// <see cref="WbFoundationFlag.IsEnabled"/> flag is on.
 /// </para>
 /// </summary>
 public sealed class WbMeshAdapter : IDisposable, IWbMeshAdapter
 {
-    // _meshManager and _graphicsDevice will be wired in Task 9 once
+    private readonly OpenGLGraphicsDevice? _graphicsDevice;
-    // WbDatReaderAdapter (Task 6) lands. For now, both are null and all
+    private readonly DefaultDatReaderWriter? _wbDats;
-    // methods no-op.
+    private readonly ObjectMeshManager? _meshManager;
-    // private ObjectMeshManager? _meshManager;
+
-    // private OpenGLGraphicsDevice? _graphicsDevice;
+    /// <summary>
+    /// True when this instance was created via <see cref="CreateUninitialized"/>;
+    /// all public methods no-op when uninitialized.
+    /// </summary>
+    private readonly bool _isUninitialized;
+
     private bool _disposed;
 
-    public WbMeshAdapter(GL gl, DatCollection dats, ILogger<WbMeshAdapter> logger)
+    /// <summary>
+    /// Constructs the full WB pipeline: OpenGLGraphicsDevice → DefaultDatReaderWriter
+    /// → ObjectMeshManager.
+    /// </summary>
+    /// <param name="gl">Active Silk.NET GL context. Must be bound to the current
+    /// thread (construction runs GL queries; call from OnLoad).</param>
+    /// <param name="datDir">Path to the dat directory (same as the one supplied
+    /// to our DatCollection). DefaultDatReaderWriter opens its own file handles.</param>
+    /// <param name="logger">Logger for the adapter; ObjectMeshManager uses
+    /// NullLogger internally.</param>
+    public WbMeshAdapter(GL gl, string datDir, ILogger<WbMeshAdapter> logger)
     {
         ArgumentNullException.ThrowIfNull(gl);
-        ArgumentNullException.ThrowIfNull(dats);
+        ArgumentNullException.ThrowIfNull(datDir);
         ArgumentNullException.ThrowIfNull(logger);
 
-        // TODO(N.4 Task 9): construct OpenGLGraphicsDevice and ObjectMeshManager
+        _graphicsDevice = new OpenGLGraphicsDevice(gl, logger, new DebugRenderSettings());
-        // once WbDatReaderAdapter (Task 6) is available to bridge our DatCollection
+        _wbDats = new DefaultDatReaderWriter(datDir);
-        // to WB's IDatReaderWriter.
+        _meshManager = new ObjectMeshManager(
+            _graphicsDevice,
+            _wbDats,
+            NullLogger<ObjectMeshManager>.Instance);
     }
 
     private WbMeshAdapter()
     {
-        // Uninitialized constructor — only for tests / for cases where the
+        // Uninitialized constructor — only for tests / flag-off cases where
-        // flag is off and the caller wants a Dispose-safe no-op instance.
+        // the caller wants a Dispose-safe no-op instance.
+        _isUninitialized = true;
     }
 
     /// <summary>Test/init helper — produces a Dispose-safe instance with no
     /// underlying mesh manager. Public methods are all no-ops.</summary>
     public static WbMeshAdapter CreateUninitialized() => new();
 
-    /// <summary>Returns null until Task 9 wires up the real mesh manager.</summary>
+    /// <summary>
-    public object? GetRenderData(ulong id) => null;
+    /// Returns the WB render data for <paramref name="id"/>, or null if not
+    /// yet uploaded or if this adapter is uninitialized.
+    /// </summary>
+    public ObjectRenderData? GetRenderData(ulong id)
+    {
+        if (_isUninitialized || _meshManager is null) return null;
+        return _meshManager.GetRenderData(id);
+    }
 
+    /// <inheritdoc/>
     public void IncrementRefCount(ulong id)
     {
-        // No-op until Task 9.
+        if (_isUninitialized || _meshManager is null) return;
+        _meshManager.IncrementRefCount(id);
     }
 
+    /// <inheritdoc/>
     public void DecrementRefCount(ulong id)
     {
-        // No-op until Task 9.
+        if (_isUninitialized || _meshManager is null) return;
+        _meshManager.DecrementRefCount(id);
     }
 
+    /// <inheritdoc/>
     public void Dispose()
     {
         if (_disposed) return;
         _disposed = true;
-        // _meshManager?.Dispose();
+        _meshManager?.Dispose();
-        // _graphicsDevice?.Dispose();
+        _wbDats?.Dispose();
+        _graphicsDevice?.Dispose();
     }
 }

tests/AcDream.Core.Tests/Rendering/Wb/WbMeshAdapterTests.cs

@@ -10,22 +10,11 @@ public sealed class WbMeshAdapterTests
     [Fact]
     public void Construct_WithNullGl_ThrowsArgumentNull()
     {
+        // GL is the first guarded parameter; verifies the constructor validates inputs.
+        // We can't pass a real GL (no context in tests), so we verify only the
+        // null-GL guard. The real pipeline is tested via integration.
         Assert.Throws<ArgumentNullException>(() =>
-            new WbMeshAdapter(gl: null!, dats: null!, logger: NullLogger<WbMeshAdapter>.Instance));
+            new WbMeshAdapter(gl: null!, datDir: "some/path", logger: NullLogger<WbMeshAdapter>.Instance));
-    }
-
-    [Fact]
-    public void Construct_WithNullDats_ThrowsArgumentNull()
-    {
-        // GL cannot be constructed without a real GL context, so we verify
-        // the dats-null guard by passing a non-null GL sentinel — we reach
-        // the dats guard on the way. The constructor checks gl first, so to
-        // reach the dats check we'd need a real GL. Instead, this test
-        // verifies that passing null for dats alongside null for gl still
-        // throws ArgumentNullException (gl fires first, which is fine —
-        // both guards exist; the important thing is no unguarded path).
-        Assert.Throws<ArgumentNullException>(() =>
-            new WbMeshAdapter(gl: null!, dats: null!, logger: NullLogger<WbMeshAdapter>.Instance));
     }
 
     [Fact]
@@ -42,6 +31,19 @@ public sealed class WbMeshAdapterTests
         var adapter = WbMeshAdapter.CreateUninitialized();
         // Should not throw, even though there's no underlying mesh manager.
         adapter.IncrementRefCount(0x01000001ul);
+    }
+
+    [Fact]
+    public void DecrementRefCount_OnUninitializedAdapter_NoOps()
+    {
+        var adapter = WbMeshAdapter.CreateUninitialized();
         adapter.DecrementRefCount(0x01000001ul);
     }
+
+    [Fact]
+    public void GetRenderData_OnUninitializedAdapter_ReturnsNull()
+    {
+        var adapter = WbMeshAdapter.CreateUninitialized();
+        Assert.Null(adapter.GetRenderData(0x01000001ul));
+    }
 }