Corner Culling
cornerculling is an optional CPU visibility package in namespace CornerCulling.
It checks whether opaque boxes or ellipsoids completely block the view between
observer and target bounds. Blockers can rotate, and multiple blockers can
combine conservatively. It works without a renderer, physics integration,
GPU or worker threads, on native and WebAssembly builds.
Add and query
tide add cornercullingKeep a CullingWorld in your game's state, build it from wall boxes, and retain
one CullingCache per directed observer/target pair. This example's Main is
the game's existing main scene:
using CornerCulling;
singleton OcclusionExample
{
CullingWorld walls;
CullingCache pair;
bool visible;
}
event(Spawned) BuildOcclusionExample(with Main, mut OcclusionExample example)
{
mut List<Occluder> blockers = [Occluder {
bounds = Bounds { center = float3(0), extents = float3(0.5, 4, 4) }
}];
// Rotation and ellipsoids use the same world/query interface.
blockers.Add(Occluder {
bounds = Bounds { center = float3(20, 0, 0), extents = float3(0.25, 2, 4) },
rotation = quaternion(0, 0.38268343, 0, 0.92387953)
});
blockers.Add(Occluder {
shape = OccluderShape.Ellipsoid,
bounds = Bounds { center = float3(24, 0, 0), extents = float3(1, 2, 1) }
});
example.walls.Rebuild(blockers);
// In a game, rebuild only when map membership changes, then run queries
// after movement and door updates. Retain one cache per directed pair.
var query = CullingQuery {
observer = Bounds { center = float3(-5, 0, 0), extents = float3(0.5) },
target = Bounds { center = float3(5, 0, 0), extents = float3(0.5, 1, 0.5) }
};
example.visible = example.walls.Query(query, example.pair).IsVisible();
}Bounds.extents is a half size, not a full size. A point observer has zero
extents. The target bounds should include the body and anything visible with it.
Only author boxes wholly inside opaque geometry; an enclosing mesh AABB can
cover empty space and incorrectly hide a visible player.
Results and updates
| API | Behavior |
|---|---|
world.Rebuild(boxes) |
Snapshot the input list and rebuild its spatial tree |
world.Query(query, cache) |
Return a result and update a candidate cache |
world.Query(query) |
Query without retaining a cache |
result.IsVisible() |
True for Visible and Unknown; false only for Occluded |
result.occluder |
Input-list index for a single-blocker proof; -1 for combined proofs or no proof |
world.Update(index, box) |
Replace an existing source index and immediately refit; false for an invalid index/unbuilt world |
world.Clear() |
Empty contents, retaining capacity; queries become Unknown until rebuilt |
Occluder.mask and CullingQuery.mask are integer bitmasks, both defaulting to -1
(all bits). A box participates if their intersection is nonzero. Set a box's
mask to zero to disable it. Invalid geometry also cannot block. Source indices
remain stable until the next rebuild; adding entries requires rebuilding.
Assign default to the world to release its owned lists.
CullingQuery.surfaceMargin defaults to 0.0001 world units and must be finite
and nonnegative. It shrinks the blocker in addition to numerical safety padding.
All blocker extents must be positive; endpoint extents can be zero. Overlapping
endpoints, endpoint/blocker contact, tangency and incomplete coverage fail open.
A default/cleared world or invalid query returns Unknown; a built empty world
returns Visible.
A single-blocker proof covers the complete corner envelope. Combined proofs
cover the union of solid wall sections or every complete subdivided envelope;
unrelated corner-ray hits are never sufficient. Caches remember single-blocker
candidates, not answers. Every query retests current geometry, so reuse after
updates, rebuilds, rollback or with another world is safe. Combined proofs
report Occluded with occluder == -1 and are recomputed on each query.
Rotation, shapes and joined walls
Occluder replaces Box. bounds.center is world-space; bounds.extents gives
local half-sizes for OccluderShape.Box (the default) or three radii for
OccluderShape.Ellipsoid. rotation defaults to quaternion.identity. Finite nonzero
quaternions are normalized internally in binary64; zero/nonfinite rotations,
unknown shapes and nonpositive extents cannot block. Observer and target bounds
remain world-aligned, including the full motion/equipment envelope.
Occluder diagonal = Occluder {
bounds = Bounds { center = float3(0), extents = float3(0.25, 2, 4) },
rotation = quaternion(0, 0.38268343, 0, 0.92387953)
};
Occluder pillar = Occluder {
shape = OccluderShape.Ellipsoid,
bounds = Bounds { center = float3(3, 0, 0), extents = float3(1, 2, 1) }
};Touching or overlapping axis-aligned box sections can form a solid wall.
The proof uses a rectangular volume inside their union, never their enclosing
AABB. Internal seams disappear; surfaceMargin shrinks the joined volume's
outside surfaces. Exact touching is accepted only when the boundary arithmetic
is exact; uncertain joins require actual overlap. No tolerance bridges a real
gap. Joining retains at most 32 boxes derived from the first 16 eligible BVH
candidates, so dense or fragmented maps can still fail open. Rotated boxes are
not welded at a touching seam.
For other layouts, maxSubdivisions (default 32, clamped to 0 to 128) bounds extra
splits of observer/target bounds. Each child is fully certified against a single
blocker or a joined volume. Both children must pass. This can combine overlapping
shadows from differently oriented boxes or ellipsoids. Depth is capped at eight;
exhausted budgets return Visible. Zero disables subdivision, not wall joining.
A visible answer means no proof was found, not that an unobstructed ray was
necessarily found. These limits trade culling effectiveness for bounded work;
they never justify hiding an uncertain target.
Reveal before a peek
Expand observer and target bounds to cover their reachable positions until the result will be consumed. Account for state age, remaining transit delay, jitter, the culling interval, acceleration and prediction error. Include camera movement, stance changes, animation and equipment. Do not count transit twice if state age already includes it. Missing snapshots increase the horizon; current velocity alone does not bound a player who can change direction.
Teleports remain visible until a reliable envelope exists. Update moving/opening doors before queries, or disable uncertain blockers. Enlarging endpoints does not compensate for stale walls. A larger envelope costs more and intentionally reveals enemies earlier.
Use Tide's visibility policy
The game builds an Audience from players whose query result IsVisible().
Keep the target's owner in that audience, apply team/spectator rules, then use
Visibility.Set(group, audience) for
an entity group, or restrict the components containing sensitive state. The
server retains the complete world for collision and wall-penetrating shots.
The query does not implement smoke, sound or gameplay events. Treat those as separate policies. Hiding one component does not hide copies of its position in public singletons, inputs or event payloads. Box2D's and Box3D's own state (their snapshots, colliders and rewind lists) isn't sent to clients, but a hidden player's body is still in the server's physics world, which decides hits. The existing visibility limitations, including projected-world host migration, still apply. This package does not resolve network correction latency.
Cost and scope
The package is ordinary Tide code with strict arithmetic, binary64 intermediates and conservative numerical padding. Match storage participates in snapshots, hashes, packing and hot reload. Scalar queries read the tree and allocate no lists. Keep their four-byte caches in caller-owned storage; do not edit the world's implementation fields. Concurrent readers need independent caches and must not overlap mutation.
A cached blocker is tested first. Otherwise a balanced BVH rejects distant
subtrees and masked geometry before corner testing. Leaves hold at most four
boxes; three-way partitioning handles repeated centroids. Build outside the
query loop. Update uses O(1) source lookup and an O(log N) ancestor refit
with unshared storage; shared snapshots can incur COW copying.
Moving blockers can still degrade spatial quality; rebuild when necessary.
Missing source/parent indices after layout migration are recovered once in O(N).
For a batch, loop over preallocated storage and call world.Query directly.
Take each cache element into a mutable local and write it back afterward.
Passing a world or its lists by value to per-pair helpers can add expensive
copies. There is no package-owned scheduler or batch allocation.
Supported primitives are boxes and ellipsoids, including spheres. Capsules, arbitrary convex hulls, mesh/terrain import, baked visibility sets, automatic scene collection and renderer integration are not implemented. Combined proofs are deliberately bounded and do not solve every possible union of occluders. Profile a representative map: overlapping near misses and large latency bounds can dominate query cost. The package provides conservative geometry queries, not a complete anti-cheat system.