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
fix: fit shadow maps to placed and deformed geometry
yhhfa13ec0e2ae2
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 873a5a951..51b466cdf 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -105,6 +105,15 @@ jobs:run: node tools/tests/render-clock.e2e.mjs --webgl-only- name: Check native placement bounds with genuine headless Chromiumrun: node tools/tests/placement-bounds.e2e.mjs --webgl-only+ - name: Check instance and deformed shadow coverage with genuine headless Chromium+ run: node tools/tests/placement-shadows.e2e.mjs --webgl-only+ - name: Upload native placement shadow observations+ if: always()+ uses: actions/upload-artifact@v7+ with:+ name: placement-shadow-runtime+ path: output/placement-shadows/+ retention-days: 3- name: Upload native placement observationsif: always()uses: actions/upload-artifact@v7diff --git a/docs/astro/src/content/docs/performance/static-batching.mdx b/docs/astro/src/content/docs/performance/static-batching.mdxindex f605f3b4b..b742cf4f4 100644--- a/docs/astro/src/content/docs/performance/static-batching.mdx+++ b/docs/astro/src/content/docs/performance/static-batching.mdx@@ -112,6 +112,11 @@ mesh LODs and the material's declared `vertexbounds`. Those bounds includeplacement rotation, scale and shear. A material that moves vertices must declareits full local displacement so a visible surface is not culled at a view edge.+Shadow-map coverage uses the same usable LOD geometry and declared displacement,+transformed through every placement and its parent. Empty instance groups add no+bounds. Receiver, caster and hair-focus bounds are gathered in one traversal, so+instancing does not move a shadow map away from the geometry it must cover.+Measured in the editor's Play on WebGL2, a model of 2,004 parts (1,600 planks, 400 posts and fourprops) under one root:diff --git a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdxindex 7a37adff3..fac5779fc 100644--- a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx@@ -100,6 +100,9 @@ world.insert(ship, CompositeBatch, {});植被和组合模型共用的原生实例组,会把两个网格 LOD 和材质声明的 `vertexbounds` 一起计入每个实例的范围,并覆盖实例的旋转、缩放与剪切。会移动顶点的材质必须声明完整的局部变形范围,避免仍在画面中的表面在视野边缘被剔除。+阴影贴图使用相同的有效 LOD 网格和材质变形范围,并计入每个实例及其父实体的变换;空实例组不占范围。+接收阴影的场景范围、投影物范围和头发精细阴影范围在一次遍历中收集,避免实例化后阴影贴图偏离实际几何。+在编辑器 Play、WebGL2 下实测,一个根节点下 2,004 个部件(1,600 块甲板、400 根柱子、4 个道具):| | 不加 | `CompositeBatch` |diff --git a/fixtures/scenes/placement-shadow-bend.esscene b/fixtures/scenes/placement-shadow-bend.esscenenew file mode 100644index 000000000..be50c5181--- /dev/null+++ b/fixtures/scenes/placement-shadow-bend.esscene@@ -0,0 +1,30 @@+{+ "version": 4,+ "name": "PlacementShadowBend",+ "entities": [+ { "id": 0, "name": "Camera", "parent": null, "children": [], "visible": true,+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ]+ },+ { "id": 1, "name": "Receiver", "parent": null, "children": [], "visible": true,+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -200 }, "scale": { "x": 600, "y": 600, "z": 1 } } },+ { "type": "MeshRenderer", "data": { "mesh": "/scenes/shadow-quad.esmesh", "lit": true, "opaque": true, "enabled": true, "castShadows": false } }+ ]+ },+ { "id": 2, "name": "Displaced caster behind camera", "parent": null, "children": [], "visible": true,+ "components": [+ { "type": "Transform", "data": { "scale": { "x": 150, "y": 150, "z": 1 } } },+ { "type": "MeshRenderer", "data": { "mesh": "/scenes/shadow-quad.esmesh", "material": "/scenes/placement-shadow-bend/caster.esmaterial", "opaque": true, "enabled": true } }+ ]+ },+ { "id": 3, "name": "Sun", "parent": null, "children": [], "visible": true,+ "components": [+ { "type": "Transform", "data": {} },+ { "type": "Light", "data": { "type": 1, "intensity": 1, "direction": { "x": 0, "y": 0 }, "meshShadows": true, "shadowExtent": 300 } }+ ]+ }+ ]+}diff --git a/fixtures/scenes/placement-shadow-bend/caster.esmaterial b/fixtures/scenes/placement-shadow-bend/caster.esmaterialnew file mode 100644index 000000000..65f2acb75--- /dev/null+++ b/fixtures/scenes/placement-shadow-bend/caster.esmaterial@@ -0,0 +1,11 @@+{+ "version": "1.0",+ "type": "material",+ "name": "Displaced shadow caster",+ "shader": "caster.esshader",+ "properties": {},+ "blendMode": 0,+ "depthTest": true,+ "depthWrite": true,+ "cull": 0+}diff --git a/fixtures/scenes/placement-shadow-bend/caster.esshader b/fixtures/scenes/placement-shadow-bend/caster.esshadernew file mode 100644index 000000000..5d8be965d--- /dev/null+++ b/fixtures/scenes/placement-shadow-bend/caster.esshader@@ -0,0 +1,26 @@+#pragma shader "DisplacedShadowCaster"+#pragma version 300 es+#pragma domain Unlit+#pragma vertexbounds 5000++#pragma vertexoffset+void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {+ local.z += 5000.0;+}+#pragma end++#pragma vertexoffset wgsl+fn esMaterialVertex(local: ptr<function, vec3f>, localNormal: ptr<function, vec3f>, uv: vec2f) {+ (*local).z += 5000.0;+}+#pragma end++#pragma fragment+precision highp float;+out vec4 fragColor;+void main() { fragColor = vec4(0.0, 1.0, 0.0, 1.0); }+#pragma end++#pragma fragment wgsl+@fragment fn fs_main(v: VSOut) -> @location(0) vec4f { return vec4f(0.0, 1.0, 0.0, 1.0); }+#pragma enddiff --git a/src/esengine/renderer/draw/MeshGeometry.hpp b/src/esengine/renderer/draw/MeshGeometry.hppnew file mode 100644index 000000000..82d24e027--- /dev/null+++ b/src/esengine/renderer/draw/MeshGeometry.hpp@@ -0,0 +1,81 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file MeshGeometry.hpp+ * @brief Shared mesh LOD eligibility and local bounds for drawing and shadow fitting.+ */+#pragma once++#include "../lod/LodSelection.hpp"+#include "../../ecs/components/LODGroup.hpp"+#include "../../ecs/components/MeshRenderer.hpp"+#include "../../resource/Mesh.hpp"+#include "../../resource/ResourceManager.hpp"+#include <algorithm>++namespace esengine {++/** Bounds include every usable level so selecting a different level cannot change the selection metric. */+struct LodLevels {+ const Mesh* mesh[lod::kMaxStandIns + 1]{};+ lod::LevelSet set;+ glm::vec3 localMin{0.0f};+ glm::vec3 localMax{0.0f};+ bool gap = false;+ bool disordered = false;+ bool skinMismatch = false;+};++/** False when neither a usable stand-in nor a valid cull size can replace the base mesh. */+inline bool gatherLodLevels(resource::ResourceManager& resources, const ecs::LODGroup& group,+ const Mesh& base, LodLevels& out) {+ out = LodLevels{};+ out.mesh[0] = &base;+ out.localMin = base.localMin;+ out.localMax = base.localMax;+ out.set.cull = group.cullSize;+ out.set.hysteresis = group.hysteresis;++ const resource::MeshHandle handles[lod::kMaxStandIns] = {group.lod1, group.lod2, group.lod3};+ const f32 sizes[lod::kMaxStandIns] = {group.lod1Size, group.lod2Size, group.lod3Size};+ for (u8 i = 0; i < lod::kMaxStandIns; ++i) {+ const Mesh* standIn = handles[i].isValid() ? resources.getMesh(handles[i]) : nullptr;+ if (!standIn || !standIn->isDrawable()) {+ // A missing level ends the reachable prefix, even if later slots are populated.+ for (u8 j = static_cast<u8>(i + 1); j < lod::kMaxStandIns; ++j) {+ if (handles[j].isValid()) out.gap = true;+ }+ break;+ }+ if (base.isSkinned() && standIn->inverseBind.size() != base.inverseBind.size()) {+ out.skinMismatch = true;+ break;+ }+ if (i > 0 && sizes[i] >= sizes[i - 1]) out.disordered = true;+ out.mesh[i + 1] = standIn;+ out.set.takeOver[i] = sizes[i];+ out.set.count = static_cast<u8>(i + 1);+ out.localMin = glm::min(out.localMin, standIn->localMin);+ out.localMax = glm::max(out.localMax, standIn->localMax);+ }+ // A cull size alone cannot validate a group whose first stand-in has an incompatible skeleton.+ return out.set.count > 0 || (out.set.cull > 0.0f && !out.skinMismatch);+}++/** A placement's coarse mesh shares the base draw layout; an incompatible mesh cannot affect its bounds. */+inline const Mesh* placementCoarseMesh(resource::ResourceManager& resources, const Mesh& base,+ const ecs::MeshInstances& placements) {+ const Mesh* coarse = placements.lod1Mesh.isValid() ? resources.getMesh(placements.lod1Mesh) : nullptr;+ return coarse && coarse->isDrawable() && coarse->hasNormals == base.hasNormals+ && coarse->hasTangents == base.hasTangents && coarse->hasLightmapUV == base.hasLightmapUV ? coarse : nullptr;+}++/** Displacement is local to the geometry and must be included before any placement or parent transform. */+inline void meshLocalBounds(const Mesh& base, const Mesh* coarse, f32 displacement,+ glm::vec3& lo, glm::vec3& hi) {+ const glm::vec3 padding(std::max(displacement, 0.0f));+ lo = (coarse ? glm::min(base.localMin, coarse->localMin) : base.localMin) - padding;+ hi = (coarse ? glm::max(base.localMax, coarse->localMax) : base.localMax) + padding;+}++} // namespace esenginediff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 45fef0350..0f1299861 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1,5 +1,9 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file RenderFrame.cpp+ * @brief Assemble and submit shared scene views, lighting and shadow passes.+ */#include "./RenderFrame.hpp"#ifdef ES_ENABLE_GPU_PARTICLES#include "./GpuParticles.hpp"@@ -9,6 +13,8 @@#include "../store/LightStore.hpp"#include "../draw/BatchBuilder.hpp"#include "../draw/ImmediateDraw.hpp"+#include "../draw/MeshGeometry.hpp"+#include "../draw/PlacementBounds.hpp"#include "../../ecs/components/Transform.hpp"#include "../../ecs/components/Light.hpp"#include "../../ecs/components/Occluder.hpp"@@ -1934,48 +1940,54 @@ bool RenderFrame::collectEnvironment(const ecs::Light& light, const glm::vec3& sreturn true;}-/// The world box every GPU-resident mesh occupies, or false when none does: what a shadow map-/// covers, and what a face is tested against before it gathers. MeshPlugin culls by the same-/// boxes, so a frustum missing this misses all. @p castersOnly leaves out what casts nothing.-bool RenderFrame::meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax, bool castersOnly) {- auto meshes = registry.activeView<ecs::Transform, ecs::MeshRenderer>();- bool any = false;- for (auto entity : meshes) {- const auto& mesh = meshes.get<ecs::MeshRenderer>(entity);- if (!mesh.enabled || !mesh.mesh.isValid() || (castersOnly && !mesh.castShadows)) continue;- const Mesh* resident = resource_manager_.getMesh(mesh.mesh);- if (!resident) continue;- auto& transform = meshes.get<ecs::Transform>(entity);- transform.ensureDecomposed();- glm::vec3 centre(0.0f), half(0.0f);- orientedWorldAabb(rebased(transform.worldPosition), transform.worldRotation, transform.worldScale,- resident->localMin, resident->localMax, centre, half);- outMin = any ? glm::min(outMin, centre - half) : centre - half;- outMax = any ? glm::max(outMax, centre + half) : centre + half;- any = true;- }- return any;-}--bool RenderFrame::hairWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax) {+RenderFrame::ShadowBounds RenderFrame::gatherShadowBounds(ecs::Registry& registry, bool includeHair) {auto meshes = registry.activeView<ecs::Transform, ecs::MeshRenderer>();- bool any = false;+ ShadowBounds bounds;for (auto entity : meshes) {const auto& mesh = meshes.get<ecs::MeshRenderer>(entity);- if (!mesh.enabled || !mesh.mesh.isValid() || mesh.material == 0) continue;- if (context_.materials().hairShadowDensity(mesh.material) <= 0.0f) continue;+ if (!mesh.enabled || !mesh.mesh.isValid()) continue;const Mesh* resident = resource_manager_.getMesh(mesh.mesh);if (!resident) continue;+ const auto* placements = registry.tryGet<ecs::MeshInstances>(entity);+ if (placements && placements->transforms.empty()) continue;+ const auto& materials = context_.materials();+ const f32 bend = materials.vertexBounds(mesh.material);+ const bool hair = includeHair && materials.hairShadowDensity(mesh.material) > 0.0f;+ glm::vec3 lo, hi;+ meshLocalBounds(*resident, placements ? placementCoarseMesh(resource_manager_, *resident, *placements) : nullptr, bend, lo, hi);+ if (!placements) {+ const auto* group = registry.tryGet<ecs::LODGroup>(entity);+ LodLevels levels;+ if (group && group->enabled && gatherLodLevels(resource_manager_, *group, *resident, levels)) {+ lo = levels.localMin - glm::vec3(bend);+ hi = levels.localMax + glm::vec3(bend);+ }+ }auto& transform = meshes.get<ecs::Transform>(entity);transform.ensureDecomposed();- glm::vec3 centre(0.0f), half(0.0f);- orientedWorldAabb(rebased(transform.worldPosition), transform.worldRotation, transform.worldScale,- resident->localMin, resident->localMax, centre, half);- outMin = any ? glm::min(outMin, centre - half) : centre - half;- outMax = any ? glm::max(outMax, centre + half) : centre + half;- any = true;+ const glm::vec3 position = rebased(transform.worldPosition);+ const auto include = [&](const glm::vec3& centre, const glm::vec3& half) {+ bounds.all.include(centre, half);+ if (mesh.castShadows) bounds.casters.include(centre, half);+ if (hair) bounds.hair.include(centre, half);+ };+ if (placements) {+ const glm::mat3 linear(glm::mat4_cast(transform.worldRotation) * glm::scale(glm::mat4(1.0f), transform.worldScale));+ const glm::vec3 localCentre = (lo + hi) * 0.5f, localHalf = (hi - lo) * 0.5f;+ for (usize i = 0; i + 16 <= placements->transforms.size(); i += 16) {+ const f32* r = placements->transforms.data() + i;+ const glm::vec3 origin = position + linear * glm::vec3(r[3], r[7], r[11]);+ glm::vec3 centre, half;+ placement_bounds::transformedBox(linear, r, origin, localCentre, localHalf, centre, half);+ include(centre, half);+ }+ } else {+ glm::vec3 centre, half;+ orientedWorldAabb(position, transform.worldRotation, transform.worldScale, lo, hi, centre, half);+ include(centre, half);+ }}- return any;+ return bounds;}/// The camera frustum's eight world corners, near plane first (GL clip z in [-1,1],@@ -2106,17 +2118,21 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {glm::vec3 corners[8];frustumCorners(invVP, corners);- glm::vec3 boundsMin(0.0f), boundsMax(0.0f);- const bool haveBounds = meshWorldBounds(registry, boundsMin, boundsMax);+ const ShadowBounds sceneBounds = gatherShadowBounds(registry, perspective);+ const auto& boundsMin = sceneBounds.all.min;+ const auto& boundsMax = sceneBounds.all.max;+ const bool haveBounds = sceneBounds.all.valid;// A map of a fixed size goes where the shadows come from. Centred on everything, a backdrop far behind a character takes it away from her: a large// receiver says nothing of where a shadow can start.- glm::vec3 castersMin(0.0f), castersMax(0.0f);- const bool haveCasters = meshWorldBounds(registry, castersMin, castersMax, true);+ const auto& castersMin = sceneBounds.casters.min;+ const auto& castersMax = sceneBounds.casters.max;+ const bool haveCasters = sceneBounds.casters.valid;// Hair is layers of cards a few millimetres apart, which a cascade spread over the view cannot tell apart: its texel is as wide as the gap.// So a perspective sun with cascades of its own also gets one fitted to the hair alone, first in its list (the nearest tile covering a// fragment wins), and everything that falls inside it, the face under a fringe included, is shadowed at that resolution.- glm::vec3 hairMin(0.0f), hairMax(0.0f);- const bool haveHair = perspective && hairWorldBounds(registry, hairMin, hairMax);+ const auto& hairMin = sceneBounds.hair.min;+ const auto& hairMax = sceneBounds.hair.max;+ const bool haveHair = sceneBounds.hair.valid;f32 nearDist = 0.0f, farDist = 1.0f;if (perspective) {diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex f84e2f5e3..51b398e76 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -1,5 +1,9 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file RenderFrame.hpp+ * @brief Frame resources and the shared scene rendering contract.+ */#pragma once#include "../../core/Types.hpp"@@ -875,12 +879,18 @@ private:/// to give back.void releaseFrameTargets();- /// The world box the resident meshes occupy — what a shadow map must cover.- /// False when nothing 3D is in the scene.- bool meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax, bool castersOnly = false);- /// The box the meshes drawn with a hair-shadow material occupy (MaterialStore::hairShadowDensity above zero), or false when there are none:- /// what the sun's focus cascade is fitted to.- bool hairWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax);+ struct MeshBounds {+ glm::vec3 min{0.0f}, max{0.0f};+ bool valid = false;+ void include(const glm::vec3& centre, const glm::vec3& half) {+ min = valid ? glm::min(min, centre - half) : centre - half;+ max = valid ? glm::max(max, centre + half) : centre + half;+ valid = true;+ }+ };+ struct ShadowBounds { MeshBounds all, casters, hair; };+ /// One traversal supplies receiver coverage, caster depth and the hair focus cascade from the geometry actually drawn.+ ShadowBounds gatherShadowBounds(ecs::Registry& registry, bool includeHair);/// Opens the frame's own target with @p clear's load-op, for begin() to bind it/// eagerly. Every other pass of the frame is the graph's to open.void openPass(const PassClear& clear, RenderTargetManager::Handle target);diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex 0c86df618..fa18fa934 100644--- a/src/esengine/renderer/plugins/MeshPlugin.cpp+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp@@ -1,5 +1,9 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file MeshPlugin.cpp+ * @brief Collect mesh geometry for scene, shadow, depth and motion passes.+ */#include "MeshPlugin.hpp"#include "../draw/BatchBuilder.hpp"#include "../store/MaterialStore.hpp"@@ -16,6 +20,7 @@#include "../draw/BillboardFacing.hpp"#include "../draw/ImpostorFrames.hpp"#include "../draw/PlacementBounds.hpp"+#include "../draw/MeshGeometry.hpp"#include "../draw/BatchBuilder.hpp"#include "../../ecs/components/Impostor.hpp"#include "../../resource/Mesh.hpp"@@ -176,70 +181,6 @@ bool morphShapes(ecs::Registry& registry, Entity entity, const Mesh& mesh,return true;}-/**- * @brief The levels a group can actually be drawn at, in the order they take over.- *- * @details Entry 0 is the renderer's own mesh: a group says what may STAND IN for- * it. `localMin/Max` are the UNION over every entry, so what is measured- * does not change with what is drawn — bounds read off the current level- * feed back into the choice that picked it and oscillate.- */-struct LodLevels {- const Mesh* mesh[lod::kMaxStandIns + 1]{};- lod::LevelSet set;- glm::vec3 localMin{0.0f};- glm::vec3 localMax{0.0f};- /// A slot filled after an empty one, which nothing will ever select.- bool gap = false;- /// Thresholds that do not descend, or a stand-in the base's skeleton cannot pose.- bool disordered = false;- bool skinMismatch = false;-};--/**- * @brief Reads a group into the levels it can be drawn at. False when it declares- * neither a usable stand-in nor a cull size, which leaves the renderer's own- * mesh the whole answer. A group with only a cull size is a real one: the- * mesh itself to a distance, then nothing (a tuft of grass has no cheaper- * version, and still is not worth drawing past sixty metres).- */-bool gatherLodLevels(resource::ResourceManager& resources, const ecs::LODGroup& group,- const Mesh& base, LodLevels& out) {- out = LodLevels{};- out.mesh[0] = &base;- out.localMin = base.localMin;- out.localMax = base.localMax;- out.set.cull = group.cullSize;- out.set.hysteresis = group.hysteresis;-- const resource::MeshHandle handles[lod::kMaxStandIns] = {group.lod1, group.lod2, group.lod3};- const f32 sizes[lod::kMaxStandIns] = {group.lod1Size, group.lod2Size, group.lod3Size};- for (u8 i = 0; i < lod::kMaxStandIns; ++i) {- const Mesh* standIn = handles[i].isValid() ? resources.getMesh(handles[i]) : nullptr;- if (!standIn || !standIn->isDrawable()) {- // Ordered slots: a level nothing hands over TO is a level nothing- // reaches, so the run ends here and a later one is an authoring gap.- for (u8 j = static_cast<u8>(i + 1); j < lod::kMaxStandIns; ++j) {- if (handles[j].isValid()) out.gap = true;- }- break;- }- if (base.isSkinned() && standIn->inverseBind.size() != base.inverseBind.size()) {- out.skinMismatch = true;- break;- }- if (i > 0 && sizes[i] >= sizes[i - 1]) out.disordered = true;- out.mesh[i + 1] = standIn;- out.set.takeOver[i] = sizes[i];- out.set.count = static_cast<u8>(i + 1);- out.localMin = glm::min(out.localMin, standIn->localMin);- out.localMax = glm::max(out.localMax, standIn->localMax);- }- // A skin whose stand-in the skeleton cannot pose is refused whole: a cull size alone is not a reason to keep a group that was authored against- // levels it cannot have.- return out.set.count > 0 || (out.set.cull > 0.0f && !out.skinMismatch);-}-/** @brief Says once what a group declares that nothing will ever use. */void reportLodAuthoring(const LodLevels& levels, bool& warned) {if (warned || !(levels.gap || levels.disordered || levels.skinMismatch)) return;@@ -824,19 +765,15 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {const f32 bend = material ? ctx.materials->vertexBounds(mesh.material) : 0.0f;const bool depthTested = mesh.opaque || (material && material->depthTest);- const Mesh* placementCoarse = placements && placements->lod1Mesh.isValid()- ? ctx.resources.getMesh(placements->lod1Mesh) : nullptr;- if (placementCoarse && (!placementCoarse->isDrawable() || placementCoarse->hasNormals != resident->hasNormals- || placementCoarse->hasTangents != resident->hasTangents- || placementCoarse->hasLightmapUV != resident->hasLightmapUV)) placementCoarse = nullptr;+ const Mesh* placementCoarse = placements ? placementCoarseMesh(ctx.resources, *resident, *placements) : nullptr;f32 placementRadius = 0.0f;glm::vec3 placementCentre(0.0f), placementHalf(0.0f);if (placements) {- const glm::vec3 lo = placementCoarse ? glm::min(resident->localMin, placementCoarse->localMin) : resident->localMin;- const glm::vec3 hi = placementCoarse ? glm::max(resident->localMax, placementCoarse->localMax) : resident->localMax;- placementRadius = placement_bounds::radius(lo, hi, bend);+ glm::vec3 lo, hi;+ meshLocalBounds(*resident, placementCoarse, bend, lo, hi);+ placementRadius = placement_bounds::radius(lo, hi, 0.0f);placementCentre = (lo + hi) * 0.5f;- placementHalf = (hi - lo) * 0.5f + glm::vec3(bend);+ placementHalf = (hi - lo) * 0.5f;}// Placements can rotate or shear independently. One origin-centred sphere includes both LODs and local deformation.const glm::vec3 reach(placements ? placementRadius * placements->maxScale : 0.0f);diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex a00532233..98f421b22 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -56,6 +56,39 @@ export function sceneWatchdogMs(backend, host) {* verbatim — an empty one is the default sprite scene.*/export const SCENES = [+ ...[+ { id: 'mesh-shadow-placements', scene: 'mesh-shadow', shadowX: 0.708 },+ { id: 'mesh-shadow-placements-perspective', scene: 'mesh-shadow-perspective', shadowX: 0.86 },+ ].map(test => ({+ id: test.id, tier: 'pr', webgpu: true,+ env: {+ ESTELLA_VERIFY_SCENE: `/scenes/${test.scene}.esscene`,+ ESTELLA_VERIFY_W: '256', ESTELLA_VERIFY_H: '256', ESTELLA_VERIFY_STEPS: '3',+ ESTELLA_VERIFY_PLACEMENTS: JSON.stringify([+ { entity: 1, transforms: [600, 0, 0, 0, 0, 600, 0, 0, 0, 0, 1, -200, 1, 1, 1, 1] },+ { entity: 2, transforms: [150, 0, 0, 0, 0, 150, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1] },+ ]),+ ESTELLA_VERIFY_SET_FIELD: JSON.stringify([1, 2].flatMap(entity => [+ { entity, component: 'Transform', key: 'position', value: { x: 0, y: 0, z: 0 } },+ { entity, component: 'Transform', key: 'scale', value: { x: 1, y: 1, z: 1 } },+ ])),+ ESTELLA_VERIFY_EXPECT: JSON.stringify([+ { x: test.shadowX, y: 0.5, rgb: [0, 0, 0], tol: 20 },+ { x: 0.1, y: 0.5, rgb: [228, 228, 228], tol: 20 },+ ]),+ },+ })),+ {+ id: 'shadow-vertex-displacement', tier: 'pr', webgpu: true,+ env: {+ ESTELLA_VERIFY_SCENE: '/scenes/placement-shadow-bend.esscene',+ ESTELLA_VERIFY_W: '256', ESTELLA_VERIFY_H: '256', ESTELLA_VERIFY_STEPS: '3',+ ESTELLA_VERIFY_EXPECT: JSON.stringify([+ { x: 0.5, y: 0.5, rgb: [0, 0, 0], tol: 20 },+ { x: 0.1, y: 0.5, rgb: [255, 255, 255], tol: 20 },+ ]),+ },+ },...[{ id: 'placements-bent', entity: 2, projection: 1, records: [1, 0, 0, -300, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1], x: 0.5, y: 0.5, coarse: 0 },{ id: 'placements-bent-scaled', entity: 2, projection: 1, records: [3, 0, 0, -900, 0, 3, 0, 0, 0, 0, 3, 0, 1, 1, 1, 1], x: 0.5, y: 0.5, coarse: 0 },diff --git a/tools/tests/placement-shadows.e2e.mjs b/tools/tests/placement-shadows.e2e.mjsnew file mode 100644index 000000000..57d0f69c2--- /dev/null+++ b/tools/tests/placement-shadows.e2e.mjs@@ -0,0 +1,104 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file placement-shadows.e2e.mjs+ * @brief Compare shadow coverage before and after native mesh instancing.+ */+import { chromium } from 'playwright';+import { readFile, writeFile, mkdir } from 'node:fs/promises';+import { createRequire } from 'node:module';+import { fileURLToPath } from 'node:url';+import path from 'node:path';+import assert from 'node:assert/strict';+import { serveHost } from '../lib/staticServer.mjs';+import { requireCurrentEngine } from '../lib/engineBuild.mjs';++const { PNG } = createRequire(new URL('../../pipeline/package.json', import.meta.url))('pngjs');+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');+const host = path.join(root, 'build/render-host');+const out = path.join(root, 'output/placement-shadows');+requireCurrentEngine(root, path.join(host, 'wasm'));+await mkdir(out, { recursive: true });+const server = await serveHost(host);+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', checks: [] };+try {+ for (const backend of process.argv.includes('--webgl-only') ? ['webgl2'] : ['webgl2', 'webgpu']) {+ const page = await browser.newPage({ viewport: { width: 256, height: 256 } });+ const errors = [];+ page.on('pageerror', error => errors.push(String(error)));+ page.on('console', event => { if (event.type() === 'error') errors.push(event.text()); });+ await page.route('**/favicon.ico', route => route.fulfill({ status: 204 }));+ for (const scene of ['mesh-shadow', 'mesh-shadow-perspective', 'mesh-shadow-cascade', 'mesh-shadow-caster-behind',+ 'mesh-shadow-tilt-sun', 'point-shadow-pair', 'spot-shadow', 'placement-shadow-bend']) {+ // Scene loading appends entities, so each independent fixture gets a fresh world.+ await page.goto(`http://127.0.0.1:${server.address().port}/?w=256&h=256&backend=${backend}`);+ await page.evaluate(async () => { await window.__estellaHeadless.ready; });+ const document = JSON.parse(await readFile(path.join(root, 'fixtures/scenes', `${scene}.esscene`), 'utf8'));+ const meshes = document.entities.filter(entity => entity.components.some(c => c.type === 'MeshRenderer'));+ assert.ok(meshes.every(entity => entity.parent == null), 'The fixture conversion requires unparented meshes');+ const loaded = await page.evaluate(scene => window.__estellaHeadless.api.loadScene(`/scenes/${scene}.esscene`), scene);+ assert.deepEqual(loaded.missing, []);+ const capture = async suffix => {+ const raw = await page.evaluate(async () => {+ const { api } = window.__estellaHeadless;+ await api.step(2);+ if (!await api.waitForShaders()) throw new Error('Shader compilation did not finish');+ await api.step(2);+ const image = await api.captureViewportPixels();+ return { width: image.width, height: image.height, rgba: Array.from(image.rgba) };+ });+ const image = new PNG({ width: raw.width, height: raw.height });+ const bytes = Buffer.from(raw.rgba), stride = raw.width * 4;+ for (let y = 0; y < raw.height; y++) bytes.copy(image.data, y * stride, (raw.height - y - 1) * stride, (raw.height - y) * stride);+ await writeFile(path.join(out, `${backend}-${scene}-${suffix}.png`), PNG.sync.write(image));+ return image.data;+ };+ const reference = await capture('individual');+ const shadowPresent = scene === 'placement-shadow-bend' ? reference[(128 * 256 + 128) * 4] < 20 : undefined;+ await page.evaluate(async meshes => {+ const { api } = window.__estellaHeadless;+ for (const entity of meshes) {+ const transform = entity.components.find(c => c.type === 'Transform')?.data ?? {};+ const p = transform.position ?? { x: 0, y: 0, z: 0 };+ const s = transform.scale ?? { x: 1, y: 1, z: 1 };+ const q = transform.rotation ?? { x: 0, y: 0, z: 0, w: 1 };+ const { x, y, z, w } = q;+ api.setMeshPlacements(entity.id, [+ (1 - 2 * (y * y + z * z)) * s.x, 2 * (x * y - w * z) * s.y, 2 * (x * z + w * y) * s.z, p.x,+ 2 * (x * y + w * z) * s.x, (1 - 2 * (x * x + z * z)) * s.y, 2 * (y * z - w * x) * s.z, p.y,+ 2 * (x * z - w * y) * s.x, 2 * (y * z + w * x) * s.y, (1 - 2 * (x * x + y * y)) * s.z, p.z,+ 1, 1, 1, 1,+ ]);+ await api.setField(entity.id, 'Transform', 'position', '', { x: 0, y: 0, z: 0 });+ await api.setField(entity.id, 'Transform', 'rotation', '', { x: 0, y: 0, z: 0, w: 1 });+ await api.setField(entity.id, 'Transform', 'scale', '', { x: 1, y: 1, z: 1 });+ }+ }, meshes);+ const instances = await capture('instances');+ let changed = 0, maxChannel = 0, litPixels = 0;+ for (let i = 0; i < reference.length; i += 4) {+ const delta = Math.max(...[0, 1, 2].map(c => Math.abs(reference[i + c] - instances[i + c])));+ maxChannel = Math.max(maxChannel, delta);+ if (delta > 2) changed++;+ if (reference[i] > 100 && reference[i + 1] > 100 && reference[i + 2] > 100) litPixels++;+ }+ assert.ok(litPixels > 1000, 'The reference must contain a visible lit receiver');+ report.checks.push({ backend, scene, changed, maxChannel, shadowPresent });+ console.log(JSON.stringify(report.checks.at(-1)));+ }+ assert.deepEqual(errors, []);+ await page.close();+ }+ assert.ok(report.checks.every(row => row.changed === 0 && row.shadowPresent !== false),+ 'Instancing must preserve shadow coverage, including deformed casters behind the camera');+ report.status = 'checks-passed';+} 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));+}