acdream/docs/research/2026-06-02-retail-cell-render-study-codex.md

Retail cell transitions, dungeons, and seamless inside/outside rendering

Report date: 2026-06-02
Author: Codex research pass

Executive conclusion

Retail AC does not treat cell membership as a fresh static classification every frame. It carries SPHEREPATH.curr_cell and SPHEREPATH.check_cell through the collision sweep, asks CObjCell::find_cell_list for collision candidates and a candidate containing cell, accepts that candidate only when the transition step validates, and finally commits CPhysicsObj::cell from sphere_path.curr_cell in CPhysicsObj::SetPositionInternal (CTransition::check_other_cells @ 0x0050AE50, pseudo_c:272717-272755; CTransition::validate_transition @ 0x0050AA70, pseudo_c:272547-272619; CPhysicsObj::SetPositionInternal(CTransition const*) @ 0x00515330, pseudo_c:283399-283462).

The current acdream physics path already ports much of the transition internals, but then re-runs ResolveCellId(...) after the sweep on both success and partial failure, discarding the swept cell ID (src/AcDream.Core/Physics/PhysicsEngine.cs:847, src/AcDream.Core/Physics/PhysicsEngine.cs:866). That is the retail mismatch most likely responsible for doorway and room boundary ping-pong.

Retail render likewise uses the shared cell graph, not an unrelated "camera cell" system. The render loader follows the player/current position through CellManager::ChangePosition, reads the current CObjCell, and uses seen_outside to decide whether landscape, sunlight, and outdoor ambient state remain live (CellManager::ChangePosition @ 0x004559B0, pseudo_c:94601-94682). The portal renderer builds one portal-clipped view traversal with PView::ConstructView, PView::InitCell, PView::AddViewToPortals, and PView::DrawCells; outside visible through a doorway is an outside_view in the same traversal, not a blue clear-color gap or separate post-process (PView::ConstructView(CEnvCell*, ushort) @ 0x005A57B0, pseudo_c:433750-433789; PView::DrawPortal @ 0x005A5AB0, pseudo_c:433895-433933; PView::DrawCells @ 0x005A4840, pseudo_c:432709-432820).

The recommended acdream target is therefore:

1. Make transition sweep state the sole source of membership updates.
2. Port the remaining CELLARRAY/do_not_load_cells behavior where acdream builds static/cross-cell lists.
3. Stop using render-side AABB camera-cell reclassification as the authority.
4. Replace the split indoor/outdoor render branch with a single PView-style portal traversal rooted in the authoritative current cell, carrying per-cell portal views plus one OutsideView.

Sources checked

Primary retail sources:

• docs/research/named-retail/acclient_2013_pseudo_c.txt
• docs/research/named-retail/acclient.h
• docs/research/named-retail/symbols.json

Reference cross-checks:

• ACE physics: references/ACE/Source/ACE.Server/Physics/Common/ObjCell.cs, EnvCell.cs, LandCell.cs, CellArray.cs, Transition.cs, PhysicsObj.cs
• ACViewer physics/render/dat: references/ACViewer/ACViewer/Physics/..., references/ACViewer/ACViewer/Render/R_Landblock.cs, R_EnvCell.cs, references/ACViewer/ACE/Source/ACE.DatLoader/...
• WorldBuilder render base: references/WorldBuilder/WorldBuilder.Shared/Services/PortalService.cs, references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs, references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/PortalRenderManager.cs, references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/EnvCellRenderManager.cs
• holtburger dat/world notes: references/holtburger/crates/holtburger-dat/src/file_type/env_cell.rs, references/holtburger/crates/holtburger-world/src/state/liveness.rs, references/holtburger/crates/holtburger-common/src/position.rs
• AC2D and Chorizite were searched for this topic; they did not provide a deeper portal-render model than retail/ACE/ACViewer/WorldBuilder. Chorizite is protocol-focused, not dat/render-focused.

A. Cell membership and transitions

A1. Retail stores membership as object state plus transition state

Retail has two relevant layers of cell state:

• CPhysicsObj::cell and CPhysicsObj::m_position.objcell_id, the committed object membership (CPhysicsObj::change_cell @ 0x00513390, pseudo_c:281192-281215).
• SPHEREPATH.curr_cell/curr_pos and SPHEREPATH.check_cell/check_pos, the in-flight sweep state. The retail SPHEREPATH struct contains begin_cell, curr_cell, check_cell, hits_interior_cell, and cell_array_valid (acclient.h:32625-32666).

CPhysicsObj::change_cell leaves the old cell, enters the new one when non-null, or clears m_position.objcell_id, part-array cell ids, and this->cell when null (CPhysicsObj::change_cell @ 0x00513390, pseudo_c:281192-281215).

CPhysicsObj::SetPositionInternal(CTransition const*) reads transition.sphere_path.curr_cell, not a static cell lookup. If the object is already in that cell, it updates position and child/part cell ids. If the cell differs, it calls change_cell(curr_cell) (CPhysicsObj::SetPositionInternal(CTransition const*) @ 0x00515330, pseudo_c:283399-283462; ACE mirror references/ACE/Source/ACE.Server/Physics/PhysicsObj.cs:1171-1215).

A2. The per-step sweep chain

The retail transition sweep is a state machine over check_pos/check_cell and curr_pos/curr_cell:

check_collisions:
    curr_cell = sphere_path.curr_cell
    check_pos = curr_pos
    check_cell = curr_cell
    FindObjCollisions(...)

transitional_insert:
    if check_cell is null: fail
    insert object into check_cell
    check_other_cells(check_cell)

check_other_cells:
    find_cell_list(cell_array, &newCell, sphere_path)
    test collision in every candidate cell except the already-tested cell
    if no collision:
        check_cell = newCell
        adjust_check_pos(newCell.id)

validate_transition:
    if OK and check_pos moved:
        curr_pos = check_pos
        curr_cell = check_cell
        reset check_pos/check_cell from current
    else if blocked/slide but not invalid:
        restore check_pos/check_cell to curr_pos/curr_cell
        return OK

SetPositionInternal:
    commit object cell from sphere_path.curr_cell

This pseudocode is from the decomp and ACE cross-checks: CTransition::check_collisions seeds check state from current state (CTransition::check_collisions @ 0x0050AA00, pseudo_c:272530-272542); CTransition::transitional_insert requires sphere_path.check_cell, inserts into it, then calls check_other_cells (CTransition::transitional_insert @ 0x0050B6F0, pseudo_c:273137-273185); CTransition::check_other_cells calls CObjCell::find_cell_list, tests other cells, then retargets check_cell through the containing cell (CTransition::check_other_cells @ 0x0050AE50, pseudo_c:272717-272755; ACE mirror references/ACE/Source/ACE.Server/Physics/Transition.cs:150-185); validate_transition advances curr_cell = check_cell only on an accepted move and restores check_cell = curr_cell on collision/slide recovery (CTransition::validate_transition @ 0x0050AA70, pseudo_c:272547-272619; ACE mirror references/ACE/Source/ACE.Server/Physics/Transition.cs:984-1091).

acdream's TransitionTypes largely mirrors this internally: it sets sp.CurCellId = sp.CheckCellId on accepted movement and resets check state from current state on blocked/slide recovery (src/AcDream.Core/Physics/TransitionTypes.cs:3388-3425). It also retargets CheckCellId after a successful other-cell query (src/AcDream.Core/Physics/TransitionTypes.cs:2061-2075). The break is after the sweep: PhysicsEngine.ResolveWithTransition wraps the final result in another ResolveCellId(...) call (src/AcDream.Core/Physics/PhysicsEngine.cs:847, src/AcDream.Core/Physics/PhysicsEngine.cs:866).

A3. How find_cell_list builds the cell array

Retail CELLARRAY has added_outside, do_not_load_cells, num_cells, and an array of CELLINFO (acclient.h:31574-31580). CObjCell::find_cell_list(Position const*, ...) clears num_cells and added_outside, inspects the low word of Position.objcell_id, and dispatches to EnvCell or LandCell visible-cell lookup (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308742-308756; CObjCell::GetVisible @ 0x0052AD40, pseudo_c:308209-308220).

If the origin cell is an EnvCell, retail marks sphere_path.hits_interior_cell = 1 and adds that EnvCell to the cell array (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308764-308766). If the origin cell is a land cell, it calls CLandCell::add_all_outside_cells to add the outdoor cells overlapped by the sphere(s) (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308769; CLandCell::add_all_outside_cells @ 0x00533630, pseudo_c:317499-317599).

Then, for every candidate cell in the array, retail calls that cell's find_transit_cells virtual (vtable + 0x80) to add portal/outdoor/building neighbors (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308775-308785). For EnvCells, CEnvCell::find_transit_cells iterates portals: loaded neighbor cells are tested by transforming the sphere into neighbor space and calling CCellStruct::sphere_intersects_cell; unloaded neighbor ids can be added as null cells; outside exit portals cause CLandCell::add_all_outside_cells to add outdoor land cells (CEnvCell::find_transit_cells @ 0x0052C820, pseudo_c:309968-310122; ACE mirror references/ACE/Source/ACE.Server/Physics/Common/EnvCell.cs:311-371). For land cells, CLandCell::find_transit_cells calls add_all_outside_cells and then the base sorted-cell transit logic (CLandCell::find_transit_cells @ 0x00533800, pseudo_c:317603-317608; ACE mirror references/ACE/Source/ACE.Server/Physics/Common/LandCell.cs:277-280).

If the caller asks for a single containing cell, retail iterates the resulting candidate array, transforms the first sphere center into each candidate's local frame, and calls point_in_cell (vtable + 0x84). The first containing candidate is returned; if it is an EnvCell, hits_interior_cell is set and the search stops (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308801-308819; ACE mirror references/ACE/Source/ACE.Server/Physics/Common/ObjCell.cs:365-383).

A4. do_not_load_cells prune

Retail prunes the cell array when CELLARRAY.do_not_load_cells != 0 and the origin position is an EnvCell. In that case, find_cell_list keeps the current visible cell and cells present in the current visible cell's visible-list, and removes other candidates (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308829-308867).

This flag is real retail state, not ACE invention: the struct contains do_not_load_cells (acclient.h:31574-31580), CPhysicsObj::calc_cross_cells_static sets it before building a cross-cell list (CPhysicsObj::calc_cross_cells_static @ 0x00515160, pseudo_c:283275-283344), and another position-check path sets it when a flag bit is present before CheckPositionInternal (CPhysicsObj position-check path @ 0x00515BD0 area, pseudo_c:283930-283946). ACE names the same behavior LoadCells; SetStatic() sets LoadCells = false, and SetDynamic() sets it true (references/ACE/Source/ACE.Server/Physics/Common/CellArray.cs:17-29).

The stability benefit is bounded: this prune limits speculative unloaded/remote cells for static/cross-cell calculations. It is not the primary doorway anti-flicker mechanism. The primary mechanism is still the accepted sweep state: blocked/slide cases restore check_pos/check_cell to curr_pos/curr_cell, and only accepted movement advances curr_cell (CTransition::validate_transition @ 0x0050AA70, pseudo_c:272593-272619).

acdream currently has no equivalent do_not_load_cells prune in CellTransit.BuildCellSetAndPickContaining; the indoor branch BFSes the portal graph with a hard maxIterations = 16, adds outdoors on any visited exit portal, then point-tests candidates (src/AcDream.Core/Physics/CellTransit.cs:426-537). That may over-admit candidates compared with retail when the caller intends a static/no-load cell list.

A5. How retail avoids boundary flicker

Retail avoids doorway and room-boundary flicker by combining four behaviors:

1. Candidate discovery is sphere/path aware, not just point-grid classification. find_cell_list uses sphere overlap via transit-cell queries before choosing a containing cell (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308775-308819).
2. The containing cell is assigned to check_cell during check_other_cells, before validation (CTransition::check_other_cells @ 0x0050AE50, pseudo_c:272717-272755; ACE mirror references/ACE/Source/ACE.Server/Physics/Transition.cs:179-183).
3. validate_transition commits check_cell to curr_cell only if the step is accepted and the position actually moved (CTransition::validate_transition @ 0x0050AA70, pseudo_c:272608-272619).
4. If the step is blocked, sliding, or adjusted but not invalid, validate_transition restores check state from the current state and returns OK; standing still or being pushed back does not independently choose a new cell (CTransition::validate_transition @ 0x0050AA70, pseudo_c:272593-272595; ACE mirror references/ACE/Source/ACE.Server/Physics/Transition.cs:1014-1017).

Therefore the answer to "what prevents flicker?" is a combination, but the load-bearing retail invariant is: membership changes only as part of an accepted swept transition, then SetPositionInternal commits from sphere_path.curr_cell (CPhysicsObj::SetPositionInternal(CTransition const*) @ 0x00515330, pseudo_c:283399-283462).

acdream violates that invariant by performing a final static re-derive from sp.GlobalSphere[0].Origin after the transition (src/AcDream.Core/Physics/PhysicsEngine.cs:847, src/AcDream.Core/Physics/PhysicsEngine.cs:866). The comments inside ResolveCellId already document previous ping-pong behavior caused by point/sphere static checks at indoor boundaries (src/AcDream.Core/Physics/PhysicsEngine.cs:286-315).

A6. Indoor to outdoor, outdoor to indoor, and interior to interior

Interior-to-interior movement is handled by CCellPortal records on EnvCells. The retail CEnvCell struct has num_portals and CCellPortal* portals (acclient.h:32072-32090); CCellPortal stores other_cell_id, other_cell_ptr, portal, portal_side, other_portal_id, and exact_match (acclient.h:32300-32308). ACViewer's dat loader confirms CellPortal fields: flags, polygon id, other cell id, and other portal id (references/ACViewer/ACE/Source/ACE.DatLoader/Entity/CellPortal.cs:6-21).

Indoor-to-outdoor movement uses EnvCell exit portals. ACE's readable port treats OtherCellId == ushort.MaxValue as outside; when the sphere crosses or is near the exit portal plane, it sets checkOutside = true, and LandCell.add_all_outside_cells adds outdoor cells to the candidate array (references/ACE/Source/ACE.Server/Physics/Common/EnvCell.cs:319-331, references/ACE/Source/ACE.Server/Physics/Common/EnvCell.cs:369-370). Retail decomp shows the same shape in CEnvCell::find_transit_cells, including outside expansion through CLandCell::add_all_outside_cells (CEnvCell::find_transit_cells @ 0x0052C820, pseudo_c:309968-310122).

Outdoor-to-indoor movement uses building portals (CBldPortal) from landblock/building data. Retail CBldPortal stores other_cell_id, other_portal_id, num_stabs, and stab_list (acclient.h:32094-32103). ACViewer's dat loader confirms CBldPortal.OtherCellId, OtherPortalId, and StabList (references/ACViewer/ACE/Source/ACE.DatLoader/Entity/CBldPortal.cs:7-32). ACE's EnvCell.check_building_transit transforms the sphere into the target EnvCell and adds it when the EnvCell BSP says the sphere intersects (references/ACE/Source/ACE.Server/Physics/Common/EnvCell.cs:128-144). acdream has an analogous CellTransit.CheckBuildingTransit (src/AcDream.Core/Physics/CellTransit.cs:299-341).

CCellPortal and CBldPortal therefore serve different roles. CCellPortal is an EnvCell-to-EnvCell or EnvCell-to-outside portal inside an EnvCell graph. CBldPortal is the building/landblock entry portal that connects an outdoor building instance to an interior EnvCell graph (acclient.h:32094-32103, acclient.h:32300-32308; WorldBuilder cross-check references/WorldBuilder/WorldBuilder.Shared/Services/PortalService.cs:45-135).

A7. Cell array vs membership

The collision cell array and current membership are related but not identical.

The cell array is a candidate set for collision and containing-cell choice. It can include current cell, adjacent EnvCells, exit outdoor land cells, building-interior cells, and possibly null/unloaded cell ids (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308742-308867; CEnvCell::find_transit_cells @ 0x0052C820, pseudo_c:309968-310122).

Membership is the single SPHEREPATH.curr_cell accepted by validate_transition and committed by SetPositionInternal (CTransition::validate_transition @ 0x0050AA70, pseudo_c:272608-272619; CPhysicsObj::SetPositionInternal(CTransition const*) @ 0x00515330, pseudo_c:283399-283462).

So find_cell_list supplies candidates and a proposed check_cell; validate_transition decides whether that proposal becomes curr_cell.

B. Underground and dungeons

B1. Runtime/dat representation

Dungeons and building interiors are both EnvCell graphs at runtime. ACViewer's dat loader describes EnvCells as cells whose low word starts at 0x0100, with surfaces, environment id, cell structure, position, cell portals, visible cells, static objects, and flags (references/ACViewer/ACE/Source/ACE.DatLoader/FileTypes/EnvCell.cs:7-63). Holtburger's dat parser reads the same shape: EnvCell has flags, surfaces, environment_id, cell_structure, position, portals, visible_cells, static_objects, and optional restriction object (references/holtburger/crates/holtburger-dat/src/file_type/env_cell.rs:8-84).

Building interiors differ from pure dungeons because the landblock still has outdoor terrain and building data. LandblockInfo records the number of EnvCells and building records (references/ACViewer/ACE/Source/ACE.DatLoader/FileTypes/LandblockInfo.cs:7-58). WorldBuilder's PortalService starts from LandBlockInfo building portals and BFSes EnvCells to build portal groups (references/WorldBuilder/WorldBuilder.Shared/Services/PortalService.cs:45-135).

ACE identifies a pure dungeon landblock by all terrain heights being zero, at least one EnvCell, and no buildings (references/ACE/Source/ACE.Server/Entity/Landblock.cs:1266-1277). It also has HasDungeon for landblocks that contain EnvCells without necessarily being fully terrainless (references/ACE/Source/ACE.Server/Entity/Landblock.cs:1282-1302). ACViewer mirrors this distinction in rendering: it skips outdoor building/static/scenery generation for landblock.IsDungeon, but builds EnvCells for landblock.HasDungeon or when OutdoorEnvCells is enabled (references/ACViewer/ACViewer/Render/R_Landblock.cs:35-55, references/ACViewer/ACViewer/Render/R_Landblock.cs:83-103).

B2. Movement through dungeons

Movement through a dungeon uses the same EnvCell transition machinery as any interior. Current low word >= 0x0100 dispatches through EnvCell visible/transit logic, CEnvCell::find_transit_cells walks portals, and validate_transition commits accepted curr_cell (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308749-308769; CEnvCell::find_transit_cells @ 0x0052C820, pseudo_c:309968-310122; CTransition::validate_transition @ 0x0050AA70, pseudo_c:272608-272619).

Retail does not need a separate movement flag for "dungeon" in this path. The low-word cell range and EnvCell portal graph are sufficient for cell tracking. Holtburger's common position helper reflects the same client-side convention: low word >= 0x0100 means indoors, while outdoor cells are the 64 land cells (references/holtburger/crates/holtburger-common/src/position.rs:79-89, references/holtburger/crates/holtburger-common/src/position.rs:129-143).

B3. No explicit "underground" flag found

I did not find a retail Position or CObjCell field that directly means "underground". The explicit flag that matters for render/load policy is CObjCell.seen_outside (acclient.h:30915-30929). ACViewer/ACE names the EnvCell flag bit SeenOutside = 0x1 (references/ACViewer/ACE/Source/ACE.Entity/Enum/EnvCellFlags.cs:6-10), and the EnvCell dat loader exposes SeenOutside => Flags.HasFlag(EnvCellFlags.SeenOutside) (references/ACViewer/ACE/Source/ACE.DatLoader/FileTypes/EnvCell.cs:22-34).

Inference from sources: "underground" for render purposes is best modeled as current cell is an EnvCell with no outside visibility/reachability and, for a pure dungeon landblock, no meaningful outdoor terrain to draw. This inference is supported by retail CellManager::ChangePosition, which keeps or releases landscape based on seen_outside and current/outdoor state rather than an underground flag (CellManager::ChangePosition @ 0x004559B0, pseudo_c:94649-94682), and by ACE's IsDungeon heuristic (references/ACE/Source/ACE.Server/Entity/Landblock.cs:1266-1277).

C. Rendering inside and outside

C1. Retail render is a portal-view traversal

Retail PView stores an outside_view, an outdoor portal list, a cell draw list, a todo list, and an LScape* (acclient.h:45934-45944). CEnvCell stores per-cell portal-view arrays: num_view and DArray<portal_view_type*> portal_view (acclient.h:32072-32090). portal_view_type contains portal clip data, view_count, cell_view_done, view_timestamp, and update_count (acclient.h:32346-32355).

The render traversal starts with PView::ConstructView(CEnvCell*, ushort): it clears outside_view.view_count, increments master_timestamp, clears todo/draw lists, initializes the seed EnvCell, inserts it into the todo list, then repeatedly pops cells, adds them to the draw list, clips portals, and propagates views to neighbor portals (PView::ConstructView(CEnvCell*, ushort) @ 0x005A57B0, pseudo_c:433750-433789).

PView::InitCell initializes the current EnvCell's portal_view_type, decides which portals are visible for the current view slice, calculates portal clip metadata, calls Render::set_view, and sets update_count = view_count (PView::InitCell @ 0x005A4B70, pseudo_c:432896-433045). PView::AddToCell processes only new view slices from update_count to view_count (PView::AddToCell @ 0x005A4D90, pseudo_c:433050-433085). PView::AddViewToPortals initializes or appends to neighbor cells' portal views, queues neighbors, and calls SetOtherSeen for matching portal ids (PView::AddViewToPortals @ 0x005A52D0, pseudo_c:433446-433520).

This is important for issue #102: retail does not use a fixed small "max reprocess per cell" cap. It uses per-cell update_count watermarks and a todo list until the propagated view slices converge (PView::InitCell @ 0x005A4B70, pseudo_c:433043; PView::AddToCell @ 0x005A4D90, pseudo_c:433056-433080; PView::AddViewToPortals @ 0x005A52D0, pseudo_c:433494-433503). acdream currently has MaxReprocessPerCell = 4 in PortalVisibilityBuilder (src/AcDream.App/Rendering/PortalVisibilityBuilder.cs:41, src/AcDream.App/Rendering/PortalVisibilityBuilder.cs:110).

C2. Outside through a doorway/window

Retail treats outside seen through an interior portal as part of the same PView. PView::DrawPortal selects a CBldPortal from outdoor_portal_list, adds the portal's stab views, calls PView::ConstructView(CBldPortal*, CPolygon*, ...), then draws cells if construction succeeds (PView::DrawPortal @ 0x005A5AB0, pseudo_c:433895-433933).

PView::ConstructView(CBldPortal*, CPolygon*, ...) classifies the viewer against the portal plane and portal side, clips through the portal polygon, gets the target EnvCell by other_cell_id, copies the view into that cell's portal view, optionally draws the portal polygon, and recursively constructs the EnvCell view (PView::ConstructView(CBldPortal*, CPolygon*, int, int) @ 0x005A59A0, pseudo_c:433827-433891).

PView::DrawCells checks outside_view.view_count; when nonzero, it enables sunlight, draws LScape, flushes alpha, then loops the cell draw list and draws EnvCell contents using the per-cell portal views (PView::DrawCells @ 0x005A4840, pseudo_c:432715-432807). This is the decomp evidence that a doorway to outside should render landscape/sky/rain/exterior content through the clipped outside view. It should not show clear color.

acdream has an OutsideView concept in PortalVisibilityBuilder, but it is currently owned by a separate render-side cell system and a split indoor branch (src/AcDream.App/Rendering/PortalVisibilityBuilder.cs:6-19, src/AcDream.App/Rendering/GameWindow.cs:11021-11235). The concept is directionally right; the authority and traversal convergence differ from retail.

C3. Interior sealing and clipping

Retail interior sealing is primarily geometry plus portal clipping:

• EnvCells render their own surfaces, environment/cell structure, static objects, and lights (CEnvCell struct fields in acclient.h:32072-32090; ACViewer R_EnvCell draws EnvCell environment and static objects from EnvCell transforms/textures, references/ACViewer/ACViewer/Render/R_EnvCell.cs:24-82).
• The visible cell list is portal-clipped by PView; each EnvCell draw uses its current portal views (PView::DrawCells @ 0x005A4840, pseudo_c:432737-432807).
• CObjCell::find_visible_child_cell searches current EnvCell/portal-neighbor/visible cells by point_in_cell, so child/entity visibility is also cell-graph based rather than global AABB visibility (CEnvCell::find_visible_child_cell @ 0x0052DC50, pseudo_c:311397-311462).

Inference from sources: retail prevents wall/entity/particle bleed by drawing only the portal-visible EnvCells/entities under the current PView clips and by treating outside as a clipped outside_view. It is not relying on a broad "render all indoor then stencil terrain" split.

WorldBuilder's current/reference path is coarser. It builds building portal groups from LandBlockInfo and EnvCell BFS (references/WorldBuilder/WorldBuilder.Shared/Services/PortalService.cs:45-135), then VisibilityManager.RenderInsideOut marks all portals of current/frustum-visible building groups in stencil, punches depth, renders full EnvCells of current buildings, and renders terrain/scenery through the stencil (references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-154). That is useful as a Silk.NET implementation base, but it is not the retail PView algorithm.

C4. Terrain and sky draw policy

Retail exposes a simple outside test for the player position. SmartBox::is_player_outside reads the player object's m_position.objcell_id low word and returns true for outdoor cell ids, i.e. low word below the EnvCell range (SmartBox::is_player_outside @ 0x00451E80, pseudo_c:90996-91007). Position::get_outside_cell_id uses LandDefs::adjust_to_outside to derive the outdoor cell id from the position's origin and returns that adjusted outside id when applicable (Position::get_outside_cell_id @ 0x004527B0, pseudo_c:91552-91575).

CellManager::ChangePosition is the main render/load bridge. When moving to a new current cell, it prefetches cells, gets the CObjCell, and if the cell is outside or seen_outside or keep_lscape_loaded, it updates the landscape load point. If not, it releases all landscape. Later, if the current cell is outside or seen_outside, it copies sunlight and landscape ambient light; otherwise it sets a flat indoor ambient value (CellManager::ChangePosition @ 0x004559B0, pseudo_c:94601-94682).

So retail's terrain/sky policy is not "indoor means no outside ever." It is:

• Outdoor current cell: landscape/sunlight/ambient are active.
• EnvCell with seen_outside: landscape/sunlight/outdoor ambient remain active and can be drawn through portal views.
• EnvCell without seen_outside: landscape is released and indoor ambient is used.

This maps to cottages/cellars/dungeons better than acdream's current split. acdream currently computes a separate render camera cell, gates a kill-switched indoor branch on ACDREAM_A8_INDOOR_BRANCH, renders sky when !cameraInsideCell || cameraInsideBuilding, and skips terrain when cameraInsideBuilding so RenderInsideOutAcdream can stencil-gate terrain (src/AcDream.App/Rendering/GameWindow.cs:7325-7356, src/AcDream.App/Rendering/GameWindow.cs:7539-7597, src/AcDream.App/Rendering/GameWindow.cs:7634-7645).

C5. Is render cell visibility the same graph as physics?

Verified: retail render and physics both operate on CObjCell/CEnvCell/CLandCell graph objects. Physics uses CObjCell::GetVisible, CEnvCell::find_transit_cells, CLandCell::add_all_outside_cells, and point_in_cell for transitions (CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308742-308867). Render uses CEnvCell portal arrays, CObjCell.seen_outside, CEnvCell::find_visible_child_cell, and PView over EnvCells (acclient.h:30915-30929, acclient.h:32072-32090, CEnvCell::find_visible_child_cell @ 0x0052DC50, pseudo_c:311397-311462; PView::ConstructView(CEnvCell*, ushort) @ 0x005A57B0, pseudo_c:433750-433789).

The render loader is explicitly fed by the player's/current position through CellManager::ChangePosition (CellManager::ChangePosition @ 0x004559B0, pseudo_c:94601-94682). That is the bridge acdream should mirror: render should be rooted in authoritative physics/current cell, even if camera collision/follow offset needs a child-cell lookup for view origin.

holtburger independently notes the same target for client-side visibility: its world-state liveness code currently uses a conservative approximation, with a TODO to replace it by detecting the player's EnvCell, reading SeenOutside, unioning current EnvCell visible cells, and merging outdoor visibility only for SeenOutside EnvCells (references/holtburger/crates/holtburger-world/src/state/liveness.rs:135-146).

D. Recommended acdream architecture

D14. Retail-faithful target

Use one cell graph and one membership authority:

• Core physics owns current membership: PhysicsBody.CellId/equivalent should be updated from transition SpherePath.CurCellId, not from a post-sweep ResolveCellId.
• CellTransit remains the port of retail candidate discovery, but its output should be consumed as check_cell inside the transition, not as a standalone static classifier at the end of every tick.
• Render receives the authoritative current cell id plus camera position. If the camera is offset from the player, render may call a retail-style visible child lookup (CEnvCell::find_visible_child_cell) within the same graph, but it should not run an independent AABB FindCameraCell as the source of truth.
• Render builds one PView-style frame: per-cell portal views, a todo list, a draw list, and an OutsideView. It uses seen_outside to decide whether outside landscape/light is active.

This aligns with the roadmap's Phase U direction: replace the abandoned two-pipe indoor/outdoor split with a unified retail-faithful render pipeline.

D15. Specific decisions

Yes: membership should be advanced inside the transition sweep. acdream should remove the final static ResolveCellId calls from ResolveWithTransition and return sp.CurCellId/accepted transition state after FindTransitionalPosition and ValidateTransition, matching retail SetPositionInternal (CPhysicsObj::SetPositionInternal(CTransition const*) @ 0x00515330, pseudo_c:283399-283462; current mismatch src/AcDream.Core/Physics/PhysicsEngine.cs:847, src/AcDream.Core/Physics/PhysicsEngine.cs:866).

Yes: port the do_not_load_cells prune, but treat it as a secondary correctness/stability fix. Add explicit CellArray semantics to CellTransit or equivalent: AddedOutside, DoNotLoadCells, candidate ids and loaded cell pointers. Then apply the retail prune when building no-load/static lists from an EnvCell origin (CELLARRAY struct acclient.h:31574-31580; prune in CObjCell::find_cell_list @ 0x0052B4E0, pseudo_c:308829-308867; ACE SetStatic/SetDynamic references/ACE/Source/ACE.Server/Physics/Common/CellArray.cs:17-29).

Yes: render should obey physics current cell and a single portal traversal. acdream's current CellVisibility.FindCameraCell does AABB point checks with grace frames (src/AcDream.App/Rendering/CellVisibility.cs:301-380), and GameWindow gates a separate indoor branch with ACDREAM_A8_INDOOR_BRANCH (src/AcDream.App/Rendering/GameWindow.cs:7325-7356). Retail instead passes current position/cell into CellManager::ChangePosition, uses seen_outside, and traverses PView (CellManager::ChangePosition @ 0x004559B0, pseudo_c:94601-94682; PView::ConstructView(CEnvCell*, ushort) @ 0x005A57B0, pseudo_c:433750-433789).

D16. Must-port functions and integration order

1. Physics result commit

   • Must-port/align: CTransition::validate_transition @ 0x0050AA70, CPhysicsObj::SetPositionInternal(CTransition const*) @ 0x00515330, CPhysicsObj::change_cell @ 0x00513390.
   • Work: return accepted sp.CurCellId/sp.CheckCellId according to retail state, remove post-sweep static ResolveCellId from success and partial-failure paths.
   • Tests: doorway stationary jitter test, room-to-room threshold test, cellar ramp top test, blocked-wall no-cell-change test. Assert cell id changes only after accepted movement.

2. Cell array parity

   • Must-port/align: CObjCell::find_cell_list @ 0x0052B4E0, CEnvCell::find_transit_cells @ 0x0052C820, CLandCell::add_all_outside_cells @ 0x00533630, CELLARRAY::add_cell @ 0x006B4FF0, CELLARRAY::remove_cell @ 0x006B4E80.
   • Work: replace hard-cap BFS/static hash-set behavior with a closer CELLARRAY model; include loaded/null cell entries, added_outside, do_not_load_cells, and retail prune.
   • Tests: golden candidate arrays around a cottage doorway, cellar exit, interior room portal, and outdoor-to-building entry. Include no-load prune cases from EnvCell origin.

3. Render cell root

   • Must-port/align: CellManager::ChangePosition @ 0x004559B0, SmartBox::is_player_outside @ 0x00451E80, Position::get_outside_cell_id @ 0x004527B0, CEnvCell::find_visible_child_cell @ 0x0052DC50.
   • Work: render frame root uses physics current cell id; seen_outside controls landscape/light availability. Camera child lookup should be graph/BSP based, not AABB-only.
   • Tests: inside EnvCell with seen_outside keeps outdoor light/landscape; sealed dungeon EnvCell suppresses landscape; camera near doorway does not strobe render branch.

4. PView traversal

   • Must-port/align: PView::ConstructView(CEnvCell*, ushort) @ 0x005A57B0, PView::InitCell @ 0x005A4B70, PView::AddToCell @ 0x005A4D90, PView::AddViewToPortals @ 0x005A52D0, PView::DrawPortal @ 0x005A5AB0, PView::DrawCells @ 0x005A4840.
   • Work: replace MaxReprocessPerCell cap with portal_view_type.update_count-style propagation. Produce cell_draw_list and outside_view from one traversal. Draw landscape through outside_view, then EnvCells through per-cell views.
   • Tests: portal graph convergence test where a cell receives multiple clipped slices; doorway outside-view non-empty test; sealed cellar no-outside-view test; no clear-color pixel through door in visual QA.

5. Render object/entity clipping

   • Must-port/align: CEnvCell::find_visible_child_cell @ 0x0052DC50 and PView draw-list semantics.
   • Work: cull or stencil entities/particles by visible cell/portal view, not just world frustum.
   • Tests: entity behind wall in adjacent EnvCell is not visible; entity visible through doorway remains visible; particles do not bleed through sealed walls.

Main risks

• Removing post-sweep ResolveCellId will expose any missing CheckCellId updates inside acdream's transition port. Before deleting it outright, add diagnostics proving sp.CheckCellId/sp.CurCellId are updated by CheckOtherCells for the known doorway, room, and cellar cases (src/AcDream.Core/Physics/TransitionTypes.cs:2061-2075, src/AcDream.Core/Physics/TransitionTypes.cs:3388-3425).
• acdream's CellTransit.FindTransitCellsSphere currently marks exitOutside = true for any exit portal encountered in BFS (src/AcDream.Core/Physics/CellTransit.cs:95-123). Retail/ACE gate outside expansion on portal-plane/sphere tests in the EnvCell transit path (CEnvCell::find_transit_cells @ 0x0052C820, pseudo_c:309968-310122; ACE references/ACE/Source/ACE.Server/Physics/Common/EnvCell.cs:319-331). Revisit this before relying on the transition cell as final truth.
• Render work can regress everything if it tries to preserve the old branch split. Implement the PView traversal as a frame product first and compare it against current PortalVisibilityBuilder outputs before changing draw order.
• Dungeons need separate visual QA from cottages: pure dungeon landblocks should not draw outdoor terrain, while seen_outside building/cellar EnvCells may still need clipped outdoor draw (CellManager::ChangePosition @ 0x004559B0, pseudo_c:94649-94682; ACE dungeon heuristic references/ACE/Source/ACE.Server/Entity/Landblock.cs:1266-1277).

Final answer to the decision

The candidate fix direction is correct, with one clarification: do_not_load_cells is necessary for parity but not sufficient by itself. The load-bearing retail behavior is transition-owned membership. acdream should stop reclassifying the final static point after the sweep, commit the swept cell like SetPositionInternal, and make render consume that same current cell through a PView-style portal traversal with seen_outside/OutsideView.