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                           │
│  TerrainModernRenderer, WbDrawDispatcher, EnvCellRenderer  │
│  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.

External-container state follows the same ownership rule. Core ExternalContainerState owns the expected/current ClientUISystem::groundObject identity, Core.Net applies authoritative ViewContents and CloseGroundContainer events, and App ExternalContainerLifecycleController owns the replacement-only NoLongerViewingContents side effect. The retained ExternalContainerController is a projection over that state; mounting or disabling the gameplay UI cannot change the session lifetime.

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.

Magic follows the same boundary. Core Spellbook is the one learned/favorite/ desired/enchantment state projection; Core.Net owns exact manifest and live message parsing; App SpellCastingController owns validated cast intent; and the retained spell bar, spell/component book, and effects controllers only project that state and invoke supplied actions. ACE remains authoritative after the targeted/untargeted request for turning, animation, mana/components, fizzle, impact, damage, and completion. The shared LayoutDesc importer resolves inherited controller trees with retail LayoutDesc::InqFullDesc/ElementDesc::Incorporate child identity semantics; panel controllers never reconstruct missing inherited widgets by hand. RetailPanelUiController is the single retained owner of retail gmPanelUI::RecvNotice_SetPanelVisibility semantics: one active main-panel child, optional DAT-property-driven deferred restoration, and visibility reconciliation for persistence. Toolbar buttons and the authored Helpful/ Harmful effects indicators both send panel IDs into this owner; neither owns a parallel window-lifecycle map.

---

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
      LiveEntityOrdinaryPhysicsUpdater.cs -> manager-less body Transition commits
      RemoteInboundMotionDispatcher.cs -> animation-optional retail UM funnel
      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 identity/state/body/projectile/spatial ownership
      RetailInboundEventDispatcher.cs -> update-thread packet/frame FIFO barrier
      LiveEntityPresentationController.cs -> Hidden/NoDraw/effect/collision presentation
      LiveEntityTeardown.cs   -> failure-isolated multi-owner lifecycle drain
      RetailLiveFrameCoordinator.cs -> object/physics-before-network frame barrier
    Rendering/
      GameWindow.cs           -> still owns too much runtime wiring
      LiveEntityAnimationScheduler.cs -> canonical ordinary live-object workset
      RetailStaticAnimatingObjectScheduler.cs -> retail static-animation workset
      StaticLiveRootCommitter.cs -> static root pose/collision commit boundary
      TerrainModernRenderer.cs -> mandatory bindless+MDI terrain path
      Wb/WbDrawDispatcher.cs  -> ordinary live/static entity draw dispatch
      Wb/EnvCellRenderer.cs   -> indoor cell-shell draw path
      ParticleRenderer.cs     -> DAT particle billboard/full-mesh dispatch
      RetailAlphaQueue.cs     -> shared delayed world alpha ordering/flush owner
      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 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.
• LiveEntityAnimationScheduler is the one update-thread walk over spatial live roots. It admits each incarnation's RetailObjectQuantumClock, advances PartArray state, then selects exactly one movement owner: remote motion, the retained projectile body, or LiveEntityOrdinaryPhysicsUpdater for a manager-less canonical body. Every hook boundary revalidates record, component, and object-clock epoch before transition, manager-tail, pose, or rebucket commits. RetailStaticAnimatingObjectScheduler remains a separate workset, matching CPhysics::UseTime: Setup DefaultAnimation is installed at PartArray construction, while DAT and live PhysicsState-Static owners advance whole elapsed intervals through animate_static_object semantics. A live static owner shares the record's canonical PartArray and PhysicsBody; raw static omega commits the root, effect pose, and collision shadow together, while zero omega does not reflood collision and Hidden never restores it. The typed animation view copies the runtime's concrete spatial dictionary through reusable storage, so update and render classification allocate nothing and scale with resident owners rather than retained KnownObjects.
• RemoteInboundMotionDispatcher is the single remote MovementManager::unpack_movement owner. Animated and animation-less live objects differ only by the presence of a PartArray dispatch sink; packet head interrupt/style routing, MoveTo cases, case-0 wholesale state, sticky, and long-jump ordering cannot drift between two GameWindow branches.
• Ordinary remote/manager-less Transition commits publish the resolved body, WorldEntity root, and full cell before invoking the canonical rebucket writer. That writer is a re-entrant lifetime boundary: the caller immediately revalidates the exact record/runtime and publishes no collision shadow or manager tail if the destination became pending or the GUID was replaced. LiveEntityPresentationController owns the symmetric non-projectile collision-residency edge: loaded-to-pending suspends the retained shadow, hydration restores it immediately, and OnLiveEntityReady reconciles an object that materialized pending before its collision registration existed. Direct local-player and authoritative remote publication use the same ordering: commit root, rebucket, then prove exact-record spatial residency before touching collision. Remote shadows are pose/cell-gated, including complete sign-invariant orientation for offset/multipart Setup shapes and a forced refresh on cell-only transitions. Projectile residency remains exclusively in ProjectileController.
• RetailInboundEventDispatcher wraps every live-object session callback and each complete live-object frame phase. Synchronous App observers can enqueue another packet, but that packet cannot interleave halfway through the older packet's collision, rebucket, shadow, pose, hook, or manager tail. The live record retains independent Position, State, Vector, and Movement authority versions plus a narrow shared velocity version for the three packet families that can install velocity. This mirrors retail's single update-thread FIFO without incorrectly making an accepted State cancel an accepted Position. Its direct frame/packet path accepts state plus a cached static callback and performs zero allocation; only real nested reentrancy materializes a queued heterogeneous operation.
• Projectile prediction is a two-phase transaction around retail's process_hooks slot. BeginQuantum holds a candidate while leaving the canonical body at its begin frame; CompleteQuantum commits only if the exact record/runtime and prediction version still match. Position, Vector, and State corrections therefore win if accepted between the two halves. Teleport placement uses the same exact-record and per-channel authority checks, so a newer Position supersedes an older resolver while an independent State is preserved alongside the completed placement.
• EntityEffectPoseRegistry assigns a monotonic lifetime to every local-ID incarnation. AnimationHookFrameQueue snapshots it before semantic AnimationDone callbacks and revalidates it before every semantic completion and every routed hook. A delete/local-ID reuse during capture or during an earlier hook can never advance the displaced sequencer or send the old owner's remaining sound, particle, or light hooks to its replacement.
• 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. Observer failures are reported only after both spatial and canonical runtime cell/projection state have committed. Every projection operation also carries a per-record mutation token; if a synchronous observer replaces the GUID or reprojects that same record, the displaced outer operation cannot overwrite the newer cell or presentation indices.
• 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, the canonical PhysicsBody, animation/remote-motion/projectile 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, logical teardown removes the exact WorldEntity incarnation rather than every projection sharing its server GUID, and per-GUID/session mutation epochs prevent a callback from resurrecting an outer CreateObject after delete/reset. Per-GUID epoch tombstones remain until session clear, so delete-then-create cannot repeat an outer operation's epoch (the ABA problem). Resource registration is an atomic boundary, superseded cleanup failures surface at the runtime boundary, and visibility observers are failure-isolated without interrupting canonical commits. 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 ordinary F754/F755/default play for an already-created cell-less object is dropped as in retail. Hidden/UnHide is the retail exception: CPhysicsObj::set_hidden resolves the typed script and calls play_script_internal, queuing it until owner eligibility returns. 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:

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

Runtime resource ownership and bounded residency

Logical lifetime, spatial residency, and physical GPU lifetime are separate contracts. A live entity or landblock owns stable logical references; moving it between buckets does not reacquire resources. Appearance replacement acquires the complete new mesh/texture set before publication, then releases the old set. Despawn and landblock demotion withdraw every public render reference before their physical resources become reclaimable. All of these transactions are retryable and generation-scoped, so a failed release cannot silently strand a half-retired owner or affect a reused server GUID.

Runtime content residency is deliberately bounded rather than proportional to every region visited:

• RuntimeDatCollectionFactory keeps DAT indexes on demand but uses FileCachingStrategy.Never; DatCollection remains the sole raw reader.
• Each typed DAT facade has a 256-entry / 64 MiB estimated LRU. Unknown object graphs are conservatively charged at least 128 KiB. Canonical decoded texture pixels use a separate 128-entry / 64 MiB cache.
• Standalone bindless textures retain at most 256 unowned entries / 32 MiB and retire at most one per frame. Owner-scoped composite textures use a 64 MiB unowned budget and 128 MiB physical budget, admitting at most 16 uploads or 8 MiB per frame.
• ObjectMeshManager may retain at most 32 empty texture atlases / 64 MiB. GlobalMeshBuffer owns reclaimable vertex/index ranges capped at 384 MiB and 128 MiB respectively, with an 896 MiB physical ceiling that includes an in-progress migration and its retired predecessor.

OpenGL deletion and range/slot reuse are not synonymous with logical release. GpuFrameFlightController fences three frames in flight. Mesh-buffer stores, texture handles, atlas layers, terrain slots, and landblock render records enter retirement only after they are no longer publishable, and their physical ids are recycled only after the corresponding fence signals. Shutdown follows the same dependency order and remains retryable: UI/controllers and render registrations withdraw first, then owner leases and caches, then GL backing stores. This keeps drivers from reading freed memory without adding a portal-specific purge or a visual-distance reduction.

---

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
       TerrainModernRenderer + WbDrawDispatcher + EnvCellRenderer
       (frustum cull, translucency pass, portal visibility, etc.)
       World Wb translucents + Scene particles submit to RetailAlphaQueue;
       RetailPViewRenderer flushes the landscape scope before the conditional
       depth clear and GameWindow flushes the final scope before private
       viewports/UI. Sky/private viewport particles remain immediate.
       Projectiles remain ordinary live-entity draws; there is no global or
       projectile-specific render pass.

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

Portal-space presentation boundary

TeleportAnimSequencer is the pure Core owner of retail's seven-state teleport lifecycle, exact 1/2/5-second thresholds, frame-aligned exit window, and 100-sample UIGlobals::GetAnimLevel view-plane curve. App-layer PortalTunnelPresentation owns the synthetic DAT Setup (0x02000306), its 40-frame/s animation (0x030005AC), CSequence, SmartBox-FOV camera, distant light, mesh references, and animation-hook delivery. It renders through the existing modern WbDrawDispatcher as a replacement 3-D viewport, after world rendering and before retained UI. The shared dispatcher is reset to no world-cell clips and no world point lights for this pass. Chat, gameplay windows, toolbar, cursor, and input continue normally above it. The synthetic object never enters LiveEntityRuntime, collision, picking, radar, or server GUID state.

TeleportViewPlaneController is the App-layer projection adapter for retail SmartBox::SetOverrideFovDistance / Render::set_vdst. It captures the active game projection at teleport begin, then applies the same table-eased view-plane distance and near plane to the portal and world viewports through the four retail FADE states. Those states do not drive a black alpha layer: the portal and world 3-D viewports switch directly at the transition view distance, while retained UI remains independently composed. Portal camera direction is a roll around its local AC +Y forward axis, so the animated scene remains a passage rather than yawing away from it. Destination placement also calls the retail chase camera's set_viewer(player, reset_sought=1) equivalent; the normal damped/swept camera path then re-extends from the arriving player.

One reset seam ends a logical transit on successful completion, replacement by a newer teleport sequence, or session teardown. It clears the destination, streaming priority, sequencer edges, projection override, and portal scene together, preventing transition state from crossing destination or session lifetimes. TeleportTransitCoordinator correlates each fresh F751 sequence with exactly one accepted UpdatePosition. Because the Position can arrive on either side of F751, a pre-notification packet is buffered only when it advances retail's TELEPORT_TS; after notification, the first accepted matching packet is consumed even if that timestamp already advanced. Duplicate/older F751 notifications are rejected with wrap-safe ordering. Canonical physics remains independent, and streaming recentering compares destination identity with the actual current streaming center rather than the player's still-unplaced source cell. A live teleport received while acdream's developer fly/orbit camera is active re-enters the existing player-mode lifecycle first; retail has no detached camera mode, and destination placement therefore always retains the canonical local physics controller and chase-camera handoff.

The destination residency gate supplies retail's EndTeleportAnimation edge once asynchronous streaming is ready. Player placement remains authoritative and separate from presentation; arrival resets camera viewer state but does not reset the character animation sequence. RetailLiveFrameCoordinator matches SmartBox::UseTime @ 0x00455410: it advances local and remote object/ projectile runtime, composes final animated/equipped poses, drains animation hooks, then advances particles before owner scripts and inbound network dispatch. RetailLocalPlayerFrameController owns the player's exactly-once tick and sends input-originated movement/jump output on the object side of that barrier. After inbound dispatch, the retail command-interpreter phase evaluates periodic AutonomousPosition from current authoritative state, then a non-advancing spatial reconciliation updates equipped children and live effect/light anchors. Consequently a teleport Hidden transition cannot freeze the last fraction of recall and replay it after UnHide, and ForcePosition/F751 cannot combine old one-shot input with a new cell. The draw pass consumes that completed update snapshot and never advances live animation independently. See docs/research/2026-07-15-retail-portal-space-pseudocode.md.

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