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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.ymlindex d62832ca5..76042a341 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -29,7 +29,7 @@ env:test_registry_ondestroy test_view_api_matrixtest_shader_device test_draw_params test_texture_fb test_buffer_devicetest_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_viewtest_text_edit test_render_graph test_device_loss test_physics_interpolationtest_bitmap_font test_texture_cache test_mesh_recovery test_aot_host test_aot_conformancetest_touch_streamdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 thetime. 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 atsomething, 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. Thediff --git a/desktop b/desktopindex 31b8113f8..6207b2ec7 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 31b8113f8e9c6eceeb3875af6cde6affa69183ae+Subproject commit 6207b2ec785ad763c05507b141bce3bf0e118e64diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.tsindex 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.jsonindex 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.esscenenew file mode 100644index 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex c6d7fb0be..56aa1cf16 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -36,6 +36,7 @@ addMeshLightmap: (entity: Entity, component: MeshLightmap) => voidaddMeshMorph: (entity: Entity, component: MeshMorph) => voidaddMeshRenderer: (entity: Entity, component: MeshRenderer) => voidaddMeshSkin: (entity: Entity, component: MeshSkin) => void+addOccluder: (entity: Entity, component: Occluder) => voidaddParent: (entity: Entity, component: Parent) => voidaddParticleEmitter: (entity: Entity, component: ParticleEmitter) => voidaddParticleForceField: (entity: Entity, component: ParticleForceField) => void@@ -85,6 +86,7 @@ getMeshLightmap: (entity: Entity) => MeshLightmapgetMeshMorph: (entity: Entity) => MeshMorphgetMeshRenderer: (entity: Entity) => MeshRenderergetMeshSkin: (entity: Entity) => MeshSkin+getOccluder: (entity: Entity) => OccludergetParent: (entity: Entity) => ParentgetParticleEmitter: (entity: Entity) => ParticleEmittergetParticleForceField: (entity: Entity) => ParticleForceField@@ -130,6 +132,7 @@ hasMeshLightmap: (entity: Entity) => booleanhasMeshMorph: (entity: Entity) => booleanhasMeshRenderer: (entity: Entity) => booleanhasMeshSkin: (entity: Entity) => boolean+hasOccluder: (entity: Entity) => booleanhasParent: (entity: Entity) => booleanhasParticleEmitter: (entity: Entity) => booleanhasParticleForceField: (entity: Entity) => boolean@@ -176,6 +179,7 @@ removeMeshLightmap: (entity: Entity) => voidremoveMeshMorph: (entity: Entity) => voidremoveMeshRenderer: (entity: Entity) => voidremoveMeshSkin: (entity: Entity) => void+removeOccluder: (entity: Entity) => voidremoveParent: (entity: Entity) => voidremoveParticleEmitter: (entity: Entity) => voidremoveParticleForceField: (entity: Entity) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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>('LightProbeVmetaDefaults<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 notdiff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 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.tsindex 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.cppindex 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 [®istry](std::uint32_t raw) -> void* {+ return registry.tryGet<esengine::ecs::Occluder>(Entity::fromRaw(raw));+ };+ }if (std::strcmp(name, "Parent") == 0) {return [®istry](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* namereturn denseAsIds(registry.entitiesWith<esengine::ecs::MeshSkin>());};}+ if (std::strcmp(name, "Occluder") == 0) {+ return [®istry]() -> Candidates {+ return denseAsIds(registry.entitiesWith<esengine::ecs::Occluder>());+ };+ }if (std::strcmp(name, "Parent") == 0) {return [®istry]() -> 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.cppindex 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::selse 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::stelse 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::stelse 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::stelse 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.cppindex 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 offsetstatic_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.hppnew file mode 100644index 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::ecsdiff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hppindex 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.hppnew file mode 100644index 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 esenginediff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 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 thediff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 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.cppindex 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.cppindex 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.cppindex 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.txtindex 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}/srcdiff --git a/tests/renderer/test_occlusion_view.cpp b/tests/renderer/test_occlusion_view.cppnew file mode 100644index 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.mjsindex 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.mjsindex 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