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
feat(ui): add behavior systems and UIBehaviorPlugin
esengine69db0a46d7dc
diff --git a/sdk/src/ui2/behavior/systems.ts b/sdk/src/ui2/behavior/systems.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});