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
      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
    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:

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.
• 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)

Currently, entity state is scattered across:

• WorldEntity (position, rotation, mesh refs)
• AnimatedEntity (animation frame, setup, sequencer)
• _entitiesByServerGuid dict (server GUID lookup)
• GpuWorldState._loaded[lb].Entities (per-landblock lists)
• _playerController (player-specific movement)

This should become ONE class:

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.

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