Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): a wall stops the frame from drawing what stands behind it

esengine18712af7fa32
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index d62832ca5..76042a341 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -29,7 +29,7 @@ env:
test_registry_ondestroy test_view_api_matrix
test_shader_device test_draw_params test_texture_fb test_buffer_device
test_compressed_format test_batch_builder test_boundary_span test_webgpu_device
- test_clip_depth test_sort_key test_sprite_mask_range test_shadow_atlas test_particle_shapes test_lod_selection test_hdr_format test_probe_store
+ test_clip_depth test_sort_key test_sprite_mask_range test_shadow_atlas test_particle_shapes test_lod_selection test_hdr_format test_probe_store test_occlusion_view
test_text_edit test_render_graph test_device_loss test_physics_interpolation
test_bitmap_font test_texture_cache test_mesh_recovery test_aot_host test_aot_conformance
test_touch_stream
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9793678dd..3853eceea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -97,6 +97,38 @@ published separately; it ships inside the editor.
Per-instance, not per-object-record, because the record was out of room at the
time. The entry below is the change that moved it.
+- **A wall can stop a frame from drawing what is behind it.** `Occluder` declares
+ a box sight does not pass through. Every camera rasterises the ones it can see
+ onto a small depth grid before collecting, and a renderable whose bounds are
+ behind that grid never becomes a draw. Nine cubes behind a wall and two beside
+ it: three draws with the component, twelve without, and the same four pixels
+ either way — an occluder changes what a frame COSTS and never what it shows.
+
+ The box is authored rather than taken from the geometry, and that is the design.
+ A mesh's bounds CONTAIN the mesh: a box around a pillar or a rock claims the air
+ at its corners, and whatever stands in that air would stop being drawn while the
+ player can plainly see it. Only whoever built the wall can say where the inside
+ of it is, so `halfExtents` is theirs to place — in world units, turned by the
+ entity, and drawn in the viewport like every other extent.
+
+ What it refuses is bounded on purpose. Only draws a depth test would have hidden
+ anyway, so sprites, UI and anything whose material turns depth off are never
+ taken away; only the camera's own collect, so a caster keeps casting into a
+ shadow map the player cannot see; and never a box the camera stands inside,
+ which would otherwise declare the whole view blocked. A scene that declares no
+ occluder — every 2D one — pays one comparison per renderable.
+
+ Two questions now have one answer. `RenderCollectContext::visible` asks "outside
+ the view" and "behind something solid" together; the mesh collect had been
+ testing the frustum itself and would have missed the second entirely. Three
+ counters say which is which: `render.cull.occluders` (boxes taken),
+ `render.cull.occluded` (renderables refused), `render.culled` (every cull).
+
+ Measuring it is what set its own resolution: read four grid texels a side rather
+ than two, because a level's texels align to the grid and not to the object, and
+ at two the region read overhangs by the object's own width — six of nine cubes
+ standing squarely behind a wall went uncalled.
+
- **Decals you can place.** Put a `DecalProjector` on an entity, point its box at
something, and Bake Decal cuts what it covers into a mesh on that same entity —
drawn with the decal's own material, won on depth by that material's bias. The
diff --git a/desktop b/desktop
index 31b8113f8..6207b2ec7 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 31b8113f8e9c6eceeb3875af6cde6affa69183ae
+Subproject commit 6207b2ec785ad763c05507b141bce3bf0e118e64
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index a4c87682d..0695addd9 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -323,6 +323,7 @@ export default defineConfig({
items: [
{ label: 'Profiling & Diagnostics', translations: { 'zh-CN': '性能剖析与诊断' }, slug: 'performance/profiling' },
{ label: 'Level of Detail', translations: { 'zh-CN': '细节层次(LOD)' }, slug: 'performance/level-of-detail' },
+ { label: 'Occlusion Culling', translations: { 'zh-CN': '遮挡剔除' }, slug: 'performance/occlusion-culling' },
],
},
{
diff --git a/docs/astro/src/content/docs/performance/occlusion-culling.mdx b/docs/astro/src/content/docs/performance/occlusion-culling.mdx
new file mode 100644
index 000000000..3549b7176
--- /dev/null
+++ b/docs/astro/src/content/docs/performance/occlusion-culling.mdx
@@ -0,0 +1,93 @@
+---
+title: Occlusion Culling
+description: Stop drawing what a wall already hides, with the Occluder component — where the box goes, what it must never claim, and how to read what it saved.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The frustum answers *is it in front of the camera*. Inside a building, a town or a
+canyon, most of what survives that question is still invisible: a wall is in the
+way. **`Occluder`** lets you say which boxes sight does not pass through, and the
+renderer then stops collecting anything standing behind one.
+
+```typescript
+world.insert(wall, Occluder, { halfExtents: { x: 400, y: 300, z: 20 } });
+```
+
+That is the whole component. It changes **what a frame costs and never what it
+shows** — the picture with occluders and the picture without them are the same
+pixels.
+
+## The box is authored, and it belongs inside the wall
+
+An occluder is not taken from the geometry beside it, and the reason is worth
+knowing: a mesh's bounds *contain* the mesh. A bounding box around a pillar, an
+archway or a rock claims the empty air at its corners, and anything standing in
+that air would stop being drawn while the player can plainly see it.
+
+So the rule is the opposite one:
+
+<Aside type="caution">
+**The box must lie inside the solid part of the geometry.** Too small only costs
+you some culling. Too big makes things vanish in front of the player — which no
+counter reports and no test catches.
+</Aside>
+
+Placing it:
+
+- `halfExtents` is in **world units**, measured from the entity's position, and
+ the entity's **rotation** turns it. Scale is not read, the same as every other
+ extent in the engine.
+- The editor draws the box in the viewport, so you can size it against the wall
+ it is inside of.
+- It can sit on the wall's own entity, or on an empty entity of its own — a
+ building made of many meshes usually wants one big box rather than one per mesh.
+
+## What it culls, and what it leaves alone
+
+Only draws a **depth test would have hidden anyway**. An object that ignores depth
+paints over the wall in front of it, and culling it would remove something the
+frame really does show — so sprites, UI, text and any surface whose material turns
+the depth test off are never refused by an occluder.
+
+It is also a **camera's** answer, not the scene's:
+
+- Two cameras in one frame each ask their own occluders.
+- **Shadows are not culled by it.** What the player cannot see still casts; a
+ caster dropped because the camera cannot see *it* would take its shadow off the
+ ground with it.
+- An occluder the camera stands **inside** is ignored, rather than declaring the
+ whole view blocked.
+
+## Reading what it did
+
+Three counters in the Profiler, and each answers a different question:
+
+| counter | says |
+|---|---|
+| `render.cull.occluders` | how many boxes this view **took** |
+| `render.cull.occluded` | how many renderables an occluder **refused** |
+| `render.culled` | every cull, the frustum's included |
+
+A scene whose occluders stopped working shows it in the first two: zero boxes
+means they were never taken (turned past the near plane, or authored to nothing),
+while boxes taken and nothing occluded means they are not in front of anything.
+
+## How much it can claim
+
+The test runs on a small grid — about a sixty-fourth of the view across — and a
+box only claims a cell of it that it covers **whole**. Two consequences worth
+designing around:
+
+- An occluder smaller than roughly 2% of the screen hides nothing. Big shapes
+ are what pay: walls, floors between storeys, buildings, cliffs.
+- An object that is hidden by the *combination* of two walls with a gap between
+ them is still drawn. Each box answers for itself.
+
+## What this is not
+
+`Occluder` is about **what is in the way**. It does not unload anything — see
+[streaming](/world/streaming/) for that — and it does not simplify what is drawn,
+which is [`LODGroup`](/performance/level-of-detail/). The three compose: streaming
+decides what exists, occlusion decides what is collected, LOD decides how much
+geometry the survivors cost.
diff --git a/docs/astro/src/content/docs/zh-cn/performance/occlusion-culling.mdx b/docs/astro/src/content/docs/zh-cn/performance/occlusion-culling.mdx
new file mode 100644
index 000000000..4f6bd9cb5
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/performance/occlusion-culling.mdx
@@ -0,0 +1,78 @@
+---
+title: 遮挡剔除
+description: 用 Occluder 组件让引擎不再绘制被墙挡住的东西 —— 盒子放在哪、它绝不能多claim什么、以及怎么读出它省下了多少。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+视锥回答的是**它在不在相机前面**。而在建筑内部、城镇或峡谷里,通过了这一问的东西大多
+仍然看不见:有一堵墙挡着。**`Occluder`** 让你说出哪些盒子是视线穿不过去的,渲染器
+随后就不再收集站在它后面的东西。
+
+```typescript
+world.insert(wall, Occluder, { halfExtents: { x: 400, y: 300, z: 20 } });
+```
+
+组件只有这些。它改变的是**一帧的代价,而绝不是它画出来的东西** —— 有遮挡体和没有
+遮挡体,两张图是同样的像素。
+
+## 盒子是创作出来的,而且它要在墙的里面
+
+遮挡体不从旁边的几何体推导出来,理由值得记住:网格的包围盒**包住**网格。柱子、拱门、
+石头的包围盒会把四角的空气也算进去,而站在那片空气里的东西就会在玩家明明看得见它的
+时候停止绘制。
+
+所以规则是反过来的:
+
+<Aside type="caution">
+**盒子必须落在几何体实心的那部分里面。** 小了只是少剔除一些;大了会让东西在玩家眼前
+凭空消失 —— 而这件事没有任何计数器会报告,也没有任何测试抓得到。
+</Aside>
+
+怎么摆:
+
+- `halfExtents` 是**世界单位**,从实体的位置量起,并随实体的**旋转**转动。缩放不读,
+ 和引擎里其它所有 extent 一致。
+- 编辑器会在视口里画出这个盒子,所以你可以对着它所在的那堵墙调大小。
+- 它可以挂在墙自己的实体上,也可以挂在一个空实体上 —— 由很多网格拼成的一栋楼,通常
+ 要的是一个大盒子,而不是每个网格一个。
+
+## 它剔什么,不剔什么
+
+只剔**深度测试本来也会挡掉的那些绘制**。一个不做深度测试的绘制会盖在它前面的墙上面,
+剔掉它就等于抹掉了这一帧真的画出来的东西 —— 所以精灵、UI、文本,以及材质关掉了深度
+测试的任何表面,都不会被遮挡体拒绝。
+
+它也是**某个相机**的答案,不是场景的答案:
+
+- 一帧里的两个相机各问各的遮挡体。
+- **阴影不被它剔除。** 玩家看不见的东西照样投影;因为相机看不见**它**就丢掉一个投影体,
+ 会把它在地上的影子一起带走。
+- 相机**站在里面**的遮挡体会被忽略,而不是宣布整个视野都被挡住了。
+
+## 怎么读它做了什么
+
+Profiler 里三个计数器,各回答一个不同的问题:
+
+| 计数器 | 说的是 |
+|---|---|
+| `render.cull.occluders` | 这个视图**采纳**了多少个盒子 |
+| `render.cull.occluded` | 遮挡体**拒绝**了多少个可渲染物 |
+| `render.culled` | 所有剔除,含视锥的那部分 |
+
+遮挡体失效时,前两个数会说出来:盒子数为零说明它们根本没被采纳(转到近平面后面去了,
+或者尺寸被编辑成了零);盒子采纳了而 occluded 为零,说明它们前面本来就没挡住什么。
+
+## 它能claim到多大
+
+这个判断跑在一张小网格上(横向约为视野的六十四分之一),而一个盒子只能claim它**整格
+盖满**的那些格子。有两条值得据此设计:
+
+- 小于屏幕约 2% 的遮挡体什么都挡不住。付得起的是大形体:墙、楼层之间的地板、建筑、崖壁。
+- 被两堵中间有缝的墙**合起来**挡住的物体,仍然会被绘制。每个盒子只为自己回答。
+
+## 它不做什么
+
+`Occluder` 说的是**什么挡在路上**。它不卸载任何东西 —— 那是[流送](/zh-cn/world/streaming/);
+它也不减少绘制的几何量 —— 那是 [`LODGroup`](/zh-cn/performance/level-of-detail/)。
+三者是可以叠加的:流送决定什么存在,遮挡决定什么被收集,LOD 决定活下来的那些花多少几何。
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index a0e3309c0..aa99dcf9f 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -85,6 +85,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
SpriteMask: { category: 'graphics', summary: "Turns this entity's Sprite into a stencil that cuts the sprites drawn after it — a window, or a hole.", doc: 'graphics/sprites', anchor: 'sprite-masks', anchorZh: '精灵遮罩' },
SortingGroup: { category: 'graphics', summary: 'Makes an entity and its whole subtree sort as one unit — the group states the layer and order, members state their place inside it.', doc: 'graphics/sprites', anchor: 'sorting-groups', anchorZh: '排序组' },
LODGroup: { category: 'graphics', summary: 'Cheaper stand-in meshes for a MeshRenderer, chosen by how much of the screen the object covers.', doc: 'performance/level-of-detail', anchor: 'the-lodgroup-component', anchorZh: 'lodgroup-组件' },
+ Occluder: { category: 'graphics', summary: 'A box sight does not pass through — what stands behind it is not collected, and the picture is unchanged.', doc: 'performance/occlusion-culling', anchor: 'the-box-is-authored-and-it-belongs-inside-the-wall', anchorZh: '盒子是创作出来的而且它要在墙的里面' },
Video: { category: 'graphics', summary: 'Plays a video stream onto a surface in the world or the UI.', doc: 'graphics/video', anchor: 'the-video-component', anchorZh: 'video-组件' },
// ── UI ─────────────────────────────────────────────────────────────────────
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index b9b6cbca8..bfb1f3ecc 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -2741,6 +2741,25 @@
"fields": [],
"tag": true
},
+ {
+ "name": "Occluder",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "halfExtents",
+ "type": "Vec3",
+ "default": "(50, 50, 50)",
+ "doc": "Half the solid box, in world units, from the entity's position.",
+ "range": "≥ 0"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true",
+ "doc": "Off: this box hides nothing."
+ }
+ ]
+ },
{
"name": "OneWayPlatform2D",
"source": "ts",
diff --git a/fixtures/scenes/occlusion-cost.esscene b/fixtures/scenes/occlusion-cost.esscene
new file mode 100644
index 000000000..699706828
--- /dev/null
+++ b/fixtures/scenes/occlusion-cost.esscene
@@ -0,0 +1,527 @@
+{
+ "version": 4,
+ "name": "OcclusionCost",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "fov": 60.0,
+ "nearPlane": 1,
+ "farPlane": 20000.0,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Wall",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": -200
+ },
+ "scale": {
+ "x": 1.5,
+ "y": 4.0,
+ "z": 0.1
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ },
+ {
+ "type": "Occluder",
+ "data": {
+ "halfExtents": {
+ "x": 75,
+ "y": 200,
+ "z": 5
+ },
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Behind1",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -150,
+ "y": 150,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Behind2",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 150,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Behind3",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 150,
+ "y": 150,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "Behind4",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -150,
+ "y": 0,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 6,
+ "name": "Behind5",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 7,
+ "name": "Behind6",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 150,
+ "y": 0,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 8,
+ "name": "Behind7",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -150,
+ "y": -150,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 9,
+ "name": "Behind8",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": -150,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 10,
+ "name": "Behind9",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 150,
+ "y": -150,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 11,
+ "name": "Beside1",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -290,
+ "y": 0,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 12,
+ "name": "Beside2",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 290,
+ "y": 0,
+ "z": -600
+ },
+ "scale": {
+ "x": 0.5,
+ "y": 0.5,
+ "z": 0.5
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ },
+ "lit": false,
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 7b49b8cc2..2e9443987 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,11 +1,11 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1827 experimental · 3 deprecated
+Symbols: 114 public · 95 beta · 1828 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"bfed6926d0e50843"
+"8ef437d46a35780d"
```
## ANCHOR_AXES — const @experimental
@@ -5886,6 +5886,17 @@ params: NodeParamSpec[]
(filter: FilterExpr): FilterExpr
```
+## Occluder — const @experimental
+```
+BuiltinComponentDef<OccluderData>
+```
+
+## OccluderData — interface @beta
+```
+enabled: boolean
+halfExtents: Vec3
+```
+
## OneWayPlatform2D — const @experimental
```
ComponentDef<OneWayPlatform2DData>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 27d1ba207..a54cf4188 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,11 +1,11 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 99 beta · 1846 experimental · 3 deprecated
+Symbols: 114 public · 100 beta · 1847 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"bfed6926d0e50843"
+"8ef437d46a35780d"
```
## ANCHOR_AXES — const @experimental
@@ -6064,6 +6064,17 @@ params: NodeParamSpec[]
(filter: FilterExpr): FilterExpr
```
+## Occluder — const @experimental
+```
+BuiltinComponentDef<OccluderData>
+```
+
+## OccluderData — interface @beta
+```
+enabled: boolean
+halfExtents: Vec3
+```
+
## OneWayPlatform2D — const @experimental
```
ComponentDef<OneWayPlatform2DData>
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 6a23120ad..76d6b437f 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 96 beta · 1826 experimental · 3 deprecated
+Symbols: 114 public · 97 beta · 1827 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5881,6 +5881,17 @@ params: NodeParamSpec[]
(filter: FilterExpr): FilterExpr
```
+## Occluder — const @experimental
+```
+BuiltinComponentDef<OccluderData>
+```
+
+## OccluderData — interface @beta
+```
+enabled: boolean
+halfExtents: Vec3
+```
+
## OneWayPlatform2D — const @experimental
```
ComponentDef<OneWayPlatform2DData>
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index be45934ea..409867e5e 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1848 experimental · 3 deprecated
+Symbols: 114 public · 95 beta · 1849 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6129,6 +6129,17 @@ params: NodeParamSpec[]
(filter: FilterExpr): FilterExpr
```
+## Occluder — const @experimental
+```
+BuiltinComponentDef<OccluderData>
+```
+
+## OccluderData — interface @beta
+```
+enabled: boolean
+halfExtents: Vec3
+```
+
## OneWayPlatform2D — const @experimental
```
ComponentDef<OneWayPlatform2DData>
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index c6d7fb0be..56aa1cf16 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -36,6 +36,7 @@ addMeshLightmap: (entity: Entity, component: MeshLightmap) => void
addMeshMorph: (entity: Entity, component: MeshMorph) => void
addMeshRenderer: (entity: Entity, component: MeshRenderer) => void
addMeshSkin: (entity: Entity, component: MeshSkin) => void
+addOccluder: (entity: Entity, component: Occluder) => void
addParent: (entity: Entity, component: Parent) => void
addParticleEmitter: (entity: Entity, component: ParticleEmitter) => void
addParticleForceField: (entity: Entity, component: ParticleForceField) => void
@@ -85,6 +86,7 @@ getMeshLightmap: (entity: Entity) => MeshLightmap
getMeshMorph: (entity: Entity) => MeshMorph
getMeshRenderer: (entity: Entity) => MeshRenderer
getMeshSkin: (entity: Entity) => MeshSkin
+getOccluder: (entity: Entity) => Occluder
getParent: (entity: Entity) => Parent
getParticleEmitter: (entity: Entity) => ParticleEmitter
getParticleForceField: (entity: Entity) => ParticleForceField
@@ -130,6 +132,7 @@ hasMeshLightmap: (entity: Entity) => boolean
hasMeshMorph: (entity: Entity) => boolean
hasMeshRenderer: (entity: Entity) => boolean
hasMeshSkin: (entity: Entity) => boolean
+hasOccluder: (entity: Entity) => boolean
hasParent: (entity: Entity) => boolean
hasParticleEmitter: (entity: Entity) => boolean
hasParticleForceField: (entity: Entity) => boolean
@@ -176,6 +179,7 @@ removeMeshLightmap: (entity: Entity) => void
removeMeshMorph: (entity: Entity) => void
removeMeshRenderer: (entity: Entity) => void
removeMeshSkin: (entity: Entity) => void
+removeOccluder: (entity: Entity) => void
removeParent: (entity: Entity) => void
removeParticleEmitter: (entity: Entity) => void
removeParticleForceField: (entity: Entity) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 869769d4e..fb2c6aaac 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1838 experimental · 3 deprecated
+Symbols: 114 public · 95 beta · 1839 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5888,6 +5888,17 @@ params: NodeParamSpec[]
(filter: FilterExpr): FilterExpr
```
+## Occluder — const @experimental
+```
+BuiltinComponentDef<OccluderData>
+```
+
+## OccluderData — interface @beta
+```
+enabled: boolean
+halfExtents: Vec3
+```
+
## OneWayPlatform2D — const @experimental
```
ComponentDef<OneWayPlatform2DData>
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 90e813e46..0c0ed705f 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -97,6 +97,8 @@ export {
ShadowCaster2D,
LightProbeVolume,
type LightProbeVolumeData,
+ Occluder,
+ type OccluderData,
SortingGroup,
SpriteMask,
TrailRenderer,
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 02ed88f70..a3a83d0c5 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -1065,6 +1065,34 @@ export function createMeshRendererData(): MeshRendererPtrData {
};
}
+export interface OccluderPtrData {
+ halfExtents: Vec3;
+ enabled: boolean;
+}
+
+export function fillOccluder(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, out: OccluderPtrData,
+): void {
+ const halfExtents_ = out.halfExtents; halfExtents_.x = f32[ptr >> 2]; halfExtents_.y = f32[(ptr >> 2) + 1]; halfExtents_.z = f32[(ptr >> 2) + 2];
+ out.enabled = u8[ptr + 12] !== 0;
+}
+
+export function writeOccluder(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, data: OccluderPtrData,
+): void {
+ f32[ptr >> 2] = data.halfExtents.x; f32[(ptr >> 2) + 1] = data.halfExtents.y; f32[(ptr >> 2) + 2] = data.halfExtents.z;
+ u8[ptr + 12] = data.enabled ? 1 : 0;
+}
+
+export function createOccluderData(): OccluderPtrData {
+ return {
+ halfExtents: { x: 0, y: 0, z: 0 },
+ enabled: false,
+ };
+}
+
export interface ParticleEmitterPtrData {
rate: number;
burstCount: number;
@@ -2392,6 +2420,7 @@ export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {
MeshCollider3D: { fill: fillMeshCollider3D, write: writeMeshCollider3D, create: createMeshCollider3DData },
MeshLightmap: { fill: fillMeshLightmap, write: writeMeshLightmap, create: createMeshLightmapData },
MeshRenderer: { fill: fillMeshRenderer, write: writeMeshRenderer, create: createMeshRendererData },
+ Occluder: { fill: fillOccluder, write: writeOccluder, create: createOccluderData },
ParticleEmitter: { fill: fillParticleEmitter, write: writeParticleEmitter, create: createParticleEmitterData },
ParticleForceField: { fill: fillParticleForceField, write: writeParticleForceField, create: createParticleForceFieldData },
RigidBody2D: { fill: fillRigidBody2D, write: writeRigidBody2D, create: createRigidBody2DData },
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index be03f9bf8..6ab9edf91 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = 'bfed6926d0e50843';
+export const ABI_LAYOUT_HASH = '8ef437d46a35780d';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -612,6 +612,20 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
joints: { tooltip: "Joint entities, in the order the mesh's bind matrices are in." },
},
},
+ Occluder: {
+ defaults: {
+ halfExtents: { x: 50, y: 50, z: 50 },
+ enabled: true,
+ },
+ assetFields: [],
+ entityFields: [],
+ colorFields: [],
+ animatableFields: [],
+ fields: {
+ halfExtents: { min: 0, tooltip: "Half the solid box, in world units, from the entity's position." },
+ enabled: { tooltip: "Off: this box hides nothing." },
+ },
+ },
Parent: {
defaults: {
entity: 0,
@@ -1463,6 +1477,17 @@ export interface MeshSkinData {
joints: Entity[];
}
+/**
+ * The fields of the engine's `Occluder` component, generated from
+ * the C++ struct so the two shapes cannot drift.
+ *
+ * @beta
+ */
+export interface OccluderData {
+ halfExtents: Vec3;
+ enabled: boolean;
+}
+
/**
* The fields of the engine's `Parent` component, generated from
* the C++ struct so the two shapes cannot drift.
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index 2700bdad1..10c5ec3f3 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -15,7 +15,7 @@ export type { AssetFieldMeta, SkeletalFieldMeta };
// extending the generated base.
import type {
TransformData, SpriteData, ShapeRendererData, LightData, ShadowCaster2DData, DraggableData,
- SortingGroupData, SpriteMaskData, LightProbeVolumeData,
+ SortingGroupData, SpriteMaskData, LightProbeVolumeData, OccluderData,
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData, DragonBonesAnimationData,
TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData,
CameraData as CameraDataCpp, ParticleEmitterData as ParticleEmitterDataCpp,
@@ -805,7 +805,7 @@ export type ScaleMode = (typeof ScaleMode)[keyof typeof ScaleMode];
// automatically; tsc then enforces every consumer matches.
export type {
TransformData, SpriteData, ShapeRendererData, LightData, ShadowCaster2DData, DraggableData,
- SortingGroupData, SpriteMaskData, LightProbeVolumeData,
+ SortingGroupData, SpriteMaskData, LightProbeVolumeData, OccluderData,
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData, DragonBonesAnimationData,
TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData,
};
@@ -928,6 +928,18 @@ export const LightProbeVolume = defineBuiltin<LightProbeVolumeData>('LightProbeV
metaDefaults<LightProbeVolumeData>('LightProbeVolume')
);
+/**
+ * A box sight does not pass through: what stands behind it is not collected, and
+ * the picture is unchanged. Authored, not taken from the geometry beside it — the
+ * box has to lie INSIDE the wall, and bounds that contain a mesh claim the air at
+ * its corners, where things would stop being drawn in front of the player.
+ *
+ * @experimental
+ */
+export const Occluder = defineBuiltin<OccluderData>('Occluder',
+ metaDefaults<OccluderData>('Occluder')
+);
+
/**
* Turns this entity's `Sprite` into a stencil: the sprites drawn AFTER it that ask to be
* masked (`Sprite.maskInteraction`) are cut by its shape. The mask's own sprite is not
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 9e46ea124..949406517 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -291,6 +291,13 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'mesh', type: 'u32', offset: 48 },
],
},
+ Occluder: {
+ ptrFn: 'getOccluderPtr',
+ fields: [
+ { name: 'halfExtents', type: 'vec3', offset: 0 },
+ { name: 'enabled', type: 'bool', offset: 12 },
+ ],
+ },
ParticleEmitter: {
ptrFn: 'getParticleEmitterPtr',
fields: [
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index fe8281fc4..c8a634189 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -613,6 +613,11 @@ export interface MeshSkin {
joints: VectorEntity;
}
+export interface Occluder {
+ halfExtents: Vec3;
+ enabled: boolean;
+}
+
export interface Parent {
entity: number;
}
@@ -1004,6 +1009,10 @@ export interface Registry {
getMeshSkin(entity: Entity): MeshSkin;
addMeshSkin(entity: Entity, component: MeshSkin): void;
removeMeshSkin(entity: Entity): void;
+ hasOccluder(entity: Entity): boolean;
+ getOccluder(entity: Entity): Occluder;
+ addOccluder(entity: Entity, component: Occluder): void;
+ removeOccluder(entity: Entity): void;
hasParent(entity: Entity): boolean;
getParent(entity: Entity): Parent;
addParent(entity: Entity, component: Parent): void;
@@ -1129,6 +1138,7 @@ export interface ESEngineModule {
MeshMorph: new () => MeshMorph;
MeshRenderer: new () => MeshRenderer;
MeshSkin: new () => MeshSkin;
+ Occluder: new () => Occluder;
Parent: new () => Parent;
ParticleEmitter: new () => ParticleEmitter;
ParticleForceField: new () => ParticleForceField;
diff --git a/src/esengine/aot/AotComponents.generated.cpp b/src/esengine/aot/AotComponents.generated.cpp
index 2105192ec..4d7df4c8b 100644
--- a/src/esengine/aot/AotComponents.generated.cpp
+++ b/src/esengine/aot/AotComponents.generated.cpp
@@ -22,6 +22,7 @@
#include "esengine/ecs/components/LODGroup.hpp"
#include "esengine/ecs/components/Light.hpp"
#include "esengine/ecs/components/MeshRenderer.hpp"
+#include "esengine/ecs/components/Occluder.hpp"
#include "esengine/ecs/components/ParticleEmitter.hpp"
#include "esengine/ecs/components/ParticleForceField.hpp"
#include "esengine/ecs/components/RigidBody2D.hpp"
@@ -177,6 +178,11 @@ ComponentAt engineComponentAt(ecs::Registry& registry, const char* name) {
return registry.tryGet<esengine::ecs::MeshSkin>(Entity::fromRaw(raw));
};
}
+ if (std::strcmp(name, "Occluder") == 0) {
+ return [&registry](std::uint32_t raw) -> void* {
+ return registry.tryGet<esengine::ecs::Occluder>(Entity::fromRaw(raw));
+ };
+ }
if (std::strcmp(name, "Parent") == 0) {
return [&registry](std::uint32_t raw) -> void* {
return registry.tryGet<esengine::ecs::Parent>(Entity::fromRaw(raw));
@@ -406,6 +412,11 @@ CandidatesOf engineComponentCandidates(ecs::Registry& registry, const char* name
return denseAsIds(registry.entitiesWith<esengine::ecs::MeshSkin>());
};
}
+ if (std::strcmp(name, "Occluder") == 0) {
+ return [&registry]() -> Candidates {
+ return denseAsIds(registry.entitiesWith<esengine::ecs::Occluder>());
+ };
+ }
if (std::strcmp(name, "Parent") == 0) {
return [&registry]() -> Candidates {
return denseAsIds(registry.entitiesWith<esengine::ecs::Parent>());
@@ -543,6 +554,7 @@ bool isEngineComponent(const char* name) {
if (std::strcmp(name, "MeshMorph") == 0) return true;
if (std::strcmp(name, "MeshRenderer") == 0) return true;
if (std::strcmp(name, "MeshSkin") == 0) return true;
+ if (std::strcmp(name, "Occluder") == 0) return true;
if (std::strcmp(name, "Parent") == 0) return true;
if (std::strcmp(name, "ParticleEmitter") == 0) return true;
if (std::strcmp(name, "ParticleForceField") == 0) return true;
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 89b6b99a5..287310b4b 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash b834e9c6d6843ea7
+ * @schema_hash 9eb680d3a8c6f4f8
*/
-#define ES_EDITOR_API_SCHEMA_HASH "b834e9c6d6843ea7"
+#define ES_EDITOR_API_SCHEMA_HASH "9eb680d3a8c6f4f8"
#include <emscripten/bind.h>
#include <string>
@@ -25,6 +25,7 @@
#include "../ecs/components/LODGroup.hpp"
#include "../ecs/components/Light.hpp"
#include "../ecs/components/MeshRenderer.hpp"
+#include "../ecs/components/Occluder.hpp"
#include "../ecs/components/ParticleEmitter.hpp"
#include "../ecs/components/ParticleForceField.hpp"
#include "../ecs/components/RigidBody2D.hpp"
@@ -87,6 +88,7 @@ std::vector<std::string> editor_getComponentNames() {
"MeshMorph",
"MeshRenderer",
"MeshSkin",
+ "Occluder",
"Parent",
"ParticleEmitter",
"ParticleForceField",
@@ -400,6 +402,13 @@ std::string editor_getComponentSchema(const std::string& name) {
return R"JSON([
{"key":"joints","type":"entity","group":"MeshSkin"}
])JSON";
+ } else if (name == "Occluder") {
+ return R"JSON([
+ {"key":"halfExtents.x","type":"float","group":"Occluder"},
+ {"key":"halfExtents.y","type":"float","group":"Occluder"},
+ {"key":"halfExtents.z","type":"float","group":"Occluder"},
+ {"key":"enabled","type":"bool","group":"Occluder"}
+ ])JSON";
} else if (name == "Parent") {
return R"JSON([
{"key":"entity","type":"entity","group":"Parent"}
@@ -844,6 +853,9 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {
} else if (name == "MeshSkin") {
if (!reg.has<esengine::ecs::MeshSkin>(entity)) reg.emplace<esengine::ecs::MeshSkin>(entity);
return true;
+ } else if (name == "Occluder") {
+ if (!reg.has<esengine::ecs::Occluder>(entity)) reg.emplace<esengine::ecs::Occluder>(entity);
+ return true;
} else if (name == "Parent") {
return false;
} else if (name == "ParticleEmitter") {
@@ -966,6 +978,8 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {
if (reg.has<esengine::ecs::MeshRenderer>(entity)) { reg.remove<esengine::ecs::MeshRenderer>(entity); return true; }
} else if (name == "MeshSkin") {
if (reg.has<esengine::ecs::MeshSkin>(entity)) { reg.remove<esengine::ecs::MeshSkin>(entity); return true; }
+ } else if (name == "Occluder") {
+ if (reg.has<esengine::ecs::Occluder>(entity)) { reg.remove<esengine::ecs::Occluder>(entity); return true; }
} else if (name == "Parent") {
if (reg.has<esengine::ecs::Parent>(entity)) { esengine::ecs::setParent(reg, entity, INVALID_ENTITY); return true; }
} else if (name == "ParticleEmitter") {
@@ -1040,6 +1054,7 @@ bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {
if (name == "MeshMorph") return reg.has<esengine::ecs::MeshMorph>(entity);
if (name == "MeshRenderer") return reg.has<esengine::ecs::MeshRenderer>(entity);
if (name == "MeshSkin") return reg.has<esengine::ecs::MeshSkin>(entity);
+ if (name == "Occluder") return reg.has<esengine::ecs::Occluder>(entity);
if (name == "Parent") return reg.has<esengine::ecs::Parent>(entity);
if (name == "ParticleEmitter") return reg.has<esengine::ecs::ParticleEmitter>(entity);
if (name == "ParticleForceField") return reg.has<esengine::ecs::ParticleForceField>(entity);
@@ -1094,6 +1109,7 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {
if (reg.has<esengine::ecs::MeshMorph>(entity)) result.push_back("MeshMorph");
if (reg.has<esengine::ecs::MeshRenderer>(entity)) result.push_back("MeshRenderer");
if (reg.has<esengine::ecs::MeshSkin>(entity)) result.push_back("MeshSkin");
+ if (reg.has<esengine::ecs::Occluder>(entity)) result.push_back("Occluder");
if (reg.has<esengine::ecs::Parent>(entity)) result.push_back("Parent");
if (reg.has<esengine::ecs::ParticleEmitter>(entity)) result.push_back("ParticleEmitter");
if (reg.has<esengine::ecs::ParticleForceField>(entity)) result.push_back("ParticleForceField");
@@ -1346,6 +1362,14 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "parallax.y") { c.parallax.y = value; }
else { return false; }
return true;
+ } else if (comp == "Occluder") {
+ if (!reg.has<esengine::ecs::Occluder>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Occluder>(entity);
+ if (field == "halfExtents.x") { c.halfExtents.x = value; }
+ else if (field == "halfExtents.y") { c.halfExtents.y = value; }
+ else if (field == "halfExtents.z") { c.halfExtents.z = value; }
+ else { return false; }
+ return true;
} else if (comp == "ParticleEmitter") {
if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;
auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
@@ -1840,6 +1864,12 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "color.a") { return c.color.a; }
else if (field == "parallax.x") { return c.parallax.x; }
else if (field == "parallax.y") { return c.parallax.y; }
+ } else if (comp == "Occluder") {
+ if (!reg.has<esengine::ecs::Occluder>(entity)) return 0.0f;
+ const auto& c = reg.get<esengine::ecs::Occluder>(entity);
+ if (field == "halfExtents.x") { return c.halfExtents.x; }
+ else if (field == "halfExtents.y") { return c.halfExtents.y; }
+ else if (field == "halfExtents.z") { return c.halfExtents.z; }
} else if (comp == "ParticleEmitter") {
if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
@@ -2702,6 +2732,12 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "enabled") { c.enabled = value; }
else { return false; }
return true;
+ } else if (comp == "Occluder") {
+ if (!reg.has<esengine::ecs::Occluder>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Occluder>(entity);
+ if (field == "enabled") { c.enabled = value; }
+ else { return false; }
+ return true;
} else if (comp == "ParticleEmitter") {
if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;
auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
@@ -2937,6 +2973,10 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "cullBackfaces") { return c.cullBackfaces; }
else if (field == "lit") { return c.lit; }
else if (field == "enabled") { return c.enabled; }
+ } else if (comp == "Occluder") {
+ if (!reg.has<esengine::ecs::Occluder>(entity)) return false;
+ const auto& c = reg.get<esengine::ecs::Occluder>(entity);
+ if (field == "enabled") { return c.enabled; }
} else if (comp == "ParticleEmitter") {
if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;
const auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 0f1e6d134..5b8f25003 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -25,6 +25,7 @@
#include "../ecs/components/LODGroup.hpp"
#include "../ecs/components/Light.hpp"
#include "../ecs/components/MeshRenderer.hpp"
+#include "../ecs/components/Occluder.hpp"
#include "../ecs/components/ParticleEmitter.hpp"
#include "../ecs/components/ParticleForceField.hpp"
#include "../ecs/components/RigidBody2D.hpp"
@@ -1723,6 +1724,10 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
value_object<MeshSkinJS>("MeshSkin")
.field("joints", &MeshSkinJS::joints);
+ value_object<esengine::ecs::Occluder>("Occluder")
+ .field("halfExtents", &esengine::ecs::Occluder::halfExtents)
+ .field("enabled", &esengine::ecs::Occluder::enabled);
+
value_object<ParentJS>("Parent")
.field("entity", &ParentJS::entity);
@@ -2536,6 +2541,27 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
r.remove<esengine::ecs::MeshSkin>(entity);
}))
+ // Occluder
+ .function("hasOccluder", optional_override([](Registry& r, u32 e) {
+ return r.has<esengine::ecs::Occluder>(static_cast<Entity>(e));
+ }))
+ .function("getOccluder", optional_override([](Registry& r, u32 e) -> esengine::ecs::Occluder& {
+ auto entity = static_cast<Entity>(e);
+ static esengine::ecs::Occluder s_dummy{};
+ if (!r.valid(entity) || !r.has<esengine::ecs::Occluder>(entity)) return s_dummy;
+ return r.get<esengine::ecs::Occluder>(entity);
+ }), allow_raw_pointers())
+ .function("addOccluder", optional_override([](Registry& r, u32 e, const esengine::ecs::Occluder& c) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity)) return;
+ r.emplaceOrReplace<esengine::ecs::Occluder>(entity, c);
+ }))
+ .function("removeOccluder", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::Occluder>(entity)) return;
+ r.remove<esengine::ecs::Occluder>(entity);
+ }))
+
// Parent
.function("hasParent", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::Parent>(static_cast<Entity>(e));
@@ -3071,6 +3097,7 @@ emscripten::val esengineGetBuiltinComponentNames() {
arr.set(i++, val(std::string("MeshMorph")));
arr.set(i++, val(std::string("MeshRenderer")));
arr.set(i++, val(std::string("MeshSkin")));
+ arr.set(i++, val(std::string("Occluder")));
arr.set(i++, val(std::string("Parent")));
arr.set(i++, val(std::string("ParticleEmitter")));
arr.set(i++, val(std::string("ParticleForceField")));
@@ -3271,6 +3298,8 @@ static_assert(offsetof(esengine::ecs::MeshRenderer, parallax) == 32, "ABI offset
static_assert(offsetof(esengine::ecs::MeshRenderer, material) == 40, "ABI offset drift: esengine::ecs::MeshRenderer.material (EHT expected 40)");
static_assert(offsetof(esengine::ecs::MeshRenderer, enabled) == 44, "ABI offset drift: esengine::ecs::MeshRenderer.enabled (EHT expected 44)");
static_assert(offsetof(esengine::ecs::MeshRenderer, mesh) == 48, "ABI offset drift: esengine::ecs::MeshRenderer.mesh (EHT expected 48)");
+static_assert(offsetof(esengine::ecs::Occluder, halfExtents) == 0, "ABI offset drift: esengine::ecs::Occluder.halfExtents (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Occluder, enabled) == 12, "ABI offset drift: esengine::ecs::Occluder.enabled (EHT expected 12)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, rate) == 0, "ABI offset drift: esengine::ecs::ParticleEmitter.rate (EHT expected 0)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, burstCount) == 4, "ABI offset drift: esengine::ecs::ParticleEmitter.burstCount (EHT expected 4)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, burstInterval) == 8, "ABI offset drift: esengine::ecs::ParticleEmitter.burstInterval (EHT expected 8)");
@@ -3497,7 +3526,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "bfed6926d0e50843";
+static const char* kEsAbiLayoutHash = "8ef437d46a35780d";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/Occluder.hpp b/src/esengine/ecs/components/Occluder.hpp
new file mode 100644
index 000000000..a07d4eeb8
--- /dev/null
+++ b/src/esengine/ecs/components/Occluder.hpp
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Occluder.hpp
+ * @brief A box sight does not pass through, so what stands behind it is not drawn.
+ * ShadowCaster2D answers where LIGHT stops; this answers where sight does.
+ *
+ * @author ESEngine Team
+ * @date 2026
+ *
+ * @copyright Copyright (c) 2026 ESEngine Team
+ * Licensed under the Apache License, Version 2.0.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "../../core/Reflection.hpp"
+
+#include <glm/glm.hpp>
+
+namespace esengine::ecs {
+
+/**
+ * @brief Declares a solid box a camera cannot see through.
+ *
+ * @details AUTHORED, not taken from the geometry: bounds CONTAIN a mesh, and a box
+ * claiming more than the surface fills makes things vanish in front of the
+ * player. World units about the entity, turned by its rotation; scale is
+ * not read — what every other extent here does, and what the gizmo draws.
+ */
+ES_COMPONENT(stability=beta)
+struct Occluder {
+ /** @brief Half the box, in world units, from the entity's position. The
+ * default fills an unscaled builtin cube exactly. */
+ ES_PROPERTY(min=0, tooltip="Half the solid box, in world units, from the entity's position.")
+ glm::vec3 halfExtents{50.0f, 50.0f, 50.0f};
+
+ /** @brief Disabled occluders hide nothing, which is what every scene without
+ * one gets: the test costs a comparison and no object is ever refused. */
+ ES_PROPERTY(tooltip="Off: this box hides nothing.")
+ bool enabled{true};
+
+ Occluder() = default;
+};
+
+} // namespace esengine::ecs
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index 8453e3943..0b5348863 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -5,6 +5,7 @@
#include "../core/Types.hpp"
#include "./frame/RenderStage.hpp"
#include "./frame/Frustum.hpp"
+#include "./frame/OcclusionView.hpp"
#include "./lod/LodSelection.hpp"
#include "./lod/LodViewState.hpp"
#include "./frame/FrameConstants.hpp"
@@ -231,6 +232,13 @@ struct RenderCollectContext {
*/
const std::unordered_set<u32>* screen_ui = nullptr;
+ /**
+ * @brief What this view is already blocked by, or null for a collect that
+ * must not ask — a shadow face looks from a light, and a camera's
+ * answer about what a camera cannot see says nothing about it.
+ */
+ const OcclusionView* occlusion = nullptr;
+
/** @brief Whether this collect is the frame's screen overlay. */
bool isOverlay() const { return frame_context.purpose == RenderPurpose::ScreenOverlay; }
@@ -247,15 +255,23 @@ struct RenderCollectContext {
}
/**
- * @brief Whether a renderable bounded by @p centre / @p halfExtents survives
- * this collect's cull.
+ * @brief Whether a renderable bounded by @p centre / @p halfExtents is drawn.
*
- * @details The overlay has no camera to be outside of: a screen element is on
- * the screen by construction, and a frustum test would ask about
- * wherever something else happens to be looking.
+ * @details TWO questions, one answer: outside the view, and inside it behind
+ * something solid. @p depthTested admits the second — an occluder may
+ * refuse only a draw a DEPTH TEST would have hidden anyway, since one
+ * that ignores depth paints over the wall and really is seen.
*/
- bool visible(const glm::vec3& centre, const glm::vec3& halfExtents) const {
- return isOverlay() || frustum.intersectsAABB(centre, halfExtents);
+ bool visible(const glm::vec3& centre, const glm::vec3& halfExtents, bool depthTested) {
+ // A screen element is on the screen by construction, with no camera to be
+ // outside of — a frustum test would ask about wherever one is looking.
+ if (isOverlay()) return true;
+ if (!frustum.intersectsAABB(centre, halfExtents)) return false;
+ if (depthTested && occlusion && occlusion->hidden(centre, halfExtents)) {
+ ++occluded;
+ return false;
+ }
+ return true;
}
/**
@@ -279,6 +295,16 @@ struct RenderCollectContext {
*/
u32 culled = 0;
+ /**
+ * @brief How many of those @ref culled an OCCLUDER refused.
+ *
+ * @details A subset, not a second total: the plugin counts the cull where it
+ * happens and this says which question rejected it. One number for
+ * both cannot tell an occluder that stopped working from a camera
+ * that turned away.
+ */
+ u32 occluded = 0;
+
/**
* @brief Which view is looking, where its level choices are kept, and where
* the selections it makes are counted.
diff --git a/src/esengine/renderer/frame/OcclusionView.hpp b/src/esengine/renderer/frame/OcclusionView.hpp
new file mode 100644
index 000000000..6511dd5f7
--- /dev/null
+++ b/src/esengine/renderer/frame/OcclusionView.hpp
@@ -0,0 +1,340 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file OcclusionView.hpp
+ * @brief What this view already has something solid in front of.
+ *
+ * @details The other half of the cull, beside Frustum: one says what is outside
+ * the view, this says what is inside it and hidden. Both are asked
+ * through one predicate (RenderCollectContext::visible) so a renderable
+ * cannot be judged by one of them and not the other.
+ *
+ * A DEPTH GRID, not a query: the collect may not touch the device
+ * (RenderFrame's first invariant), and a GPU occlusion query answers a
+ * frame late through a readback the WebGL2 path would stall on. Solid
+ * boxes an author declared are rasterised onto a small grid here, and
+ * every bound is tested against it before it becomes a draw.
+ *
+ * Conservative in one direction ON PURPOSE. Claiming too little costs
+ * draws that were already being paid; claiming too much makes objects
+ * vanish in front of the player, which no counter shows and no gate
+ * catches. Everything below rounds towards drawing: only texels a face
+ * covers WHOLE take a depth, that depth is the face's farthest point
+ * over the texel, and a box that reaches behind the eye is dropped
+ * rather than approximated.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+
+#include <glm/glm.hpp>
+#include <glm/gtc/quaternion.hpp>
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <limits>
+
+namespace esengine {
+
+/**
+ * @brief The depths this view is blocked at, and the test a bound asks it.
+ *
+ * @details `begin`, an `addBox` per declared occluder, `finish`, then `hidden`
+ * until the next `begin`. The stored view-projection serves both halves:
+ * a tester holding its own copy is how a raster and a test come to
+ * disagree about where something is.
+ */
+class OcclusionView {
+public:
+ /** @brief Grid resolution of the coarsest useful answer. A texel is ~1.5% of
+ * the screen, which is what an occluder must exceed to hide anything;
+ * finer costs the rasterisation, which is the only cost here. */
+ static constexpr u32 kSize = 64;
+ /** @brief 64, 32, 16, 8, 4, 2, 1 — down to one texel, so an object covering
+ * the whole screen still takes a bounded number of reads. */
+ static constexpr u32 kLevels = 7;
+
+ /** @brief Texels a side a bound is tested over: sixteen reads, whatever its
+ * size on screen. */
+ static constexpr u32 kTestSpan = 4;
+
+ /** @brief Depth of a texel nothing covers: no bound is ever farther. */
+ static constexpr f32 kOpen = std::numeric_limits<f32>::infinity();
+
+ /** @brief Smallest clip w a corner may have. Anything at or behind the eye
+ * plane makes the projection meaningless, and the cases that reach
+ * it — the eye inside the box, the box across the near plane — are
+ * exactly the ones a conservative answer must refuse. */
+ static constexpr f32 kMinW = 1e-4f;
+
+ /** @brief Opens a view looking through @p viewProjection. Nothing is blocked
+ * until a box is taken, which is what a scene declaring no occluder
+ * (every 2D one) pays: one comparison per renderable. */
+ void begin(const glm::mat4& viewProjection) {
+ view_projection_ = viewProjection;
+ boxes_ = 0;
+ }
+
+ /**
+ * @brief Takes one solid box — @p half world half-extents about @p centre,
+ * turned by @p rotation — as something sight does not pass through.
+ *
+ * @return Whether it was taken. A refusal is not an error: a box reaching
+ * behind the eye plane is dropped whole rather than clipped, because
+ * everything this class may get wrong must be got wrong towards
+ * drawing.
+ */
+ bool addBox(const glm::vec3& centre, const glm::quat& rotation, const glm::vec3& half) {
+ glm::vec3 corners[8];
+ if (!projectBox(centre, rotation, half, corners)) return false;
+
+ // Grid coordinates, where a texel is one unit and its centre a half — the
+ // edge bias and the depth slope below are both read in texels, and two
+ // spaces would put the rounding in one of them only.
+ glm::vec2 lo(static_cast<f32>(kSize)), hi(0.0f);
+ for (const glm::vec3& c : corners) {
+ lo = glm::min(lo, glm::vec2(c));
+ hi = glm::max(hi, glm::vec2(c));
+ }
+ // The texels the silhouette TOUCHES, both ends floored: a rectangle that
+ // rounded one end up would hand the coverage test a texel the box never
+ // reaches, and the test and the scan must agree on which texels exist.
+ const i32 x0 = std::max(0, static_cast<i32>(std::floor(lo.x)));
+ const i32 y0 = std::max(0, static_cast<i32>(std::floor(lo.y)));
+ const i32 x1 = std::min(static_cast<i32>(kSize) - 1, static_cast<i32>(std::floor(hi.x)));
+ const i32 y1 = std::min(static_cast<i32>(kSize) - 1, static_cast<i32>(std::floor(hi.y)));
+ // Off screen entirely: what is outside the view hides nothing inside it,
+ // and the frustum has already answered for anything out there.
+ if (x1 < x0 || y1 < y0) return false;
+
+ Face faces[6];
+ u32 faceCount = 0;
+ for (const auto& quad : kFaces) {
+ Face face;
+ if (buildFace(corners, quad, face)) faces[faceCount++] = face;
+ }
+ // Every face edge-on at once means a box with no thickness on screen.
+ if (faceCount == 0) return false;
+
+ if (boxes_ == 0) base_.fill(kOpen);
+ ++boxes_;
+
+ for (i32 y = y0; y <= y1; ++y) {
+ for (i32 x = x0; x <= x1; ++x) {
+ const glm::vec2 p(static_cast<f32>(x) + 0.5f, static_cast<f32>(y) + 0.5f);
+ f32 blocked = kOpen;
+ for (u32 f = 0; f < faceCount; ++f) {
+ const Face& face = faces[f];
+ if (!face.covers(p)) continue;
+ // The face's FARTHEST depth over the whole texel, not its depth
+ // at the centre: the claim a texel makes is about every point in
+ // it, and half a texel of slope is what separates the two.
+ blocked = std::min(blocked, face.maxDepthOver(p));
+ }
+ if (blocked < kOpen) {
+ f32& cell = base_[static_cast<usize>(y) * kSize + static_cast<usize>(x)];
+ // Nearest wins: whatever is in front blocks most, and which box
+ // it came from cannot change the answer — so the order the
+ // registry hands them over in cannot either.
+ cell = std::min(cell, blocked);
+ }
+ }
+ }
+ return true;
+ }
+
+ /** @brief Closes the view: reduces the grid by MAXIMUM into a pyramid, so a
+ * bound of any size on screen costs four reads rather than its area.
+ * A coarse texel answers for a whole region, and taking the farthest
+ * of them is what keeps a region that is only partly blocked drawn. */
+ void finish() {
+ if (boxes_ == 0) return;
+ for (u32 level = 1; level < kLevels; ++level) {
+ const u32 size = kSize >> level;
+ const u32 src = kSize >> (level - 1);
+ f32* out = levelData(level);
+ const f32* in = levelData(level - 1);
+ for (u32 y = 0; y < size; ++y) {
+ for (u32 x = 0; x < size; ++x) {
+ const f32 a = in[(2 * y) * src + 2 * x];
+ const f32 b = in[(2 * y) * src + 2 * x + 1];
+ const f32 c = in[(2 * y + 1) * src + 2 * x];
+ const f32 d = in[(2 * y + 1) * src + 2 * x + 1];
+ out[y * size + x] = std::max(std::max(a, b), std::max(c, d));
+ }
+ }
+ }
+ }
+
+ /** @brief Whether nothing of a box bounded by @p centre / @p half can be seen,
+ * because every texel it covers is blocked nearer than its nearest point. */
+ bool hidden(const glm::vec3& centre, const glm::vec3& half) const {
+ if (boxes_ == 0) return false;
+
+ glm::vec3 corners[8];
+ if (!projectBox(centre, glm::quat(1.0f, 0.0f, 0.0f, 0.0f), half, corners)) return false;
+
+ glm::vec2 lo(static_cast<f32>(kSize)), hi(0.0f);
+ f32 nearest = kOpen;
+ for (const glm::vec3& c : corners) {
+ lo = glm::min(lo, glm::vec2(c));
+ hi = glm::max(hi, glm::vec2(c));
+ nearest = std::min(nearest, c.z);
+ }
+
+ // Clamped to the grid, because what falls outside it is off screen and needs
+ // no occluder to be unseen. An empty rectangle after the clamp is entirely
+ // off screen, which is the frustum's answer to give, not this one's.
+ const i32 x0 = std::max(0, static_cast<i32>(std::floor(lo.x)));
+ const i32 y0 = std::max(0, static_cast<i32>(std::floor(lo.y)));
+ const i32 x1 = std::min(static_cast<i32>(kSize) - 1, static_cast<i32>(std::floor(hi.x)));
+ const i32 y1 = std::min(static_cast<i32>(kSize) - 1, static_cast<i32>(std::floor(hi.y)));
+ if (x1 < x0 || y1 < y0) return false;
+
+ // FOUR texels a side, not two: a level's texels align to the grid and not to
+ // this rectangle, so at two the overhang is the object's own width again —
+ // measured, six of nine cubes squarely behind a wall went uncalled.
+ u32 level = 0;
+ while (level + 1 < kLevels
+ && ((x1 >> level) - (x0 >> level) >= static_cast<i32>(kTestSpan)
+ || (y1 >> level) - (y0 >> level) >= static_cast<i32>(kTestSpan))) {
+ ++level;
+ }
+ const u32 size = kSize >> level;
+ const f32* cells = levelData(level);
+ f32 farthest = -kOpen;
+ for (i32 y = y0 >> level; y <= (y1 >> level); ++y) {
+ for (i32 x = x0 >> level; x <= (x1 >> level); ++x) {
+ farthest = std::max(farthest, cells[static_cast<usize>(y) * size
+ + static_cast<usize>(x)]);
+ }
+ }
+ // Strictly nearer, so a bound resting exactly on the blocking depth is drawn:
+ // equality here is a surface touching the occluder, which is visible.
+ return farthest < nearest;
+ }
+
+ /** @brief Whether this view blocks nothing, so every bound is visible to it. */
+ bool empty() const { return boxes_ == 0; }
+
+ /** @brief How many declared boxes this view took. */
+ u32 boxes() const { return boxes_; }
+
+private:
+ /** @brief One planar face of a box, in grid space: where it lies and how deep. */
+ struct Face {
+ /** Edge functions as (a, b, c) with a*x + b*y + c >= bias inside. */
+ glm::vec3 edges[4];
+ /** How far each edge function may fall across half a texel either way. */
+ f32 bias[4];
+ /** Depth as an affine function of grid position — which is what a PLANE's
+ * depth is in screen space, and why no perspective divide happens here. */
+ f32 zx = 0.0f, zy = 0.0f, z0 = 0.0f;
+
+ bool covers(const glm::vec2& p) const {
+ for (u32 i = 0; i < 4; ++i) {
+ if (edges[i].x * p.x + edges[i].y * p.y + edges[i].z < bias[i]) return false;
+ }
+ return true;
+ }
+
+ f32 maxDepthOver(const glm::vec2& p) const {
+ return zx * p.x + zy * p.y + z0 + 0.5f * (std::fabs(zx) + std::fabs(zy));
+ }
+ };
+
+ /** @brief The six faces as corner indices, each a ring around the quad. Winding
+ * is not read: which side faces the eye is decided per face from the
+ * projection, so a box turned inside out cannot flip the answer. */
+ static constexpr u32 kFaces[6][4] = {
+ {0, 1, 3, 2}, {4, 6, 7, 5}, {0, 4, 5, 1}, {2, 3, 7, 6}, {0, 2, 6, 4}, {1, 5, 7, 3},
+ };
+
+ /**
+ * @brief Projects a box's eight corners into grid space with depth.
+ *
+ * @return False when any corner is at or behind the eye plane. Rejecting the
+ * whole box is what keeps the arithmetic honest: a projection is only
+ * monotone in depth where w stays positive, and the eye INSIDE an
+ * occluder is this same case — a box whose every ray would be called
+ * blocked.
+ */
+ bool projectBox(const glm::vec3& centre, const glm::quat& rotation, const glm::vec3& half,
+ glm::vec3 (&out)[8]) const {
+ const glm::mat3 basis = glm::mat3_cast(rotation);
+ for (u32 i = 0; i < 8; ++i) {
+ const glm::vec3 local((i & 1u) ? half.x : -half.x,
+ (i & 2u) ? half.y : -half.y,
+ (i & 4u) ? half.z : -half.z);
+ const glm::vec4 clip = view_projection_ * glm::vec4(centre + basis * local, 1.0f);
+ if (clip.w <= kMinW) return false;
+ const glm::vec3 ndc = glm::vec3(clip) / clip.w;
+ // Behind the near plane in the convention every camera projection here
+ // is built in (near = -1). A depth-zero-to-one projection simply never
+ // trips it, which costs culling and never correctness.
+ if (ndc.z < -1.0f) return false;
+ out[i] = {(ndc.x + 1.0f) * 0.5f * static_cast<f32>(kSize),
+ (ndc.y + 1.0f) * 0.5f * static_cast<f32>(kSize), ndc.z};
+ }
+ return true;
+ }
+
+ /** @brief Builds the face @p quad names, or false if it projected to a sliver —
+ * a face seen edge-on covers nothing and has no depth to give. */
+ static bool buildFace(const glm::vec3 (&corners)[8], const u32 (&quad)[4], Face& out) {
+ const glm::vec3 v[4] = {corners[quad[0]], corners[quad[1]],
+ corners[quad[2]], corners[quad[3]]};
+ // Signed area decides the orientation, so the inside test below is the same
+ // expression for a face pointing at the eye and one pointing away.
+ f32 area = 0.0f;
+ for (u32 i = 0; i < 4; ++i) {
+ const glm::vec3& a = v[i];
+ const glm::vec3& b = v[(i + 1) % 4];
+ area += a.x * b.y - b.x * a.y;
+ }
+ if (std::fabs(area) < 1e-3f) return false;
+ const f32 sign = area > 0.0f ? 1.0f : -1.0f;
+
+ for (u32 i = 0; i < 4; ++i) {
+ const glm::vec3& a = v[i];
+ const glm::vec3& b = v[(i + 1) % 4];
+ const f32 ex = -(b.y - a.y) * sign;
+ const f32 ey = (b.x - a.x) * sign;
+ out.edges[i] = {ex, ey, -(ex * a.x + ey * a.y)};
+ // Half a texel each way: the test is then "covers this texel WHOLE",
+ // which is the difference between an occluder that may hide something
+ // and one that only touches the pixels at its own silhouette.
+ out.bias[i] = 0.5f * (std::fabs(ex) + std::fabs(ey));
+ }
+
+ const glm::vec2 d1(v[1].x - v[0].x, v[1].y - v[0].y);
+ const glm::vec2 d2(v[2].x - v[0].x, v[2].y - v[0].y);
+ const f32 det = d1.x * d2.y - d1.y * d2.x;
+ if (std::fabs(det) < 1e-6f) return false;
+ const f32 dz1 = v[1].z - v[0].z;
+ const f32 dz2 = v[2].z - v[0].z;
+ out.zx = (dz1 * d2.y - dz2 * d1.y) / det;
+ out.zy = (d1.x * dz2 - d2.x * dz1) / det;
+ out.z0 = v[0].z - out.zx * v[0].x - out.zy * v[0].y;
+ return true;
+ }
+
+ /** @brief One pyramid in one array: level 0 is the grid, each next a quarter. */
+ static constexpr usize kCells = (kSize * kSize * 4) / 3 + 1;
+
+ f32* levelData(u32 level) { return base_.data() + offsetOf(level); }
+ const f32* levelData(u32 level) const { return base_.data() + offsetOf(level); }
+
+ static constexpr usize offsetOf(u32 level) {
+ usize offset = 0;
+ for (u32 i = 0; i < level; ++i) offset += static_cast<usize>(kSize >> i) * (kSize >> i);
+ return offset;
+ }
+
+ glm::mat4 view_projection_{1.0f};
+ std::array<f32, kCells> base_{};
+ u32 boxes_ = 0;
+};
+
+} // namespace esengine
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index f11a8a8ac..8fb55f738 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -8,6 +8,7 @@
#include "../draw/ImmediateDraw.hpp"
#include "../../ecs/components/Transform.hpp"
#include "../../ecs/components/Light.hpp"
+#include "../../ecs/components/Occluder.hpp"
#include "../../ecs/components/ShadowCaster2D.hpp"
#include "../../ecs/components/SortingGroup.hpp"
#include "../../ecs/components/SpriteMask.hpp"
@@ -543,6 +544,11 @@ void RenderFrame::flush() {
ES_PROFILE_COUNTER("render.targets.bytes", target_pool_.bytes());
ES_PROFILE_COUNTER("render.culled", stats_.culled);
+ // Which question did the culling, and how much was declared to do it with. A
+ // scene whose occluders stopped being taken — turned past the near plane, or
+ // authored to nothing — reads zero boxes here while render.culled says nothing.
+ ES_PROFILE_COUNTER("render.cull.occluded", stats_.occluded);
+ ES_PROFILE_COUNTER("render.cull.occluders", occlusion_.boxes());
ES_PROFILE_COUNTER("render.sprites", stats_.sprites);
// The 3D path had no counter at all, and its cost is the one a pixel hides
// best: identical geometry drawn N times merges into ONE instanced call, so
@@ -1133,6 +1139,32 @@ void RenderFrame::collectProbes(ecs::Registry& registry) {
}
}
+/**
+ * @brief Rasterises this camera's occluders: every declared box, as this view sees it.
+ *
+ * @details Before the plugins, because every one of them reads it: a renderable is
+ * tested against the whole scene's occluders and not against those that
+ * happen to have been walked first. The box is ORIENTED, never its own
+ * bounding box — that would claim the corners the wall does not fill.
+ */
+void RenderFrame::collectOccluders(ecs::Registry& registry) {
+ occlusion_.begin(view_projection_);
+ auto view = registry.view<ecs::Occluder>();
+ for (auto entity : view) {
+ const auto& occluder = view.get(entity);
+ if (!occluder.enabled) continue;
+ auto* transform = registry.tryGet<ecs::Transform>(entity);
+ if (!transform) continue;
+ transform->ensureDecomposed();
+ // Scale is not read, matching every other authored extent and the box the
+ // viewport draws: one value, two readers, and the picture an author places
+ // the box by IS what the cull uses.
+ occlusion_.addBox(transform->worldPosition, transform->worldRotation,
+ glm::abs(occluder.halfExtents));
+ }
+ occlusion_.finish();
+}
+
void RenderFrame::collectLights(ecs::Registry& registry) {
LightStore& lights = context_.lights();
lights.clear();
@@ -1847,6 +1879,9 @@ void RenderFrame::collectAll(ecs::Registry& registry) {
// Beside the lights and for the same reason: this answers what reaches a point
// that no light can be asked about, and the mesh collect below reads both.
{ ES_PROFILE_SCOPE("render.collect.probes"); collectProbes(registry); }
+ // Before the plugins and after nothing: it reads the scene and this camera's
+ // projection, both of which are already settled when the collect opens.
+ { ES_PROFILE_SCOPE("render.collect.occluders"); collectOccluders(registry); }
// Decided here, drawn by the graph. Nothing in this function may touch the
// device: the frame reaches the host as several calls with its own draws
// between them, and a pass opened here would swallow them.
@@ -1864,6 +1899,10 @@ void RenderFrame::collectAll(ecs::Registry& registry) {
// through a view matrix puts a HUD wherever the view happens to be looking.
collectCtx.screen_ui = screen_domain_;
collectCtx.lod = {view_id_, &lod_view_state_, &lod_counts_};
+ // Only the camera collect. The shadow collect above builds its own context and
+ // leaves this null: what a player cannot see still casts, and a caster dropped
+ // because the camera cannot see IT takes its shadow off the ground with it.
+ collectCtx.occlusion = &occlusion_;
{ ES_PROFILE_SCOPE("render.collect.sky"); collectSky(collectCtx); }
for (auto& plugin : plugins_) {
ES_PROFILE_SCOPE(plugin->collectScope());
@@ -1874,6 +1913,7 @@ void RenderFrame::collectAll(ecs::Registry& registry) {
// like the per-type counts beside it, so a frame composited from several
// cameras reports every cull each of them made.
stats_.culled += collectCtx.culled;
+ stats_.occluded += collectCtx.occluded;
// OR-ed across the frame's cameras, applied at the next beginFrame and never
// mid-frame: the capture is scratch each camera composites out of, and the
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index be6287bbd..4e0ebc21e 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -90,6 +90,8 @@ public:
u32 particles = 0;
u32 shapes = 0;
u32 culled = 0;
+ /// Of `culled`, how many an occluder refused rather than the frustum.
+ u32 occluded = 0;
f32 gpu_time_ms = -1.0f; // -1 when the timer is unavailable
};
@@ -468,6 +470,8 @@ private:
glm::mat4 view_projection_{1.0f};
Frustum frustum_;
+ /// The other half of this camera's cull, rebuilt from the scene each collect.
+ OcclusionView occlusion_;
RenderTargetManager::Handle current_target_ = 0;
RenderStage current_stage_ = RenderStage::Transparent;
@@ -586,6 +590,12 @@ private:
/** @brief Gathers the frame's LightProbeVolume components into the ProbeStore. */
void collectProbes(ecs::Registry& registry);
+ /**
+ * @brief Rasterises the scene's declared occluders into this camera's
+ * @ref occlusion_, which the collect below then tests bounds against.
+ */
+ void collectOccluders(ecs::Registry& registry);
+
/// Makes this ambient light the frame's environment, when it names one that is
/// loaded. `scale` is the light's colour times its intensity, folded into the
/// coefficients — an environment is what the light casts, not a second source.
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 7d7a3277e..2560053d5 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -467,7 +467,6 @@ RenderPrewarmResult MeshPlugin::prewarm(RenderFrameContext& ctx, ecs::Registry&
void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
auto& registry = collect_ctx.registry;
- auto& frustum = collect_ctx.frustum;
auto& clips = collect_ctx.clip_state;
auto& buffers = collect_ctx.buffer_pool;
auto& draw_list = collect_ctx.draw_list;
@@ -542,9 +541,19 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
const glm::vec3 localMax = group ? levels.localMax
: resident ? resident->localMax : glm::vec3(mesh.localMax, 0.0f);
+ // BEFORE the cull, because whether this draw depth-tests decides if an
+ // occluder may refuse it, and the material is where that is finally said.
+ // Reused by the draw key below: two lookups is how the two come to differ.
+ const MaterialRecord* material = (mesh.material != 0 && ctx.materials)
+ ? ctx.materials->find(mesh.material) : nullptr;
+ const bool depthTested = material ? material->depthTest : mesh.opaque;
+
glm::vec3 aabbCenter(0.0f), halfExtents(0.0f);
orientedWorldAabb(position, rotation, scale, localMin, localMax, aabbCenter, halfExtents);
- if (!frustum.intersectsAABB(aabbCenter, halfExtents)) {
+ // The collect's own predicate, not a frustum test of this plugin's: it
+ // answers "outside the view" AND "behind something solid", and a mesh is
+ // what both were built for.
+ if (!collect_ctx.visible(aabbCenter, halfExtents, depthTested)) {
++collect_ctx.culled;
tick(2);
continue;
@@ -615,7 +624,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// the default batch shader; a material owns shading fully, so it takes
// precedence over the lit toggle.
if (mesh.material != 0) {
- if (const MaterialRecord* m = ctx.materials ? ctx.materials->find(mesh.material) : nullptr) {
+ if (const MaterialRecord* m = material) {
key.shaderId = (m->shader != 0) ? m->shader : ctx.batch_shader_id;
key.blend = m->blend;
key.materialId = mesh.material;
diff --git a/src/esengine/renderer/plugins/SpritePlugin.cpp b/src/esengine/renderer/plugins/SpritePlugin.cpp
index 01459d399..f27c73ecc 100644
--- a/src/esengine/renderer/plugins/SpritePlugin.cpp
+++ b/src/esengine/renderer/plugins/SpritePlugin.cpp
@@ -47,7 +47,10 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {
0.0f);
glm::vec3 halfExtents = flatHalfExtents(
turn, glm::vec3(std::abs(finalSize.x), std::abs(finalSize.y), 0.0f) * 0.5f);
- if (!collect_ctx.visible(aabbCenter, halfExtents)) {
+ // Never depth-tested unless a material says so, and that is resolved
+ // below — so a sprite is judged by the view alone, and an occluder in
+ // front of it does not get to speak.
+ if (!collect_ctx.visible(aabbCenter, halfExtents, false)) {
++collect_ctx.culled;
continue;
}
diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cpp
index 0490a9b94..0e4333dd8 100644
--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp
+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp
@@ -90,7 +90,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
// `position` above already carries the turned offset, so only the extents do.
glm::vec3 halfExtents = flatHalfExtents(
flatTurnZ(rotation), glm::vec3(w * scale.x, h * scale.y, 0.0f) * 0.5f);
- if (!collect_ctx.visible(position, halfExtents)) { ++collect_ctx.culled; continue; }
+ if (!collect_ctx.visible(position, halfExtents, false)) { ++collect_ctx.culled; continue; }
f32 angle = 2.0f * std::atan2(rotation.z, rotation.w);
i32 layer = UI_BASE_LAYER + renderer.uiOrder;
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index e086b6232..c0dc4fbd5 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -238,6 +238,16 @@ add_test(NAME test_lod_selection COMMAND test_lod_selection)
# without a device — the pixel gates say a draw came out the wrong colour, this
# says whether the read left the box, took the wrong volume, or accepted a grid
# too short to fill it.
+# What an occluder hides and what it must not. Header-only, so it runs without a
+# device — and it runs every claim under BOTH depth conventions, which is the one
+# thing a pixel gate on one backend cannot ask.
+add_executable(test_occlusion_view renderer/test_occlusion_view.cpp)
+target_include_directories(test_occlusion_view PRIVATE
+ ${CMAKE_SOURCE_DIR}/src
+ ${CMAKE_SOURCE_DIR}/third_party/glm
+)
+add_test(NAME test_occlusion_view COMMAND test_occlusion_view)
+
add_executable(test_probe_store renderer/test_probe_store.cpp)
target_include_directories(test_probe_store PRIVATE
${CMAKE_SOURCE_DIR}/src
diff --git a/tests/renderer/test_occlusion_view.cpp b/tests/renderer/test_occlusion_view.cpp
new file mode 100644
index 000000000..d6ca0fa41
--- /dev/null
+++ b/tests/renderer/test_occlusion_view.cpp
@@ -0,0 +1,251 @@
+/**
+ * @file test_occlusion_view.cpp
+ * @brief What an occluder hides and — the half that matters — what it must not.
+ *
+ * A pixel gate says a frame drew too much; only this says whether the coverage,
+ * the depth order, the orientation or the near plane is what broke. Every claim
+ * runs against BOTH depth conventions the engine's matrices arrive in (the SDK
+ * builds GL clip volumes, glm here is compiled zero-to-one), because nothing in
+ * OcclusionView may read a depth as anything but "farther than" another.
+ */
+
+#include "esengine/renderer/frame/OcclusionView.hpp"
+
+#include <glm/gtc/matrix_transform.hpp>
+
+#include <cmath>
+#include <cstdio>
+
+using namespace esengine;
+
+static int g_failures = 0;
+static const char* g_convention = "";
+#define CHECK(cond, msg) \
+ do { \
+ if (!(cond)) { std::printf("FAIL: [%s] %s\n", g_convention, msg); ++g_failures; } \
+ else { std::printf("ok: [%s] %s\n", g_convention, msg); } \
+ } while (0)
+
+/** A camera at the origin looking down -Z, which is what every scene here means. */
+static glm::mat4 view() {
+ return glm::lookAt(glm::vec3(0.0f), glm::vec3(0.0f, 0.0f, -1.0f), glm::vec3(0.0f, 1.0f, 0.0f));
+}
+
+/** glm's own projection — zero-to-one here, since that is how it is compiled. */
+static glm::mat4 zeroToOneVP() {
+ return glm::perspective(glm::radians(60.0f), 1.0f, 1.0f, 10000.0f) * view();
+}
+
+/**
+ * The projection the SDK ships (sdk/src/math/mat4.ts), cell for cell: near maps
+ * to -1. Written out rather than taken from glm because glm is compiled the other
+ * way here, and the convention IS what this pair of runs is about.
+ */
+static glm::mat4 glVP() {
+ const f32 f = 1.0f / std::tan(glm::radians(60.0f) * 0.5f);
+ const f32 near = 1.0f, far = 10000.0f;
+ const f32 nf = near - far;
+ glm::mat4 p(0.0f);
+ p[0][0] = f;
+ p[1][1] = f;
+ p[2][2] = (far + near) / nf;
+ p[2][3] = -1.0f;
+ p[3][2] = (2.0f * far * near) / nf;
+ return p * view();
+}
+
+static constexpr glm::quat kNoTurn(1.0f, 0.0f, 0.0f, 0.0f);
+
+/** A wall 100 wide and 200 tall, 100 in front of the eye: it fills the screen
+ * vertically and a little over half of it across. */
+static void addWall(OcclusionView& v) {
+ CHECK(v.addBox({0.0f, 0.0f, -100.0f}, kNoTurn, {30.0f, 60.0f, 5.0f}), "the wall is taken");
+}
+
+static void testNothingDeclared(const glm::mat4& vp) {
+ OcclusionView v;
+ v.begin(vp);
+ v.finish();
+ CHECK(v.empty(), "a view with no occluder blocks nothing");
+ CHECK(!v.hidden({0.0f, 0.0f, -300.0f}, {20.0f, 20.0f, 20.0f}),
+ "and hides nothing standing in front of the camera");
+}
+
+static void testBehindAndBeside(const glm::mat4& vp) {
+ OcclusionView v;
+ v.begin(vp);
+ addWall(v);
+ v.finish();
+ CHECK(v.boxes() == 1, "one declared box is one taken box");
+
+ CHECK(v.hidden({0.0f, 0.0f, -300.0f}, {20.0f, 20.0f, 20.0f}),
+ "what stands squarely behind the wall is hidden");
+ CHECK(!v.hidden({150.0f, 0.0f, -300.0f}, {10.0f, 10.0f, 10.0f}),
+ "what stands beside it is drawn");
+ // Overlapping the wall's edge: part of it is blocked and part is not, and a
+ // cull that answers for the majority is a cull that removes what can be seen.
+ CHECK(!v.hidden({100.0f, 0.0f, -300.0f}, {20.0f, 20.0f, 20.0f}),
+ "what straddles its edge is drawn");
+}
+
+static void testDepthOrder(const glm::mat4& vp) {
+ OcclusionView v;
+ v.begin(vp);
+ addWall(v);
+ v.finish();
+ // The same footprint as the hidden one, on the near side. Only the depth
+ // separates them, which is the whole difference between a cull and a mask.
+ CHECK(!v.hidden({0.0f, 0.0f, -60.0f}, {5.0f, 5.0f, 5.0f}),
+ "what stands in FRONT of the wall is drawn");
+ CHECK(!v.hidden({0.0f, 0.0f, -100.0f}, {30.0f, 60.0f, 5.0f}),
+ "the wall does not hide itself");
+}
+
+/** Which face of a solid box is the one that blocks: the NEAR one. Everything
+ * past it is either inside the wall or behind it, and neither is seen. */
+static void testBlockedAtTheNearFace(const glm::mat4& vp) {
+ OcclusionView v;
+ v.begin(vp);
+ // Thick: forty units of wall between its two faces, which is where the two
+ // answers differ and the only place they can be told apart.
+ v.addBox({0.0f, 0.0f, -100.0f}, kNoTurn, {30.0f, 60.0f, 20.0f});
+ v.finish();
+ CHECK(v.hidden({0.0f, 0.0f, -100.0f}, {2.0f, 2.0f, 2.0f}),
+ "what stands inside the wall's own thickness is hidden");
+ CHECK(!v.hidden({0.0f, 0.0f, -75.0f}, {2.0f, 2.0f, 2.0f}),
+ "what stands just in front of its near face is drawn");
+}
+
+static void testTooSmallToHide(const glm::mat4& vp) {
+ OcclusionView v;
+ v.begin(vp);
+ // Two units across at a hundred out: less than a texel of the grid, so it
+ // covers no texel WHOLE and may claim none.
+ v.addBox({0.0f, 0.0f, -100.0f}, kNoTurn, {1.0f, 1.0f, 1.0f});
+ v.finish();
+ CHECK(!v.hidden({0.0f, 0.0f, -300.0f}, {2.0f, 2.0f, 2.0f}),
+ "an occluder finer than the grid hides nothing");
+}
+
+/** The world x that lands at @p ndc across, seen from @p depth away. */
+static f32 worldX(f32 ndc, f32 depth) {
+ return ndc * std::tan(glm::radians(30.0f)) * depth;
+}
+
+/**
+ * The half-texel every claim here is built on: a texel the occluder covers only
+ * PART of stays open. Written against the grid's own grain rather than a round
+ * number, because the defect it guards is exactly one texel wide — an object
+ * standing just past a wall's edge, inside the texel that edge runs through.
+ */
+static void testPartlyCoveredTexelStaysOpen(const glm::mat4& vp) {
+ const f32 texel = 2.0f / static_cast<f32>(OcclusionView::kSize);
+ // A wall filling everything left of a line 60% of the way through one texel.
+ // Thin, so the silhouette is the near face and the edge lands where it is put.
+ const f32 edge = worldX(0.6f * texel, 99.5f);
+ OcclusionView v;
+ v.begin(vp);
+ CHECK(v.addBox({(edge - 4000.0f) * 0.5f, 0.0f, -100.0f}, kNoTurn,
+ {(edge + 4000.0f) * 0.5f, 4000.0f, 0.5f}),
+ "the half-covering wall is taken");
+ v.finish();
+
+ // Past the wall's edge but not past the texel it runs through. A raster that
+ // claimed the whole texel would make this vanish standing in the open.
+ const f32 beyond = worldX(0.8f * texel, 300.0f);
+ const f32 sliver = worldX(0.1f * texel, 300.0f);
+ CHECK(!v.hidden({beyond, 0.0f, -300.0f}, {sliver, sliver, sliver}),
+ "an object just past a wall's edge, inside the same texel, is drawn");
+ // Two texels in, where the coverage is whole whichever way the rim is read.
+ CHECK(v.hidden({worldX(-2.0f * texel, 300.0f), 0.0f, -300.0f}, {sliver, sliver, sliver}),
+ "and the same object well behind the wall is not");
+}
+
+static void testTurnedIsNotItsBoundingBox(const glm::mat4& vp) {
+ OcclusionView v;
+ v.begin(vp);
+ // A wall turned 45 degrees: a diamond on screen, reaching 70 out along each
+ // axis and only 35 along the diagonal. Its bounding box claims the whole 70
+ // square — the corners the wall does not fill.
+ const glm::quat turn = glm::angleAxis(glm::radians(45.0f), glm::vec3(0.0f, 0.0f, 1.0f));
+ CHECK(v.addBox({0.0f, 0.0f, -200.0f}, turn, {50.0f, 50.0f, 5.0f}), "the turned wall is taken");
+ v.finish();
+ CHECK(v.hidden({0.0f, 0.0f, -400.0f}, {10.0f, 10.0f, 10.0f}),
+ "a turned wall still hides what is behind its middle");
+ // Twice the diamond's diagonal reach and well inside its bounding box — the
+ // one place the two answers differ, so it is the only place worth asking.
+ CHECK(!v.hidden({110.0f, 110.0f, -400.0f}, {10.0f, 10.0f, 10.0f}),
+ "but not what is behind a corner its bounding box would have claimed");
+}
+
+static void testEyeInsideAndNearPlane(const glm::mat4& vp) {
+ OcclusionView v;
+ v.begin(vp);
+ // A box the camera stands inside would call every ray blocked — including the
+ // rays reaching what is in front of the player.
+ CHECK(!v.addBox({0.0f, 0.0f, 0.0f}, kNoTurn, {50.0f, 50.0f, 50.0f}),
+ "a box the eye is inside is refused");
+ CHECK(!v.addBox({0.0f, 0.0f, -100.0f}, kNoTurn, {50.0f, 50.0f, 200.0f}),
+ "a box reaching behind the eye is refused");
+ v.finish();
+ CHECK(v.empty(), "a view left with no taken box blocks nothing");
+ CHECK(!v.hidden({0.0f, 0.0f, -300.0f}, {20.0f, 20.0f, 20.0f}),
+ "so everything in front of the camera is drawn");
+}
+
+static void testOrderDoesNotMatter(const glm::mat4& vp) {
+ // Two walls, one nearer and one farther, declared each way round. Combining
+ // them keeps the NEAREST, which no iteration order may change.
+ const glm::vec3 nearWall(0.0f, 0.0f, -100.0f), farWall(0.0f, 0.0f, -200.0f);
+ OcclusionView a, b;
+ a.begin(vp);
+ a.addBox(nearWall, kNoTurn, {30.0f, 60.0f, 5.0f});
+ a.addBox(farWall, kNoTurn, {60.0f, 120.0f, 5.0f});
+ a.finish();
+ b.begin(vp);
+ b.addBox(farWall, kNoTurn, {60.0f, 120.0f, 5.0f});
+ b.addBox(nearWall, kNoTurn, {30.0f, 60.0f, 5.0f});
+ b.finish();
+
+ const glm::vec3 between(0.0f, 0.0f, -150.0f), behind(0.0f, 0.0f, -300.0f);
+ const glm::vec3 half(10.0f);
+ CHECK(a.hidden(between, half) == b.hidden(between, half)
+ && a.hidden(behind, half) == b.hidden(behind, half),
+ "the order the boxes arrive in changes no answer");
+ CHECK(a.hidden(between, half), "the nearer wall hides what stands between them");
+}
+
+static void testReopening(const glm::mat4& vp) {
+ OcclusionView v;
+ v.begin(vp);
+ addWall(v);
+ v.finish();
+ CHECK(v.hidden({0.0f, 0.0f, -300.0f}, {20.0f, 20.0f, 20.0f}), "hidden while the wall stands");
+ // The next camera of the same frame: the grid is this view's, and a wall left
+ // over from the last one would hide what this one can see.
+ v.begin(vp);
+ v.finish();
+ CHECK(v.empty() && !v.hidden({0.0f, 0.0f, -300.0f}, {20.0f, 20.0f, 20.0f}),
+ "and drawn again for the next view, which declared none");
+}
+
+static void runAll(const char* name, const glm::mat4& vp) {
+ g_convention = name;
+ testNothingDeclared(vp);
+ testBehindAndBeside(vp);
+ testDepthOrder(vp);
+ testBlockedAtTheNearFace(vp);
+ testTooSmallToHide(vp);
+ testPartlyCoveredTexelStaysOpen(vp);
+ testTurnedIsNotItsBoundingBox(vp);
+ testEyeInsideAndNearPlane(vp);
+ testOrderDoesNotMatter(vp);
+ testReopening(vp);
+}
+
+int main() {
+ runAll("gl", glVP());
+ runAll("zero-to-one", zeroToOneVP());
+ std::printf(g_failures == 0 ? "\nall occlusion claims hold\n" : "\n%d failure(s)\n", g_failures);
+ return g_failures == 0 ? 0 : 1;
+}
diff --git a/tools/check-gizmo-coverage.mjs b/tools/check-gizmo-coverage.mjs
index fe6407f78..94da254e4 100644
--- a/tools/check-gizmo-coverage.mjs
+++ b/tools/check-gizmo-coverage.mjs
@@ -78,6 +78,7 @@ const DISPOSITION = {
'Light.innerRadius': 'extent',
'Light.cookieSize': 'extent',
'LightProbeVolume.halfExtents': 'extent',
+ 'Occluder.halfExtents': 'extent',
'MeleeAttack.radius': 'extent',
'AudioSource.minDistance': 'extent',
'AudioSource.maxDistance': 'extent',
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 904ea2d83..b40327f0c 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -283,6 +283,11 @@ export const SCENES = [
// rather than honoured into a bind pose: the skin draws as it always did
// (mesh-skin's own points), and thresholds that would cull it decide nothing.
{ id: "lod-skin-refused", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/lod-skin.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.lod.groups\":0,\"render.lod.culled\":0,\"render.meshes\":1}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.35,\"y\":0.6,\"rgb\":[0,255,0],\"tol\":30},{\"x\":0.75,\"y\":0.35,\"rgb\":[0,255,0],\"tol\":30},{\"x\":0.75,\"y\":0.60,\"rgb\":[0,0,0],\"tol\":20}]" } },
+ // A PAIR differing in ONE field: nine cubes behind a wall an Occluder declares
+ // solid, two beside it. Three draws here, twelve with that field off below — and
+ // the SAME four pixels, which is the whole claim about what an occluder changes.
+ { id: "occlusion-cull", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/occlusion-cost.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.meshes\": 3, \"render.culled\": 9, \"render.cull.occluded\": 9, \"render.cull.occluders\": 1}", ESTELLA_VERIFY_EXPECT: "[{\"x\": 0.5, \"y\": 0.5, \"rgb\": [255, 255, 255], \"tol\": 20}, {\"x\": 0.918, \"y\": 0.5, \"rgb\": [0, 255, 0], \"tol\": 30}, {\"x\": 0.082, \"y\": 0.5, \"rgb\": [0, 255, 0], \"tol\": 30}, {\"x\": 0.98, \"y\": 0.02, \"rgb\": [0, 0, 0], \"tol\": 10}]" } },
+ { id: "occlusion-off", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/occlusion-cost.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_SET_FIELD: "{\"entity\": 1, \"component\": \"Occluder\", \"key\": \"enabled\", \"value\": false, \"steps\": 2}", ESTELLA_VERIFY_COUNTERS: "{\"render.meshes\": 12, \"render.culled\": 0, \"render.cull.occluded\": 0, \"render.cull.occluders\": 0}", ESTELLA_VERIFY_EXPECT: "[{\"x\": 0.5, \"y\": 0.5, \"rgb\": [255, 255, 255], \"tol\": 20}, {\"x\": 0.918, \"y\": 0.5, \"rgb\": [0, 255, 0], \"tol\": 30}, {\"x\": 0.082, \"y\": 0.5, \"rgb\": [0, 255, 0], \"tol\": 30}, {\"x\": 0.98, \"y\": 0.02, \"rgb\": [0, 0, 0], \"tol\": 10}]" } },
{ id: "mesh-builtin", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-builtin.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.3667,\"y\":0.5,\"rgb\":[236,236,236],\"tol\":20},{\"x\":0.1333,\"y\":0.5,\"rgb\":[98,98,98],\"tol\":20},{\"x\":0.75,\"y\":0.5,\"rgb\":[236,236,236],\"tol\":20},{\"x\":0.6667,\"y\":0.5,\"rgb\":[155,155,155],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },
// A baked panorama lighting a surface BY DIRECTION: two coplanar triangles, one
// white colour, normals up and down under a sky blue above and red below. A flat