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(ui): bound mask traversal and skip empty viewport geometry
yhh56f4e68ccc8a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 72dc1207e..bb5ede47a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -27,6 +27,8 @@ published separately; it ships inside the editor.- **Playable preview records identify the delivered archive.** Full export reports verify the adjacent ZIP hash before previewing, catching config changes even when HTML stays identical. Downloaded logs retain HTML/delivery hashes and explicitly disclose omitted events; HTML-only previews remain labeled accordingly.+- **UI masks handle deep hierarchies and empty viewports.** Scissor and stencil propagation use reusable iterative work stacks instead of recursive calls, preserving nested and sibling stencil references. Zero-area rotated boxes remain empty clips; empty stencil subtrees and zero-area visuals skip geometry uploads and recover when their dimensions return.+- **World transforms preserve mirrored axes.** Quaternion decomposition retains signed scale instead of converting reflected bases into invalid rotations. Planar transforms keep a Z rotation, including collapsed axes; mirrored UI pointer bounds and flat render bounds follow their displayed geometry.- **Playable checks verify mandatory SDK scripts and placement.** The report detects missing Google/TikTok/Pangle scripts, incorrect head/body placement and delayed TikTok/Pangle loading before game code. Script text and JSON metadata do not count as SDK tags. The editor shows the SDK finding separately, while interaction and availability remain pending runtime evidence.diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex d9fd39975..eebe6a79c 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -909,6 +909,8 @@ private:std::vector<Entity> mask_scissor_scratch_;std::vector<Entity> mask_stencil_scratch_;std::vector<Entity> mask_root_scratch_;+ std::vector<std::pair<Entity, ScissorRect>> mask_scissor_walk_scratch_;+ std::vector<std::pair<Entity, i32>> mask_stencil_walk_scratch_;std::unordered_set<u32> mask_set_scratch_;std::unordered_set<u32> stencil_set_scratch_;};diff --git a/src/esengine/renderer/frame/RenderFrameMask.cpp b/src/esengine/renderer/frame/RenderFrameMask.cppindex 94543e352..a0c1bcf1d 100644--- a/src/esengine/renderer/frame/RenderFrameMask.cpp+++ b/src/esengine/renderer/frame/RenderFrameMask.cpp@@ -18,9 +18,7 @@ namespace esengine {namespace {-struct ScreenRect {- i32 x = 0, y = 0, w = 0, h = 0;-};+using ScreenRect = ScissorRect;ScreenRect intersectRects(const ScreenRect& a, const ScreenRect& b) {i32 x1 = std::max(a.x, b.x);@@ -49,6 +47,7 @@ ScreenRect computeMaskScreenRect(return {0, 0, 0, 0};}const auto& node = registry.get<ecs::UINode>(entity);+ if (node.computed_size_.x <= 0.0f || node.computed_size_.y <= 0.0f) return {0, 0, 0, 0};auto& transform = registry.get<ecs::Transform>(entity);// The world TRS below is decomposed on demand, so a mask whose transform no// other pass has read this frame would be clipped to where it used to be.@@ -56,6 +55,7 @@ ScreenRect computeMaskScreenRect(f32 worldW = node.computed_size_.x * transform.worldScale.x;f32 worldH = node.computed_size_.y * transform.worldScale.y;+ if (worldW == 0.0f || worldH == 0.0f) return {0, 0, 0, 0};f32 cx = transform.worldPosition.x;f32 cy = transform.worldPosition.y;f32 px = 0.5f; // UINode box is pivot-centered@@ -127,67 +127,94 @@ bool hasAncestorStencilMask(ecs::Registry& registry, Entity entity,void applyScissorToDescendants(ecs::Registry& registry, RenderFrame& frame, Entity entity,const ScreenRect& clipRect, const std::unordered_set<u32>& maskSet,- const glm::mat4& vp, i32 vpX, i32 vpY, i32 vpW, i32 vpH+ const glm::mat4& vp, i32 vpX, i32 vpY, i32 vpW, i32 vpH,+ std::vector<std::pair<Entity, ScissorRect>>& work) {- if (!registry.has<ecs::Children>(entity)) return;- const auto& children = registry.get<ecs::Children>(entity);- for (auto child : children.entities) {- ScreenRect childClip = clipRect;-- if (maskSet.count(child.id())) {- const auto& childMask = registry.get<ecs::UIMask>(child);- if (childMask.mode == ecs::MaskMode::Scissor) {- ScreenRect childRect = computeMaskScreenRect(registry, child, vp, vpX, vpY, vpW, vpH);- childClip = intersectRects(clipRect, childRect);+ work.clear();+ work.emplace_back(entity, clipRect);+ usize walked = 0;+ while (!work.empty()) {+ if (++walked > registry.entityCount()) {+ ES_LOG_WARN("Scissor hierarchy repeats nodes; stopping mask traversal");+ work.clear();+ return;+ }+ const auto [owner, parentClip] = work.back();+ work.pop_back();+ if (!registry.has<ecs::Children>(owner)) continue;+ const auto& children = registry.get<ecs::Children>(owner).entities;+ for (auto it = children.rbegin(); it != children.rend(); ++it) {+ const Entity child = *it;+ if (!registry.valid(child)) continue;+ ScreenRect childClip = parentClip;+ if (maskSet.count(child.id())) {+ const auto& childMask = registry.get<ecs::UIMask>(child);+ if (childMask.mode == ecs::MaskMode::Scissor) {+ const auto childRect = computeMaskScreenRect(registry, child, vp, vpX, vpY, vpW, vpH);+ childClip = intersectRects(parentClip, childRect);+ }}+ frame.setEntityClipRect(child.id(), childClip.x, childClip.y, childClip.w, childClip.h);+ work.emplace_back(child, childClip);}-- frame.setEntityClipRect(child.id(), childClip.x, childClip.y, childClip.w, childClip.h);- applyScissorToDescendants(registry, frame, child, childClip, maskSet, vp, vpX, vpY, vpW, vpH);}}static constexpr i32 MAX_STENCIL_REF = 255;-void applyStencilDescendants(ecs::Registry& registry, RenderFrame& frame,- Entity entity, i32 refValue,- const std::unordered_set<u32>& stencilSet, i32& nextRef, bool& overflowed);+bool hasEmptyMaskBox(ecs::Registry& registry, Entity entity) {+ const auto* node = registry.tryGet<ecs::UINode>(entity);+ auto* transform = registry.tryGet<ecs::Transform>(entity);+ if (!node || !transform) return false;+ if (node->computed_size_.x <= 0.0f || node->computed_size_.y <= 0.0f) return true;+ transform->ensureDecomposed();+ return transform->worldScale.x == 0.0f || transform->worldScale.y == 0.0f;+}void applyStencilHierarchy(ecs::Registry& registry, RenderFrame& frame,Entity entity, i32 refValue,- const std::unordered_set<u32>& stencilSet, i32& nextRef, bool& overflowed) {+ const std::unordered_set<u32>& stencilSet, i32& nextRef, bool& overflowed,+ std::vector<std::pair<Entity, i32>>& work) {if (overflowed) return;- frame.setEntityStencilMask(entity.id(), refValue);-- if (!registry.has<ecs::Children>(entity)) return;- const auto& children = registry.get<ecs::Children>(entity);- for (auto child : children.entities) {- if (overflowed) return;- if (stencilSet.count(child.id())) {- if (nextRef > MAX_STENCIL_REF) { overflowed = true; return; }- applyStencilHierarchy(registry, frame, child, nextRef++, stencilSet, nextRef, overflowed);- } else {- frame.setEntityStencilTest(child.id(), refValue);- applyStencilDescendants(registry, frame, child, refValue, stencilSet, nextRef, overflowed);- }+ work.clear();+ if (hasEmptyMaskBox(registry, entity)) {+ refValue = 0;+ frame.setEntityClipRect(entity.id(), 0, 0, 0, 0);+ } else {+ frame.setEntityStencilMask(entity.id(), refValue);}-}--void applyStencilDescendants(ecs::Registry& registry, RenderFrame& frame,- Entity entity, i32 refValue,- const std::unordered_set<u32>& stencilSet, i32& nextRef, bool& overflowed) {- if (overflowed) return;- if (!registry.has<ecs::Children>(entity)) return;- const auto& children = registry.get<ecs::Children>(entity);- for (auto child : children.entities) {- if (overflowed) return;- if (stencilSet.count(child.id())) {- if (nextRef > MAX_STENCIL_REF) { overflowed = true; return; }- applyStencilHierarchy(registry, frame, child, nextRef++, stencilSet, nextRef, overflowed);+ const auto enqueueChildren = [&](Entity owner, i32 parentRef) {+ if (!registry.has<ecs::Children>(owner)) return;+ const auto& children = registry.get<ecs::Children>(owner).entities;+ for (auto it = children.rbegin(); it != children.rend(); ++it) {+ if (registry.valid(*it)) work.emplace_back(*it, parentRef);+ }+ };+ enqueueChildren(entity, refValue);+ usize walked = 0;+ while (!work.empty()) {+ if (++walked > registry.entityCount()) {+ ES_LOG_WARN("Stencil hierarchy repeats nodes; stopping mask traversal");+ work.clear();+ return;+ }+ auto [owner, currentRef] = work.back();+ work.pop_back();+ if (currentRef == 0) {+ frame.setEntityClipRect(owner.id(), 0, 0, 0, 0);+ } else if (stencilSet.count(owner.id())) {+ if (hasEmptyMaskBox(registry, owner)) {+ frame.setEntityClipRect(owner.id(), 0, 0, 0, 0);+ enqueueChildren(owner, 0);+ continue;+ }+ if (nextRef > MAX_STENCIL_REF) { overflowed = true; work.clear(); return; }+ currentRef = nextRef++;+ frame.setEntityStencilMask(owner.id(), currentRef);} else {- frame.setEntityStencilTest(child.id(), refValue);- applyStencilDescendants(registry, frame, child, refValue, stencilSet, nextRef, overflowed);+ frame.setEntityStencilTest(owner.id(), currentRef);}+ enqueueChildren(owner, currentRef);}}@@ -238,7 +265,7 @@ void RenderFrame::processMasks(ecs::Registry& registry, const glm::mat4& projectfor (auto entity : rootScissors) {ScreenRect rect = computeMaskScreenRect(registry, entity, projection, vpX, vpY, vpW, vpH);rect = intersectRects(rect, {vpX, vpY, vpW, vpH});- applyScissorToDescendants(registry, *this, entity, rect, maskSet, projection, vpX, vpY, vpW, vpH);+ applyScissorToDescendants(registry, *this, entity, rect, maskSet, projection, vpX, vpY, vpW, vpH, mask_scissor_walk_scratch_);}}@@ -260,7 +287,7 @@ void RenderFrame::processMasks(ecs::Registry& registry, const glm::mat4& projectfor (auto entity : rootStencils) {if (overflowed) break;if (nextRef > MAX_STENCIL_REF) break;- applyStencilHierarchy(registry, *this, entity, nextRef++, stencilSet, nextRef, overflowed);+ applyStencilHierarchy(registry, *this, entity, nextRef++, stencilSet, nextRef, overflowed, mask_stencil_walk_scratch_);}if (overflowed) {diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cppindex c573c27eb..b1f725cdf 100644--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp@@ -70,7 +70,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {if (clips.isEmptyScissor(entity)) { ++collect_ctx.culled; continue; }f32 w = node->computed_size_.x, h = node->computed_size_.y;f32 pivotX = 0.5f, pivotY = 0.5f;- if (w <= 0.0f && h <= 0.0f) continue;+ if (w <= 0.0f || h <= 0.0f) continue;auto& transform = uiView.get<ecs::Transform>(entity);transform.ensureDecomposed();@@ -78,6 +78,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {glm::vec3 position = transform.worldPosition;const auto& rotation = transform.worldRotation;const auto& scale = transform.worldScale;+ if (scale.x == 0.0f || scale.y == 0.0f) continue;// UI bakes the pivot into the world position here, so the quad is emitted centered.f32 dx = (0.5f - pivotX) * w * scale.x;diff --git a/src/esengine/ui/UIHitTestSystem.hpp b/src/esengine/ui/UIHitTestSystem.hppindex a091efd4e..644191373 100644--- a/src/esengine/ui/UIHitTestSystem.hpp+++ b/src/esengine/ui/UIHitTestSystem.hpp@@ -31,6 +31,7 @@ inline bool pointInOBB(f32 pivotX, f32 pivotY,f32 rotationZ, f32 rotationW) {+ if (worldW == 0.0f || worldH == 0.0f) return false;f32 angle = quaternionToAngle2D(rotationZ, rotationW);f32 sinA = std::sin(-angle);f32 cosA = std::cos(-angle);diff --git a/tests/ecs/test_ui_tree.cpp b/tests/ecs/test_ui_tree.cppindex c870f7516..a936aae27 100644--- a/tests/ecs/test_ui_tree.cpp+++ b/tests/ecs/test_ui_tree.cpp@@ -8,6 +8,8 @@ using namespace esengine;using namespace esengine::ecs;TEST_CASE("mirrored UI boxes keep their pivot and rotated pointer bounds") {+ CHECK_FALSE(pointInOBB(13, 17, 13, 17, 0, 8, .5f, .5f, 0, 1));+ CHECK_FALSE(pointInOBB(13, 17, 13, 17, 10, 0, .5f, .5f, 0, 1));for (float x : {1.0f, -1.0f}) for (float y : {1.0f, -1.0f}) {for (float angle : {0.0f, .7f}) {const auto rotation = glm::angleAxis(angle, glm::vec3(0, 0, 1));diff --git a/tests/renderer/MockGfxDevice.hpp b/tests/renderer/MockGfxDevice.hppindex f381b81a6..20b8e7d3c 100644--- a/tests/renderer/MockGfxDevice.hpp+++ b/tests/renderer/MockGfxDevice.hpp@@ -13,6 +13,7 @@namespace esengine {struct MockGfxDevice final : GfxDevice {+ std::vector<i32> stencilReferences;// Device-loss entry points a backend calls on itself. Protected on GfxDevice,// so a harness driving the state machine needs them republished here.using GfxDevice::markDeviceLost;@@ -161,7 +162,7 @@ struct MockGfxDevice final : GfxDevice {/// Answers as GL does; a test that cares sets it.bool originTopLeft = false;bool textureOriginTopLeft() const override { return originTopLeft; }- void setStencilReference(i32) override {}+ void setStencilReference(i32 ref) override { stencilReferences.push_back(ref); }void drawElements(u32 indexCount, GfxDataType, u32 byteOffset) override {++drawElementsCalls;diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cppindex 89104d7ba..cdbea135f 100644--- a/tests/renderer/test_batch_builder.cpp+++ b/tests/renderer/test_batch_builder.cpp@@ -21,6 +21,7 @@#include "esengine/ecs/components/UINode.hpp"#include "esengine/ecs/components/UIVisual.hpp"#include "esengine/ecs/components/UIMask.hpp"+#include "esengine/ecs/components/Hierarchy.hpp"#include <functional>#include <utility>@@ -278,6 +279,104 @@ TEST_CASE("camera mask: hidden text and skeletal submissions upload no geometry"CHECK(frame.stats().triangles == 4);}+TEST_CASE("UI masks: deep grouping hierarchies reach their leaf without call-stack recursion") {+ for (auto mode : {ecs::MaskMode::Scissor, ecs::MaskMode::Stencil}) {+ MockGfxDevice device;+ RenderContext context(device);+ resource::ResourceManager resources;+ ecs::Registry registry;+ RenderFrame frame(device, context, resources);+ frame.init(64, 64);+ const auto root = registry.create();+ registry.emplace<ecs::Transform>(root);+ registry.get<ecs::Transform>(root).worldRotation = glm::angleAxis(.7f, glm::vec3(0, 0, 1));+ registry.get<ecs::Transform>(root).worldScale.y = -1;+ auto& node = registry.emplace<ecs::UINode>(root);+ node.computed_size_ = {20, 20};+ registry.emplace<ecs::UIMask>(root).mode = mode;+ Entity leaf = root;+ for (u32 i = 0; i < 50000; ++i) {+ const auto child = registry.create();+ registry.emplace<ecs::Parent>(child).entity = leaf;+ registry.emplace<ecs::Children>(leaf).entities.push_back(child);+ leaf = child;+ }+ const glm::mat4 projection = glm::ortho(-32.0f, 32.0f, -32.0f, 32.0f);+ const glm::mat4 transform(1);+ const f32 text[36] = {};+ const u16 indices[] = {0, 1, 2, 2, 3, 0};+ for (bool empty : {true, false}) {+ node.computed_size_.x = empty ? 0 : 20;+ frame.beginFrame();+ frame.begin(projection);+ frame.processMasks(registry, 0, 0, 64, 64);+ frame.collectAll(registry);+ const int uploads = device.updateBufferCalls;+ frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], leaf, 0, 0, false);+ frame.flush();+ if (empty) {+ CHECK(frame.stats().text == 0);+ CHECK(device.updateBufferCalls == uploads);+ } else {+ CHECK(frame.stats().text == 1);+ CHECK(device.updateBufferCalls > uploads);+ }+ frame.end();+ frame.endFrame();+ }+ }+}++TEST_CASE("UI stencil traversal keeps nested and sibling references in authored order") {+ MockGfxDevice device;+ RenderContext context(device);+ resource::ResourceManager resources;+ ecs::Registry registry;+ RenderFrame frame(device, context, resources);+ frame.init(64, 64);+ const auto child = [&](Entity parent, bool mask) {+ const Entity entity = registry.create();+ if (parent != INVALID_ENTITY) {+ registry.emplace<ecs::Parent>(entity).entity = parent;+ if (!registry.has<ecs::Children>(parent)) registry.emplace<ecs::Children>(parent);+ registry.get<ecs::Children>(parent).entities.push_back(entity);+ }+ if (mask) registry.emplace<ecs::UIMask>(entity).mode = ecs::MaskMode::Stencil;+ return entity;+ };+ const Entity root = child(INVALID_ENTITY, true), a = child(root, false), nested = child(root, true);+ const Entity b = child(nested, false), deep = child(nested, true), c = child(deep, false);+ const Entity group = child(root, false), d = child(group, false), e = child(root, false);+ registry.emplace<ecs::Transform>(deep);+ auto& nestedBox = registry.emplace<ecs::UINode>(deep);+ nestedBox.computed_size_ = {20, 20};+ const glm::mat4 transform(1);+ const f32 text[36] = {};+ const u16 indices[] = {0, 1, 2, 2, 3, 0};+ for (u32 repeat = 0; repeat < 4; ++repeat) {+ const bool empty = repeat == 2;+ nestedBox.computed_size_.y = empty ? 0 : 20;+ device.stencilReferences.clear();+ frame.beginFrame();+ frame.begin(transform);+ frame.processMasks(registry, 0, 0, 64, 64);+ frame.collectAll(registry);+ i32 layer = 0;+ for (Entity entity : {a, b, c, d, e}) {+ frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], entity, layer++, 0, false);+ }+ frame.flush();+ frame.end();+ CHECK(frame.stats().text == (empty ? 4 : 5));+ const std::vector<i32> expected = empty ? std::vector<i32>{1, 2, 1} : std::vector<i32>{1, 2, 3, 1};+ CHECK(device.stencilReferences.size() == expected.size());+ for (u32 i = 0; i < std::min(device.stencilReferences.size(), expected.size()); ++i) {+ CHECK(device.stencilReferences[i] == expected[i]);+ }+ frame.endFrame();+ }+}+TEST_CASE("flat bounds: reflected extents enclose the same rotated box") {for (f32 x : {1.0f, -1.0f}) for (f32 y : {1.0f, -1.0f}) {for (f32 angle : {0.0f, .7f}) {@@ -372,11 +471,13 @@ TEST_CASE("nine-slice: signed transforms and UV flips preserve every cell") {}}-TEST_CASE("UI visuals: zero alpha skips geometry and a restored fade draws again") {+TEST_CASE("UI visuals: invisible and collapsed boxes skip geometry and recover") {+ enum class Hidden { OwnAlpha, InheritedAlpha, Width, Height, ScaleX, ScaleY };for (auto mode : {ecs::UIVisualType::SolidColor, ecs::UIVisualType::Image,ecs::UIVisualType::NineSlice, ecs::UIVisualType::Tiled,ecs::UIVisualType::Filled}) {- for (bool inherited : {false, true}) {+ for (auto hidden : {Hidden::OwnAlpha, Hidden::InheritedAlpha, Hidden::Width,+ Hidden::Height, Hidden::ScaleX, Hidden::ScaleY}) {Harness h;RenderContext context(h.device);resource::ResourceManager resources;@@ -390,8 +491,15 @@ TEST_CASE("UI visuals: zero alpha skips geometry and a restored fade draws againvisual.sliceBorder = {2, 2, 2, 2};visual.fillMethod = ecs::UIFillMethod::Radial360;visual.fillAmount = .5f;- if (inherited) node.alpha_in_tree_ = 0;- else visual.color.a = 0;+ auto& scale = registry.get<ecs::Transform>(entity).worldScale;+ switch (hidden) {+ case Hidden::OwnAlpha: visual.color.a = 0; break;+ case Hidden::InheritedAlpha: node.alpha_in_tree_ = 0; break;+ case Hidden::Width: node.computed_size_.x = 0; break;+ case Hidden::Height: node.computed_size_.y = 0; break;+ case Hidden::ScaleX: scale.x = 0; break;+ case Hidden::ScaleY: scale.y = 0; break;+ }RenderFrameContext frameContext{context, resources};frameContext.purpose = RenderPurpose::ScreenOverlay;std::unordered_set<u32> screen{entity.id()};@@ -406,6 +514,8 @@ TEST_CASE("UI visuals: zero alpha skips geometry and a restored fade draws againCHECK(h.pool.indicesUsed(LayoutId::Batch) == 0);node.alpha_in_tree_ = .5f;visual.color.a = 1;+ node.computed_size_ = {20, 20};+ scale = {1, 1, 1};plugin.collect(collect);CHECK(h.list.commandCount() > 0);CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) > 0);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 873c8962a..d5309316b 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -34,6 +34,9 @@ export const NOTED = {'fix(playable): bind preview records to delivery hashes':{ note: 'Playable preview records identify the delivered archive.' },++ 'fix(ui): bound mask traversal and skip empty viewport geometry':+ { note: 'UI masks handle deep hierarchies and empty viewports.' },'fix(transform): preserve reflected world transforms and UI bounds':{ note: 'World transforms preserve mirrored axes.' },