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): particles and plain sprites in a Canvas paint by their place in its tree
yhh5b43e8569247
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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/desktopindex 9f96242b9..6192d1d00 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 9f96242b9777560eb48a1921b56a8c0d9745c1da+Subproject commit 6192d1d007ef555eb5a6ddc807b5df172d9b233ediff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdxindex 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, notdiff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdxindex 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.cppindex 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.cppindex 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 UIdiff --git a/src/esengine/bindings/UIBindings.hpp b/src/esengine/bindings/UIBindings.hppindex 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.hppindex 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'sdiff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 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.hppindex 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.cppindex 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.cppindex 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.cppindex 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.cppindex 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.hppindex 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, u32sprite.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, u32return 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.mjsindex 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":