acdream/docs/architecture/worldbuilder-inventory.md

# WorldBuilder Inventory — what we extracted, adapted, or left behind

> **Phase O shipped 2026-05-21.** The ~33 WB files we actually use have
> been extracted into our tree. `references/WorldBuilder/` stays as a
> **read-reference only** — nothing in `src/AcDream.*` references it as a
> project dependency. `DatCollection` is now the only dat reader in process.
>
> Use this document to:
> 1. Know **where our extracted code lives** (look for the "Extracted to"
>    column / notes in each section below).
> 2. Know **what WB still has** that we haven't needed yet — grep
>    `references/WorldBuilder/` if you ever need to add something.
> 3. Know **what WB never had** (the 🔴 list) — those are always ours.

**Pre-O status (archived for context):** As of Phase N.4 (2026-05-08)
acdream relied heavily on WorldBuilder as a project reference for rendering
and dat-handling. WorldBuilder is MIT-licensed, verified by visual inspection
to render the AC world correctly (terrain, scenery, slabs, dungeons, slopes,
particles), and uses the same Silk.NET + .NET stack we target.

**Post-O integration model:** Extracted WB code lives in two locations in
our tree (see CLAUDE.md for the full breakdown):
- `src/AcDream.Core/Rendering/Wb/` — pure helpers (no GL): `TerrainUtils`,
  `TerrainEntry`, `RegionInfo`, `SceneryHelpers`, `TextureHelpers`.
- `src/AcDream.App/Rendering/Wb/` — GL infrastructure + mesh pipeline:
  `ObjectMeshManager`, `WbMeshAdapter`, `WbDrawDispatcher`, texture cache,
  shader infra, EnvCell/portal/scenery/terrain-blending pipeline classes.

**EnvCell streaming seam:** `EnvCellLandblockBuildBuilder` is an acdream-owned
adapter around the extracted WB rendering path. One streaming job privately builds
the complete portal-cell + shell-placement payload, and `EnvCellRenderer.CommitLandblock`
publishes that completed snapshot on the render thread. WB's geometry-id arithmetic
and mesh preparation remain unchanged; the transaction wrapper exists because
acdream streams asynchronously while the WB editor's manager owned its own loading
loop. Do not reintroduce worker-side `RegisterCell` calls or shared pending cell
collections.

`DatCollectionAdapter` bridges the sole `DatCollection` to Content's
`IDatReaderWriter`. Since MP1c, production `ObjectMeshManager` no longer reads
DAT; the adapter remains the bounded typed-object access seam for runtime
non-render content plus explicit bake/equivalence tooling.

**MP1a (2026-07-05): CPU mesh-extraction half moved to `AcDream.Content`.**
The GL-free portion of the former `ObjectMeshManager` — dat read → polygon
walk → vertex/index build → inline BCn/palette texture decode →
`ObjectMeshData` — is now `MeshExtractor` in a new `src/AcDream.Content/`
assembly (no Silk.NET dependency), so the MP1b bake tool can run the exact
same extraction code offline without an OpenGL context. This was a
mechanical, verbatim move (namespace + visibility only) per
`docs/superpowers/plans/2026-07-05-mp1a-content-extraction.md` — no
behavior change, no divergence-register row.

- `src/AcDream.Content/MeshExtractor.cs` — the `Prepare*` family
  (`PrepareMeshData`, `PrepareSetupMeshData`, `PrepareGfxObjMeshData`,
  `PrepareEnvCellMeshData`, `PrepareCellStructMeshData`,
  `PrepareCellStructEdgeLineData`) + private helpers (`CollectParts`,
  `CollectEmittersFromScript`, `ComputeBounds`, `BuildPolygonIndices`,
  `BuildCellStructPolygonIndices`) and the decoded-texture cache /
  `ThreadLocal<BcDecoder>` that back them.
- `src/AcDream.Content/ObjectMeshData.cs` — the CPU-side boundary records:
  `VertexPositionNormalTexture`, `StagedEmitter`, `ObjectMeshData`,
  `MeshBatchData`, `TextureBatchData`.
- `src/AcDream.Content/TextureKey.cs` — the atlas dedup key, lifted out of
  the GL-owning `TextureAtlasManager` (which stays in App and now
  references the lifted struct).
- `src/AcDream.Content/UploadFormats.cs` — Content-owned
  `UploadPixelFormat`/`UploadPixelType` enums carried by
  `MeshBatchData`/`TextureBatchData` instead of
  `Silk.NET.OpenGL.PixelFormat`/`PixelType` (Content must stay
  Silk.NET-free — the bake tool must not ship GL binaries). Underlying
  values are the GL ABI constants, numerically identical to the Silk.NET
  members; App casts at its single upload boundary (the `AddTexture` call
  in `UploadGfxObjMeshData`) via a lifted nullable enum conversion —
  value- and null-preserving.
- `src/AcDream.Content/IDatReaderWriter.cs`, `EdgeLineBuilder.cs` — GL-free
  dependencies of the extractor, moved (namespace-only) alongside it.
- **Side-stage sink seam:** `CollectEmittersFromScript` pre-loads particle
  GfxObj meshes mid-extraction and, pre-MP1a, enqueued them directly onto
  `ObjectMeshManager._stagedMeshData`. The extractor now takes an
  `Action<ObjectMeshData>? sideStagedSink` constructor parameter; App wires
  it to `_stagedMeshData.Enqueue`, preserving the original
  immediate-enqueue semantics exactly — including on a mid-`Prepare*`
  throw (preloads staged before a malformed-dat texture-decode exception
  survive, as they always did). The MP1b bake tool passes its own
  collector.
- **Stays in `src/AcDream.App/Rendering/Wb/`:** `ObjectMeshManager` (the
  staged-queue/worker-pool/Dispose-quiesce lifecycle and all GL upload;
  production workers now consume `IPreparedAssetSource`),
  `ObjectRenderData`/`ObjectRenderBatch`
  (hold a GL `TextureAtlasManager` field), `TextureAtlasManager`,
  `GeometryUtils` (used only by App-side raycasting, not by extraction),
  `AcSurfaceMetadata`/
  `AcSurfaceMetadataTable` (not on the extraction path), `Building.cs`
  (explicitly out of scope).
- `AcDream.Core` is untouched; `AcDream.Content` references `AcDream.Core`
  (for `TextureHelpers`, `Sphere`/`BoundingBox` via `Chorizite.Core.Lib`);
  `AcDream.App` references `AcDream.Content`. `AcDream.Core` does NOT
  reference `AcDream.Content` (one-way dependency, per Code Structure Rule 2).
- Reason: MP1 (`docs/superpowers/specs/2026-07-05-modern-pipeline-design.md`
  §6.1) — the bake tool needs the identical mesh/texture extraction code
  running with no GL context, so baked pak output and live-client output stay
  byte-identical.

**MP1b EnvCell content identity correction (2026-07-24).** The extracted
WorldBuilder `EnvCellRenderManager.GetEnvCellGeomId` 31× polynomial is not a
safe unique resource key. A guarded full retail-DAT catalog found the concrete
collision `0x00030175` versus `0x01BC0105`: different environment/surface
tuples both map to `0x00000002020E8C13` and contain different polygons.
`AcDream.Core.Rendering.Wb.EnvCellGeometryIdentity` now owns one namespaced
FNV-1a identity shared by the App streaming build and `acdream-bake`; the
legacy calculation remains executable only for the conformance test that proves
the collision. The bake additionally compares the complete source tuple before
aliasing and fails on any collision. This is an acdream resource-ownership seam,
not a second DAT interpreter; `DatCollection` and `MeshExtractor` remain the
only reader/extractor path.

**MP1c production prepared-asset cutover (2026-07-24).** Production
world-mesh workers no longer invoke `MeshExtractor` or rebuild Setup, GfxObj,
EnvCell, Surface, palette, and texture graphs during portals. The validated
machine-local `acdream.pak` is opened through Content's
`IPreparedAssetSource`; typed GfxObj and EnvCell requests deserialize immutable
`ObjectMeshData` while retaining the existing App worker, staging, render-thread
upload, cache, ownership, and shutdown contracts. The original
format-1/bake-tool-3 render payload persists exact batch translucency so App
does not reconstruct a
`GfxObjMesh` for metadata. Setup activation uses the package TOC as an explicit
type-presence index before reading valid Setup records through the bounded DAT
cache. `DatPreparedAssetSource` and `MeshExtractor` remain explicit
bake/equivalence/UI-Studio tools, not a production fallback. Portal → HighRes
→ Language → Cell lookup precedence is encoded directly in
`DatCollectionAdapter.TryResolvePreferred`. The connected physical and
installed-DAT gates are recorded in
`docs/research/2026-07-24-slice-c-prepared-asset-cutover-report.md`.

**Slice I3 prepared collision extension (2026-07-25).** The package remains
format 1 and retains mesh type values 1–3; bake-tool 4 appends typed GfxObj,
Setup, CellStruct, and EnvCell-topology collision payloads. Core owns the
immutable flat records and deterministic raw-DAT flattener. Content owns the
strict little-endian codec and `IPreparedCollisionSource`.
`PakPreparedAssetSource` implements the render and collision interfaces over
one mmap; it does not create a second DAT reader or mapping. CellStruct
payloads alias only after exact serialized-byte comparison, while each
EnvCell topology remains independently keyed. Production traversal remained
on the parsed graph oracle until the later Slice-I cutover. Full-catalog evidence:
`docs/research/2026-07-25-slice-i3-prepared-collision-package.md`.

**Slice I5 dual-publication seam (2026-07-25).** Near-tier
`LandblockBuild` payloads now carry one immutable prepared-collision closure
outside the DAT lock. `LandblockPhysicsPublisher` installs the parsed oracle
and flat view under the same retained receipt; live objects use the strict
`LiveCollisionAssetPublisher`. Cell/topology ownership is landblock-scoped and
withdrawn on replacement, demotion, removal, and reset. The connected
graph-authoritative referee completed 14,064 exact samples with no mismatch or
fault. This is still one `DatCollection` and one prepared-package mmap, not a
second reader or a WorldBuilder runtime dependency. Evidence:
`docs/research/2026-07-25-slice-i5-dual-collision-shadow.md`.

**Slice I6/I7 flat-authoritative closeout (2026-07-25).** Production
`PhysicsDataCache` now publishes only immutable flat GfxObj, Setup,
CellStruct, and EnvCell-topology records from the validated package. Stable
world state strips temporary `PhysicsDatBundle` source material, and near
landblock builds discard raw Environment/GfxObj collision graphs once the
flat closure exists. Parsed graph constructors remain explicit
test/bake/equivalence oracles only; gameplay has no graph fallback or referee.
Both exact-binary connected routes report `0/0/0` retained parsed collision
graphs at every stable checkpoint while flat residency remains populated.
This remains one `DatCollection`, one preparation algorithm, and one package
mmap. Evidence:
`docs/research/2026-07-25-slice-i7-closeout.md`.

**Prepared indoor-transit consumer correction (2026-07-26).** The package
already retained exact portal planes through
`FlatEnvCellTopology.PolygonIndex` plus the aliased CellStruct portal-polygon
table. The production `CellTransit` consumer now reads that prepared
relationship directly; it no longer treats the intentionally absent parsed
`CellPhysics.PortalPolygons` dictionary as “this cell has no portals.” No
package schema, bake, DAT reader, collision formula, or render portal graph
changed. Evidence:
`docs/research/2026-07-26-prepared-indoor-transit-regression.md`.

**Retail VFX hook compatibility seam (2026-07-14).** Chorizite.DatReaderWriter
2.1.7 models `CreateBlockingParticleHook` as the common hook header only, while
retail inherits the complete `CreateParticleHook` payload. The narrow readers in
`src/AcDream.Content/Vfx/` read raw bytes through the existing `DatCollection`
database, delegate every ordinary hook to the package, and substitute only the
retail blocking-particle shape. Both live animation playback and PhysicsScript
loading use those cached readers; `MeshExtractor` uses the same PhysicsScript
loader when preloading emitter meshes. This is not a second DAT reader:
`DatCollection` remains the sole database owner and access path. Retail anchors:
`CreateBlockingParticleHook::Execute` `0x00526EF0` and
`ParticleManager::CreateBlockingParticleEmitter` `0x0051B8A0`.

**Retail particle visibility/degradation seam (2026-07-17).** WorldBuilder's
particle simulator remains a useful DAT-integrator and batching reference, but
it does not carry the live retail client's `CObjCell::IsInView` degradation
path. `EmitterDescRegistry` now resolves the hardware particle GfxObj and its
ordered `GfxObjDegradeInfo` entries through the same sole `DatCollection`;
`ParticleSystem` ports the retail finite/infinite degraded branches; App feeds
the unified PView interior set plus the landscape renderer's independently
computed outdoor landcell set through a focused
`ParticleVisibilityController`. Examination and dedicated-pass emitters carry
an explicit bypass policy; missing/portal world views are empty rather than
fail-open.
No WorldBuilder dependency or second DAT access layer was introduced. Retail
anchors: `CPhysicsPart::GetMaxDegradeDistance` `0x0050D510`,
`GfxObjDegradeInfo::get_max_degrade_distance` `0x0051E2D0`,
`CPhysicsObj::ShouldDrawParticles` `0x0050FE60`, and
`ParticleEmitter::UpdateParticles` `0x0051D180`.

Hardwareless ParticleEmitterInfo records are also retained exactly. Retail
`ParticleEmitter::SetInfo @ 0x0051CE90` returns false when
`hw_gfxobj_id == INVALID_DID`; it does not substitute the software GfxObj.
`EmitterDescRegistry` negative-caches that authored outcome and the hook sink
reports it once per DAT ID rather than once per owner. This is classification
and bounded diagnostics around the existing `DatCollection`, not a fallback
reader or invented VFX. Evidence:
`docs/research/2026-07-26-retail-hardwareless-particle-emitter-diagnostics.md`.

**Retail shared world-alpha seam (2026-07-18).** WorldBuilder's editor
renderers classify translucent mesh batches correctly, but they have no live
retail `CPartCell`/`CShadowPart` list and render particles in a separate
batcher. `src/AcDream.App/Rendering/RetailAlphaQueue.cs` is therefore an
acdream-owned runtime seam above the extracted mesh pipeline. During the main
world frame, `WbDrawDispatcher` and `ParticleRenderer` submit transparent
GfxObj subsets and scene particles into one stable far-to-near stream keyed by
the transformed DAT `SortCenter`; only adjacent compatible entries may batch.
Billboard particle textures are resident bindless `sampler2DArray` handles in
the per-instance vertex ABI, so different textures preserve that sorted order
inside one instanced draw; only a DAT blend-mode boundary splits the run. This
keeps dense particle fields from becoming one GL draw per alternating texture.
`RetailPViewRenderer` drains the landscape scope before the optional depth
clear, and `GameWindow` drains the final scope before private viewports/UI.
Sky and sealed off-screen render targets remain independent. No DAT reader,
mesh decoder, or second scene graph was introduced. Retail anchors:
`CPhysicsPart::UpdateViewerDistance` `0x0050E030`,
`RenderDeviceD3D::DrawObjCellForDummies` `0x005A0760`,
`CShadowPart::insertion_sort` `0x006B5130`,
`D3DPolyRender::AddMeshToAlphaList` `0x0059C230`, and
`D3DPolyRender::FlushAlphaList` `0x0059D2E0`. The modern per-cell-order and
EnvCell-shell residual is tracked explicitly as AP-34.

**Retail portal-space viewport adapter (2026-07-15).**
`src/AcDream.App/Rendering/PortalTunnelPresentation.cs` uses the extracted
Setup/GfxObj mesh pipeline and mandatory `WbDrawDispatcher` for retail's
synthetic CreatureMode tunnel object. The adapter does not duplicate mesh or
DAT decoding: it resolves the two client-enum assets through `DatCollection`,
uses the shared `RetailAnimationLoader`, registers Setup part refs through
`WbMeshAdapter`, and submits the animated `SetupMesh` through the existing
dispatcher. It clears world clip routing and point lights for the private scene
before installing retail's distant light. The lifecycle, camera, animation,
and draw ordering are acdream-owned ports of `gmSmartBoxUI`; WorldBuilder never
implemented this UI viewport.

**Portal destination render-readiness seam (2026-07-16).**
`GpuWorldState.IsRenderReady` does not treat dictionary publication as a draw
barrier. `LandblockSpawnAdapter` retains the complete required-id set for each
landblock: atlas-tier GfxObjs plus the synthetic geometry ids prepared by the
independent EnvCell shell pipeline. `WbMeshAdapter.IsRenderDataReady` opens the
gate only after `ObjectMeshManager` has real GPU render data. Its bounded CPU
cache retains texture payloads and stages a missing GPU object through a
deduplicated upload queue on cache hit only when the exact renderer owner is
still live, covering eviction and revisit churn without letting an unowned
cache hit recreate stale staged work. Reacquiring an exact owner stages once.
GPU upload is deliberately not an ownership acquire: atlas GfxObjs use their
landblock/entity pins, while synthetic EnvCell geometry uses a no-generic-decode
pin balanced from each landblock snapshot. A late upload after all owners have
released enters the evictable LRU instead of resurrecting a reference. After
publication pins the synthetic ids, the controller replays their immutable
environment/cell-structure/surface preparation descriptors; if a formerly
unowned mesh was evicted between worker scheduling and publication, this
schema-aware replay re-stages it without a generic GfxObj lookup.
Near-to-Far demotion is a separate App transaction: it releases EnvCell
rendering and landblock mesh pins while retaining the terrain slot. Core's
matching physics demotion preserves the terrain surface but removes indoor
cells, portals, buildings, and static shadow registrations.

**Cost-budgeted publication seam (2026-07-24).** WorldBuilder's editor path
publishes a complete manager-owned scene; acdream's live streamer instead
advances prepared render, physics, static, building, EnvCell, and spatial
receipts under one typed frame meter. Stable cursor work may span frames, while
building/EnvCell replacement and the final `GpuWorldState` spatial identity
swap remain observer-atomic. Destination live-object render ownership prepares
while the world is quiesced. `GpuWorldState.IsLiveEntityProjectionResident`
answers that spatial ownership question; availability-gated drawing,
collision, picking, radar/status targeting, effects, and audio continue to use
`IsLiveEntityVisible`. This is an acdream async-integration seam around the
extracted WB pipeline, not a second mesh or DAT implementation. Connected
evidence:
`docs/research/2026-07-24-slice-e-cost-budgeted-streaming-report.md`.

**Bounded residency and GPU retirement seam (2026-07-18).** Runtime DAT access
keeps raw file payload caching disabled and layers bounded typed-object and
decoded-pixel LRUs above the single `DatCollection`. `ObjectMeshManager`, the
standalone bindless texture cache, and the owner-scoped composite texture-array
cache all distinguish an active owner from an evictable unowned entry. Appearance
changes and landblock demotion acquire-before-publish and withdraw-before-release;
rebucketing never creates a second owner. `GlobalMeshBuffer` uses reclaimable,
coalescing vertex/index ranges and migrates incrementally within explicit physical
ceilings. Texture layers, terrain slots, mesh ranges, and old backing stores are
returned only after `GpuFrameFlightController` observes the frame fence that can
no longer reference them. This lifetime machinery is acdream-owned integration
around the extracted WB mesh pipeline; it does not add a second DAT decoder or a
reduced-distance rendering path.

**Unified residency policy seam (2026-07-24).** The extracted WB caches remain
the physical owners of mesh, arena, atlas, and texture resources.
`AcDream.App.Rendering.Residency.ResidencyManager` adds an acdream-owned typed
policy/diagnostic layer over them: generation-safe asset handles, independent
owner tokens and leases, immutable startup budgets, aggregate accounting, and
bounded trim requests. It never stores or deletes a GL name. Existing owners
perform logical eviction and fence-delayed physical release on the render
thread. The same ledger observes the prepared-package mapping, prepared/staged
CPU mesh data, decoded animation/audio data, and retained shared-alpha scratch
without double-counting the package's clean memory-mapped pages as committed
heap. Deterministic pressure tests exceed every configured ceiling and prove
zero-charge teardown. Connected evidence:
`docs/research/2026-07-24-slice-d-unified-residency-report.md`.

**Workflow:** Before re-implementing any AC-specific rendering or dat-handling
algorithm, **check this inventory first**. If we already extracted it (🟢
sections), it's in `src/AcDream.App/Rendering/Wb/` — use our copy. If WB has
it but we haven't extracted it yet, grep `references/WorldBuilder/` and extract
as needed. Retail decomp remains the oracle for things WB never had (🔴 list).

Attribution: WorldBuilder is MIT-licensed. `NOTICE.md` includes WB attribution.

---

## Read-reference layout (under `references/WorldBuilder/`, not project-referenced)

- **`Chorizite.OpenGLSDLBackend/`** — full OpenGL renderer (Silk.NET). The
  components we use are extracted into `src/AcDream.App/Rendering/Wb/`.
- **`WorldBuilder.Shared/`** — data models, dat parsers, landscape module.
  The helpers we use are extracted into `src/AcDream.Core/Rendering/Wb/`.
- **`WorldBuilder/`** — Avalonia desktop app shell (not taken).
- **`WorldBuilder.{Windows,Linux,Mac}/`** — platform entry points (not taken).
- **`WorldBuilder.Server/`** — collab editing backend (not taken).
- **`Tests/` + `WorldBuilder.Shared.Benchmarks/`** — test harness (study only).

**Upstream NuGet dependencies** (these stay as NuGet packages, we don't
vendor them):

| Package | Version | Purpose |
|---|---|---|
| `Chorizite.Core` | 0.0.18 | Plugin framework — contains `Chorizite.Core.Lib.BoundingBox`, `Chorizite.Core.Render.*` interfaces used by every render manager |
| `Chorizite.DatReaderWriter` | 2.1.x | dat parsing (we already use 2.1.7) |
| `Chorizite.DatReaderWriter.Extensions` | 1.1.x | extra dat helpers |
| `BCnEncoder.Net` | 2.2.x | DXT decode (we already use) |
| `SixLabors.ImageSharp` | 3.1.x | image loading |
| `Silk.NET.OpenGL` + `Silk.NET.SDL` | 2.23.x | GL + windowing (we use Silk's own windowing, they use SDL) |
| `MP3Sharp` | 1.0.5 | MP3 decode |

---

## 🟢 RENDERING — take wholesale or adapt

These are what makes WB "perfect". Anything in this section, we should
use from WB rather than re-implement.

### Terrain

| Component | What it does |
|---|---|
| `TerrainRenderManager` | Full pipeline (per-chunk GPU buffers, draw orchestration) |
| `LandSurfaceManager` | Texture blending atlas (palCode, alpha masks, road overlays) |
| `TerrainGeometryGenerator` | Heightmap → mesh, normals, OnRoad, GetHeight, GetNormal |
| `TerrainChunk` | 16×16 landblock chunk geometry |
| `TextureAtlasManager` | Texture atlas builder |
| `VertexLandscape` | Terrain vertex format |

**Modern terrain adapter:** acdream's bindless path uses `TerrainAtlas` plus
`TerrainModernRenderer` rather than WB's draw manager, but retains
`LandSurfaceManager`'s layer-indexed `TerrainTex.TexTiling` contract. The
36-entry table is uploaded to `terrain_modern.frag`; base, overlay, and road
layers each use their owning repeat count while alpha masks stay at cell scale.
Retail `TexMerge::CopyAndTile` (`0x00503580`) and `TexMerge::Merge`
(`0x005038C0`) are the behavior oracle; see
`docs/research/2026-07-13-retail-terrain-texture-tiling-pseudocode.md`.

### Scenery (procedural placement: trees, bushes, rocks, fences)

| Component | What it does |
|---|---|
| `SceneryRenderManager` | Generate + render per-vertex scenery |
| `SceneryHelpers` | Displace / RotateObj / ScaleObj / ObjAlign / CheckSlope |
| `SceneryInstance` | Per-spawn instance data |

acdream's streamed projection assigns generated instances local runtime IDs
through `AcDream.Core.World.ProceduralSceneryIdAllocator`. The namespace is
`0x8XXYYIII` (full X/Y bytes plus a 12-bit counter); bit 31 remains the stable
scenery classification seam. This is projection identity, not placement
behavior. The former 8-bit counter rejected dense retail-DAT landblocks before
their render transaction could publish (#218).

### Static objects (buildings, slabs, props — Setup + GfxObj + ObjDesc)

| Component | What it does |
|---|---|
| `StaticObjectRenderManager` | Master pipeline for static objects |
| `ObjectRenderManagerBase` + `BaseObjectRenderManager` | Common render base |
| `ObjectMeshManager` | Mesh extraction from Setup/GfxObj, ObjDesc application |

### Dungeons / interiors

| Component | What it does |
|---|---|
| `EnvCellRenderManager` | Dungeon interior cell geometry |
| `PortalRenderManager` | Portal traversal / visibility |

### Sky + atmosphere

| Component | What it does |
|---|---|
| `SkyboxRenderManager` | Skybox rendering |
| `ParticleEmitterRenderer` + `ParticleBatcher` + `ActiveParticleEmitter` | Particle systems (sky particles, weather, magic) |

### Visibility / culling

| Component | What it does |
|---|---|
| `VisibilityManager` + `VisibilitySnapshot` | Frustum + cell visibility |
| `Frustum` | Frustum-cull math |

### Other rendering helpers

| Component | What it does |
|---|---|
| `MinimapRenderer` | Top-down minimap |
| `GlobalMeshBuffer` | Shared GPU mesh buffer; one reclaimable vertex/index allocation per mesh, released by `ObjectMeshManager` eviction |
| `GpuResourceManager` | GPU resource lifecycle |
| `InstanceData` | Instanced draw data |
| `TextureHelpers` | INDEX16, P8, BGRA, DXT decode + alpha (canonical port) |
| `DebugRenderer` + `DebugRendererLineDrawer` + `EdgeLineBuilder` | Debug primitives |

### Shaders (22 total)

Located at `Chorizite.OpenGLSDLBackend/Shaders/`:

`Landscape.{vert,frag}` · `StaticObject.{vert,frag}` · `StaticObjectModern.{vert,frag}` · `Particle.{vert,frag}` · `PortalStencil.{vert,frag}` · `Outline.{vert,frag}` · `Simple3D.{vert,frag}` · `InstancedLine.{vert,frag}` · `Text.{vert,frag}` · `UI.{vert,frag}` · `Gizmo.{vert,frag}` (editor-only)

---

## 🟢 LOW-LEVEL GL / FRAMEWORK — take or replace with our own

Either take WB's wrappers wholesale, or keep our own and adapt the
render managers to use ours. These wrappers are stateless or
near-stateless and are the easiest to swap.

| Component | What it does |
|---|---|
| `OpenGLGraphicsDevice` | Silk.NET.OpenGL wrapper |
| `OpenGLRenderer` | Render orchestration |
| `GLSLShader` | Shader compile/link/uniforms |
| `GLHelpers` + `GLStateScope` | GL state utility |
| `ManagedGLFrameBuffer` / `ManagedGLIndexBuffer` / `ManagedGLTexture` / `ManagedGLTextureArray` / `ManagedGLUniformBuffer` / `ManagedGLVertexArray` / `ManagedGLVertexBuffer` | GL resource wrappers |
| `TextureParameters` | Sampler config |
| `GpuMemoryTracker` | Memory tracking |
| `Camera2D` / `Camera3D` / `CameraBase` / `ICamera` / `CameraController` | Camera primitives |
| `GameScene` + `SingleObjectScene` + `SceneData` + `ModernRenderData` + `RenderPass` | Scene / pass structures |

---

## 🟢 GEOMETRY / MATH UTILS — take wholesale

| Component | File |
|---|---|
| `TerrainUtils` (OnRoad, GetNormal, GetHeight, GetRoad, palCode) | `WorldBuilder.Shared/Modules/Landscape/Lib/TerrainUtils.cs` |
| `TerrainCacheManager` | `…/Lib/TerrainCacheManager.cs` |
| `TerrainRaycast` | `…/Lib/TerrainRaycast.cs` |
| `GeometryUtils` | `WorldBuilder.Shared/Lib/GeometryUtils.cs` |
| `RaycastingUtils` (ray-vs-sphere/AABB/triangle) | `WorldBuilder.Shared/Lib/RaycastingUtils.cs` |
| `DoubleNumerics` (double-precision Vector/Matrix) | `WorldBuilder.Shared/Lib/DoubleNumerics.cs` |
| `DatUtils` | `WorldBuilder.Shared/Lib/DatUtils.cs` |
| `BoundingBoxExtensions` | `Chorizite.OpenGLSDLBackend/Lib/BoundingBoxExtensions.cs` |

---

## 🟢 DATA MODELS — take selectively

| Component | What it does |
|---|---|
| `RegionInfo` | Landblock metadata wrapper (LandblockSizeInUnits, CellSizeInUnits, etc.) |
| `TerrainEntry` | Per-vertex terrain (Type/Scenery/Road/Height) |
| `MergedLandblock` | Merged dat data |
| `CellSplitDirection` | SW-NE vs NE-SW |
| `Cell` | Generic cell wrapper |
| `ObjectId` | Object identifier |
| `Position` | World position |
| `ACEnums` | AC-specific enums |
| `WbBuildingPortal` / `WbCellPortal` | Portal structures |
| `BuildingObject` | Building data |

---

## 🟡 EDITOR-ONLY — leave behind / delete in fork

These exist for the editor experience and have no place in a game
client. Delete in fork.

- **`Modules/Landscape/Tools/*`** — `BrushTool`, `BucketFillTool`,
  `RoadLineTool`, `RoadVertexTool`, `InspectorTool`,
  `ObjectManipulationTool`, `Gizmo*` (DragHandler, HitTester, Renderer,
  State), `TexturePainting*`, `SceneRaycaster`,
  `LandscapeBrush`, `LandscapeToolBase`, `LandscapeToolContext`,
  `IToolSettingsProvider`, `ILandscapeBrush`, `ILandscapeEditorService`,
  `ILandscapeRaycastService`, `ILandscapeTool`, `ITexturePaintingTool`
- **`Modules/Landscape/Commands/*`** — undo/redo command pattern for
  editor (Add/Delete/Move/Rename/Reorder/etc.)
- **`LandscapeDocument` + `LandscapeLayer` + `LandscapeLayerGroup` + `LandscapeChunk` + `LandscapeLayerChunk` + `LandscapeLayerBase`** — editor document model
- **`Modules/Landscape/Models/TerrainPatch*` + `LandblockChangedEventArgs`** — editor mutation events
- **`Modules/Landscape/Services/ILandscapeCacheService` + `ILandscapeDataProvider` + `ILandscapeObjectService` + impls** — editor data flow
- **All `Migrations/*`** — SQLite schema migrations (project file format)
- **`Repositories/*`** + **`Services/*`** — project storage, dat repository, AceDb, SignalR sync, document manager, undo stack, world coordinates, keyword DB, project migration, semantic kernel AI helpers
- **`Hubs/*`** — collaborative editing via SignalR
- **`StaticObject` (editor model)** — replace with our own scene-state data model fed from network
- **`BackendGizmoDrawer` + `GizmoRenderer`** — editor gizmos
- **`ProjectStructures, IProject, Project`** — editor project files
- **`KeyBinding`** — editor input binding
- **`ViewportInputEvent[Extensions]`** — editor viewport input
- **`EditorState`** — editor state container

---

## 🟡 AUDIO / FONT — we already have alternatives

Keep ours; don't take theirs.

- **`AudioPlaybackEngine`** — uses MP3Sharp. We have OpenAL.
- **`FontRenderer`** — uses ImageSharp. We have BitmapFont/StbTrueTypeSharp + ImGui.

---

## 🔴 NOT IN WORLDBUILDER — port from retail decomp ourselves

WorldBuilder is a dat editor; it does not have:

- **Network protocol** — UDP framing, ISAAC, packet codec, ACE message
  layer (we have this; oracle is `references/holtburger`)
- **Physics** — collision (CPhysicsObj transitions, BSP queries, sphere
  sweeps), step-up, walkable validation (we have partial; oracle is the
  retail decomp at `docs/research/named-retail/`)
- **Animation** — motion sequencer, cycle/non-cycle parts, animation
  frame interpolation (we have this; oracle is retail decomp)
- **Movement** — local player WASD → MoveToState wire, remote-entity
  motion via UpdateMotion + dead-reckoning (we have this; oracle is
  `references/holtburger` + retail decomp)
- **Game UI** — chat, vitals, inventory, spell book, allegiance, options
  (we have this; ImGui-based today, custom-toolkit later)
- **Plugin API** — `IGameState`, `IEvents`, `IActions`, `IPacketPipeline`,
  `IOverlay` (we have this — acdream-unique)
- **Game events** — combat, allegiance, spell casting, quest events
  (we have this; oracle is ACE for opcodes + retail for client behavior)
- **Audio** — OpenAL pipeline, sound triggers (we have this)
- **TurbineChat** + **slash commands** (we have this)
- **Login + character selection flow** (we have this)
- **World-object mouse selection** — WorldBuilder supplies mesh/DAT access but
  no retail client picker. Our narrow `RetailSelectionGeometryCache` reuses
  `DatCollection` to expose each GfxObj drawing-BSP root sphere and visual
  polygons; `WbDrawDispatcher` supplies the normal draw's current part
  transforms to the named-retail selection accumulator.

---

## What this means for the workflow (post-Phase O)

The CLAUDE.md "grep named → decompile → verify → port" workflow stays
the rule for everything in the 🔴 list (network, physics, animation,
movement, UI, plugin, audio, chat).

For anything in 🟢 that we've already extracted: **the code is in our
tree at `src/AcDream.{Core,App}/Rendering/Wb/`**. Read it there — don't
grep `references/WorldBuilder/` unless you want to compare against the
original. Re-porting from retail decomp when we already have a tested
port is still how we'd get the scenery edge-vertex bug back.

For anything in 🟢 that we have NOT yet extracted: grep
`references/WorldBuilder/` to find the source, then extract it using the
Phase O pattern (verbatim copy → adapt constructor to accept
`IDatCollection` via `DatCollectionAdapter` where needed → add to
`src/AcDream.App/Rendering/Wb/`). Do NOT add a new project reference back
to `WorldBuilder.Shared` or `Chorizite.OpenGLSDLBackend` — Phase O
permanently removed those.

When we discover a behavior mismatch with retail (rare — the extracted
code is the same as the original), the resolution is: reconcile extracted
code ↔ retail decomp ↔ holtburger ↔ ACE ↔ ACViewer (the existing
reference hierarchy in CLAUDE.md). Our extracted code ranks at the top
of that hierarchy for anything 🟢.