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(ui): export mask mode and verify nested mask inspection

yhh4fb5d8a5f4ae
diff --git a/desktop b/desktop
index 70bccb2b6..f068cea73 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 70bccb2b646a8c24bad34c630350d5157db4e742
+Subproject commit f068cea73cb0144fb73047320b7cf90bf4c2e70f
diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.md
index 2e02199f5..1e77af2eb 100644
--- a/examples/ui-localization-debug/README.md
+++ b/examples/ui-localization-debug/README.md
@@ -34,5 +34,13 @@ An input candidate is a configuration result, not a successful pointer hit.
World bounds do not account for clipping or occlusion; parent masks need review.
Inspection does not raycast, change hover/focus, or add persistent gizmos.
+Masked rows also show their ancestor mask chain (nearest first), mask mode and
+bounds. Unrotated 2D scissor rectangles report estimated containment, partial
+clipping or full clipping, plus the remaining world bounds. Stencil, rotated,
+unresolved and invalid-hierarchy cases require review. This estimate excludes
+camera projection, screen pixel rounding, stencil alpha and actual pointer
+delivery. The browser verification fixture finishes with a dedicated nested
+mask scene containing Inside / Partial / Outside controls.
+
This is a partial RM-009 delivery. Actual pointer hits, platform shaping,
real IME/device acceptance and layout cache performance remain separate work.
diff --git a/examples/ui-localization-debug/VALIDATION.md b/examples/ui-localization-debug/VALIDATION.md
index b3e81a817..6001b0f46 100644
--- a/examples/ui-localization-debug/VALIDATION.md
+++ b/examples/ui-localization-debug/VALIDATION.md
@@ -88,3 +88,29 @@ snapshot; live-game-only dialogs and scripts need runtime acceptance separately.
- The card remains In Progress. Actual clipped/occluded pointer delivery,
platform shaping, IME/accessibility/devices and performance remain open.
No local Electron/native test runner was launched.
+
+## Ancestor mask inspection increment — 2026-10-08
+
+The inspector shows the ancestor mask chain, mode and bounds. Unrotated 2D
+scissor rectangles estimate contained/partial/fully-clipped geometry; stencil,
+rotation, unavailable bounds and malformed hierarchy explicitly require review.
+These are world-rectangle estimates, not actual hit or visibility verdicts.
+Projection, pixel rounding, stencil alpha, occlusion and pointer delivery remain
+runtime acceptance work. The public SDK now exports MaskMode at runtime as well
+as in declarations, avoiding an undefined enum for inspector consumers.
+
+- SDK build and all 16 source/declaration API checks pass.
+- Editor: 26 layout/i18n/menu checks pass with a single thread worker. An initial
+ fork-worker run exited unexpectedly; the bounded thread run completed cleanly.
+ Tests cover nested intersection, contained/partial/full clipping, disabled
+ masks, rotated/stencil/unresolved masks and unchanged inspection data.
+- Browser verification includes a dedicated nested-mask scene. The fixture
+ removes its first disposable scene through SceneCommands before loading the
+ second; inspection itself does not alter either authored snapshot.
+- Built-in WebGL2: 27/27 checks pass. Manual widening of InnerMask from 200 to
+ 280 makes the snapshot stale; refresh changes Partial to contained and Outside
+ to partial. Undo restores the original geometry; no manual edit was saved.
+- Editor typecheck/production build and CSS-variable checks pass. The theme
+ gate retains the existing 18 findings; browser startup still reports missing
+ desktop MCP bridge and optional DragonBones, as in the prior increment.
+- No local desktop/native runner was launched. RM-009 remains In Progress.
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.ts
index ddc442162..9b172edd8 100644
--- a/sdk/src/core-ui.ts
+++ b/sdk/src/core-ui.ts
@@ -75,7 +75,7 @@ export {
SafeArea,
type TextData,
type UIMaskData,
- type MaskMode,
+ MaskMode,
type ScreenRect,
type InteractableData,
type UIInteractionData,
diff --git a/tools/ui-localization-browser.mjs b/tools/ui-localization-browser.mjs
index 4470258c5..8a32e83de 100644
--- a/tools/ui-localization-browser.mjs
+++ b/tools/ui-localization-browser.mjs
@@ -17,6 +17,9 @@ const server = await createServer({ configFile: false, root: path.join(root, 'de
if (req.url === '/__localization-scene.json') {
res.setHeader('Content-Type', 'application/json');
res.end(fs.readFileSync(path.join(root, 'examples/ui-localization-debug/assets/scenes/main.esscene')));
+ } else if (req.url === '/__mask-scene.json') {
+ res.setHeader('Content-Type', 'application/json');
+ res.end(fs.readFileSync(path.join(root, 'tools/ui-mask-inspection.esscene')));
} else if (req.url === '/__localization') {
const entry = `/@fs/${path.join(root, 'tools/ui-localization-browser.tsx').replaceAll('\\', '/')}`;
const html = `<html><head><title>UI localization Web verification</title></head><body><div id="root"></div><script type="module" src="${entry}"></script></body></html>`;
diff --git a/tools/ui-localization-browser.tsx b/tools/ui-localization-browser.tsx
index 7e89a100b..6eb2697b4 100644
--- a/tools/ui-localization-browser.tsx
+++ b/tools/ui-localization-browser.tsx
@@ -3,8 +3,9 @@ import '../desktop/src/main';
import { captureUITextRows, captureUIFocusRows, captureUILayoutRows } from '../desktop/src/panels/UITextDebugPanel';
import { EngineHost } from '../desktop/src/engine/EngineHost';
import { SceneModel } from '../desktop/src/engine/SceneModel';
+import { SceneCommands } from '../desktop/src/engine/SceneCommands';
import { useEditorStore } from '../desktop/src/store/editorStore';
-import { inspectTextLayout, pseudoLocalize } from 'esengine';
+import { inspectTextLayout, pseudoLocalize, MaskMode } from 'esengine';
const status = document.createElement('pre');
status.style.cssText = 'position:fixed;left:20px;bottom:20px;z-index:1001;max-width:600px;background:#19191d;color:white;padding:12px';
@@ -48,6 +49,22 @@ check(layoutRows.every(row => row.bounds !== null && row.width > 0 && row.height
check(layoutRows.filter(row => row.gate === 'candidate').map(row => row.name).join(',') === 'LocaleButton,PseudoButton,WidthButton', 'Only the three buttons are input candidates');
check(layoutRows.filter(row => row.gate === 'no-interactable').length === 10, 'Decorative boxes are not advertised as input targets');
check(JSON.stringify(SceneModel.serialize()) === before, 'Layout/input snapshot does not change authored data');
+check(MaskMode.Scissor === 0 && MaskMode.Stencil === 1, 'MaskMode is exported as a runtime enum');
+// The fixture replaces its disposable scene through the normal authoring door.
+SceneCommands.deleteEntities(SceneModel.serialize().entities.filter(entity => entity.parent === null).map(entity => entity.id) as never);
+await EngineHost.loadScene('/__mask-scene.json');
+EngineHost.syncEditorViewToScene();
+for (let i = 0; i < 12; i++) await new Promise(requestAnimationFrame);
+const maskBefore = JSON.stringify(SceneModel.serialize());
+const maskedRows = captureUILayoutRows();
+check(maskedRows.length === 6, 'Mask scene resolves Canvas, two masks and three buttons');
+check(maskedRows.find(row => row.name === 'Inside')?.clip === 'inside', 'Contained button is inside rectangular masks');
+check(maskedRows.find(row => row.name === 'Partial')?.clip === 'partial', 'Overflowing button is partially clipped');
+check(maskedRows.find(row => row.name === 'Outside')?.clip === 'outside', 'Outside button is fully clipped');
+check(maskedRows.find(row => row.name === 'Partial')?.masks.map(mask => mask.name).join(',') === 'InnerMask,OuterMask', 'Nested ancestor mask chain is resolved');
+const partial = maskedRows.find(row => row.name === 'Partial');
+check(!!partial?.clippedBounds && Math.abs(partial.clippedBounds.right - partial.clippedBounds.left - 60) < .01, 'Partial button retains 60 world units inside the mask');
+check(JSON.stringify(SceneModel.serialize()) === maskBefore, 'Mask inspection preserves scene data');
status.textContent += `RESULT ${passed} passed, ${failed} failed · ${EngineHost.activeBackend}`;
const dismiss = document.createElement('button');
dismiss.textContent = 'Dismiss verification report';
diff --git a/tools/ui-mask-inspection.esscene b/tools/ui-mask-inspection.esscene
new file mode 100644
index 000000000..4e8cdcac0
--- /dev/null
+++ b/tools/ui-mask-inspection.esscene
@@ -0,0 +1,365 @@
+{
+ "version": 4,
+ "name": "UI mask inspection",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "z": 10,
+ "y": 0
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Canvas",
+ "parent": null,
+ "children": [
+ 2
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Canvas",
+ "data": {
+ "designResolution": {
+ "x": 800,
+ "y": 600
+ },
+ "scaleMode": 2
+ }
+ },
+ {
+ "data": {},
+ "type": "UINode"
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "OuterMask",
+ "parent": 1,
+ "children": [
+ 3
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 340,
+ "unit": 0
+ },
+ "height": {
+ "value": 260,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 40,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 80,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIMask",
+ "data": {
+ "enabled": true,
+ "mode": 0
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.1,
+ "g": 0.13,
+ "b": 0.18,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "InnerMask",
+ "parent": 2,
+ "children": [
+ 4,
+ 5,
+ 6
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 200,
+ "unit": 0
+ },
+ "height": {
+ "value": 180,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 20,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 20,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIMask",
+ "data": {
+ "enabled": true,
+ "mode": 0
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.18,
+ "g": 0.22,
+ "b": 0.28,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Inside",
+ "parent": 3,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 120,
+ "unit": 0
+ },
+ "height": {
+ "value": 32,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 20,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 20,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.15,
+ "g": 0.45,
+ "b": 0.7,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Inside",
+ "fontFamily": "Arial",
+ "fontSize": 18
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "raycastTarget": true,
+ "blockRaycast": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "Partial",
+ "parent": 3,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 120,
+ "unit": 0
+ },
+ "height": {
+ "value": 32,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 140,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 70,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.15,
+ "g": 0.45,
+ "b": 0.7,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Partial",
+ "fontFamily": "Arial",
+ "fontSize": 18
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "raycastTarget": true,
+ "blockRaycast": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 6,
+ "name": "Outside",
+ "parent": 3,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 120,
+ "unit": 0
+ },
+ "height": {
+ "value": 32,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 230,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 120,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.15,
+ "g": 0.45,
+ "b": 0.7,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Outside",
+ "fontFamily": "Arial",
+ "fontSize": 18
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "raycastTarget": true,
+ "blockRaycast": true
+ }
+ }
+ ]
+ }
+ ]
+}