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
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.esscenenew file mode 100644index 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.tsindex 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.tsindex 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.cppindex 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);