acdream/docs/research/2026-05-31-u4c-initcell-pseudocode.md

U.4c — PView::InitCell portal-side pseudocode (Task U.4c-3 oracle note)

Decomp anchor: docs/research/named-retail/acclient_2013_pseudo_c.txt:432896 (PView::InitCell), sidedness classification at 432928-432975; the consumer gate PView::ClipPortals at 433589. Struct layout from acclient.h: CCellPortal (~32300) { other_cell_id; other_cell_ptr; portal /*CPolygon* */; portal_side; other_portal_id; exact_match } (stride 0x18, matches InitCell's edx_1 += 0x18); portal_info (~32458) { int seen; int inflag }.

PortalFlags.PortalSide = 0x2, ExactMatch = 0x1 — confirmed by reflection against Chorizite.DatReaderWriter 2.1.7 (the version the audit tool + app use):

PortalFlags.ExactMatch = 1 (0x1)
PortalFlags.PortalSide = 2 (0x2)

Our physics-side PortalInfo.PortalSide already decodes this as a BOOLEAN with INVERTED polarity: PortalSide(bool) = (Flags & 2) == 0 (TRUE when the bit is clear). This matches ACE EnvCell.find_transit_cells and the existing pseudocode doc acclient_indoor_transitions_pseudocode.md:291.

What InitCell actually computes (per portal)

Render::FrameCurrent[0..2] is the viewer position in the cell's pushed coordinate frame (positionPush(3, &ebp->pos) at 432906 → viewer expressed in cell-local space). ecx_4 = portal->portal is the CPolygon*; ecx_4[8..0xb] are the portal-plane coefficients (a, b, c, d).

D = FrameCurrent.z*c + FrameCurrent.y*b + FrameCurrent.x*a + d
  = dot(viewerLocal, planeNormal) + planeD        // signed distance, viewer→plane
eps = 0.000199999995f                              // ~2e-4

// 432938-432969: a 3-way classification of D vs ±eps, then a compare to portal_side.
// (Decoded from the x87 status-word idiom: byte[1] bit0=C0 (D<y), bit2=C2 (unordered),
//  bit6=C3 (D==y).  &0x41 = C0|C3 = D<=y ;  &0x05 = C0|C2 = D< y (ordered).)
if (D <= +eps) {                  // 432941: not clearly in front
    if (D < -eps) {               // 432948 (!p_1 is false): clearly BEHIND the plane
        portal.inflag = 0; var_4 = 1;       // 432954 — handled, no side compare
        // (seen was cleared to 0 at 432933 for non-entry portals)
    } else {                      // -eps <= D <= +eps : ON the plane
        eax_9 = 1; goto compare;  // 432950
    }
} else {                          // D > +eps : clearly IN FRONT
    eax_9 = 0;                    // 432959
compare:
    if (eax_9 == portal.portal_side)        // 432962 (raw int field 0/1)
        portal.inflag = 0; var_4 = 1;       // 432964
    else
        portal.inflag = 1;                  // 432968
}

ClipPortals (433589) traverses a portal iff seen != 0 && inflag != 1. NOTE: seen is set elsewhere (entry portal at 432973-432974; AddViewToPortals/ AddToCell/SetOtherSeen on neighbour discovery) — InitCell here primarily writes inflag. The BN field-write polarity for InitCell's local seen/inflag toggling is genuinely ambiguous in the pseudo-C (the *(uint32_t*)esi base aliases portal.data, and the entry-portal vs other-portal cases write both fields), and mis-decoding it is exactly the #98 trap. We therefore DO NOT hinge the port on the exact BN write polarity.

What we port (robust, cross-checked, polarity-resolved by real data)

Three things are unambiguous and cross-checked against THREE independent sources (InitCell structure; ACE find_transit_cells as ported in our own CellTransit.cs:161; acclient_indoor_transitions_pseudocode.md:305-314):

1. Signed distance D = dot(viewerLocal, planeN) + planeD (we already compute this in CameraOnInteriorSide; the plane geometry is fine).
2. A near-plane band is always traversable (the on-plane eax_9=1 branch + the ±eps tolerance). This is what kills the flap: a camera a few cm either side of the opening is in/near the band and never spuriously culled.
3. The traverse/cull SENSE is keyed on the authored PortalSide bit, NOT a centroid guess.

The sense (resolved against real dat — winding-corrected)

Boolean PortalSide = (Flags & 2) == 0 (our existing convention, matching ACE / PortalInfo.cs:44). The doc-§314 intuition says "PortalSide=true ⇒ interior is the POSITIVE half-space (dist>0 is inside the cell)", which would give PortalSide ? (D > -eps) : (D < +eps). But that intuition assumes ACE/retail's stored plane-normal orientation; our hydration normal is Cross(p1-p0, p2-p0) (GameWindow:5641), whose winding is FLIPPED relative to ACE's for these cells. The real-dat evidence proves it: for 0171→0170 (N=(0,-1,0), d=-7.65) the cell's own centroid is at centroidDot = -4.400 (NEGATIVE side) yet datPortalSide=0 (PortalSide-bool=true). So for OUR winding, PortalSide=true ⇒ interior is the NEGATIVE half. The sign-correct traverse test is the INVERSE of the doc intuition:

traverse(portal, D) =
    PortalSide ?  (D <  +eps)      // OUR winding: interior = negative half → cull only when clearly on positive (far) side
               :  (D >  -eps)      // interior = positive half → cull only when clearly on negative (far) side
eps = 0.01f   // PortalSideEpsilon, the existing builder tolerance (≈ retail's near-plane band, scaled to our units)

Genuinely back-facing is still culled: a camera clearly on the FAR side (|D| >> eps, wrong sign) fails the inequality → CULL. The ±eps band keeps a camera sitting a few cm either side of the opening traversable → no flap.

Real-dat verification (A8CellAudit portals, camera = cell centroid + a swept pose toward/just past each portal plane). Sign-correct ONLY IF every interior pose traverses ALL the camera cell's portals (neighbours, incl. the window/exit cell, stay reachable). With the formula above, ALL of 0171's three portals AND 0170's two portals (incl. its 0xFFFF exit) traverse from interior poses:

from→portal	N	d	centroidDot	datPortalSide	PortalSide(bool)	traverse@centroid
0171→0170	(0,-1,0)	-7.65	-4.400	0	true → D<+eps	-4.40 < eps → TRAVERSE
0171→0173	(-1,0,0)	+4.10	-2.450	0	true → D<+eps	-2.45 < eps → TRAVERSE
0171→0175	(0,0,-1)	-0.00	-4.600	0	true → D<+eps	-4.60 < eps → TRAVERSE
0170→EXIT	(0,-.99,.10)	-8.56	-0.346	0	true → D<+eps	-0.35 < eps → TRAVERSE
0170→0171	(0,-1,0)	-7.65	+0.480	1	false → D>-eps	+0.48 > -eps → TRAVERSE

⚠️ FINDING — the PortalSide swap is a NO-OP for the flap (BLOCKED 2026-05-31)

The swept-pose A8CellAudit portals run (camera lerped from cell centroid toward the nearest portal vertex and a bit past the plane, t∈[0,1.3]) was meant to confirm the sense. It instead falsified the whole premise of this fix. For EVERY portal of the flap cells, three candidate senses were evaluated per pose:

• O — OLD centroid InsideSide (pre-fix CameraOnInteriorSide)
• A — winding-corrected PortalSide (the formula above)
• B — doc-§314 literal PortalSide (opposite polarity)

0171→0170  N=(0,-1,0) d=-7.65  ourInsideSide=1 datPortalSide=0
  t0.00:D=-4.40/O=T/A=T/B=x  t0.25:D=-3.30/O=T/A=T/B=x  ... t1.00:D=0.00/O=T/A=T/B=T
  t1.15:D=0.66/O=x/A=x/B=T   t1.30:D=1.32/O=x/A=x/B=T
0170→0171  N=(0,-1,0) d=-7.65  ourInsideSide=0 datPortalSide=1
  t0.00:D=0.48/O=T/A=T/B=x   ... t1.00:D=0.00/O=T/A=T/B=T  t1.15:D=-0.07/O=x/A=x/B=T

(All of 0171's three portals + 0170's two + 0174 + 0175 show the same pattern.)

Two facts kill the side-test fix:

1. A ≡ O at every pose, every portal. The "anti-correlation" the characterization doc saw is in the RAW stored values (InsideSide=1 vs datPortalSide=0); but each value maps to the SAME inequality direction, so the centroid sense and the winding-corrected PortalSide sense make the identical traverse/cull decision. Swapping centroid InsideSide → dat PortalSide is a literal no-op for these cells and cannot fix the flap.
2. B culls true-interior poses (B=x at t0.00, the cell centroid) → the doc-literal polarity is wrong for our winding. So there is no viable alternative polarity either.

Root cause of the flap is NOT the side-test sense. It is structural: set membership is rebuilt every frame from a plane-side test against the 3rd-person camera EYE (camPos, GameWindow:7290), which legitimately CROSSES interior portal planes while FindCameraCell still roots the camera in the cell (AABB + grace frames). Once the eye is clearly on the far side of the 0171→0170 plane (D > +eps, poses t1.15+), ANY plane-side test — centroid or PortalSide, either polarity — culls the portal, drops 0170, empties OutsideView, and flaps terrain/shells off. The audit proves no sense choice avoids this.

The retail-faithful fix is PVS / stab_list grounding (spec §5.2 H1; U.4 handoff 2026-05-30-phase-u4-shipped-and-flap-handoff.md lines 91-115): seed every cell in the camera cell's stab_list (add_views / grab_visible_cells, decomp 433382 / 311878) as a participant BEFORE the per-frame walk, so the window/exit cell stays in the set regardless of the side test. The side test then only refines WHERE each cell draws, never WHICH cells exist. That is the spec's Layer 2 — out of scope for the task's "swap the side test in the builder" framing, which is why this is reported BLOCKED.

ClipPlanes[i].Normal/D remain correct (plane geometry is fine); InsideSide remains on the struct. The builder side test is left UNCHANGED — no no-op swap shipped.