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.

fix(ui): particles and plain sprites in a Canvas paint by their place in its tree

yhh5b43e8569247
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f956041e3..0ef97741f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Particles and plain sprites in a Canvas paint by their place in its tree.** An emitter listed after a panel went under it, and one listed before a plain `Sprite` went over it. Both now follow the hierarchy like the controls round them, and the `layer` they were authored with is no longer overwritten. A `Sprite` with no `UINode` under a Canvas may change place as a result; a non-zero `layer` keeps the old order.
+
- **A trigger no longer stops a 2D character.** The mover took a sensor for a wall and for a floor.
- **A 2D character honours one-way platforms.** It was stopped from below by the mover as if they were solid.
- **A 2D character under a parent moves in the world.** Its local position was handed to the mover as a world position.
diff --git a/desktop b/desktop
index 9f96242b9..6192d1d00 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 9f96242b9777560eb48a1921b56a8c0d9745c1da
+Subproject commit 6192d1d007ef555eb5a6ddc807b5df172d9b233e
diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdx
index 20b550e78..4e1589bb0 100644
--- a/docs/astro/src/content/docs/world/particles.mdx
+++ b/docs/astro/src/content/docs/world/particles.mdx
@@ -190,7 +190,7 @@ See [Noise & turbulence](#noise--turbulence-1) below.
| Property | Type | Default | Description |
|---|---|---|---|
| `blendMode` | `BlendMode` | `Additive` | How particles composite. See [Blend modes](#blend-modes). |
-| `layer` | number | `0` | Sorting layer for draw order. |
+| `layer` | number | `0` | Sorting layer for draw order. Under a `Canvas`, `0` paints by its place in the tree; see [Particles in a UI](#particles-in-a-ui). |
| `material` | asset | none | Optional custom material/shader. |
| `simulationSpace` | `SimulationSpace` | `World` | `World` or `Local` (see [below](#simulation-space)). |
| `renderMode` | `ParticleRenderMode` | `Billboard` | `Billboard` faces the view; `Stretched` lays the quad along the particle's velocity (see [Stretched particles](#stretched-particles)). |
@@ -686,6 +686,12 @@ A kernel appends what happens to a buffer: each birth, death or collision the em
**Trails** use the same `trailEnabled`, `trailWidth`, `trailPoints` and `trailMinDistance`. Each particle's path is kept in a buffer of its own and drawn as quads along it, narrowing and fading from the head. They cost memory for every slot whether alive or not: `maxParticles` x `trailPoints` x 60 bytes, so 100,000 particles with 12 points is 72 MB. Each piece turns to face the camera that first drew it that frame, so a second camera sees them slightly edge on.
+## Particles in a UI
+
+An emitter under a `Canvas` paints by its place in the tree, like the controls round it: listed after a panel or inside it, it is over the panel; listed before, it is under it. A `Sprite` under a `Canvas` with no `UINode` does the same. A `layer` other than `0` opts out and sorts as a layer does, against the controls' 1000 and up: `layer: 5000` holds it over the whole UI.
+
+An emitter that is not under a `Canvas` belongs to the scene, and a screen `Canvas` is drawn after the scene: its particles are always under that UI, whatever their `layer`. To put an effect over a HUD, make it a child of the `Canvas`. `gpuSimulation` emitters do not draw under a screen `Canvas`.
+
## Performance & best practices
- **Budget `maxParticles`.** It's a fixed pool; size it to the worst case, not
diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdx
index f203ef470..c5e4fccc6 100644
--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx
+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx
@@ -181,7 +181,7 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `blendMode` | `BlendMode` | `Additive` | 粒子如何合成。见 [混合模式](#混合模式)。 |
-| `layer` | number | `0` | 决定绘制顺序的排序层。 |
+| `layer` | number | `0` | 决定绘制顺序的排序层。Canvas 下为 `0` 时按树中的位置绘制,见 [UI 中的粒子](#ui-中的粒子)。 |
| `material` | asset | 无 | 可选的自定义材质/着色器。 |
| `simulationSpace` | `SimulationSpace` | `World` | `World` 或 `Local`(见[下](#模拟空间))。 |
| `renderMode` | `ParticleRenderMode` | `Billboard` | `Billboard` 朝向视图;`Stretched` 让四边形沿粒子速度方向拉伸(见[拉伸粒子](#拉伸粒子))。 |
@@ -623,6 +623,12 @@ kernel 把发生的事追加到一个缓冲里:`subEmitterTrigger` 要的出
**拖尾** 用同样的 `trailEnabled`、`trailWidth`、`trailPoints` 和 `trailMinDistance`。每个粒子的路径存在单独的缓冲里,沿路径画成四边形,从头部开始逐渐变窄变淡。无论粒子是否存活,每个槽都占内存:`maxParticles` x `trailPoints` x 60 字节,10 万粒子配 12 个点就是 72 MB。每一段都朝向这一帧最先绘制的相机,所以第二个相机看到的会略微偏向侧面。
+## UI 中的粒子
+
+`Canvas` 下的发射器按它在树中的位置绘制,和周围的控件一样:排在面板后面或放在面板里面,就在面板上方;排在前面,就在面板下方。`Canvas` 下没有 `UINode` 的 `Sprite` 也一样。`layer` 不为 `0` 时不走树序,按层排序,控件的层从 1000 开始:`layer: 5000` 能让它压在整个 UI 上方。
+
+不在 `Canvas` 下的发射器属于场景,而屏幕 `Canvas` 在场景之后绘制,所以无论 `layer` 是多少,这些粒子都在该 UI 下方。要让特效盖在 HUD 上,把它放到 `Canvas` 下。`gpuSimulation` 发射器不会在屏幕 `Canvas` 下绘制。
+
## 性能与最佳实践
- **控制 `maxParticles`。** 它是固定池;按最坏情况定大小,别更高。多个小发射器比一个巨大的
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 767bd09ad..884b9eed7 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -2,6 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#include <cmath>
+#include "UIBindings.hpp"
#include "RendererBindings.hpp"
#include "TestProbeBindings.hpp"
@@ -838,6 +839,7 @@ void renderer_submitScreenOverlay(ecs::Registry& registry) {
if (!g_renderFrame) return;
ensureTransformsUpdated(registry);
g_renderFrame->setScreenDomain(screenDomain());
+ g_renderFrame->setUITreeLayers(uiTreeLayers());
g_renderFrame->submitScreenOverlay(registry);
}
@@ -855,6 +857,7 @@ void renderer_submitAll(ecs::Registry& registry, i32 vpX, i32 vpY, i32 vpW, i32
// frame: the set is rebuilt by each layout pass, and a camera holding the
// previous one would draw a just-reparented element in the wrong domain.
g_renderFrame->setScreenDomain(screenDomain());
+ g_renderFrame->setUITreeLayers(uiTreeLayers());
g_renderFrame->processMasks(registry, vpX, vpY, vpW, vpH);
g_renderFrame->collectAll(registry);
diff --git a/src/esengine/bindings/UIBindings.cpp b/src/esengine/bindings/UIBindings.cpp
index 1ac6f4d1e..2fc540270 100644
--- a/src/esengine/bindings/UIBindings.cpp
+++ b/src/esengine/bindings/UIBindings.cpp
@@ -10,6 +10,7 @@
* QuickJS wrappers call the same code embind registers.
*/
#include "UIBindings.hpp"
+#include "../renderer/plugins/UIElementPlugin.hpp"
#include "ActiveContext.hpp"
#include "../core/EstellaContext.hpp"
@@ -84,8 +85,16 @@ f32 uiNode_computedHeight(ecs::Registry& r, u32 e) {
return n ? n->computed_size_.y : 0.0f;
}
+// What the Canvases hold with no uiOrder of its own; the frame borrows it. One table: the order pass and every collect it serves run in turn.
+static ecs::UITreeOrder g_uiTreeOrder;
+
+const std::unordered_map<u32, i32>* uiTreeLayers() {
+ return &g_uiTreeOrder.layers;
+}
+
void uiRenderOrder_update(ecs::Registry& registry) {
- ecs::uiRenderOrderUpdate(registry);
+ g_uiTreeOrder.base = UIElementPlugin::UI_BASE_LAYER;
+ ecs::uiRenderOrderUpdate(registry, &g_uiTreeOrder);
}
// The SDF text path (TS) reads an entity's UI
diff --git a/src/esengine/bindings/UIBindings.hpp b/src/esengine/bindings/UIBindings.hpp
index 69b070329..264448321 100644
--- a/src/esengine/bindings/UIBindings.hpp
+++ b/src/esengine/bindings/UIBindings.hpp
@@ -13,6 +13,7 @@
*/
#pragma once
+#include <unordered_map>
#include "../core/Types.hpp"
namespace esengine {
@@ -59,6 +60,8 @@ f32 uiNode_computedWidth(ecs::Registry& registry, u32 entity);
f32 uiNode_computedHeight(ecs::Registry& registry, u32 entity);
void uiRenderOrder_update(ecs::Registry& registry);
+/** The layers of what the Canvases hold with no uiOrder of its own, by entity id. */
+const std::unordered_map<u32, i32>* uiTreeLayers();
/** An entity's UI draw order, so the SDF text path can interleave glyph quads
* with UI quads. -1 = not a UI node. */
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index bb6f866a7..3f7421c6c 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -27,6 +27,7 @@
#include <cmath>
#include <algorithm>
#include <array>
+#include <unordered_map>
#include <unordered_set>
#include <vector>
@@ -258,6 +259,19 @@ struct RenderCollectContext {
*/
const std::unordered_set<u32>* screen_ui = nullptr;
+ /** @brief The layer of each emitter and plain Sprite a Canvas holds, by entity id, or null. @see ecs::UITreeOrder */
+ const std::unordered_map<u32, i32>* ui_tree_layers = nullptr;
+
+ /**
+ * @brief The layer @p entity draws at: its place in a Canvas's tree, unless its author named one.
+ * @details 0 is the default, and says nothing. A layer named outright is the way to hold something over or under a whole UI.
+ */
+ i32 treeLayer(Entity entity, i32 authored) const {
+ if (authored != 0 || !ui_tree_layers) return authored;
+ const auto it = ui_tree_layers->find(entity.id());
+ return it == ui_tree_layers->end() ? authored : it->second;
+ }
+
/**
* @brief What this view is already blocked by, or null for a collect that
* must not ask — a shadow face looks from a light, and a camera's
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index ee8c83dca..45b0eabd0 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -2489,6 +2489,7 @@ void RenderFrame::executeShadowPass(ecs::Registry& registry) {
collectCtx.shadowReachCap = view.reachCap;
}
collectCtx.screen_ui = screen_domain_;
+ collectCtx.ui_tree_layers = ui_tree_layers_;
// A shadow is part of the camera's picture: what the camera culled by its level of detail (grass past its distance)
// does not cast, and what it draws coarse casts coarse.
collectCtx.lod = {view_id_, &lod_view_state_, nullptr, true};
@@ -2680,6 +2681,7 @@ void RenderFrame::collectAll(ecs::Registry& registry, bool sceneGBuffer) {
// entities are laid out in pixels centred on the origin, and drawing them
// through a view matrix puts a HUD wherever the view happens to be looking.
collectCtx.screen_ui = screen_domain_;
+ collectCtx.ui_tree_layers = ui_tree_layers_;
collectCtx.lod = {view_id_, &lod_view_state_, &lod_counts_};
collectCtx.shading = view_shading_.get(view_id_);
collectCtx.weights = view_shading_.weights(view_id_);
@@ -2733,6 +2735,7 @@ void RenderFrame::collectMotion(ecs::Registry& registry) {
RenderCollectContext collectCtx{registry, frustum_, clip_state_, velocity_pool_, velocity_list_, ctx,
computeCameraView(ctx.view_projection)};
collectCtx.screen_ui = screen_domain_;
+ collectCtx.ui_tree_layers = ui_tree_layers_;
// The level the scene settled on, not a new choice, and not counted a second time.
collectCtx.lod = {view_id_, &lod_view_state_, nullptr};
collectCtx.occlusion = &occlusion_;
@@ -2774,6 +2777,7 @@ void RenderFrame::collectCover(ecs::Registry& registry) {
RenderCollectContext collectCtx{registry, frustum, clip_state_, cover_pool_, cover_list_, ctx,
computeCameraView(cover_view_projection_)};
collectCtx.screen_ui = screen_domain_;
+ collectCtx.ui_tree_layers = ui_tree_layers_;
for (auto& plugin : plugins_) {
if (plugin->castsShadows()) plugin->collect(collectCtx);
}
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 51b398e76..5dd7f4358 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -216,6 +216,8 @@ public:
/** @brief The screen's entities (UISystem::screenDomain), borrowed for the
* frame. Null partitions nothing — every collect is a world one. */
void setScreenDomain(const std::unordered_set<u32>* domain) { screen_domain_ = domain; }
+ /** @brief The layers of what a Canvas holds with no uiOrder, borrowed for the frame. @see ecs::UITreeOrder */
+ void setUITreeLayers(const std::unordered_map<u32, i32>* layers) { ui_tree_layers_ = layers; }
/** @brief Opens the overlay: @p projection maps the layout domain onto the
* pixel rect @p vpX/@p vpY/@p vpW/@p vpH of the surface. */
@@ -1133,6 +1135,7 @@ private:
/// Borrowed from the UI system for the frame (see setScreenDomain).
const std::unordered_set<u32>* screen_domain_ = nullptr;
+ const std::unordered_map<u32, i32>* ui_tree_layers_ = nullptr;
bool overlay_active_ = false;
glm::mat4 overlay_projection_{1.0f};
i32 overlay_vp_x_ = 0, overlay_vp_y_ = 0;
diff --git a/src/esengine/renderer/frame/RenderFrameOverlay.cpp b/src/esengine/renderer/frame/RenderFrameOverlay.cpp
index 93b322e0f..02bb52f31 100644
--- a/src/esengine/renderer/frame/RenderFrameOverlay.cpp
+++ b/src/esengine/renderer/frame/RenderFrameOverlay.cpp
@@ -66,6 +66,7 @@ void RenderFrame::submitScreenOverlay(ecs::Registry& registry) {
RenderCollectContext collectCtx{registry, overlayFrustum, clip_state_, pool_, draw_list_,
ctx, computeCameraView(overlay_projection_)};
collectCtx.screen_ui = screen_domain_;
+ collectCtx.ui_tree_layers = ui_tree_layers_;
// Only the plugins that can draw an entity out of a UI tree. Everything else
// draws world content, which by definition is not what this pass is for —
// and would land in it at layout-pixel coordinates.
diff --git a/src/esengine/renderer/frame/RenderFramePlanar.cpp b/src/esengine/renderer/frame/RenderFramePlanar.cpp
index 597a33620..7ba683a5b 100644
--- a/src/esengine/renderer/frame/RenderFramePlanar.cpp
+++ b/src/esengine/renderer/frame/RenderFramePlanar.cpp
@@ -159,6 +159,7 @@ void RenderFrame::executePlanarReflection(ecs::Registry& registry, u32 view) {
RenderCollectContext collect{registry, frustum, clip_state_, planar_pool_, planar_list_, ctx,
computeCameraView(ctx.view_projection)};
collect.screen_ui = screen_domain_;
+ collect.ui_tree_layers = ui_tree_layers_;
collect.excluded = capture.receiver;
collectSky(collect);
// No recursive frame/scene collect, post-processing, host overlays or HUD.
diff --git a/src/esengine/renderer/plugins/ParticlePlugin.cpp b/src/esengine/renderer/plugins/ParticlePlugin.cpp
index 172c923c2..b1ca82bc3 100644
--- a/src/esengine/renderer/plugins/ParticlePlugin.cpp
+++ b/src/esengine/renderer/plugins/ParticlePlugin.cpp
@@ -230,9 +230,10 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
}
}
+ const i32 layer = collect_ctx.treeLayer(entity, emitter.layer);
BatchDrawKey key{
.stage = ctx.current_stage,
- .layer = emitter.layer,
+ .layer = layer,
.shaderId = shaderId,
.blend = blend,
.textureId = textureId,
@@ -269,7 +270,7 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
state->trail_count.size() == state->pool.particles().size()) {
BatchDrawKey trailKey{
.stage = ctx.current_stage,
- .layer = emitter.layer,
+ .layer = layer,
.shaderId = ctx.batch_shader_id,
.blend = blendMode,
.textureId = ctx.white_texture_id,
diff --git a/src/esengine/renderer/plugins/SpritePlugin.cpp b/src/esengine/renderer/plugins/SpritePlugin.cpp
index 323a8dff6..2e46964c8 100644
--- a/src/esengine/renderer/plugins/SpritePlugin.cpp
+++ b/src/esengine/renderer/plugins/SpritePlugin.cpp
@@ -117,7 +117,7 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {
BatchDrawKey key{
.stage = ctx.current_stage,
- .layer = sprite.layer,
+ .layer = collect_ctx.treeLayer(entity, sprite.layer),
.order = sprite.order,
.shaderId = batch_shader_id_,
.blend = BlendMode::Normal,
diff --git a/src/esengine/ui/UIRenderOrderSystem.hpp b/src/esengine/ui/UIRenderOrderSystem.hpp
index a5fe5e048..6c2e3d493 100644
--- a/src/esengine/ui/UIRenderOrderSystem.hpp
+++ b/src/esengine/ui/UIRenderOrderSystem.hpp
@@ -11,11 +11,22 @@
#include "../ecs/components/ParticleEmitter.hpp"
#include "CanvasRoots.hpp"
+#include <unordered_map>
#include <vector>
namespace esengine::ecs {
-inline i32 assignRenderOrder(Registry& registry, Entity entity, i32 counter, u32 cullBit) {
+/**
+ * @brief The draw layer of what a Canvas holds that has no uiOrder of its own: an emitter, and a Sprite with no UINode.
+ * @details They paint by their place in the tree like the controls round them, so one listed after a panel is over it and one listed
+ * before is under it. Written to this table and not to their `layer`, which stays what its author said.
+ */
+struct UITreeOrder {
+ std::unordered_map<u32, i32> layers;
+ i32 base = 0;
+};
+
+inline i32 assignRenderOrder(Registry& registry, Entity entity, i32 counter, u32 cullBit, UITreeOrder* tree = nullptr) {
struct Task { Entity entity; u32 cullBit; };
std::vector<Task> pending{{entity, cullBit}};
std::vector<u8> visited;
@@ -44,14 +55,13 @@ inline i32 assignRenderOrder(Registry& registry, Entity entity, i32 counter, u32
sprite.layer = counter;
}
counter++;
- } else if (auto* emitter = registry.tryGet<ParticleEmitter>(entity)) {
- // UI emitters inherit tree order so their particles interleave with controls.
- if (emitter->layer != counter) {
- emitter->layer = counter;
- }
- counter++;
}
}
+ if (tree && !registry.has<UIVisual>(entity)
+ && (registry.has<ParticleEmitter>(entity) || (registry.has<Sprite>(entity) && !registry.has<UINode>(entity)))) {
+ tree->layers[entity.id()] = tree->base + counter;
+ counter++;
+ }
auto* children = registry.tryGet<Children>(entity);
if (!children) continue;
for (auto child = children->entities.rbegin(); child != children->entities.rend(); ++child)
@@ -60,12 +70,13 @@ inline i32 assignRenderOrder(Registry& registry, Entity entity, i32 counter, u32
return counter;
}
-inline void uiRenderOrderUpdate(Registry& registry) {
+inline void uiRenderOrderUpdate(Registry& registry, UITreeOrder* tree = nullptr) {
+ if (tree) tree->layers.clear();
i32 counter = 0;
for (Entity entity : canvasRoots(registry, false)) {
const auto& canvas = registry.get<Canvas>(entity);
const u32 bit = (canvas.layer < 0 || canvas.layer >= 32) ? 0u : (1u << canvas.layer);
- counter = assignRenderOrder(registry, entity, counter, bit);
+ counter = assignRenderOrder(registry, entity, counter, bit, tree);
}
}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index a5b82787e..b66b350b6 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4228,6 +4228,8 @@ export const NOTED = {
{"note": "GPU particles can hit things, tell each other, and drag trails."},
"feat(particles): draw a ParticleCollider's shape, and check GPU particle collision, events and trails in real frames":
{"note": "GPU particles can hit things, tell each other, and drag trails."},
+ "fix(ui): particles and plain sprites in a Canvas paint by their place in its tree":
+ {"note": "Particles and plain sprites in a Canvas paint by their place in its tree."},
"fix(assets): one hot load at a time per asset, so two rescans cannot lose a texture":
{"note": "A texture stays on a scene that rescans as it is placed."},
"feat(rig): the 2D rig editor, from an image to a character in the scene":