# Research task — Retail AC: cell transitions, underground/dungeons, and seamless inside/outside rendering

> **Shared prompt for a multi-model study (2026-06-02).** The same prompt is run on
> several models (Opus 4.6/4.7/4.8, Sonnet 4.6, and an external model) so we can compare
> independent reads before committing to an architecture. Study the **source** (retail
> decomp + reference repos) and **cite everything** — do not guess. Depth + citations
> matter far more than brevity.

## 0. Why this study exists (context)

**acdream** is a modern C# .NET port of the retail Asheron's Call client (Sept 2013 EoR
build). The rule: *the code is modern, the behavior is retail.* Every AC-specific algorithm
is ported faithfully from the named retail decomp.

We are at an architecture decision and want ground truth before choosing. Two coupled
problems:

1. **Cell-membership flicker (physics).** The player's "current cell" ping-pongs at
   boundaries — at a near-static position the cell flips e.g. `0xA9B40170` (indoor cottage
   vestibule) ↔ `0xA9B40031` (outdoor landcell) every physics tick, and also
   `vestibule ↔ room` and inside the cellar. Root finding so far: acdream runs retail's
   collision *sweep* but then **discards the swept cell** and **re-derives the cell from the
   final static position every tick** (`PhysicsEngine.ResolveCellId`), which flips as the
   collision push-back jitters the end position ±~8 cm across the boundary.

2. **Non-seamless indoor render.** Standing inside a cottage/cellar the interior does not
   seal: the ceiling isn't capped, the doorway opening shows the blue clear-color instead of
   the real outside (no sky / no rain visible through the door), entities/particles bleed
   through walls, and at the threshold the view strobes between "indoor (incomplete)" and
   "outdoor." acdream's render maintains its **own** cell/visibility system separate from
   physics; we believe retail renders inside+outside seamlessly through a single
   portal-visibility traversal.

We have a candidate fix direction ("track the cell through the transition sweep like
retail's `validate_transition` + `change_cell`, drop the static re-derive, add the
`do_not_load_cells` prune, and make the render obey one portal-visibility traversal"), but
we want a **solid, decomp-grounded understanding of how retail ACTUALLY does all of this**
before we commit — patches/guesses in this exact area have failed ~10× historically.

## 1. Your deliverable

A comprehensive, decomp-cited markdown report. For **every** non-trivial claim, cite the
retail function **name + address** (from the decomp) or the reference **file:line** you
verified it from. Include short pseudocode where it clarifies control flow. End with a
concrete "Recommended acdream architecture" section (questions D14–16).

Write your report to the output path given to you (e.g.
`docs/research/2026-06-02-retail-cell-render-study-<model>.md`).

## 2. Sources to study

**Primary oracle — the retail decomp (study this first and most):**
- `docs/research/named-retail/acclient_2013_pseudo_c.txt` — 1.4 M lines of named pseudo-C.
  Grep by `Class::method` (e.g. `CTransition::validate_transition`).
- `docs/research/named-retail/acclient.h` — verbatim retail struct definitions.
- `docs/research/named-retail/symbols.json` — name ↔ address index (grep by name or addr).

**Reference repos (cross-check at least two per topic; the intersection is usually truth):**
- `references/ACE/` — server-side C# physics port. `Source/ACE.Server/Physics/` has
  `Common/` (ObjCell, EnvCell, LandCell, Position), `Animation/` and the transition/
  sphere-path/cell logic. Authoritative C# reading of `find_cell_list`, `change_cell`,
  `Transition`, `SpherePath`.
- `references/ACViewer/` — MonoGame client that renders world + dungeons. `Physics/Common/`
  (EnvCell, ObjCell, CellArray) and `Render/` (how cells/portals are drawn).
- `references/WorldBuilder/` — the render base acdream extracted from. EnvCell/portal/
  visibility/scenery managers; how it draws interiors + the (flat-stencil) inside/outside
  split it uses.
- `references/Chorizite.ACProtocol/`, `references/AC2D/`, `references/holtburger/` — use as
  relevant (struct field order, simpler client confirmations).

**acdream's current code (so your synthesis is actionable, not abstract):**
- `src/AcDream.Core/Physics/PhysicsEngine.cs` — `ResolveCellId` (~:272), `ResolveWithTransition` (~:651, see the two `ResolveCellId(sp.GlobalSphere[0].Origin,…)` calls at ~:909/:928 that discard the swept cell).
- `src/AcDream.Core/Physics/CellTransit.cs` — `FindCellList`/`FindCellSet`/`BuildCellSetAndPickContaining`, `FindTransitCellsSphere`, `AddAllOutsideCells`, `CheckBuildingTransit` (note: NO `do_not_load_cells` prune today).
- `src/AcDream.Core/Physics/TransitionTypes.cs` — `SpherePath` (`CheckCellId`/`CheckPos`, only set at `InitPath`/reset — NOT advanced through the sweep), `Transition` (`FindEnvCollisions`, `CheckOtherCells`).
- `src/AcDream.Core/World/Cells/` — the W1 unified cell graph (`ObjCell`/`EnvCell`/`LandCell`/`CellGraph`/`CellPortal`).
- `src/AcDream.App/Rendering/CellVisibility.cs` + `PortalVisibilityBuilder.cs` + `GameWindow.cs` (terrain/shell/entity draw gates ~:7150–7420).

## 3. Decomp anchors (verified starting points — confirm and expand; find more yourself)

Physics / cell tracking:
- `CPhysicsObj::change_cell` @ `0x00513390` (pseudo_c ~:281192) — the leave/enter setter.
- `CPhysicsObj::SetPositionInternal` @ `0x00515330` (~:283399) — reads `arg2->sphere_path.curr_cell`, calls `change_cell` only when it differs.
- `CTransition::validate_transition` @ `0x0050aa70` (~:272547) — advances `sphere_path.curr_cell = check_cell` on an accepted move (~:272608-272619); resets to `curr_cell` on a block/slide (~:272593).
- `CTransition::check_collisions` @ `0x0050aa00` (~:272530); `CTransition::check_other_cells` @ `0x0050ae50` (~:272717) — calls `find_cell_list`.
- `CTransition::transitional_insert` @ `0x0050b6f0` (~:273137) — the sweep stepper.
- `CObjCell::find_cell_list` @ `0x0052b4e0` (~:308742) — builds the cell array, picks the containing cell (`*arg5`), applies the `do_not_load_cells` prune (~:308829-308867).
- `CObjCell::GetVisible` (pseudo_c ~:308209) magnitude dispatch; `CEnvCell::GetVisible`, `CLandCell::GetVisible`, `CLandCell::add_all_outside_cells`, `CObjCell::point_in_cell` (vtable +0x84), `CEnvCell::find_transit_cells`.

Cell structs (acclient.h): `CObjCell` (:30915), `CEnvCell` (:32072), `CLandCell` (:31886),
`CSortCell` (:31880), `CCellPortal` (:32300), `CBldPortal` (:32094), `CellStruct` (:32275),
plus `SPHEREPATH`, `CELLARRAY`, `Position`.

Rendering / visibility (verify addresses; these are from prior notes):
- `ConstructView` (~:433750 / :433827), `InitCell` (~:432896),
  `CObjCell::find_visible_child_cell` (~:311397). Find the full PVS/PView traversal,
  the EnvCell draw path, how exit portals / `seen_outside` feed render, terrain/sky gating.

## 4. Questions to answer (be comprehensive + cited)

### A. Cell membership & transitions (physics)
1. How does retail represent and store "the cell I'm in" (`curr_cell`)? When/where is it updated? Trace the full chain: per-step sweep → `find_cell_list` → `validate_transition` advance → `SetPositionInternal`/`change_cell`.
2. Exactly how does `find_cell_list` build the candidate cell array, and how does it pick the single containing cell (`*arg5`)? What is the `do_not_load_cells` prune — when is it set, what does it remove, and what stability does it buy?
3. **Precisely how does retail avoid cell flicker** at a doorway / indoor↔outdoor / room↔room? Is it directed portal-crossing, swept-path containment with accept-on-move, the prune, `point_in_cell` semantics, or a combination? What guarantees a blocked/standing-still step does NOT change the cell?
4. How does a player transition indoor→outdoor (exit) and outdoor→indoor (enter)? Between interior cells? What do `CCellPortal` vs `CBldPortal` do, and how does the exit portal / outdoor landcell get added and chosen?
5. Is the cell ARRAY (for collision) the same mechanism as `curr_cell` (membership), or two? How do they relate within one transition?

### B. Underground / dungeons
6. How are dungeons represented in the dats and at runtime — EnvCell graph, portals, the absence of terrain? How does this differ from building interiors (cottage/inn) which sit ON a landblock with terrain?
7. How does the player move through a dungeon: cell tracking, dungeon cell loading/streaming, and how the engine knows there is no sky/terrain to draw?
8. Is there an explicit "underground" flag/state (e.g. on `Position`/landblock/cell), or is "underground" simply "current cell is an EnvCell with no outdoor reachability"? Cite the flag/field if it exists.

### C. Rendering inside and outside (the seamless seal)
9. Trace retail's render visibility: how does it build the visible set in ONE pass (`ConstructView`/`InitCell`/`find_visible_child_cell`/PVS/PView)? What does it output (visible cell list, per-portal clip regions/frustum)?
10. How does retail draw the OUTSIDE seen through a doorway/window from inside (sky, rain, terrain, exterior buildings) so there is **no blue clear-color hole**? How are exit portals / `seen_outside` handled in the render traversal?
11. How does retail seal interiors — cap ceilings, prevent the outdoor world from bleeding in, and clip entities/particles to the visible cells?
12. How does retail decide to draw terrain + sky vs not, as a function of the current cell (indoor / outdoor / underground)?
13. **Is the render cell/visibility the SAME `curr_cell`/cell-graph as physics, or separate?** Trace whether render reads the physics `curr_cell` and traverses the shared cell graph, or maintains its own. (Central to acdream's decision.)

### D. Synthesis for acdream (be concrete)
14. Given acdream re-derives membership statically per tick (instead of tracking it through the sweep) and renders with a separate cell system, what is the **retail-faithful target architecture** we should port?
15. Specifically: should membership be advanced inside the transition sweep (port `validate_transition`'s `curr_cell` advance + the `do_not_load_cells` prune + drop the static `ResolveCellId`, reading `sphere_path.curr_cell` like `SetPositionInternal`)? Should the render obey the physics `curr_cell` + a single portal-visibility traversal? Justify from the decomp.
16. List the **must-port functions** (with decomp addresses), the integration order, the main risks (esp. anything touching the collision sweep where acdream has a history of bugs), and what conformance tests would prove faithfulness.

## 5. Method reminders
- Grep the named decomp by `Class::method` FIRST; confirm addresses in `symbols.json`.
- The decomp is ground truth; ACE/ACViewer/WorldBuilder are interpretation aids — when they
  disagree, the decomp wins, but note the disagreement.
- Distinguish what you VERIFIED in source from what you INFER. Flag inferences.
- Cite: `function_name @ 0xADDR (pseudo_c:LINE)` or `repo/path/File.cs:LINE`.