acdream/docs/research/2026-06-09-landdefs-outside-cells-pseudocode.md

# LandDefs + add_all_outside_cells — retail pseudocode (issue #106)

**Date:** 2026-06-09. **Purpose:** ground the #106 fix (outdoor membership freezes at
landblock boundaries) in the retail decomp. The pre-fix acdream port of
`AddAllOutsideCells` clamped candidates to the current landblock's 8×8 grid; retail
has NO such clamp — its cell math runs in a **global** landcell coordinate space
(`lcoord`, 0..2039) spanning the entire map, so landblock crossings are inherent.

**Sources:** `docs/research/named-retail/acclient_2013_pseudo_c.txt` (primary);
`references/ACE/Source/ACE.Server/Physics/Common/LandDefs.cs` + `LandCell.cs`
(cross-check, in the MAIN repo checkout — this worktree only vendors WorldBuilder).

---

## 1. The coordinate model

- A **landblock id** packs the map grid into the high word of a cell id:
  bits 31–24 = `block_x` (east–west), bits 23–16 = `block_y` (north–south).
- An **outdoor cell** low word is `1 + cell_x*8 + cell_y` (`cell_x`,`cell_y` ∈ 0..7,
  24 m cells, row-major with X outer).
- A **global lcoord** is `(block_x*8 + cell_x, block_y*8 + cell_y)` — a flat map-wide
  cell grid, valid range `[0, 0x7F8)` = `[0, 2040)` (255 blocks × 8).
- Positions in retail `Position` structs are **block-local** (`[0,192)` per axis).

acdream divergence to bridge: physics positions are in a **floating world frame**
anchored at the login/teleport landblock (origin = that block's SW corner;
`GameWindow.ApplyLoadedTerrainLocked` registers each block's origin as
`((lbX − centerX)·192, (lbY − centerY)·192)`). Convert world → current-block-local by
subtracting the current block's registered origin (`CellGraph._terrain` stores it),
then retail's math applies verbatim.

## 2. LandDefs functions (verbatim-equivalent pseudocode)

### in_bounds (pc:68509, @0x0043d650)
```
in_bounds(x, y) := x >= 0 && y >= 0 && x < 0x7F8 && y < 0x7F8
```

### blockid_to_lcoord (pc:68520, @0x0043d680)
```
blockid_to_lcoord(cellId, out lx, out ly):
    if cellId == 0: return false
    lx = ((cellId >> 24) & 0xFF) * 8        // decomp form: (cellId >> 21) & 0x7F8
    ly = ((cellId >> 16) & 0xFF) * 8        // decomp form: (cellId >> 13) & 0x7F8
    return in_bounds(lx, ly)
```
⚠️ **BN artifact:** the decomp renders the Y extraction as `(int8_t)(cellId >> 16) << 3`
— a signed cast that would explode for block_y ≥ 0x80 (e.g. 0xB4). ACE's
`blockid_to_lcoord` (LandDefs.cs:169) confirms plain zero-extended masks. Use unsigned.

### inbound_valid_cellid (pc:163438, @0x004979a0)
```
inbound_valid_cellid(cellId):
    low = cellId & 0xFFFF
    if !(low in [1,0x40] || low in [0x100,0xFFFD] || low == 0xFFFF): return false
    lx = (cellId >> 21) & 0x7F8; ly = (cellId >> 13) & 0x7F8
    return in_bounds(lx, ly)
```
⚠️ **ACE divergence:** ACE's `inbound_valid_cellid` (LandDefs.cs:241) checks only
`block_x`. Retail checks both axes. Port retail.

### gid_to_lcoord (pc:163500, @0x00497a90) — outdoor cells only
```
gid_to_lcoord(cellId, out lx, out ly):
    if !inbound_valid_cellid(cellId): return false
    if (cellId & 0xFFFF) >= 0x100: return false          // outdoor only
    lx = block_x*8 + ((low−1) >> 3)
    ly = block_y*8 + ((low−1) & 7)
    return in_bounds(lx, ly)
```

### lcoord_to_gid (pc:171859, @0x004a19a0)
```
lcoord_to_gid(lx, ly):
    if !in_bounds(lx, ly): return 0
    low   = (ly & 7) + (lx & 7)*8 + 1
    block = ((lx >> 3) << 8) | (ly >> 3)                  // decomp: ((lx & ~7) << 5) | (ly >> 3)
    return (block << 16) | low
```
Cross-block is transparent: `lx = 1439` → `block_y = 179 (0xB3)` even when the input
block was 0xB4.

### get_outside_lcoord (pc:438690, @0x005a9b00)
```
get_outside_lcoord(cellId, blockLocalPos, out lx, out ly):
    if cellId low16 not in {1..0x40, 0x100..0xFFFD, 0xFFFF}: return false
    blockid_to_lcoord(cellId, out lx, out ly)
    lx += floor(pos.x / 24); ly += floor(pos.y / 24)      // floor() — negative-safe
    return in_bounds(lx, ly)
```
`floor(pos/24)` may be negative or ≥ 8 — **this is the landblock crossing**. No clamp.

### adjust_to_outside (pc:438719, @0x005a9bc0)
```
adjust_to_outside(ref cellId, ref blockLocalPos):
    low = cellId & 0xFFFF
    if low in valid ranges (as above):
        if |pos.x| < 0.000199999995: pos.x = 0            // retail EPSILON snap
        if |pos.y| < 0.000199999995: pos.y = 0
        if get_outside_lcoord(cellId, pos, out lx, out ly):
            cellId = lcoord_to_gid(lx, ly)
            pos.x -= floor(pos.x / 192) * 192             // re-normalize to NEW block
            pos.y -= floor(pos.y / 192) * 192
            return true
    cellId = 0
    return false
```
⚠️ **BN artifact:** the decomp shows `floor(pos.x / 0f) * 0f` — the constant was
dropped. ACE (LandDefs.cs:140-141) confirms `BlockLength = 192`.

## 3. CLandCell::add_all_outside_cells — sphere variant (pc:317499, @0x00533630)

```
add_all_outside_cells(position, numSphere, spheres[], cellArray):
    if cellArray.added_outside: return
    cellArray.added_outside = 1
    if numSphere == 0:
        cellId = position.objcell_id; pos = position.frame.origin
        if adjust_to_outside(ref cellId, ref pos) && gid_to_lcoord(cellId, out lx, ly):
            add_outside_cell(cellArray, lx, ly)
        return
    for each sphere (center copied):
        cellId = position.objcell_id
        if !adjust_to_outside(ref cellId, ref center): BREAK   // break, not continue
        if gid_to_lcoord(cellId, out lx, out ly):
            add_outside_cell(cellArray, lx, ly)
            point.x = center.x mod 24; point.y = center.y mod 24   // center is [0,192) post-adjust
            check_add_cell_boundary(cellArray, point, lx, ly, minRad=radius, maxRad=24−radius)
```

### add_outside_cell (pc:317056, @0x00532ec0)
```
add_outside_cell(cellArray, lx, ly):
    if in_bounds(lx, ly):
        cellArray.add_cell(lcoord_to_gid(lx, ly), LScape::get_landcell(...))
```
**NO same-block filter.** ⚠️ ACE's `add_cell_block` (LandCell.cs:198) inserts
`if (id >> 16 != cellID >> 16) continue;` annotated `// FIXME!` — an ACE divergence
that drops cross-landblock cells. Do NOT copy it.

### check_add_cell_boundary (pc:317229, @0x00533260)
```
check_add_cell_boundary(cellArray, point, lx, ly, minRad, maxRad):   // strict > / <
    if point.x > maxRad:
        add_outside_cell(lx+1, ly)
        if point.y > maxRad: add_outside_cell(lx+1, ly+1)
        if point.y < minRad: add_outside_cell(lx+1, ly−1)
    if point.x < minRad:
        add_outside_cell(lx−1, ly)
        if point.y > maxRad: add_outside_cell(lx−1, ly+1)
        if point.y < minRad: add_outside_cell(lx−1, ly−1)
    if point.y > maxRad: add_outside_cell(lx, ly+1)
    if point.y < minRad: add_outside_cell(lx, ly−1)
```
A sphere exactly tangent to a 24 m boundary does NOT add the neighbour (strict
comparisons — matches ACE).

## 4. The containing-cell pick (CObjCell::find_cell_list, pc:308742-308869, @0x0052b4e0)

After the transit set is built, retail iterates candidates IN ORDER; for each it
subtracts `LandDefs::get_block_offset(position.block, candidate.block)` from the
sphere center (cross-block-aware) and calls the cell's `point_in_cell` (vtable
+0x84). Any containing cell sets the running result; an INTERIOR containing cell
breaks immediately (interior-wins); outdoor cells are disjoint columns so at most one
contains the point. acdream adaptation (landcells have no BSP `point_in_cell`): the
containing outdoor cell is `adjust_to_outside(currentCellId, blockLocal(center))` —
the global XY-column id — compared by identity against candidates. Pre-#106 this was
computed with a `[0,8)` grid clamp under the current block's prefix, which is what
froze membership at boundaries.

## 5. Worked goldens (from the #106 capture geometry)

Anchor A9B4 at world origin; A9B3 is one block SOUTH (origin (0, −192)).

| Input | Result |
|---|---|
| `blockid_to_lcoord(0xA9B40031)` | (1352, 1440) |
| `gid_to_lcoord(0xA9B40031)` (low 0x31 = 49 → cell 6,0) | (1358, 1440) |
| `lcoord_to_gid(1358, 1440)` | 0xA9B40031 (roundtrip) |
| `lcoord_to_gid(1358, 1439)` | **0xA9B30038** (block_y 179, cell 6,7) |
| `adjust_to_outside(0xA9B40031, (150, −1))` | cellId **0xA9B30038**, pos (150, **191**) |
| `adjust_to_outside(0xA9B40031, (150, −109.65))` | cellId **0xA9B30034** (floor(−109.65/24) = −5 → ly 1435), pos (150, 82.35) |
| `adjust_to_outside(0xA9B30038, (150, 193))` from A9B3 frame | cellId **0xA9B40031**, pos (150, 1) — northbound return |