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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file What a pointer tells the entity it presses: where, which pointer, and what it does next.
*
* The UI interaction system already picks the topmost interactable under a pointer, lets that entity hold the gesture, and bubbles
* what happens to it. These pin the parts a touch-style consumer needs on top: a rectangle-only entity can be the one picked, every
* pointer event says where the pointer is, a held entity hears the pointer move, and a hold can be given up (nothing clicks).
*/
import { afterEach, beforeAll, describe, expect, it } from 'vitest';
import { App, flushPendingRegistrations } from '../src/app/app';
import { AppContext, setDefaultContext } from '../src/ecs/context';
import { EntityEvents } from '../src/ecs/entityEvents';
import { Input, InputState } from '../src/input/input';
import { Transform } from '../src/ecs/component';
import { ContentRect } from '../src/ui/core/content-rect';
import { UICameraInfo } from '../src/ui/core/ui-camera-info';
import { UIEventType } from '../src/ui/core/events';
import { UILayoutGeneration } from '../src/ui/layout/ui-layout-generation';
import { Interactable, UIInteraction } from '../src/ui/input/interactable';
import { UIControlPointers, type UiPointerEventData } from '../src/ui/input/control-pointers';
import { uiInteractionPlugin } from '../src/ui/input/interaction';
import { registerComponent } from '../src/ecs/component';
import type { Entity } from '../src/types';
import type { ESEngineModule } from '../src/wasm';
import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
describe.skipIf(!HAS_WASM)('pointer events (WASM integration)', () => {
let module: ESEngineModule;
let app: App | undefined;
let registry: InstanceType<ESEngineModule['Registry']> | undefined;
beforeAll(async () => { module = await loadWasmModule(); });
afterEach(() => {
if (app) uiInteractionPlugin.cleanup(app);
app?.world.disconnectCpp();
registry?.delete();
app = undefined;
registry = undefined;
});
/** A 100 x 100 view: world x and y run from -50 to 50, and a pointer at CSS (50, 50) is the origin. */
function boot(): { app: App; input: InputState; events: InstanceType<typeof import('../src/ecs/entityEvents').EntityEventQueue> } {
setDefaultContext(new AppContext());
registry = new module.Registry();
app = App.new();
app.connectCpp(registry, module);
const input = new InputState();
app.insertResource(Input, input);
const projection = new Float32Array([.02, 0, 0, 0, 0, .02, 0, 0, 0, 0, -.001, 0, 0, 0, 0, 1]);
app.insertResource(UICameraInfo, { ...UICameraInfo._default, viewProjection: projection, vpW: 100, vpH: 100, screenW: 100, screenH: 100, valid: true });
app.insertResource(UILayoutGeneration, { generation: 0 });
registerComponent('ContentRect', ContentRect);
uiInteractionPlugin.build(app);
flushPendingRegistrations(app);
return { app, input, events: app.getResource(EntityEvents) as never };
}
/** An entity that is only a rectangle: nothing to draw, so no sprite to take a box from. */
function area(a: App, x: number, y: number, w: number, h: number, blockRaycast = true): Entity {
const e = a.world.spawn('area');
a.world.insert(e, Transform, { position: { x, y, z: 0 } });
a.world.insert(e, ContentRect, { size: { x: w, y: h }, pivot: { x: 0.5, y: 0.5 } });
a.world.insert(e, Interactable, { blockRaycast });
return e;
}
/** One frame with the mouse at CSS (x, y) and the button as given. */
async function frame(a: App, input: InputState, x: number, y: number, press?: 'down' | 'up'): Promise<void> {
input.mouseX = x;
input.mouseY = y;
input.mouseButtonsPressed.clear();
input.mouseButtonsReleased.clear();
if (press === 'down') input.noteMouseDown(0);
if (press === 'up') input.noteMouseUp(0);
a.world.ensureTransformsComposed();
await a.tick(1 / 60);
}
it('gives every Interactable its UIInteraction before a pointer reaches it', async () => {
const { app: a, input } = boot();
const untouched = area(a, 200, 200, 10, 10);
await frame(a, input, 0, 0);
expect(a.world.has(untouched, UIInteraction)).toBe(true);
expect(a.world.get(untouched, UIInteraction)).toMatchObject({ hovered: false, pressed: false });
});
it('lets an entity that is only a rectangle be the one pressed', async () => {
const { app: a, input, events } = boot();
const hit = area(a, 0, 0, 40, 20);
const seen: UiPointerEventData[] = [];
events.on(hit, UIEventType.Press, (e) => seen.push(e.data as UiPointerEventData));
await frame(a, input, 50, 50, 'down');
expect(seen).toHaveLength(1);
// and outside its rectangle it is not
await frame(a, input, 50, 50, 'up');
const miss: unknown[] = [];
events.on(hit, UIEventType.Press, (e) => miss.push(e));
await frame(a, input, 5, 5, 'down');
expect(miss).toHaveLength(0);
});
it('says where the pointer is in every event: which pointer, and its world and surface position', async () => {
const { app: a, input, events } = boot();
const hit = area(a, 0, 0, 100, 100);
const log: Array<{ type: string; data: UiPointerEventData }> = [];
for (const type of [UIEventType.Press, UIEventType.Release, UIEventType.Click]) {
events.on(hit, type, (e) => log.push({ type: e.type, data: e.data as UiPointerEventData }));
}
await frame(a, input, 75, 25, 'down'); // right of centre by 25, above it by 25
await frame(a, input, 75, 25, 'up');
expect(log.map((l) => l.type)).toEqual([UIEventType.Press, UIEventType.Release, UIEventType.Click]);
const press = log[0]!.data;
expect(press.pointer).toBe(-1);
expect(press.worldX).toBeCloseTo(25, 3);
expect(press.worldY).toBeCloseTo(25, 3);
// the surface's y is up from the bottom: CSS y 25 of 100 is GL y 75
expect(press.screenX).toBeCloseTo(75, 3);
expect(press.screenY).toBeCloseTo(75, 3);
});
it('tells the holder when the pointer moves while it is held, and not otherwise', async () => {
const { app: a, input, events } = boot();
const hit = area(a, 0, 0, 100, 100);
const moves: UiPointerEventData[] = [];
events.on(hit, UIEventType.PointerMove, (e) => moves.push(e.data as UiPointerEventData));
await frame(a, input, 50, 50); // hovering: not a held pointer
await frame(a, input, 60, 50);
expect(moves).toHaveLength(0);
await frame(a, input, 60, 50, 'down'); // the press frame is not a move
expect(moves).toHaveLength(0);
await frame(a, input, 60, 50); // held, still
expect(moves).toHaveLength(0);
await frame(a, input, 70, 50);
await frame(a, input, 80, 40);
expect(moves.map((m) => [Math.round(m.worldX), Math.round(m.worldY)])).toEqual([[20, 0], [30, 10]]);
});
it('goes on telling the holder when the pointer leaves it: the gesture is the holder\'s', async () => {
const { app: a, input, events } = boot();
const hit = area(a, 0, 0, 20, 20);
const moves: number[] = [];
events.on(hit, UIEventType.PointerMove, (e) => moves.push((e.data as UiPointerEventData).worldX));
await frame(a, input, 50, 50, 'down');
await frame(a, input, 90, 50); // far outside the 20 x 20 area
expect(moves).toHaveLength(1);
expect(moves[0]).toBeCloseTo(40, 3);
});
it('bubbles a move to an ancestor that lets events through', async () => {
const { app: a, input, events } = boot();
const parent = area(a, 0, 0, 100, 100, false);
const child = area(a, 0, 0, 20, 20, false);
a.world.setParent(child, parent);
const heard: Array<[Entity, Entity]> = [];
events.on(parent, UIEventType.PointerMove, (e) => heard.push([e.target, e.currentTarget]));
await frame(a, input, 50, 50, 'down');
await frame(a, input, 55, 50);
expect(heard).toEqual([[child, parent]]);
});
it('lets a hold be given up: the holder hears press_cancel, and the lift clicks nothing', async () => {
const { app: a, input, events } = boot();
const hit = area(a, 0, 0, 100, 100);
const log: string[] = [];
for (const type of [UIEventType.Press, UIEventType.PressCancel, UIEventType.Release, UIEventType.Click, UIEventType.PointerMove]) {
events.on(hit, type, (e) => log.push(e.type));
}
await frame(a, input, 50, 50, 'down');
a.getResource(UIControlPointers).cancelHold(-1);
await frame(a, input, 55, 50); // moving after the cancel is nobody's move
await frame(a, input, 55, 50, 'up');
expect(log).toEqual([UIEventType.Press, UIEventType.PressCancel]);
});
it('can hand the hold to another entity, which then hears the moves and the release', async () => {
const { app: a, input, events } = boot();
const scroller = area(a, 0, 0, 100, 100); // made first, so the button — made after it — is the topmost
const button = area(a, 0, 0, 20, 20);
a.world.setParent(button, scroller);
const log: Array<[string, Entity]> = [];
for (const e of [button, scroller]) {
for (const type of [UIEventType.PressCancel, UIEventType.PointerMove, UIEventType.Release]) {
events.on(e, type, (ev) => { if (ev.currentTarget === ev.target) log.push([ev.type, ev.target]); });
}
}
await frame(a, input, 50, 50, 'down'); // the button, the topmost, holds it
a.getResource(UIControlPointers).cancelHold(-1, scroller);
await frame(a, input, 60, 50);
await frame(a, input, 60, 50, 'up');
expect(log.map(([t, e]) => `${t}:${e === button ? 'button' : 'scroller'}`)).toEqual([
'press_cancel:button', 'pointer_move:scroller', 'release:scroller',
]); // no click: the pointer lifted over the button, which is not what it held
});
it('cancelling a hold that is not there does nothing', async () => {
const { app: a, input } = boot();
area(a, 0, 0, 100, 100);
await frame(a, input, 50, 50);
expect(() => a.getResource(UIControlPointers).cancelHold(-1)).not.toThrow();
});
});