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(ui): export mask mode and verify nested mask inspection
yhh4fb5d8a5f4ae
diff --git a/desktop b/desktopindex 70bccb2b6..f068cea73 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 70bccb2b646a8c24bad34c630350d5157db4e742+Subproject commit f068cea73cb0144fb73047320b7cf90bf4c2e70fdiff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.mdindex 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.mdindex 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.tsindex 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.mjsindex 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, 'deif (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.tsxindex 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.heightcheck(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.esscenenew file mode 100644index 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+ }+ }+ ]+ }+ ]+}