Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

perf(ui): skip fully transparent visual geometry

yhh45a22c0b1992
diff --git a/CHANGELOG.md b/CHANGELOG.md
index db646ee35..64f39beab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,10 @@ published separately; it ships inside the editor.
- **Playable exports report static checks and pending acceptance.** Export results and the editor package dialog show actual HTML/delivery hashes, network size limits, literal resource references and orientation config checks. Mandatory network SDK scripts are allowed explicitly. CTA, lifecycle, dynamic requests and device/network acceptance remain pending runtime evidence, including when static checks pass.
+### Fixed
+
+- **Fully transparent UI visuals skip geometry uploads.** Default-material solid, image, nine-slice, tiled and filled visuals stop generating vertices and indices when their own or inherited alpha is zero, and resume when visible. Stencil mask geometry and custom-material draws remain available for clipping and shader-defined output.
+
## [0.81.0] - 2026-10-14
### Added
diff --git a/src/esengine/renderer/draw/ClipState.hpp b/src/esengine/renderer/draw/ClipState.hpp
index 3c1c74e79..f7f41a26a 100644
--- a/src/esengine/renderer/draw/ClipState.hpp
+++ b/src/esengine/renderer/draw/ClipState.hpp
@@ -31,6 +31,11 @@ public:
e.stencil_ref = refValue;
}
+ bool isStencilMask(Entity entity) const {
+ const auto it = entries_.find(entity.id());
+ return it != entries_.end() && (it->second.flags & CMD_STATE_STENCIL_WRITE) != 0;
+ }
+
void setStencilTest(u32 entity, i32 refValue) {
auto& e = entries_[entity];
e.flags |= CMD_STATE_STENCIL_TEST;
diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cpp
index aa10e354b..c573c27eb 100644
--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp
+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp
@@ -60,6 +60,13 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
// Geometry from the UINode (CSS box) — always pivot-centered.
const auto* node = registry.tryGet<ecs::UINode>(entity);
if (!node || node->hidden_in_tree_) continue;
+ const auto* mask = registry.tryGet<ecs::UIMask>(entity);
+ const bool writesStencil = mask && mask->enabled && mask->mode == ecs::MaskMode::Stencil;
+ // Stencil draws still define clipping at zero alpha; custom materials
+ // may produce visible output independently of the vertex alpha.
+ if (renderer.material == 0 && !writesStencil
+ && renderer.color.a * node->alpha_in_tree_ == 0.0f
+ && !clips.isStencilMask(entity)) continue;
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;
@@ -236,8 +243,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
// the mask pass runs this same draw with color writes off, so it needs
// the variant that discards transparent fragments — otherwise the whole
// quad writes stencil and a circular mask clips a rectangle.
- if (const auto* mask = registry.tryGet<ecs::UIMask>(entity);
- mask && mask->enabled && mask->mode == ecs::MaskMode::Stencil && mask->alphaCutoff > 0.0f) {
+ if (writesStencil && mask->alphaCutoff > 0.0f) {
key.shaderId = ctx.frame->batchProgram({"ALPHA_CLIP"});
}
diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cpp
index c4df66c79..1d182afb3 100644
--- a/tests/renderer/test_batch_builder.cpp
+++ b/tests/renderer/test_batch_builder.cpp
@@ -17,6 +17,10 @@
#include "esengine/renderer/frame/RenderFrame.hpp"
#include "esengine/renderer/frame/RenderContext.hpp"
#include "esengine/resource/ResourceManager.hpp"
+#include "esengine/renderer/plugins/UIElementPlugin.hpp"
+#include "esengine/ecs/components/UINode.hpp"
+#include "esengine/ecs/components/UIVisual.hpp"
+#include "esengine/ecs/components/UIMask.hpp"
#include <functional>
#include <utility>
@@ -270,6 +274,79 @@ TEST_CASE("camera mask: hidden text and skeletal submissions upload no geometry"
CHECK(frame.stats().triangles == 4);
}
+TEST_CASE("UI visuals: zero alpha skips geometry and a restored fade draws again") {
+ for (auto mode : {ecs::UIVisualType::SolidColor, ecs::UIVisualType::Image,
+ ecs::UIVisualType::NineSlice, ecs::UIVisualType::Tiled,
+ ecs::UIVisualType::Filled}) {
+ for (bool inherited : {false, true}) {
+ Harness h;
+ RenderContext context(h.device);
+ resource::ResourceManager resources;
+ ecs::Registry registry;
+ const auto entity = registry.create();
+ registry.emplace<ecs::Transform>(entity);
+ auto& node = registry.emplace<ecs::UINode>(entity);
+ node.computed_size_ = {20, 20};
+ auto& visual = registry.emplace<ecs::UIVisual>(entity);
+ visual.visualType = mode;
+ visual.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;
+ RenderFrameContext frameContext{context, resources};
+ frameContext.purpose = RenderPurpose::ScreenOverlay;
+ std::unordered_set<u32> screen{entity.id()};
+ Frustum frustum;
+ RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
+ collect.screen_ui = &screen;
+ UIElementPlugin plugin;
+ plugin.init(frameContext);
+ plugin.collect(collect);
+ CHECK(h.list.commandCount() == 0);
+ CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == 0);
+ CHECK(h.pool.indicesUsed(LayoutId::Batch) == 0);
+ node.alpha_in_tree_ = .5f;
+ visual.color.a = 1;
+ plugin.collect(collect);
+ CHECK(h.list.commandCount() > 0);
+ CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) > 0);
+ CHECK(h.pool.indicesUsed(LayoutId::Batch) > 0);
+ }
+ }
+}
+
+TEST_CASE("UI visuals: transparent stencil masks and custom materials retain geometry") {
+ for (int kind : {0, 1, 2}) {
+ Harness h;
+ RenderContext context(h.device);
+ resource::ResourceManager resources;
+ ecs::Registry registry;
+ const auto entity = registry.create();
+ registry.emplace<ecs::Transform>(entity);
+ auto& node = registry.emplace<ecs::UINode>(entity);
+ node.computed_size_ = {20, 20};
+ node.alpha_in_tree_ = 0;
+ auto& visual = registry.emplace<ecs::UIVisual>(entity);
+ visual.visualType = ecs::UIVisualType::SolidColor;
+ if (kind == 0) visual.material = 42;
+ if (kind == 1) registry.emplace<ecs::UIMask>(entity).mode = ecs::MaskMode::Stencil;
+ if (kind == 2) h.clips.setStencilMask(entity.id(), 1);
+ RenderFrameContext frameContext{context, resources};
+ frameContext.purpose = RenderPurpose::ScreenOverlay;
+ std::unordered_set<u32> screen{entity.id()};
+ Frustum frustum;
+ RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
+ collect.screen_ui = &screen;
+ UIElementPlugin plugin;
+ plugin.init(frameContext);
+ plugin.collect(collect);
+ CHECK(h.list.commandCount() == 1);
+ CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == 4 * sizeof(BatchVertex));
+ CHECK(h.pool.indicesUsed(LayoutId::Batch) == 6);
+ }
+}
+
TEST_CASE("camera passes: empty text and skeletal clips recover on the next camera") {
MockGfxDevice device;
RenderContext context(device);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 6b90860e0..cbdeae8f4 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -32,6 +32,9 @@ export const NOTED = {
{ note: 'Playable exports report static checks and pending acceptance.' },
'feat(editor): show playable export checks in package results':
{ note: 'Playable exports report static checks and pending acceptance.' },
+
+ 'perf(ui): skip fully transparent visual geometry':
+ { note: 'Fully transparent UI visuals skip geometry uploads.' },
'fix(playable): pass store destinations through the CTA bridge':
{ note: 'MRAID store clicks carry their destination.' },
'fix(playable): observe MRAID readiness and viewability':