A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
Implement shared planar reflection captures and authoring
yhh7b7e62d1c84f
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 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_activitytest_shader_device test_draw_params test_per_draw_blocks test_texture_fb test_buffer_devicetest_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_storetest_text_edit test_render_graph test_device_loss test_physics_interpolationtest_bitmap_font test_texture_cache test_material_shader_lifetime test_mesh_recovery test_aot_host test_aot_conformancetest_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 hostrun: 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 framesif: always()uses: actions/upload-artifact@v7diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.cmakeindex 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.cppdiff --git a/desktop b/desktopindex a1acec43c..e69f4b736 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit a1acec43c6f90d45608746acad949b505ca409bb+Subproject commit e69f4b736529099cd50b3294c9f38b7919feae51diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdxindex 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 appconst 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 editordiff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxindex 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 无界面检查覆盖几何位置、裁剪、层过滤与更新策略;+移动端真机帧时间验收仍待完成。+## 在编辑器里diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.esmaterialnew file mode 100644index 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.metanew file mode 100644index 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.esmeshnew file mode 100644index 000000000..50c383e43Binary files /dev/null and b/examples/planar-reflection/assets/meshes/plane.esmesh differdiff --git a/examples/planar-reflection/assets/meshes/plane.esmesh.meta b/examples/planar-reflection/assets/meshes/plane.esmesh.metanew file mode 100644index 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.esscenenew file mode 100644index 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.metanew file mode 100644index 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.esprojectnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.esmaterialnew file mode 100644index 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.esscenenew file mode 100644index 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.mdindex 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: QualityControllerminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number+planarReflectionMaxSize: number+planarReflectionScale: number+planarReflectionUpdatesPerSecond: numberpostProcess: booleanrenderScale: numbershadowAtlasSize: number@@ -7016,6 +7049,13 @@ get: () => Tsubscribe: (fn: (value: T) => void) => () => void```+## ReflectionAxis — enum @experimental+```+X = 0+Y = 1+Z = 2+```+## ReflectionProbe — const @experimental```BuiltinComponentDef<ReflectionProbeData>@@ -7029,6 +7069,19 @@ reflection: numberslot: 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>): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: QualityControllerminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number+planarReflectionMaxSize: number+planarReflectionScale: number+planarReflectionUpdatesPerSecond: numberpostProcess: booleanrenderScale: numbershadowAtlasSize: number@@ -7229,6 +7262,13 @@ get: () => Tsubscribe: (fn: (value: T) => void) => () => void```+## ReflectionAxis — enum @experimental+```+X = 0+Y = 1+Z = 2+```+## ReflectionProbe — const @experimental```BuiltinComponentDef<ReflectionProbeData>@@ -7242,6 +7282,19 @@ reflection: numberslot: 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>): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: QualityControllerminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number+planarReflectionMaxSize: number+planarReflectionScale: number+planarReflectionUpdatesPerSecond: numberpostProcess: booleanrenderScale: numbershadowAtlasSize: number@@ -7011,6 +7044,13 @@ get: () => Tsubscribe: (fn: (value: T) => void) => () => void```+## ReflectionAxis — enum @experimental+```+X = 0+Y = 1+Z = 2+```+## ReflectionProbe — const @experimental```BuiltinComponentDef<ReflectionProbeData>@@ -7024,6 +7064,19 @@ reflection: numberslot: 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>): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: QualityControllerminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number+planarReflectionMaxSize: number+planarReflectionScale: number+planarReflectionUpdatesPerSecond: numberpostProcess: booleanrenderScale: numbershadowAtlasSize: number@@ -7304,6 +7337,13 @@ get: () => Tsubscribe: (fn: (value: T) => void) => () => void```+## ReflectionAxis — enum @experimental+```+X = 0+Y = 1+Z = 2+```+## ReflectionProbe — const @experimental```BuiltinComponentDef<ReflectionProbeData>@@ -7317,6 +7357,19 @@ reflection: numberslot: 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>): voiddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 2fd7d1f8b..d3b8b7071 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -41,6 +41,7 @@ addOccluder: (entity: Entity, component: Occluder) => voidaddParent: (entity: Entity, component: Parent) => voidaddParticleEmitter: (entity: Entity, component: ParticleEmitter) => voidaddParticleForceField: (entity: Entity, component: ParticleForceField) => void+addPlanarReflection: (entity: Entity, component: PlanarReflection) => voidaddReflectionProbe: (entity: Entity, component: ReflectionProbe) => voidaddRigidBody2D: (entity: Entity, component: RigidBody2D) => voidaddRigidBody3D: (entity: Entity, component: RigidBody3D) => void@@ -95,6 +96,7 @@ getOccluder: (entity: Entity) => OccludergetParent: (entity: Entity) => ParentgetParticleEmitter: (entity: Entity) => ParticleEmittergetParticleForceField: (entity: Entity) => ParticleForceField+getPlanarReflection: (entity: Entity) => PlanarReflectiongetReflectionProbe: (entity: Entity) => ReflectionProbegetRigidBody2D: (entity: Entity) => RigidBody2DgetRigidBody3D: (entity: Entity) => RigidBody3D@@ -143,6 +145,7 @@ hasOccluder: (entity: Entity) => booleanhasParent: (entity: Entity) => booleanhasParticleEmitter: (entity: Entity) => booleanhasParticleForceField: (entity: Entity) => boolean+hasPlanarReflection: (entity: Entity) => booleanhasReflectionProbe: (entity: Entity) => booleanhasRigidBody2D: (entity: Entity) => booleanhasRigidBody3D: (entity: Entity) => boolean@@ -194,6 +197,7 @@ removeOccluder: (entity: Entity) => voidremoveParent: (entity: Entity) => voidremoveParticleEmitter: (entity: Entity) => voidremoveParticleForceField: (entity: Entity) => void+removePlanarReflection: (entity: Entity) => voidremoveReflectionProbe: (entity: Entity) => voidremoveRigidBody2D: (entity: Entity) => voidremoveRigidBody3D: (entity: Entity) => void@@ -453,6 +457,7 @@ renderer_getEstimatedGpuBytes: (() => number) | undefinedrenderer_getGpuTimeMs: (() => number) | undefinedrenderer_getLiveObjects: (() => GfxLiveObjects | null) | undefinedrenderer_getMeshes: () => number+renderer_getPlanarReflectionStatus: ((view: number, entity: number) => string) | undefinedrenderer_getPreviewHeight: () => numberrenderer_getPreviewPtr: () => numberrenderer_getPreviewSize: () => number@@ -494,6 +499,7 @@ renderer_setDepthLayers: ((mask: number) => void) | undefinedrenderer_setEntityDrawOrder: ((registry: CppRegistry, entitiesPtr: number, count: number) => void) | undefinedrenderer_setLodPreview: ((view: number, entity: number, level: number) => void) | undefinedrenderer_setMeshEdgeBuffers: ((enabled: boolean) => void) | undefined+renderer_setPlanarReflectionQuality: ((scale: number, maxSize: number, updatesPerSecond: number) => void) | undefinedrenderer_setQualityBudgets: ((atlasSize: number, cellSize: number, cascades: number, particleLimit: number) => void) | undefinedrenderer_setShadowDistance: ((distance: number) => void) | undefinedrenderer_setStage: (stage: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: QualityControllerminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number+planarReflectionMaxSize: number+planarReflectionScale: number+planarReflectionUpdatesPerSecond: numberpostProcess: booleanrenderScale: numbershadowAtlasSize: number@@ -7018,6 +7051,13 @@ get: () => Tsubscribe: (fn: (value: T) => void) => () => void```+## ReflectionAxis — enum @experimental+```+X = 0+Y = 1+Z = 2+```+## ReflectionProbe — const @experimental```BuiltinComponentDef<ReflectionProbeData>@@ -7031,6 +7071,19 @@ reflection: numberslot: 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>): voiddiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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>('LightProbeVmetaDefaults<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 Componentdiff --git a/sdk/src/render/planarReflection.ts b/sdk/src/render/planarReflection.tsnew file mode 100644index 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.tsindex 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.tsindex 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: nuquality.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.tsindex 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.tsindex 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.tsindex 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.snapindex 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.tsindex 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.cppindex 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 [®istry](std::uint32_t raw) -> void* {+ return registry.tryGet<esengine::ecs::PlanarReflection>(Entity::fromRaw(raw));+ };+ }if (std::strcmp(name, "ReflectionProbe") == 0) {return [®istry](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* namereturn denseAsIds(registry.entitiesWith<esengine::ecs::ParticleForceField>());};}+ if (std::strcmp(name, "PlanarReflection") == 0) {+ return [®istry]() -> Candidates {+ return denseAsIds(registry.entitiesWith<esengine::ecs::PlanarReflection>());+ };+ }if (std::strcmp(name, "ReflectionProbe") == 0) {return [®istry]() -> 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.cppindex 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::selse 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::stelse 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::strif (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::striif (!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::stelse 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::stconst 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.cppindex 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, fg_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.hppindex 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, indiff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 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 offstatic_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.cppindex 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.hppnew file mode 100644index 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::ecsdiff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hppindex 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.cppindex 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.hppindex 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.hppindex 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.cppindex 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.hppindex 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.hppnew file mode 100644index 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 esenginediff --git a/src/esengine/renderer/frame/RenderContext.cpp b/src/esengine/renderer/frame/RenderContext.cppindex 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 validmaterials_.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.hppindex 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.cppindex 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 tpass.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.hppindex 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.cppnew file mode 100644index 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, ®istry, 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 esenginediff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cppindex 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 heigreturn 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.hppindex 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.cppindex 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, Entitbool& 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.hppindex 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 esenginediff --git a/src/esengine/renderer/rhi/Shader.cpp b/src/esengine/renderer/rhi/Shader.cppindex 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& fragmentSrdevice_->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.hppnew file mode 100644index 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 esenginediff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex 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.cppindex 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;+ }+#endifif (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.txtindex 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 adiff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.hindex 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 0xc3d0e057d5701a2eULLdiff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.cindex 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 belongsto the MACHINE, so it mixes in here rather than in the compiler and a32-bit artifact cannot load into a 64-bit host. */-#define ES_ABI_ENGINE_DIGEST 0x33ad01505ff01deaULL+#define ES_ABI_ENGINE_DIGEST 0x5b7515b290a65867ULLES_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.cppnew file mode 100644index 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.cppindex 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,} // namespaceint 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.mjsindex 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.tsindex 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): RuntimeAconst 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.mjsindex 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.mjsnew file mode 100644index 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));+}