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.

Implement shared planar reflection captures and authoring

yhh7b7e62d1c84f
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 69f804742..1b2d619f7 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -30,7 +30,7 @@ env:
test_hierarchy_links test_entity_activity test_transform_traversal test_ui_tree test_tween_activity
test_shader_device test_draw_params test_per_draw_blocks test_texture_fb test_buffer_device
test_compressed_format test_batch_builder test_skeletal_batch_color test_boundary_span test_webgpu_device
- test_clip_depth test_sort_key test_sprite_mask_range test_sprite_draw_mode test_shadow_atlas test_particle_shapes test_lod_selection test_view_shading test_mesh_edges test_hdr_format test_probe_store test_occlusion_view test_reflection_store
+ test_clip_depth test_planar_reflection test_sort_key test_sprite_mask_range test_sprite_draw_mode test_shadow_atlas test_particle_shapes test_lod_selection test_view_shading test_mesh_edges test_hdr_format test_probe_store test_occlusion_view test_reflection_store
test_text_edit test_render_graph test_device_loss test_physics_interpolation
test_bitmap_font test_texture_cache test_material_shader_lifetime test_mesh_recovery test_aot_host test_aot_conformance
test_touch_stream
@@ -87,6 +87,17 @@ jobs:
node tools/tests/wechat-starter.e2e.mjs --dir output/wechat-starter-ci-fixture --out output/wechat-starter-ci-check
- name: Check OpenPaaS 2D and 3D exports in a headless contract host
run: node tools/tests/openpaas-runtime.e2e.mjs --wasm build/wasm/quickgame --out output/openpaas-ci-check
+ - name: Check dynamic planar reflections with genuine headless Chromium
+ run: |
+ node tools/render-host/build.mjs
+ node tools/tests/planar-reflection.e2e.mjs --webgl-only
+ - name: Upload planar reflection runtime observations
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: planar-reflection-runtime
+ path: output/rm044-runtime/
+ retention-days: 3
- name: Upload OpenPaaS contract observations and frames
if: always()
uses: actions/upload-artifact@v7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2faa0ed32..b13bc5b7f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Added
+- **Dynamic planar reflections.** A shared 2D/3D render-graph capture provides mirrored cameras, plane clipping, layer filtering and PBR reflection input for flat meshes. Details adds quality overrides, plane preview and capture diagnostics; project tiers, every-frame/fixed-rate/on-demand capture, per-camera ownership and device recovery share one implementation. A runnable example and WebGL2/WebGPU headless pixel checks are included. One visible surface per view; mobile device acceptance remains pending.
+
- **SUD OpenPaaS development export.** An opt-in project platform preset exports a `main.js` directory for PinK's third-party builder. Its SDK profile bridges `sud`, package-file WASM loading, XHR, WebSocket and localStorage through the shared 2D/3D mini-game runtime. Headless checks exercise real exported 2D and 3D frames, including a WASM result without `module`; PinK packaging and Android/iOS acceptance remain pending. Login, ads, payment, WebGPU and EmscriptenGLX are not enabled by this initial integration.
The directory includes the initial `manifest.json` emitted by the official web2sp converter. That converter produces a SUD project directory, not a binary `.sp` file; final package generation remains separate from directory export.
`package-openpaas` now invokes PinK's official packer directly to generate encrypted, signed `.sp` files and verify all payload files before replacing the output. Real 2D/3D examples pass export → package → verify → decrypt → payload comparison → headless rendering with independent test keys; authorized Hello PinK and device acceptance remain pending. Uploading is user-managed.
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmake
index ea392c026..18ba6e606 100644
--- a/cmake/ESEngineSources.cmake
+++ b/cmake/ESEngineSources.cmake
@@ -26,6 +26,7 @@ set(ESENGINE_SOURCES
${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFrame.cpp
${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFrameMask.cpp
${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFrameShadow2D.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFramePlanar.cpp
${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFrameOverlay.cpp
${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFrameSubmit.cpp
${ESENGINE_ROOT}/src/esengine/renderer/frame/FrameCapture.cpp
diff --git a/desktop b/desktop
index a1acec43c..e69f4b736 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit a1acec43c6f90d45608746acad949b505ca409bb
+Subproject commit e69f4b736529099cd50b3294c9f38b7919feae51
diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdx
index deac3602c..8da1a872a 100644
--- a/docs/astro/src/content/docs/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/graphics/lighting.mdx
@@ -455,6 +455,58 @@ WeChat, playable — boot the same pipeline. Code-first projects pass it at app
const app = createWebApp(module, { colorSpace: 'linear' });
```
+## Dynamic planar reflections
+
+Add `PlanarReflection` to a flat entity with a resident `MeshRenderer` mesh and a
+lit/PBR material. Its world origin and selected local axis define the reflecting
+plane. The current camera is mirrored across that plane; geometry on its opposite
+side, the receiving entity, and screen-space UI are excluded from the capture.
+Water, mirrors and polished floors use the same capture; this is not a water simulation.
+
+```typescript
+import { PlanarReflection, ReflectionAxis, ReflectionQuality,
+ ReflectionUpdate, refreshPlanarReflection, planarReflectionStatus } from 'esengine';
+
+world.insert(surface, PlanarReflection, {
+ axis: ReflectionAxis.Y,
+ quality: ReflectionQuality.Custom,
+ resolutionScale: 0.5,
+ maxSize: 1024,
+ update: ReflectionUpdate.EveryFrame,
+});
+// For OnDemand, request a refresh after changing the reflected scene:
+refreshPlanarReflection(app, surface);
+const capture = planarReflectionStatus(app, surface, cameraEntity);
+```
+
+The existing material controls tint, metallic response, Fresnel and roughness.
+The captured radiance replaces the environment's specular input for this draw;
+it is not added over an already reflected sky. The roughness filter is a small
+spatial approximation, not a prefiltered GGX convolution. An unlit material does
+not sample PBR reflections. Use an actual flat mesh, rather than a thick box, so
+the reflecting geometry agrees with its plane.
+
+One visible surface is captured per view, selected by stable entity ID. Additional
+surfaces report `budget-excluded`. Each camera owns a separate capture; inactive
+views release their targets, resizing refreshes them, and a device rebuild forces
+a recapture. Captures run without post-processing, host draw callbacks or recursion.
+World-space 2D light masks are not regenerated for the reflected camera.
+
+Project quality defaults are ¼ / 512, ½ / 1024 and 1× / 2048 for low, medium and
+high, all updating every frame. Override `planarReflectionScale`,
+`planarReflectionMaxSize`, and `planarReflectionUpdatesPerSecond` in a quality
+profile; zero updates-per-second means every frame. Custom fixed-rate and on-demand
+updates affect only the capture, never the main scene's frame rate.
+
+Details exposes capture settings, quality overrides, a transient plane preview and
+live capture size/draw/resource diagnostics. View 0 is the manual/editor view;
+runtime diagnostics use the camera's runtime entity ID.
+
+Open `examples/planar-reflection`: Space toggles capture, 1/2/3 selects project
+quality, and a moving object demonstrates dynamic reflection. WebGL2/WebGPU
+headless checks cover geometry placement, clipping, layers and update policies;
+physical mobile-device frame-time acceptance remains pending.
+
## In the editor
![A 2D light in the editor viewport — its reach and the shadows its casters throw](@/assets/guides/en/lighting.png)
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
index 88874bf6d..1d7c15fbf 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
@@ -356,6 +356,49 @@ Lighting 面板会说场景已经过期。
const app = createWebApp(module, { colorSpace: 'linear' });
```
+## 动态平面反射
+
+给平面实体添加 `PlanarReflection`,实体需要有 GPU 常驻网格的 `MeshRenderer`
+以及受光 / PBR 材质。实体世界原点与选定的本地轴定义反射平面。捕获跟随当前渲染相机,
+排除平面另一侧的几何、接收面自身及屏幕 UI。水面、镜子、光滑地面复用同一能力;
+这一步提供反射基础,不包含水体模拟。
+
+```typescript
+import { PlanarReflection, ReflectionAxis, ReflectionQuality,
+ ReflectionUpdate, refreshPlanarReflection, planarReflectionStatus } from 'esengine';
+
+world.insert(surface, PlanarReflection, {
+ axis: ReflectionAxis.Y,
+ quality: ReflectionQuality.Custom,
+ resolutionScale: 0.5,
+ maxSize: 1024,
+ update: ReflectionUpdate.EveryFrame,
+});
+// 按需模式下,场景改变后主动刷新:
+refreshPlanarReflection(app, surface);
+const capture = planarReflectionStatus(app, surface, cameraEntity);
+```
+
+继续使用材质原有的颜色、金属度、Fresnel 与粗糙度。捕获替换本次绘制的环境镜面输入,
+不会与原有天空反射重复相加。粗糙度使用小范围空间滤波近似,不是预过滤 GGX 卷积。
+不受光材质不会采样 PBR 反射;接收网格应是平面,避免用有厚度的盒子代替反射平面。
+
+每个视图先支持一个可见反射面,按稳定实体 ID 选择;其他面明确显示 `budget-excluded`。
+多相机各自保存捕获;视图不再使用时释放目标,尺寸改变或设备重建后重新捕获。
+捕获不执行后处理、项目绘制回调或递归反射,也不会为反射相机重新生成 2D 光照遮罩。
+
+低 / 中 / 高档默认使用 ¼ / 512、½ / 1024、1× / 2048 的比例与最长边上限,全部每帧更新。
+可在项目画质档中配置 `planarReflectionScale`、`planarReflectionMaxSize`、
+`planarReflectionUpdatesPerSecond`;更新次数为 0 表示每帧。
+自定义频率和按需更新只影响反射捕获,不限制主场景帧率。
+
+Details 提供捕获参数、画质覆盖、临时反射平面预览和实际尺寸 / 绘制 / 资源诊断。
+视图 0 是手动 / 编辑器视图;游戏运行时传入相机的运行时实体 ID。
+
+打开 `examples/planar-reflection`:空格切换反射,1 / 2 / 3 切换项目画质,移动物体展示动态倒影。
+WebGL2 / WebGPU 无界面检查覆盖几何位置、裁剪、层过滤与更新策略;
+移动端真机帧时间验收仍待完成。
+
## 在编辑器里
![编辑器视口里的 2D 光——它的照射范围与投射的阴影](@/assets/guides/zh/lighting.png)
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index fae43871a..2fc18eefb 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 115,
"beta": 164,
- "experimental": 2236,
+ "experimental": 2248,
"deprecated": 3
},
- "total": 2515,
+ "total": 2527,
"subsystems": [
{
"id": "mobile-controls",
diff --git a/examples/planar-reflection/assets/materials/mirror.esmaterial b/examples/planar-reflection/assets/materials/mirror.esmaterial
new file mode 100644
index 000000000..d1dd6983a
--- /dev/null
+++ b/examples/planar-reflection/assets/materials/mirror.esmaterial
@@ -0,0 +1,13 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "builtin:model",
+ "blendMode": 9,
+ "depthTest": true,
+ "depthWrite": true,
+ "properties": {
+ "u_metallic": 1,
+ "u_roughness": 0,
+ "u_specular": 1
+ }
+}
diff --git a/examples/planar-reflection/assets/materials/mirror.esmaterial.meta b/examples/planar-reflection/assets/materials/mirror.esmaterial.meta
new file mode 100644
index 000000000..a20f73894
--- /dev/null
+++ b/examples/planar-reflection/assets/materials/mirror.esmaterial.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "6bd132e9-b63a-49d2-8304-0ca60640e0af",
+ "version": "2.0",
+ "type": "material",
+ "importer": {}
+}
diff --git a/examples/planar-reflection/assets/meshes/plane.esmesh b/examples/planar-reflection/assets/meshes/plane.esmesh
new file mode 100644
index 000000000..50c383e43
Binary files /dev/null and b/examples/planar-reflection/assets/meshes/plane.esmesh differ
diff --git a/examples/planar-reflection/assets/meshes/plane.esmesh.meta b/examples/planar-reflection/assets/meshes/plane.esmesh.meta
new file mode 100644
index 000000000..822d90cdb
--- /dev/null
+++ b/examples/planar-reflection/assets/meshes/plane.esmesh.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "686313d4-f663-4532-973a-48bcc36da403",
+ "version": "2.0",
+ "type": "mesh",
+ "importer": {}
+}
diff --git a/examples/planar-reflection/assets/scenes/main.esscene b/examples/planar-reflection/assets/scenes/main.esscene
new file mode 100644
index 000000000..de76d859c
--- /dev/null
+++ b/examples/planar-reflection/assets/scenes/main.esscene
@@ -0,0 +1,242 @@
+{
+ "version": 4,
+ "name": "Planar Reflection",
+ "entities": [
+ {
+ "id": 1,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 3,
+ "z": 6
+ },
+ "rotation": {
+ "x": -0.22975292,
+ "y": 0,
+ "z": 0,
+ "w": 0.97324899
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "orthoSize": 6,
+ "isActive": true,
+ "clearFlags": 3,
+ "backgroundColor": {
+ "r": 0.02,
+ "g": 0.02,
+ "b": 0.02,
+ "a": 1
+ },
+ "fov": 50,
+ "nearPlane": 0.1,
+ "farPlane": 100
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Mirror",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "rotation": {
+ "x": -0.70710678,
+ "y": 0,
+ "z": 0,
+ "w": 0.70710678
+ },
+ "scale": {
+ "x": 7,
+ "y": 7,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "assets/meshes/plane.esmesh",
+ "material": "assets/materials/mirror.esmaterial",
+ "opaque": true,
+ "lit": true,
+ "enabled": true
+ }
+ },
+ {
+ "type": "PlanarReflection",
+ "data": {
+ "axis": 2,
+ "quality": 0,
+ "resolutionScale": 1,
+ "maxSize": 512,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Red",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -1.3,
+ "y": 1.0,
+ "z": 0
+ },
+ "scale": {
+ "x": 0.01,
+ "y": 0.01,
+ "z": 0.01
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "cullBackfaces": true,
+ "lit": true,
+ "layer": 1,
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "ReflectionSubject",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Green",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 1.3,
+ "y": 0.7,
+ "z": -0.8
+ },
+ "scale": {
+ "x": 0.007,
+ "y": 0.007,
+ "z": 0.007
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "cullBackfaces": true,
+ "lit": true,
+ "layer": 2,
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 10,
+ "name": "Lamp",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "rotation": {
+ "x": -0.3,
+ "y": -0.25,
+ "z": 0,
+ "w": 0.9205976319760985
+ }
+ }
+ },
+ {
+ "type": "Light",
+ "data": {
+ "type": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 3,
+ "meshShadows": false,
+ "shadowExtent": 8,
+ "enabled": true,
+ "sourceAngle": 0.53
+ }
+ }
+ ]
+ },
+ {
+ "id": 11,
+ "name": "Ambient",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Light",
+ "data": {
+ "type": 2,
+ "intensity": 0.2,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "enabled": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/examples/planar-reflection/assets/scenes/main.esscene.meta b/examples/planar-reflection/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..7d9825cbe
--- /dev/null
+++ b/examples/planar-reflection/assets/scenes/main.esscene.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "b9cc03e6-ee5f-4538-8e6d-94cbf65bdacb",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {}
+}
diff --git a/examples/planar-reflection/project.esproject b/examples/planar-reflection/project.esproject
new file mode 100644
index 000000000..b004a4368
--- /dev/null
+++ b/examples/planar-reflection/project.esproject
@@ -0,0 +1,19 @@
+{
+ "formatVersion": "1",
+ "name": "Planar Reflection",
+ "version": "0.1.0",
+ "defaultScene": "assets/scenes/main.esscene",
+ "designResolution": {
+ "width": 960,
+ "height": 640
+ },
+ "features": {
+ "rendering": {
+ "colorSpace": "linear",
+ "outputTransform": "aces",
+ "quality": {
+ "mode": "medium"
+ }
+ }
+ }
+}
diff --git a/examples/planar-reflection/src/main.ts b/examples/planar-reflection/src/main.ts
new file mode 100644
index 000000000..05bb91a39
--- /dev/null
+++ b/examples/planar-reflection/src/main.ts
@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { addPlugin, defineTag, defineSystem, Res, Query, Mut, Time, Input, Transform,
+ PlanarReflection, Quality } from 'esengine';
+
+export const ReflectionSubject = defineTag('ReflectionSubject');
+addPlugin({
+ name: 'planar-reflection-demo',
+ build(app) {
+ let elapsed = 0;
+ app.addSystem(defineSystem([
+ Res(Time), Res(Input), Res(Quality),
+ Query(Mut(Transform), ReflectionSubject), Query(Mut(PlanarReflection)),
+ ], (time, input, quality, subjects, surfaces) => {
+ elapsed += time.delta;
+ for (const [, transform] of subjects) {
+ transform.position.x = -1.2 + Math.sin(elapsed) * 0.8;
+ transform.rotation = { x: 0, y: Math.sin(elapsed * 0.4), z: 0, w: Math.cos(elapsed * 0.4) };
+ }
+ if (input.isKeyPressed('Space')) {
+ for (const [, surface] of surfaces) surface.enabled = !surface.enabled;
+ }
+ for (const [key, mode] of [['Digit1', 'low'], ['Digit2', 'medium'], ['Digit3', 'high']] as const) {
+ if (input.isKeyPressed(key)) quality?.setMode(mode);
+ }
+ }, { name: 'PlanarReflectionDemo' }));
+ },
+});
diff --git a/examples/planar-reflection/tsconfig.json b/examples/planar-reflection/tsconfig.json
new file mode 100644
index 000000000..105dd19fa
--- /dev/null
+++ b/examples/planar-reflection/tsconfig.json
@@ -0,0 +1,21 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "outDir": "./dist",
+ "rootDir": ".",
+ "paths": {
+ "esengine": ["./.esengine/sdk/index.d.ts"],
+ "estella-plugin-*": ["./.esengine/packages/*"],
+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"]
+ }
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules"]
+}
diff --git a/fixtures/scenes/mat-planar/mirror.esmaterial b/fixtures/scenes/mat-planar/mirror.esmaterial
new file mode 100644
index 000000000..d1dd6983a
--- /dev/null
+++ b/fixtures/scenes/mat-planar/mirror.esmaterial
@@ -0,0 +1,13 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "builtin:model",
+ "blendMode": 9,
+ "depthTest": true,
+ "depthWrite": true,
+ "properties": {
+ "u_metallic": 1,
+ "u_roughness": 0,
+ "u_specular": 1
+ }
+}
diff --git a/fixtures/scenes/planar-reflection.esscene b/fixtures/scenes/planar-reflection.esscene
new file mode 100644
index 000000000..c14e28dea
--- /dev/null
+++ b/fixtures/scenes/planar-reflection.esscene
@@ -0,0 +1,260 @@
+{
+ "version": 4,
+ "name": "Planar Reflection",
+ "entities": [
+ {
+ "id": 1,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 3,
+ "z": 6
+ },
+ "rotation": {
+ "x": -0.22975292,
+ "y": 0,
+ "z": 0,
+ "w": 0.97324899
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 6,
+ "isActive": true,
+ "clearFlags": 3,
+ "backgroundColor": {
+ "r": 0.02,
+ "g": 0.02,
+ "b": 0.02,
+ "a": 1
+ },
+ "nearPlane": 0.1,
+ "farPlane": 100
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Mirror",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "rotation": {
+ "x": -0.70710678,
+ "y": 0,
+ "z": 0,
+ "w": 0.70710678
+ },
+ "scale": {
+ "x": 7,
+ "y": 7,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "/scenes/shadow-quad.esmesh",
+ "material": "/scenes/mat-planar/mirror.esmaterial",
+ "opaque": true,
+ "lit": true,
+ "enabled": true
+ }
+ },
+ {
+ "type": "PlanarReflection",
+ "data": {
+ "axis": 2,
+ "quality": 1,
+ "resolutionScale": 1,
+ "maxSize": 512,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Red",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -1.3,
+ "y": 1.0,
+ "z": 0
+ },
+ "scale": {
+ "x": 0.01,
+ "y": 0.01,
+ "z": 0.01
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "cullBackfaces": true,
+ "lit": false,
+ "layer": 1,
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Green",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 1.3,
+ "y": 0.7,
+ "z": -0.8
+ },
+ "scale": {
+ "x": 0.007,
+ "y": 0.007,
+ "z": 0.007
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "cullBackfaces": true,
+ "lit": false,
+ "layer": 2,
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "Below plane",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": -1,
+ "z": 0
+ },
+ "scale": {
+ "x": 0.007,
+ "y": 0.007,
+ "z": 0.007
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "lit": false,
+ "color": {
+ "r": 0,
+ "g": 0,
+ "b": 1,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 6,
+ "name": "Second camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 1.5,
+ "y": 3,
+ "z": 6
+ },
+ "rotation": {
+ "x": -0.22975292,
+ "y": 0,
+ "z": 0,
+ "w": 0.97324899
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 6,
+ "isActive": false,
+ "clearFlags": 3,
+ "backgroundColor": {
+ "r": 0.02,
+ "g": 0.02,
+ "b": 0.02,
+ "a": 1
+ },
+ "nearPlane": 0.1,
+ "farPlane": 100,
+ "priority": 1,
+ "viewport": {
+ "x": 0.5,
+ "y": 0,
+ "z": 0.5,
+ "w": 1
+ }
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index b050a91ac..2765f2102 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: 115 public · 152 beta · 1612 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1620 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"2f29375a9e0f797d"
+"2f5ac38ffa80eb57"
```
## ANCHOR_AXES — const @experimental
@@ -6137,6 +6137,36 @@ LayoutWorld & Pick<World, 'getAllEntities'>
Pick<World, 'getCppRegistry' | 'getWasmModule'>
```
+## PlanarReflection — const @experimental
+```
+BuiltinComponentDef<PlanarReflectionData>
+```
+
+## PlanarReflectionData — interface @experimental
+```
+axis: ReflectionAxis
+clipOffset: number
+cullingMask: number
+enabled: boolean
+maxSize: number
+quality: ReflectionQuality
+resolutionScale: number
+revision: number
+update: ReflectionUpdate
+updatesPerSecond: number
+```
+
+## PlanarReflectionStatus — interface @experimental
+```
+bytes: number | undefined
+draws: number | undefined
+height: number | undefined
+rejected: number | undefined
+state: "unavailable" | "inactive" | "budget-excluded" | "ready"
+updated: boolean | undefined
+width: number | undefined
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -6895,6 +6925,9 @@ static prototype: QualityController
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
+planarReflectionMaxSize: number
+planarReflectionScale: number
+planarReflectionUpdatesPerSecond: number
postProcess: boolean
renderScale: number
shadowAtlasSize: number
@@ -7016,6 +7049,13 @@ get: () => T
subscribe: (fn: (value: T) => void) => () => void
```
+## ReflectionAxis — enum @experimental
+```
+X = 0
+Y = 1
+Z = 2
+```
+
## ReflectionProbe — const @experimental
```
BuiltinComponentDef<ReflectionProbeData>
@@ -7029,6 +7069,19 @@ reflection: number
slot: number
```
+## ReflectionQuality — enum @experimental
+```
+Custom = 1
+Project = 0
+```
+
+## ReflectionUpdate — enum @experimental
+```
+EveryFrame = 0
+FixedRate = 1
+OnDemand = 2
+```
+
## ReliableOrderedTransport — interface @experimental
```
delivery: "reliable-ordered"
@@ -12916,6 +12969,11 @@ ParticlePlugin
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
```
+## planarReflectionStatus — function @experimental
+```
+(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -13171,6 +13229,11 @@ PrefabsPlugin
(source: string): ShaderReflection
```
+## refreshPlanarReflection — function @experimental
+```
+(app: App, entity: Entity): void
+```
+
## registerAction — function @experimental
```
(name: string, fn: AiAction<AiContext> | AiActionSpec<AiContext>): void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 1daa742ba..b71da9a3a 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: 115 public · 157 beta · 1631 experimental · 3 deprecated
+Symbols: 115 public · 157 beta · 1639 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"2f29375a9e0f797d"
+"2f5ac38ffa80eb57"
```
## ANCHOR_AXES — const @experimental
@@ -6340,6 +6340,36 @@ LayoutWorld & Pick<World, 'getAllEntities'>
Pick<World, 'getCppRegistry' | 'getWasmModule'>
```
+## PlanarReflection — const @experimental
+```
+BuiltinComponentDef<PlanarReflectionData>
+```
+
+## PlanarReflectionData — interface @experimental
+```
+axis: ReflectionAxis
+clipOffset: number
+cullingMask: number
+enabled: boolean
+maxSize: number
+quality: ReflectionQuality
+resolutionScale: number
+revision: number
+update: ReflectionUpdate
+updatesPerSecond: number
+```
+
+## PlanarReflectionStatus — interface @experimental
+```
+bytes: number | undefined
+draws: number | undefined
+height: number | undefined
+rejected: number | undefined
+state: "unavailable" | "inactive" | "budget-excluded" | "ready"
+updated: boolean | undefined
+width: number | undefined
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -7098,6 +7128,9 @@ static prototype: QualityController
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
+planarReflectionMaxSize: number
+planarReflectionScale: number
+planarReflectionUpdatesPerSecond: number
postProcess: boolean
renderScale: number
shadowAtlasSize: number
@@ -7229,6 +7262,13 @@ get: () => T
subscribe: (fn: (value: T) => void) => () => void
```
+## ReflectionAxis — enum @experimental
+```
+X = 0
+Y = 1
+Z = 2
+```
+
## ReflectionProbe — const @experimental
```
BuiltinComponentDef<ReflectionProbeData>
@@ -7242,6 +7282,19 @@ reflection: number
slot: number
```
+## ReflectionQuality — enum @experimental
+```
+Custom = 1
+Project = 0
+```
+
+## ReflectionUpdate — enum @experimental
+```
+EveryFrame = 0
+FixedRate = 1
+OnDemand = 2
+```
+
## ReliableOrderedTransport — interface @experimental
```
delivery: "reliable-ordered"
@@ -13179,6 +13232,11 @@ ParticlePlugin
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
```
+## planarReflectionStatus — function @experimental
+```
+(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -13434,6 +13492,11 @@ PrefabsPlugin
(source: string): ShaderReflection
```
+## refreshPlanarReflection — function @experimental
+```
+(app: App, entity: Entity): void
+```
+
## registerAction — function @experimental
```
(name: string, fn: AiAction<AiContext> | AiActionSpec<AiContext>): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 9082c05d5..4babdc884 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: 115 public · 154 beta · 1611 experimental · 3 deprecated
+Symbols: 115 public · 154 beta · 1619 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6132,6 +6132,36 @@ LayoutWorld & Pick<World, 'getAllEntities'>
Pick<World, 'getCppRegistry' | 'getWasmModule'>
```
+## PlanarReflection — const @experimental
+```
+BuiltinComponentDef<PlanarReflectionData>
+```
+
+## PlanarReflectionData — interface @experimental
+```
+axis: ReflectionAxis
+clipOffset: number
+cullingMask: number
+enabled: boolean
+maxSize: number
+quality: ReflectionQuality
+resolutionScale: number
+revision: number
+update: ReflectionUpdate
+updatesPerSecond: number
+```
+
+## PlanarReflectionStatus — interface @experimental
+```
+bytes: number | undefined
+draws: number | undefined
+height: number | undefined
+rejected: number | undefined
+state: "unavailable" | "inactive" | "budget-excluded" | "ready"
+updated: boolean | undefined
+width: number | undefined
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -6890,6 +6920,9 @@ static prototype: QualityController
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
+planarReflectionMaxSize: number
+planarReflectionScale: number
+planarReflectionUpdatesPerSecond: number
postProcess: boolean
renderScale: number
shadowAtlasSize: number
@@ -7011,6 +7044,13 @@ get: () => T
subscribe: (fn: (value: T) => void) => () => void
```
+## ReflectionAxis — enum @experimental
+```
+X = 0
+Y = 1
+Z = 2
+```
+
## ReflectionProbe — const @experimental
```
BuiltinComponentDef<ReflectionProbeData>
@@ -7024,6 +7064,19 @@ reflection: number
slot: number
```
+## ReflectionQuality — enum @experimental
+```
+Custom = 1
+Project = 0
+```
+
+## ReflectionUpdate — enum @experimental
+```
+EveryFrame = 0
+FixedRate = 1
+OnDemand = 2
+```
+
## ReliableOrderedTransport — interface @experimental
```
delivery: "reliable-ordered"
@@ -12921,6 +12974,11 @@ ParticlePlugin
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
```
+## planarReflectionStatus — function @experimental
+```
+(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -13176,6 +13234,11 @@ PrefabsPlugin
(source: string): ShaderReflection
```
+## refreshPlanarReflection — function @experimental
+```
+(app: App, entity: Entity): void
+```
+
## registerAction — function @experimental
```
(name: string, fn: AiAction<AiContext> | AiActionSpec<AiContext>): void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index cac311fc4..f7fd6e960 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: 115 public · 152 beta · 1633 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1641 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6425,6 +6425,36 @@ LayoutWorld & Pick<World, 'getAllEntities'>
Pick<World, 'getCppRegistry' | 'getWasmModule'>
```
+## PlanarReflection — const @experimental
+```
+BuiltinComponentDef<PlanarReflectionData>
+```
+
+## PlanarReflectionData — interface @experimental
+```
+axis: ReflectionAxis
+clipOffset: number
+cullingMask: number
+enabled: boolean
+maxSize: number
+quality: ReflectionQuality
+resolutionScale: number
+revision: number
+update: ReflectionUpdate
+updatesPerSecond: number
+```
+
+## PlanarReflectionStatus — interface @experimental
+```
+bytes: number | undefined
+draws: number | undefined
+height: number | undefined
+rejected: number | undefined
+state: "unavailable" | "inactive" | "budget-excluded" | "ready"
+updated: boolean | undefined
+width: number | undefined
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -7183,6 +7213,9 @@ static prototype: QualityController
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
+planarReflectionMaxSize: number
+planarReflectionScale: number
+planarReflectionUpdatesPerSecond: number
postProcess: boolean
renderScale: number
shadowAtlasSize: number
@@ -7304,6 +7337,13 @@ get: () => T
subscribe: (fn: (value: T) => void) => () => void
```
+## ReflectionAxis — enum @experimental
+```
+X = 0
+Y = 1
+Z = 2
+```
+
## ReflectionProbe — const @experimental
```
BuiltinComponentDef<ReflectionProbeData>
@@ -7317,6 +7357,19 @@ reflection: number
slot: number
```
+## ReflectionQuality — enum @experimental
+```
+Custom = 1
+Project = 0
+```
+
+## ReflectionUpdate — enum @experimental
+```
+EveryFrame = 0
+FixedRate = 1
+OnDemand = 2
+```
+
## ReliableOrderedTransport — interface @experimental
```
delivery: "reliable-ordered"
@@ -13225,6 +13278,11 @@ ParticlePlugin
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
```
+## planarReflectionStatus — function @experimental
+```
+(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -13480,6 +13538,11 @@ PrefabsPlugin
(source: string): ShaderReflection
```
+## refreshPlanarReflection — function @experimental
+```
+(app: App, entity: Entity): void
+```
+
## registerAction — function @experimental
```
(name: string, fn: AiAction<AiContext> | AiActionSpec<AiContext>): void
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 2fd7d1f8b..d3b8b7071 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -41,6 +41,7 @@ addOccluder: (entity: Entity, component: Occluder) => void
addParent: (entity: Entity, component: Parent) => void
addParticleEmitter: (entity: Entity, component: ParticleEmitter) => void
addParticleForceField: (entity: Entity, component: ParticleForceField) => void
+addPlanarReflection: (entity: Entity, component: PlanarReflection) => void
addReflectionProbe: (entity: Entity, component: ReflectionProbe) => void
addRigidBody2D: (entity: Entity, component: RigidBody2D) => void
addRigidBody3D: (entity: Entity, component: RigidBody3D) => void
@@ -95,6 +96,7 @@ getOccluder: (entity: Entity) => Occluder
getParent: (entity: Entity) => Parent
getParticleEmitter: (entity: Entity) => ParticleEmitter
getParticleForceField: (entity: Entity) => ParticleForceField
+getPlanarReflection: (entity: Entity) => PlanarReflection
getReflectionProbe: (entity: Entity) => ReflectionProbe
getRigidBody2D: (entity: Entity) => RigidBody2D
getRigidBody3D: (entity: Entity) => RigidBody3D
@@ -143,6 +145,7 @@ hasOccluder: (entity: Entity) => boolean
hasParent: (entity: Entity) => boolean
hasParticleEmitter: (entity: Entity) => boolean
hasParticleForceField: (entity: Entity) => boolean
+hasPlanarReflection: (entity: Entity) => boolean
hasReflectionProbe: (entity: Entity) => boolean
hasRigidBody2D: (entity: Entity) => boolean
hasRigidBody3D: (entity: Entity) => boolean
@@ -194,6 +197,7 @@ removeOccluder: (entity: Entity) => void
removeParent: (entity: Entity) => void
removeParticleEmitter: (entity: Entity) => void
removeParticleForceField: (entity: Entity) => void
+removePlanarReflection: (entity: Entity) => void
removeReflectionProbe: (entity: Entity) => void
removeRigidBody2D: (entity: Entity) => void
removeRigidBody3D: (entity: Entity) => void
@@ -453,6 +457,7 @@ renderer_getEstimatedGpuBytes: (() => number) | undefined
renderer_getGpuTimeMs: (() => number) | undefined
renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefined
renderer_getMeshes: () => number
+renderer_getPlanarReflectionStatus: ((view: number, entity: number) => string) | undefined
renderer_getPreviewHeight: () => number
renderer_getPreviewPtr: () => number
renderer_getPreviewSize: () => number
@@ -494,6 +499,7 @@ renderer_setDepthLayers: ((mask: number) => void) | undefined
renderer_setEntityDrawOrder: ((registry: CppRegistry, entitiesPtr: number, count: number) => void) | undefined
renderer_setLodPreview: ((view: number, entity: number, level: number) => void) | undefined
renderer_setMeshEdgeBuffers: ((enabled: boolean) => void) | undefined
+renderer_setPlanarReflectionQuality: ((scale: number, maxSize: number, updatesPerSecond: number) => void) | undefined
renderer_setQualityBudgets: ((atlasSize: number, cellSize: number, cascades: number, particleLimit: number) => void) | undefined
renderer_setShadowDistance: ((distance: number) => void) | undefined
renderer_setStage: (stage: number) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 1c5842c4a..e07e96d3a 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: 115 public · 152 beta · 1624 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1632 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6139,6 +6139,36 @@ LayoutWorld & Pick<World, 'getAllEntities'>
Pick<World, 'getCppRegistry' | 'getWasmModule'>
```
+## PlanarReflection — const @experimental
+```
+BuiltinComponentDef<PlanarReflectionData>
+```
+
+## PlanarReflectionData — interface @experimental
+```
+axis: ReflectionAxis
+clipOffset: number
+cullingMask: number
+enabled: boolean
+maxSize: number
+quality: ReflectionQuality
+resolutionScale: number
+revision: number
+update: ReflectionUpdate
+updatesPerSecond: number
+```
+
+## PlanarReflectionStatus — interface @experimental
+```
+bytes: number | undefined
+draws: number | undefined
+height: number | undefined
+rejected: number | undefined
+state: "unavailable" | "inactive" | "budget-excluded" | "ready"
+updated: boolean | undefined
+width: number | undefined
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -6897,6 +6927,9 @@ static prototype: QualityController
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
+planarReflectionMaxSize: number
+planarReflectionScale: number
+planarReflectionUpdatesPerSecond: number
postProcess: boolean
renderScale: number
shadowAtlasSize: number
@@ -7018,6 +7051,13 @@ get: () => T
subscribe: (fn: (value: T) => void) => () => void
```
+## ReflectionAxis — enum @experimental
+```
+X = 0
+Y = 1
+Z = 2
+```
+
## ReflectionProbe — const @experimental
```
BuiltinComponentDef<ReflectionProbeData>
@@ -7031,6 +7071,19 @@ reflection: number
slot: number
```
+## ReflectionQuality — enum @experimental
+```
+Custom = 1
+Project = 0
+```
+
+## ReflectionUpdate — enum @experimental
+```
+EveryFrame = 0
+FixedRate = 1
+OnDemand = 2
+```
+
## ReliableOrderedTransport — interface @experimental
```
delivery: "reliable-ordered"
@@ -12952,6 +13005,11 @@ ParticlePlugin
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
```
+## planarReflectionStatus — function @experimental
+```
+(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -13207,6 +13265,11 @@ PrefabsPlugin
(source: string): ShaderReflection
```
+## refreshPlanarReflection — function @experimental
+```
+(app: App, entity: Entity): void
+```
+
## registerAction — function @experimental
```
(name: string, fn: AiAction<AiContext> | AiActionSpec<AiContext>): void
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 9e2149a3b..e9ae00f75 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -16,6 +16,7 @@
// =============================================================================
export { Filters } from './render/filters';
+export { planarReflectionStatus, refreshPlanarReflection, type PlanarReflectionStatus } from './render/planarReflection';
export { LIGHT_FORWARD, lightAimRotation, lightAimOf } from './render/lightAim';
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index bd1636e7f..0974b2fd1 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -102,6 +102,9 @@ export {
type OccluderData,
ReflectionProbe,
type ReflectionProbeData,
+ PlanarReflection,
+ type PlanarReflectionData,
+ ReflectionAxis, ReflectionQuality, ReflectionUpdate,
SortingGroup,
SpriteMask,
TrailRenderer,
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index f643a5b10..ea183698c 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -169,6 +169,7 @@ export interface NativeEngineApi {
renderer_getEstimatedGpuBytes?(): number;
renderer_getGpuTimeMs?(): number;
renderer_getMeshes?(): number;
+ renderer_getPlanarReflectionStatus?(view: number, entity: number): string;
renderer_getPreviewHeight?(): number;
renderer_getPreviewSize?(): number;
renderer_getPreviewWidth?(): number;
@@ -207,6 +208,7 @@ export interface NativeEngineApi {
renderer_setEntityDrawOrder?(registry: unknown, entitiesPtr: number, count: number): void;
renderer_setLodPreview?(view: number, entity: number, level: number): void;
renderer_setMeshEdgeBuffers?(enabled: boolean): void;
+ renderer_setPlanarReflectionQuality?(scale: number, maxSize: number, updatesPerSecond: number): void;
renderer_setQualityBudgets?(atlasSize: number, cellSize: number, cascades: number, particleLimit: number): void;
renderer_setShadowDistance?(distance: number): void;
renderer_setStage?(stage: number): void;
@@ -480,6 +482,7 @@ export function createNativeEngineApi(
bind('renderer_getEstimatedGpuBytes', 'es_renderer_getEstimatedGpuBytes', false);
bind('renderer_getGpuTimeMs', 'es_renderer_getGpuTimeMs', false);
bind('renderer_getMeshes', 'es_renderer_getMeshes', false);
+ bind('renderer_getPlanarReflectionStatus', 'es_renderer_getPlanarReflectionStatus', false);
bind('renderer_getPreviewHeight', 'es_renderer_getPreviewHeight', false);
bind('renderer_getPreviewSize', 'es_renderer_getPreviewSize', false);
bind('renderer_getPreviewWidth', 'es_renderer_getPreviewWidth', false);
@@ -518,6 +521,7 @@ export function createNativeEngineApi(
bind('renderer_setEntityDrawOrder', 'es_renderer_setEntityDrawOrder', true);
bind('renderer_setLodPreview', 'es_renderer_setLodPreview', false);
bind('renderer_setMeshEdgeBuffers', 'es_renderer_setMeshEdgeBuffers', false);
+ bind('renderer_setPlanarReflectionQuality', 'es_renderer_setPlanarReflectionQuality', false);
bind('renderer_setQualityBudgets', 'es_renderer_setQualityBudgets', false);
bind('renderer_setShadowDistance', 'es_renderer_setShadowDistance', false);
bind('renderer_setStage', 'es_renderer_setStage', false);
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 739ac9d91..b58a4e895 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -1421,6 +1421,66 @@ export function createParticleForceFieldData(): ParticleForceFieldPtrData {
};
}
+export interface PlanarReflectionPtrData {
+ axis: number;
+ clipOffset: number;
+ cullingMask: number;
+ quality: number;
+ resolutionScale: number;
+ maxSize: number;
+ update: number;
+ updatesPerSecond: number;
+ revision: number;
+ enabled: boolean;
+}
+
+export function fillPlanarReflection(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, out: PlanarReflectionPtrData,
+): void {
+ out.axis = u8[ptr];
+ out.clipOffset = f32[(ptr + 4) >> 2];
+ out.cullingMask = u32[(ptr + 8) >> 2];
+ out.quality = u8[ptr + 12];
+ out.resolutionScale = f32[(ptr + 16) >> 2];
+ out.maxSize = u32[(ptr + 20) >> 2];
+ out.update = u8[ptr + 24];
+ out.updatesPerSecond = f32[(ptr + 28) >> 2];
+ out.revision = u32[(ptr + 32) >> 2];
+ out.enabled = u8[ptr + 36] !== 0;
+}
+
+export function writePlanarReflection(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, data: PlanarReflectionPtrData,
+): void {
+ u8[ptr] = data.axis;
+ f32[(ptr + 4) >> 2] = data.clipOffset;
+ u32[(ptr + 8) >> 2] = data.cullingMask;
+ u8[ptr + 12] = data.quality;
+ f32[(ptr + 16) >> 2] = data.resolutionScale;
+ u32[(ptr + 20) >> 2] = data.maxSize;
+ u8[ptr + 24] = data.update;
+ f32[(ptr + 28) >> 2] = data.updatesPerSecond;
+ u32[(ptr + 32) >> 2] = data.revision;
+ u8[ptr + 36] = data.enabled ? 1 : 0;
+}
+
+export function createPlanarReflectionData(): PlanarReflectionPtrData {
+ return {
+ axis: 0,
+ clipOffset: 0,
+ cullingMask: 0,
+ quality: 0,
+ resolutionScale: 0,
+ maxSize: 0,
+ update: 0,
+ updatesPerSecond: 0,
+ revision: 0,
+ enabled: false,
+ };
+}
+
export interface ReflectionProbePtrData {
reflection: number;
halfExtents: Vec3;
@@ -2495,6 +2555,7 @@ export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {
Occluder: { fill: fillOccluder, write: writeOccluder, create: createOccluderData },
ParticleEmitter: { fill: fillParticleEmitter, write: writeParticleEmitter, create: createParticleEmitterData },
ParticleForceField: { fill: fillParticleForceField, write: writeParticleForceField, create: createParticleForceFieldData },
+ PlanarReflection: { fill: fillPlanarReflection, write: writePlanarReflection, create: createPlanarReflectionData },
ReflectionProbe: { fill: fillReflectionProbe, write: writeReflectionProbe, create: createReflectionProbeData },
RigidBody2D: { fill: fillRigidBody2D, write: writeRigidBody2D, create: createRigidBody2DData },
RigidBody3D: { fill: fillRigidBody3D, write: writeRigidBody3D, create: createRigidBody3DData },
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index f288b79bf..8ec0354de 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -7,7 +7,7 @@
import type { AssetFieldType } from '../scene/scene';
import type { FieldMeta } from './component';
import type { Color, Entity, Quat, Vec2, Vec3, Vec4 } from '../types';
-import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, ClearFlags, Dimension, EmitterShape, FlexDirection, FlexWrap, ForceFieldType, JustifyContent, LightType, MaskMode, Padding, ParticleCollisionFallback, ParticleCollisionMode, ParticleEasing, ProjectionType, ScrollMovement, ShapeType, SimulationSpace, SpriteDrawMode, SpriteMaskInteraction, SubEmitterTrigger, TextAlign, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex, UIDisplay, UIFillMethod, UIFillOrigin, UIPointerEvents, UIPositionType, UIVisualFit, UIVisualType } from '../wasm/wasm.generated';
+import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, ClearFlags, Dimension, EmitterShape, FlexDirection, FlexWrap, ForceFieldType, JustifyContent, LightType, MaskMode, Padding, ParticleCollisionFallback, ParticleCollisionMode, ParticleEasing, ProjectionType, ReflectionAxis, ReflectionQuality, ReflectionUpdate, ScrollMovement, ShapeType, SimulationSpace, SpriteDrawMode, SpriteMaskInteraction, SubEmitterTrigger, TextAlign, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex, UIDisplay, UIFillMethod, UIFillOrigin, UIPointerEvents, UIPositionType, UIVisualFit, UIVisualType } from '../wasm/wasm.generated';
/**
* Single-source-of-truth hash of the C++/TS boundary ABI (component
@@ -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 = '2f29375a9e0f797d';
+export const ABI_LAYOUT_HASH = '2f5ac38ffa80eb57';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -798,6 +798,35 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
falloff: { category: "Field" },
},
},
+ PlanarReflection: {
+ defaults: {
+ axis: 1,
+ clipOffset: 0.02,
+ cullingMask: 4294967295,
+ quality: 0,
+ resolutionScale: 0.5,
+ maxSize: 1024,
+ update: 0,
+ updatesPerSecond: 30,
+ revision: 0,
+ enabled: true,
+ },
+ assetFields: [],
+ entityFields: [],
+ colorFields: [],
+ animatableFields: [],
+ fields: {
+ axis: { enum: [{ label: 'X', value: 0 }, { label: 'Y', value: 1 }, { label: 'Z', value: 2 }], tooltip: "Local normal axis, transformed with the entity. Y for a floor, Z for a mirror.", category: "Capture" },
+ clipOffset: { min: 0, step: 0.005, tooltip: "Clip offset in world units; excludes geometry behind the reflecting plane.", category: "Capture" },
+ cullingMask: { tooltip: "Sorting-layer bits captured by the reflection. The receiving surface and screen UI are excluded.", category: "Capture", bitmask: { source: "sortingLayers" } },
+ quality: { enum: [{ label: 'Project', value: 0 }, { label: 'Custom', value: 1 }], category: "Quality" },
+ resolutionScale: { min: 0.125, max: 1, step: 0.125, category: "Quality", shownWhen: { field: "quality", values: [1] } },
+ maxSize: { min: 64, max: 4096, step: 64, category: "Quality", shownWhen: { field: "quality", values: [1] } },
+ update: { enum: [{ label: 'EveryFrame', value: 0 }, { label: 'FixedRate', value: 1 }, { label: 'OnDemand', value: 2 }], tooltip: "Only the reflection capture; never limits the main scene frame rate.", category: "Quality", shownWhen: { field: "quality", values: [1] } },
+ updatesPerSecond: { min: 1, max: 120, category: "Quality", shownWhen: { field: "update", values: [1] } },
+ revision: { advanced: true },
+ },
+ },
ReflectionProbe: {
defaults: {
reflection: 0,
@@ -1618,6 +1647,25 @@ export interface ParticleForceFieldData {
enabled: boolean;
}
+/**
+ * The fields of the engine's `PlanarReflection` component, generated from
+ * the C++ struct so the two shapes cannot drift.
+ *
+ * @experimental
+ */
+export interface PlanarReflectionData {
+ axis: ReflectionAxis;
+ clipOffset: number;
+ cullingMask: number;
+ quality: ReflectionQuality;
+ resolutionScale: number;
+ maxSize: number;
+ update: ReflectionUpdate;
+ updatesPerSecond: number;
+ revision: number;
+ enabled: boolean;
+}
+
/**
* The fields of the engine's `ReflectionProbe` 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 dfdc4094a..eafcd70c6 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -17,7 +17,7 @@ export type { AssetFieldMeta, SkeletalFieldMeta };
import type {
TransformData, SpriteData, ShapeRendererData, LightData, ShadowCaster2DData, DraggableData,
SortingGroupData, SpriteMaskData, LightProbeVolumeData, OccluderData,
- ReflectionProbeData,
+ ReflectionProbeData, PlanarReflectionData,
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData, DragonBonesAnimationData,
TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData,
CameraData as CameraDataCpp, ParticleEmitterData as ParticleEmitterDataCpp,
@@ -28,7 +28,7 @@ import type {
// C++ enum and the editor dropdowns derive from the same values. ScaleMode's
// canonical values come from CanvasScaleMode (only its Cocos-compat aliases
// ShowAll/NoBorder are TS-side).
-import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, ForceFieldType, LightType, CanvasScaleMode, ShapeType, ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, SpriteMaskInteraction, SpriteDrawMode } from '../wasm/wasm.generated';
+import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, ForceFieldType, LightType, CanvasScaleMode, ShapeType, ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ReflectionAxis, ReflectionQuality, ReflectionUpdate, SpriteMaskInteraction, SpriteDrawMode } from '../wasm/wasm.generated';
import { BlendMode } from '../render/blend';
import { getDefaultContext } from './context';
import type {
@@ -831,7 +831,7 @@ export type ScaleMode = (typeof ScaleMode)[keyof typeof ScaleMode];
export type {
TransformData, SpriteData, ShapeRendererData, LightData, ShadowCaster2DData, DraggableData,
SortingGroupData, SpriteMaskData, LightProbeVolumeData, OccluderData,
- ReflectionProbeData,
+ ReflectionProbeData, PlanarReflectionData,
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData, DragonBonesAnimationData,
TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData,
};
@@ -954,6 +954,11 @@ export const LightProbeVolume = defineBuiltin<LightProbeVolumeData>('LightProbeV
metaDefaults<LightProbeVolumeData>('LightProbeVolume')
);
+/** A non-recursive planar capture, received by this entity's lit material. @experimental */
+export const PlanarReflection = defineBuiltin<PlanarReflectionData>('PlanarReflection',
+ metaDefaults<PlanarReflectionData>('PlanarReflection')
+);
+
/**
* A box inside which reflections come from a bake rather than from the sky: the
* specular half of what LightProbeVolume answers. The atlas is the SCENE's and
@@ -1167,7 +1172,7 @@ export const TilemapLayer = defineBuiltin<TilemapLayerData>('TilemapLayer',
// EmitterShape, SimulationSpace and ParticleEasing are re-exported from the
// generated module (see the import at the top) — single-sourced from their C++
// ES_ENUMs beside the component fields that serialize them.
-export { ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback };
+export { ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ReflectionAxis, ReflectionQuality, ReflectionUpdate };
// =============================================================================
// ParticleEmitter Component
diff --git a/sdk/src/render/planarReflection.ts b/sdk/src/render/planarReflection.ts
new file mode 100644
index 000000000..86cef7d6a
--- /dev/null
+++ b/sdk/src/render/planarReflection.ts
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { App } from '../app/app';
+import type { Entity } from '../types';
+import { engineApi } from '../ecs/bridge/engineApi';
+import { PlanarReflection } from '../ecs/component';
+
+/** The latest capture for one surface in one view. @experimental */
+export interface PlanarReflectionStatus {
+ state: 'inactive' | 'budget-excluded' | 'unavailable' | 'ready';
+ width?: number;
+ height?: number;
+ draws?: number;
+ bytes?: number;
+ rejected?: number;
+ updated?: boolean;
+}
+
+/** View 0 is the manual/editor view; game views use their runtime camera entity. @experimental */
+export function planarReflectionStatus(app: App, entity: Entity, view: Entity = 0): PlanarReflectionStatus {
+ const read = engineApi(app)?.renderer_getPlanarReflectionStatus;
+ if (!read) return { state: 'unavailable' };
+ return JSON.parse(read(view >>> 0, entity >>> 0)) as PlanarReflectionStatus;
+}
+
+/** Refreshes an OnDemand capture through the same component mutation path as authoring. @experimental */
+export function refreshPlanarReflection(app: App, entity: Entity): void {
+ const value = app.world.get(entity, PlanarReflection);
+ app.world.set(entity, PlanarReflection, { ...value, revision: (value.revision + 1) >>> 0 });
+}
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index f4a2e7a46..fc3d36c26 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -20,6 +20,10 @@ export interface QualityProfile {
shadowCascades: number;
shadowDistance: number;
particleLimit: number;
+ planarReflectionScale: number;
+ planarReflectionMaxSize: number;
+ /** Zero means every frame; this never caps the main scene. */
+ planarReflectionUpdatesPerSecond: number;
postProcess: boolean;
ssao: boolean;
}
@@ -46,16 +50,19 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
low: {
renderScale: 0.75, minRenderScale: 0.5, msaaSamples: 1,
shadowAtlasSize: 1024, shadowCellSize: 256, shadowCascades: 2,
+ planarReflectionScale: 0.25, planarReflectionMaxSize: 512, planarReflectionUpdatesPerSecond: 0,
shadowDistance: 0, particleLimit: 1000, postProcess: true, ssao: false,
},
medium: {
renderScale: 1, minRenderScale: 0.65, msaaSamples: 2,
shadowAtlasSize: 2048, shadowCellSize: 512, shadowCascades: 3,
+ planarReflectionScale: 0.5, planarReflectionMaxSize: 1024, planarReflectionUpdatesPerSecond: 0,
shadowDistance: 0, particleLimit: 5000, postProcess: true, ssao: true,
},
high: {
renderScale: 1, minRenderScale: 0.75, msaaSamples: 4,
shadowAtlasSize: 2048, shadowCellSize: 512, shadowCascades: 4,
+ planarReflectionScale: 1, planarReflectionMaxSize: 2048, planarReflectionUpdatesPerSecond: 0,
shadowDistance: 0, particleLimit: 20000, postProcess: true, ssao: true,
},
};
@@ -124,6 +131,9 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
shadowCascades: Math.round(finite(r.shadowCascades, base.shadowCascades, 1, 4)),
shadowDistance: finite(r.shadowDistance, base.shadowDistance, 0, 10000000),
particleLimit: Math.round(finite(r.particleLimit, base.particleLimit, 0, 1000000)),
+ planarReflectionScale: finite(r.planarReflectionScale, base.planarReflectionScale, 0.125, 1),
+ planarReflectionMaxSize: Math.round(finite(r.planarReflectionMaxSize, base.planarReflectionMaxSize, 64, 4096)),
+ planarReflectionUpdatesPerSecond: finite(r.planarReflectionUpdatesPerSecond, base.planarReflectionUpdatesPerSecond, 0, 120),
postProcess: typeof r.postProcess === 'boolean' ? r.postProcess : base.postProcess,
ssao: typeof r.ssao === 'boolean' ? r.ssao : base.ssao,
};
diff --git a/sdk/src/render/qualityRuntime.ts b/sdk/src/render/qualityRuntime.ts
index 94faf7f58..c8eaef697 100644
--- a/sdk/src/render/qualityRuntime.ts
+++ b/sdk/src/render/qualityRuntime.ts
@@ -39,6 +39,9 @@ export function installQuality(app: App, config: QualityConfig, authoredMsaa: nu
quality.setLimitation('shadow-distance-unavailable',
enabled && applied.shadowDistance > 0 && !api?.renderer_setShadowDistance);
api?.renderer_setShadowDistance?.(enabled ? applied.shadowDistance : 0);
+ api?.renderer_setPlanarReflectionQuality?.(enabled ? applied.planarReflectionScale : 0.5,
+ enabled ? applied.planarReflectionMaxSize : 1024,
+ enabled ? applied.planarReflectionUpdatesPerSecond : 0);
};
app.pipeline?.setQuality(quality, apply);
apply();
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 4e82eedf3..7d5ed48dc 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -675,6 +675,8 @@ export interface ESEngineModule {
renderer_setQualityBudgets?(atlasSize: number, cellSize: number,
cascades: number, particleLimit: number): void;
renderer_setShadowDistance?(distance: number): void;
+ renderer_setPlanarReflectionQuality?(scale: number, maxSize: number, updatesPerSecond: number): void;
+ renderer_getPlanarReflectionStatus?(view: number, entity: number): string;
renderer_setViewLighting?(mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean): void;
renderer_setCullingMask?(mask: number): void;
renderer_setViewId?(view: number): void;
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 121aa454e..72f140de9 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -380,6 +380,21 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'enabled', type: 'bool', offset: 25 },
],
},
+ PlanarReflection: {
+ ptrFn: 'getPlanarReflectionPtr',
+ fields: [
+ { name: 'axis', type: 'u8', offset: 0 },
+ { name: 'clipOffset', type: 'f32', offset: 4 },
+ { name: 'cullingMask', type: 'u32', offset: 8 },
+ { name: 'quality', type: 'u8', offset: 12 },
+ { name: 'resolutionScale', type: 'f32', offset: 16 },
+ { name: 'maxSize', type: 'u32', offset: 20 },
+ { name: 'update', type: 'u8', offset: 24 },
+ { name: 'updatesPerSecond', type: 'f32', offset: 28 },
+ { name: 'revision', type: 'u32', offset: 32 },
+ { name: 'enabled', type: 'bool', offset: 36 },
+ ],
+ },
ReflectionProbe: {
ptrFn: 'getReflectionProbePtr',
fields: [
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 7a9b4996a..802b2098d 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -213,6 +213,23 @@ export enum ProjectionType {
Orthographic = 1,
}
+export enum ReflectionAxis {
+ X = 0,
+ Y = 1,
+ Z = 2,
+}
+
+export enum ReflectionQuality {
+ Project = 0,
+ Custom = 1,
+}
+
+export enum ReflectionUpdate {
+ EveryFrame = 0,
+ FixedRate = 1,
+ OnDemand = 2,
+}
+
export enum ScrollMovement {
Clamped = 0,
Elastic = 1,
@@ -734,6 +751,19 @@ export interface ParticleForceField {
enabled: boolean;
}
+export interface PlanarReflection {
+ axis: number;
+ clipOffset: number;
+ cullingMask: number;
+ quality: number;
+ resolutionScale: number;
+ maxSize: number;
+ update: number;
+ updatesPerSecond: number;
+ revision: number;
+ enabled: boolean;
+}
+
export interface ReflectionProbe {
reflection: number;
halfExtents: Vec3;
@@ -1079,6 +1109,10 @@ export interface Registry {
getParticleForceField(entity: Entity): ParticleForceField;
addParticleForceField(entity: Entity, component: ParticleForceField): void;
removeParticleForceField(entity: Entity): void;
+ hasPlanarReflection(entity: Entity): boolean;
+ getPlanarReflection(entity: Entity): PlanarReflection;
+ addPlanarReflection(entity: Entity, component: PlanarReflection): void;
+ removePlanarReflection(entity: Entity): void;
hasReflectionProbe(entity: Entity): boolean;
getReflectionProbe(entity: Entity): ReflectionProbe;
addReflectionProbe(entity: Entity, component: ReflectionProbe): void;
@@ -1205,6 +1239,7 @@ export interface ESEngineModule {
Parent: new () => Parent;
ParticleEmitter: new () => ParticleEmitter;
ParticleForceField: new () => ParticleForceField;
+ PlanarReflection: new () => PlanarReflection;
ReflectionProbe: new () => ReflectionProbe;
RigidBody2D: new () => RigidBody2D;
RigidBody3D: new () => RigidBody3D;
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 11ac49303..4345cd045 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -1056,6 +1056,114 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
],
},
},
+ "PlanarReflection": {
+ "axis": {
+ "category": "Capture",
+ "enum": [
+ {
+ "label": "X",
+ "value": 0,
+ },
+ {
+ "label": "Y",
+ "value": 1,
+ },
+ {
+ "label": "Z",
+ "value": 2,
+ },
+ ],
+ "tooltip": "Local normal axis, transformed with the entity. Y for a floor, Z for a mirror.",
+ },
+ "clipOffset": {
+ "category": "Capture",
+ "min": 0,
+ "step": 0.005,
+ "tooltip": "Clip offset in world units; excludes geometry behind the reflecting plane.",
+ },
+ "cullingMask": {
+ "bitmask": {
+ "source": "sortingLayers",
+ },
+ "category": "Capture",
+ "tooltip": "Sorting-layer bits captured by the reflection. The receiving surface and screen UI are excluded.",
+ },
+ "maxSize": {
+ "category": "Quality",
+ "max": 4096,
+ "min": 64,
+ "shownWhen": {
+ "field": "quality",
+ "values": [
+ 1,
+ ],
+ },
+ "step": 64,
+ },
+ "quality": {
+ "category": "Quality",
+ "enum": [
+ {
+ "label": "Project",
+ "value": 0,
+ },
+ {
+ "label": "Custom",
+ "value": 1,
+ },
+ ],
+ },
+ "resolutionScale": {
+ "category": "Quality",
+ "max": 1,
+ "min": 0.125,
+ "shownWhen": {
+ "field": "quality",
+ "values": [
+ 1,
+ ],
+ },
+ "step": 0.125,
+ },
+ "revision": {
+ "advanced": true,
+ },
+ "update": {
+ "category": "Quality",
+ "enum": [
+ {
+ "label": "EveryFrame",
+ "value": 0,
+ },
+ {
+ "label": "FixedRate",
+ "value": 1,
+ },
+ {
+ "label": "OnDemand",
+ "value": 2,
+ },
+ ],
+ "shownWhen": {
+ "field": "quality",
+ "values": [
+ 1,
+ ],
+ },
+ "tooltip": "Only the reflection capture; never limits the main scene frame rate.",
+ },
+ "updatesPerSecond": {
+ "category": "Quality",
+ "max": 120,
+ "min": 1,
+ "shownWhen": {
+ "field": "update",
+ "values": [
+ 1,
+ ],
+ },
+ },
+ },
"PostProcessVolume": {
"effects": {
"effectStack": true,
diff --git a/sdk/tests/quality-runtime.test.ts b/sdk/tests/quality-runtime.test.ts
index 5d64d734c..f17132e1d 100644
--- a/sdk/tests/quality-runtime.test.ts
+++ b/sdk/tests/quality-runtime.test.ts
@@ -12,10 +12,10 @@ vi.mock('../src/platform', () => ({
platformOnAppHide: () => () => {}, platformOnAppShow: () => () => {},
}));
vi.mock('../src/ecs/bridge/engineApi', () => ({
- engineApi: () => ({ renderer_setQualityBudgets: vi.fn(), renderer_setShadowDistance: distanceBudget }),
+ engineApi: () => ({ renderer_setQualityBudgets: vi.fn(), renderer_setShadowDistance: distanceBudget, renderer_setPlanarReflectionQuality: reflectionBudget }),
}));
-const { distanceBudget } = vi.hoisted(() => ({ distanceBudget: vi.fn() }));
+const { distanceBudget, reflectionBudget } = vi.hoisted(() => ({ distanceBudget: vi.fn(), reflectionBudget: vi.fn() }));
describe('quality runtime device selection', () => {
it('applies the tier shadow range and restores camera coverage when disabled', () => {
@@ -25,10 +25,12 @@ describe('quality runtime device selection', () => {
pipeline: { setQuality: (_: unknown, callback: () => void) => { apply = callback; } },
addPlugin: vi.fn(), onFrameEnd: () => () => {},
} as unknown as App;
- installQuality(app, { mode: 'high', profiles: { high: { shadowDistance: 60 } } }, 4);
+ installQuality(app, { mode: 'high', profiles: { high: { shadowDistance: 60, planarReflectionScale: 0.75, planarReflectionMaxSize: 1536 } } }, 4);
+ expect(reflectionBudget).toHaveBeenLastCalledWith(0.75,1536,0);
expect(distanceBudget).toHaveBeenLastCalledWith(60);
controller!.setMode('off'); apply!();
expect(distanceBudget).toHaveBeenLastCalledWith(0);
+ expect(reflectionBudget).toHaveBeenLastCalledWith(0.5,1024,0);
});
it('uses this app’s actual renderer identity when a GPU rule matches', () => {
const insertResource = vi.fn();
diff --git a/src/esengine/aot/AotComponents.generated.cpp b/src/esengine/aot/AotComponents.generated.cpp
index 7e81a5303..bb7c459ca 100644
--- a/src/esengine/aot/AotComponents.generated.cpp
+++ b/src/esengine/aot/AotComponents.generated.cpp
@@ -25,6 +25,7 @@
#include "esengine/ecs/components/Occluder.hpp"
#include "esengine/ecs/components/ParticleEmitter.hpp"
#include "esengine/ecs/components/ParticleForceField.hpp"
+#include "esengine/ecs/components/PlanarReflection.hpp"
#include "esengine/ecs/components/ReflectionProbe.hpp"
#include "esengine/ecs/components/RigidBody2D.hpp"
#include "esengine/ecs/components/ShadowCaster2D.hpp"
@@ -199,6 +200,11 @@ ComponentAt engineComponentAt(ecs::Registry& registry, const char* name) {
return registry.tryGet<esengine::ecs::ParticleForceField>(Entity::fromRaw(raw));
};
}
+ if (std::strcmp(name, "PlanarReflection") == 0) {
+ return [&registry](std::uint32_t raw) -> void* {
+ return registry.tryGet<esengine::ecs::PlanarReflection>(Entity::fromRaw(raw));
+ };
+ }
if (std::strcmp(name, "ReflectionProbe") == 0) {
return [&registry](std::uint32_t raw) -> void* {
return registry.tryGet<esengine::ecs::ReflectionProbe>(Entity::fromRaw(raw));
@@ -438,6 +444,11 @@ CandidatesOf engineComponentCandidates(ecs::Registry& registry, const char* name
return denseAsIds(registry.entitiesWith<esengine::ecs::ParticleForceField>());
};
}
+ if (std::strcmp(name, "PlanarReflection") == 0) {
+ return [&registry]() -> Candidates {
+ return denseAsIds(registry.entitiesWith<esengine::ecs::PlanarReflection>());
+ };
+ }
if (std::strcmp(name, "ReflectionProbe") == 0) {
return [&registry]() -> Candidates {
return denseAsIds(registry.entitiesWith<esengine::ecs::ReflectionProbe>());
@@ -569,6 +580,7 @@ bool isEngineComponent(const char* name) {
if (std::strcmp(name, "Parent") == 0) return true;
if (std::strcmp(name, "ParticleEmitter") == 0) return true;
if (std::strcmp(name, "ParticleForceField") == 0) return true;
+ if (std::strcmp(name, "PlanarReflection") == 0) return true;
if (std::strcmp(name, "ReflectionProbe") == 0) return true;
if (std::strcmp(name, "RigidBody2D") == 0) return true;
if (std::strcmp(name, "RigidBody3D") == 0) return true;
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index dd50f672f..c978ea309 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 6d39e5df3d1dc9e7
+ * @schema_hash a6d32400f48c59c2
*/
-#define ES_EDITOR_API_SCHEMA_HASH "6d39e5df3d1dc9e7"
+#define ES_EDITOR_API_SCHEMA_HASH "a6d32400f48c59c2"
#include <emscripten/bind.h>
#include <string>
@@ -28,6 +28,7 @@
#include "../ecs/components/Occluder.hpp"
#include "../ecs/components/ParticleEmitter.hpp"
#include "../ecs/components/ParticleForceField.hpp"
+#include "../ecs/components/PlanarReflection.hpp"
#include "../ecs/components/ReflectionProbe.hpp"
#include "../ecs/components/RigidBody2D.hpp"
#include "../ecs/components/RigidBody3D.hpp"
@@ -93,6 +94,7 @@ std::vector<std::string> editor_getComponentNames() {
"Parent",
"ParticleEmitter",
"ParticleForceField",
+ "PlanarReflection",
"ReflectionProbe",
"RigidBody2D",
"RigidBody3D",
@@ -505,6 +507,19 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"falloff","type":"bool","group":"ParticleForceField"},
{"key":"enabled","type":"bool","group":"ParticleForceField"}
])JSON";
+ } else if (name == "PlanarReflection") {
+ return R"JSON([
+ {"key":"axis","type":"enum","group":"PlanarReflection","values":["X","Y","Z"]},
+ {"key":"clipOffset","type":"float","group":"PlanarReflection"},
+ {"key":"cullingMask","type":"int","group":"PlanarReflection"},
+ {"key":"quality","type":"enum","group":"PlanarReflection","values":["Project","Custom"]},
+ {"key":"resolutionScale","type":"float","group":"PlanarReflection"},
+ {"key":"maxSize","type":"int","group":"PlanarReflection"},
+ {"key":"update","type":"enum","group":"PlanarReflection","values":["EveryFrame","FixedRate","OnDemand"]},
+ {"key":"updatesPerSecond","type":"float","group":"PlanarReflection"},
+ {"key":"revision","type":"int","group":"PlanarReflection"},
+ {"key":"enabled","type":"bool","group":"PlanarReflection"}
+ ])JSON";
} else if (name == "ReflectionProbe") {
return R"JSON([
{"key":"reflection","type":"asset","group":"ReflectionProbe"},
@@ -884,6 +899,9 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {
} else if (name == "ParticleForceField") {
if (!reg.has<esengine::ecs::ParticleForceField>(entity)) reg.emplace<esengine::ecs::ParticleForceField>(entity);
return true;
+ } else if (name == "PlanarReflection") {
+ if (!reg.has<esengine::ecs::PlanarReflection>(entity)) reg.emplace<esengine::ecs::PlanarReflection>(entity);
+ return true;
} else if (name == "ReflectionProbe") {
if (!reg.has<esengine::ecs::ReflectionProbe>(entity)) reg.emplace<esengine::ecs::ReflectionProbe>(entity);
return true;
@@ -1009,6 +1027,8 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {
if (reg.has<esengine::ecs::ParticleEmitter>(entity)) { reg.remove<esengine::ecs::ParticleEmitter>(entity); return true; }
} else if (name == "ParticleForceField") {
if (reg.has<esengine::ecs::ParticleForceField>(entity)) { reg.remove<esengine::ecs::ParticleForceField>(entity); return true; }
+ } else if (name == "PlanarReflection") {
+ if (reg.has<esengine::ecs::PlanarReflection>(entity)) { reg.remove<esengine::ecs::PlanarReflection>(entity); return true; }
} else if (name == "ReflectionProbe") {
if (reg.has<esengine::ecs::ReflectionProbe>(entity)) { reg.remove<esengine::ecs::ReflectionProbe>(entity); return true; }
} else if (name == "RigidBody2D") {
@@ -1083,6 +1103,7 @@ bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {
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);
+ if (name == "PlanarReflection") return reg.has<esengine::ecs::PlanarReflection>(entity);
if (name == "ReflectionProbe") return reg.has<esengine::ecs::ReflectionProbe>(entity);
if (name == "RigidBody2D") return reg.has<esengine::ecs::RigidBody2D>(entity);
if (name == "RigidBody3D") return reg.has<esengine::ecs::RigidBody3D>(entity);
@@ -1139,6 +1160,7 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {
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");
+ if (reg.has<esengine::ecs::PlanarReflection>(entity)) result.push_back("PlanarReflection");
if (reg.has<esengine::ecs::ReflectionProbe>(entity)) result.push_back("ReflectionProbe");
if (reg.has<esengine::ecs::RigidBody2D>(entity)) result.push_back("RigidBody2D");
if (reg.has<esengine::ecs::RigidBody3D>(entity)) result.push_back("RigidBody3D");
@@ -1459,6 +1481,14 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "direction.z") { c.direction.z = value; }
else { return false; }
return true;
+ } else if (comp == "PlanarReflection") {
+ if (!reg.has<esengine::ecs::PlanarReflection>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::PlanarReflection>(entity);
+ if (field == "clipOffset") { c.clipOffset = value; }
+ else if (field == "resolutionScale") { c.resolutionScale = value; }
+ else if (field == "updatesPerSecond") { c.updatesPerSecond = value; }
+ else { return false; }
+ return true;
} else if (comp == "ReflectionProbe") {
if (!reg.has<esengine::ecs::ReflectionProbe>(entity)) return false;
auto& c = reg.get<esengine::ecs::ReflectionProbe>(entity);
@@ -1964,6 +1994,12 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "direction.x") { return c.direction.x; }
else if (field == "direction.y") { return c.direction.y; }
else if (field == "direction.z") { return c.direction.z; }
+ } else if (comp == "PlanarReflection") {
+ if (!reg.has<esengine::ecs::PlanarReflection>(entity)) return 0.0f;
+ const auto& c = reg.get<esengine::ecs::PlanarReflection>(entity);
+ if (field == "clipOffset") { return c.clipOffset; }
+ else if (field == "resolutionScale") { return c.resolutionScale; }
+ else if (field == "updatesPerSecond") { return c.updatesPerSecond; }
} else if (comp == "ReflectionProbe") {
if (!reg.has<esengine::ecs::ReflectionProbe>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::ReflectionProbe>(entity);
@@ -2328,6 +2364,17 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
if (field == "type") { c.type = static_cast<i32>(value); }
else { return false; }
return true;
+ } else if (comp == "PlanarReflection") {
+ if (!reg.has<esengine::ecs::PlanarReflection>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::PlanarReflection>(entity);
+ if (field == "axis") { c.axis = static_cast<ReflectionAxis>(value); }
+ else if (field == "cullingMask") { c.cullingMask = static_cast<u32>(value); }
+ else if (field == "quality") { c.quality = static_cast<ReflectionQuality>(value); }
+ else if (field == "maxSize") { c.maxSize = static_cast<u32>(value); }
+ else if (field == "update") { c.update = static_cast<ReflectionUpdate>(value); }
+ else if (field == "revision") { c.revision = static_cast<u32>(value); }
+ else { return false; }
+ return true;
} else if (comp == "ReflectionProbe") {
if (!reg.has<esengine::ecs::ReflectionProbe>(entity)) return false;
auto& c = reg.get<esengine::ecs::ReflectionProbe>(entity);
@@ -2576,6 +2623,15 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
if (!reg.has<esengine::ecs::ParticleForceField>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::ParticleForceField>(entity);
if (field == "type") { return static_cast<i32>(c.type); }
+ } else if (comp == "PlanarReflection") {
+ if (!reg.has<esengine::ecs::PlanarReflection>(entity)) return 0;
+ const auto& c = reg.get<esengine::ecs::PlanarReflection>(entity);
+ if (field == "axis") { return static_cast<i32>(c.axis); }
+ else if (field == "cullingMask") { return static_cast<i32>(c.cullingMask); }
+ else if (field == "quality") { return static_cast<i32>(c.quality); }
+ else if (field == "maxSize") { return static_cast<i32>(c.maxSize); }
+ else if (field == "update") { return static_cast<i32>(c.update); }
+ else if (field == "revision") { return static_cast<i32>(c.revision); }
} else if (comp == "ReflectionProbe") {
if (!reg.has<esengine::ecs::ReflectionProbe>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::ReflectionProbe>(entity);
@@ -2825,6 +2881,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 == "PlanarReflection") {
+ if (!reg.has<esengine::ecs::PlanarReflection>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::PlanarReflection>(entity);
+ if (field == "enabled") { c.enabled = value; }
+ else { return false; }
+ return true;
} else if (comp == "ReflectionProbe") {
if (!reg.has<esengine::ecs::ReflectionProbe>(entity)) return false;
auto& c = reg.get<esengine::ecs::ReflectionProbe>(entity);
@@ -3068,6 +3130,10 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st
const auto& c = reg.get<esengine::ecs::ParticleForceField>(entity);
if (field == "falloff") { return c.falloff; }
else if (field == "enabled") { return c.enabled; }
+ } else if (comp == "PlanarReflection") {
+ if (!reg.has<esengine::ecs::PlanarReflection>(entity)) return false;
+ const auto& c = reg.get<esengine::ecs::PlanarReflection>(entity);
+ if (field == "enabled") { return c.enabled; }
} else if (comp == "ReflectionProbe") {
if (!reg.has<esengine::ecs::ReflectionProbe>(entity)) return false;
const auto& c = reg.get<esengine::ecs::ReflectionProbe>(entity);
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 7429e912e..faa674a16 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -592,7 +592,7 @@ void renderer_beginFrame(f32 elapsedSec) {
rc->setFrameTime(elapsedSec, g_viewportWidth, g_viewportHeight);
}
// The frame's own opening, which begin() is not: it runs once per camera.
- if (g_renderFrame) g_renderFrame->beginFrame();
+ if (g_renderFrame) { g_renderFrame->setPlanarTime(elapsedSec); g_renderFrame->beginFrame(); }
}
// The pass's load-op rides begin: clearFlags bit0 = color, bit1 = depth; the color
@@ -1068,6 +1068,14 @@ void renderer_setViewLighting(u32 mode, f32 rotationDegrees, f32 keyIntensity, f
g_renderFrame->setViewLighting(lighting);
}
+void renderer_setPlanarReflectionQuality(f32 scale, u32 maxSize, f32 updatesPerSecond) {
+ if (g_renderFrame) g_renderFrame->setPlanarQuality(scale, maxSize, updatesPerSecond);
+}
+
+std::string renderer_getPlanarReflectionStatus(u32 view, u32 entity) {
+ return g_renderFrame ? g_renderFrame->planarStatus(view, entity) : "{\"state\":\"unavailable\"}";
+}
+
void renderer_setShadowDistance(f32 distance) {
if (g_renderFrame) g_renderFrame->setShadowDistance(distance);
}
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index 63f35301b..a99f7ad6c 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -26,6 +26,8 @@ void renderer_init(u32 width, u32 height);
void renderer_resize(u32 width, u32 height);
void renderer_setQualityBudgets(u32 atlasSize, u32 cellSize, u32 cascades, u32 particleLimit);
void renderer_setShadowDistance(f32 distance);
+void renderer_setPlanarReflectionQuality(f32 scale, u32 maxSize, f32 updatesPerSecond);
+std::string renderer_getPlanarReflectionStatus(u32 view, u32 entity);
/**
* The editor view's lighting. mode 0 = the scene's own lights (the default, and the
* only one a packaged build ever has); 1 = studio: a neutral sky, a key and a fill, in
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 053a1a90f..dc4daa0cf 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -28,6 +28,7 @@
#include "../ecs/components/Occluder.hpp"
#include "../ecs/components/ParticleEmitter.hpp"
#include "../ecs/components/ParticleForceField.hpp"
+#include "../ecs/components/PlanarReflection.hpp"
#include "../ecs/components/ReflectionProbe.hpp"
#include "../ecs/components/RigidBody2D.hpp"
#include "../ecs/components/RigidBody3D.hpp"
@@ -220,6 +221,20 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {
.value("Perspective", esengine::ecs::ProjectionType::Perspective)
.value("Orthographic", esengine::ecs::ProjectionType::Orthographic);
+ enum_<esengine::ecs::ReflectionAxis>("ReflectionAxis")
+ .value("X", esengine::ecs::ReflectionAxis::X)
+ .value("Y", esengine::ecs::ReflectionAxis::Y)
+ .value("Z", esengine::ecs::ReflectionAxis::Z);
+
+ enum_<esengine::ecs::ReflectionQuality>("ReflectionQuality")
+ .value("Project", esengine::ecs::ReflectionQuality::Project)
+ .value("Custom", esengine::ecs::ReflectionQuality::Custom);
+
+ enum_<esengine::ecs::ReflectionUpdate>("ReflectionUpdate")
+ .value("EveryFrame", esengine::ecs::ReflectionUpdate::EveryFrame)
+ .value("FixedRate", esengine::ecs::ReflectionUpdate::FixedRate)
+ .value("OnDemand", esengine::ecs::ReflectionUpdate::OnDemand);
+
enum_<esengine::ecs::ScrollMovement>("ScrollMovement")
.value("Clamped", esengine::ecs::ScrollMovement::Clamped)
.value("Elastic", esengine::ecs::ScrollMovement::Elastic);
@@ -1051,6 +1066,53 @@ ParticleEmitterJS particleemitterToJS(const esengine::ecs::ParticleEmitter& c) {
return js;
}
+struct PlanarReflectionJS {
+ i32 axis;
+ f32 clipOffset;
+ u32 cullingMask;
+ i32 quality;
+ f32 resolutionScale;
+ u32 maxSize;
+ i32 update;
+ f32 updatesPerSecond;
+ u32 revision;
+ bool enabled;
+};
+
+void planarreflectionApplyJS(esengine::ecs::PlanarReflection& c, const PlanarReflectionJS& js) {
+ c.axis = static_cast<ReflectionAxis>(js.axis);
+ c.clipOffset = js.clipOffset;
+ c.cullingMask = js.cullingMask;
+ c.quality = static_cast<ReflectionQuality>(js.quality);
+ c.resolutionScale = js.resolutionScale;
+ c.maxSize = js.maxSize;
+ c.update = static_cast<ReflectionUpdate>(js.update);
+ c.updatesPerSecond = js.updatesPerSecond;
+ c.revision = js.revision;
+ c.enabled = js.enabled;
+}
+
+esengine::ecs::PlanarReflection planarreflectionFromJS(const PlanarReflectionJS& js) {
+ esengine::ecs::PlanarReflection c;
+ planarreflectionApplyJS(c, js);
+ return c;
+}
+
+PlanarReflectionJS planarreflectionToJS(const esengine::ecs::PlanarReflection& c) {
+ PlanarReflectionJS js;
+ js.axis = static_cast<i32>(c.axis);
+ js.clipOffset = c.clipOffset;
+ js.cullingMask = c.cullingMask;
+ js.quality = static_cast<i32>(c.quality);
+ js.resolutionScale = c.resolutionScale;
+ js.maxSize = c.maxSize;
+ js.update = static_cast<i32>(c.update);
+ js.updatesPerSecond = c.updatesPerSecond;
+ js.revision = c.revision;
+ js.enabled = c.enabled;
+ return js;
+}
+
struct ReflectionProbeJS {
u32 reflection;
glm::vec3 halfExtents;
@@ -1880,6 +1942,18 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("falloff", &esengine::ecs::ParticleForceField::falloff)
.field("enabled", &esengine::ecs::ParticleForceField::enabled);
+ value_object<PlanarReflectionJS>("PlanarReflection")
+ .field("axis", &PlanarReflectionJS::axis)
+ .field("clipOffset", &PlanarReflectionJS::clipOffset)
+ .field("cullingMask", &PlanarReflectionJS::cullingMask)
+ .field("quality", &PlanarReflectionJS::quality)
+ .field("resolutionScale", &PlanarReflectionJS::resolutionScale)
+ .field("maxSize", &PlanarReflectionJS::maxSize)
+ .field("update", &PlanarReflectionJS::update)
+ .field("updatesPerSecond", &PlanarReflectionJS::updatesPerSecond)
+ .field("revision", &PlanarReflectionJS::revision)
+ .field("enabled", &PlanarReflectionJS::enabled);
+
value_object<ReflectionProbeJS>("ReflectionProbe")
.field("reflection", &ReflectionProbeJS::reflection)
.field("halfExtents", &ReflectionProbeJS::halfExtents)
@@ -2145,6 +2219,7 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
if (r.has<esengine::ecs::Parent>(entity)) { if (!names.empty()) names += "|"; names += "Parent"; }
if (r.has<esengine::ecs::ParticleEmitter>(entity)) { if (!names.empty()) names += "|"; names += "ParticleEmitter"; }
if (r.has<esengine::ecs::ParticleForceField>(entity)) { if (!names.empty()) names += "|"; names += "ParticleForceField"; }
+ if (r.has<esengine::ecs::PlanarReflection>(entity)) { if (!names.empty()) names += "|"; names += "PlanarReflection"; }
if (r.has<esengine::ecs::ReflectionProbe>(entity)) { if (!names.empty()) names += "|"; names += "ReflectionProbe"; }
if (r.has<esengine::ecs::RigidBody2D>(entity)) { if (!names.empty()) names += "|"; names += "RigidBody2D"; }
if (r.has<esengine::ecs::RigidBody3D>(entity)) { if (!names.empty()) names += "|"; names += "RigidBody3D"; }
@@ -2196,6 +2271,7 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
if (name == "Parent") return static_cast<int>(componentTypeId<esengine::ecs::Parent>());
if (name == "ParticleEmitter") return static_cast<int>(componentTypeId<esengine::ecs::ParticleEmitter>());
if (name == "ParticleForceField") return static_cast<int>(componentTypeId<esengine::ecs::ParticleForceField>());
+ if (name == "PlanarReflection") return static_cast<int>(componentTypeId<esengine::ecs::PlanarReflection>());
if (name == "ReflectionProbe") return static_cast<int>(componentTypeId<esengine::ecs::ReflectionProbe>());
if (name == "RigidBody2D") return static_cast<int>(componentTypeId<esengine::ecs::RigidBody2D>());
if (name == "RigidBody3D") return static_cast<int>(componentTypeId<esengine::ecs::RigidBody3D>());
@@ -2828,6 +2904,30 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
r.remove<esengine::ecs::ParticleForceField>(entity);
}))
+ // PlanarReflection
+ .function("hasPlanarReflection", optional_override([](Registry& r, u32 e) {
+ return r.has<esengine::ecs::PlanarReflection>(static_cast<Entity>(e));
+ }))
+ .function("getPlanarReflection", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::PlanarReflection>(entity)) return PlanarReflectionJS{};
+ return planarreflectionToJS(r.get<esengine::ecs::PlanarReflection>(entity));
+ }))
+ .function("addPlanarReflection", optional_override([](Registry& r, u32 e, const PlanarReflectionJS& js) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity)) return;
+ if (auto* existing = r.tryGet<esengine::ecs::PlanarReflection>(entity)) {
+ planarreflectionApplyJS(*existing, js);
+ return;
+ }
+ r.emplaceOrReplace<esengine::ecs::PlanarReflection>(entity, planarreflectionFromJS(js));
+ }))
+ .function("removePlanarReflection", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::PlanarReflection>(entity)) return;
+ r.remove<esengine::ecs::PlanarReflection>(entity);
+ }))
+
// ReflectionProbe
.function("hasReflectionProbe", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::ReflectionProbe>(static_cast<Entity>(e));
@@ -3331,6 +3431,7 @@ emscripten::val esengineGetBuiltinComponentNames() {
arr.set(i++, val(std::string("Parent")));
arr.set(i++, val(std::string("ParticleEmitter")));
arr.set(i++, val(std::string("ParticleForceField")));
+ arr.set(i++, val(std::string("PlanarReflection")));
arr.set(i++, val(std::string("ReflectionProbe")));
arr.set(i++, val(std::string("RigidBody2D")));
arr.set(i++, val(std::string("RigidBody3D")));
@@ -3603,6 +3704,16 @@ static_assert(offsetof(esengine::ecs::ParticleForceField, radius) == 8, "ABI off
static_assert(offsetof(esengine::ecs::ParticleForceField, direction) == 12, "ABI offset drift: esengine::ecs::ParticleForceField.direction (EHT expected 12)");
static_assert(offsetof(esengine::ecs::ParticleForceField, falloff) == 24, "ABI offset drift: esengine::ecs::ParticleForceField.falloff (EHT expected 24)");
static_assert(offsetof(esengine::ecs::ParticleForceField, enabled) == 25, "ABI offset drift: esengine::ecs::ParticleForceField.enabled (EHT expected 25)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, axis) == 0, "ABI offset drift: esengine::ecs::PlanarReflection.axis (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, clipOffset) == 4, "ABI offset drift: esengine::ecs::PlanarReflection.clipOffset (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, cullingMask) == 8, "ABI offset drift: esengine::ecs::PlanarReflection.cullingMask (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, quality) == 12, "ABI offset drift: esengine::ecs::PlanarReflection.quality (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, resolutionScale) == 16, "ABI offset drift: esengine::ecs::PlanarReflection.resolutionScale (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, maxSize) == 20, "ABI offset drift: esengine::ecs::PlanarReflection.maxSize (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, update) == 24, "ABI offset drift: esengine::ecs::PlanarReflection.update (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, updatesPerSecond) == 28, "ABI offset drift: esengine::ecs::PlanarReflection.updatesPerSecond (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, revision) == 32, "ABI offset drift: esengine::ecs::PlanarReflection.revision (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::PlanarReflection, enabled) == 36, "ABI offset drift: esengine::ecs::PlanarReflection.enabled (EHT expected 36)");
static_assert(offsetof(esengine::ecs::ReflectionProbe, reflection) == 0, "ABI offset drift: esengine::ecs::ReflectionProbe.reflection (EHT expected 0)");
static_assert(offsetof(esengine::ecs::ReflectionProbe, halfExtents) == 4, "ABI offset drift: esengine::ecs::ReflectionProbe.halfExtents (EHT expected 4)");
static_assert(offsetof(esengine::ecs::ReflectionProbe, slot) == 16, "ABI offset drift: esengine::ecs::ReflectionProbe.slot (EHT expected 16)");
@@ -3770,7 +3881,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "2f29375a9e0f797d";
+static const char* kEsAbiLayoutHash = "2f5ac38ffa80eb57";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index b9876b1e6..35172e548 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -775,6 +775,8 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_setDepthLayers", &esengine::renderer_setDepthLayers);
emscripten::function("renderer_setQualityBudgets", &esengine::renderer_setQualityBudgets);
emscripten::function("renderer_setShadowDistance", &esengine::renderer_setShadowDistance);
+ emscripten::function("renderer_setPlanarReflectionQuality", &esengine::renderer_setPlanarReflectionQuality);
+ emscripten::function("renderer_getPlanarReflectionStatus", &esengine::renderer_getPlanarReflectionStatus);
emscripten::function("renderer_setViewLighting", &esengine::renderer_setViewLighting);
emscripten::function("renderer_setCullingMask", &esengine::renderer_setCullingMask);
emscripten::function("renderer_setViewId", &esengine::renderer_setViewId);
diff --git a/src/esengine/ecs/components/PlanarReflection.hpp b/src/esengine/ecs/components/PlanarReflection.hpp
new file mode 100644
index 000000000..7c597035d
--- /dev/null
+++ b/src/esengine/ecs/components/PlanarReflection.hpp
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#pragma once
+#include "../../core/Types.hpp"
+#include "../../core/Reflection.hpp"
+
+namespace esengine::ecs {
+ES_ENUM()
+enum class ReflectionAxis : u8 { X, Y, Z };
+ES_ENUM()
+enum class ReflectionQuality : u8 { Project, Custom };
+ES_ENUM()
+enum class ReflectionUpdate : u8 { EveryFrame, FixedRate, OnDemand };
+
+/** A non-recursive capture received by this entity's lit mesh/material.
+ * The plane passes through its world origin; the selected local axis is its normal.
+ * Surface appearance remains owned by the material's PBR properties.
+ */
+ES_COMPONENT(stability=experimental)
+struct PlanarReflection {
+ ES_PROPERTY(enum=ReflectionAxis, category=Capture, tooltip="Local normal axis, transformed with the entity. Y for a floor, Z for a mirror.")
+ ReflectionAxis axis{ReflectionAxis::Y};
+ ES_PROPERTY(min=0, step=0.005, category=Capture, tooltip="Clip offset in world units; excludes geometry behind the reflecting plane.")
+ f32 clipOffset{0.02f};
+ ES_PROPERTY(bitmask_source=sortingLayers, category=Capture, tooltip="Sorting-layer bits captured by the reflection. The receiving surface and screen UI are excluded.")
+ u32 cullingMask{0xFFFFFFFFu};
+ ES_PROPERTY(enum=ReflectionQuality, category=Quality)
+ ReflectionQuality quality{ReflectionQuality::Project};
+ ES_PROPERTY(min=0.125, max=1, step=0.125, category=Quality, shown_when=quality:Custom)
+ f32 resolutionScale{0.5f};
+ ES_PROPERTY(min=64, max=4096, step=64, category=Quality, shown_when=quality:Custom)
+ u32 maxSize{1024};
+ ES_PROPERTY(enum=ReflectionUpdate, category=Quality, shown_when=quality:Custom, tooltip="Only the reflection capture; never limits the main scene frame rate.")
+ ReflectionUpdate update{ReflectionUpdate::EveryFrame};
+ ES_PROPERTY(min=1, max=120, category=Quality, shown_when=update:FixedRate)
+ f32 updatesPerSecond{30.0f};
+ /** Increment to request a fresh OnDemand capture from a script or editor action. */
+ ES_PROPERTY(advanced)
+ u32 revision{0};
+ ES_PROPERTY()
+ bool enabled{true};
+};
+} // namespace esengine::ecs
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index e90d34cc8..ba1248b2c 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -240,6 +240,7 @@ struct RenderCollectContext {
* answer about what a camera cannot see says nothing about it.
*/
const OcclusionView* occlusion = nullptr;
+ Entity excluded = INVALID_ENTITY;
/** @brief Whether this collect is the frame's screen overlay. */
bool isOverlay() const { return frame_context.purpose == RenderPurpose::ScreenOverlay; }
@@ -252,6 +253,7 @@ struct RenderCollectContext {
* twice — or by nobody, which is what a 3D HUD was.
*/
bool accepts(Entity entity) const {
+ if (entity == excluded) return false;
const bool screen = screen_ui && screen_ui->count(entity.id()) != 0;
return isOverlay() == screen;
}
diff --git a/src/esengine/renderer/draw/BatchBuilder.cpp b/src/esengine/renderer/draw/BatchBuilder.cpp
index 3bed3cfb0..ee3d586ad 100644
--- a/src/esengine/renderer/draw/BatchBuilder.cpp
+++ b/src/esengine/renderer/draw/BatchBuilder.cpp
@@ -119,6 +119,7 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,
cmd.skin_count = key.skinCount;
cmd.morph_index = key.morphIndex;
cmd.probe_index = key.probeIndex;
+ cmd.planar_index = key.planarIndex;
cmd.shader_id = key.shaderId;
cmd.blend_mode = key.blend;
cmd.layout_id = key.layoutId;
diff --git a/src/esengine/renderer/draw/BatchBuilder.hpp b/src/esengine/renderer/draw/BatchBuilder.hpp
index baf832889..c4cf9e31e 100644
--- a/src/esengine/renderer/draw/BatchBuilder.hpp
+++ b/src/esengine/renderer/draw/BatchBuilder.hpp
@@ -146,6 +146,7 @@ struct BatchDrawKey {
/// pool (0 = no volume holds it). Not part of the key — a volume does not
/// change what program or buffer a draw needs, only what it reads.
u32 probeIndex = 0;
+ u32 planarIndex = 0;
/// The baked atlas this draw reads, on the last slot a draw's own stream has.
/// Part of the key and not only of the command: two objects sharing a mesh but
/// baked into different atlases are two draws.
diff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hpp
index 536ec06d4..1ad7b2cc7 100644
--- a/src/esengine/renderer/draw/DrawCommand.hpp
+++ b/src/esengine/renderer/draw/DrawCommand.hpp
@@ -3,6 +3,7 @@
#pragma once
#include "../store/ProbeConstants.hpp"
+#include "../store/PlanarConstants.hpp"
#include "../../core/Types.hpp"
#include "../frame/RenderStage.hpp"
#include "./RenderItem.hpp"
@@ -165,6 +166,7 @@ struct DrawCommand {
// frame's pool, so 0 means no volume holds it and the frame's environment
// answers instead.
u32 probe_index = 0;
+ u32 planar_index = 0;
// Where this draw's instances start in the frame's probe texture. A merged
// run reads slot `probe_base + gl_InstanceID`, which is why the merge
// records every instance's probe in draw order rather than dropping it.
@@ -344,6 +346,7 @@ struct DrawCommand {
if (!hasPersistentGeometry() || !next.hasPersistentGeometry()) return false;
if (instance_stride == 0 || instance_stride != next.instance_stride) return false;
if (skin_count != 0 || next.skin_count != 0) return false;
+ if (planar_index != next.planar_index) return false;
// Same reason: one draw can only be in one shape.
if (morph_index != 0 || next.morph_index != 0) return false;
// Indirect light is NOT in this list: it is per instance, so two draws
@@ -367,6 +370,7 @@ struct DrawCommand {
}
BatchBreak mergeBlocker(const DrawCommand& next) const {
+ if (planar_index != next.planar_index) return BatchBreak::Material;
// UI mask vertices are replayed to restore their parent's stencil.
// Changing sampler indices while merging the entering draw would also
// change its later replay, so both must keep the same binding plan.
@@ -437,6 +441,7 @@ struct DrawCommand {
}
bool canMergeWith(const DrawCommand& next) const {
+ if (planar_index != next.planar_index) return false;
return mergeBlocker(next) == BatchBreak::None;
}
};
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index 50cc6f05a..a5cda0724 100644
--- a/src/esengine/renderer/draw/DrawList.cpp
+++ b/src/esengine/renderer/draw/DrawList.cpp
@@ -73,6 +73,7 @@ void DrawList::clear() {
skin_matrices_.clear();
morph_shapes_.clear();
probes_.clear();
+ planar_.clear();
probe_slots_.clear();
run_entities_.clear();
run_first_.clear();
@@ -303,6 +304,9 @@ void DrawList::stageBlocks(const PerDrawBlockSet& blocks) {
const auto& cmd = commands_[i];
StagedBlocks& staged = staged_[i];
+ if (blocks.planar && cmd.planar_index > 0) {
+ staged.planar = blocks.planar->stage(&planar_[cmd.planar_index - 1], sizeof(PlanarConstants));
+ }
// The pose, for a draw that has one — in a range of this draw's own. A
// block shared between two draws of one pass is read by both with what
// the last wrote, which is a room of characters in one pose.
@@ -346,7 +350,7 @@ void DrawList::stageBlocks(const PerDrawBlockSet& blocks) {
staged.instance = blocks.instance->stage(&at, sizeof(at));
}
}
- for (PerDrawBlocks* pool : {blocks.skin, blocks.morph, blocks.probe, blocks.instance}) {
+ for (PerDrawBlocks* pool : {blocks.skin, blocks.morph, blocks.probe, blocks.instance, blocks.planar}) {
if (pool) pool->upload();
}
}
@@ -418,6 +422,8 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
blocks.probe->bind(PROBE_CONSTANTS_BINDING, staged.probe);
}
+ if (blocks.planar) blocks.planar->bind(PLANAR_CONSTANTS_BINDING, staged.planar);
+
// Dynamic per-draw state (sorted+merged draws already group these coarsely).
if (cmd.state_flags & CMD_STATE_SCISSOR) {
device.setScissorTest(true);
diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hpp
index 3e5d5ce6d..b987fd5d1 100644
--- a/src/esengine/renderer/draw/DrawList.hpp
+++ b/src/esengine/renderer/draw/DrawList.hpp
@@ -67,6 +67,7 @@ public:
/** Append one draw's indirect light; returns 1 + where it sits, so that 0
* stays available for "no volume holds this draw". */
u32 addProbe(const ProbeConstants& probe);
+ u32 addPlanar(const PlanarConstants& value) { planar_.push_back(value); return static_cast<u32>(planar_.size()); }
u32 commandCount() const { return static_cast<u32>(commands_.size()); }
/** Entities by original submission type, independent of a merged run's head. */
@@ -202,6 +203,7 @@ private:
std::vector<glm::mat4> skin_matrices_;
std::vector<MorphConstants> morph_shapes_;
std::vector<ProbeConstants> probes_;
+ std::vector<PlanarConstants> planar_;
/// One entry per INSTANCE of every merged run, in the order the run draws
/// them: the merge is where an instance's probe is still known, and the
/// texture is packed from this afterwards.
@@ -215,7 +217,7 @@ private:
std::vector<glm::vec4> probe_run_;
/// Each merged draw's per-draw blocks, staged for the pass before it draws.
struct StagedBlocks {
- PerDrawBlocks::Range skin, morph, probe, instance;
+ PerDrawBlocks::Range skin, morph, probe, instance, planar;
};
std::vector<StagedBlocks> staged_;
void stageBlocks(const PerDrawBlockSet& blocks);
diff --git a/src/esengine/renderer/frame/PlanarReflectionCamera.hpp b/src/esengine/renderer/frame/PlanarReflectionCamera.hpp
new file mode 100644
index 000000000..f46a1ebc5
--- /dev/null
+++ b/src/esengine/renderer/frame/PlanarReflectionCamera.hpp
@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#pragma once
+#include "FrameConstants.hpp"
+#include <glm/gtc/matrix_access.hpp>
+#include <algorithm>
+#include <cmath>
+
+namespace esengine {
+struct PlanarReflectionCamera {
+ glm::mat4 projection{1.0f};
+ glm::mat4 samplingProjection{1.0f};
+};
+
+/** Mirrors through a world plane; supports perspective and orthographic sources.
+ * Engine clip depth stays [-1,1] until the existing device remap at upload.
+ * Oblique row replacement: https://terathon.com/blog/oblique-clipping.html
+ */
+inline bool planarReflectionCamera(const glm::mat4& source, const glm::vec3& origin,
+ glm::vec3 normal, f32 offset, PlanarReflectionCamera& out) {
+ const f32 length = glm::length(normal);
+ if (!std::isfinite(length) || length < 1e-6f || !std::isfinite(offset)) return false;
+ normal /= length;
+ const glm::vec4 eye = cameraFromViewProjection(source);
+ const f32 side = eye.w > 0.5f ? glm::dot(glm::vec3(eye) - origin, normal)
+ : glm::dot(glm::vec3(eye), normal);
+ if (!std::isfinite(side) || std::abs(side) < 1e-5f) return false;
+ if (side < 0) normal = -normal;
+ const f32 d = -glm::dot(normal, origin);
+ glm::mat4 mirror(1.0f);
+ for (int c = 0; c < 3; ++c) {
+ for (int r = 0; r < 3; ++r) mirror[c][r] -= 2.0f * normal[c] * normal[r];
+ mirror[3][c] = -2.0f * d * normal[c];
+ }
+ glm::mat4 reflected = source * mirror;
+ // Reflection reverses handedness. Flip clip X as well so the existing
+ // front-face and two-sided normal rules stay valid; sampling uses this
+ // same projection, undoing the image flip on the receiving surface.
+ for (int c = 0; c < 4; ++c) reflected[c][0] = -reflected[c][0];
+ const f32 determinant = glm::determinant(reflected);
+ if (!std::isfinite(determinant) || std::abs(determinant) < 1e-12f) return false;
+ const glm::vec4 plane(normal, d - std::max(offset, 0.0f));
+ const glm::mat4 inverse = glm::inverse(reflected);
+ const glm::vec4 clipPlane = glm::transpose(inverse) * plane;
+ const glm::vec4 corner(clipPlane.x < 0 ? -1.0f : 1.0f,
+ clipPlane.y < 0 ? -1.0f : 1.0f, 1.0f, 1.0f);
+ const f32 denominator = glm::dot(plane, inverse * corner);
+ if (!std::isfinite(denominator) || denominator < 1e-6f) return false;
+ const glm::vec4 scaled = plane * (2.0f / denominator);
+ out.samplingProjection = reflected;
+ out.projection = reflected;
+ for (int c = 0; c < 4; ++c) out.projection[c][2] = scaled[c] - reflected[c][3];
+ return true;
+}
+} // namespace esengine
diff --git a/src/esengine/renderer/frame/RenderContext.cpp b/src/esengine/renderer/frame/RenderContext.cpp
index c18d66d7b..0e3c86a13 100644
--- a/src/esengine/renderer/frame/RenderContext.cpp
+++ b/src/esengine/renderer/frame/RenderContext.cpp
@@ -17,6 +17,7 @@
#include "../draw/DrawParams.hpp"
#include "../store/SkinConstants.hpp"
#include "../store/MorphConstants.hpp"
+#include "../store/PlanarConstants.hpp"
#include "../store/InstanceConstants.hpp"
#include "../store/ProbeConstants.hpp"
#include "../../core/Log.hpp"
@@ -82,6 +83,7 @@ void RenderContext::shutdown() {
morphBlocks_.shutdown();
probeBlocks_.shutdown();
instanceBlocks_.shutdown();
+ planarBlocks_.shutdown();
materials_.clear(); // free per-material UBOs while the device is still valid
materials_.setResourceManager(nullptr);
@@ -148,11 +150,13 @@ void RenderContext::initFrameUbo() {
// says about every object in it, and GL wants the whole declared block bound.
probeBlocks_.init(device_, PROBE_BLOCK_BYTES);
instanceBlocks_.init(device_, static_cast<u32>(sizeof(InstanceConstants)));
+ planarBlocks_.init(device_, static_cast<u32>(sizeof(PlanarConstants)));
// What a draw with no shapes and no volume reads. A pose has no zero: geometry
// without one is drawn by a shader that does not declare the block.
morphBlocks_.bindZero(MORPH_CONSTANTS_BINDING);
probeBlocks_.bindZero(PROBE_CONSTANTS_BINDING);
instanceBlocks_.bindZero(INSTANCE_CONSTANTS_BINDING);
+ planarBlocks_.bindZero(PLANAR_CONSTANTS_BINDING);
ES_LOG_DEBUG("FrameConstants UBO created (handle: {})", static_cast<u32>(frameUbo_));
}
diff --git a/src/esengine/renderer/frame/RenderContext.hpp b/src/esengine/renderer/frame/RenderContext.hpp
index 8db40e8d1..d17c9ab03 100644
--- a/src/esengine/renderer/frame/RenderContext.hpp
+++ b/src/esengine/renderer/frame/RenderContext.hpp
@@ -233,11 +233,12 @@ private:
PerDrawBlocks morphBlocks_;
PerDrawBlocks probeBlocks_;
PerDrawBlocks instanceBlocks_;
+ PerDrawBlocks planarBlocks_;
public:
/** @brief The blocks the draw loop rewrites before each draw. */
PerDrawBlockSet perDrawBlocks() {
- return {&skinBlocks_, &morphBlocks_, &probeBlocks_, &instanceBlocks_};
+ return {&skinBlocks_, &morphBlocks_, &probeBlocks_, &instanceBlocks_, &planarBlocks_};
}
/** @brief Hand every one of them back at the top of a frame. */
void beginPerDrawBlocks() {
@@ -245,6 +246,7 @@ public:
morphBlocks_.beginFrame();
probeBlocks_.beginFrame();
instanceBlocks_.beginFrame();
+ planarBlocks_.beginFrame();
}
private:
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 7c4b81d27..209764c5f 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -163,6 +163,7 @@ void RenderFrame::init(u32 width, u32 height) {
pool_.init();
shadow_pool_.init();
+ planar_pool_.init();
batch_shader_id_ = initBatchShader();
RenderFrameContext initCtx{
@@ -187,6 +188,8 @@ void RenderFrame::shutdown() {
plugins_.clear();
pool_.shutdown();
shadow_pool_.shutdown();
+ planar_pool_.shutdown();
+ releasePlanarCaptures();
releaseShadowFrameUbos();
releaseShadow2DResources();
releaseShape2DResources();
@@ -263,6 +266,13 @@ void RenderFrame::releaseFrameTargets() {
}
void RenderFrame::beginFrame() {
+ ++planar_frame_;
+ for (auto it = planar_captures_.begin(); it != planar_captures_.end();) {
+ if (it->second.lastSeen + 1 < planar_frame_) {
+ if (it->second.frameUbo != BufferHandle::Invalid) device_.deleteBuffer(it->second.frameUbo);
+ it = planar_captures_.erase(it);
+ } else ++it;
+ }
// Here and not at end(), which runs once per CAMERA: every camera plans and
// renders its own maps, and the pool hands the same physical atlas to each in
// turn. Then one tick of the clock, by the frame that owns the pool.
@@ -384,6 +394,7 @@ void RenderFrame::openPass(const PassClear& clear, RenderTargetManager::Handle t
pass.clearColorValue[1] = clearRgb.g;
pass.clearColorValue[2] = clearRgb.b;
pass.clearColorValue[3] = clear.colorValue.a;
+ scene_clear_ = glm::make_vec4(pass.clearColorValue);
pass.clearX = clear.x;
pass.clearY = clear.y;
pass.clearW = clear.w;
@@ -594,6 +605,7 @@ void RenderFrame::end() {
if (shadow_2d_resource_ != rg::kNoResource) {
scene.dependencies.push_back(shadow_2d_resource_);
}
+ if (planar_resource_ != rg::kNoResource) scene.dependencies.push_back(planar_resource_);
scene.execute = [this](const rg::PassContext&) {
drawScene();
if (presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
@@ -2127,6 +2139,7 @@ void RenderFrame::collectAll(ecs::Registry& registry) {
{ ES_PROFILE_SCOPE("render.collect.shadowDeclare"); declareShadowPass(registry); }
{ ES_PROFILE_SCOPE("render.collect.shadow2dDeclare"); declareShadow2DPass(); }
{ ES_PROFILE_SCOPE("render.collect.shape2dDeclare"); declareShape2DPass(); }
+ { ES_PROFILE_SCOPE("render.collect.planar"); declarePlanarReflection(registry); }
auto ctx = makeContext();
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index c0f2927f3..9cc567580 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -6,6 +6,8 @@
#include "../draw/RenderItem.hpp"
#include "../rhi/RenderTarget.hpp"
#include "./RenderContext.hpp"
+#include "./PlanarReflectionCamera.hpp"
+#include "../store/PlanarConstants.hpp"
#include "../store/LightConstants.hpp"
#include "../store/ShadowAtlas.hpp"
#include "../store/ShadowPlan.hpp"
@@ -107,6 +109,12 @@ public:
void resize(u32 width, u32 height);
void setShadowBudget(u32 atlasSize, u32 cellSize, u32 cascades);
void setShadowDistance(f32 distance);
+ void setPlanarQuality(f32 scale, u32 maxSize, f32 updatesPerSecond);
+ u32 planarTextureFor(Entity entity) const {
+ return entity == planar_receiver_ ? planar_texture_ : 0;
+ }
+ const PlanarConstants& planarConstants() const { return planar_constants_; }
+ std::string planarStatus(u32 view, u32 entity) const;
/** Geometry collected for this camera and drawn after its scene. */
void setPresentedOverlayDraw(ImmediateDraw* draw) { presented_overlay_draw_ = draw; }
@@ -131,6 +139,7 @@ public:
* (@ref applySceneDepthNeed), once, for every camera in the frame.
*/
void beginFrame();
+ void setPlanarTime(f32 seconds) { planar_elapsed_ = seconds; }
/**
* @brief Closes the FRAME, once, after every camera and every overlay.
@@ -664,6 +673,36 @@ private:
/** @brief Gathers the scene's reflection probes and binds the atlas they name. */
void collectReflections(ecs::Registry& registry);
+ void declarePlanarReflection(ecs::Registry& registry);
+ void executePlanarReflection(ecs::Registry& registry, u32 view);
+ struct PlanarCapture {
+ Unique<Framebuffer> target;
+ BufferHandle frameUbo = BufferHandle::Invalid;
+ Entity receiver = INVALID_ENTITY;
+ PlanarReflectionCamera camera;
+ u64 lastSeen = 0;
+ u64 generation = 0;
+ u32 revision = 0;
+ u32 mask = 0xFFFFFFFFu;
+ f32 lastTime = -1.0f;
+ u32 draws = 0;
+ u32 rejected = 0;
+ bool valid = false;
+ };
+ std::unordered_map<u32, PlanarCapture> planar_captures_;
+ TransientBufferPool planar_pool_{device_};
+ DrawList planar_list_;
+ u64 planar_frame_ = 0;
+ f32 planar_elapsed_ = 0;
+ f32 planar_scale_ = 0.5f;
+ u32 planar_max_size_ = 1024;
+ f32 planar_rate_ = 0;
+ Entity planar_receiver_ = INVALID_ENTITY;
+ u32 planar_texture_ = 0;
+ PlanarConstants planar_constants_;
+ glm::vec4 scene_clear_{0.0f, 0.0f, 0.0f, 1.0f};
+ rg::ResourceId planar_resource_ = rg::kNoResource;
+ void releasePlanarCaptures();
/// Makes this ambient light the frame's environment, when it names one that is
/// loaded; `scale` (colour times intensity) is folded into the coefficients.
diff --git a/src/esengine/renderer/frame/RenderFramePlanar.cpp b/src/esengine/renderer/frame/RenderFramePlanar.cpp
new file mode 100644
index 000000000..7c19982d0
--- /dev/null
+++ b/src/esengine/renderer/frame/RenderFramePlanar.cpp
@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#include "RenderFrame.hpp"
+#include "../../ecs/components/PlanarReflection.hpp"
+#include "../../ecs/components/MeshRenderer.hpp"
+#include "../../resource/Mesh.hpp"
+#include "../../core/FrameProfiler.hpp"
+#include <glm/gtc/type_ptr.hpp>
+#include <sstream>
+
+namespace esengine {
+void RenderFrame::setPlanarQuality(f32 scale, u32 maxSize, f32 rate) {
+ planar_scale_ = std::isfinite(scale) ? std::clamp(scale, 0.125f, 1.0f) : 0.5f;
+ planar_max_size_ = std::clamp(maxSize, 64u, 4096u);
+ planar_rate_ = std::isfinite(rate) ? std::clamp(rate, 0.0f, 120.0f) : 0.0f;
+}
+
+void RenderFrame::releasePlanarCaptures() {
+ for (auto& [view, capture] : planar_captures_) {
+ if (capture.frameUbo != BufferHandle::Invalid) device_.deleteBuffer(capture.frameUbo);
+ }
+ planar_captures_.clear();
+ planar_receiver_ = INVALID_ENTITY;
+ planar_texture_ = 0;
+ planar_resource_ = rg::kNoResource;
+}
+
+void RenderFrame::declarePlanarReflection(ecs::Registry& registry) {
+ planar_receiver_ = INVALID_ENTITY;
+ planar_texture_ = 0;
+ planar_resource_ = rg::kNoResource;
+ if (scene_resource_ == rg::kNoResource) return;
+ auto surfaces = registry.activeView<ecs::Transform, ecs::MeshRenderer, ecs::PlanarReflection>();
+ Entity selected = INVALID_ENTITY;
+ PlanarReflectionCamera camera;
+ u32 eligible = 0;
+ for (const Entity entity : surfaces) {
+ if (screen_domain_ && screen_domain_->count(entity.id()) != 0) continue;
+ const auto& surface = surfaces.get<ecs::PlanarReflection>(entity);
+ const auto& mesh = surfaces.get<ecs::MeshRenderer>(entity);
+ if (!surface.enabled || !mesh.enabled || !mesh.mesh.isValid()
+ || !draw_list_.layerVisible(DrawList::layerBit(mesh.layer))) continue;
+ const Mesh* geometry = resource_manager_.getMesh(mesh.mesh);
+ if (!geometry || !geometry->isDrawable()) continue;
+ auto& transform = surfaces.get<ecs::Transform>(entity);
+ transform.ensureDecomposed();
+ glm::vec3 centre, half;
+ orientedWorldAabb(transform.worldPosition, transform.worldRotation, transform.worldScale,
+ geometry->localMin, geometry->localMax, centre, half);
+ if (!frustum_.intersectsAABB(centre, half)) continue;
+ const u32 axis = static_cast<u32>(surface.axis);
+ if (axis > 2 || std::abs(transform.worldScale[axis]) < 1e-6f) continue;
+ glm::vec3 normal(0.0f); normal[axis] = 1.0f;
+ PlanarReflectionCamera candidate;
+ if (!planarReflectionCamera(view_projection_, transform.worldPosition,
+ transform.worldRotation * normal, surface.clipOffset, candidate)) continue;
+ ++eligible;
+ // A stable winner, independent of sparse-set iteration and camera movement.
+ if (selected != INVALID_ENTITY && selected.id() < entity.id()) continue;
+ selected = entity;
+ camera = candidate;
+ }
+ if (selected == INVALID_ENTITY) return;
+ const auto& surface = registry.get<ecs::PlanarReflection>(selected);
+ auto& capture = planar_captures_[view_id_];
+ capture.lastSeen = planar_frame_;
+ capture.rejected = eligible - 1;
+ const bool project = surface.quality == ecs::ReflectionQuality::Project;
+ const f32 requestedScale = project ? planar_scale_ : surface.resolutionScale;
+ const f32 scale = std::isfinite(requestedScale) ? std::clamp(requestedScale, 0.125f, 1.0f) : 0.5f;
+ const u32 limit = std::clamp(project ? planar_max_size_ : surface.maxSize, 64u, 4096u);
+ u32 sourceW = scene_viewport_.w ? scene_viewport_.w : width_;
+ u32 sourceH = scene_viewport_.h ? scene_viewport_.h : height_;
+ if (auto* target = target_manager_.get(current_target_); target && !scene_viewport_.w) {
+ sourceW = target->getWidth(); sourceH = target->getHeight();
+ }
+ const f32 ratio = std::min(scale, static_cast<f32>(limit) / std::max({sourceW, sourceH, 1u}));
+ const u32 w = std::max(1u, static_cast<u32>(std::round(sourceW * ratio)));
+ const u32 h = std::max(1u, static_cast<u32>(std::round(sourceH * ratio)));
+ const GfxPixelFormat format = linear_color_ && device_.supportsFloatTargets()
+ ? GfxPixelFormat::RGBA16F : GfxPixelFormat::RGBA8;
+ const bool generationChanged = capture.generation != device_.deviceGeneration();
+ if (!capture.target || capture.target->getWidth() != w || capture.target->getHeight() != h
+ || capture.target->getSpecification().colorFormat != format) {
+ FramebufferSpec spec;
+ spec.width = w; spec.height = h; spec.linearFilter = true;
+ spec.depthStencil = true; spec.colorFormat = format;
+ capture.target = Framebuffer::create(device_, spec);
+ capture.valid = false;
+ }
+ if (!capture.target) return;
+ const auto policy = project ? (planar_rate_ > 0 ? ecs::ReflectionUpdate::FixedRate : ecs::ReflectionUpdate::EveryFrame) : surface.update;
+ const f32 requestedRate = project ? planar_rate_ : surface.updatesPerSecond;
+ const f32 rate = std::isfinite(requestedRate) ? std::clamp(requestedRate, 1.0f, 120.0f) : 30.0f;
+ const bool due = !capture.valid || generationChanged || capture.receiver != selected
+ || capture.revision != surface.revision || capture.mask != surface.cullingMask
+ || policy == ecs::ReflectionUpdate::EveryFrame
+ || (policy == ecs::ReflectionUpdate::FixedRate && (planar_elapsed_ < capture.lastTime
+ || planar_elapsed_ - capture.lastTime >= 1.0f / rate));
+ const auto resource = graph_.importTarget(capture.target->handle(), w, h, /*output=*/false);
+ if (due) {
+ capture.receiver = selected;
+ capture.camera = camera;
+ capture.mask = surface.cullingMask;
+ capture.revision = surface.revision;
+ capture.generation = device_.deviceGeneration();
+ rg::PassDesc pass;
+ pass.name = "planar-reflection";
+ pass.write = resource;
+ pass.clear = pass.clearDepth = true;
+ for (u32 i = 0; i < 4; ++i) pass.clearColor[i] = scene_clear_[i];
+ if (shadow_resource_ != rg::kNoResource) pass.dependencies.push_back(shadow_resource_);
+ const u32 view = view_id_;
+ pass.execute = [this, &registry, view](const rg::PassContext&) { executePlanarReflection(registry, view); };
+ graph_.addPass(std::move(pass));
+ }
+ // Imported targets do not publish a texture until explicitly named.
+ planar_resource_ = resource;
+ planar_receiver_ = selected;
+ planar_texture_ = static_cast<u32>(capture.target->getColorAttachment());
+ planar_constants_.projection = capture.camera.samplingProjection;
+ planar_constants_.params = {1.0f,
+ device_.textureOriginTopLeft() ? -1.0f : 1.0f,
+ 1.0f / w, 1.0f / h};
+}
+
+void RenderFrame::executePlanarReflection(ecs::Registry& registry, u32 view) {
+ auto& capture = planar_captures_.at(view);
+ if (capture.frameUbo == BufferHandle::Invalid) {
+ capture.frameUbo = device_.createBuffer({GfxBufferUsage::Uniform, RenderContext::frameConstantsSize(), true}, GfxContent::transient(), nullptr);
+ }
+ if (capture.frameUbo == BufferHandle::Invalid) return;
+ planar_pool_.beginFrame();
+ planar_list_.clear();
+ planar_list_.setCullingMask(capture.mask);
+ planar_list_.setDepthMask(draw_list_.depthMask());
+ planar_list_.setYSortMask(draw_list_.ySortMask());
+ auto ctx = makeContext();
+ ctx.view_projection = capture.camera.projection;
+ Frustum frustum;
+ frustum.extractFromMatrix(ctx.view_projection);
+ RenderCollectContext collect{registry, frustum, clip_state_, planar_pool_, planar_list_, ctx,
+ computeCameraView(ctx.view_projection)};
+ collect.screen_ui = screen_domain_;
+ collect.excluded = capture.receiver;
+ collectSky(collect);
+ // No recursive frame/scene collect, post-processing, host overlays or HUD.
+ for (auto& plugin : plugins_) plugin->collect(collect);
+ planar_list_.finalize(planar_pool_);
+ planar_pool_.upload();
+ context_.useFrameConstants(capture.frameUbo,
+ toClipDepthRange(capture.camera.projection, device_.clipDepthRange()));
+ context_.lights().uploadAndBind();
+ planar_list_.execute(device_, planar_pool_, context_.materials(),
+ context_.getWhiteTextureId(), nullptr, context_.perDrawBlocks());
+ capture.valid = true;
+ capture.lastTime = planar_elapsed_;
+ capture.draws = planar_list_.mergedDrawCallCount();
+ accumulateStats(planar_list_);
+ tallyPass(planar_list_);
+ ES_PROFILE_COUNTER("render.planar.draws", capture.draws);
+ ES_PROFILE_COUNTER("render.planar.rejected", capture.rejected);
+ device_.invalidatePipelineCache();
+}
+
+std::string RenderFrame::planarStatus(u32 view, u32 entity) const {
+ const auto found = planar_captures_.find(view);
+ if (found == planar_captures_.end() || found->second.lastSeen != planar_frame_) return "{\"state\":\"inactive\"}";
+ const auto& c = found->second;
+ if (c.receiver.id() != entity) return "{\"state\":\"budget-excluded\"}";
+ if (!c.valid || !c.target) return "{\"state\":\"unavailable\"}";
+ const auto& spec = c.target->getSpecification();
+ std::ostringstream out;
+ out << "{\"state\":\"ready\",\"width\":" << spec.width << ",\"height\":" << spec.height
+ << ",\"draws\":" << c.draws << ",\"bytes\":" << (static_cast<u64>(spec.width) * spec.height * (spec.colorFormat == GfxPixelFormat::RGBA16F ? 12u : 8u))
+ << ",\"rejected\":" << c.rejected << ",\"updated\":" << (c.lastTime == planar_elapsed_ ? "true" : "false") << "}";
+ return out.str();
+}
+} // namespace esengine
diff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cpp
index 5d108b279..84f280cc4 100644
--- a/src/esengine/renderer/graph/RenderGraph.cpp
+++ b/src/esengine/renderer/graph/RenderGraph.cpp
@@ -53,15 +53,16 @@ ResourceId RenderGraph::importTexture(TextureHandle texture, u32 width, u32 heig
return static_cast<ResourceId>(resources_.size() - 1);
}
-ResourceId RenderGraph::importTarget(FramebufferHandle target, u32 width, u32 height) {
+ResourceId RenderGraph::importTarget(FramebufferHandle target, u32 width, u32 height, bool output) {
Resource res;
res.kind = Kind::ImportedTarget;
res.target = target;
res.width = width;
res.height = height;
resources_.push_back(res);
- finalTarget_ = static_cast<ResourceId>(resources_.size() - 1);
- return finalTarget_;
+ const ResourceId id = static_cast<ResourceId>(resources_.size() - 1);
+ if (output) finalTarget_ = id;
+ return id;
}
ResourceId RenderGraph::createTarget(const TargetDesc& desc) {
diff --git a/src/esengine/renderer/graph/RenderGraph.hpp b/src/esengine/renderer/graph/RenderGraph.hpp
index 5e8990d0b..efdc6e4fa 100644
--- a/src/esengine/renderer/graph/RenderGraph.hpp
+++ b/src/esengine/renderer/graph/RenderGraph.hpp
@@ -152,9 +152,11 @@ public:
* @brief The framebuffer the graph must end in (the screen, an editor FBO).
*
* @details Also what culling works back from: a pass no path reaches from
- * here did not contribute to the image and is dropped.
+ * here did not contribute to the image and is dropped. Set output
+ * false for a persistent intermediate capture: importing it must
+ * not move the final output away from the scene or its post stack.
*/
- ResourceId importTarget(FramebufferHandle target, u32 width, u32 height);
+ ResourceId importTarget(FramebufferHandle target, u32 width, u32 height, bool output = true);
/** A target the graph allocates from the pool and recycles after its last read. */
ResourceId createTarget(const TargetDesc& desc);
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 890eef646..265d1187f 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -335,7 +335,8 @@ MeshDrawKeys meshDrawFor(RenderFrameContext& ctx, ecs::Registry& registry, Entit
bool& warnedBones, bool weightHeat = false) {
const MeshProgramFacts facts =
meshFactsFromEntity(ctx, registry, entity, mesh, resident, warnedBones);
- return { meshVariantFrom(facts, ctx.environment_texture_id != 0, shadowDepth, weightHeat),
+ return { meshVariantFrom(facts, ctx.environment_texture_id != 0
+ || (!shadowDepth && ctx.frame && ctx.frame->planarTextureFor(entity) != 0), shadowDepth, weightHeat),
facts.normalTextureId };
}
} // namespace
@@ -667,6 +668,14 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
.type = RenderType::Mesh,
};
+ if (!shadowDepth && ctx.frame) {
+ const u32 reflection = ctx.frame->planarTextureFor(entity);
+ if (reflection != 0) {
+ key.envTextureId = reflection;
+ key.planarIndex = draw_list.addPlanar(ctx.frame->planarConstants());
+ }
+ }
+
// An opaque surface says so itself rather than waiting for a depth layer:
// no blending, depth written AND tested — the only way one mesh hides
// another. Opaque sorts ahead of blended within a layer, so 2D stays on top.
diff --git a/src/esengine/renderer/rhi/PerDrawBlocks.hpp b/src/esengine/renderer/rhi/PerDrawBlocks.hpp
index 170740e53..414ee2fa1 100644
--- a/src/esengine/renderer/rhi/PerDrawBlocks.hpp
+++ b/src/esengine/renderer/rhi/PerDrawBlocks.hpp
@@ -169,6 +169,7 @@ struct PerDrawBlockSet {
PerDrawBlocks* morph = nullptr;
PerDrawBlocks* probe = nullptr;
PerDrawBlocks* instance = nullptr;
+ PerDrawBlocks* planar = nullptr;
};
} // namespace esengine
diff --git a/src/esengine/renderer/rhi/Shader.cpp b/src/esengine/renderer/rhi/Shader.cpp
index 558218d5a..e4a8dcde5 100644
--- a/src/esengine/renderer/rhi/Shader.cpp
+++ b/src/esengine/renderer/rhi/Shader.cpp
@@ -23,6 +23,7 @@
#include "../store/InstanceConstants.hpp"
#include "../store/MorphConstants.hpp"
#include "../store/ProbeConstants.hpp"
+#include "../store/PlanarConstants.hpp"
#include "../../core/Log.hpp"
#include <cstring>
@@ -250,6 +251,11 @@ bool Shader::compile(const std::string& vertexSrc, const std::string& fragmentSr
device_->uniformBlockBinding(program_, instanceBlock, INSTANCE_CONSTANTS_BINDING);
}
+ const u32 planarBlock = device_->getUniformBlockIndex(program_, PLANAR_CONSTANTS_BLOCK);
+ if (planarBlock != GFX_INVALID_UNIFORM_BLOCK) {
+ device_->uniformBlockBinding(program_, planarBlock, PLANAR_CONSTANTS_BINDING);
+ }
+
// Same for the per-draw params block (rewriteLooseUniforms generates it for
// shaders whose loose uniforms were lifted); commitParams binds the UBO.
u32 drawParamsBlock = device_->getUniformBlockIndex(program_, DRAW_PARAMS_BLOCK);
diff --git a/src/esengine/renderer/store/PlanarConstants.hpp b/src/esengine/renderer/store/PlanarConstants.hpp
new file mode 100644
index 000000000..394b4c9ac
--- /dev/null
+++ b/src/esengine/renderer/store/PlanarConstants.hpp
@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#pragma once
+#include "../../core/Types.hpp"
+#include <glm/glm.hpp>
+namespace esengine {
+inline constexpr u32 PLANAR_CONSTANTS_BINDING = 9;
+inline constexpr const char* PLANAR_CONSTANTS_BLOCK = "PlanarConstants";
+struct PlanarConstants {
+ glm::mat4 projection{1.0f};
+ // x = active, y = render-target UV y sign, zw = one texel.
+ glm::vec4 params{0.0f};
+};
+static_assert(sizeof(PlanarConstants) == 80);
+} // namespace esengine
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index c83de3e7a..b0b33521d 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -564,10 +564,9 @@ private:
u32 bound_pipeline_ = 0;
u32 bound_index_buffer_ = 0;
i32 stencil_ref_ = 0; ///< Last user-set reference (re-applied after internal quads).
- /// Nine: the eight the engine had, plus where a draw's objects start in the
- /// frame's record texture. WebGPU grants 12 uniform buffers a stage and
- /// WebGL2 grants 12 blocks a stage, so nine is inside both.
- static constexpr u32 kUniformSlots = 9;
+ /// Slots 0..9 include the per-draw planar capture. Ten is inside both
+ /// WebGPU's and WebGL2's guaranteed 12 uniform buffers per stage.
+ static constexpr u32 kUniformSlots = 10;
u32 uniform_slots_[kUniformSlots] = {}; ///< BufferHandle id per UBO binding slot.
u32 uniform_offsets_[kUniformSlots] = {};
u32 uniform_sizes_[kUniformSlots] = {}; ///< 0 = the whole buffer.
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index ab249406a..69f758e1c 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -1107,6 +1107,8 @@ struct LightConstants {
@group(0) @binding(2) var<uniform> lc : LightConstants;
struct ProbeConstants { u_probeIrradiance : array<vec4f, 1000>, u_probeTail : vec4f };
@group(0) @binding(7) var<uniform> pc : ProbeConstants;
+struct PlanarConstants { planarProjection : mat4x4f, planarParams : vec4f };
+@group(0) @binding(9) var<uniform> planar : PlanarConstants;
// Which run of that block this fragment's instance reads. WGSL has no module
// varying, so the entry point hands it over — the GLSL twin reads the varying
// straight, which is the one place the two stages differ in shape.
@@ -1449,6 +1451,22 @@ fn reflectionDirection(R : vec3f, P : vec3f, column : f32) -> vec3f {
return (P + R * t) - (lo + hi) * 0.5;
}
fn envRadiance(R : vec3f, roughness : f32, column : f32, P : vec3f) -> vec3f {
+#ifdef ES_ENV_MAP
+ if (planar.planarParams.x > 0.5) {
+ let clip = planar.planarProjection * vec4f(P, 1.0);
+ if (clip.w <= 0.0) { return vec3f(0.0); }
+ let uv = clip.xy / clip.w * vec2f(0.5, 0.5 * planar.planarParams.y) + vec2f(0.5);
+ if (any(uv < vec2f(0.0)) || any(uv > vec2f(1.0))) { return vec3f(0.0); }
+ // A small spatial filter, not prefiltered GGX: preserves material roughness
+ // without allocating a second blur chain or claiming an exact BRDF convolution.
+ let r = max(planar.planarParams.zw, vec2f(roughness * roughness * 0.015));
+ return (textureSampleLevel(t3, s3, uv, 0.0).rgb * 4.0
+ + textureSampleLevel(t3, s3, clamp(uv + vec2f(r.x, 0.0), vec2f(0.0), vec2f(1.0)), 0.0).rgb
+ + textureSampleLevel(t3, s3, clamp(uv - vec2f(r.x, 0.0), vec2f(0.0), vec2f(1.0)), 0.0).rgb
+ + textureSampleLevel(t3, s3, clamp(uv + vec2f(0.0, r.y), vec2f(0.0), vec2f(1.0)), 0.0).rgb
+ + textureSampleLevel(t3, s3, clamp(uv - vec2f(0.0, r.y), vec2f(0.0), vec2f(1.0)), 0.0).rgb) * 0.125;
+ }
+#endif
if (lc.u_envParams.x < 0.5) { return lc.u_ambient.rgb; }
let dir = reflectionDirection(R, P, column);
let lod = clamp(roughness, 0.0, 1.0) * lc.u_envParams.z;
@@ -1942,6 +1960,9 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" highp vec4 u_probeIrradiance[10 * 100];\n"
" highp vec4 u_probeTail;\n" // see PROBE_BLOCK_BYTES
"};\n"
+ "layout(std140) uniform PlanarConstants {\n"
+ " highp mat4 u_planarProjection; highp vec4 u_planarParams;\n"
+ "};\n"
"flat in highp float v_probeSlot;\n"
// The shadow map rides the draw's third texture slot, behind the feature the
// MESH vertex sources set: the batch stream owns 0..7 as a per-vertex merge
@@ -2320,6 +2341,20 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// this is the flat ambient term, the same way the diffuse half is.
"highp vec3 envRadiance(in highp vec3 R, in highp float roughness,\n"
" in highp float column, in highp vec3 P) {\n"
+ "#ifdef ES_ENV_MAP\n"
+ " if (u_planarParams.x > 0.5) {\n"
+ " highp vec4 clip = u_planarProjection * vec4(P, 1.0);\n"
+ " if (clip.w <= 0.0) return vec3(0.0);\n"
+ " highp vec2 uv = clip.xy / clip.w * vec2(0.5, 0.5 * u_planarParams.y) + 0.5;\n"
+ " if (any(lessThan(uv, vec2(0.0))) || any(greaterThan(uv, vec2(1.0)))) return vec3(0.0);\n"
+ " highp vec2 r = max(u_planarParams.zw, vec2(roughness * roughness * 0.015));\n"
+ " return (textureLod(u_envMap, uv, 0.0).rgb * 4.0\n"
+ " + textureLod(u_envMap, clamp(uv + vec2(r.x, 0.0), 0.0, 1.0), 0.0).rgb\n"
+ " + textureLod(u_envMap, clamp(uv - vec2(r.x, 0.0), 0.0, 1.0), 0.0).rgb\n"
+ " + textureLod(u_envMap, clamp(uv + vec2(0.0, r.y), 0.0, 1.0), 0.0).rgb\n"
+ " + textureLod(u_envMap, clamp(uv - vec2(0.0, r.y), 0.0, 1.0), 0.0).rgb) * 0.125;\n"
+ " }\n"
+ "#endif\n"
" if (u_envParams.x < 0.5) return u_ambient.rgb;\n"
" highp vec3 dir = reflectionDirection(R, P, column);\n"
" highp float lod = clamp(roughness, 0.0, 1.0) * u_envParams.z;\n"
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 1a59cfbdb..277d94026 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -304,6 +304,13 @@ target_include_directories(test_clip_depth PRIVATE
)
add_test(NAME test_clip_depth COMMAND test_clip_depth)
+add_executable(test_planar_reflection renderer/test_planar_reflection.cpp)
+target_include_directories(test_planar_reflection PRIVATE
+ ${CMAKE_SOURCE_DIR}/src
+ ${CMAKE_SOURCE_DIR}/third_party/glm
+)
+add_test(NAME test_planar_reflection COMMAND test_planar_reflection)
+
# Shadow atlas allocation. Header-only, and here rather than in a pixel gate for
# the arithmetic a frame cannot show: which square a claim hands out, and what a
# refused one leaves behind. Whether a light READS the square it was given is a
diff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.h
index 077a00def..7e8a1d7b2 100644
--- a/tests/aot/generated/conformance/handshake.h
+++ b/tests/aot/generated/conformance/handshake.h
@@ -1,5 +1,5 @@
/* GENERATED by sdk/tests/aot-conformance.test.ts — do not edit. */
/* The contract half of the handshake. The width half is the harness. */
-#define ES_CONF_EXPECTED_CONTRACT_HASH 0x33ad01505ff01deaULL
+#define ES_CONF_EXPECTED_CONTRACT_HASH 0x5b7515b290a65867ULL
/* And which BUILD the artifact beside this one is. */
#define ES_CONF_EXPECTED_MODULE_CONTRACT 0xc3d0e057d5701a2eULL
diff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.c
index 11a345ed1..9d0a1298b 100644
--- a/tests/aot/generated/conformance/systems_decl.c
+++ b/tests/aot/generated/conformance/systems_decl.c
@@ -10,7 +10,7 @@
answer, it is a read of a different field. The address width belongs
to the MACHINE, so it mixes in here rather than in the compiler and a
32-bit artifact cannot load into a 64-bit host. */
-#define ES_ABI_ENGINE_DIGEST 0x33ad01505ff01deaULL
+#define ES_ABI_ENGINE_DIGEST 0x5b7515b290a65867ULL
ES_EXPORT const uint64_t es_abi_hash =
ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));
diff --git a/tests/renderer/test_planar_reflection.cpp b/tests/renderer/test_planar_reflection.cpp
new file mode 100644
index 000000000..693e3443d
--- /dev/null
+++ b/tests/renderer/test_planar_reflection.cpp
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include <doctest.h>
+#include "esengine/renderer/frame/PlanarReflectionCamera.hpp"
+#include "esengine/renderer/draw/DrawCommand.hpp"
+#include <glm/gtc/matrix_transform.hpp>
+
+using namespace esengine;
+namespace {
+glm::vec3 projected(const glm::mat4& vp, const glm::vec3& p) {
+ const glm::vec4 q = vp * glm::vec4(p, 1);
+ return glm::vec3(q) / q.w;
+}
+}
+TEST_CASE("planar camera mirrors geometry with an unchanged surface projection") {
+ const glm::mat4 source = glm::perspective(glm::radians(55.0f), 1.5f, 0.1f, 100.0f)
+ * glm::lookAt(glm::vec3(3, 4, 7), glm::vec3(0), glm::vec3(0, 1, 0));
+ PlanarReflectionCamera camera;
+ REQUIRE(planarReflectionCamera(source, {0,0,0}, {0,1,0}, 0, camera));
+ const auto eye = cameraFromViewProjection(camera.projection);
+ CHECK(eye.x == doctest::Approx(3).epsilon(1e-4));
+ CHECK(eye.y == doctest::Approx(-4).epsilon(1e-4));
+ CHECK(eye.z == doctest::Approx(7).epsilon(1e-4));
+ for (const glm::vec3 p : {glm::vec3(1,0,1), glm::vec3(-2,0,-1)}) {
+ const auto a = projected(source, p), b = projected(camera.samplingProjection, p);
+ CHECK(a.x == doctest::Approx(-b.x).epsilon(1e-4));
+ CHECK(a.y == doctest::Approx(b.y).epsilon(1e-4));
+ }
+ CHECK(glm::determinant(source) * glm::determinant(camera.samplingProjection) > 0);
+}
+TEST_CASE("near clipping rejects the opposite half space on both devices") {
+ for (const bool ortho : {false, true}) {
+ const glm::mat4 projection = ortho ? glm::ortho(-5.0f,5.0f,-5.0f,5.0f,0.1f,100.0f)
+ : glm::perspective(glm::radians(60.0f),1.0f,0.1f,100.0f);
+ const glm::mat4 source = projection * glm::lookAt(glm::vec3(0,3,6),glm::vec3(0),glm::vec3(0,1,0));
+ PlanarReflectionCamera camera;
+ REQUIRE(planarReflectionCamera(source, {0,0,0}, {0,1,0}, 0.02f, camera));
+ for (auto range : {ClipDepthRange::MinusOneToOne, ClipDepthRange::ZeroToOne}) {
+ const auto vp = toClipDepthRange(camera.projection, range);
+ const float nearDepth = range == ClipDepthRange::MinusOneToOne ? -1.0f : 0.0f;
+ CHECK(projected(vp,{0,1,0}).z > nearDepth);
+ CHECK(projected(vp,{0,-1,0}).z < nearDepth);
+ CHECK(projected(vp,{0,0.02f,0}).z == doctest::Approx(nearDepth).epsilon(1e-4));
+ }
+ }
+}
+TEST_CASE("tilted planes and cameras on either side share the same contract") {
+ const auto normal = glm::normalize(glm::vec3(1,1,0));
+ const glm::vec3 origin(2,1,-1);
+ for (float side : {-1.0f,1.0f}) {
+ const glm::vec3 eye = origin + side * normal * 4.0f + glm::vec3(0,0,6);
+ const auto source = glm::perspective(glm::radians(60.0f),1.0f,0.1f,100.0f)
+ * glm::lookAt(eye, origin, glm::vec3(0,1,0));
+ PlanarReflectionCamera camera;
+ REQUIRE(planarReflectionCamera(source, origin, normal, 0, camera));
+ CHECK(projected(camera.projection, origin + normal * side).z > -1);
+ CHECK(projected(camera.projection, origin - normal * side).z < -1);
+ }
+}
+TEST_CASE("invalid and grazing inputs leave no invalid camera") {
+ PlanarReflectionCamera camera;
+ CHECK_FALSE(planarReflectionCamera(glm::mat4(0), {0,0,0}, {0,1,0},0,camera));
+ CHECK_FALSE(planarReflectionCamera(glm::mat4(1), {0,0,0}, {0,0,0},0,camera));
+ CHECK_FALSE(planarReflectionCamera(glm::mat4(1), {0,0,0}, {0,1,0},0,camera));
+}
+TEST_CASE("receiving and ordinary surfaces never merge their uniform blocks") {
+ DrawCommand a, b;
+ a.planar_index = 1;
+ CHECK_FALSE(a.canMergeWith(b));
+ CHECK(a.mergeBlocker(b) == BatchBreak::Material);
+}
diff --git a/tests/renderer/test_render_graph.cpp b/tests/renderer/test_render_graph.cpp
index 782da3e30..ff1ce55b5 100644
--- a/tests/renderer/test_render_graph.cpp
+++ b/tests/renderer/test_render_graph.cpp
@@ -37,6 +37,22 @@ rg::PassDesc fullscreen(const char* name, std::vector<rg::ResourceId> reads,
} // namespace
int main() {
+ // A persistent capture is an input to the scene, not its replacement.
+ {
+ MockGfxDevice d;
+ rg::RenderGraph graph(d);
+ std::vector<std::string> ran;
+ graph.begin(256, 128);
+ const auto screen = graph.importTarget(FramebufferHandle{9}, 256, 128);
+ const auto capture = graph.importTarget(FramebufferHandle{10}, 128, 64, false);
+ graph.addPass(fullscreen("capture", {}, capture, &ran));
+ auto scene = fullscreen("scene", {}, screen, &ran);
+ scene.dependencies.push_back(capture);
+ graph.addPass(std::move(scene));
+ graph.execute();
+ CHECK((ran == std::vector<std::string>{"capture", "scene"}),
+ "a non-output import preserves the final scene and its capture dependency");
+ }
// --- a linear chain runs on two physical targets ---
{
MockGfxDevice d;
diff --git a/tools/check-shader-blocks.mjs b/tools/check-shader-blocks.mjs
index d1c1d6b57..7bb3b39a6 100644
--- a/tools/check-shader-blocks.mjs
+++ b/tools/check-shader-blocks.mjs
@@ -30,6 +30,7 @@ const BLOCKS = {
FrameConstants: 'src/esengine/renderer/frame/FrameConstants.hpp',
TimeConstants: 'src/esengine/renderer/frame/FrameConstants.hpp',
LightConstants: 'src/esengine/renderer/store/LightConstants.hpp',
+ PlanarConstants: 'src/esengine/renderer/store/PlanarConstants.hpp',
};
const parser = readFileSync(path.join(ROOT, PARSER), 'utf8');
@@ -88,6 +89,8 @@ const ALIASES = {
// The block holds view * projection; the shaders have called it u_projection
// since before there was a view, and `.esshader` is a format users write.
'FrameConstants.viewProjection': 'projection',
+ 'PlanarConstants.projection': 'planarProjection',
+ 'PlanarConstants.params': 'planarParams',
};
/**
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 67386e773..a89e977af 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -22,6 +22,7 @@ import {
getComponent, DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice,
getContextLossGuardInfo, decodeImagePixels, captureFramePixels, captureFrame, replayDraw, BatchBreak,
RenderTexture, Camera, Sprite,
+ planarReflectionStatus,
EditorViewLighting, EditorViewShading, EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,
ProfileRecorder, AnimatorController, Timeline, onDeviceRestored, Schedule, defineSystem,
textureImportSettingsFrom,
@@ -416,6 +417,10 @@ function skeletalSource(toUrl: (ref: string) => string, label: string): RuntimeA
const api = {
loadScene,
+ planarReflectionStatus(id: number, cameraId?: number) {
+ if (!app) throw new Error('planarReflectionStatus before boot');
+ return planarReflectionStatus(app, requireEntity(id), cameraId === undefined ? 0 : requireEntity(cameraId));
+ },
resizeViewport(w: number, h: number): void {
if (!canvas) throw new Error('resizeViewport before boot');
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 2bc0bcf9d..52a29efc2 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -354,6 +354,9 @@ export const SCENES = [
// surface reflects +Z, which is the image centre — green there, and the whole
// sphere averaged at the rough end. One flat term would draw them alike.
+ // Dynamic captures keep source geometry and the clipped reflection visible together.
+ {"id": "planar-reflection", "tier": "pr", "webgpu": true, "env": {"ESTELLA_VERIFY_SCENE": "/scenes/planar-reflection.esscene", "ESTELLA_VERIFY_W": "512", "ESTELLA_VERIFY_H": "512", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_EXPECT": "[{\"x\": 0.390625, \"y\": 0.41015625, \"rgb\": [255, 0, 0], \"tol\": 25}, {\"x\": 0.390625, \"y\": 0.56640625, \"rgb\": [255, 0, 0], \"tol\": 25}, {\"x\": 0.60546875, \"y\": 0.5234375, \"rgb\": [0, 255, 0], \"tol\": 25}]", "ESTELLA_VERIFY_COUNTERS": "{\"render.planar.draws\": 1}"}},
+ {"id": "planar-reflection-off", "tier": "pr", "webgpu": true, "env": {"ESTELLA_VERIFY_SCENE": "/scenes/planar-reflection.esscene", "ESTELLA_VERIFY_W": "512", "ESTELLA_VERIFY_H": "512", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_EXPECT": "[{\"x\": 0.390625, \"y\": 0.41015625, \"rgb\": [255, 0, 0], \"tol\": 25}, {\"x\": 0.390625, \"y\": 0.56640625, \"rgb\": [0, 0, 0], \"tol\": 15}]", "ESTELLA_VERIFY_SET_FIELD": "{\"entity\": 2, \"component\": \"PlanarReflection\", \"key\": \"enabled\", \"value\": false, \"steps\": 3}"}},
// TWO mirrors under one sky, one inside a ReflectionProbe: the baked column is
// red and the sky green, so the picture says which answer each surface took.
// One atlas serves both — a reflection is a number per instance, not a bind.
diff --git a/tools/tests/planar-reflection.e2e.mjs b/tools/tests/planar-reflection.e2e.mjs
new file mode 100644
index 000000000..d609b712f
--- /dev/null
+++ b/tools/tests/planar-reflection.e2e.mjs
@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+// Genuine headless Chromium, shipped SDK + WASM, and the engine-owned render host.
+import { chromium } from 'playwright';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile, realpath, mkdir, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import assert from 'node:assert/strict';
+import { requireCurrentEngine } from '../lib/engineBuild.mjs';
+const { PNG } = createRequire(new URL('../../pipeline/package.json', import.meta.url))('pngjs');
+const repo = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+requireCurrentEngine(repo, path.join(repo, 'build/render-host/wasm'));
+const out = path.join(repo, 'output/rm044-runtime');
+await mkdir(out, { recursive: true });
+const server = http.createServer(async (req, res) => {
+ try {
+ const url = new URL(req.url, 'http://localhost');
+ if (url.pathname === '/favicon.ico') { res.writeHead(204).end(); return; }
+ const under = decodeURIComponent(url.pathname);
+ const scenes = under.startsWith('/scenes/');
+ const root = await realpath(path.join(repo, scenes ? 'fixtures/scenes' : 'build/render-host'));
+ const file = await realpath(path.resolve(root, scenes ? under.slice(8) : under.slice(1) || 'index.html'));
+ if (!file.startsWith(root + path.sep)) throw Error('Outside host');
+ res.setHeader('Content-Type', ({'.js':'text/javascript','.wasm':'application/wasm','.html':'text/html'})[path.extname(file)] ?? 'application/octet-stream');
+ res.end(await readFile(file));
+ } catch { res.writeHead(404).end(); }
+});
+await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+const browser = await chromium.launch({ channel: 'chromium', headless: true, args: ['--enable-unsafe-webgpu', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader', '--mute-audio'] });
+const report = { status: 'failed', mode: 'headless-engine', checks: [], deviceAcceptance: 'pending' };
+try {
+ const backends = process.argv.includes('--webgl-only') ? ['webgl2'] : ['webgl2', 'webgpu'];
+ for (const backend of backends) {
+ const page = await browser.newPage({ viewport: {width:512,height:512} });
+ const errors = [];
+ const lossLogs = [];
+ let injectingLoss = false;
+ report.activeBackend = backend;
+ report.errors = errors;
+ page.on('pageerror', e => errors.push(String(e)));
+ page.on('console', msg => { if (msg.type() === 'error') (injectingLoss ? lossLogs : errors).push(msg.text()); });
+ await page.goto(`http://127.0.0.1:${server.address().port}/?w=512&h=512&backend=${backend}`);
+ await page.evaluate(async () => { await window.__estellaHeadless.ready; });
+ const load = await page.evaluate(() => window.__estellaHeadless.api.loadScene('/scenes/planar-reflection.esscene'));
+ assert.deepEqual(load.missing, []);
+ const step = n => page.evaluate(n => window.__estellaHeadless.api.step(n), n);
+ const field = (id, component, key, value) => page.evaluate(({id,component,key,value}) => window.__estellaHeadless.api.setField(id,component,key,'',value), {id,component,key,value});
+ const status = () => page.evaluate(() => window.__estellaHeadless.api.planarReflectionStatus(2,1));
+ const capture = async name => {
+ const raw = await page.evaluate(async () => {
+ const p = await window.__estellaHeadless.api.captureViewportPixels();
+ return {width:p.width,height:p.height,data:Array.from(p.rgba)};
+ });
+ const image = new PNG({width:raw.width,height:raw.height});
+ // The engine readback contract is bottom-up on both backends; PNG is top-down.
+ const pixels = Buffer.from(raw.data), stride = raw.width * 4;
+ for (let y=0;y<raw.height;y++) pixels.copy(image.data,y*stride,(raw.height-1-y)*stride,(raw.height-y)*stride);
+ await writeFile(path.join(out, `${backend}-${name}.png`), PNG.sync.write(image));
+ return image;
+ };
+ const changed = (a,b,startY=0) => {
+ let count=0;
+ for(let i=startY*a.width*4;i<a.data.length;i+=4) {
+ if(Math.abs(a.data[i]-b.data[i])+Math.abs(a.data[i+1]-b.data[i+1])+Math.abs(a.data[i+2]-b.data[i+2])>40) count++;
+ }
+ return count;
+ };
+ await step(3);
+ const ready = await status();
+ assert.equal(ready.state,'ready', JSON.stringify({ready,errors}));
+ assert.equal(ready.width,512); assert.ok(ready.draws>0);
+ const on = await capture('enabled');
+ const drawsOn = await page.evaluate(() => window.__estellaHeadless.api.getStats().drawCalls);
+ const pixel = (image,x,y) => Array.from(image.data.subarray((y*image.width+x)*4,(y*image.width+x)*4+3));
+ for (const [x,y,r,g] of [[200,210,255,0],[200,290,255,0],[310,214,0,255],[310,268,0,255]]) {
+ const c = pixel(on,x,y);
+ assert.ok(Math.abs(c[0]-r)<25 && Math.abs(c[1]-g)<25 && c[2]<25, `source/reflection placement ${backend} ${x},${y}: ${c}`);
+ }
+ await field(2,'PlanarReflection','enabled',false); await step(3);
+ assert.equal((await status()).state,'inactive');
+ const off = await capture('disabled');
+ const drawsOff = await page.evaluate(() => window.__estellaHeadless.api.getStats().drawCalls);
+ assert.equal(drawsOn-drawsOff,ready.draws,'frame statistics must include the capture cost');
+ assert.ok(changed(on,off,256)>100,'reflection must change the lower half of the image');
+ assert.ok(pixel(off,200,290).every(c=>c<10),'disabled reflection must not leave stale pixels');
+ await field(2,'PlanarReflection','enabled',true); await step(2);
+ await field(5,'MeshRenderer','enabled',false); await step(2);
+ const noUnderwater = await capture('below-plane-hidden');
+ assert.equal(changed(on,noUnderwater),0,'opposite-half-space object must be clipped');
+ await field(2,'PlanarReflection','cullingMask',4); await step(2);
+ const masked = await capture('green-layer-only');
+ assert.ok(pixel(masked,200,290).every(c=>c<10),'reflection mask must exclude red layer');
+ assert.ok(pixel(masked,310,268)[1]>230,'reflection mask must keep green layer');
+ assert.ok(pixel(masked,200,210)[0]>230,'capture mask must not change the source view');
+ await field(2,'PlanarReflection','cullingMask',0xffffffff); await step(2);
+ await field(3,'Transform','position.x',-0.5); await step(2);
+ const moved = await capture('moved');
+ assert.ok(changed(on,moved,256)>100,'moving geometry must update its reflection');
+ await field(2,'PlanarReflection','update',1);
+ await field(2,'PlanarReflection','updatesPerSecond',1); await step(2);
+ assert.equal((await status()).updated,false,'capture rate must be independent of scene frames');
+ await field(2,'PlanarReflection','update',2); await step(2);
+ await field(3,'Transform','position.x',1); await step(2);
+ assert.equal((await status()).updated,false,'OnDemand must keep its capture');
+ await field(2,'PlanarReflection','revision',1); await step(1);
+ assert.equal((await status()).updated,true,'revision requests a new capture');
+ await field(2,'PlanarReflection','maxSize',128); await step(1);
+ assert.equal((await status()).width,128,'resize must rebuild and refresh the target');
+ assert.deepEqual(errors,[]);
+ const beforeLoss = await capture('before-loss');
+ injectingLoss = true;
+ const recovery = await page.evaluate(async () => {
+ const {device:d,api} = window.__estellaHeadless;
+ const generation = d.deviceGen();
+ if (!d.lose()) throw Error('Device loss injection unavailable');
+ for (let i=0;i<30 && d.status()===0;i++) { await api.step(1); await new Promise(r=>setTimeout(r,50)); }
+ const lost = d.status();
+ d.restore();
+ await new Promise(r=>setTimeout(r,500));
+ let recovered = false;
+ for (let i=0;i<20 && !recovered;i++) { recovered=d.recover(); if(!recovered) await new Promise(r=>setTimeout(r,100)); }
+ if (!recovered || !(await d.recoverFull())) throw Error('Full device recovery failed');
+ await api.step(1);
+ return {lost,before:generation,after:d.deviceGen()};
+ });
+ injectingLoss = false;
+ assert.notEqual(recovery.lost,0);
+ assert.ok(recovery.after>recovery.before);
+ assert.equal((await status()).updated,true,'OnDemand must refresh after device recovery');
+ const afterLoss = await capture('after-loss');
+ assert.equal(changed(beforeLoss,afterLoss),0,'recovered capture must match its previous content');
+ assert.ok(lossLogs.every(line=>/lost|destroyed|context.*restore/i.test(line)),JSON.stringify(lossLogs));
+ assert.deepEqual(errors,[]);
+ await field(3,'Transform','position.x',-1.3);
+ await field(2,'PlanarReflection','update',0);
+ await field(2,'PlanarReflection','maxSize',512);
+ await field(1,'Camera','viewport',{x:0,y:0,z:0.5,w:1});
+ await field(6,'Camera','isActive',true); await step(2);
+ const secondView = await page.evaluate(() => window.__estellaHeadless.api.planarReflectionStatus(2,6));
+ assert.equal((await status()).width,256);
+ assert.equal(secondView.width,256);
+ const split = await capture('two-cameras');
+ assert.ok(pixel(split,72,290)[0]>230,'first view must keep its own reflection');
+ assert.ok(pixel(split,375,268)[1]>230,'second view must capture from its own camera');
+ assert.deepEqual(errors,[]);
+ report.checks.push({backend,ready,drawsOn,drawsOff,reflectionPixels:changed(on,off,256),movingPixels:changed(on,moved,256),recovery,secondView,lossLogs,errors});
+ await page.close();
+ }
+ report.status = 'checks-passed';
+ delete report.activeBackend;
+ console.log(JSON.stringify(report));
+} catch (error) { report.error = String(error); throw error; }
+finally {
+ await writeFile(path.join(out,'report.json'),JSON.stringify(report,null,2));
+ await browser.close(); await new Promise(resolve=>server.close(resolve));
+}