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
import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
createButton,
createToggle,
createProgress,
createDialog,
setButtonState,
interactionGears,
Interactable,
UIController,
UIGear,
INTERACTION_CONTROLLER,
UINode,
UIVisual,
UIVisualType,
FillMethod,
FillOrigin,
UIEventQueue,
UIEventType,
UIDisplay,
UIDialog,
UIToggle,
createToggleSystem,
themeColors,
type UIControllerData,
type UIGearData,
} from '../src/ui';
import type { Entity } from '../src/types';
import { fireGestureClick } from '../src/ui/input/gestureClick';
import type { World } from '../src/ecs/world';
// Minimal mock world — only the surface widgets + helpers touch.
interface MockWorld {
_entities: Set<number>;
_components: Map<number, Map<object, unknown>>;
_parents: Map<number, number>;
_names: Map<number, string>;
_nextId: number;
_despawnListeners: Array<(e: Entity) => void>;
spawn(): Entity;
despawn(e: Entity): void;
valid(e: Entity): boolean;
setParent(child: Entity, parent: Entity): void;
has(e: Entity, c: object): boolean;
get(e: Entity, c: object): unknown;
insert(e: Entity, c: object, data: unknown): void;
getEntitiesWithComponents(cs: object[]): Entity[];
onDespawn(cb: (e: Entity) => void): () => void;
}
function createMockWorld(): MockWorld {
const w: MockWorld = {
_entities: new Set<number>(),
_components: new Map(),
_parents: new Map(),
_names: new Map(),
_nextId: 1,
_despawnListeners: [],
spawn() {
const id = w._nextId++;
w._entities.add(id);
w._components.set(id, new Map());
return id as Entity;
},
despawn(e) {
for (const cb of w._despawnListeners) cb(e);
w._entities.delete(e as number);
w._components.delete(e as number);
w._parents.delete(e as number);
},
valid(e) {
return w._entities.has(e as number);
},
setParent(child, parent) {
w._parents.set(child as number, parent as number);
},
has(e, c) {
return w._components.get(e as number)?.has(c) ?? false;
},
get(e, c) {
return w._components.get(e as number)?.get(c);
},
insert(e, c, data) {
w._components.get(e as number)?.set(c, data);
},
getEntitiesWithComponents(cs) {
return [...w._entities].filter((e) =>
cs.every((c) => w._components.get(e)?.has(c))) as Entity[];
},
onDespawn(cb) {
w._despawnListeners.push(cb);
return () => {
const idx = w._despawnListeners.indexOf(cb);
if (idx !== -1) w._despawnListeners.splice(idx, 1);
};
},
};
return w;
}
describe('createButton', () => {
let world: MockWorld;
let events: UIEventQueue;
beforeEach(() => {
world = createMockWorld();
events = new UIEventQueue();
});
const interactionOf = (btn: Entity) =>
(world.get(btn, UIController) as UIControllerData).controllers
.find((c) => c.name === INTERACTION_CONTROLLER)!;
it('attaches the required components', () => {
const { entity: btn } = createButton({
world: world as unknown as World,
events,
states: {
normal: { color: { r: 1, g: 1, b: 1, a: 1 } },
hover: { color: { r: 0.9, g: 0.9, b: 0.9, a: 1 } },
pressed: { color: { r: 0.8, g: 0.8, b: 0.8, a: 1 } },
disabled: { color: { r: 0.5, g: 0.5, b: 0.5, a: 1 } },
},
});
expect(world.has(btn, UINode)).toBe(true);
expect(world.has(btn, UIVisual)).toBe(true);
expect(world.has(btn, Interactable)).toBe(true);
expect(world.has(btn, UIController)).toBe(true);
expect(world.has(btn, UIGear)).toBe(true);
});
it('folds the `states` map into a $interaction color gear', () => {
const { entity: btn } = createButton({
world: world as unknown as World,
events,
states: {
normal: { color: { r: 1, g: 0, b: 0, a: 1 } },
hover: { color: { r: 0, g: 1, b: 0, a: 1 } },
},
fadeDuration: 0.2,
});
const gear = world.get(btn, UIGear) as UIGearData;
expect(gear.bindings).toHaveLength(1);
const b = gear.bindings[0]!;
expect(b).toMatchObject({ controller: INTERACTION_CONTROLLER, component: 'UIVisual', property: 'color' });
expect(b.pages.normal).toEqual({ r: 1, g: 0, b: 0, a: 1 });
expect(b.pages.hover).toEqual({ r: 0, g: 1, b: 0, a: 1 });
expect(b.pages.pressed).toBeUndefined(); // sparse: unauthored pages leave the field alone
expect(b.tween?.duration).toBeCloseTo(0.2);
});
it('defaults its states to the active theme control roles (de-nude)', () => {
const { entity: btn } = createButton({ world: world as unknown as World, events, text: 'OK' });
const gear = world.get(btn, UIGear) as UIGearData;
const colorGear = gear.bindings.find((b) => b.property === 'color')!;
const c = themeColors();
expect(colorGear.pages.normal).toMatchObject(c.control);
expect(colorGear.pages.hover).toMatchObject(c.controlHover);
expect(colorGear.pages.pressed).toMatchObject(c.controlActive);
expect(colorGear.pages.disabled).toBeDefined();
});
it('starts on the "disabled" page when opts.disabled is true', () => {
const { entity: btn } = createButton({
world: world as unknown as World,
events,
disabled: true,
states: {
normal: {}, hover: {}, pressed: {}, disabled: {},
},
});
const i = world.get(btn, Interactable) as { enabled: boolean };
expect(interactionOf(btn).current).toBe('disabled');
expect(i.enabled).toBe(false);
});
it('lists canonical pages first, then custom states', () => {
const { entity: btn } = createButton({
world: world as unknown as World,
events,
states: { normal: {}, loading: {}, celebrating: {} },
});
expect(interactionOf(btn).pages).toEqual(
['normal', 'hover', 'pressed', 'disabled', 'focused', 'loading', 'celebrating'],
);
});
it('fires onClick on the interaction layer click event', () => {
const onClick = vi.fn();
const { entity: btn } = createButton({
world: world as unknown as World,
events,
states: { normal: {}, hover: {}, pressed: {} },
onClick,
});
events.emit(btn, UIEventType.Click);
expect(onClick).toHaveBeenCalledWith(btn);
});
it('runs a user-gesture click inside the release, and not again on the frame after', () => {
const onClick = vi.fn();
const { entity: btn } = createButton({
world: world as unknown as World, events, userGesture: true,
states: { normal: {}, hover: {}, pressed: {} }, onClick,
});
expect(fireGestureClick(world as unknown as World, btn)).toBe(true);
expect(onClick).toHaveBeenCalledTimes(1);
events.emit(btn, UIEventType.Click);
expect(onClick).toHaveBeenCalledTimes(1);
// A click no release reached — a key, or a tap too quick for a frame to
// see it pressed — still runs, on the frame.
events.emit(btn, UIEventType.Click);
expect(onClick).toHaveBeenCalledTimes(2);
});
it('swallows clicks while disabled', () => {
const onClick = vi.fn();
const { entity: btn } = createButton({
world: world as unknown as World,
events,
disabled: true,
states: { normal: {}, hover: {}, pressed: {} },
onClick,
});
events.emit(btn, UIEventType.Click);
expect(onClick).not.toHaveBeenCalled();
});
it('setButtonState writes the $interaction page, growing the enum for custom states', () => {
const { entity: btn } = createButton({
world: world as unknown as World,
events,
states: { normal: {} },
});
setButtonState(world as unknown as World, btn, 'loading');
const ctrl = interactionOf(btn);
expect(ctrl.current).toBe('loading');
expect(ctrl.pages).toContain('loading');
});
});
describe('interactionGears', () => {
it('splits color / sprite / scale overrides into per-field bindings', () => {
const bindings = interactionGears({
normal: { color: { r: 1, g: 1, b: 1, a: 1 }, sprite: 7, scale: 1 },
pressed: { color: { r: 0.5, g: 0.5, b: 0.5, a: 1 }, sprite: 8, scale: 0.95 },
}, 0.1);
const byProp = Object.fromEntries(bindings.map((b) => [b.property, b]));
expect(Object.keys(byProp).sort()).toEqual(['color', 'scale', 'texture']);
expect(byProp.color!.component).toBe('UIVisual');
expect(byProp.texture!.component).toBe('UIVisual');
expect(byProp.scale!.component).toBe('Transform');
expect(byProp.texture!.pages.pressed).toBe(8);
expect(byProp.scale!.pages.pressed).toEqual({ x: 0.95, y: 0.95, z: 1 });
// Sprite swaps are discrete: no tween even when fadeDuration is set.
expect(byProp.texture!.tween).toBeUndefined();
expect(byProp.color!.tween?.duration).toBeCloseTo(0.1);
expect(byProp.scale!.tween?.duration).toBeCloseTo(0.1);
});
it('emits no binding for a field no state overrides', () => {
const bindings = interactionGears({ normal: { color: { r: 1, g: 1, b: 1, a: 1 } }, hover: {} });
expect(bindings).toHaveLength(1);
expect(bindings[0]!.property).toBe('color');
expect(bindings[0]!.tween).toBeUndefined();
});
});
describe('createToggle', () => {
let world: MockWorld;
let events: UIEventQueue;
let tick: () => void;
beforeEach(() => {
world = createMockWorld();
events = new UIEventQueue();
const sys = createToggleSystem(world as unknown as World, events);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
tick = () => (sys as any)._fn();
});
it('starts with the provided isOn value, carried in the UIToggle component', () => {
const on = createToggle({
world: world as unknown as World,
events,
interactionStates: { normal: {}, hover: {}, pressed: {} },
isOn: true,
});
expect(on.getValue()).toBe(true);
expect((world.get(on.entity, UIToggle) as { isOn: boolean }).isOn).toBe(true);
});
it('flips isOn on click through the behavior system and emits change', () => {
const onChange = vi.fn();
const toggle = createToggle({
world: world as unknown as World,
events,
interactionStates: { normal: {}, hover: {}, pressed: {} },
isOn: false,
onChange,
});
tick(); // initial paint — no change event
events.emit(toggle.entity, UIEventType.Click);
expect(toggle.getValue()).toBe(true);
tick();
expect(onChange).toHaveBeenCalledWith(true, toggle.entity);
});
it('setValue writes the component; the system emits one change per transition', () => {
const onChange = vi.fn();
const toggle = createToggle({
world: world as unknown as World,
events,
interactionStates: { normal: {}, hover: {}, pressed: {} },
onChange,
});
tick();
toggle.setValue(true);
tick();
expect(onChange).toHaveBeenCalledTimes(1);
toggle.setValue(true); // no-op
tick();
expect(onChange).toHaveBeenCalledTimes(1);
expect(toggle.getValue()).toBe(true);
});
it('ignores clicks while disabled', () => {
const toggle = createToggle({
world: world as unknown as World,
events,
interactionStates: { normal: {}, hover: {}, pressed: {} },
disabled: true,
});
tick();
events.emit(toggle.entity, UIEventType.Click);
expect(toggle.getValue()).toBe(false);
});
it('dispose despawns the root entity', () => {
const toggle = createToggle({
world: world as unknown as World,
events,
interactionStates: { normal: {}, hover: {}, pressed: {} },
});
expect(world.valid(toggle.entity)).toBe(true);
toggle.dispose();
expect(world.valid(toggle.entity)).toBe(false);
});
});
describe('createProgress', () => {
let world: MockWorld;
beforeEach(() => {
world = createMockWorld();
});
it('clamps the initial value to [0, 1]', () => {
const p = createProgress({
world: world as unknown as World,
value: 1.5,
});
expect(p.getValue()).toBe(1);
const q = createProgress({
world: world as unknown as World,
value: -0.2,
});
expect(q.getValue()).toBe(0);
});
it('setValue writes fillAmount (default "right" = Filled from the left)', () => {
const p = createProgress({
world: world as unknown as World,
value: 0,
});
p.setValue(0.4);
const vis = world.get(p.fillEntity, UIVisual) as {
visualType: number;
fillAmount: number;
fillMethod: number;
fillOrigin: number;
};
expect(vis.visualType).toBe(UIVisualType.Filled);
expect(vis.fillAmount).toBeCloseTo(0.4);
expect(vis.fillMethod).toBe(FillMethod.Horizontal);
expect(vis.fillOrigin).toBe(FillOrigin.Left);
});
it('anchors the fill to the right when direction = "left"', () => {
const p = createProgress({
world: world as unknown as World,
direction: 'left',
value: 0.25,
});
const vis = world.get(p.fillEntity, UIVisual) as {
fillAmount: number;
fillMethod: number;
fillOrigin: number;
};
expect(vis.fillAmount).toBeCloseTo(0.25);
expect(vis.fillMethod).toBe(FillMethod.Horizontal);
expect(vis.fillOrigin).toBe(FillOrigin.Right);
});
it('uses the vertical fill axis for "up" / "down"', () => {
const up = createProgress({ world: world as unknown as World, direction: 'up', value: 0.5 });
const down = createProgress({ world: world as unknown as World, direction: 'down', value: 0.5 });
const upVis = world.get(up.fillEntity, UIVisual) as { fillMethod: number; fillOrigin: number };
const downVis = world.get(down.fillEntity, UIVisual) as { fillMethod: number; fillOrigin: number };
expect(upVis.fillMethod).toBe(FillMethod.Vertical);
expect(upVis.fillOrigin).toBe(FillOrigin.Bottom);
expect(downVis.fillMethod).toBe(FillMethod.Vertical);
expect(downVis.fillOrigin).toBe(FillOrigin.Top);
});
it('radial gauges use Radial360 from the top', () => {
const p = createProgress({ world: world as unknown as World, radial: true, value: 0.25 });
const vis = world.get(p.fillEntity, UIVisual) as {
visualType: number;
fillMethod: number;
fillOrigin: number;
fillAmount: number;
};
expect(vis.visualType).toBe(UIVisualType.Filled);
expect(vis.fillMethod).toBe(FillMethod.Radial360);
expect(vis.fillOrigin).toBe(FillOrigin.Top);
expect(vis.fillAmount).toBeCloseTo(0.25);
});
it('dispose despawns the track', () => {
const p = createProgress({ world: world as unknown as World });
expect(world.valid(p.entity)).toBe(true);
p.dispose();
expect(world.valid(p.entity)).toBe(false);
});
});
describe('createDialog', () => {
let world: MockWorld;
let events: UIEventQueue;
beforeEach(() => {
world = createMockWorld();
events = new UIEventQueue();
});
it('starts hidden by default — backdrop subtree is display:none', () => {
const dialog = createDialog({ world: world as unknown as World, events });
expect(dialog.isOpen()).toBe(false);
const bg = world.get(dialog.entity, UINode) as { display: number };
expect(bg.display).toBe(UIDisplay.None);
});
it('open() restores display:flex on the backdrop root', () => {
const dialog = createDialog({ world: world as unknown as World, events });
dialog.open();
expect(dialog.isOpen()).toBe(true);
const bg = world.get(dialog.entity, UINode) as { display: number };
expect(bg.display).toBe(UIDisplay.Flex);
// The blocker stays enabled permanently — display:none already removes
// the whole subtree from hit-testing while closed.
const inter = world.get(dialog.entity, Interactable) as { enabled: boolean };
expect(inter.enabled).toBe(true);
});
it('close() sets display:none so user children under the panel vanish too', () => {
const dialog = createDialog({ world: world as unknown as World, events, startHidden: false });
expect(dialog.isOpen()).toBe(true);
dialog.close();
expect(dialog.isOpen()).toBe(false);
const bg = world.get(dialog.entity, UINode) as { display: number };
expect(bg.display).toBe(UIDisplay.None);
});
it('open/close carry the dismissal component and report through onOpenChange', () => {
const seen: boolean[] = [];
const dialog = createDialog({
world: world as unknown as World, events,
onOpenChange: (open) => seen.push(open),
});
expect(world.has(dialog.entity, UIDialog)).toBe(true);
dialog.open();
dialog.close();
expect(seen).toEqual([true, false]);
});
it('dispose despawns the backdrop', () => {
const dialog = createDialog({ world: world as unknown as World, events });
expect(world.valid(dialog.entity)).toBe(true);
dialog.dispose();
expect(world.valid(dialog.entity)).toBe(false);
});
});