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 DragPlugin's pointer-drag state machine, driven through the mock-wasm
* App harness. The drag lifecycle — hit test → arm on press → cross the
* threshold to begin → move the target → release to end — is all TS logic
* over the Input + UICameraInfo resources and the Draggable/UIInteraction
* components, so it runs without a native binary. Assertions are on the
* observable state (DragState.isDragging, Transform.position) rather than
* the emitted events.
*/
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { flushPendingRegistrations } from '../src/app/app';
import type { App } from '../src/app/app';
import { Disabled, Transform } from '../src/ecs/component';
import { Input, InputState, inputEventCallbacks } from '../src/input/input';
import { inputRouter } from '../src/input/inputRouter';
import { takePrimaryPointerCancellation } from '../src/input/pointerCancellation';
import { UIEvents, UIEventQueue } from '../src/ui/core/events';
import { UICameraInfo } from '../src/ui/core/ui-camera-info';
import type { UICameraData } from '../src/ui/core/ui-camera-info';
import { Draggable, DragState } from '../src/ui/input/draggable';
import type { DragStateData } from '../src/ui/input/draggable';
import { Interactable, UIInteraction } from '../src/ui/input/interactable';
import { dragPlugin } from '../src/ui/input/drag';
import { bootMockApp } from './helpers/mockApp';
import type { Entity } from '../src/types';
let app: App;
afterEach(() => dragPlugin.cleanup(app));
beforeEach(() => {
app = bootMockApp().app;
app.insertResource(Input, new InputState());
app.insertResource(UIEvents, new UIEventQueue());
// A 1:1 world↔screen camera (100 world units == 100 screen px) so the default
// 5px drag threshold maps to 5 world units.
app.insertResource(UICameraInfo, {
vpX: 0, vpY: 0, vpW: 100, vpH: 100,
worldLeft: 0, worldBottom: 0, worldRight: 100, worldTop: 100,
worldMouseX: 0, worldMouseY: 0, valid: true,
} as UICameraData);
dragPlugin.build(app); // reads UIEvents; registers Draggable/DragState; adds DragSystem
flushPendingRegistrations(app);
});
function draggable(opts: Partial<{ enabled: boolean; dragThreshold: number; lockX: boolean; lockY: boolean; hovered: boolean }> = {}): Entity {
const e = app.world.spawn();
app.world.insert(e, Draggable, {
enabled: opts.enabled ?? true,
dragThreshold: opts.dragThreshold ?? 5,
lockX: opts.lockX ?? false,
lockY: opts.lockY ?? false,
});
// hovered is set by hand here, which makes every test below about the drag
// LOGIC and none of them about whether such an entity can be hovered at all.
// That question is ui-pick-world.test.ts, against the real raycast.
app.world.insert(e, UIInteraction, { hovered: opts.hovered ?? true });
app.world.insert(e, Transform, { position: { x: 0, y: 0, z: 0 }, worldPosition: { x: 0, y: 0, z: 0 } });
return e;
}
const input = (): InputState => app.getResource(Input) as InputState;
const cam = (): UICameraData => app.getResource(UICameraInfo) as UICameraData;
const dragOf = (e: Entity): DragStateData => app.world.get(e, DragState) as DragStateData;
const posX = (e: Entity): number => (app.world.get(e, Transform) as { position: { x: number } }).position.x;
const posY = (e: Entity): number => (app.world.get(e, Transform) as { position: { y: number } }).position.y;
// No inputPlugin runs here, so nothing auto-clears the per-frame press/release
// edges — we consume them ourselves after each tick, exactly as end-of-frame
// would. Without this the "pressed" edge sticks and re-arms the drag every tick.
async function step(): Promise<void> {
await app.tick(1 / 60);
const i = input();
i.mouseButtonsPressed.clear();
i.mouseButtonsReleased.clear();
}
async function press(x = 0, y = 0): Promise<void> {
cam().worldMouseX = x; cam().worldMouseY = y;
input().mouseButtons.add(0);
input().mouseButtonsPressed.add(0);
await step();
}
async function hold(x: number, y: number): Promise<void> {
cam().worldMouseX = x; cam().worldMouseY = y;
input().mouseButtons.add(0); // still held; the press edge was already consumed
await step();
}
async function release(x: number, y: number): Promise<void> {
cam().worldMouseX = x; cam().worldMouseY = y;
input().mouseButtons.delete(0);
input().mouseButtonsReleased.add(0);
await step();
}
describe('DragPlugin lifecycle', () => {
it('does not begin dragging while movement stays under the threshold', async () => {
const e = draggable({ dragThreshold: 5 });
await press(0, 0);
await hold(3, 0); // 3px < 5px threshold
expect(dragOf(e).isDragging).toBe(false);
expect(posX(e)).toBe(0); // target unmoved
});
it('begins dragging past the threshold and moves the target with the pointer', async () => {
const e = draggable({ dragThreshold: 5 });
await press(0, 0);
await hold(10, 0); // crosses threshold ⇒ drag starts and the move applies same frame
expect(dragOf(e).isDragging).toBe(true);
expect(posX(e)).toBeCloseTo(10, 5);
await hold(25, 0);
expect(posX(e)).toBeCloseTo(25, 5); // follows the pointer
});
it('releasing the button ends the drag', async () => {
const e = draggable();
await press(0, 0);
await hold(20, 0);
expect(dragOf(e).isDragging).toBe(true);
await release(20, 0);
expect(dragOf(e).isDragging).toBe(false);
});
it('lockX pins the X axis while Y still tracks', async () => {
const e = draggable({ lockX: true });
await press(0, 0);
await hold(20, 15); // past threshold diagonally
expect(dragOf(e).isDragging).toBe(true);
expect(posX(e)).toBeCloseTo(0, 5); // X locked to the start
expect(posY(e)).toBeCloseTo(15, 5); // Y free
});
});
describe('DragPlugin hit-test gating', () => {
it('ignores a disabled Draggable', async () => {
const e = draggable({ enabled: false });
await press(0, 0);
await hold(20, 0);
expect(app.world.has(e, DragState)).toBe(false); // never armed
expect(posX(e)).toBe(0);
});
it('ignores a Draggable that is not hovered', async () => {
const e = draggable({ hovered: false });
await press(0, 0);
await hold(20, 0);
expect(app.world.has(e, DragState)).toBe(false);
expect(posX(e)).toBe(0);
});
});
describe('DragPlugin cancellation', () => {
it('an editor-consumed release stops without applying another pointer movement', async () => {
const e = draggable(); await press(); await hold(20, 0);
const off = inputRouter.setEditorHandler({ onPointerUp: () => true });
try { inputEventCallbacks(input()).onPointerUp(0); } finally { off(); }
takePrimaryPointerCancellation(input());
cam().worldMouseX = 100; await step();
expect(posX(e)).toBeCloseTo(20);
expect(dragOf(e).isDragging).toBe(false);
});
it.each(['inactive', 'draggable-disabled', 'noninteractive', 'removed'])('%s cancels an active drag', async kind => {
const e = draggable(); await press(); await hold(20, 0);
if (kind === 'inactive') app.world.insert(e, Disabled);
if (kind === 'draggable-disabled') app.world.update(e, Draggable, d => { d.enabled = false; });
if (kind === 'noninteractive') app.world.insert(e, Interactable, { enabled: false });
if (kind === 'removed') app.world.remove(e, Draggable);
await hold(100, 0);
expect(posX(e)).toBeCloseTo(20);
expect(dragOf(e).isDragging).toBe(false);
});
it('losing the pointer projection cannot resume an old drag', async () => {
const e = draggable(); await press(); await hold(20, 0);
cam().valid = false; await hold(40, 0);
cam().valid = true; await hold(100, 0);
expect(posX(e)).toBeCloseTo(20);
expect(dragOf(e).isDragging).toBe(false);
});
it('a drag_start callback can disable the target before its first movement', async () => {
const e = draggable(), events = app.getResource(UIEvents), ended = vi.fn();
events.on(e, 'drag_start', () => app.world.update(e, Draggable, d => { d.enabled = false; }));
events.on(e, 'drag_end', ended);
await press(); await hold(20, 0); await hold(100, 0);
expect(posX(e)).toBe(0);
expect(dragOf(e).isDragging).toBe(false);
expect(ended).toHaveBeenCalledTimes(1);
});
it('a drag_move callback can remove Draggable without another movement or duplicate end', async () => {
const e = draggable(), events = app.getResource(UIEvents), ended = vi.fn();
events.on(e, 'drag_move', () => app.world.remove(e, Draggable));
events.on(e, 'drag_end', ended);
await press(); await hold(20, 0); await release(100, 0);
expect(posX(e)).toBeCloseTo(20);
expect(dragOf(e).isDragging).toBe(false);
expect(ended).toHaveBeenCalledTimes(1);
});
});