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.

perf(ui): share virtual control pointer groups per sample

yhh74e3b6bc4b1f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e75b030b8..48a8b384a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Virtual controls share each sample's pointer projection.** Stable buttons and joysticks group held pointers and completed taps once instead of cloning and scanning every pointer for every control. A change callback invalidates the grouping before later controls run, preserving capture cancellation and concurrent move/fire behavior.
+
- **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.
diff --git a/sdk/src/ui/behavior/virtual-controls.ts b/sdk/src/ui/behavior/virtual-controls.ts
index c96384007..b1e1e2d88 100644
--- a/sdk/src/ui/behavior/virtual-controls.ts
+++ b/sdk/src/ui/behavior/virtual-controls.ts
@@ -55,6 +55,8 @@ interface ControlState {
thumb: Vec2;
value: Vec2;
}
+interface PointerGroup { held: ControlPointer[]; tapped: boolean }
+const NO_HELD_POINTERS: readonly ControlPointer[] = [];
export function createVirtualControlSystem(world: World, events: UIEventQueue) {
const states = new Map<Entity, ControlState>();
const engine = worldEngineApi(world); const registry = world.getCppRegistry();
@@ -108,6 +110,21 @@ export function createVirtualControlSystem(world: World, events: UIEventQueue) {
(current: InputState, frame: { pointers: Map<number, ControlPointer> }, time: TimeData) => {
input = current;
let hidden = createLiveVisibilityQuery(world, hiddenFallback);
+ let groups: Map<Entity, PointerGroup> | null = null;
+ const pointersFor = (entity: Entity): PointerGroup | undefined => {
+ if (!groups) {
+ groups = new Map();
+ for (const pointer of frame.pointers.values()) {
+ const target = pointer.down ? pointer.entity : pointer.pressed ? pointer.pressedEntity : null;
+ if (target === null) continue;
+ let group = groups.get(target);
+ if (!group) { group = { held: [], tapped: false }; groups.set(target, group); }
+ if (pointer.down) group.held.push(pointer);
+ else group.tapped = true;
+ }
+ }
+ return groups.get(entity);
+ };
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) {
@@ -115,7 +132,8 @@ export function createVirtualControlSystem(world: World, events: UIEventQueue) {
if (!world.has(entity, Transform)) { release(entity); continue; }
const state = getState(entity);
const available = enabled(entity, hidden);
- const held = [...frame.pointers.values()].filter(p => available && p.entity === entity && p.down);
+ const group = available ? pointersFor(entity) : undefined;
+ const held = group?.held ?? NO_HELD_POINTERS;
let value: Vec2 = { x: 0, y: 0 };
let id: string;
if (type === VirtualJoystick) {
@@ -147,10 +165,9 @@ export function createVirtualControlSystem(world: World, events: UIEventQueue) {
positionChild(entity, data.handle, { x: state.origin.x + state.thumb.x, y: state.origin.y + state.thumb.y });
} else {
const data = world.get(entity, VirtualButton); id = data.inputId;
- for (const pointer of [...state.buttons]) if (!held.some(p => p.id === pointer)) state.buttons.delete(pointer);
+ for (const pointer of state.buttons) if (!held.some(p => p.id === pointer)) state.buttons.delete(pointer);
for (const pointer of held) if (pointer.pressed) state.buttons.add(pointer.id);
- const tapped = available && [...frame.pointers.values()].some(p => p.pressed
- && !p.down && p.pressedEntity === entity);
+ const tapped = group?.tapped;
if (state.buttons.size || tapped) value.x = data.value;
}
current.setVirtualSource(state.owner, id, value.x, value.y);
@@ -158,6 +175,7 @@ export function createVirtualControlSystem(world: World, events: UIEventQueue) {
state.value = value;
events.emit(entity, UIEventType.Change, { value: { ...value } });
hidden = createLiveVisibilityQuery(world, hiddenFallback);
+ groups = null;
}
}
}
diff --git a/sdk/tests/virtual-controls.test.ts b/sdk/tests/virtual-controls.test.ts
index ee7bb6f3d..363bf7633 100644
--- a/sdk/tests/virtual-controls.test.ts
+++ b/sdk/tests/virtual-controls.test.ts
@@ -32,7 +32,8 @@ function fixture() {
world.insert(id as Entity, component, { ...component._default, ...patch });
};
const input = new InputState(); const pointers = new Map<number, ControlPointer>();
- const control = createVirtualControlSystem(world, new UIEventQueue());
+ const events = new UIEventQueue();
+ const control = createVirtualControlSystem(world, events);
const invoke = control.system._fn as unknown as (input: InputState, frame: { pointers: Map<number, ControlPointer> }, time: { delta: number }) => void;
const tick = () => invoke(input, { pointers }, { delta: 1 / 60 });
const point = (id: number, entity: number, x: number, y: number, pressed = false) => {
@@ -40,9 +41,33 @@ function fixture() {
down: true, pressed, layoutX: x, layoutY: y, worldX: x, worldY: y });
};
const remove = (id: number) => { for (const h of removals) h(id as Entity); entities.delete(id); };
- return { world, input, pointers, tick, point, add, remove, dispose: control.dispose };
+ return { world, input, pointers, events, tick, point, add, remove, dispose: control.dispose };
}
describe('virtual control ownership and InputMap', () => {
+ it('does not rescan every pointer for every idle or held control', () => {
+ const f = fixture();
+ for (let entity = 1; entity <= 100; entity++) f.add(entity, VirtualButton);
+ for (let pointer = 1; pointer <= 10; pointer++) f.point(pointer, pointer, 0, 0, true);
+ f.tick();
+ for (const pointer of f.pointers.values()) pointer.pressed = false;
+ const values = f.pointers.values.bind(f.pointers);
+ let visits = 0;
+ f.pointers.values = () => {
+ const iterator = values(), next = iterator.next.bind(iterator);
+ iterator.next = () => { const result = next(); if (!result.done) visits++; return result; };
+ return iterator;
+ };
+ f.tick();
+ expect(visits).toBeLessThanOrEqual(2 * f.pointers.size);
+ expect(f.input.getVirtual('fire').x).toBe(1); f.dispose();
+ });
+ it('refreshes the pointer projection after a change callback cancels another capture', () => {
+ const f = fixture(); f.add(1, VirtualButton); f.add(2, VirtualButton, { inputId: 'second' });
+ f.point(1, 1, 0, 0, true); f.point(2, 2, 0, 0, true);
+ f.events.on(1 as Entity, 'change', () => { f.pointers.delete(2); });
+ f.tick(); expect(f.input.getVirtual('fire').x).toBe(1);
+ expect(f.input.getVirtual('second').x).toBe(0); f.dispose();
+ });
it('two fingers move and fire at once; cancelling only the button leaves movement held', () => {
const f = fixture(); f.add(1, VirtualJoystick); f.add(2, VirtualButton);
const map = new InputMap({ Move: Axis2D(Virtual('move')), Fire: Button(Virtual('fire')) });
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index b10cc6419..3d18fb4ef 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 = {
+ 'perf(ui): share virtual control pointer groups per sample':
+ { note: 'Virtual controls share each sample\'s pointer projection.' },
'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':