acdream/docs/architecture/acdream-architecture.md

# acdream — Comprehensive Architecture Plan

## Vision

A modern C# .NET 10 Asheron's Call client that:
- **Behaves identically to the retail client** — same physics, same
  animations, same terrain, same collision, same network protocol
- **Looks identical to the retail client** — same meshes, same textures,
  same lighting, same blending, rendered via modern Silk.NET OpenGL
- **Adds a plugin API** the retail client never had — native C# plugins
  + Lua macro scripting for player automation
- **Is NOT a 1:1 C++ port** — uses modern C# patterns (composition over
  inheritance, interfaces, dependency injection) while matching retail
  behavior exactly

## Guiding Principle

**The code is modern. The behavior is retail.**

Every AC-specific algorithm is ported faithfully from the **named retail
decomp** at `docs/research/named-retail/` — Sept 2013 EoR build PDB
(18,366 named functions, 5,371 named struct types) + Binary Ninja
pseudo-C with 99.6% function-name recovery + verbatim retail header
struct definitions. The older Ghidra `FUN_xxx` chunks at
`docs/research/decompiled/` (688K lines) remain a fallback for the
obfuscated/packed minority. The code AROUND those algorithms is modern
C# with clean architecture. The plugin API exposes game state through
well-defined interfaces that the retail client never had.

---

## Layer Architecture

```
┌──────────────────────────────────────────────────────────────┐
│  LAYER 5: Plugin API                                        │
│  IGameState, IEvents, IActions, IPacketPipeline, IOverlay   │
│  Plugin host (ALC), Lua macro engine (MoonSharp)            │
│  ► acdream-unique — not in retail client                    │
├──────────────────────────────────────────────────────────────┤
│  LAYER 4: Game Objects                                      │
│  GameEntity (one per world object)                          │
│    ├── PhysicsBody      (ported from decompiled)            │
│    ├── AnimSequencer     (ported from decompiled)            │
│    ├── CellTracker      (ported from decompiled)            │
│    ├── AppearanceState  (ObjDesc: palettes, textures, parts)│
│    └── MotionState      (ported from decompiled)            │
│  ► behavior matches retail, code is modern C# composition   │
├──────────────────────────────────────────────────────────────┤
│  LAYER 3: World Systems                                     │
│  TerrainSystem   (heightmap, blending, scenery)             │
│  CellSystem      (LandCells, EnvCells, portals, BSP)        │
│  StreamingSystem (background loading, LOD, frustum cull)    │
│  ► behavior matches retail, streaming is acdream-unique     │
├──────────────────────────────────────────────────────────────┤
│  LAYER 2: Network                                           │
│  WorldSession (ISAAC, fragments, game messages)             │
│  MessageRouter (opcode dispatch, sequence tracking)         │
│  ► wire-format identical to retail                          │
├──────────────────────────────────────────────────────────────┤
│  LAYER 1: Renderer                                          │
│  Silk.NET OpenGL 4.3 core profile                           │
│  TerrainRenderer, StaticMeshRenderer, TextureCache          │
│  Shaders (terrain blending, mesh lighting, translucency)    │
│  ► completely different from retail (D3D7), same visual     │
│    output                                                   │
├──────────────────────────────────────────────────────────────┤
│  LAYER 0: Platform                                          │
│  .NET 10, Silk.NET window/input, DatReaderWriter            │
│  ► acdream-unique infrastructure                            │
└──────────────────────────────────────────────────────────────┘
```

### UI Architecture (two coexisting presentation stacks)

The 2026-04-24 design began with a swappable renderer abstraction. D.2b proved
that retail fidelity needs a retained LayoutDesc/DAT tree, while ImGui remains
valuable as permanent devtools. The current architecture therefore has two
presentation stacks over shared state, ViewModels, events, and commands. Full
history and the corrected contract live in
`docs/plans/2026-04-24-ui-framework.md`.

```
┌─────────────────────────────────────────────────────────────┐
│  DEVELOPER UI                                               │
│  IPanel/IPanelRenderer → permanent ImGui devtools           │
│  GAMEPLAY UI                                                │
│  LayoutDesc/DAT → UiRoot retained widgets + controllers     │
├─────────────────────────────────────────────────────────────┤
│  SHARED CONTRACTS                                           │
│  ViewModels, commands, input actions, state/event services  │
│  ► one model and mutation path, two presentation projections│
├─────────────────────────────────────────────────────────────┤
│  Game state + events (unchanged)                            │
│  IGameState / IEvents / WorldSession — UI only reads        │
└─────────────────────────────────────────────────────────────┘
```

`AcDream.UI.Abstractions` owns backend-neutral ViewModels, commands, input,
and the `IPanel`/`IPanelRenderer` devtools contract. `AcDream.App/UI` owns the
retained gameplay tree, LayoutDesc importer, window runtime, and panel
controllers. Neither presentation stack owns independent game-state truth.
Chat submission follows the same rule: both presentation stacks enter the
shared `ChatCommandRouter`, which emits distinct backend-neutral intents for a
retail client command (`ExecuteClientCommandCmd`), an ACE-owned command
(`SendServerCommandCmd`), or ordinary chat (`SendChatCmd`). App-layer
handlers and controllers translate those intents to `WorldSession`; panels
never inspect or construct wire messages.
Plugins register retained gameplay markup through the BCL-only
`AcDream.Plugin.Abstractions.IUiRegistry`; they do not import App or ImGui
assemblies. Core `SelectionState` is the sole selected-object owner for world,
radar, inventory, paperdoll, toolbar, use/examine consumers, and plugins;
`IPluginHost.Selection` exposes that same state and retail-style old/new callback.
Temporary pointer modes are separate App orchestration in `InteractionState` and
must never become a competing selection owner.

Every retained gameplay window has a typed `RetailWindowHandle` and at most one
`IRetainedPanelController` lifecycle owner. Multi-controller windows use
`RetainedPanelControllerGroup`; the manager disposes controllers exactly once in
reverse ownership order. `UiHost` removes Silk device subscriptions first, then
disposes the manager/controllers, then its GL renderer. `GameWindow.OnClosing`
tears this runtime down before session and game-state sources.

`RetailUiRuntime` is the production composition boundary. `GameWindow` creates
the GL/DAT resolvers and supplies focused state/action binding records in one
mount call; the runtime owns all LayoutDesc imports, controller construction,
window registration, plugin mounts, cursor feedback, layout persistence, and the
retained tick/draw/restore/dispose paths. Panel-specific construction must not
move back into `GameWindow.OnLoad`.

---

## Project Structure (current + target)

```
src/
  AcDream.Core/              Layer 2-4: no GL, no Silk.NET, pure logic
    Physics/
      PhysicsBody.cs          -> body state / integration foundation (done)
      CollisionPrimitives.cs  -> retail primitive helpers (partial, active)
      MotionInterpreter.cs    -> motion state machine (done, still L.1 polish)
      AnimationSequencer.cs   -> animation playback + root-motion data (done, L.1 active)
      TerrainSurface.cs       -> triangle-aware terrain contact (done)
      BSPQuery.cs             -> partial retail BSP dispatcher (active in L.2)
      TransitionTypes.cs      -> SpherePath / CollisionInfo / transition helpers (active in L.2)
      PhysicsDataCache.cs     -> GfxObj / Setup / CellStruct collision data (done, active)
      ShadowObjectRegistry.cs -> broadphase for nearby physics objects (active)
      PhysicsEngine.cs        -> ResolveWithTransition active player path
      ProjectilePhysicsStepper.cs -> pure retail projectile integration + sweep
      RetailFrameMath.cs      -> retail full-3D vector-heading frame construction
      CellBsp.cs              -> not a first-class runtime owner yet (L.2e)
    World/
      GameEntity.cs           -> target unified entity, not current reality
      WorldState.cs           -> target entity owner
      CellTracker.cs          -> target per-entity cell management
      SceneryGenerator.cs     -> verified against decompiled (done)
      LandblockLoader.cs      -> done
    Terrain/
      LandblockMesh.cs        -> verified against ACME (done)
      TerrainBlending.cs      -> verified against ACME (done)
    Meshing/
      GfxObjMesh.cs           -> cross-checked against ACME (done)
      SetupMesh.cs            -> cross-checked (done)
    Textures/
      SurfaceDecoder.cs       -> done
    Dat/
      MotionResolver.cs       -> done (target move from Meshing/)
  
  AcDream.Core.Net/          Layer 2: networking
    WorldSession.cs           -> done (wire-compatible with ACE)
    NetClient.cs              -> done
    Messages/                 -> done (CreateObject, MoveToState, etc.)
  
  AcDream.Plugin.Abstractions/  Layer 5: plugin interfaces
    IAcDreamPlugin.cs         -> done
    IPluginHost.cs            -> done
    IGameState.cs             -> done
    IEvents.cs                -> done
    ISelectionService.cs      -> done
  
  AcDream.App/               Layer 1 + Layer 4 wiring
    Physics/
      ProjectileController.cs -> live-record projectile orchestration/corrections
      RemotePhysicsUpdater.cs -> ordinary/Hidden remote narrow-tick integration
      RemoteTeleportController.cs -> incarnation-scoped loaded/pending placement owner
      RemoteTeleportHook.cs   -> ordered retail teleport teardown seam
      RemoteTeleportPlacement.cs -> collision-seated SetPosition transition commit
    World/
      LiveEntityRuntime.cs    -> canonical logical identity/state/spatial ownership
      LiveEntityPresentationController.cs -> Hidden/NoDraw/effect/collision presentation
      LiveEntityTeardown.cs   -> failure-isolated multi-owner lifecycle drain
    Rendering/
      GameWindow.cs           -> still owns too much runtime wiring
      TerrainRenderer.cs      -> done
      StaticMeshRenderer.cs   -> done
      TextureCache.cs         -> done
      ChaseCamera.cs          -> done
      FlyCamera.cs            -> done
    Streaming/
      StreamingController.cs  -> done
      GpuWorldState.cs        -> done
    Input/
      PlayerMovementController.cs  -> active movement driver
    Plugins/
      AppPluginHost.cs        -> done
```

---

## Movement And Collision Architecture

Phase L.2 is the current organizing program for physics, collision,
boundaries, buildings, sliding, cell ownership, movement packets, and server
authority. Detailed plan: `docs/plans/2026-04-29-movement-collision-conformance.md`.

The active player movement spine is:

```text
InputDispatcher / PlayerMovementController
  -> MotionInterpreter + local body prediction
  -> PhysicsEngine.ResolveWithTransition
  -> TransitionTypes + BSPQuery + ShadowObjectRegistry
  -> ResolveResult contact/cell state
  -> MoveToState / AutonomousPosition outbound messages
  -> WorldSession server echo or correction handling
```

What exists and is active:

- `PhysicsEngine.ResolveWithTransition` is the path used for local player
  collision resolution and the shared continuous object sweep.
- `ProjectilePhysicsStepper` is the pure Core driver for retail projectile
  clock quanta, final-state acceleration, velocity/angular integration,
  AlignPath, Setup-sphere transition sweeps, and collision response. It owns no
  live entity, network, rendering, or App state; the App controller supplies
  those boundaries.
- `ProjectileController` is that App boundary. It installs one body on the
  canonical `LiveEntityRecord`, advances it on the update/render thread,
  commits through `WorldEntity.SetPosition`, publishes the effect root,
  synchronizes the existing shadow, and calls `RebucketLiveEntity` only when
  the full cell changes. Pending/leave-world residence suspends the shadow's
  cell rows while retaining its registration for exact re-entry. Timestamp-
  gated State/Vector/Position/Movement packets correct or stop that same body;
  every production MovementManager delegates full-cell reads/writes to the
  incarnation-scoped live record, and projectile acquisition adopts its body
  without replaying vectors already installed when that body was created,
  regardless of component creation order. Accepted SetState flags reach that
  canonical body before optional projectile acquisition, so absent/unsupported
  DAT shape data cannot leave collision state stale; a non-finite local receipt
  clock uses the controller's last finite game-clock value and cannot consume
  first-time Missile classification. Shared-body acquisition validates the
  adopted body's current frame/vectors, not obsolete CreateObject inputs.
  Initial and late Setup resolution share GameWindow's `_datLock`, preserving
  the single-reader `DatCollection` invariant while streaming is active.
  Generic remote translation is suppressed while projectile integration
  owns the frame;
  delete, generation replacement, pickup/parent leave-world, and session reset
  use `LiveEntityRuntime`'s normal lifecycle and never create a second GUID map.
- `RemoteTeleportController` owns the placement half of a fresh remote
  teleport after `RemoteTeleportHook` has torn down movement/target state. It
  collision-seats loaded destinations through `RemoteTeleportPlacement`; an
  unloaded destination retains one generation- and PositionSequence-scoped
  pending placement and resolves the latest accepted frame when that same
  projection becomes visible. It neither owns GUID identity nor reconstructs
  an entity. A placement failure after hydration restores the captured source
  frame/cell/contact rather than leaving a visible collisionless projection;
  source-resident shadows restore immediately, while an unloaded source
  delegates one incarnation-scoped restore to
  `LiveEntityPresentationController`, shared with Hidden/UnHide. A newer
  placement transfers that marker into an explicit active-placement generation
  before rebucketing even while Hidden. That generation suppresses every
  intervening Hidden/UnHide and projection restore until the controller reaches
  a stable result, then it either restores after collision seating, re-defers
  its rollback source, or hands a Hidden result back for UnHide. The typed
  `ILiveEntityRemotePlacementRuntime` seam permits a same-incarnation wrapper
  rebind only around the canonical body; pending placement adopts that wrapper
  before hydration and cannot silently lose ownership. Clearing a motion or
  projectile component retains the incarnation's body/contract identity until
  logical teardown. The production wrapper exposes an immutable body, while
  hydration defensively validates arbitrary implementations against the record
  and rolls the retained body back on mismatch. Runtime binding snapshots the
  interface Body getter once for validation, assignment, and state mutation.
  `GpuWorldState`
  rebuckets atomically and commits spatial visibility before draining its
  transition FIFO; `LiveEntityRuntime` rejects delayed duplicate edges. A
  rollback/rebucket inside a visibility observer therefore cannot expose a
  remove/add pulse, leave stale final visibility, or reorder the final
  presentation edge.
- `BSPQuery` contains the partial retail-style BSP collision dispatcher used by
  the transition path.
- `TransitionTypes` carries `SpherePath`, `CollisionInfo`, `ObjectInfo`,
  transition validation, step-up/down, contact-plane handling, and partial
  slide behavior.
- `PhysicsDataCache` loads GfxObj, Setup, and CellStruct physics data from DATs.
- `ShadowObjectRegistry` gives movement a broadphase over nearby objects and
  buildings.
- `TerrainSurface` uses triangle-aware terrain contact; older "bilinear terrain
  Z" descriptions are historical B.3 language, not current architecture.

What remains incomplete:

- `CELLARRAY`, `CObjCell::find_cell_list`, adjacent-cell checks, and low outdoor
  cell id updates across 24m seams.
- `cell_bsp` / `CellBSP` as the authoritative runtime owner for indoor and
  building collision.
- Building portal transit and normal walking through building entry/exit
  boundaries.
- Full retail `edge_slide`, `cliff_slide`, `precipice_slide`, and `NegPolyHit`
  dispatch behavior.
- Exact `CSphere` / `CCylSphere` object-shape parity, especially for live
  entities that currently collapse to a simplified cylinder fallback.
- Routine local/server correction diagnostics. ACE accepting a position is a
  compatibility signal, not proof of fine retail collision parity.

Ownership by phase:

- B.3 is shipped MVP history: first resolver foundation and tests.
- L.1 owns animation/motion parity, including root-motion coupling.
- L.2 owns the movement/collision conformance stack listed above.
- G.3 owns dungeon streaming and portal-space delivery after L.2e gives it
  trustworthy cell/building boundaries.

---

## GameEntity: The Unified Entity (target refactor)

`LiveEntityRuntime` is now the shipped bridge to this target. It owns one
`LiveEntityRecord` per accepted server-object incarnation, ServerGuid-to-local-id
translation, accepted snapshots/timestamp gates, animation and remote-motion
components, parent-event state, effect-profile defaults, and exact logical
teardown. Live `PhysicsDesc` effect fields replace Setup defaults on that same
record; rebucketing never recreates them. `GpuWorldState`
owns spatial buckets only: register/rebucket/unregister are separate operations,
and landblock reloads reuse the same `WorldEntity` without replaying renderer or
script creation. Its canonical materialized view remains stable across pending
landblocks, while a separate visible-only view feeds radar, picking, status, and
targeting. Raw server PhysicsState and the final state produced by retail's
ordered Lighting/NoDraw/Hidden side effects are stored separately.
`LiveEntityPresentationController` drains those accepted transitions only after
the renderer/effect owner is ready: Hidden suppresses the retained root's mesh,
collision, interaction, radar, and target eligibility while preserving the
logical record, scripts, particles, lights, full cell, and local identity.
Direct attached children receive retail's NoDraw mutation, and typed
Hidden/UnHide effects resolve through the live PhysicsScriptTable.
Pickup/parent leave-world clears cell membership and pauses root
movement/animation without destroying retained owners. `GameWindow` retains
storage-free typed views while its large feature loops are extracted.

DAT decoding for runtime VFX crosses one narrow `AcDream.Content.Vfx` seam.
`RetailAnimationLoader` and `RetailPhysicsScriptLoader` still read through the
single shared `DatCollection`, delegate ordinary animation-hook schemas to
Chorizite.DatReaderWriter, and replace only its incomplete
`CreateBlockingParticleHook` model with retail's inherited CreateParticle
payload. Core consumes the loaders through delegates/interfaces and therefore
does not depend on Content or a database implementation.

Runtime effect delivery is owned by App-layer `EntityEffectController`. It
retains pre-materialization F754/F755 packets in one mixed FIFO per server GUID,
resolves the canonical local ID through `LiveEntityRuntime` only after
renderer/resources/profile are ready, and resolves typed/default/part-default
hooks through the live owner's current `EntityEffectProfile`. It does not own a
second GUID map. The same profile publishes Setup/static or network/live
SoundTable ownership at readiness and on every same-generation PhysicsDesc
replacement, including present-zero clearing. Core `PhysicsScriptRunner` mirrors retail's one
serial FIFO per owner: duplicate plays append, owners progress independently,
`CallPES` uses an injected uniform delay, and every hook traverses the shared
`AnimationHookRouter`. Existing queues on cell-less or Frozen live roots do
not advance; a new play for an already-created cell-less object is dropped as in
retail. Attached children advance through their eligible parent. Every effect
resource uses the canonical, globally unique `WorldEntity.Id`; static
allocators fail before their namespace can wrap. `EntityEffectPoseRegistry`
publishes the final root and indexed rigid animated-part transforms after animation
and equipped-child composition. Animation hooks are captured during sequence
advance and drained only after those poses are current; PhysicsScripts then run,
attached emitters and object lights refresh, and particle simulation advances.
World-released particles retain their birth positions and parent-local particles
follow their current owner while in-world. Pending spatial projections skip
particle updates and drawing exactly like retail's cell-less object gate without
ending emitter state or identity; absolute creation timestamps remain unchanged,
so elapsed particles/durations expire on re-entry without a backlog burst. Their
anchors may still accept authoritative pose correction before that update.
Missing emitter DAT records fail diagnostically
without a synthesized effect. `LiveEntityLightController` keeps live light
projection/re-entry outside `GameWindow`; `LightingHookSink` remains the Core
hook and per-frame pose consumer. It also owns retail's Lighting-bit/
`SetLightHook` latch so spatial withdrawal preserves logical state while a
true state transition creates or destroys the Setup lights. Stable indexed
poses exclude Setup visual scale and remain separate from drawable `MeshRefs`.
Light registration follows final runtime visibility edges; equipped-child
updates are parent-before-child with retained per-child buffers and cascade
withdrawal when an ancestor pose disappears. A later pose publication drains
the waiting attachment graph transitively, so A→B→C recovers B before C in the
same parent-first pass. Recovery is edge-triggered by object/appearance/pose
publication; permanent missing DAT or holding parts are never polled per frame.

The remaining aggregation is primarily `_playerController`'s player-specific
movement plus the separate `WorldEntity`/animation/physics component types.
Those should become ONE class:

```csharp
public sealed class GameEntity
{
    // Identity
    public uint ServerGuid { get; }
    public uint SetupId { get; }
    public string? Name { get; }

    // Spatial (ported from CPhysicsObj)
    public PhysicsBody Physics { get; }      // position, velocity, gravity
    public CellTracker Cell { get; }         // which cell we're in
    
    // Appearance (ported from CPartArray)
    public AnimationSequencer Animation { get; }  // frame playback
    public AppearanceState Appearance { get; }     // ObjDesc overrides
    
    // Motion (ported from CMotionInterp)
    public MotionInterpreter Motion { get; }  // walk/run/turn state
    
    // Render output (consumed by StaticMeshRenderer)
    public IReadOnlyList<MeshRef> MeshRefs { get; }
    
    // Per-frame update (matches retail update_object)
    public void Update(float dt)
    {
        Motion.ApplyCurrentMovement();     // set velocity from motion state
        Physics.UpdateObject(dt);          // integrate position
        PhysicsEngine.ResolveWithTransition(); // current L.2 collision spine
        Cell.UpdateCell(Physics.Position); // target: retail cell ownership
        Animation.Advance(dt);            // advance animation frames
        RebuildMeshRefs();                // compute per-part transforms
    }
}
```

Target state: every entity in the world — player, NPC, monster, lifestone,
door, chest — becomes a `GameEntity`. The renderer iterates them and draws.
The plugin API exposes them as `WorldEntitySnapshot`. GameWindow becomes thin.

Lifecycle invariant in both the current split model and the target `GameEntity`:
an `ObjDescEvent` changes appearance in place. It may replace resolved meshes,
palette ranges, part overrides, and visual bounds, but it must preserve entity
identity plus animation, motion, physics, collision, selection, and
dead-reckoning owners. Only a real delete/despawn tears those owners down. This
matches retail's `CPhysicsObj::DoObjDescChangesFromDefault` behavior.

---

## Per-Frame Update Order (current runtime)

```
1. Network tick
   └── Drain inbound queue → process CreateObject, UpdateMotion,
       UpdatePosition, PlayerTeleport → create/update GameEntities

2. Streaming tick
   └── Compute observer position → load/unload landblocks →
       create terrain + scenery GameEntities

3. Input tick (player mode only)
   └── InputDispatcher scopes → PlayerMovementController →
       MotionInterpreter/body prediction → ResolveWithTransition →
       send MoveToState/AutonomousPosition to server

4. Entity / animation tick
   └── Current code still has scattered world/entity state. L.1 owns
       animation parity; L.2 owns movement/collision conformance.

5. Render tick
   └── Read current entity mesh refs, draw
       TerrainRenderer.Draw, StaticMeshRenderer.Draw
       (frustum cull, translucency pass, etc.)

6. Plugin tick
   └── Fire IEvents, drain IActions queue

6a. UI tick
    IPanelHost.Draw → iterate registered IPanel instances, build
    ViewModels from IGameState, dispatch user Commands via ICommandBus.
    Backend-agnostic — ImGui or custom retail-look draws here depending
    on which is compiled in. See docs/plans/2026-04-24-ui-framework.md.
```

---

## Render Pipeline (SSOT — current state + unified-PView target)

> **The per-frame render step above is STALE** (it names deleted classes
> `TerrainRenderer` / `StaticMeshRenderer`). The modern path (Phase N.5, mandatory) is
> `WbDrawDispatcher` (entities) + `EnvCellRenderer` (indoor cell shells) +
> `TerrainModernRenderer` (terrain), fed by the portal-visibility stack. This section is
> the authoritative description of how indoor/outdoor rendering is *supposed* to work and
> where the code currently diverges. Canonical reset handoff:
> `docs/research/2026-05-31-render-architecture-reset-handoff.md`.

**The principle (retail PView).** acdream must render the world the way retail does —
through **one** portal-visibility traversal whose output **gates every geometry type
uniformly**. From the player's cell, walk the portal graph; each visible cell carries a
screen-space clip region (its portal opening, recursively intersected); the **outside**
(terrain + outdoor scenery) is reached only through **exit portals** and is clipped to
those openings. Interior cell shells, interior statics, and the outside are **all**
clipped to their PView region. This is why retail is **seamless by construction**. Decomp
anchors: `PView::ConstructView` (`:433750`), `InitCell` (`:432896`), `DrawCells`
(`:432715`), `CEnvCell::find_visible_child_cell` (`:311397`), `SmartBox::update_viewer`
(`:92761`). Reference port acdream owns but never invokes: WB `RenderInsideOut` /
`VisibilityManager`.

**The one rule:** *compute visibility once; enforce it once, for all geometry.* Indoors,
you see the outside **only** through portal openings (clipped); an empty outside-view
(windowless interior) draws **no** outdoor geometry. Outdoors, the gate is "everything."

**Current divergence (the patchwork — what the reset must fix).** acdream computes the
visibility correctly (`CellVisibility.ComputeVisibility` → `PortalVisibilityBuilder.Build`,
a `ConstructView` port → `ClipFrameAssembler`) but then **enforces it three different,
inconsistent ways**:
1. `TerrainModernRenderer` — gated by `TerrainClipMode {Skip|Scissor|Planes}` (the Scissor
   fallback over-includes).
2. `EnvCellRenderer` — gated by the per-cell clip slot (≈correct; the shells DO render —
   proven by the `[shell]` probe, `ACDREAM_PROBE_SHELL`).
3. `WbDrawDispatcher` — gated by `ParentCellId ∈ visibleCellIds`, **but outdoor stabs
   (`ParentCellId==null`) bypass the gate** → outdoor scenery/terrain shows from inside
   (issue #78).

Three gates that must agree but don't → structural seams (transparent walls,
terrain-through-floor, grey enclosure). **The reset consolidates them into the single
PView gate** (outside content clipped to the `OutsideView` region; no `ParentCellId==null`
bypass; no Scissor over-include). This is a **consolidation of existing machinery**
(`PortalVisibilityBuilder` + `ClipFrame`), not a rewrite. Do NOT add a fourth special-case
gate to mask a seam — that anti-pattern produced the patchwork.

### Streaming publication ownership

The streaming worker may read dats and build CPU payloads, but it must not mutate
live render-frame registries. A near-tier job produces one `LandblockBuild` whose
optional `EnvCellLandblockBuild` owns the complete portal-cell and drawable-shell
sets for that landblock. The exact build object crosses the `LandblockStreamer`
completion channel. On the render thread, `StreamingController` applies that one
completion to `CellVisibility`, cell physics state, `EnvCellRenderer`, and finally
`GpuWorldState` during the same update-frame drain.

This is the publication boundary: per-job builders are private and single-use;
completed payloads are immutable snapshots; live landblock stores are replaced as
complete units. Process-wide pending bags or renderer-owned pending lists are not
valid streaming seams because a duplicate load or a second landblock can drain or
replace state produced by another job. CPU mesh extraction may still be scheduled
onto `ObjectMeshManager`'s thread-safe work queue, but the worker never publishes
partially hydrated cell membership or shell placement to the renderer.

### Teleport cell identity at the streaming boundary

The network and physics layers carry retail's complete `Position`: an
authoritative `objcell_id` plus a frame. Any streaming decision that asks
whether a teleport crossed a landblock compares the source and destination cell
IDs. It must never reconstruct either landblock by flooring render/world XYZ.
Dungeon EnvCells have arbitrary frame origins, including valid negative local
coordinates, so XYZ-to-grid inference can evict the landblock the player is
still standing in.

`TeleportLandblockTransition` owns this App-layer classification. When the
source cell is unavailable before first placement, it uses the typed current
streaming-center landblock as the fallback identity. The existing async
recenter/hydration path runs only for a real cell-ID landblock change; a
same-landblock teleport keeps the already-published render and physics unit.
This is the asynchronous adapter for retail's direct full-`Position` placement
(`SmartBox::TeleportPlayer @ 0x00453910`).

## Roadmap Model

The old R1-R8 architecture sequence was a useful early refactor sketch, but it
is no longer the execution plan. The strategic source of truth is now
`docs/plans/2026-04-11-roadmap.md`, with per-phase details in `docs/plans/`
and `docs/superpowers/specs/`.

Current movement/collision ownership:

- **B.3** is shipped MVP history: first collision resolver foundation.
- **L.1** owns animation/motion parity, including root-motion coupling.
- **L.2** owns movement and collision conformance:
  `docs/plans/2026-04-29-movement-collision-conformance.md`.
- **G.3** owns dungeon streaming and portal-space delivery after L.2e lands
  trustworthy `cell_bsp`, `CELLARRAY`, adjacent-cell checks, and building
  entry/exit boundaries.

The GameEntity / thin GameWindow refactor remains a valid target architecture,
but it is not a prerequisite for L.2. Do not resurrect old R1-R8 phase numbers
for new work; add or update roadmap phases instead.

---

## Development Workflow (mandatory for ALL work)

```
For every AC-specific behavior:

0. GREP NAMED   → Search docs/research/named-retail/ by class::method
1. FALLBACK     → Use older docs/research/decompiled/ chunks only if needed
2. CROSS-CHECK  → Verify against ACE + ACME + holtburger where relevant
3. PSEUDOCODE   → Translate to readable pseudocode
4. PORT         → Faithful C# translation
5. TEST         → Conformance test against retail/decomp golden values
6. INTEGRATE    → Surgical wiring into the existing system
7. VERIFY       → Visual + functional test
```

For acdream-specific code (renderer, plugin API, streaming):
- Design for clean interfaces
- Test independently
- No AC-specific magic — those live in the ported layer

---

## Reference Hierarchy

| Domain | Primary Oracle | Secondary |
|--------|---------------|-----------|
| Physics/collision | `docs/research/named-retail/` | ACE Physics/ + older decompiled chunks |
| Animation | `docs/research/named-retail/` + ACE Animation/ | — |
| Terrain | ACME ClientReference.cs | named retail / older decompiled chunks |
| Rendering | WorldBuilder (Silk.NET) | ACViewer |
| Protocol | holtburger | AC2D |
| Server behavior | ACE | — |

---

## Success Criteria

The client is "done" when:
1. You can log in to an ACE server
2. Walk around the entire world (streaming loads new areas)
3. Enter and exit buildings through doorways
4. See all NPCs, monsters, and players animated correctly
5. Open doors, talk to NPCs, pick up items
6. Send and receive chat
7. A Lua macro can automate gameplay
8. Side-by-side with the retail client, the world looks the same