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): pointerEvents Receive takes the pointer back under a None ancestor

yhh72a45f11d038
diff --git a/desktop b/desktop
index 99fcc561c..1214b4363 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 99fcc561c1a93d8e97733929b5900dab2aa880e4
+Subproject commit 1214b4363749fb0a910442d65cad7e2275c48a51
diff --git a/docs/astro/src/content/docs/ui/layout.mdx b/docs/astro/src/content/docs/ui/layout.mdx
index 951900262..6275c6dc7 100644
--- a/docs/astro/src/content/docs/ui/layout.mdx
+++ b/docs/astro/src/content/docs/ui/layout.mdx
@@ -65,7 +65,7 @@ isAuto(d) // true when d is the auto length
| `position` | `UIPositionType` | `Relative` | `Relative` = in the flex flow; `Absolute` = out of flow, placed by insets. |
| `display` | `UIDisplay` | `Flex` | `None` removes this node **and its whole subtree** from layout, rendering, and hit-testing — the hierarchical show/hide. Contrast `UIVisual.enabled`, which hides only this entity's visual. |
| `opacity` | number | `1` | Subtree opacity, multiplied down the tree like CSS `opacity` (it multiplies into each descendant's own alpha; the subtree is not composited offscreen). |
-| `pointerEvents` | `UIPointerEvents` | `Auto` | `None` makes this node **and its subtree** transparent to the pointer: still drawn, hits pass through. |
+| `pointerEvents` | `UIPointerEvents` | `Auto` | `None` makes this node **and its subtree** transparent to the pointer: still drawn, hits pass through. A child set to `Receive` takes the pointer back (and gives it to its own subtree) — CSS's `pointer-events: auto` written on the child: a click-through overlay whose close button still answers. |
| `width` / `height` | `Dimension` | `auto()` | Box size; `auto` = content-/flex-driven. |
| `minWidth` / `minHeight` | `Dimension` | `auto()` | Lower size bounds; `auto` = unconstrained. |
| `maxWidth` / `maxHeight` | `Dimension` | `auto()` | Upper size bounds; `auto` = unconstrained. |
diff --git a/docs/astro/src/content/docs/ui/overview.mdx b/docs/astro/src/content/docs/ui/overview.mdx
index b04def95c..a639cd228 100644
--- a/docs/astro/src/content/docs/ui/overview.mdx
+++ b/docs/astro/src/content/docs/ui/overview.mdx
@@ -246,7 +246,7 @@ resolves `display`:
| Field | Default | Effect |
|---|---|---|
| `opacity` | `1` | Multiplied down the tree like CSS `opacity`. Fades a whole panel with one value. |
-| `pointerEvents` | `Auto` | `None` makes the node **and its subtree** transparent to the pointer — still drawn, hits pass straight through. |
+| `pointerEvents` | `Auto` | `None` makes the node **and its subtree** transparent to the pointer — still drawn, hits pass straight through. A child set to `Receive` takes the pointer back (and gives it to its own subtree) — CSS's `pointer-events: auto` written on the child: a click-through overlay whose close button still answers. |
These are the "CanvasGroup" knobs: fading a panel used to mean touching every visual's
`color.a`, and a decorative overlay had no way to stop eating clicks (`Interactable.blockRaycast`
diff --git a/docs/astro/src/content/docs/zh-cn/ui/layout.mdx b/docs/astro/src/content/docs/zh-cn/ui/layout.mdx
index deefaae56..b77a525ee 100644
--- a/docs/astro/src/content/docs/zh-cn/ui/layout.mdx
+++ b/docs/astro/src/content/docs/zh-cn/ui/layout.mdx
@@ -58,7 +58,7 @@ isAuto(d) // true when d is the auto length
| `position` | `UIPositionType` | `Relative` | `Relative` = 在 flex 流中;`Absolute` = 脱离流,由内偏移放置。 |
| `display` | `UIDisplay` | `Flex` | `None` 把该节点**连同整棵子树**从布局、渲染和命中测试中移除——层级式显示/隐藏。对比 `UIVisual.enabled`:后者只隐藏本实体的视觉。 |
| `opacity` | number | `1` | 子树不透明度,沿树向下相乘,同 CSS `opacity`(乘进每个后代自己的 alpha,不会把子树离屏合成)。 |
-| `pointerEvents` | `UIPointerEvents` | `Auto` | `None` 让该节点**连同整棵子树**对指针透明:照常绘制,点击直接穿过。 |
+| `pointerEvents` | `UIPointerEvents` | `Auto` | `None` 让该节点**连同整棵子树**对指针透明:照常绘制,点击直接穿过。 子节点设为 `Receive` 会重新接收指针(并交给它自己的子树)——相当于在子节点上写 CSS 的 `pointer-events: auto`:可点穿的遮罩上,关闭按钮照样能点。 |
| `width` / `height` | `Dimension` | `auto()` | 盒尺寸;`auto` = 内容/flex 驱动。 |
| `minWidth` / `minHeight` | `Dimension` | `auto()` | 尺寸下限;`auto` = 无约束。 |
| `maxWidth` / `maxHeight` | `Dimension` | `auto()` | 尺寸上限;`auto` = 无约束。 |
diff --git a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx b/docs/astro/src/content/docs/zh-cn/ui/overview.mdx
index bbefb12ca..dec8ccbb5 100644
--- a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/ui/overview.mdx
@@ -221,7 +221,7 @@ pages.close('shop');
| 字段 | 默认 | 效果 |
|---|---|---|
| `opacity` | `1` | 像 CSS `opacity` 一样沿树相乘。一个值淡出整块面板。 |
-| `pointerEvents` | `Auto` | `None` 让该节点**及其子树**对指针透明——照常绘制,点击直接穿过。 |
+| `pointerEvents` | `Auto` | `None` 让该节点**及其子树**对指针透明——照常绘制,点击直接穿过。 子节点设为 `Receive` 会重新接收指针(并交给它自己的子树)——相当于在子节点上写 CSS 的 `pointer-events: auto`:可点穿的遮罩上,关闭按钮照样能点。 |
这就是 "CanvasGroup" 那组旋钮:以前淡出一块面板意味着挨个改每个视觉的 `color.a`,而装饰性
覆盖层没有办法不吃掉点击(`Interactable.blockRaycast` 是逐实体的,不继承)。`opacity` 遵循
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index f9eb2a310..432cf5f21 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -2,11 +2,11 @@
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
"public": 115,
- "beta": 173,
- "experimental": 2745,
+ "beta": 176,
+ "experimental": 2821,
"deprecated": 3
},
- "total": 3033,
+ "total": 3112,
"subsystems": [
{
"id": "mobile-controls",
@@ -1925,6 +1925,30 @@
"minigame"
]
},
+ {
+ "name": "BillboardData",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "BillboardMode",
+ "kind": "enum",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Camera",
"kind": "const",
@@ -2155,6 +2179,18 @@
"minigame"
]
},
+ {
+ "name": "ImpostorData",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Input",
"kind": "const",
diff --git a/sdk/etc/ai.api.md b/sdk/etc/ai.api.md
index 1e4dfd714..2644f31f9 100644
--- a/sdk/etc/ai.api.md
+++ b/sdk/etc/ai.api.md
@@ -218,6 +218,7 @@ y: number | undefined
## BtPlugin — class @experimental
```
+activeWhen: ComponentDef<BehaviorTreeAgentData>[]
build: (app: App) => void
name: string
static new (): BtPlugin
@@ -304,6 +305,7 @@ transition: FsmTransition
## FsmPlugin — class @experimental
```
+activeWhen: ComponentDef<StateMachineAgentData>[]
build: (app: App) => void
name: string
static new (): FsmPlugin
@@ -548,6 +550,7 @@ status: "unknown" | "unavailable" | "complete" | "partial"
## NavPlugin — class @experimental
```
+activeWhen: (ComponentDef<NavAgentData> | ComponentDef<NavVolumeData>)[]
build: (app: App) => void
name: string
static new (): NavPlugin
@@ -665,6 +668,7 @@ visible: boolean
## PerceptionPlugin — class @experimental
```
+activeWhen: ComponentDef<PerceiverData>[]
build: (app: App) => void
name: string
static new (): PerceptionPlugin
diff --git a/sdk/etc/foliage.api.md b/sdk/etc/foliage.api.md
index 188577e1f..58f9311e8 100644
--- a/sdk/etc/foliage.api.md
+++ b/sdk/etc/foliage.api.md
@@ -64,6 +64,7 @@ static prototype: FoliageField
## FoliagePlugin — class @experimental
```
+activeWhen: ComponentDef<FoliageData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 41d6117ae..b1c709941 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,11 +1,11 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 2027 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2030 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"0f608f110f54e807"
+"ace63550c0783bc7"
```
## ANCHOR_AXES — const @experimental
@@ -767,7 +767,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; activeWhen?: readonly AnyComponentDef[]; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
@@ -784,6 +784,7 @@ getResource: <T>(resource: ResourceDef<T>) => T
getResourceByName: (name: string) => unknown | undefined
getResourceChangeTick: (name: string) => number
getResourceEntries: () => Array<[string, unknown]>
+getRunInBackground: () => boolean
getSystemTimings: () => ReadonlyMap<string, number> | null
getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
@@ -814,6 +815,7 @@ setMaxFixedSteps: (v: number) => App
setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
+setRunInBackground: (on: boolean) => void
setSideModules: (host: SideModuleHost) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
@@ -2762,6 +2764,8 @@ keyof ThemeColors
## CommandsInstance — class @public
```
@internal describe: () => string
+@internal isWorldIterating: () => boolean
+@internal reserveEntity: () => Entity
@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string, parent?: Entity | null) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
@@ -4475,6 +4479,7 @@ static prototype: FoliageField
## FoliagePlugin — class @experimental
```
+activeWhen: ComponentDef<FoliageData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -4654,6 +4659,7 @@ quality: QualityReport | undefined
seq: number | undefined
sprites: number
staticBatch: StaticBatchSummary | undefined
+textureStreaming: { enabled: boolean; textures: number; streamedMB: number; fullMB: number; moves: number; failures: number; startedSmall: number; } | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -6206,7 +6212,7 @@ ComponentDef<MotorJoint2DData>
## MouseButton — const @public
```
-(button: number) => Binding
+((button: number) => Binding) & { readonly Left: 0; readonly Middle: 1; readonly Right: 2; }
```
## Mut — function @public
@@ -7157,6 +7163,7 @@ world: string
## PlanetPlugin — class @experimental
```
+activeWhen: ComponentDef<PlanetData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -7521,6 +7528,7 @@ string | number | boolean
## Plugin — interface @experimental
```
+activeWhen: readonly AnyComponentDef[] | undefined
after: string[] | undefined
before: string[] | undefined
build: (app: App) => void
@@ -8181,6 +8189,7 @@ scanned: number
```
@internal resetChangeSequence: (sequence: number) => void
@internal resetTick: (tick: number) => void
+@internal settleKeptRows: () => void
@internal takeCost: () => QueryCost
[Symbol.iterator]: () => Iterator<QueryResult<C>>
count: () => number
@@ -9118,6 +9127,7 @@ getActiveScenes: () => string[]
getInitial: () => string | null
getLoadOrder: () => string[]
getLoaded: () => string[]
+getLoading: () => string[]
getScene: (name: string) => SceneContext | null
getSceneStatus: (name: string) => SceneStatus | null
isActive: (name: string) => boolean
@@ -9140,6 +9150,7 @@ switchTo: (name: string, options?: TransitionOptions) => Promise<void>
unload: (name: string, options?: TransitionOptions) => Promise<void>
updateTransition: (dt: number) => void
wake: (name: string) => void
+whenLoadsSettle: () => Promise<void>
static new (app: App): SceneManagerState
static prototype: SceneManagerState
```
@@ -10974,6 +10985,7 @@ z0: number
## TerrainPlugin — class @experimental
```
+activeWhen: ComponentDef<TerrainData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -12274,6 +12286,7 @@ static prototype: UIPlugin
```
Auto = 0
None = 1
+Receive = 2
```
## UIPositionType — enum @experimental
@@ -12862,6 +12875,7 @@ static prototype: WaterField
## WaterPlugin — class @experimental
```
+activeWhen: (ComponentDef<WaterBodyData> | ComponentDef<WaterZoneData>)[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -13087,6 +13101,7 @@ Generator<number, T, void>
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal closeSpeculation: () => void
+@internal commitReservedSpawn: (entity: Entity, name?: string) => void
@internal compositionChanges: () => CompositionDelta | null
@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void
@internal disconnectCpp: () => void
@@ -13142,6 +13157,7 @@ Generator<number, T, void>
@internal registerWriteReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number
@internal releaseScriptPools: () => void
@internal removedReaderCount: (component: AnyComponentDef) => number
+@internal reserveEntity: () => Entity
@internal resetIterationDepth: () => void
@internal resetQueryCacheStats: () => void
@internal resetQueryPool: () => void
@@ -13152,6 +13168,7 @@ Generator<number, T, void>
@internal resumeIteration: (depth: number) => void
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
+@internal setAssetFieldResolver: (resolver: AssetFieldResolver | null) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal setTransformChangeTracking: (on: boolean) => boolean
@internal speculating: boolean
@@ -15400,6 +15417,11 @@ InputRouter
(): boolean
```
+## isPointerBlockedInTree — function @experimental
+```
+(world: Pick<World, "has" | "get" | "valid">, entity: Entity): boolean
+```
+
## isPrefabEntry — function @experimental
```
(e: SceneEntry): e is PrefabInstanceEntry
@@ -16555,6 +16577,11 @@ Plugin
(app: App): boolean
```
+## sceneOutOfBandFields — function @experimental
+```
+(type: string): readonly string[]
+```
+
## sceneUses3DPhysics — function @experimental
```
(sceneData: SceneData): boolean
@@ -17185,6 +17212,11 @@ TrailPlugin
(): number
```
+## uiHitAtScreen — function @experimental
+```
+(world: PickableWorld, camera: UICameraData, overlay: ScreenOverlayData, screenGLX: number, screenGLY: number): Entity | null
+```
+
## uiHitTestWorld — function @experimental
```
(world: PickableWorld, ray: WorldRay, screenRay?: WorldRay): Entity | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index eebd84168..6e9f0cada 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,11 +1,11 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 169 beta · 2046 experimental · 3 deprecated
+Symbols: 115 public · 169 beta · 2049 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"0f608f110f54e807"
+"ace63550c0783bc7"
```
## ANCHOR_AXES — const @experimental
@@ -767,7 +767,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; activeWhen?: readonly AnyComponentDef[]; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
@@ -784,6 +784,7 @@ getResource: <T>(resource: ResourceDef<T>) => T
getResourceByName: (name: string) => unknown | undefined
getResourceChangeTick: (name: string) => number
getResourceEntries: () => Array<[string, unknown]>
+getRunInBackground: () => boolean
getSystemTimings: () => ReadonlyMap<string, number> | null
getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
@@ -814,6 +815,7 @@ setMaxFixedSteps: (v: number) => App
setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
+setRunInBackground: (on: boolean) => void
setSideModules: (host: SideModuleHost) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
@@ -2762,6 +2764,8 @@ keyof ThemeColors
## CommandsInstance — class @public
```
@internal describe: () => string
+@internal isWorldIterating: () => boolean
+@internal reserveEntity: () => Entity
@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string, parent?: Entity | null) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
@@ -4483,6 +4487,7 @@ static prototype: FoliageField
## FoliagePlugin — class @experimental
```
+activeWhen: ComponentDef<FoliageData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -4662,6 +4667,7 @@ quality: QualityReport | undefined
seq: number | undefined
sprites: number
staticBatch: StaticBatchSummary | undefined
+textureStreaming: { enabled: boolean; textures: number; streamedMB: number; fullMB: number; moves: number; failures: number; startedSmall: number; } | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -6219,7 +6225,7 @@ ComponentDef<MotorJoint2DData>
## MouseButton — const @public
```
-(button: number) => Binding
+((button: number) => Binding) & { readonly Left: 0; readonly Middle: 1; readonly Right: 2; }
```
## Mut — function @public
@@ -7360,6 +7366,7 @@ world: string
## PlanetPlugin — class @experimental
```
+activeWhen: ComponentDef<PlanetData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -7724,6 +7731,7 @@ string | number | boolean
## Plugin — interface @experimental
```
+activeWhen: readonly AnyComponentDef[] | undefined
after: string[] | undefined
before: string[] | undefined
build: (app: App) => void
@@ -8384,6 +8392,7 @@ scanned: number
```
@internal resetChangeSequence: (sequence: number) => void
@internal resetTick: (tick: number) => void
+@internal settleKeptRows: () => void
@internal takeCost: () => QueryCost
[Symbol.iterator]: () => Iterator<QueryResult<C>>
count: () => number
@@ -9331,6 +9340,7 @@ getActiveScenes: () => string[]
getInitial: () => string | null
getLoadOrder: () => string[]
getLoaded: () => string[]
+getLoading: () => string[]
getScene: (name: string) => SceneContext | null
getSceneStatus: (name: string) => SceneStatus | null
isActive: (name: string) => boolean
@@ -9353,6 +9363,7 @@ switchTo: (name: string, options?: TransitionOptions) => Promise<void>
unload: (name: string, options?: TransitionOptions) => Promise<void>
updateTransition: (dt: number) => void
wake: (name: string) => void
+whenLoadsSettle: () => Promise<void>
static new (app: App): SceneManagerState
static prototype: SceneManagerState
```
@@ -11187,6 +11198,7 @@ z0: number
## TerrainPlugin — class @experimental
```
+activeWhen: ComponentDef<TerrainData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -12487,6 +12499,7 @@ static prototype: UIPlugin
```
Auto = 0
None = 1
+Receive = 2
```
## UIPositionType — enum @experimental
@@ -13075,6 +13088,7 @@ static prototype: WaterField
## WaterPlugin — class @experimental
```
+activeWhen: (ComponentDef<WaterBodyData> | ComponentDef<WaterZoneData>)[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -13300,6 +13314,7 @@ Generator<number, T, void>
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal closeSpeculation: () => void
+@internal commitReservedSpawn: (entity: Entity, name?: string) => void
@internal compositionChanges: () => CompositionDelta | null
@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void
@internal disconnectCpp: () => void
@@ -13355,6 +13370,7 @@ Generator<number, T, void>
@internal registerWriteReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number
@internal releaseScriptPools: () => void
@internal removedReaderCount: (component: AnyComponentDef) => number
+@internal reserveEntity: () => Entity
@internal resetIterationDepth: () => void
@internal resetQueryCacheStats: () => void
@internal resetQueryPool: () => void
@@ -13365,6 +13381,7 @@ Generator<number, T, void>
@internal resumeIteration: (depth: number) => void
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
+@internal setAssetFieldResolver: (resolver: AssetFieldResolver | null) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal setTransformChangeTracking: (on: boolean) => boolean
@internal speculating: boolean
@@ -15663,6 +15680,11 @@ InputRouter
(): boolean
```
+## isPointerBlockedInTree — function @experimental
+```
+(world: Pick<World, "has" | "get" | "valid">, entity: Entity): boolean
+```
+
## isPrefabEntry — function @experimental
```
(e: SceneEntry): e is PrefabInstanceEntry
@@ -16818,6 +16840,11 @@ Plugin
(app: App): boolean
```
+## sceneOutOfBandFields — function @experimental
+```
+(type: string): readonly string[]
+```
+
## sceneUses3DPhysics — function @experimental
```
(sceneData: SceneData): boolean
@@ -17448,6 +17475,11 @@ TrailPlugin
(): number
```
+## uiHitAtScreen — function @experimental
+```
+(world: PickableWorld, camera: UICameraData, overlay: ScreenOverlayData, screenGLX: number, screenGLY: number): Entity | null
+```
+
## uiHitTestWorld — function @experimental
```
(world: PickableWorld, ray: WorldRay, screenRay?: WorldRay): Entity | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 5a64430c3..778c21b75 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 166 beta · 2026 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2029 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -762,7 +762,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; activeWhen?: readonly AnyComponentDef[]; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
@@ -779,6 +779,7 @@ getResource: <T>(resource: ResourceDef<T>) => T
getResourceByName: (name: string) => unknown | undefined
getResourceChangeTick: (name: string) => number
getResourceEntries: () => Array<[string, unknown]>
+getRunInBackground: () => boolean
getSystemTimings: () => ReadonlyMap<string, number> | null
getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
@@ -809,6 +810,7 @@ setMaxFixedSteps: (v: number) => App
setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
+setRunInBackground: (on: boolean) => void
setSideModules: (host: SideModuleHost) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
@@ -2757,6 +2759,8 @@ keyof ThemeColors
## CommandsInstance — class @public
```
@internal describe: () => string
+@internal isWorldIterating: () => boolean
+@internal reserveEntity: () => Entity
@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string, parent?: Entity | null) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
@@ -4470,6 +4474,7 @@ static prototype: FoliageField
## FoliagePlugin — class @experimental
```
+activeWhen: ComponentDef<FoliageData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -4649,6 +4654,7 @@ quality: QualityReport | undefined
seq: number | undefined
sprites: number
staticBatch: StaticBatchSummary | undefined
+textureStreaming: { enabled: boolean; textures: number; streamedMB: number; fullMB: number; moves: number; failures: number; startedSmall: number; } | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -6201,7 +6207,7 @@ ComponentDef<MotorJoint2DData>
## MouseButton — const @public
```
-(button: number) => Binding
+((button: number) => Binding) & { readonly Left: 0; readonly Middle: 1; readonly Right: 2; }
```
## Mut — function @public
@@ -7152,6 +7158,7 @@ world: string
## PlanetPlugin — class @experimental
```
+activeWhen: ComponentDef<PlanetData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -7516,6 +7523,7 @@ string | number | boolean
## Plugin — interface @experimental
```
+activeWhen: readonly AnyComponentDef[] | undefined
after: string[] | undefined
before: string[] | undefined
build: (app: App) => void
@@ -8176,6 +8184,7 @@ scanned: number
```
@internal resetChangeSequence: (sequence: number) => void
@internal resetTick: (tick: number) => void
+@internal settleKeptRows: () => void
@internal takeCost: () => QueryCost
[Symbol.iterator]: () => Iterator<QueryResult<C>>
count: () => number
@@ -9113,6 +9122,7 @@ getActiveScenes: () => string[]
getInitial: () => string | null
getLoadOrder: () => string[]
getLoaded: () => string[]
+getLoading: () => string[]
getScene: (name: string) => SceneContext | null
getSceneStatus: (name: string) => SceneStatus | null
isActive: (name: string) => boolean
@@ -9135,6 +9145,7 @@ switchTo: (name: string, options?: TransitionOptions) => Promise<void>
unload: (name: string, options?: TransitionOptions) => Promise<void>
updateTransition: (dt: number) => void
wake: (name: string) => void
+whenLoadsSettle: () => Promise<void>
static new (app: App): SceneManagerState
static prototype: SceneManagerState
```
@@ -10969,6 +10980,7 @@ z0: number
## TerrainPlugin — class @experimental
```
+activeWhen: ComponentDef<TerrainData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -12269,6 +12281,7 @@ static prototype: UIPlugin
```
Auto = 0
None = 1
+Receive = 2
```
## UIPositionType — enum @experimental
@@ -12857,6 +12870,7 @@ static prototype: WaterField
## WaterPlugin — class @experimental
```
+activeWhen: (ComponentDef<WaterBodyData> | ComponentDef<WaterZoneData>)[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -13082,6 +13096,7 @@ Generator<number, T, void>
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal closeSpeculation: () => void
+@internal commitReservedSpawn: (entity: Entity, name?: string) => void
@internal compositionChanges: () => CompositionDelta | null
@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void
@internal disconnectCpp: () => void
@@ -13137,6 +13152,7 @@ Generator<number, T, void>
@internal registerWriteReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number
@internal releaseScriptPools: () => void
@internal removedReaderCount: (component: AnyComponentDef) => number
+@internal reserveEntity: () => Entity
@internal resetIterationDepth: () => void
@internal resetQueryCacheStats: () => void
@internal resetQueryPool: () => void
@@ -13147,6 +13163,7 @@ Generator<number, T, void>
@internal resumeIteration: (depth: number) => void
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
+@internal setAssetFieldResolver: (resolver: AssetFieldResolver | null) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal setTransformChangeTracking: (on: boolean) => boolean
@internal speculating: boolean
@@ -15395,6 +15412,11 @@ InputRouter
(): boolean
```
+## isPointerBlockedInTree — function @experimental
+```
+(world: Pick<World, "has" | "get" | "valid">, entity: Entity): boolean
+```
+
## isPrefabEntry — function @experimental
```
(e: SceneEntry): e is PrefabInstanceEntry
@@ -16560,6 +16582,11 @@ Plugin
(app: App): boolean
```
+## sceneOutOfBandFields — function @experimental
+```
+(type: string): readonly string[]
+```
+
## sceneUses3DPhysics — function @experimental
```
(sceneData: SceneData): boolean
@@ -17190,6 +17217,11 @@ TrailPlugin
(): number
```
+## uiHitAtScreen — function @experimental
+```
+(world: PickableWorld, camera: UICameraData, overlay: ScreenOverlayData, screenGLX: number, screenGLY: number): Entity | null
+```
+
## uiHitTestWorld — function @experimental
```
(world: PickableWorld, ray: WorldRay, screenRay?: WorldRay): Entity | null
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index c460403e8..e9b0dc82e 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 2048 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2051 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -762,7 +762,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; activeWhen?: readonly AnyComponentDef[]; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
@@ -779,6 +779,7 @@ getResource: <T>(resource: ResourceDef<T>) => T
getResourceByName: (name: string) => unknown | undefined
getResourceChangeTick: (name: string) => number
getResourceEntries: () => Array<[string, unknown]>
+getRunInBackground: () => boolean
getSystemTimings: () => ReadonlyMap<string, number> | null
getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
@@ -809,6 +810,7 @@ setMaxFixedSteps: (v: number) => App
setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
+setRunInBackground: (on: boolean) => void
setSideModules: (host: SideModuleHost) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
@@ -2757,6 +2759,8 @@ keyof ThemeColors
## CommandsInstance — class @public
```
@internal describe: () => string
+@internal isWorldIterating: () => boolean
+@internal reserveEntity: () => Entity
@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string, parent?: Entity | null) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
@@ -4470,6 +4474,7 @@ static prototype: FoliageField
## FoliagePlugin — class @experimental
```
+activeWhen: ComponentDef<FoliageData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -4649,6 +4654,7 @@ quality: QualityReport | undefined
seq: number | undefined
sprites: number
staticBatch: StaticBatchSummary | undefined
+textureStreaming: { enabled: boolean; textures: number; streamedMB: number; fullMB: number; moves: number; failures: number; startedSmall: number; } | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -6496,7 +6502,7 @@ ComponentDef<MotorJoint2DData>
## MouseButton — const @public
```
-(button: number) => Binding
+((button: number) => Binding) & { readonly Left: 0; readonly Middle: 1; readonly Right: 2; }
```
## Mut — function @public
@@ -7447,6 +7453,7 @@ world: string
## PlanetPlugin — class @experimental
```
+activeWhen: ComponentDef<PlanetData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -7811,6 +7818,7 @@ string | number | boolean
## Plugin — interface @experimental
```
+activeWhen: readonly AnyComponentDef[] | undefined
after: string[] | undefined
before: string[] | undefined
build: (app: App) => void
@@ -8471,6 +8479,7 @@ scanned: number
```
@internal resetChangeSequence: (sequence: number) => void
@internal resetTick: (tick: number) => void
+@internal settleKeptRows: () => void
@internal takeCost: () => QueryCost
[Symbol.iterator]: () => Iterator<QueryResult<C>>
count: () => number
@@ -9408,6 +9417,7 @@ getActiveScenes: () => string[]
getInitial: () => string | null
getLoadOrder: () => string[]
getLoaded: () => string[]
+getLoading: () => string[]
getScene: (name: string) => SceneContext | null
getSceneStatus: (name: string) => SceneStatus | null
isActive: (name: string) => boolean
@@ -9430,6 +9440,7 @@ switchTo: (name: string, options?: TransitionOptions) => Promise<void>
unload: (name: string, options?: TransitionOptions) => Promise<void>
updateTransition: (dt: number) => void
wake: (name: string) => void
+whenLoadsSettle: () => Promise<void>
static new (app: App): SceneManagerState
static prototype: SceneManagerState
```
@@ -11264,6 +11275,7 @@ z0: number
## TerrainPlugin — class @experimental
```
+activeWhen: ComponentDef<TerrainData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -12564,6 +12576,7 @@ static prototype: UIPlugin
```
Auto = 0
None = 1
+Receive = 2
```
## UIPositionType — enum @experimental
@@ -13158,6 +13171,7 @@ static prototype: WaterField
## WaterPlugin — class @experimental
```
+activeWhen: (ComponentDef<WaterBodyData> | ComponentDef<WaterZoneData>)[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -13383,6 +13397,7 @@ Generator<number, T, void>
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal closeSpeculation: () => void
+@internal commitReservedSpawn: (entity: Entity, name?: string) => void
@internal compositionChanges: () => CompositionDelta | null
@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void
@internal disconnectCpp: () => void
@@ -13438,6 +13453,7 @@ Generator<number, T, void>
@internal registerWriteReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number
@internal releaseScriptPools: () => void
@internal removedReaderCount: (component: AnyComponentDef) => number
+@internal reserveEntity: () => Entity
@internal resetIterationDepth: () => void
@internal resetQueryCacheStats: () => void
@internal resetQueryPool: () => void
@@ -13448,6 +13464,7 @@ Generator<number, T, void>
@internal resumeIteration: (depth: number) => void
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
+@internal setAssetFieldResolver: (resolver: AssetFieldResolver | null) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal setTransformChangeTracking: (on: boolean) => boolean
@internal speculating: boolean
@@ -15711,6 +15728,11 @@ InputRouter
(): boolean
```
+## isPointerBlockedInTree — function @experimental
+```
+(world: Pick<World, "has" | "get" | "valid">, entity: Entity): boolean
+```
+
## isPrefabEntry — function @experimental
```
(e: SceneEntry): e is PrefabInstanceEntry
@@ -16866,6 +16888,11 @@ Plugin
(app: App): boolean
```
+## sceneOutOfBandFields — function @experimental
+```
+(type: string): readonly string[]
+```
+
## sceneUses3DPhysics — function @experimental
```
(sceneData: SceneData): boolean
@@ -17496,6 +17523,11 @@ TrailPlugin
(): number
```
+## uiHitAtScreen — function @experimental
+```
+(world: PickableWorld, camera: UICameraData, overlay: ScreenOverlayData, screenGLX: number, screenGLY: number): Entity | null
+```
+
## uiHitTestWorld — function @experimental
```
(world: PickableWorld, ray: WorldRay, screenRay?: WorldRay): Entity | null
diff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.md
index 44dd9d09c..e414c3bba 100644
--- a/sdk/etc/terrain.api.md
+++ b/sdk/etc/terrain.api.md
@@ -287,6 +287,7 @@ world: string
## PlanetPlugin — class @experimental
```
+activeWhen: ComponentDef<PlanetData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -544,6 +545,7 @@ z0: number
## TerrainPlugin — class @experimental
```
+activeWhen: ComponentDef<TerrainData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
diff --git a/sdk/etc/tilemap.api.md b/sdk/etc/tilemap.api.md
index f602114be..89a7e576d 100644
--- a/sdk/etc/tilemap.api.md
+++ b/sdk/etc/tilemap.api.md
@@ -442,6 +442,7 @@ Staggered = 2
## TilemapPlugin — class @experimental
```
+activeWhen: (ComponentDef<TilemapData> | BuiltinComponentDef<TilemapLayerData>)[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
diff --git a/sdk/etc/water.api.md b/sdk/etc/water.api.md
index 3057bb23e..f85e8f232 100644
--- a/sdk/etc/water.api.md
+++ b/sdk/etc/water.api.md
@@ -175,6 +175,7 @@ static prototype: WaterField
## WaterPlugin — class @experimental
```
+activeWhen: (ComponentDef<WaterBodyData> | ComponentDef<WaterZoneData>)[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index bc98f89ec..06aa89daf 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 2039 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2042 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -762,7 +762,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; activeWhen?: readonly AnyComponentDef[]; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
@@ -779,6 +779,7 @@ getResource: <T>(resource: ResourceDef<T>) => T
getResourceByName: (name: string) => unknown | undefined
getResourceChangeTick: (name: string) => number
getResourceEntries: () => Array<[string, unknown]>
+getRunInBackground: () => boolean
getSystemTimings: () => ReadonlyMap<string, number> | null
getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
@@ -809,6 +810,7 @@ setMaxFixedSteps: (v: number) => App
setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
+setRunInBackground: (on: boolean) => void
setSideModules: (host: SideModuleHost) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
@@ -2757,6 +2759,8 @@ keyof ThemeColors
## CommandsInstance — class @public
```
@internal describe: () => string
+@internal isWorldIterating: () => boolean
+@internal reserveEntity: () => Entity
@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string, parent?: Entity | null) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
@@ -4470,6 +4474,7 @@ static prototype: FoliageField
## FoliagePlugin — class @experimental
```
+activeWhen: ComponentDef<FoliageData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -4649,6 +4654,7 @@ quality: QualityReport | undefined
seq: number | undefined
sprites: number
staticBatch: StaticBatchSummary | undefined
+textureStreaming: { enabled: boolean; textures: number; streamedMB: number; fullMB: number; moves: number; failures: number; startedSmall: number; } | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -6208,7 +6214,7 @@ ComponentDef<MotorJoint2DData>
## MouseButton — const @public
```
-(button: number) => Binding
+((button: number) => Binding) & { readonly Left: 0; readonly Middle: 1; readonly Right: 2; }
```
## Mut — function @public
@@ -7159,6 +7165,7 @@ world: string
## PlanetPlugin — class @experimental
```
+activeWhen: ComponentDef<PlanetData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -7523,6 +7530,7 @@ string | number | boolean
## Plugin — interface @experimental
```
+activeWhen: readonly AnyComponentDef[] | undefined
after: string[] | undefined
before: string[] | undefined
build: (app: App) => void
@@ -8183,6 +8191,7 @@ scanned: number
```
@internal resetChangeSequence: (sequence: number) => void
@internal resetTick: (tick: number) => void
+@internal settleKeptRows: () => void
@internal takeCost: () => QueryCost
[Symbol.iterator]: () => Iterator<QueryResult<C>>
count: () => number
@@ -9120,6 +9129,7 @@ getActiveScenes: () => string[]
getInitial: () => string | null
getLoadOrder: () => string[]
getLoaded: () => string[]
+getLoading: () => string[]
getScene: (name: string) => SceneContext | null
getSceneStatus: (name: string) => SceneStatus | null
isActive: (name: string) => boolean
@@ -9142,6 +9152,7 @@ switchTo: (name: string, options?: TransitionOptions) => Promise<void>
unload: (name: string, options?: TransitionOptions) => Promise<void>
updateTransition: (dt: number) => void
wake: (name: string) => void
+whenLoadsSettle: () => Promise<void>
static new (app: App): SceneManagerState
static prototype: SceneManagerState
```
@@ -10976,6 +10987,7 @@ z0: number
## TerrainPlugin — class @experimental
```
+activeWhen: ComponentDef<TerrainData>[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -12276,6 +12288,7 @@ static prototype: UIPlugin
```
Auto = 0
None = 1
+Receive = 2
```
## UIPositionType — enum @experimental
@@ -12864,6 +12877,7 @@ static prototype: WaterField
## WaterPlugin — class @experimental
```
+activeWhen: (ComponentDef<WaterBodyData> | ComponentDef<WaterZoneData>)[]
build: (app: App) => void
cleanup: (app?: App) => void
name: string
@@ -13114,6 +13128,7 @@ Generator<number, T, void>
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal closeSpeculation: () => void
+@internal commitReservedSpawn: (entity: Entity, name?: string) => void
@internal compositionChanges: () => CompositionDelta | null
@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void
@internal disconnectCpp: () => void
@@ -13169,6 +13184,7 @@ Generator<number, T, void>
@internal registerWriteReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number
@internal releaseScriptPools: () => void
@internal removedReaderCount: (component: AnyComponentDef) => number
+@internal reserveEntity: () => Entity
@internal resetIterationDepth: () => void
@internal resetQueryCacheStats: () => void
@internal resetQueryPool: () => void
@@ -13179,6 +13195,7 @@ Generator<number, T, void>
@internal resumeIteration: (depth: number) => void
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
+@internal setAssetFieldResolver: (resolver: AssetFieldResolver | null) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal setTransformChangeTracking: (on: boolean) => boolean
@internal speculating: boolean
@@ -15437,6 +15454,11 @@ InputRouter
(): boolean
```
+## isPointerBlockedInTree — function @experimental
+```
+(world: Pick<World, "has" | "get" | "valid">, entity: Entity): boolean
+```
+
## isPrefabEntry — function @experimental
```
(e: SceneEntry): e is PrefabInstanceEntry
@@ -16592,6 +16614,11 @@ Plugin
(app: App): boolean
```
+## sceneOutOfBandFields — function @experimental
+```
+(type: string): readonly string[]
+```
+
## sceneUses3DPhysics — function @experimental
```
(sceneData: SceneData): boolean
@@ -17222,6 +17249,11 @@ TrailPlugin
(): number
```
+## uiHitAtScreen — function @experimental
+```
+(world: PickableWorld, camera: UICameraData, overlay: ScreenOverlayData, screenGLX: number, screenGLY: number): Entity | null
+```
+
## uiHitTestWorld — function @experimental
```
(world: PickableWorld, ray: WorldRay, screenRay?: WorldRay): Entity | null
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.ts
index a8afe12cc..80f0c925b 100644
--- a/sdk/src/core-ui.ts
+++ b/sdk/src/core-ui.ts
@@ -69,6 +69,7 @@ export {
uiWorldToScreen,
uiHitTestWorld,
uiHitAtScreen,
+ isPointerBlockedInTree,
uiPickWorld,
uiPickAllWorld,
type PickableWorld,
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index ce9f1b51e..7cb12d46d 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BillboardMode, BodyType, Canv
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '0f608f110f54e807';
+export const ABI_LAYOUT_HASH = 'ace63550c0783bc7';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -1384,7 +1384,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
position: { enum: [{ label: 'Relative', value: 0 }, { label: 'Absolute', value: 1 }] },
display: { enum: [{ label: 'Flex', value: 0 }, { label: 'None', value: 1 }], tooltip: "None removes this node and its whole subtree from layout, rendering and input." },
opacity: { min: 0, max: 1, tooltip: "Subtree opacity, multiplied down the tree. Fades this node and everything under it." },
- pointerEvents: { enum: [{ label: 'Auto', value: 0 }, { label: 'None', value: 1 }], tooltip: "None makes this node and its subtree transparent to the pointer — hits pass through to what is behind." },
+ pointerEvents: { enum: [{ label: 'Auto', value: 0 }, { label: 'None', value: 1 }, { label: 'Receive', value: 2 }], tooltip: "None makes this node and its subtree transparent to the pointer — hits pass through to what is behind." },
alignSelf: { enum: [{ label: 'Auto', value: 0 }, { label: 'Start', value: 1 }, { label: 'Center', value: 2 }, { label: 'End', value: 3 }, { label: 'Stretch', value: 4 }] },
},
},
diff --git a/sdk/src/ui/behavior/virtual-controls.ts b/sdk/src/ui/behavior/virtual-controls.ts
index cd99f466a..4a9292d98 100644
--- a/sdk/src/ui/behavior/virtual-controls.ts
+++ b/sdk/src/ui/behavior/virtual-controls.ts
@@ -8,13 +8,13 @@ import { Input, type InputState } from '../../input/input';
import type { World } from '../../ecs/world';
import type { Entity, Vec2 } from '../../types';
import { worldEngineApi } from '../../ecs/bridge/engineApi';
-import { UINode, UIPointerEvents } from '../core/ui-node';
+import { UINode } from '../core/ui-node';
import { px, DimensionUnit } from '../core/dimension';
import { UIEventType, type UIEventQueue } from '../core/events';
import { Interactable } from '../input/interactable';
import { UIControlPointers, type ControlPointer } from '../input/control-pointers';
import { isScreenEntity } from '../util/ui-pick';
-import { walkParentChain } from '../util/helpers';
+import { isPointerBlockedInTree } from '../util/helpers';
import { createLiveVisibilityQuery } from '../util/live-visibility';
import { createLocalTransformReader } from '../util/local-transform';
@@ -73,12 +73,7 @@ export function createVirtualControlSystem(world: World, events: UIEventQueue) {
if (!world.valid(entity) || !world.isEntityActive(entity) || world.isDestructionPending(entity)
|| (world.has(entity, Interactable) && !world.get(entity, Interactable).enabled)
|| hidden(entity)) return false;
- let blocked = world.has(entity, UINode) && world.get(entity, UINode).pointerEvents === UIPointerEvents.None;
- walkParentChain(world, entity, parent => {
- if (world.has(parent, UINode) && world.get(parent, UINode).pointerEvents === UIPointerEvents.None) blocked = true;
- return blocked;
- });
- return !blocked;
+ return !isPointerBlockedInTree(world, entity);
};
const getState = (entity: Entity): ControlState => {
let state = states.get(entity);
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index 479e6df8a..ba36ef596 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -11,6 +11,7 @@ export {
nextPowerOf2,
ensureComponent,
walkParentChain,
+ isPointerBlockedInTree,
EntityStateMap,
} from './util/helpers';
diff --git a/sdk/src/ui/util/helpers.ts b/sdk/src/ui/util/helpers.ts
index 74a4b6926..44469dde5 100644
--- a/sdk/src/ui/util/helpers.ts
+++ b/sdk/src/ui/util/helpers.ts
@@ -5,6 +5,7 @@ import type { ParentData, AnyComponentDef } from '../../ecs/component';
import type { Entity } from '../../types';
import type { World } from '../../ecs/world';
import { UIVisual, UIVisualType } from '../core/ui-visual';
+import { UINode, UIPointerEvents } from '../core/ui-node';
import type { CppRegistry } from '../../wasm';
import type { EngineApi } from '../../ecs/bridge/engineApi';
import { WasmBridge } from '../../wasm/WasmBridge';
@@ -87,6 +88,28 @@ export function getUINodeHeight(entity: Entity): number {
}
+/**
+ * Whether the pointer passes through @p entity because of `UINode.pointerEvents`:
+ * the nearest node, itself first, whose value is not Auto decides — None lets the
+ * pointer through, Receive takes it back (CSS `pointer-events: auto` written on a
+ * child). The rule the engine's layout applies; this is it for code that asks
+ * between layouts.
+ */
+export function isPointerBlockedInTree(world: Pick<World, 'has' | 'get' | 'valid'>, entity: Entity): boolean {
+ const decided = (e: Entity): boolean | null => {
+ if (!world.has(e, UINode)) return null;
+ const value = (world.get(e, UINode) as { pointerEvents: number }).pointerEvents;
+ return value === UIPointerEvents.None ? true : value === UIPointerEvents.Receive ? false : null;
+ };
+ let blocked = decided(entity);
+ if (blocked !== null) return blocked;
+ walkParentChain(world, entity, (parent) => {
+ blocked = decided(parent);
+ return blocked !== null;
+ });
+ return blocked === true;
+}
+
export function walkParentChain(
world: Pick<World, 'has' | 'get' | 'valid'>, entity: Entity,
callback: (ancestor: Entity) => boolean,
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index e7d594a1e..0d9fda1b9 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -433,6 +433,7 @@ export enum UIFillOrigin {
export enum UIPointerEvents {
Auto = 0,
None = 1,
+ Receive = 2,
}
export enum UIPositionType {
diff --git a/sdk/tests/pointer-blocked-in-tree.test.ts b/sdk/tests/pointer-blocked-in-tree.test.ts
new file mode 100644
index 000000000..4ae5800d2
--- /dev/null
+++ b/sdk/tests/pointer-blocked-in-tree.test.ts
@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/** The nearest node that is not Auto decides: None lets the pointer through, Receive takes it back. */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { World } from '../src/ecs/world';
+import type { ESEngineModule } from '../src/wasm';
+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
+import { Parent } from '../src/ecs/component';
+import { UINode, UIPointerEvents } from '../src/ui/core/ui-node';
+import { isPointerBlockedInTree } from '../src/ui/util/helpers';
+import type { Entity } from '../src/types';
+
+function node(world: World, pointerEvents: number, parent?: Entity): Entity {
+ const e = world.spawn();
+ world.insert(e, UINode, { pointerEvents } as never);
+ if (parent !== undefined) world.insert(e, Parent, { entity: parent });
+ return e;
+}
+
+describe.skipIf(!HAS_WASM)('isPointerBlockedInTree', () => {
+ let module: ESEngineModule;
+ beforeAll(async () => { module = await loadWasmModule(); });
+
+ it('follows the nearest decided node', () => {
+ const world = new World();
+ const registry = new module.Registry();
+ world.connectCpp(registry as never, module);
+ const overlay = node(world, UIPointerEvents.None);
+ const label = node(world, UIPointerEvents.Auto, overlay);
+ const close = node(world, UIPointerEvents.Receive, overlay);
+ const icon = node(world, UIPointerEvents.Auto, close);
+ const inner = node(world, UIPointerEvents.None, close);
+ expect(isPointerBlockedInTree(world, overlay)).toBe(true);
+ expect(isPointerBlockedInTree(world, label)).toBe(true);
+ expect(isPointerBlockedInTree(world, close)).toBe(false);
+ expect(isPointerBlockedInTree(world, icon)).toBe(false);
+ expect(isPointerBlockedInTree(world, inner)).toBe(true);
+ expect(isPointerBlockedInTree(world, node(world, UIPointerEvents.Auto))).toBe(false);
+ world.disconnectCpp(); registry.delete();
+ });
+});
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 94a905b0c..d7c650134 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -835,7 +835,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"position","type":"enum","group":"UINode","values":["Relative","Absolute"]},
{"key":"display","type":"enum","group":"UINode","values":["Flex","None"]},
{"key":"opacity","type":"float","group":"UINode"},
- {"key":"pointerEvents","type":"enum","group":"UINode","values":["Auto","None"]},
+ {"key":"pointerEvents","type":"enum","group":"UINode","values":["Auto","None","Receive"]},
{"key":"width.value","type":"float","group":"UINode"},
{"key":"width.unit","type":"float","group":"UINode"},
{"key":"height.value","type":"float","group":"UINode"},
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 2407b3cce..136247501 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -359,7 +359,8 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {
enum_<esengine::ecs::UIPointerEvents>("UIPointerEvents")
.value("Auto", esengine::ecs::UIPointerEvents::Auto)
- .value("None", esengine::ecs::UIPointerEvents::None);
+ .value("None", esengine::ecs::UIPointerEvents::None)
+ .value("Receive", esengine::ecs::UIPointerEvents::Receive);
enum_<esengine::ecs::UIPositionType>("UIPositionType")
.value("Relative", esengine::ecs::UIPositionType::Relative)
@@ -4371,7 +4372,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "0f608f110f54e807";
+static const char* kEsAbiLayoutHash = "ace63550c0783bc7";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/UINode.hpp b/src/esengine/ecs/components/UINode.hpp
index daa041568..7c2e32fbf 100644
--- a/src/esengine/ecs/components/UINode.hpp
+++ b/src/esengine/ecs/components/UINode.hpp
@@ -49,16 +49,23 @@ enum class UIDisplay : u8 {
};
/**
- * @brief CSS `pointer-events`. None makes the node AND its whole subtree
+ * @brief CSS `pointer-events`. None makes the node AND its subtree
* transparent to the pointer — still drawn, but hits pass straight
* through to whatever is behind. The hierarchical input gate (a panel
* mid-fade, a decorative overlay). Contrast with Interactable.enabled,
* which silences one entity without letting hits through it.
+ *
+ * Auto inherits: a node under a None ancestor is transparent too.
+ * Receive takes the pointer even there, and gives it back to its own
+ * subtree — CSS's `pointer-events: auto` written on the child, Unity's
+ * CanvasGroup "ignore parent groups": a click-through overlay whose one
+ * close button still answers.
*/
ES_ENUM()
enum class UIPointerEvents : u8 {
Auto,
- None
+ None,
+ Receive
};
/**
diff --git a/src/esengine/ui/UILayoutSystem.cpp b/src/esengine/ui/UILayoutSystem.cpp
index b22e67214..12ba30e9a 100644
--- a/src/esengine/ui/UILayoutSystem.cpp
+++ b/src/esengine/ui/UILayoutSystem.cpp
@@ -417,7 +417,8 @@ void propagateInheritedUIState(Registry& registry, UITree& tree) {
continue;
}
const f32 alpha = parentAlpha * std::clamp(n->opacity, 0.0f, 1.0f);
- const bool blocked = parentBlocked || n->pointerEvents == UIPointerEvents::None;
+ const bool blocked = n->pointerEvents == UIPointerEvents::None
+ || (parentBlocked && n->pointerEvents != UIPointerEvents::Receive);
n->alpha_in_tree_ = alpha;
n->pointer_blocked_in_tree_ = blocked;
inherited_alpha_stack_[depth] = alpha;
@@ -553,7 +554,8 @@ void UISystem::propagateDetachedUIState(Registry& registry) {
if (auto* node = registry.tryGet<UINode>(*it)) {
state.hidden = state.hidden || node->display == UIDisplay::None;
state.alpha *= std::clamp(node->opacity, 0.0f, 1.0f);
- state.blocked = state.blocked || node->pointerEvents == UIPointerEvents::None;
+ state.blocked = node->pointerEvents == UIPointerEvents::None
+ || (state.blocked && node->pointerEvents != UIPointerEvents::Receive);
node->hidden_in_tree_ = state.hidden;
node->alpha_in_tree_ = state.alpha;
node->pointer_blocked_in_tree_ = state.blocked;
diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cpp
index e304a9618..066dc03ae 100644
--- a/tests/renderer/test_batch_builder.cpp
+++ b/tests/renderer/test_batch_builder.cpp
@@ -1564,6 +1564,38 @@ TEST_CASE("detached UI refreshes inherited state without relocating its geometry
CHECK(registry.get<ecs::UINode>(leaf).alpha_in_tree_ == doctest::Approx(.4f));
}
+TEST_CASE("pointer events: Receive takes the pointer back under a None ancestor, in and out of the layout tree") {
+ for (bool inTree : {true, false}) {
+ ecs::Registry registry;
+ ecs::UISystem ui;
+ const auto node = [&](Entity parent, ecs::UIPointerEvents pe) {
+ const Entity e = registry.create();
+ registry.emplace<ecs::Transform>(e);
+ registry.emplace<ecs::UINode>(e).pointerEvents = pe;
+ if (parent != INVALID_ENTITY) {
+ registry.emplace<ecs::Parent>(e).entity = parent;
+ if (!registry.has<ecs::Children>(parent)) registry.emplace<ecs::Children>(parent);
+ registry.get<ecs::Children>(parent).entities.push_back(e);
+ }
+ return e;
+ };
+ const Entity overlay = node(INVALID_ENTITY, ecs::UIPointerEvents::None);
+ if (inTree) registry.emplace<ecs::Canvas>(overlay);
+ const Entity label = node(overlay, ecs::UIPointerEvents::Auto);
+ const Entity close = node(overlay, ecs::UIPointerEvents::Receive);
+ const Entity icon = node(close, ecs::UIPointerEvents::Auto);
+ const Entity quiet = node(close, ecs::UIPointerEvents::None);
+ ui.layoutUpdate(registry, -100, -100, 100, 100, true);
+ const auto blocked = [&](Entity e) { return registry.get<ecs::UINode>(e).pointer_blocked_in_tree_; };
+ CAPTURE(inTree);
+ CHECK(blocked(overlay));
+ CHECK(blocked(label));
+ CHECK_FALSE(blocked(close));
+ CHECK_FALSE(blocked(icon));
+ CHECK(blocked(quiet));
+ }
+}
+
TEST_CASE("detached UI state walks shared deep ancestry iteratively and recovers from reparenting") {
ecs::Registry registry;
ecs::UISystem ui;