# Phase N.1 — Scenery via WorldBuilder Helpers Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Replace the in-line algorithm guts of `SceneryGenerator.Generate()` with calls to WorldBuilder's `SceneryHelpers` (Displace / RotateObj / ScaleObj / CheckSlope / ObjAlign) and `TerrainUtils` (OnRoad / GetNormal). Keep our data flow, our `ScenerySpawn` shape, and our renderer integration. Place behind a `ACDREAM_USE_WB_SCENERY=1` feature flag, prove equivalence with helper-level conformance tests, then flip default-on after visual verification at landblock `0xA9B1`.
**Architecture:** Strangler-fig substitution. The 9×9 vertex loop, scene-selection hash, frequency roll, bounds check, building grid, and `BaseLoc.Z` handling stay identical. Only the five algorithm calls (displacement, road test, slope normal, rotation, scale) get replaced. A small adapter `WbSceneryAdapter.BuildTerrainEntries(LandBlock)` produces the `TerrainEntry[]` shape WB's helpers expect.
**Tech Stack:** .NET 10 / C# 13, Silk.NET (transitively), `WorldBuilder.Shared` + `Chorizite.OpenGLSDLBackend` (project references already wired up in Phase N.0), DatReaderWriter for `LandBlock` / `Region` / `ObjectDesc` / `Scene` types, xUnit for tests.
**Spec:** `docs/superpowers/specs/2026-05-08-phase-n1-scenery-via-wb-helpers-design.md`
**Parent design:** `docs/superpowers/specs/2026-05-08-phase-n-worldbuilder-migration-design.md`
**Inventory:** `docs/architecture/worldbuilder-inventory.md`
**Prerequisite:** Phase N.0 already shipped (commit `c8782c9`) — `references/WorldBuilder/` is a git submodule pointing at `github.com/eriknihlen/WorldBuilder.git` `acdream` branch; `AcDream.Core.csproj` references `WorldBuilder.Shared` + `Chorizite.OpenGLSDLBackend`.
---
## File Plan
| File | Disposition | Responsibility |
|---|---|---|
| `src/AcDream.Core/World/WbSceneryAdapter.cs` | NEW | `LandBlock` (acdream's dat type) → `TerrainEntry[]` (WB's data shape). Stateless. |
| `src/AcDream.Core/World/SceneryGenerator.cs` | MODIFY | Add `UseWbScenery` feature-flag flag. Add `GenerateViaWb` private alternative path. Wire dispatch in `Generate()`. Keep legacy methods for now — deleted in final task. |
| `tests/AcDream.Core.Tests/World/WbSceneryAdapterTests.cs` | NEW | Verify field bit-packing round-trips (Road, Type, Scenery, Height) and bounds-check behavior. |
| `tests/AcDream.Core.Tests/World/SceneryWbConformanceTests.cs` | NEW | Five small tests proving WB's `Displace`/`OnRoad`/`GetNormal`/`RotateObj`/`ScaleObj` match our existing inline logic for representative inputs. |
| `tests/AcDream.Core.Tests/World/SceneryGeneratorTests.cs` | MODIFY | After Task 7 (legacy delete), prune the now-irrelevant `DisplaceObject_*` tests and update class doc. |
**Why split adapter into its own file:** the adapter is a pure stateless utility. Putting it in its own file keeps `SceneryGenerator.cs` focused on the generator algorithm, and makes the adapter trivially reusable in N.2+ (terrain math helpers will need the same `TerrainEntry[]`).
**Why combine conformance tests in one file:** all five tests share the same imports and fixtures, and they all measure the same thing (helper equivalence). Splitting would be over-decomposed.
---
## Task 1: LandBlock → TerrainEntry[] adapter
**Files:**
- Create: `src/AcDream.Core/World/WbSceneryAdapter.cs`
- Test: `tests/AcDream.Core.Tests/World/WbSceneryAdapterTests.cs`
- [ ] **Step 1.1: Write the failing test**
Create `tests/AcDream.Core.Tests/World/WbSceneryAdapterTests.cs`:
```csharp
using AcDream.Core.World;
using DatReaderWriter.DBObjs;
namespace AcDream.Core.Tests.World;
///
/// Tests for . The adapter converts our
/// LandBlock dat type (Terrain ushort[81] + Height byte[81]) into
/// WorldBuilder's [81]
/// shape, which WB's TerrainUtils / SceneryRenderManager consume.
///
/// Bit layout in our LandBlock.Terrain[i] (ushort):
/// bits 0-1 : Road (2 bits, ACViewer convention)
/// bits 2-6 : TerrainType (5 bits) → WB calls this Texture
/// bits 11-15 : SceneType (5 bits) → WB calls this Scenery
/// Height comes from LandBlock.Height[i] (byte).
///
public class WbSceneryAdapterTests
{
[Fact]
public void BuildTerrainEntries_PreservesRoadTextureSceneryHeight()
{
var block = new LandBlock
{
Terrain = new ushort[81],
Height = new byte[81],
};
// Vertex 0: road=0x3, type=0x00, scenery=0x1F, height=42
// raw layout: bits 0-1=11, bits 2-6=00000, bits 7-10=0000, bits 11-15=11111
// = 0xF803
block.Terrain[0] = 0xF803;
block.Height[0] = 42;
// Vertex 80: road=0x0, type=0x1F, scenery=0x00, height=200
// raw layout: bits 0-1=00, bits 2-6=11111, bits 11-15=00000
// = 0x007C
block.Terrain[80] = 0x007C;
block.Height[80] = 200;
var entries = WbSceneryAdapter.BuildTerrainEntries(block);
Assert.Equal(81, entries.Length);
Assert.Equal((byte)42, entries[0].Height);
Assert.Equal((byte)0x3, entries[0].Road);
Assert.Equal((byte)0x00, entries[0].Texture);
Assert.Equal((byte)0x1F, entries[0].Scenery);
Assert.Equal((byte)200, entries[80].Height);
Assert.Equal((byte)0x0, entries[80].Road);
Assert.Equal((byte)0x1F, entries[80].Texture);
Assert.Equal((byte)0x00, entries[80].Scenery);
}
[Fact]
public void BuildTerrainEntries_AllZeros_ProducesEmptyEntries()
{
var block = new LandBlock
{
Terrain = new ushort[81],
Height = new byte[81],
};
var entries = WbSceneryAdapter.BuildTerrainEntries(block);
Assert.All(entries, e =>
{
Assert.Equal((byte)0, e.Height);
Assert.Equal((byte)0, e.Road);
Assert.Equal((byte)0, e.Texture);
Assert.Equal((byte)0, e.Scenery);
});
}
[Fact]
public void BuildTerrainEntries_NullBlock_Throws()
{
Assert.Throws(() =>
WbSceneryAdapter.BuildTerrainEntries(null!));
}
}
```
- [ ] **Step 1.2: Run the test to verify it fails**
Run: `dotnet test --no-restore tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "WbSceneryAdapterTests" 2>&1 | tail -10`
Expected: BUILD ERROR or FAIL with "type or namespace 'WbSceneryAdapter' could not be found".
- [ ] **Step 1.3: Implement the adapter**
Create `src/AcDream.Core/World/WbSceneryAdapter.cs`:
```csharp
using DatReaderWriter.DBObjs;
using WorldBuilder.Shared.Models;
namespace AcDream.Core.World;
///
/// Bridges acdream's dat types into WorldBuilder's data shapes for the
/// Phase N rendering migration. See
/// docs/architecture/worldbuilder-inventory.md for the full strategy.
///
internal static class WbSceneryAdapter
{
private const int VerticesPerSide = 9;
private const int TerrainSize = VerticesPerSide * VerticesPerSide; // 81
///
/// Builds a 9×9 = 81-entry array from a
/// 's packed terrain bits + height bytes. WB's
/// TerrainUtils.OnRoad / GetNormal / GetHeight
/// consume this shape.
///
/// Bit layout in our LandBlock.Terrain[i] (ushort):
/// bits 0-1 : Road (2 bits) → WB Road
/// bits 2-6 : TerrainType (5 bits) → WB Texture
/// bits 11-15 : SceneType (5 bits) → WB Scenery
/// Height comes from LandBlock.Height[i] (byte).
///
public static TerrainEntry[] BuildTerrainEntries(LandBlock block)
{
ArgumentNullException.ThrowIfNull(block);
if (block.Terrain.Length != TerrainSize)
throw new ArgumentException(
$"LandBlock.Terrain must be {TerrainSize} entries (9×9), got {block.Terrain.Length}",
nameof(block));
if (block.Height.Length != TerrainSize)
throw new ArgumentException(
$"LandBlock.Height must be {TerrainSize} entries (9×9), got {block.Height.Length}",
nameof(block));
var entries = new TerrainEntry[TerrainSize];
for (int i = 0; i < TerrainSize; i++)
{
ushort raw = block.Terrain[i];
byte road = (byte)(raw & 0x3);
byte texture = (byte)((raw >> 2) & 0x1F);
byte scenery = (byte)((raw >> 11) & 0x1F);
byte height = block.Height[i];
entries[i] = new TerrainEntry(height, texture, scenery, road, encounters: null);
}
return entries;
}
}
```
- [ ] **Step 1.4: Run the test to verify it passes**
Run: `dotnet test --no-restore tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "WbSceneryAdapterTests" 2>&1 | tail -5`
Expected: `Passed! - Failed: 0, Passed: 3` (or similar — three tests).
- [ ] **Step 1.5: Commit**
```bash
git add src/AcDream.Core/World/WbSceneryAdapter.cs tests/AcDream.Core.Tests/World/WbSceneryAdapterTests.cs
git commit -m "$(cat <<'EOF'
phase(N.1): add LandBlock → TerrainEntry[] adapter
Phase N.1 step 1: WbSceneryAdapter.BuildTerrainEntries converts our
LandBlock dat type into the TerrainEntry[81] shape WorldBuilder's
TerrainUtils / SceneryRenderManager consume.
Bit-pack mapping (ours → WB):
Terrain bits 0-1 (Road) → TerrainEntry.Road
Terrain bits 2-6 (TerrainType) → TerrainEntry.Texture
Terrain bits 11-15 (SceneType) → TerrainEntry.Scenery
Height byte → TerrainEntry.Height
Spec: docs/superpowers/specs/2026-05-08-phase-n1-scenery-via-wb-helpers-design.md
Co-Authored-By: Claude Opus 4.7 (1M context)
EOF
)"
```
---
## Task 2: Feature flag scaffold
**Files:**
- Modify: `src/AcDream.Core/World/SceneryGenerator.cs`
This task only adds the flag-read field. It changes no behavior and there is nothing to assert beyond "it compiles." The flag is consumed in Task 5.
- [ ] **Step 2.1: Add the feature flag field**
Open `src/AcDream.Core/World/SceneryGenerator.cs`. Find the line:
```csharp
// AC landblock geometry — matches LandblockMesh.
private const int VerticesPerSide = 9;
private const float CellSize = 24.0f;
private const float LandblockSize = 192.0f; // 8 cells * 24 units
```
Immediately AFTER the `LandblockSize` constant, ADD:
```csharp
///
/// Phase N.1 feature flag — when set to "1", scenery placement uses
/// WorldBuilder's SceneryHelpers + TerrainUtils instead of
/// our hand-ported algorithms. Default off until visual verification at
/// landblock 0xA9B1 confirms behavior. See
/// docs/superpowers/specs/2026-05-08-phase-n1-scenery-via-wb-helpers-design.md.
///
internal static readonly bool UseWbScenery =
System.Environment.GetEnvironmentVariable("ACDREAM_USE_WB_SCENERY") == "1";
```
- [ ] **Step 2.2: Verify build still passes**
Run: `dotnet build src/AcDream.Core/AcDream.Core.csproj 2>&1 | tail -5`
Expected: `Build succeeded.` and `0 Error(s)`.
- [ ] **Step 2.3: Verify all existing tests still pass**
Run: `dotnet test --no-build tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "SceneryGenerator|Wb" 2>&1 | tail -3`
Expected: `Passed!` with all scenery-area tests passing.
- [ ] **Step 2.4: Commit**
```bash
git add src/AcDream.Core/World/SceneryGenerator.cs
git commit -m "$(cat <<'EOF'
phase(N.1): add ACDREAM_USE_WB_SCENERY feature flag scaffold
Phase N.1 step 2: read the env var into a static bool. No behavior
change yet — the flag is consumed in step 5 when GenerateViaWb is
wired in.
Co-Authored-By: Claude Opus 4.7 (1M context)
EOF
)"
```
---
## Task 3: Per-helper conformance tests
**Files:**
- Create: `tests/AcDream.Core.Tests/World/SceneryWbConformanceTests.cs`
These five tests prove WB's `SceneryHelpers.Displace` / `TerrainUtils.OnRoad` / `TerrainUtils.GetNormal` / `SceneryHelpers.RotateObj` / `SceneryHelpers.ScaleObj` produce the same answers as the hand-ported logic currently inlined in `Generate()`. After this task, we have empirical evidence that the substitution is safe.
If a test fails, that is the bug — investigate before proceeding to Task 4.
- [ ] **Step 3.1: Write all five conformance tests**
Create `tests/AcDream.Core.Tests/World/SceneryWbConformanceTests.cs`:
```csharp
using System.Numerics;
using AcDream.Core.World;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using WB_TerrainUtils = WorldBuilder.Shared.Modules.Landscape.Lib.TerrainUtils;
using WB_SceneryHelpers = Chorizite.OpenGLSDLBackend.Lib.SceneryHelpers;
namespace AcDream.Core.Tests.World;
///
/// Phase N.1 helper-level conformance tests. Each test compares an algorithm
/// in our existing path against WorldBuilder's
/// equivalent for representative inputs. Passing tests are empirical evidence
/// that swapping our inline logic for WB's helpers is behavior-preserving.
///
/// If any of these fails the substitution would silently change rendered
/// scenery; investigate before proceeding to Task 4 (GenerateViaWb).
///
/// Inputs are chosen to exercise:
/// - A non-edge vertex (gx=100, gy=100, j=0) — typical case
/// - The edge vertex at y=8 specifically (Issue #49 territory)
///
public class SceneryWbConformanceTests
{
private static ObjectDesc MakeObj(
float displaceX = 12f,
float displaceY = 12f,
float minScale = 1f,
float maxScale = 1f,
float maxRotation = 0f,
float minSlope = 0f,
float maxSlope = 1f,
int align = 0)
{
return new ObjectDesc
{
ObjectId = 0x02000258u,
DisplaceX = displaceX,
DisplaceY = displaceY,
MinScale = minScale,
MaxScale = maxScale,
MaxRotation = maxRotation,
MinSlope = minSlope,
MaxSlope = maxSlope,
Align = (uint)align,
BaseLoc = new Frame { Origin = new Vector3(0, 0, 0) },
};
}
///
/// Our DisplaceObject ↔ WB's SceneryHelpers.Displace must produce the
/// same Vector3 for the same (obj, ix, iy, iq).
///
[Theory]
[InlineData(100u, 100u, 0u)] // typical
[InlineData( 50u, 50u, 1u)] // typical, j=1
[InlineData( 4u, 8u, 0u)] // edge vertex y=8
[InlineData( 8u, 4u, 0u)] // edge vertex x=8
public void Displace_OursMatchesWb(uint ix, uint iy, uint iq)
{
var obj = MakeObj();
var ours = SceneryGenerator.DisplaceObject(obj, ix, iy, iq);
var wb = WB_SceneryHelpers.Displace(obj, ix, iy, iq);
Assert.Equal(ours.X, wb.X, precision: 4);
Assert.Equal(ours.Y, wb.Y, precision: 4);
Assert.Equal(ours.Z, wb.Z, precision: 4);
}
///
/// Our IsOnRoad ↔ WB's TerrainUtils.OnRoad must produce the same bool
/// for the same (lx, ly) when the underlying terrain bits match.
///
[Theory]
[InlineData( 12.0f, 12.0f)] // cell (0,0) center
[InlineData( 85.08f, 190.97f)] // the 0xA9B1 edge-vertex bug location
[InlineData( 3.0f, 3.0f)] // near a road if r0 is set
[InlineData( 23.5f, 12.0f)] // edge of cell, between cells
public void OnRoad_OursMatchesWb_DiagonalRoad(float lx, float ly)
{
// Build a synthetic LandBlock with road bits at SW (0,0) and NE (1,1)
// of cell (0,0) — the diagonal pattern we saw at 0xA9B1.
var block = new LandBlock
{
Terrain = new ushort[81],
Height = new byte[81],
};
// road bit at vertex (0,0) — index 0*9+0 = 0
block.Terrain[0] = 0x0003; // road=3
// road bit at vertex (1,1) — index 1*9+1 = 10
block.Terrain[10] = 0x0003;
bool ours = SceneryGenerator.IsOnRoad(block, lx, ly);
var entries = WbSceneryAdapter.BuildTerrainEntries(block);
bool wb = WB_TerrainUtils.OnRoad(new Vector3(lx, ly, 0), entries);
Assert.Equal(ours, wb);
}
///
/// Our SampleNormalZFromHeightmap ↔ WB's TerrainUtils.GetNormal(...).Z
/// must produce the same Z for representative slope inputs.
///
[Theory]
[InlineData( 12.0f, 12.0f)] // cell center
[InlineData( 85.08f, 190.97f)] // the 0xA9B1 edge-vertex location
[InlineData( 3.0f, 188.0f)] // near a y-edge
public void GetNormalZ_OursMatchesWb_LinearTable(float lx, float ly)
{
// Heightmap with non-flat terrain so normals are non-trivial.
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 * 17 + y * 13) % 256);
var heightTable = new float[256];
for (int i = 0; i < 256; i++) heightTable[i] = i * 1.0f;
const uint lbX = 0xA9, lbY = 0xB1;
// Build a Region-shaped object with the LandHeightTable populated.
// (TerrainUtils.GetNormal calls region.LandDefs.LandHeightTable[height].)
// LandHeightTable is float[] (size 256) in DatReaderWriter — see
// src/AcDream.App/Rendering/GameWindow.cs:1306-1308 for the runtime check.
var region = new DatReaderWriter.DBObjs.Region
{
LandDefs = new LandDefs(),
};
// If LandDefs default-initializes LandHeightTable to a non-null float[256],
// copy into it. If it's null, assign directly. The implementer should
// pick whichever pattern compiles in DatReaderWriter 2.1.7's API:
// Option A: region.LandDefs.LandHeightTable = heightTable;
// Option B: Array.Copy(heightTable, region.LandDefs.LandHeightTable, 256);
region.LandDefs.LandHeightTable = heightTable;
var block = new LandBlock
{
Terrain = new ushort[81],
Height = heights,
};
var entries = WbSceneryAdapter.BuildTerrainEntries(block);
float ours = AcDream.Core.Physics.TerrainSurface.SampleNormalZFromHeightmap(
heights, heightTable, lbX, lbY, lx, ly);
float wb = WB_TerrainUtils.GetNormal(region, entries, lbX, lbY,
new Vector3(lx, ly, 0)).Z;
Assert.Equal(ours, wb, precision: 4);
}
///
/// Our inline rotation logic ↔ WB's SceneryHelpers.RotateObj must
/// produce the same Quaternion for non-Align objects with MaxRotation.
///
[Theory]
[InlineData( 100u, 100u, 0u, 360f)]
[InlineData( 4u, 8u, 0u, 360f)]
[InlineData( 200u, 250u, 1u, 180f)]
public void RotateObj_OursMatchesWb_NonAlign(uint gx, uint gy, uint j, float maxRot)
{
var obj = MakeObj(maxRotation: maxRot);
// Our inline logic from SceneryGenerator.Generate (~lines 220-231):
Quaternion ours = obj.BaseLoc.Orientation;
if (ours.LengthSquared() < 0.0001f) ours = Quaternion.Identity;
if (obj.MaxRotation > 0f)
{
double rotNoise = unchecked((uint)(1813693831u * gy
- (j + 63127u) * (1360117743u * gy * gx + 1888038839u)
- 1109124029u * gx)) * 2.3283064e-10;
float degrees = (float)(rotNoise * obj.MaxRotation);
float yawDeg = -((450f - degrees) % 360f);
float yawRad = yawDeg * MathF.PI / 180f;
var headingQuat = Quaternion.CreateFromAxisAngle(Vector3.UnitZ, yawRad);
ours = headingQuat * ours;
}
// WB's SceneryHelpers.Displace returns the localPos that RotateObj
// expects for its loc parameter (used only when SetHeading is called
// with non-zero matrix, but a stub Vector3 works since BaseLoc is identity).
var localPos = WB_SceneryHelpers.Displace(obj, gx, gy, j);
Quaternion wb = WB_SceneryHelpers.RotateObj(obj, gx, gy, j, localPos);
Assert.Equal(ours.X, wb.X, precision: 4);
Assert.Equal(ours.Y, wb.Y, precision: 4);
Assert.Equal(ours.Z, wb.Z, precision: 4);
Assert.Equal(ours.W, wb.W, precision: 4);
}
///
/// Our inline scale logic ↔ WB's SceneryHelpers.ScaleObj must produce
/// the same float for representative inputs.
///
[Theory]
[InlineData(100u, 100u, 0u, 0.5f, 1.5f)]
[InlineData( 4u, 8u, 0u, 1.0f, 1.0f)]
[InlineData(200u, 250u, 1u, 0.8f, 1.2f)]
public void ScaleObj_OursMatchesWb(uint gx, uint gy, uint j, float minScale, float maxScale)
{
var obj = MakeObj(minScale: minScale, maxScale: maxScale);
// Our inline logic from SceneryGenerator.Generate (~lines 236-247):
float ours;
if (obj.MinScale == obj.MaxScale)
{
ours = obj.MaxScale;
}
else
{
double scaleNoise = unchecked((uint)(1813693831u * gy
- (j + 32593u) * (1360117743u * gy * gx + 1888038839u)
- 1109124029u * gx)) * 2.3283064e-10;
ours = (float)(Math.Pow(obj.MaxScale / obj.MinScale, scaleNoise) * obj.MinScale);
}
if (ours <= 0) ours = 1f;
float wb = WB_SceneryHelpers.ScaleObj(obj, gx, gy, j);
if (wb <= 0) wb = 1f;
Assert.Equal(ours, wb, precision: 4);
}
}
```
- [ ] **Step 3.2: Make our `IsOnRoad` accessible to the test**
`IsOnRoad` is currently `private`. Bump to `internal` so the conformance test can call it. Open `src/AcDream.Core/World/SceneryGenerator.cs` and change:
```csharp
private static bool IsOnRoad(LandBlock block, float lx, float ly)
```
to:
```csharp
internal static bool IsOnRoad(LandBlock block, float lx, float ly)
```
- [ ] **Step 3.3: Run the conformance tests**
Run: `dotnet test --no-restore tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "SceneryWbConformance" 2>&1 | tail -10`
Expected: ALL TESTS PASS.
If any test fails, **stop and investigate** — that's the bug WB is hiding from us. Report which assertion failed (e.g., "Displace at gx=4 gy=8 returns different Y") and confer with the user before proceeding.
- [ ] **Step 3.4: Commit**
```bash
git add tests/AcDream.Core.Tests/World/SceneryWbConformanceTests.cs src/AcDream.Core/World/SceneryGenerator.cs
git commit -m "$(cat <<'EOF'
phase(N.1): per-helper conformance tests for WB substitutions
Phase N.1 step 3: prove our inline algorithms (Displace, IsOnRoad,
slope normal Z, RotateObj, ScaleObj) match WorldBuilder's helpers
for representative inputs including the 0xA9B1 edge-vertex case.
Bumps IsOnRoad to internal so the test can call it directly.
Co-Authored-By: Claude Opus 4.7 (1M context)
EOF
)"
```
---
## Task 4: Implement `GenerateViaWb`
**Files:**
- Modify: `src/AcDream.Core/World/SceneryGenerator.cs`
Add a new private method `GenerateViaWb` that produces `IReadOnlyList` using only WB helpers for the substituted algorithm calls. The 9×9 loop, scene selection, frequency check, bounds check, building grid, and `BaseLoc.Z` handling stay structurally identical to `Generate`.
- [ ] **Step 4.1: Add the required `using` directives**
Open `src/AcDream.Core/World/SceneryGenerator.cs`. The file currently has:
```csharp
using System.Numerics;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
namespace AcDream.Core.World;
```
Replace with:
```csharp
using System.Numerics;
using Chorizite.OpenGLSDLBackend.Lib;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using WorldBuilder.Shared.Modules.Landscape.Lib;
namespace AcDream.Core.World;
```
- [ ] **Step 4.2: Add `GenerateViaWb` immediately after `Generate`**
Find the closing `}` of `Generate(...)` in `SceneryGenerator.cs` (just before the `IsRoadVertex` method). Immediately AFTER `Generate`'s closing brace, ADD:
```csharp
///
/// Phase N.1 alternative implementation that delegates the
/// algorithm calls to WorldBuilder's SceneryHelpers +
/// TerrainUtils. Structurally identical to
/// but with WB's tested ports doing the work. Selected by
/// .
///
private static IReadOnlyList GenerateViaWb(
DatCollection dats,
Region region,
LandBlock block,
uint landblockId,
HashSet? buildingCells)
{
var result = new List();
if (region.TerrainInfo?.TerrainTypes is null || region.SceneInfo?.SceneTypes is null)
return result;
// Build the TerrainEntry[] WB's helpers consume — once per landblock.
var terrainEntries = WbSceneryAdapter.BuildTerrainEntries(block);
uint blockX = (landblockId >> 24) * 8;
uint blockY = ((landblockId >> 16) & 0xFFu) * 8;
uint lbX = landblockId >> 24;
uint lbY = (landblockId >> 16) & 0xFFu;
for (int x = 0; x < VerticesPerSide; x++)
{
for (int y = 0; y < VerticesPerSide; y++)
{
int i = x * VerticesPerSide + y;
ushort raw = block.Terrain[i];
uint terrainType = (uint)((raw >> 2) & 0x1F);
uint sceneType = (uint)((raw >> 11) & 0x1F);
if (terrainType >= region.TerrainInfo.TerrainTypes.Count) continue;
var sceneTypeList = region.TerrainInfo.TerrainTypes[(int)terrainType].SceneTypes;
if (sceneType >= sceneTypeList.Count) continue;
uint sceneInfo = sceneTypeList[(int)sceneType];
if (sceneInfo >= region.SceneInfo.SceneTypes.Count) continue;
var scenes = region.SceneInfo.SceneTypes[(int)sceneInfo].Scenes;
if (scenes.Count == 0) continue;
uint cellX = (uint)x;
uint cellY = (uint)y;
uint globalCellX = cellX + blockX;
uint globalCellY = cellY + blockY;
// Scene-selection hash: identical to Generate.
uint cellMat = globalCellY * (712977289u * globalCellX + 1813693831u)
- 1109124029u * globalCellX + 2139937281u;
double offset = cellMat * 2.3283064e-10;
int sceneIdx = (int)(scenes.Count * offset);
if (sceneIdx >= scenes.Count || sceneIdx < 0) sceneIdx = 0;
uint sceneId = (uint)scenes[sceneIdx];
var scene = dats.Get(sceneId);
if (scene is null) continue;
// Per-object frequency setup: identical to Generate.
uint cellXMat = unchecked(0u - 1109124029u * globalCellX);
uint cellYMat = 1813693831u * globalCellY;
uint cellMat2 = 1360117743u * globalCellX * globalCellY + 1888038839u;
for (uint j = 0; j < scene.Objects.Count; j++)
{
var obj = scene.Objects[(int)j];
if (obj.WeenieObj != 0) continue;
double noise = unchecked((uint)(cellXMat + cellYMat - cellMat2 * (23399u + j))) * 2.3283064e-10;
if (noise >= obj.Frequency) continue;
// ─── WB substitution: displacement ───────────────────
var localPos = SceneryHelpers.Displace(obj, globalCellX, globalCellY, j);
float lx = cellX * CellSize + localPos.X;
float ly = cellY * CellSize + localPos.Y;
if (lx < 0 || ly < 0 || lx >= LandblockSize || ly >= LandblockSize)
continue;
// ─── WB substitution: road check ──────────────────────
if (TerrainUtils.OnRoad(new Vector3(lx, ly, 0), terrainEntries))
continue;
// Building check: identical to Generate.
if (buildingCells is not null)
{
int dcx = Math.Clamp((int)(lx / CellSize), 0, CellsPerSide - 1);
int dcy = Math.Clamp((int)(ly / CellSize), 0, CellsPerSide - 1);
if (buildingCells.Contains(dcx * VerticesPerSide + dcy))
continue;
}
// ─── WB substitution: slope check ─────────────────────
Vector3 normal = TerrainUtils.GetNormal(
region, terrainEntries, lbX, lbY,
new Vector3(lx, ly, 0));
if (!SceneryHelpers.CheckSlope(obj, normal.Z))
continue;
float lz = obj.BaseLoc.Origin.Z;
// ─── WB substitution: rotation ────────────────────────
Quaternion rotation;
if (obj.Align != 0)
rotation = SceneryHelpers.ObjAlign(obj, normal, lz, localPos);
else
rotation = SceneryHelpers.RotateObj(obj, globalCellX, globalCellY, j, localPos);
// ─── WB substitution: scale ───────────────────────────
float scale = SceneryHelpers.ScaleObj(obj, globalCellX, globalCellY, j);
if (scale <= 0) scale = 1f;
result.Add(new ScenerySpawn(
ObjectId: obj.ObjectId,
LocalPosition: new Vector3(lx, ly, lz),
Rotation: rotation,
Scale: scale));
}
}
}
return result;
}
```
- [ ] **Step 4.3: Verify build**
Run: `dotnet build src/AcDream.Core/AcDream.Core.csproj 2>&1 | tail -5`
Expected: `Build succeeded.` `0 Error(s)`.
If you get an error like `'SceneryHelpers' is an ambiguous reference`, it's because both Chorizite.OpenGLSDLBackend.Lib and WorldBuilder.Shared expose helpers — fix by qualifying: `Chorizite.OpenGLSDLBackend.Lib.SceneryHelpers.Displace(...)`.
- [ ] **Step 4.4: Verify existing tests still pass**
Run: `dotnet test --no-build tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "SceneryGenerator|WbSceneryAdapter|SceneryWbConformance" 2>&1 | tail -3`
Expected: all scenery-area tests pass (the ones added in Tasks 1 and 3, plus the original SceneryGeneratorTests). No behavior change yet for the live `Generate` path — `GenerateViaWb` is added but not called.
- [ ] **Step 4.5: Commit**
```bash
git add src/AcDream.Core/World/SceneryGenerator.cs
git commit -m "$(cat <<'EOF'
phase(N.1): implement GenerateViaWb alternative path
Phase N.1 step 4: parallel implementation of Generate() that calls
WB's SceneryHelpers (Displace/CheckSlope/RotateObj/ObjAlign/ScaleObj)
and TerrainUtils (OnRoad/GetNormal) instead of the inline ports.
Not yet wired in — Generate() still runs the legacy path. Step 5
adds the dispatch.
Per-helper conformance tests in step 3 prove this implementation is
behavior-equivalent to the legacy path.
Co-Authored-By: Claude Opus 4.7 (1M context)
EOF
)"
```
---
## Task 5: Wire feature-flag dispatch
**Files:**
- Modify: `src/AcDream.Core/World/SceneryGenerator.cs`
- [ ] **Step 5.1: Add the dispatch at the top of `Generate`**
In `src/AcDream.Core/World/SceneryGenerator.cs`, find the body of `Generate`:
```csharp
public static IReadOnlyList Generate(
DatCollection dats,
Region region,
LandBlock block,
uint landblockId,
HashSet? buildingCells = null,
float[]? heightTable = null)
{
var result = new List();
if (region.TerrainInfo?.TerrainTypes is null || region.SceneInfo?.SceneTypes is null)
return result;
```
Immediately AFTER the opening `{` and BEFORE `var result = new List();`, ADD:
```csharp
// Phase N.1: route to the WorldBuilder-backed implementation when
// ACDREAM_USE_WB_SCENERY=1. See
// docs/superpowers/specs/2026-05-08-phase-n1-scenery-via-wb-helpers-design.md.
if (UseWbScenery)
return GenerateViaWb(dats, region, block, landblockId, buildingCells);
```
So the method's opening becomes:
```csharp
public static IReadOnlyList Generate(
DatCollection dats,
Region region,
LandBlock block,
uint landblockId,
HashSet? buildingCells = null,
float[]? heightTable = null)
{
// Phase N.1: route to the WorldBuilder-backed implementation when
// ACDREAM_USE_WB_SCENERY=1. See
// docs/superpowers/specs/2026-05-08-phase-n1-scenery-via-wb-helpers-design.md.
if (UseWbScenery)
return GenerateViaWb(dats, region, block, landblockId, buildingCells);
var result = new List();
if (region.TerrainInfo?.TerrainTypes is null || region.SceneInfo?.SceneTypes is null)
return result;
```
Note: `heightTable` is NOT passed to `GenerateViaWb` — the WB path uses `region.LandDefs.LandHeightTable` via `TerrainUtils.GetNormal`. The legacy path keeps the parameter for backward compatibility.
- [ ] **Step 5.2: Verify build**
Run: `dotnet build src/AcDream.Core/AcDream.Core.csproj 2>&1 | tail -5`
Expected: `Build succeeded.`
- [ ] **Step 5.3: Verify all existing tests still pass with flag OFF (default)**
Run: `dotnet test --no-build tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "SceneryGenerator|WbSceneryAdapter|SceneryWbConformance" 2>&1 | tail -3`
Expected: all pass (the legacy path is still default, so behavior is unchanged).
- [ ] **Step 5.4: Commit**
```bash
git add src/AcDream.Core/World/SceneryGenerator.cs
git commit -m "$(cat <<'EOF'
phase(N.1): wire ACDREAM_USE_WB_SCENERY dispatch in Generate()
Phase N.1 step 5: when the flag is set, Generate() delegates to
GenerateViaWb. Default off; flag flips to default-on in step 7
after visual verification.
Co-Authored-By: Claude Opus 4.7 (1M context)
EOF
)"
```
---
## Task 6: Visual verification — manual checkpoint
This task is interactive. **You must work with the user.** They run the client, look at landblock `0xA9B1`, and confirm two things visually:
1. The road-edge tree we have been chasing all session is **not present** in the WB-backed render.
2. The Issue #49 missing scenery (the trees the 9×9 loop expansion fixed) is **still visible**.
- [ ] **Step 6.1: Make sure build is green**
Run: `dotnet build 2>&1 | tail -3`
Expected: `Build succeeded.`
- [ ] **Step 6.2: Tell the user how to launch with the flag set**
Tell the user (paraphrase): "Set `$env:ACDREAM_USE_WB_SCENERY = '1'` in your launch terminal alongside the other env vars, then launch the client and navigate to Holtburg. Specifically check the road-edge area near coordinates (87, 191) in landblock 0xA9B1 — the tree we have been chasing all session should be gone now. Also confirm Issue #49's previously missing trees are still there."
If `dotnet run` is the standard launch command, the full PowerShell launch is:
```powershell
$env:ACDREAM_DAT_DIR = "$env:USERPROFILE\Documents\Asheron's Call"
$env:ACDREAM_LIVE = "1"
$env:ACDREAM_TEST_HOST = "127.0.0.1"
$env:ACDREAM_TEST_PORT = "9000"
$env:ACDREAM_TEST_USER = "testaccount"
$env:ACDREAM_TEST_PASS = "testpassword"
$env:ACDREAM_USE_WB_SCENERY = "1"
dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | Tee-Object -FilePath "launch.log"
```
- [ ] **Step 6.3: Wait for user's verification report**
The user will tell you "yes the offending tree is gone and Issue #49 is still fine" or "still wrong". If still wrong, do NOT proceed — investigate and report back.
- [ ] **Step 6.4: Commit nothing**
This task does not produce a code change. The commit happens in Task 7 once the flag is flipped to default-on.
---
## Task 7: Flip default-on
**Files:**
- Modify: `src/AcDream.Core/World/SceneryGenerator.cs`
After visual verification passes in Task 6, the WB-backed path becomes the default. The env var still exists as an escape hatch (`ACDREAM_USE_WB_SCENERY=0` reverts to legacy) so that if a regression is reported the next day, we can flip back without redeploying.
- [ ] **Step 7.1: Flip the flag default**
In `src/AcDream.Core/World/SceneryGenerator.cs`, find:
```csharp
internal static readonly bool UseWbScenery =
System.Environment.GetEnvironmentVariable("ACDREAM_USE_WB_SCENERY") == "1";
```
Replace with:
```csharp
///
/// Phase N.1: scenery placement uses WorldBuilder's SceneryHelpers
/// + TerrainUtils by default. Set ACDREAM_USE_WB_SCENERY=0
/// to restore the legacy in-line algorithms (escape hatch — to be deleted
/// in a follow-up commit once we have a few sessions of green visuals).
///
internal static readonly bool UseWbScenery =
System.Environment.GetEnvironmentVariable("ACDREAM_USE_WB_SCENERY") != "0";
```
- [ ] **Step 7.2: Verify build + tests**
Run: `dotnet build 2>&1 | tail -3 && dotnet test --no-build tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "SceneryGenerator|WbSceneryAdapter|SceneryWbConformance" 2>&1 | tail -3`
Expected: build green, all targeted tests pass.
- [ ] **Step 7.3: Commit**
```bash
git add src/AcDream.Core/World/SceneryGenerator.cs
git commit -m "$(cat <<'EOF'
phase(N.1): WB-backed scenery is now default-on
Phase N.1 step 7: flips ACDREAM_USE_WB_SCENERY to default-on after
visual verification at Holtburg confirmed the road-edge tree at
0xA9B1 is gone and Issue #49 trees are still visible.
ACDREAM_USE_WB_SCENERY=0 still reverts to the legacy path. Follow-up
commit will delete the legacy code entirely.
Co-Authored-By: Claude Opus 4.7 (1M context)
EOF
)"
```
---
## Task 8: Delete the legacy code path
**Files:**
- Modify: `src/AcDream.Core/World/SceneryGenerator.cs`
- Modify: `tests/AcDream.Core.Tests/World/SceneryGeneratorTests.cs`
After at least one session of clean visuals on the default-on flag, remove the legacy code so we don't accumulate dead-code drift.
- [ ] **Step 8.1: Delete the legacy `Generate` body and rename `GenerateViaWb`**
In `src/AcDream.Core/World/SceneryGenerator.cs`:
1. Delete the `UseWbScenery` field entirely.
2. Delete the entire body of `Generate` after its signature.
3. Replace it with a body that just calls `GenerateViaWb`'s logic (or rename `GenerateViaWb` to `Generate`'s body).
The simplest approach: rename `GenerateViaWb` to `GenerateInternal` and have the public `Generate` call it. Then delete the legacy logic. Final shape:
```csharp
public static IReadOnlyList Generate(
DatCollection dats,
Region region,
LandBlock block,
uint landblockId,
HashSet? buildingCells = null,
float[]? heightTable = null)
{
// heightTable kept for backward compat; WB path uses
// region.LandDefs.LandHeightTable internally.
_ = heightTable;
return GenerateInternal(dats, region, block, landblockId, buildingCells);
}
private static IReadOnlyList GenerateInternal(
DatCollection dats,
Region region,
LandBlock block,
uint landblockId,
HashSet? buildingCells)
{
// ... body that was GenerateViaWb ...
}
```
4. Delete the now-unused private helpers: `IsOnRoad`, `DisplaceObject`, `RoadHalfWidth`, `CellsPerSide` (if only used by legacy path — keep if `GenerateInternal`'s building check still references it).
Concretely, keep:
- `VerticesPerSide`, `CellSize`, `LandblockSize`, `CellsPerSide` constants (still used in `GenerateInternal`)
- `IsRoadVertex` (still useful as a tiny public predicate)
- `WbSceneryAdapter` (still used)
Delete:
- `UseWbScenery`
- `IsOnRoad` (and its `RoadHalfWidth` dependency)
- `DisplaceObject` (now dead)
- [ ] **Step 8.2: Update SceneryGeneratorTests.cs to remove now-irrelevant tests**
In `tests/AcDream.Core.Tests/World/SceneryGeneratorTests.cs`, the existing
`DisplaceObject_EdgeVertex_CanProduceValidPosition` and
`DisplaceObject_InteriorVertex_AlwaysNearOrigin` tests reference the deleted
`SceneryGenerator.DisplaceObject` helper. Delete them.
Keep:
- All `IsRoadVertex_*` tests (`IsRoadVertex` is preserved).
The class doc comment at the top should be updated to reflect the new state:
```csharp
///
/// Tests for SceneryGenerator: the road-vertex predicate (only piece of
/// our own algorithm code remaining post Phase N.1). The displacement /
/// road / slope / rotation / scale algorithms now run through
/// WorldBuilder's helpers — see SceneryWbConformanceTests.cs for the
/// helper-level equivalence proof.
///
```
- [ ] **Step 8.3: Update the SceneryWbConformanceTests now that legacy helpers are gone**
`SceneryWbConformanceTests` currently calls `SceneryGenerator.DisplaceObject` and `SceneryGenerator.IsOnRoad`. Once those are deleted, the tests are now testing "WB matches WB" which is meaningless.
Delete `SceneryWbConformanceTests.cs` entirely. The conformance tests served their purpose during the migration — they proved the substitution was safe. Now that we're committed to the WB path, they're vestigial.
Run: `rm tests/AcDream.Core.Tests/World/SceneryWbConformanceTests.cs`
- [ ] **Step 8.4: Verify build + tests**
Run: `dotnet build 2>&1 | tail -3 && dotnet test --no-build tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "SceneryGenerator|WbSceneryAdapter" 2>&1 | tail -3`
Expected: build green, tests pass (just the IsRoadVertex tests + WbSceneryAdapter tests).
- [ ] **Step 8.5: Commit**
```bash
git add src/AcDream.Core/World/SceneryGenerator.cs tests/AcDream.Core.Tests/World/SceneryGeneratorTests.cs tests/AcDream.Core.Tests/World/SceneryWbConformanceTests.cs
git commit -m "$(cat <<'EOF'
phase(N.1): delete legacy scenery code path; WB is the only path
Phase N.1 step 8 (final): now that ACDREAM_USE_WB_SCENERY has been
default-on for a session with no regressions, remove the legacy
in-line algorithms so we don't accumulate dead-code drift.
Deleted:
- SceneryGenerator.UseWbScenery (feature flag)
- SceneryGenerator.IsOnRoad / DisplaceObject / RoadHalfWidth (legacy ports)
- SceneryGeneratorTests.DisplaceObject_* (test the deleted method)
- SceneryWbConformanceTests.cs (purpose served — proved equivalence pre-migration)
Renamed:
- GenerateViaWb → GenerateInternal (the only path now)
Kept:
- IsRoadVertex (small predicate, still used by tests + may be useful elsewhere)
- WbSceneryAdapter (consumed by GenerateInternal; reusable in N.2)
Phase N.1 complete. Issues #48, #49 are addressed via WB's tested
algorithms. Roadmap entry under Phase N can be marked shipped.
Co-Authored-By: Claude Opus 4.7 (1M context)
EOF
)"
```
- [ ] **Step 8.6: Mark Phase N.1 shipped in the roadmap**
In `docs/plans/2026-04-11-roadmap.md`, find the Phase N section (search for `### Phase N — WorldBuilder Rendering Migration`). Inside the sub-phases table find the row for **N.1**, currently:
```
- **N.1 — Scenery algorithm calls.** Replace `IsOnRoad` /
`DisplaceObject` / slope-normal calc / rotation / scale inside
`SceneryGenerator.Generate()` with calls to WB's `SceneryHelpers` +
`TerrainUtils`. Tiny adapter `LandBlock → TerrainEntry[]`. Keeps our
data flow + `ScenerySpawn` shape. Feature flag
`ACDREAM_USE_WB_SCENERY=1`. ~1-2 days.
```
Add a status marker at the start of the line:
```
- **✓ SHIPPED — N.1 — Scenery algorithm calls.** Shipped 2026-05-08.
Replaced `IsOnRoad` / `DisplaceObject` / slope-normal calc / rotation /
scale inside `SceneryGenerator.Generate()` with calls to WB's
`SceneryHelpers` + `TerrainUtils`. Adapter `WbSceneryAdapter` produces
`TerrainEntry[]`. Visual verification at Holtburg confirmed the
road-edge tree at 0xA9B1 is gone and Issue #49 trees are still visible.
```
Also: add a row to the top of the file's "Phases already shipped" table, in commit-shipped order:
```
| N.1 | WorldBuilder-backed scenery (Chorizite/WorldBuilder fork as submodule, SceneryHelpers + TerrainUtils replace our inline ports) | Live ✓ |
```
Then commit:
```bash
git add docs/plans/2026-04-11-roadmap.md
git commit -m "$(cat <<'EOF'
docs(roadmap): mark Phase N.1 (scenery via WB helpers) shipped
Co-Authored-By: Claude Opus 4.7 (1M context)
EOF
)"
```
---
## Done definition
After all 8 tasks land cleanly:
- [x] `dotnet build` and `dotnet test` (excluding the 8 pre-existing `DispatcherToMovementIntegrationTests` failures unrelated to this work) green.
- [x] Visual verification at Holtburg confirms:
- The road-edge tree near `0xA9B1` is **gone**.
- Issue #49's missing scenery is **still visible**.
- No new visual regressions in surrounding landblocks during a brief flight.
- [x] Phase N.1 marked shipped in `docs/plans/2026-04-11-roadmap.md`.
- [x] `SceneryGenerator.Generate` calls only WB helpers for displacement / road / slope / rotation / scale.
- [x] Issue #49 stays closed; no new related issues filed.