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 event-binding.test.ts
* @brief Authored event → action wiring: target resolution (nearest-name),
* dispatch through the shared aiRegistry, guards/once/enabled, and
* bubbling from a child into an ancestor's rows.
*/
import { beforeEach, describe, expect, it } from 'vitest';
import { EntityEventQueue } from '../src/ecs/entityEvents';
import {
EventBinding,
createEventBindingRuntime,
ensureEventBindingActions,
resolveBindingTarget,
type EventBindingRow,
} from '../src/eventBinding';
import { Blackboard } from '../src/ai/fsm/Blackboard';
import { aiRegistry } from '../src/ai/fsm/AiContext';
import type { AiParams } from '../src/ai/fsm/registry';
import { Children, Name, Parent } from '../src/ecs/component';
import type { AnyComponentDef } from '../src/ecs/component';
import type { Entity } from '../src/types';
/** A world stub with just the slice EventBinding touches (+ hierarchy helpers). */
function makeWorld() {
const storage = new Map<AnyComponentDef, Map<Entity, unknown>>();
const alive = new Set<Entity>();
let next = 1;
const storeFor = (c: AnyComponentDef) => {
let s = storage.get(c);
if (!s) storage.set(c, (s = new Map()));
return s;
};
const world = {
spawn: (name?: string) => {
const e = next++ as Entity;
alive.add(e);
if (name !== undefined) storeFor(Name).set(e, { value: name });
return e;
},
despawn: (e: Entity) => alive.delete(e),
valid: (e: Entity) => alive.has(e),
has: (e: Entity, c: AnyComponentDef) => storeFor(c).has(e),
get: (e: Entity, c: AnyComponentDef) => storeFor(c).get(e),
set: (e: Entity, c: AnyComponentDef, d: unknown) => storeFor(c).set(e, d),
insert: (e: Entity, c: AnyComponentDef, d: unknown) => storeFor(c).set(e, d),
getEntitiesWithComponents: (comps: readonly AnyComponentDef[]) =>
[...storeFor(comps[0]).keys()].filter((e) => alive.has(e)),
findEntityByName: (name: string) => {
for (const [e, d] of storeFor(Name)) {
if ((d as { value: string }).value === name && alive.has(e)) return e;
}
return null;
},
/** Test helper: attach `child` under `parent`, maintaining both sides. */
parent: (child: Entity, parent: Entity) => {
storeFor(Parent).set(child, { entity: parent });
const kids = (storeFor(Children).get(parent) as { entities: Entity[] } | undefined) ?? { entities: [] };
kids.entities.push(child);
storeFor(Children).set(parent, kids);
},
};
return world;
}
type TestWorld = ReturnType<typeof makeWorld>;
function bind(world: TestWorld, entity: Entity, ...rows: EventBindingRow[]): void {
world.insert(entity, EventBinding, { rows });
}
/** Runtime over a fresh queue, wired to per-entity throwaway blackboards. */
function makeRuntime(world: TestWorld) {
const events = new EntityEventQueue();
const boards = new Map<Entity, Blackboard>();
const runtime = createEventBindingRuntime({
world: world as never,
events,
blackboardOf: (e) => {
let bb = boards.get(e);
if (!bb) boards.set(e, (bb = new Blackboard()));
return bb;
},
commands: () => null,
dt: () => 1 / 60,
});
return { events, runtime, boards };
}
/** Records (entity, arg) for every invocation of the test action. */
let calls: Array<{ entity: Entity; arg?: string; params?: AiParams }> = [];
beforeEach(() => {
calls = [];
aiRegistry.registerAction('test.record', (ctx, _bb, arg) => {
calls.push({ entity: ctx.entity, arg });
});
aiRegistry.registerCondition('test.never', () => false);
aiRegistry.registerCondition('test.always', () => true);
});
describe('resolveBindingTarget — nearest name wins', () => {
it('empty target is the entity that carries the binding', () => {
const world = makeWorld();
const self = world.spawn('Button');
expect(resolveBindingTarget(world as never, self, '')).toBe(self);
});
it('finds a sibling through the shared parent', () => {
const world = makeWorld();
const root = world.spawn('Root');
const button = world.spawn('Button');
const panel = world.spawn('Panel');
world.parent(button, root);
world.parent(panel, root);
expect(resolveBindingTarget(world as never, button, 'Panel')).toBe(panel);
});
it('prefers the match inside its own subtree over an outer one', () => {
// Two prefab instances, each with a "Panel": a binding inside instance A
// must not reach into instance B.
const world = makeWorld();
const root = world.spawn('Root');
const instA = world.spawn('Dialog');
const instB = world.spawn('Dialog');
world.parent(instA, root);
world.parent(instB, root);
const panelA = world.spawn('Panel');
const panelB = world.spawn('Panel');
world.parent(panelA, instA);
world.parent(panelB, instB);
const buttonA = world.spawn('Close');
world.parent(buttonA, instA);
expect(resolveBindingTarget(world as never, buttonA, 'Panel')).toBe(panelA);
});
it('falls back to the world name index for an unrelated root', () => {
const world = makeWorld();
const button = world.spawn('Button');
const hud = world.spawn('HUD'); // no shared ancestor
expect(resolveBindingTarget(world as never, button, 'HUD')).toBe(hud);
});
it('returns null when nothing is named that', () => {
const world = makeWorld();
const button = world.spawn('Button');
expect(resolveBindingTarget(world as never, button, 'Nope')).toBeNull();
});
});
describe('dispatch', () => {
it('runs the row action on click, with the row arg', () => {
const world = makeWorld();
const button = world.spawn('Button');
bind(world, button, { event: 'click', action: 'test.record', arg: 'tabs:settings' });
const { events, runtime } = makeRuntime(world);
runtime.sync();
events.emit(button, 'click');
expect(calls).toEqual([{ entity: button, arg: 'tabs:settings' }]);
});
it('runs the action on the NAMED target, not on the emitter', () => {
const world = makeWorld();
const root = world.spawn('Root');
const button = world.spawn('Button');
const dialog = world.spawn('Dialog');
world.parent(button, root);
world.parent(dialog, root);
bind(world, button, { event: 'click', action: 'test.record', target: 'Dialog' });
const { events, runtime } = makeRuntime(world);
runtime.sync();
events.emit(button, 'click');
expect(calls).toEqual([{ entity: dialog, arg: undefined }]);
});
it('ignores events of other types and rows that are disabled', () => {
const world = makeWorld();
const button = world.spawn('Button');
bind(
world,
button,
{ event: 'click', action: 'test.record', arg: 'on' },
{ event: 'click', action: 'test.record', arg: 'off', enabled: false },
);
const { events, runtime } = makeRuntime(world);
runtime.sync();
events.emit(button, 'hover_enter');
events.emit(button, 'click');
expect(calls.map((c) => c.arg)).toEqual(['on']);
});
it('honours a guard condition', () => {
const world = makeWorld();
const button = world.spawn('Button');
bind(
world,
button,
{ event: 'click', action: 'test.record', arg: 'blocked', guard: 'test.never' },
{ event: 'click', action: 'test.record', arg: 'allowed', guard: 'test.always' },
);
const { events, runtime } = makeRuntime(world);
runtime.sync();
events.emit(button, 'click');
expect(calls.map((c) => c.arg)).toEqual(['allowed']);
});
it('a `once` row fires exactly once', () => {
const world = makeWorld();
const button = world.spawn('Button');
bind(world, button, { event: 'click', action: 'test.record', once: true });
const { events, runtime } = makeRuntime(world);
runtime.sync();
events.emit(button, 'click');
events.emit(button, 'click');
expect(calls).toHaveLength(1);
});
it('an ancestor row hears a bubbled child event', () => {
const world = makeWorld();
const panel = world.spawn('Panel');
const button = world.spawn('Button');
world.parent(button, panel);
bind(world, panel, { event: 'click', action: 'test.record', arg: 'from-panel' });
const { events, runtime } = makeRuntime(world);
runtime.sync();
const root = events.emit(button, 'click'); // the child has no rows
events.emitBubbled(panel, root); // the interaction layer bubbles
expect(calls.map((c) => c.arg)).toEqual(['from-panel']);
});
it('picks up rows authored after the last sync only once re-synced', () => {
const world = makeWorld();
const button = world.spawn('Button');
const { events, runtime } = makeRuntime(world);
runtime.sync(); // nothing authored yet
bind(world, button, { event: 'click', action: 'test.record' });
events.emit(button, 'click');
expect(calls).toHaveLength(0);
runtime.sync(); // the per-frame pass the plugin runs
events.emit(button, 'click');
expect(calls).toHaveLength(1);
});
it('stops dispatching after dispose', () => {
const world = makeWorld();
const button = world.spawn('Button');
bind(world, button, { event: 'click', action: 'test.record' });
const { events, runtime } = makeRuntime(world);
runtime.sync();
runtime.dispose();
events.emit(button, 'click');
expect(calls).toHaveLength(0);
});
it('survives an unknown action / missing target without throwing', () => {
const world = makeWorld();
const button = world.spawn('Button');
bind(
world,
button,
{ event: 'click', action: 'no.such.action' },
{ event: 'click', action: 'test.record', target: 'Ghost' },
);
const { events, runtime } = makeRuntime(world);
runtime.sync();
expect(() => events.emit(button, 'click')).not.toThrow();
expect(calls).toHaveLength(0);
});
});
describe('declared parameters', () => {
beforeEach(() => {
aiRegistry.registerAction('test.pair', {
params: [{ name: 'left', type: 'string' }, { name: 'right', type: 'string' }],
run: (ctx, _bb, arg, params) => { calls.push({ entity: ctx.entity, arg, params }); },
});
});
it('a row authored as params reaches the action as params AND as the canonical string', () => {
const world = makeWorld();
const button = world.spawn('Button');
bind(world, button, { event: 'click', action: 'test.pair', params: { left: 'a', right: 'b' } });
const { events, runtime } = makeRuntime(world);
runtime.sync();
events.emit(button, 'click');
expect(calls[0]!.arg).toBe('a:b');
expect(calls[0]!.params).toEqual({ left: 'a', right: 'b' });
});
it('a row authored as a string (before the action declared params) still runs', () => {
const world = makeWorld();
const button = world.spawn('Button');
bind(world, button, { event: 'click', action: 'test.pair', arg: 'a:b' });
const { events, runtime } = makeRuntime(world);
runtime.sync();
events.emit(button, 'click');
expect(calls[0]!.params).toEqual({ left: 'a', right: 'b' });
});
});
describe('the actions events unlock', () => {
it('fsm.fire raises a trigger on the target blackboard', () => {
ensureEventBindingActions();
const world = makeWorld();
const root = world.spawn('Root');
const button = world.spawn('Button');
const hero = world.spawn('Hero');
world.parent(button, root);
world.parent(hero, root);
bind(world, button, { event: 'click', action: 'fsm.fire', arg: 'start', target: 'Hero' });
const { events, runtime, boards } = makeRuntime(world);
runtime.sync();
events.emit(button, 'click');
expect(boards.get(hero)?.isFired('start')).toBe(true);
});
it('blackboard.set parses JSON values, keeps bare words', () => {
ensureEventBindingActions();
const world = makeWorld();
const button = world.spawn('Button');
bind(
world,
button,
{ event: 'click', action: 'blackboard.set', arg: 'lives=3' },
{ event: 'click', action: 'blackboard.set', arg: 'mode=hard' },
);
const { events, runtime, boards } = makeRuntime(world);
runtime.sync();
events.emit(button, 'click');
expect(boards.get(button)?.get('lives')).toBe(3);
expect(boards.get(button)?.get('mode')).toBe('hard');
});
});