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.

feat(ui): add behavior systems and UIBehaviorPlugin

esengine69db0a46d7dc
diff --git a/sdk/src/ui2/behavior/systems.ts b/sdk/src/ui2/behavior/systems.ts
new file mode 100644
index 000000000..7adf279c2
--- /dev/null
+++ b/sdk/src/ui2/behavior/systems.ts
@@ -0,0 +1,140 @@
+import { defineSystem, type SystemDef } from '../../system';
+import { Transform, type TransformData } from '../../component';
+import type { World } from '../../world';
+
+import { Interactable, UIInteraction, type InteractableData, type UIInteractionData } from './interactable';
+import { StateMachine, type StateMachineData } from './state-machine';
+import {
+ StateVisuals,
+ TransitionFlag,
+ STATE_VISUALS_SLOT_COUNT,
+ type StateVisualsData,
+} from './state-visuals';
+import { UIRenderer, type UIRendererData } from '../core/ui-renderer';
+import { UIEventType, type UIEventQueue } from '../core/events';
+
+/**
+ * State names that the interactable driver owns. If StateMachine.current
+ * holds any other value, it was set by user code (e.g. "loading") and
+ * the driver must not overwrite it.
+ */
+const DRIVER_OWNED_STATES: ReadonlySet<string> = new Set([
+ '', 'normal', 'hover', 'pressed', 'disabled',
+]);
+
+/**
+ * Pure derivation: choose the state a hit-test pass implies.
+ * Extracted so unit tests can cover the branching without a World.
+ */
+export function driverStateFor(
+ enabled: boolean,
+ interaction: UIInteractionData | null,
+): string {
+ if (!enabled) return 'disabled';
+ if (interaction?.pressed) return 'pressed';
+ if (interaction?.hovered) return 'hover';
+ return 'normal';
+}
+
+/**
+ * Pure lookup: index of the StateVisuals slot whose name matches `state`.
+ * Returns -1 if no slot matches (caller should skip applying visuals).
+ */
+export function findStateSlot(sv: StateVisualsData, state: string): number {
+ if (state === '') return -1;
+ const record = sv as unknown as Record<string, unknown>;
+ for (let i = 0; i < STATE_VISUALS_SLOT_COUNT; i++) {
+ if (record[`slot${i}Name`] === state) return i;
+ }
+ return -1;
+}
+
+/**
+ * Writes StateMachine.current based on Interactable + UIInteraction.
+ * Leaves user-managed states (anything outside DRIVER_OWNED_STATES) alone.
+ */
+export function createInteractableDriverSystem(world: World): SystemDef {
+ return defineSystem([], () => {
+ const entities = world.getEntitiesWithComponents([Interactable, StateMachine]);
+ for (const e of entities) {
+ const sm = world.get(e, StateMachine) as StateMachineData;
+ if (!DRIVER_OWNED_STATES.has(sm.current)) continue;
+
+ const inter = world.has(e, UIInteraction)
+ ? (world.get(e, UIInteraction) as UIInteractionData)
+ : null;
+ const interactable = world.get(e, Interactable) as InteractableData;
+ const next = driverStateFor(interactable.enabled, inter);
+ if (next !== sm.current) {
+ sm.current = next;
+ world.insert(e, StateMachine, sm);
+ }
+ }
+ }, { name: 'InteractableDriverSystem' });
+}
+
+/**
+ * Emits a `state_changed` event on every StateMachine whose `current`
+ * differs from `previous`, then advances `previous` to match.
+ */
+export function createStateMachineDiffSystem(
+ world: World,
+ events: UIEventQueue,
+): SystemDef {
+ return defineSystem([], () => {
+ const entities = world.getEntitiesWithComponents([StateMachine]);
+ for (const e of entities) {
+ const sm = world.get(e, StateMachine) as StateMachineData;
+ if (sm.current === sm.previous) continue;
+ events.emit(e, UIEventType.StateChanged, {
+ from: sm.previous,
+ to: sm.current,
+ });
+ sm.previous = sm.current;
+ world.insert(e, StateMachine, sm);
+ }
+ }, { name: 'StateMachineDiffSystem' });
+}
+
+/**
+ * Reads StateMachine.current, looks up the matching StateVisuals slot,
+ * and applies the selected visual dimensions (color / sprite / scale)
+ * to the targetGraphic entity (or the owning entity when unset).
+ *
+ * `fadeDuration` is currently ignored — changes snap. Continuous fading
+ * will be layered on in a later iteration.
+ */
+export function createStateVisualsApplySystem(world: World): SystemDef {
+ return defineSystem([], () => {
+ const entities = world.getEntitiesWithComponents([StateMachine, StateVisuals]);
+ for (const e of entities) {
+ const sm = world.get(e, StateMachine) as StateMachineData;
+ const sv = world.get(e, StateVisuals) as StateVisualsData;
+ const slot = findStateSlot(sv, sm.current);
+ if (slot < 0) continue;
+
+ const target = sv.targetGraphic !== 0 ? sv.targetGraphic : e;
+ const flags = sv.transitionFlags;
+ const record = sv as unknown as Record<string, unknown>;
+
+ if ((flags & TransitionFlag.ColorTint) && world.has(target, UIRenderer)) {
+ const r = world.get(target, UIRenderer) as UIRendererData;
+ r.color = record[`slot${slot}Color`] as UIRendererData['color'];
+ world.insert(target, UIRenderer, r);
+ }
+
+ if ((flags & TransitionFlag.SpriteSwap) && world.has(target, UIRenderer)) {
+ const r = world.get(target, UIRenderer) as UIRendererData;
+ r.texture = record[`slot${slot}Sprite`] as number;
+ world.insert(target, UIRenderer, r);
+ }
+
+ if ((flags & TransitionFlag.Scale) && world.has(target, Transform)) {
+ const t = world.get(target, Transform) as TransformData;
+ const s = record[`slot${slot}Scale`] as number;
+ t.scale = { x: s, y: s, z: 1 };
+ world.insert(target, Transform, t);
+ }
+ }
+ }, { name: 'StateVisualsApplySystem' });
+}
diff --git a/sdk/src/ui2/core/events.ts b/sdk/src/ui2/core/events.ts
index cf29e4971..d3668727f 100644
--- a/sdk/src/ui2/core/events.ts
+++ b/sdk/src/ui2/core/events.ts
@@ -1,3 +1,4 @@
+import { defineResource } from '../../resource';
import type { Entity } from '../../types';
/**
@@ -267,3 +268,9 @@ export class UIEventQueue {
}
}
}
+
+/**
+ * Shared UIEventQueue resource. A plugin inserts the authoritative
+ * instance on startup; systems access it via `Res(UIEventBus)`.
+ */
+export const UIEventBus = defineResource<UIEventQueue>(new UIEventQueue(), 'UIEventBus');
diff --git a/sdk/src/ui2/index.ts b/sdk/src/ui2/index.ts
index a8a9db41a..957248ce6 100644
--- a/sdk/src/ui2/index.ts
+++ b/sdk/src/ui2/index.ts
@@ -3,6 +3,7 @@
export {
UIEventQueue,
UIEventType,
+ UIEventBus,
type UIEvent,
type UIEventHandler,
type Unsubscribe,
@@ -95,3 +96,13 @@ export {
type DraggableData,
type DragStateData,
} from './behavior/draggable';
+
+export {
+ driverStateFor,
+ findStateSlot,
+ createInteractableDriverSystem,
+ createStateMachineDiffSystem,
+ createStateVisualsApplySystem,
+} from './behavior/systems';
+
+export { UIBehaviorPlugin, uiBehaviorPlugin } from './plugin';
diff --git a/sdk/src/ui2/plugin.ts b/sdk/src/ui2/plugin.ts
new file mode 100644
index 000000000..4915c91fa
--- /dev/null
+++ b/sdk/src/ui2/plugin.ts
@@ -0,0 +1,54 @@
+import type { App, Plugin } from '../app';
+import { Schedule } from '../system';
+
+import { UIEventBus, UIEventQueue } from './core/events';
+import {
+ createInteractableDriverSystem,
+ createStateMachineDiffSystem,
+ createStateVisualsApplySystem,
+} from './behavior/systems';
+
+/**
+ * Wires the Layer 2 behavior systems — interactable-driven state machine
+ * diffing and state-visual application — and owns the shared event bus.
+ *
+ * Depends on the existing hit-test system to have written UIInteraction
+ * during PreUpdate; these systems run in Update and react to that data.
+ */
+export class UIBehaviorPlugin implements Plugin {
+ name = 'uiBehavior';
+
+ private events_: UIEventQueue | null = null;
+
+ /** The authoritative event queue for this app instance. */
+ get events(): UIEventQueue {
+ if (!this.events_) {
+ throw new Error('UIBehaviorPlugin.events accessed before build()');
+ }
+ return this.events_;
+ }
+
+ build(app: App): void {
+ const events = new UIEventQueue();
+ this.events_ = events;
+ app.insertResource(UIEventBus, events);
+ app.world.onDespawn((entity) => events.removeAll(entity));
+
+ app.addSystemToSchedule(
+ Schedule.Update,
+ createInteractableDriverSystem(app.world),
+ );
+ app.addSystemToSchedule(
+ Schedule.Update,
+ createStateMachineDiffSystem(app.world, events),
+ { runAfter: ['InteractableDriverSystem'] },
+ );
+ app.addSystemToSchedule(
+ Schedule.Update,
+ createStateVisualsApplySystem(app.world),
+ { runAfter: ['StateMachineDiffSystem'] },
+ );
+ }
+}
+
+export const uiBehaviorPlugin = new UIBehaviorPlugin();
diff --git a/sdk/tests/ui2-systems.test.ts b/sdk/tests/ui2-systems.test.ts
new file mode 100644
index 000000000..ead0e28cf
--- /dev/null
+++ b/sdk/tests/ui2-systems.test.ts
@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import {
+ driverStateFor,
+ findStateSlot,
+ TransitionFlag,
+ type StateVisualsData,
+ type UIInteractionData,
+} from '../src/ui2';
+
+const sv = (overrides: Partial<StateVisualsData> = {}): StateVisualsData => ({
+ targetGraphic: 0 as never,
+ transitionFlags: 0,
+ fadeDuration: 0,
+ slot0Name: '', slot0Color: { r: 1, g: 1, b: 1, a: 1 }, slot0Sprite: 0, slot0Scale: 1,
+ slot1Name: '', slot1Color: { r: 1, g: 1, b: 1, a: 1 }, slot1Sprite: 0, slot1Scale: 1,
+ slot2Name: '', slot2Color: { r: 1, g: 1, b: 1, a: 1 }, slot2Sprite: 0, slot2Scale: 1,
+ slot3Name: '', slot3Color: { r: 1, g: 1, b: 1, a: 1 }, slot3Sprite: 0, slot3Scale: 1,
+ slot4Name: '', slot4Color: { r: 1, g: 1, b: 1, a: 1 }, slot4Sprite: 0, slot4Scale: 1,
+ slot5Name: '', slot5Color: { r: 1, g: 1, b: 1, a: 1 }, slot5Sprite: 0, slot5Scale: 1,
+ slot6Name: '', slot6Color: { r: 1, g: 1, b: 1, a: 1 }, slot6Sprite: 0, slot6Scale: 1,
+ slot7Name: '', slot7Color: { r: 1, g: 1, b: 1, a: 1 }, slot7Sprite: 0, slot7Scale: 1,
+ ...overrides,
+});
+
+const inter = (hovered: boolean, pressed: boolean): UIInteractionData => ({
+ hovered, pressed, justPressed: false, justReleased: false,
+});
+
+describe('driverStateFor', () => {
+ it('returns "disabled" when the component is disabled regardless of input', () => {
+ expect(driverStateFor(false, null)).toBe('disabled');
+ expect(driverStateFor(false, inter(true, true))).toBe('disabled');
+ });
+
+ it('returns "pressed" when the pointer is pressing', () => {
+ expect(driverStateFor(true, inter(true, true))).toBe('pressed');
+ expect(driverStateFor(true, inter(false, true))).toBe('pressed');
+ });
+
+ it('returns "hover" when only hovered', () => {
+ expect(driverStateFor(true, inter(true, false))).toBe('hover');
+ });
+
+ it('returns "normal" when idle or no interaction data', () => {
+ expect(driverStateFor(true, inter(false, false))).toBe('normal');
+ expect(driverStateFor(true, null)).toBe('normal');
+ });
+});
+
+describe('findStateSlot', () => {
+ it('returns -1 when state is the empty string', () => {
+ expect(findStateSlot(sv({ slot0Name: 'normal' }), '')).toBe(-1);
+ });
+
+ it('returns the index of the matching slot', () => {
+ const data = sv({
+ slot0Name: 'normal',
+ slot1Name: 'hover',
+ slot2Name: 'pressed',
+ });
+ expect(findStateSlot(data, 'normal')).toBe(0);
+ expect(findStateSlot(data, 'hover')).toBe(1);
+ expect(findStateSlot(data, 'pressed')).toBe(2);
+ });
+
+ it('returns -1 when no slot matches', () => {
+ expect(findStateSlot(sv({ slot0Name: 'normal' }), 'loading')).toBe(-1);
+ });
+
+ it('returns -1 for user-defined states in unused slots (all slots empty)', () => {
+ expect(findStateSlot(sv(), 'any')).toBe(-1);
+ });
+
+ it('returns the first match when names collide', () => {
+ const data = sv({ slot2Name: 'x', slot5Name: 'x' });
+ expect(findStateSlot(data, 'x')).toBe(2);
+ });
+});
+
+describe('TransitionFlag composability', () => {
+ it('composable via bitwise OR', () => {
+ const flags = TransitionFlag.ColorTint | TransitionFlag.Scale;
+ expect(flags & TransitionFlag.ColorTint).toBeTruthy();
+ expect(flags & TransitionFlag.Scale).toBeTruthy();
+ expect(flags & TransitionFlag.SpriteSwap).toBe(0);
+ });
+});