Merge branch 'claude/quirky-jepsen-fd60f1' — N.4-N.10 strategy revision

docs/plans/2026-04-11-roadmap.md

@@ -1,6 +1,6 @@
 # acdream — strategic roadmap
 
-**Status:** Living document. Updated 2026-05-08 for Phase N.3 (texture decode via WB TextureHelpers) shipping.
+**Status:** Living document. Updated 2026-05-08 for Phase N.3 shipping + N.4-N.9 strategy revision (rendering rebuild on shared WB infrastructure rather than independent substitutions).
 **Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file.
 
 ---
@@ -604,41 +604,57 @@ for our deletions/additions; merge upstream `master` periodically.
   byte-identical equivalence per format** before substitution; updated
   `SurfaceDecoderTests` to match the new A8 split semantics. Visual
   verification at Holtburg passed 2026-05-08 — no texture regressions.
-- **N.4 — Object meshing.** Replace `SetupMesh.cs` + `GfxObjMesh.cs`
-  with calls to WB's `ObjectMeshManager`. Character-appearance
-  behaviors (CreaturePalette / GfxObjRemapping / HiddenParts) remain
-  ours — ACME is the secondary oracle. **Realistic estimate: 1.5-2
-  weeks** (was 1) — character appearance edge cases like N.1's
-  rotation bug will surface.
-- **N.5 — Terrain rendering.** Replace `TerrainChunkRenderer` +
-  `TerrainAtlas` + `TerrainBlending` with WB's `TerrainRenderManager` +
-  `LandSurfaceManager` + `TerrainGeometryGenerator`. **Realistic
-  estimate: 3-4 weeks** (was 2) — largest single phase, GPU-buffer
-  ownership shifts, integration with our streaming loader is
-  non-trivial.
-- **N.6 — Static objects rendering.** Replace `StaticMeshRenderer` +
-  `InstancedMeshRenderer` with WB's `StaticObjectRenderManager`.
-  **Realistic estimate: 2-3 weeks** (was 2) — interacts with N.4
-  output.
+- **N.4 — Rendering pipeline foundation.** **Rebranded from "object
+  meshing" 2026-05-08 after brainstorm.** WB's `ObjectMeshManager` is
+  not a static helper — it's a 2070-line stateful asset pipeline that
+  owns GPU resources (VAO/VBO/IBO), an LRU cache + memory budget,
+  background staging, a shared texture atlas, and a bindless rendering
+  path. Adopting it wholesale is the foundation that N.5 + N.6 + N.7
+  build on. Concretely: (1) integrate `ObjectMeshManager` +
+  `TextureAtlasManager` as the shared infrastructure; (2) build a
+  per-instance customization layer that threads `CreaturePalette` /
+  `GfxObjRemapping` / `HiddenParts` / `TextureChanges` / `SubPalettes` /
+  `AnimPartChange` through WB's atlas keys; (3) extend WB's
+  `MeshBatchData` to carry our surface metadata (`Translucency` /
+  `Luminosity` / `Diffuse` / `SurfOpacity` / `NeedsUvRepeat` /
+  `DisableFog`) — likely a fork patch on the `acdream` branch; (4)
+  decide animation cache strategy (per-frame transform via uniform/SSBO
+  vs. cache invalidation); (5) adapter from our streaming loader's
+  Setup/Static spawn events to WB's `IncrementRefCount` lifecycle.
+  **Estimate: 3-4 weeks.** No visible change yet — visual verification =
+  "world looks identical to before." Foundation enables the next phases.
+- **N.5 — Terrain rendering.** Wire WB's `TerrainRenderManager` +
+  `LandSurfaceManager` + `TerrainGeometryGenerator` onto the foundation
+  N.4 builds. Closes N.2's deferred terrain math substitution: visual
+  mesh and physics both switch to WB's `CalculateSplitDirection` +
+  `GetHeight` + `GetNormal` in lockstep, resolving ISSUE #51. **Estimate:
+  2-3 weeks** (was 3-4 — atlas + GPU pipeline already in place from N.4).
+- **N.6 — Static objects rendering.** Wire WB's
+  `StaticObjectRenderManager` onto N.4's foundation; replace our
+  `StaticMeshRenderer` + `InstancedMeshRenderer`. Mostly draw
+  orchestration at this point — most of the substance landed in N.4.
+  **Estimate: 1-2 weeks** (was 2-3).
 - **N.7 — EnvCells / dungeons.** Replace EnvCell rendering with WB's
-  `EnvCellRenderManager` + `PortalRenderManager`. **Realistic
-  estimate: 2-3 weeks** (was 2).
+  `EnvCellRenderManager` + `PortalRenderManager` on top of N.4's
+  foundation. **Estimate: 1-2 weeks** (was 2-3 — naturally smaller now
+  that infrastructure is shared).
 - **N.8 — Sky + particles.** Replace sky rendering + particle pipeline
   (#36 / C.1 work) with WB's `SkyboxRenderManager` +
-  `ParticleEmitterRenderer`. **Realistic estimate: 1.5-2 weeks**
-  (was 1) — visual continuity matters; we just shipped C.1 and that
-  work flows through here.
+  `ParticleEmitterRenderer`. **Estimate: ~1 week** (was 1.5-2 — C.1
+  already shipped most of this; N.8 is glue + sampler-object reuse).
 - **N.9 — Visibility / culling.** Replace `CellVisibility` +
-  `FrustumCuller` with WB's `VisibilityManager`. **Realistic
-  estimate: 1 week** (was 3-5 days) — affects perf and what gets
-  drawn.
+  `FrustumCuller` with WB's `VisibilityManager`. **Estimate: ~1 week**
+  (was 3-5 days, slight bump for streaming-loader interaction).
 - **N.10 — GL infrastructure consolidation (optional).** Replace our
   `Shader` / `TextureCache` / `SamplerCache` plumbing with WB's
-  `ManagedGL*` wrappers + `OpenGLGraphicsDevice`. ~1 week.
+  `ManagedGL*` wrappers + `OpenGLGraphicsDevice`. **Largely subsumed by
+  N.4** — `OpenGLGraphicsDevice` arrives as the host of `ObjectMeshManager`
+  and atlas. May not need a dedicated phase; revisit after N.6.
 
-**Estimated calendar:** **3-4 months / 10-12 engineering weeks for
-N.2-N.9 (skipping N.10).** (Was 2-3 months / 6-8 weeks — revised
-upward after N.1 landed; realistic per-phase numbers above.)
+**Estimated calendar:** **2.5-3 months / 9-13 engineering weeks for
+N.4-N.9 (N.10 likely subsumed; N.2 folded into N.5; N.3 shipped).**
+Revised 2026-05-08 after recognizing N.4-N.6 are one rendering rebuild
+on shared infrastructure rather than three independent substitutions.
 
 **Each sub-phase:**
 - Ships behind `ACDREAM_USE_WB_<NAME>=1` flag.