erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
acdream/docs/architecture/worldbuilder-inventory.md

33 KiB
Raw Blame History

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 🟢.