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.

feat(text): SDF text z-order interleaves with UI elements (REARCH_GUI P1.4d #1)

esenginef4f433366294
diff --git a/desktop/public/scenes/ui-text-zorder.esscene b/desktop/public/scenes/ui-text-zorder.esscene
new file mode 100644
index 000000000..deea5f7b8
--- /dev/null
+++ b/desktop/public/scenes/ui-text-zorder.esscene
@@ -0,0 +1,64 @@
+{
+ "version": "1.0",
+ "name": "SDF Text z-order over UI",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Canvas",
+ "parent": null,
+ "children": [2],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "Canvas", "data": { "designResolution": { "x": 800, "y": 600 }, "scaleMode": 2 } },
+ { "type": "UIRect", "data": { "anchorMin": { "x": 0.5, "y": 0.5 }, "anchorMax": { "x": 0.5, "y": 0.5 }, "size": { "x": 800, "y": 600 }, "pivot": { "x": 0.5, "y": 0.5 } } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "Panel",
+ "parent": 1,
+ "children": [3],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UIRect", "data": { "anchorMin": { "x": 0.5, "y": 0.5 }, "anchorMax": { "x": 0.5, "y": 0.5 }, "size": { "x": 460, "y": 150 }, "pivot": { "x": 0.5, "y": 0.5 } } },
+ { "type": "UIRenderer", "data": { "visualType": 1, "color": { "r": 0.2, "g": 0.32, "b": 0.6, "a": 1 }, "enabled": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "Label",
+ "parent": 2,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UIRect", "data": { "anchorMin": { "x": 0.5, "y": 0.5 }, "anchorMax": { "x": 0.5, "y": 0.5 }, "size": { "x": 440, "y": 130 }, "pivot": { "x": 0.5, "y": 0.5 } } },
+ {
+ "type": "Text",
+ "data": {
+ "content": "文字在面板上 Text on panel",
+ "fontFamily": "sans-serif",
+ "fontSize": 44,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 1,
+ "verticalAlign": 1,
+ "wordWrap": true
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 3615ea7a8..2056d6ed9 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -5,17 +5,21 @@
* path. A pre-flush callback scans Text entities, composes the world
* transform, places the text inside its UIRect box (no auto-size — the
* UIRect is the box; rendering never mutates layout) and draws batched
- * SDF glyph quads. Renderer is created lazily.
+ * SDF glyph quads, layered to interleave with sibling UI elements.
*/
import type { App, Plugin } from '../../app';
import { Transform, type TransformData, registerComponent } from '../../component';
-import type { ESEngineModule } from '../../wasm';
+import { defineSystem, Schedule } from '../../system';
+import type { ESEngineModule, CppRegistry } from '../../wasm';
import type { Entity } from '../../types';
import { SdfTextRenderer } from './text-renderer';
import { composeTRS, rectTextBox, UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';
import { Text, type TextData } from '../core/text';
import { UIRect, type UIRectData } from '../core/ui-rect';
-import { getEffectiveWidth, getEffectiveHeight } from '../uiHelpers';
+import { getEffectiveWidth, getEffectiveHeight, ensureUIRenderer } from '../uiHelpers';
+
+// Matches C++ UIElementPlugin::UI_BASE_LAYER — UI quads use layer = base + uiOrder.
+const UI_BASE_LAYER = 1000;
export class TextPlugin implements Plugin {
name = 'text';
@@ -26,10 +30,24 @@ export class TextPlugin implements Plugin {
build(app: App): void {
registerComponent('Text', Text);
+ const world = app.world;
+
+ // A Text node inside a UIRect is a UI render node: ensure it carries a
+ // UIRenderer (visualType None — not drawn as a quad) so the UI
+ // render-order pass assigns it a uiOrder and the SDF glyphs sort with
+ // sibling UI elements. Idempotent; runs before the PostUpdate order pass.
+ app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([], () => {
+ for (const e of world.getEntitiesWithComponents([Text, UIRect])) {
+ ensureUIRenderer(world, e as Entity);
+ }
+ }, { name: 'TextRenderNodeSystem' }));
+
const pipeline = app.pipeline;
if (!pipeline) return; // logic-only host → nothing to draw
- const world = app.world;
+ const module = app.wasmModule as ESEngineModule;
+ const registry = world.getCppRegistry() as CppRegistry;
+
pipeline.addPreFlushCallback(() => {
for (const e of world.getEntitiesWithComponents([Text, Transform])) {
const entity = e as Entity;
@@ -46,12 +64,14 @@ export class TextPlugin implements Plugin {
// Text.lineHeight is a ratio of fontSize (legacy convention).
const lineHeightPx = t.lineHeight > 0 ? t.lineHeight * t.fontSize : undefined;
- // A UIRect (UI canvas) is the text box: place + align + wrap inside it.
- // No UIRect ⇒ a world-space label anchored at the entity origin.
+ // A UIRect (UI canvas) is the text box: place + align + wrap inside
+ // it and sort by the UI render order. No UIRect ⇒ a world-space
+ // label at the entity origin, layer 0.
let originX: number | undefined;
let originY: number | undefined;
let maxWidth: number | undefined;
let boxHeight: number | undefined;
+ let layer = 0;
if (world.has(entity, UIRect)) {
const rect = world.get(entity, UIRect) as UIRectData;
const w = getEffectiveWidth(rect, entity);
@@ -61,6 +81,11 @@ export class TextPlugin implements Plugin {
originY = box.originY;
boxHeight = box.boxHeight;
if (t.wordWrap) maxWidth = box.maxWidth;
+
+ const order = module.ui_getRenderOrder
+ ? module.ui_getRenderOrder(registry, entity as number)
+ : -1;
+ layer = order >= 0 ? UI_BASE_LAYER + order : UI_BASE_LAYER;
}
this.renderer_.drawText(
@@ -81,7 +106,7 @@ export class TextPlugin implements Plugin {
},
this.matrix_,
entity as number,
- 0, // layer: UI z-order integration with UIElementPlugin is a follow-up
+ layer,
tr.worldPosition.z,
);
}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 5d13a53d6..dbbf06d83 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -124,6 +124,12 @@ export interface ESEngineModule {
* pointers to width*height byte buffers; the SDF is written into `outPtr`.
*/
sdfFromAlpha?(alphaPtr: number, outPtr: number, width: number, height: number, spread: number): void;
+ /**
+ * UI draw order of an entity (its UIRenderer.uiOrder, assigned by the UI
+ * render-order pass), so SDF text quads interleave with UI quads. -1 if the
+ * entity is not a UI render node (REARCH_GUI P1.4d #1).
+ */
+ ui_getRenderOrder?(registry: CppRegistry, entity: number): number;
getSpineBounds?(registry: CppRegistry, entity: number): SpineBounds;
renderer_submitSpineBatch?(
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index b210b6971..7d734a4c2 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -42,6 +42,7 @@
#include "../ecs/components/Velocity.hpp"
#include "../ecs/components/Camera.hpp"
#include "../ecs/components/UIRect.hpp"
+#include "../ecs/components/UIRenderer.hpp"
#include "../ecs/components/RigidBody.hpp"
#include "../ecs/components/Collider.hpp"
#include "../ecs/components/ShapeRenderer.hpp"
@@ -541,6 +542,15 @@ void uiRenderOrder_update(ecs::Registry& registry) {
ecs::uiRenderOrderUpdate(registry);
}
+// REARCH_GUI P1.4d (#1 z-order): the SDF text path (TS) reads an entity's UI
+// draw order so glyph quads interleave with UI quads. uiRenderOrderUpdate
+// assigns uiOrder to every UIRenderer in the UI tree (text nodes carry a
+// visualType=None UIRenderer purely to be ordered). -1 = not a UI node.
+i32 ui_getRenderOrder(ecs::Registry& registry, u32 entity) {
+ auto* ui = registry.tryGet<ecs::UIRenderer>(Entity::fromRaw(entity));
+ return ui ? ui->uiOrder : -1;
+}
+
void uiFlexLayout_update(ecs::Registry& registry) {
// Flex layout is now integrated into uiLayout_update via unified layout pass.
// Kept as no-op for backward compatibility with TS plugin.
@@ -627,6 +637,7 @@ EMSCRIPTEN_BINDINGS(esengine_ui_systems) {
emscripten::function("uiHitTest_getHitEntity", &esengine::uiHitTest_getHitEntity);
emscripten::function("uiHitTest_getHitEntityPrev", &esengine::uiHitTest_getHitEntityPrev);
emscripten::function("uiRenderOrder_update", &esengine::uiRenderOrder_update);
+ emscripten::function("ui_getRenderOrder", &esengine::ui_getRenderOrder);
emscripten::function("uiFlexLayout_update", &esengine::uiFlexLayout_update);
emscripten::function("getUIRectComputedWidth", &esengine::getUIRectComputedWidth);
emscripten::function("getUIRectComputedHeight", &esengine::getUIRectComputedHeight);