acdream/docs/superpowers/specs/2026-05-08-phase-n1-scenery-via-wb-helpers-design.md

Phase N.1 — Scenery via WorldBuilder Helpers: Design

Date: 2026-05-08 Parent design: 2026-05-08-phase-n-worldbuilder-migration-design.md Status: Design complete, awaiting plan generation.

Goal

Replace the algorithm guts of SceneryGenerator.Generate() with calls to WorldBuilder's stateless SceneryHelpers and TerrainUtils. Keep our data flow, our ScenerySpawn shape, and our renderer integration unchanged.

Why scenery first

1. Active bug source. Issues #48, #49 are scenery-related; the investigation in this session uncovered another (the road-edge tree at 0xA9B1) we couldn't easily root-cause despite our code looking identical to WB's.
2. Smallest coherent slice. Scenery placement uses only stateless helpers from WB (Displace, OnRoad, GetNormal, CheckSlope, RotateObj, ScaleObj). No need to take WB's SceneryRenderManager, no need for editor-shaped data flow.
3. Proves the integration pattern. Phase N.0 wires up the submodule + project references. N.1 uses them with a tiny surface area. If something is wrong with the dependency model, we discover it cheaply.

Architecture

What changes

src/AcDream.Core/World/SceneryGenerator.cs:

• Remove our private IsOnRoad(LandBlock, float, float) helper.
• Remove our private DisplaceObject(ObjectDesc, uint, uint, uint) helper.
• Remove the RoadHalfWidth constant.
• Replace inline algorithm calls with WB equivalents (see table below).

New file src/AcDream.Core/World/WbSceneryAdapter.cs (or similar location — TBD during implementation):

• Helper BuildTerrainEntries(LandBlock block) → TerrainEntry[] converting our DatReaderWriter.DBObjs.LandBlock (the dat type) into the TerrainEntry[] shape WB's TerrainUtils expects (9×9 grid, Type/Scenery/Road/Height fields per vertex).
• Helper for RegionInfo if needed (small wrapper over our Region dat).

Algorithm-call substitution table

Today (ours)	Phase N.1 (WB)
IsRoadVertex(raw) (kept; small util)	unchanged — small predicate, no benefit to swap
IsOnRoad(block, lx, ly)	TerrainUtils.OnRoad(new Vector3(lx, ly, 0), terrainEntries)
DisplaceObject(obj, gx, gy, j)	SceneryHelpers.Displace(obj, gx, gy, j)
Slope normal: TerrainSurface.SampleNormalZFromHeightmap(...)	TerrainUtils.GetNormal(region, terrainEntries, lbX, lbY, lbOffset).Z
Slope check: nz < obj.MinSlope || nz > obj.MaxSlope	SceneryHelpers.CheckSlope(obj, normal.Z) (returns bool)
Rotation logic (AFrame::set_heading reproduction)	SceneryHelpers.RotateObj(obj, gx, gy, j, localPos) (returns Quaternion)
Scale logic (LCG + Pow + clamp)	SceneryHelpers.ScaleObj(obj, gx, gy, j) (returns float)

What does NOT change

• The 9×9 vertex loop (for (x = 0; x < 9; x++) for (y = 0; y < 9; y++)).
• Scene selection hash.
• Frequency roll.
• obj.WeenieObj != 0 skip (weenie entries are dynamic spawns).
• Bounds check lx, ly ∈ [0, 192).
• Per-spawn building check using our buildingCells HashSet.
• BaseLoc.Z offset application.
• ScenerySpawn record shape returned to the renderer.
• Generate() method signature — same parameters, same return type.

What about obj_within_block?

We attempted this during the bug investigation but it's too aggressive when applied with the model's actual sorting sphere radius (rejects trees that should be there). WB also doesn't apply it. The retail behavior we couldn't reproduce stays unreproduced for now — we accept that as a known minor cosmetic discrepancy and move on. The point of N.1 is matching WB's behavior, not retail's. If WB and retail disagree, that's a WB-upstream problem to file separately.

Components

Files modified

• src/AcDream.Core/World/SceneryGenerator.cs — algorithm-call swap.
• src/AcDream.Core/AcDream.Core.csproj — already has WB project ref from N.0.

Files added

• src/AcDream.Core/World/WbSceneryAdapter.cs — LandBlock → TerrainEntry[] and any other small adapters needed.
• tests/AcDream.Core.Tests/World/SceneryGeneratorWbConformanceTests.cs — side-by-side test asserting our generator's output equals what comes out when the same algorithms are called via WB directly.

Files deleted (eventually, after flag is on by default)

• The deleted helpers in SceneryGenerator.cs mentioned above.

Feature flag

Phase 1 of the rollout: ACDREAM_USE_WB_SCENERY=1 (default off — old path runs). When the env var is set, the new WB-backed path runs.

Phase 2 (after visual verification at Holtburg / 0xA9B1): flag default-on. Old path can still be reached via ACDREAM_USE_WB_SCENERY=0.

Phase 3 (one or two sessions later, after no regressions): delete the flag and the old code paths entirely.

Done criteria

1. dotnet build green with no new warnings.
2. All existing tests pass (870+).
3. New conformance test passes: SceneryGeneratorWbConformanceTests runs both code paths against fixture LandBlock data and asserts identical spawn lists (same ObjectId, same LocalPosition within 1e-4, same Rotation within 1e-4, same Scale within 1e-4).
4. Visual verification at landblock 0xA9B1 (Holtburg area):
   • The offending tree near the road that retail/WB do not show is gone in our render.
   • Issue #49's previously missing scenery (the tree from the 9×9 loop expansion) is still visible.
   • No new visual regressions in surrounding landblocks during a brief flight around Holtburg.
5. Issue #49 stays closed; no new issues filed.

Risks (Phase-N.1-specific)

1. TerrainEntry field semantics. WB packs Type/Scenery/Road/ Height into the TerrainEntry struct in a specific format. Getting the adapter wrong means OnRoad / scenery selection produces different results than ours. Mitigation: read WorldBuilder.Shared/Modules/Landscape/Models/TerrainEntry.cs carefully; cross-check against WB's TerrainUtils.GetRoad / GetTerrainEntryForCell to confirm field encoding.
2. RegionInfo dependencies. WB's TerrainUtils.GetNormal takes a RegionInfo parameter. We need to either build a minimal RegionInfo from our Region dat or call WB's normal calc differently. Mitigation: investigate during implementation; expect this is a small wrapper.
3. obj.MaxScale / obj.MinScale divide-by-zero. Our code checks if (obj.MinScale == obj.MaxScale) first; WB's ScaleObj does the same per-line review of references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/SceneryHelpers.cs:42-51. Should be a non-issue.
4. Rotation quaternion convention. Our rotation produces headingQuat * baseLoc.Orientation. WB's RotateObj calls SetHeading which does its own composition. Need to confirm the resulting quaternion is the same convention our renderer expects. Mitigation: the conformance test catches this if it's wrong.

Testing

Conformance test (new)

SceneryGeneratorWbConformanceTests:

• Construct a synthetic LandBlock with known terrain data.
• Run SceneryGenerator.Generate(...) with ACDREAM_USE_WB_SCENERY=0 and again with =1.
• Assert spawn counts equal.
• Assert each spawn's ObjectId, LocalPosition (within 1e-4), Rotation (within 1e-4 per component), Scale (within 1e-4) are equal.

Existing tests

SceneryGeneratorTests covers: road-vertex predicate, edge-vertex displacement bounds, interior-vertex displacement bounds. These tests exercise our internal helpers (IsRoadVertex, DisplaceObject). After N.1, the DisplaceObject test must be either deleted (if we delete the helper) or replaced (if we keep IsRoadVertex as a small predicate — it's only one bit-test).

Visual verification

User runs the client against ACE locally:

• Navigate to landblock 0xA9B1 (Holtburg). Verify offending tree near road is gone.
• Confirm Issue #49's tree is still visible.
• Fly around Holtburg, scan visible scenery for any obvious regression.

Out of scope for N.1

• Replacing our SceneryRenderManager (we don't have one — we have SceneryGenerator producing ScenerySpawn[] and the renderer consuming it directly). N.1 only touches the generator.
• Replacing our terrain math helpers (that's N.2).
• Replacing the static-object renderer (that's N.6).
• Anything in N.2-N.10.