acdream/docs/research/2026-06-24-obstruction-ethereal-pseudocode.md

obstruction_ethereal — set / clear / consume contract

Research date: 2026-06-24
Oracle: docs/research/named-retail/acclient_2013_pseudo_c.txt
Phase: Task 3 of the collision-inclusion verbatim-retail port

---

1. Gate 1 — CPhysicsObj::FindObjCollisions (pc:276782 / 0x0050f050)

// pc:276782
if (state & 4) AND (state & 0x10):   // ETHEREAL_PS | IGNORE_COLLISIONS_PS
    return 1   // OK_TS — instant-skip, no further work
// else fall through: ETHEREAL-alone goes into the block below

// pc:276802
int32_t var_c;
if ((state_2 & 4) != 0                              // target ETHEREAL
    || (ebx->object_info.ethereal != 0              // mover is ethereal
        && (state_2 & 1) == 0)):                    // AND target not REPORTS_COLLISIONS
    var_c = 1
    if (sphere_path.step_down == 0):
        goto label_50f0c9   // set obstruction_ethereal = 1 and continue
else:
    var_c = 0
// label_50f0c9:
ebx->sphere_path.obstruction_ethereal = var_c  // pc:276806
// ... continue with shape dispatch (FindObjCollisions body: BSP / Sphere / Cyl) ...

// At the END of the FindObjCollisions body (after all shape tests):
// pc:276989 / 0x0050f31e:
ebx->sphere_path.obstruction_ethereal = 0   // clear after each object's test

Translation (C#):

• ShouldSkip returns true ONLY when (targetState & 0x4) != 0 && (targetState & 0x10) != 0.
• ETHEREAL-alone falls through. Before the shape dispatch (BSP/Sphere/Cyl call), set sp.ObstructionEthereal = true when (targetState & 0x4) != 0.
• After the shape dispatch, retail clears the flag (= 0). In acdream we clear it at the END of the per-target loop iteration (mirrors the per-object clear at pc:276989).

Note on step_down gate: retail's var_c assignment also checks step_down == 0 before jumping to label_50f0c9. When step_down != 0, var_c stays 1 but hits the else var_c = 0 branch at pc:276804 (which sets var_c = 0). Reading the full branching tree: the ONLY path that sets obstruction_ethereal = 1 is when (state_2 & 4) != 0 (target ETHEREAL) AND step_down == 0. For acdream's transitional player insert, step_down is false at the outer loop entry, so the flag fires when target is ETHEREAL. We match retail exactly by gating on target ETHEREAL (the (obj.State & 0x4) != 0 check in the loop).

---

2. D5 clear — CEnvCell::find_env_collisions (pc:309580 / 0x0052c144)

// 0x0052c144:
arg2->sphere_path.obstruction_ethereal = 0;
// ... then: BSP dispatch for the ENV cell walls (not objects) ...

Translation (C#): At the top of FindEnvCollisions, clear sp.ObstructionEthereal = false before any BSP dispatch. The ENV path clears it because ENV walls are always solid — the flag only applies to object (CPhysicsObj) tests. This prevents a stale flag from a prior object loop from weakening ENV wall tests.

---

3. Consume site 1 — CSphere::intersects_sphere (pc:321692 / 0x00537ae4)

// pc:321692:
if (obstruction_ethereal != 0 || insert_type == PLACEMENT_INSERT):
    // sphere_intersects_solid test — allows passage if sphere is NOT inside solid
    if (collides_with_sphere(center, pos, radius_sum)):
        return 2   // COLLIDED — solid containment  
    // else: sphere is NOT inside solid, passage allowed — no push-back
else if (step_down == 0):
    // normal walkable / check_walkable / slide path (the BLOCKING path)
    ...

What this means: when obstruction_ethereal (target is passable-ethereal) or PLACEMENT_INSERT, the test only fails if the sphere FULLY OVERLAPS the solid region of the sphere target. In practice for a Sphere-type entity with no BSP this means you can walk through it as long as your sphere center isn't inside its solid — which is almost never true during normal movement. The blocker path (slide/push-back) is bypassed entirely.

acdream scope note: SphereCollision in TransitionTypes.cs does NOT currently implement this gate; it always does the slide path. That is a separate task (Task 5 or equivalent). For Task 3 scope: BSP objects are the priority for opened doors; the Sphere path is a separate port.

---

4. Consume site 2 — BSPTREE::find_collisions (pc:323742 / 0x0053a496)

// pc:323742:
if (insert_type == PLACEMENT_INSERT || obstruction_ethereal != 0):
    // sphere_intersects_solid with bldg_check center_solid flag
    ebp_4 = 1
    if (bldg_check != 0):
        ebp_4 = (hits_interior_cell == 0)  // center_solid weakens inside buildings
    if (root_node->sphere_intersects_solid(localspace_sphere, ebp_4)):
        return 2   // COLLIDED
    if (num_sphere > 1):
        if (root_node->sphere_intersects_solid(localspace_sphere[1], ebp_4)):
            return 2
else:
    // check_walkable / step_down / normal blocking path
    ...

This is the BSPQuery Path 1 at BSPQuery.cs:1717. The existing code:

if (path.InsertType == InsertType.Placement || obj.Ethereal)

obj.Ethereal is ObjectInfo.Ethereal (the MOVER's ethereal flag) which is NEVER set — it's always false. The correct translation of obstruction_ethereal is path.ObstructionEthereal (on SpherePath).

Fix: change to:

if (path.InsertType == InsertType.Placement || path.ObstructionEthereal)

This is the ONLY consume site for Task 3 scope (BSP objects). For the BSP path: when the target is ETHEREAL, path.ObstructionEthereal is set before calling BSPQuery.FindCollisions, so Path 1 fires instead of the normal blocking path. Path 1 uses sphere_intersects_solid which only returns COLLIDED if the player is inside a BSP solid leaf — during forward movement toward a door (which has no solid wall when open), the BSP finds no solid intersection, returns OK, player passes through.

---

5. Consume site 3 — CCylSphere::intersects_sphere (pc:324573 / 0x0053b4a0)

// pc:324573:
if (insert_type == PLACEMENT_INSERT || obstruction_ethereal != 0):
    // collides_with_sphere test (3D overlap only)
    if (CCylSphere::collides_with_sphere(this, global_sphere, ...)):
        return  // early-out, no Collided return — void return here
    // else: no collision, return (void — passable)
else:
    // step_down / check_walkable / normal blocking path
    ...

acdream implementation (Task 3 follow-up, 2026-06-24): CylinderCollision in TransitionTypes.cs now implements this gate as if (sp.ObstructionEthereal) return OK at the top of the method — mirroring exactly how SphereCollision (consume site 1) is handled. The retail function is void __thiscall, so all returns in the ethereal branch are void (= OK). An ethereal Cylinder (e.g. an NPC ghost) is now fully passable.

---

3b. Consume site 1 — CSphere::intersects_sphere (pc:321692) — full contract

The full decomp at pc:321692 / 0x537ae4 confirms:

// pc:321692:
if (obstruction_ethereal != 0 || insert_type == PLACEMENT_INSERT):
    // distSq check — if sphere NOT overlapping: return (void = passable)
    if (distSq < radiusSumSq):   // overlapping:
        // calls collides_with_sphere on sphere[1] if num_sphere > 1
        // returns void — no COLLIDED
    return  // void = passable in all cases
else:
    // step_down / check_walkable / slide blocking paths

Key: the CSphere::intersects_sphere function is void __thiscall — there is NO return 2 (COLLIDED) from the ethereal branch. The inner collides_with_sphere call (for the penetrating case) also produces no blocking result (it may contribute to a side-channel contact; it does NOT stop the player). The player is passable in ALL sub-cases of the ethereal branch.

acdream implementation (Task 3 follow-up, 2026-06-24): SphereCollision implements if (sp.ObstructionEthereal) return OK at the top. The inner overlap/slide path is bypassed — matches the void-return semantics of the retail ethereal branch.

---

Summary: set / clear / consume flow (complete after Task 3 follow-up)

FindObjCollisionsLoop():
    for each obj in cell.shadow_entries:
        // Gate 1: instant-skip needs BOTH bits
        if obj.State has ETHEREAL AND IGNORE_COLLISIONS:
            continue  // pass through, no obstruction_ethereal

        // Set flag for ETHEREAL-alone
        sp.ObstructionEthereal = (obj.State & 0x4) != 0

        // Shape dispatch — ALL three shapes now consume the flag:
        //   BSP:      BSPQuery.FindCollisions Path 1 → sphere_intersects_solid (passable)
        //   Sphere:   SphereCollision → if (ObstructionEthereal) return OK
        //   Cylinder: CylinderCollision → if (ObstructionEthereal) return OK

        // Clear after per-object test (retail pc:276989)
        sp.ObstructionEthereal = false

FindEnvCollisions():
    sp.ObstructionEthereal = false  // D5 clear — ENV walls are always solid
    // BSP dispatch against cell walls ...

Contracts (complete):

• ETHEREAL-alone BSP target (e.g. open door): ShouldSkip = false → flag set → BSP Path 1 fires → sphere_intersects_solid → player walks through open door. Passable.
• ETHEREAL-alone Sphere target (e.g. ghost NPC with sphere shape): flag set → SphereCollision returns OK immediately. Passable.
• ETHEREAL-alone Cylinder target (e.g. ghost NPC with cyl shape): flag set → CylinderCollision returns OK immediately. Passable.
• Non-ethereal wall/object: flag = false → normal blocking paths. Blocked.
• ENV cell walls: flag cleared before BSP dispatch → ENV BSP always blocking. Blocked.