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.

fix(ui): release hidden virtual controls before layout

yhh74fe844e2fde
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1de7369b3..e75b030b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Virtual controls stop when their authored UI is hidden.** Buttons and joysticks read current display ancestry instead of the previous layout's hidden cache. Hiding a captured control releases its source on the next sample and showing it requires a fresh press; new presses on shown controls are accepted before layout catches up. Change callbacks invalidate shared visibility reads before later controls are sampled.
+
- **Named actions reach fixed simulation steps independently of render frames.** Input maps sample before FixedUpdate instead of exposing the previous render frame's actions. Presses and releases survive frames without a fixed step, reach only the first catch-up step, and remain independently visible to Update. Pending flags use constant space per action, host cancellation drops buffered pulses, and current axis values are sampled for each cadence.
## [0.87.1] - 2026-10-15
diff --git a/sdk/src/ui/behavior/virtual-controls.ts b/sdk/src/ui/behavior/virtual-controls.ts
index 535381b55..c96384007 100644
--- a/sdk/src/ui/behavior/virtual-controls.ts
+++ b/sdk/src/ui/behavior/virtual-controls.ts
@@ -15,6 +15,7 @@ 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 { createLiveVisibilityQuery } from '../util/live-visibility';
export enum VirtualJoystickMode { Fixed = 0, Follow = 1 }
export interface VirtualJoystickData {
@@ -63,10 +64,11 @@ export function createVirtualControlSystem(world: World, events: UIEventQueue) {
input?.removeVirtualSource(state.owner); states.delete(entity);
};
const offDespawn = world.onDespawn(release);
- const enabled = (entity: Entity) => {
+ const hiddenFallback = (entity: Entity) => !!engine?.getUINodeHiddenInTree?.(registry!, entity);
+ const enabled = (entity: Entity, hidden: (entity: Entity) => boolean) => {
if (!world.valid(entity) || !world.isEntityActive(entity) || world.isDestructionPending(entity)
|| (world.has(entity, Interactable) && !world.get(entity, Interactable).enabled)
- || engine?.getUINodeHiddenInTree?.(registry!, entity)) return false;
+ || 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;
@@ -105,13 +107,14 @@ export function createVirtualControlSystem(world: World, events: UIEventQueue) {
system: defineSystem([Res(Input), Res(UIControlPointers), Res(Time)],
(current: InputState, frame: { pointers: Map<number, ControlPointer> }, time: TimeData) => {
input = current;
+ let hidden = createLiveVisibilityQuery(world, hiddenFallback);
for (const entity of states.keys()) if (!world.valid(entity)
|| (!world.has(entity, VirtualJoystick) && !world.has(entity, VirtualButton))) release(entity);
for (const type of [VirtualJoystick, VirtualButton] as const) {
for (const entity of world.getEntitiesWithComponents([type])) {
if (!world.has(entity, Transform)) { release(entity); continue; }
const state = getState(entity);
- const available = enabled(entity);
+ const available = enabled(entity, hidden);
const held = [...frame.pointers.values()].filter(p => available && p.entity === entity && p.down);
let value: Vec2 = { x: 0, y: 0 };
let id: string;
@@ -154,6 +157,7 @@ export function createVirtualControlSystem(world: World, events: UIEventQueue) {
if (value.x !== state.value.x || value.y !== state.value.y) {
state.value = value;
events.emit(entity, UIEventType.Change, { value: { ...value } });
+ hidden = createLiveVisibilityQuery(world, hiddenFallback);
}
}
}
diff --git a/sdk/tests/virtual-controls-visibility-wasm.test.ts b/sdk/tests/virtual-controls-visibility-wasm.test.ts
new file mode 100644
index 000000000..7216e716c
--- /dev/null
+++ b/sdk/tests/virtual-controls-visibility-wasm.test.ts
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { App } from '../src/app/app';
+import { AppContext, setDefaultContext } from '../src/ecs/context';
+import { Canvas, Transform } from '../src/ecs/component';
+import { InputState } from '../src/input/input';
+import { UINode, UIDisplay } from '../src/ui/core/ui-node';
+import { UIEventQueue } from '../src/ui/core/events';
+import { Interactable } from '../src/ui/input/interactable';
+import { createVirtualControlSystem, VirtualButton, VirtualJoystick } from '../src/ui/behavior/virtual-controls';
+import type { ControlPointer } from '../src/ui/input/control-pointers';
+import type { CppRegistry, ESEngineModule } from '../src/wasm';
+import type { Entity } from '../src/types';
+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
+
+describe.skipIf(!HAS_WASM)('virtual controls read authored visibility on real WASM', () => {
+ let engine: ESEngineModule, registry: CppRegistry, app: App, input: InputState;
+ let controls: ReturnType<typeof createVirtualControlSystem>;
+ let parent: Entity, entity: Entity;
+ const pointers = new Map<number, ControlPointer>();
+ const layout = () => engine.uiLayout_update(registry, -100, -100, 100, 100, true);
+ const point = (pressed: boolean) => pointers.set(1, {
+ id: 1, entity, pressedEntity: pressed ? entity : null, pressed, down: true,
+ layoutX: 50, layoutY: 0, worldX: 50, worldY: 0,
+ });
+ const tick = () => (controls.system._fn as (...args: unknown[]) => void)(input, { pointers }, { delta: 1 / 60 });
+ beforeAll(async () => { engine = await loadWasmModule(); });
+ beforeEach(() => {
+ setDefaultContext(new AppContext()); registry = new engine.Registry();
+ app = App.new(); app.connectCpp(registry, engine); input = new InputState(); pointers.clear();
+ parent = app.world.spawn(); entity = app.world.spawn();
+ for (const node of [parent, entity]) { app.world.insert(node, Transform); app.world.insert(node, UINode); }
+ app.world.insert(parent, Canvas); app.world.setParent(entity, parent); app.world.insert(entity, Interactable);
+ controls = createVirtualControlSystem(app.world, new UIEventQueue());
+ });
+ afterEach(() => { controls.dispose(); app.quit({ keepRenderer: true }); registry.delete(); });
+
+ for (const type of [VirtualButton, VirtualJoystick] as const) {
+ it.each(['self', 'ancestor'] as const)(`${type._name} releases when %s hides before layout and needs a fresh press`, target => {
+ app.world.insert(entity, type);
+ layout(); point(true); tick();
+ const id = type === VirtualButton ? 'fire' : 'move';
+ expect(input.getVirtual(id).x).toBe(1);
+ app.world.update(target === 'self' ? entity : parent, UINode, node => { node.display = UIDisplay.None; });
+ expect(engine.getUINodeHiddenInTree!(registry, entity)).toBe(false);
+ point(false); tick(); expect(input.getVirtual(id).x).toBe(0);
+ app.world.update(target === 'self' ? entity : parent, UINode, node => { node.display = UIDisplay.Flex; });
+ tick(); expect(input.getVirtual(id).x).toBe(0);
+ point(true); tick(); expect(input.getVirtual(id).x).toBe(1);
+ });
+ }
+ it('accepts a fresh press after showing even while the resolved cache is hidden', () => {
+ app.world.insert(entity, VirtualButton);
+ app.world.update(parent, UINode, node => { node.display = UIDisplay.None; }); layout();
+ expect(engine.getUINodeHiddenInTree!(registry, entity)).toBe(true);
+ app.world.update(parent, UINode, node => { node.display = UIDisplay.Flex; });
+ point(true); tick(); expect(input.getVirtual('fire').x).toBe(1);
+ });
+ it('observes an ancestor hidden by an earlier control change callback', () => {
+ controls.dispose();
+ const events = new UIEventQueue();
+ controls = createVirtualControlSystem(app.world, events);
+ app.world.insert(entity, VirtualButton);
+ const second = app.world.spawn();
+ app.world.insert(second, Transform); app.world.insert(second, UINode); app.world.insert(second, Interactable);
+ app.world.insert(second, VirtualButton, { inputId: 'second' }); app.world.setParent(second, parent);
+ layout(); point(true);
+ pointers.set(2, { ...pointers.get(1)!, id: 2, entity: second, pressedEntity: second });
+ events.on(entity, 'change', () => {
+ app.world.update(parent, UINode, node => { node.display = UIDisplay.None; });
+ });
+ tick(); expect(input.getVirtual('second').x).toBe(0);
+ point(false); tick(); expect(input.getVirtual('fire').x).toBe(0);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 57cd374c9..b10cc6419 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(ui): release hidden virtual controls before layout':
+ { note: 'Virtual controls stop when their authored UI is hidden.' },
'fix(input): sample named actions independently for fixed steps':
{ note: 'Named actions reach fixed simulation steps independently of render frames.' },
'test(youtube): acknowledge each hit and retain failure state':