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 StateMachine and StateVisuals components

esengine3b69b0cef990
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index eb55687fa..0db2b070c 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -377,6 +377,59 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
colorFields: ['color'],
animatableFields: ['color.r', 'color.g', 'color.b', 'color.a', 'size.x', 'size.y'],
},
+ StateMachine: {
+ defaults: {
+ current: '',
+ previous: '',
+ },
+ assetFields: [],
+ entityFields: [],
+ colorFields: [],
+ animatableFields: [],
+ },
+ StateVisuals: {
+ defaults: {
+ targetGraphic: 0,
+ 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,
+ },
+ assetFields: [{ field: 'slot0Sprite', type: 'texture' as AssetFieldType }, { field: 'slot1Sprite', type: 'texture' as AssetFieldType }, { field: 'slot2Sprite', type: 'texture' as AssetFieldType }, { field: 'slot3Sprite', type: 'texture' as AssetFieldType }, { field: 'slot4Sprite', type: 'texture' as AssetFieldType }, { field: 'slot5Sprite', type: 'texture' as AssetFieldType }, { field: 'slot6Sprite', type: 'texture' as AssetFieldType }, { field: 'slot7Sprite', type: 'texture' as AssetFieldType }],
+ entityFields: ['targetGraphic'],
+ colorFields: ['slot0Color', 'slot1Color', 'slot2Color', 'slot3Color', 'slot4Color', 'slot5Color', 'slot6Color', 'slot7Color'],
+ animatableFields: [],
+ },
Transform: {
defaults: {
position: { x: 0, y: 0, z: 0 },
diff --git a/sdk/src/ecs/ptrAccessors.generated.ts b/sdk/src/ecs/ptrAccessors.generated.ts
index c993066c6..ee0fe7886 100644
--- a/sdk/src/ecs/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/ptrAccessors.generated.ts
@@ -1077,6 +1077,130 @@ export function createSpriteData(): SpritePtrData {
};
}
+export interface StateVisualsPtrData {
+ transitionFlags: number;
+ fadeDuration: number;
+ slot0Color: Color;
+ slot0Sprite: number;
+ slot0Scale: number;
+ slot1Color: Color;
+ slot1Sprite: number;
+ slot1Scale: number;
+ slot2Color: Color;
+ slot2Sprite: number;
+ slot2Scale: number;
+ slot3Color: Color;
+ slot3Sprite: number;
+ slot3Scale: number;
+ slot4Color: Color;
+ slot4Sprite: number;
+ slot4Scale: number;
+ slot5Color: Color;
+ slot5Sprite: number;
+ slot5Scale: number;
+ slot6Color: Color;
+ slot6Sprite: number;
+ slot6Scale: number;
+ slot7Color: Color;
+ slot7Sprite: number;
+ slot7Scale: number;
+}
+
+export function fillStateVisuals(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, out: StateVisualsPtrData,
+): void {
+ out.transitionFlags = u32[ptr >> 2];
+ out.fadeDuration = f32[(ptr + 4) >> 2];
+ const slot0Color_ = out.slot0Color; slot0Color_.r = f32[(ptr + 8) >> 2]; slot0Color_.g = f32[((ptr + 8) >> 2) + 1]; slot0Color_.b = f32[((ptr + 8) >> 2) + 2]; slot0Color_.a = f32[((ptr + 8) >> 2) + 3];
+ out.slot0Sprite = u32[(ptr + 24) >> 2];
+ out.slot0Scale = f32[(ptr + 28) >> 2];
+ const slot1Color_ = out.slot1Color; slot1Color_.r = f32[(ptr + 32) >> 2]; slot1Color_.g = f32[((ptr + 32) >> 2) + 1]; slot1Color_.b = f32[((ptr + 32) >> 2) + 2]; slot1Color_.a = f32[((ptr + 32) >> 2) + 3];
+ out.slot1Sprite = u32[(ptr + 48) >> 2];
+ out.slot1Scale = f32[(ptr + 52) >> 2];
+ const slot2Color_ = out.slot2Color; slot2Color_.r = f32[(ptr + 56) >> 2]; slot2Color_.g = f32[((ptr + 56) >> 2) + 1]; slot2Color_.b = f32[((ptr + 56) >> 2) + 2]; slot2Color_.a = f32[((ptr + 56) >> 2) + 3];
+ out.slot2Sprite = u32[(ptr + 72) >> 2];
+ out.slot2Scale = f32[(ptr + 76) >> 2];
+ const slot3Color_ = out.slot3Color; slot3Color_.r = f32[(ptr + 80) >> 2]; slot3Color_.g = f32[((ptr + 80) >> 2) + 1]; slot3Color_.b = f32[((ptr + 80) >> 2) + 2]; slot3Color_.a = f32[((ptr + 80) >> 2) + 3];
+ out.slot3Sprite = u32[(ptr + 96) >> 2];
+ out.slot3Scale = f32[(ptr + 100) >> 2];
+ const slot4Color_ = out.slot4Color; slot4Color_.r = f32[(ptr + 104) >> 2]; slot4Color_.g = f32[((ptr + 104) >> 2) + 1]; slot4Color_.b = f32[((ptr + 104) >> 2) + 2]; slot4Color_.a = f32[((ptr + 104) >> 2) + 3];
+ out.slot4Sprite = u32[(ptr + 120) >> 2];
+ out.slot4Scale = f32[(ptr + 124) >> 2];
+ const slot5Color_ = out.slot5Color; slot5Color_.r = f32[(ptr + 128) >> 2]; slot5Color_.g = f32[((ptr + 128) >> 2) + 1]; slot5Color_.b = f32[((ptr + 128) >> 2) + 2]; slot5Color_.a = f32[((ptr + 128) >> 2) + 3];
+ out.slot5Sprite = u32[(ptr + 144) >> 2];
+ out.slot5Scale = f32[(ptr + 148) >> 2];
+ const slot6Color_ = out.slot6Color; slot6Color_.r = f32[(ptr + 152) >> 2]; slot6Color_.g = f32[((ptr + 152) >> 2) + 1]; slot6Color_.b = f32[((ptr + 152) >> 2) + 2]; slot6Color_.a = f32[((ptr + 152) >> 2) + 3];
+ out.slot6Sprite = u32[(ptr + 168) >> 2];
+ out.slot6Scale = f32[(ptr + 172) >> 2];
+ const slot7Color_ = out.slot7Color; slot7Color_.r = f32[(ptr + 176) >> 2]; slot7Color_.g = f32[((ptr + 176) >> 2) + 1]; slot7Color_.b = f32[((ptr + 176) >> 2) + 2]; slot7Color_.a = f32[((ptr + 176) >> 2) + 3];
+ out.slot7Sprite = u32[(ptr + 192) >> 2];
+ out.slot7Scale = f32[(ptr + 196) >> 2];
+}
+
+export function writeStateVisuals(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, data: StateVisualsPtrData,
+): void {
+ u32[ptr >> 2] = data.transitionFlags;
+ f32[(ptr + 4) >> 2] = data.fadeDuration;
+ f32[(ptr + 8) >> 2] = data.slot0Color.r; f32[((ptr + 8) >> 2) + 1] = data.slot0Color.g; f32[((ptr + 8) >> 2) + 2] = data.slot0Color.b; f32[((ptr + 8) >> 2) + 3] = data.slot0Color.a;
+ u32[(ptr + 24) >> 2] = data.slot0Sprite;
+ f32[(ptr + 28) >> 2] = data.slot0Scale;
+ f32[(ptr + 32) >> 2] = data.slot1Color.r; f32[((ptr + 32) >> 2) + 1] = data.slot1Color.g; f32[((ptr + 32) >> 2) + 2] = data.slot1Color.b; f32[((ptr + 32) >> 2) + 3] = data.slot1Color.a;
+ u32[(ptr + 48) >> 2] = data.slot1Sprite;
+ f32[(ptr + 52) >> 2] = data.slot1Scale;
+ f32[(ptr + 56) >> 2] = data.slot2Color.r; f32[((ptr + 56) >> 2) + 1] = data.slot2Color.g; f32[((ptr + 56) >> 2) + 2] = data.slot2Color.b; f32[((ptr + 56) >> 2) + 3] = data.slot2Color.a;
+ u32[(ptr + 72) >> 2] = data.slot2Sprite;
+ f32[(ptr + 76) >> 2] = data.slot2Scale;
+ f32[(ptr + 80) >> 2] = data.slot3Color.r; f32[((ptr + 80) >> 2) + 1] = data.slot3Color.g; f32[((ptr + 80) >> 2) + 2] = data.slot3Color.b; f32[((ptr + 80) >> 2) + 3] = data.slot3Color.a;
+ u32[(ptr + 96) >> 2] = data.slot3Sprite;
+ f32[(ptr + 100) >> 2] = data.slot3Scale;
+ f32[(ptr + 104) >> 2] = data.slot4Color.r; f32[((ptr + 104) >> 2) + 1] = data.slot4Color.g; f32[((ptr + 104) >> 2) + 2] = data.slot4Color.b; f32[((ptr + 104) >> 2) + 3] = data.slot4Color.a;
+ u32[(ptr + 120) >> 2] = data.slot4Sprite;
+ f32[(ptr + 124) >> 2] = data.slot4Scale;
+ f32[(ptr + 128) >> 2] = data.slot5Color.r; f32[((ptr + 128) >> 2) + 1] = data.slot5Color.g; f32[((ptr + 128) >> 2) + 2] = data.slot5Color.b; f32[((ptr + 128) >> 2) + 3] = data.slot5Color.a;
+ u32[(ptr + 144) >> 2] = data.slot5Sprite;
+ f32[(ptr + 148) >> 2] = data.slot5Scale;
+ f32[(ptr + 152) >> 2] = data.slot6Color.r; f32[((ptr + 152) >> 2) + 1] = data.slot6Color.g; f32[((ptr + 152) >> 2) + 2] = data.slot6Color.b; f32[((ptr + 152) >> 2) + 3] = data.slot6Color.a;
+ u32[(ptr + 168) >> 2] = data.slot6Sprite;
+ f32[(ptr + 172) >> 2] = data.slot6Scale;
+ f32[(ptr + 176) >> 2] = data.slot7Color.r; f32[((ptr + 176) >> 2) + 1] = data.slot7Color.g; f32[((ptr + 176) >> 2) + 2] = data.slot7Color.b; f32[((ptr + 176) >> 2) + 3] = data.slot7Color.a;
+ u32[(ptr + 192) >> 2] = data.slot7Sprite;
+ f32[(ptr + 196) >> 2] = data.slot7Scale;
+}
+
+export function createStateVisualsData(): StateVisualsPtrData {
+ return {
+ transitionFlags: 0,
+ fadeDuration: 0,
+ slot0Color: { r: 0, g: 0, b: 0, a: 0 },
+ slot0Sprite: 0,
+ slot0Scale: 0,
+ slot1Color: { r: 0, g: 0, b: 0, a: 0 },
+ slot1Sprite: 0,
+ slot1Scale: 0,
+ slot2Color: { r: 0, g: 0, b: 0, a: 0 },
+ slot2Sprite: 0,
+ slot2Scale: 0,
+ slot3Color: { r: 0, g: 0, b: 0, a: 0 },
+ slot3Sprite: 0,
+ slot3Scale: 0,
+ slot4Color: { r: 0, g: 0, b: 0, a: 0 },
+ slot4Sprite: 0,
+ slot4Scale: 0,
+ slot5Color: { r: 0, g: 0, b: 0, a: 0 },
+ slot5Sprite: 0,
+ slot5Scale: 0,
+ slot6Color: { r: 0, g: 0, b: 0, a: 0 },
+ slot6Sprite: 0,
+ slot6Scale: 0,
+ slot7Color: { r: 0, g: 0, b: 0, a: 0 },
+ slot7Sprite: 0,
+ slot7Scale: 0,
+ };
+}
+
export interface TransformPtrData {
position: Vec3;
rotation: Vec4;
@@ -1335,6 +1459,7 @@ export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {
ShapeRenderer: { fill: fillShapeRenderer, write: writeShapeRenderer, create: createShapeRendererData },
SpineAnimation: { fill: fillSpineAnimation, write: writeSpineAnimation, create: createSpineAnimationData },
Sprite: { fill: fillSprite, write: writeSprite, create: createSpriteData },
+ StateVisuals: { fill: fillStateVisuals, write: writeStateVisuals, create: createStateVisualsData },
Transform: { fill: fillTransform, write: writeTransform, create: createTransformData },
UIInteraction: { fill: fillUIInteraction, write: writeUIInteraction, create: createUIInteractionData },
UIMask: { fill: fillUIMask, write: writeUIMask, create: createUIMaskData },
diff --git a/sdk/src/ptrLayouts.generated.ts b/sdk/src/ptrLayouts.generated.ts
index a51c51f48..747348334 100644
--- a/sdk/src/ptrLayouts.generated.ts
+++ b/sdk/src/ptrLayouts.generated.ts
@@ -285,6 +285,37 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'enabled', type: 'bool', offset: 80 },
],
},
+ StateVisuals: {
+ ptrFn: 'getStateVisualsPtr',
+ fields: [
+ { name: 'transitionFlags', type: 'u32', offset: 0 },
+ { name: 'fadeDuration', type: 'f32', offset: 4 },
+ { name: 'slot0Color', type: 'color', offset: 8 },
+ { name: 'slot0Sprite', type: 'u32', offset: 24 },
+ { name: 'slot0Scale', type: 'f32', offset: 28 },
+ { name: 'slot1Color', type: 'color', offset: 32 },
+ { name: 'slot1Sprite', type: 'u32', offset: 48 },
+ { name: 'slot1Scale', type: 'f32', offset: 52 },
+ { name: 'slot2Color', type: 'color', offset: 56 },
+ { name: 'slot2Sprite', type: 'u32', offset: 72 },
+ { name: 'slot2Scale', type: 'f32', offset: 76 },
+ { name: 'slot3Color', type: 'color', offset: 80 },
+ { name: 'slot3Sprite', type: 'u32', offset: 96 },
+ { name: 'slot3Scale', type: 'f32', offset: 100 },
+ { name: 'slot4Color', type: 'color', offset: 104 },
+ { name: 'slot4Sprite', type: 'u32', offset: 120 },
+ { name: 'slot4Scale', type: 'f32', offset: 124 },
+ { name: 'slot5Color', type: 'color', offset: 128 },
+ { name: 'slot5Sprite', type: 'u32', offset: 144 },
+ { name: 'slot5Scale', type: 'f32', offset: 148 },
+ { name: 'slot6Color', type: 'color', offset: 152 },
+ { name: 'slot6Sprite', type: 'u32', offset: 168 },
+ { name: 'slot6Scale', type: 'f32', offset: 172 },
+ { name: 'slot7Color', type: 'color', offset: 176 },
+ { name: 'slot7Sprite', type: 'u32', offset: 192 },
+ { name: 'slot7Scale', type: 'f32', offset: 196 },
+ ],
+ },
Transform: {
ptrFn: 'getTransformPtr',
fields: [
diff --git a/sdk/src/ui2/behavior/draggable.ts b/sdk/src/ui2/behavior/draggable.ts
new file mode 100644
index 000000000..f8c7f206f
--- /dev/null
+++ b/sdk/src/ui2/behavior/draggable.ts
@@ -0,0 +1,6 @@
+export {
+ Draggable,
+ DragState,
+ type DraggableData,
+ type DragStateData,
+} from '../../ui/Draggable';
diff --git a/sdk/src/ui2/behavior/focusable.ts b/sdk/src/ui2/behavior/focusable.ts
new file mode 100644
index 000000000..4aed82cb8
--- /dev/null
+++ b/sdk/src/ui2/behavior/focusable.ts
@@ -0,0 +1,6 @@
+export {
+ Focusable,
+ FocusManager,
+ FocusManagerState,
+ type FocusableData,
+} from '../../ui/Focusable';
diff --git a/sdk/src/ui2/behavior/interactable.ts b/sdk/src/ui2/behavior/interactable.ts
new file mode 100644
index 000000000..18c078bb9
--- /dev/null
+++ b/sdk/src/ui2/behavior/interactable.ts
@@ -0,0 +1,9 @@
+export {
+ Interactable,
+ type InteractableData,
+} from '../../ui/Interactable';
+
+export {
+ UIInteraction,
+ type UIInteractionData,
+} from '../../ui/UIInteraction';
diff --git a/sdk/src/ui2/behavior/state-machine.ts b/sdk/src/ui2/behavior/state-machine.ts
new file mode 100644
index 000000000..1f1783737
--- /dev/null
+++ b/sdk/src/ui2/behavior/state-machine.ts
@@ -0,0 +1,11 @@
+import { defineBuiltin } from '../../component';
+
+export interface StateMachineData {
+ current: string;
+ previous: string;
+}
+
+export const StateMachine = defineBuiltin<StateMachineData>('StateMachine', {
+ current: '',
+ previous: '',
+});
diff --git a/sdk/src/ui2/behavior/state-visuals.ts b/sdk/src/ui2/behavior/state-visuals.ts
new file mode 100644
index 000000000..e91c13219
--- /dev/null
+++ b/sdk/src/ui2/behavior/state-visuals.ts
@@ -0,0 +1,45 @@
+import { defineBuiltin } from '../../component';
+import type { Color, Entity } from '../../types';
+
+export const TransitionFlag = {
+ None: 0,
+ ColorTint: 1 << 0,
+ SpriteSwap: 1 << 1,
+ Scale: 1 << 2,
+} as const;
+
+export type TransitionFlag = (typeof TransitionFlag)[keyof typeof TransitionFlag];
+
+export const STATE_VISUALS_SLOT_COUNT = 8;
+
+export interface StateVisualsData {
+ targetGraphic: Entity;
+ transitionFlags: number;
+ fadeDuration: number;
+
+ slot0Name: string; slot0Color: Color; slot0Sprite: number; slot0Scale: number;
+ slot1Name: string; slot1Color: Color; slot1Sprite: number; slot1Scale: number;
+ slot2Name: string; slot2Color: Color; slot2Sprite: number; slot2Scale: number;
+ slot3Name: string; slot3Color: Color; slot3Sprite: number; slot3Scale: number;
+ slot4Name: string; slot4Color: Color; slot4Sprite: number; slot4Scale: number;
+ slot5Name: string; slot5Color: Color; slot5Sprite: number; slot5Scale: number;
+ slot6Name: string; slot6Color: Color; slot6Sprite: number; slot6Scale: number;
+ slot7Name: string; slot7Color: Color; slot7Sprite: number; slot7Scale: number;
+}
+
+const WHITE = (): Color => ({ r: 1, g: 1, b: 1, a: 1 });
+
+export const StateVisuals = defineBuiltin<StateVisualsData>('StateVisuals', {
+ targetGraphic: 0 as Entity,
+ transitionFlags: 0,
+ fadeDuration: 0,
+
+ slot0Name: '', slot0Color: WHITE(), slot0Sprite: 0, slot0Scale: 1,
+ slot1Name: '', slot1Color: WHITE(), slot1Sprite: 0, slot1Scale: 1,
+ slot2Name: '', slot2Color: WHITE(), slot2Sprite: 0, slot2Scale: 1,
+ slot3Name: '', slot3Color: WHITE(), slot3Sprite: 0, slot3Scale: 1,
+ slot4Name: '', slot4Color: WHITE(), slot4Sprite: 0, slot4Scale: 1,
+ slot5Name: '', slot5Color: WHITE(), slot5Sprite: 0, slot5Scale: 1,
+ slot6Name: '', slot6Color: WHITE(), slot6Sprite: 0, slot6Scale: 1,
+ slot7Name: '', slot7Color: WHITE(), slot7Sprite: 0, slot7Scale: 1,
+});
diff --git a/sdk/src/ui2/index.ts b/sdk/src/ui2/index.ts
index 77a8d561d..a8a9db41a 100644
--- a/sdk/src/ui2/index.ts
+++ b/sdk/src/ui2/index.ts
@@ -60,3 +60,38 @@ export {
GridLayoutDirection,
type GridLayoutData,
} from './layout/grid';
+
+// Layer 2 — Behaviors
+
+export {
+ Interactable,
+ UIInteraction,
+ type InteractableData,
+ type UIInteractionData,
+} from './behavior/interactable';
+
+export {
+ StateMachine,
+ type StateMachineData,
+} from './behavior/state-machine';
+
+export {
+ StateVisuals,
+ TransitionFlag,
+ STATE_VISUALS_SLOT_COUNT,
+ type StateVisualsData,
+} from './behavior/state-visuals';
+
+export {
+ Focusable,
+ FocusManager,
+ FocusManagerState,
+ type FocusableData,
+} from './behavior/focusable';
+
+export {
+ Draggable,
+ DragState,
+ type DraggableData,
+ type DragStateData,
+} from './behavior/draggable';
diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.ts
index 54303a307..2af47760c 100644
--- a/sdk/src/wasm.generated.ts
+++ b/sdk/src/wasm.generated.ts
@@ -394,6 +394,49 @@ export interface Sprite {
enabled: boolean;
}
+export interface StateMachine {
+ current: string;
+ previous: string;
+}
+
+export interface StateVisuals {
+ targetGraphic: number;
+ transitionFlags: number;
+ fadeDuration: number;
+ slot0Name: string;
+ slot0Color: Vec4;
+ slot0Sprite: number;
+ slot0Scale: number;
+ slot1Name: string;
+ slot1Color: Vec4;
+ slot1Sprite: number;
+ slot1Scale: number;
+ slot2Name: string;
+ slot2Color: Vec4;
+ slot2Sprite: number;
+ slot2Scale: number;
+ slot3Name: string;
+ slot3Color: Vec4;
+ slot3Sprite: number;
+ slot3Scale: number;
+ slot4Name: string;
+ slot4Color: Vec4;
+ slot4Sprite: number;
+ slot4Scale: number;
+ slot5Name: string;
+ slot5Color: Vec4;
+ slot5Sprite: number;
+ slot5Scale: number;
+ slot6Name: string;
+ slot6Color: Vec4;
+ slot6Sprite: number;
+ slot6Scale: number;
+ slot7Name: string;
+ slot7Color: Vec4;
+ slot7Sprite: number;
+ slot7Scale: number;
+}
+
export interface Transform {
position: Vec3;
rotation: Quat;
@@ -535,6 +578,14 @@ export interface Registry {
getSprite(entity: Entity): Sprite;
addSprite(entity: Entity, component: Sprite): void;
removeSprite(entity: Entity): void;
+ hasStateMachine(entity: Entity): boolean;
+ getStateMachine(entity: Entity): StateMachine;
+ addStateMachine(entity: Entity, component: StateMachine): void;
+ removeStateMachine(entity: Entity): void;
+ hasStateVisuals(entity: Entity): boolean;
+ getStateVisuals(entity: Entity): StateVisuals;
+ addStateVisuals(entity: Entity, component: StateVisuals): void;
+ removeStateVisuals(entity: Entity): void;
hasTransform(entity: Entity): boolean;
getTransform(entity: Entity): Transform;
addTransform(entity: Entity, component: Transform): void;
@@ -589,6 +640,8 @@ export interface ESEngineModule {
ShapeRenderer: new () => ShapeRenderer;
SpineAnimation: new () => SpineAnimation;
Sprite: new () => Sprite;
+ StateMachine: new () => StateMachine;
+ StateVisuals: new () => StateVisuals;
Transform: new () => Transform;
UIInteraction: new () => UIInteraction;
UIMask: new () => UIMask;
diff --git a/sdk/tests/ui2-behavior.test.ts b/sdk/tests/ui2-behavior.test.ts
new file mode 100644
index 000000000..72972a414
--- /dev/null
+++ b/sdk/tests/ui2-behavior.test.ts
@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import {
+ StateMachine,
+ StateVisuals,
+ TransitionFlag,
+ STATE_VISUALS_SLOT_COUNT,
+ Interactable,
+ UIInteraction,
+ Focusable,
+ Draggable,
+} from '../src/ui2';
+
+describe('ui2 behavior components', () => {
+ describe('StateMachine', () => {
+ it('registers as a builtin named "StateMachine"', () => {
+ expect(StateMachine._builtin).toBe(true);
+ expect(StateMachine._name).toBe('StateMachine');
+ });
+
+ it('defaults to empty current and previous', () => {
+ expect(StateMachine._default).toEqual({ current: '', previous: '' });
+ });
+ });
+
+ describe('StateVisuals', () => {
+ it('registers as a builtin named "StateVisuals"', () => {
+ expect(StateVisuals._builtin).toBe(true);
+ expect(StateVisuals._name).toBe('StateVisuals');
+ });
+
+ it('exposes exactly 8 slots', () => {
+ expect(STATE_VISUALS_SLOT_COUNT).toBe(8);
+ const d = StateVisuals._default as Record<string, unknown>;
+ for (let i = 0; i < 8; i++) {
+ expect(d[`slot${i}Name`]).toBe('');
+ expect(d[`slot${i}Color`]).toEqual({ r: 1, g: 1, b: 1, a: 1 });
+ expect(d[`slot${i}Sprite`]).toBe(0);
+ expect(d[`slot${i}Scale`]).toBe(1);
+ }
+ });
+
+ it('declares targetGraphic as an entity reference for serialization', () => {
+ // EHT populates entityFields from ES_PROPERTY(entity_ref)
+ expect(StateVisuals.entityFields).toContain('targetGraphic');
+ });
+
+ it('declares each slot color for editor color-picker detection', () => {
+ for (let i = 0; i < 8; i++) {
+ expect(StateVisuals.colorKeys).toContain(`slot${i}Color`);
+ }
+ });
+
+ it('declares each slot sprite as a texture asset field', () => {
+ const fields = StateVisuals.assetFields.map((f) => f.field);
+ for (let i = 0; i < 8; i++) {
+ expect(fields).toContain(`slot${i}Sprite`);
+ }
+ });
+ });
+
+ describe('TransitionFlag', () => {
+ it('defines composable bitmask values', () => {
+ expect(TransitionFlag.None).toBe(0);
+ expect(TransitionFlag.ColorTint).toBe(1);
+ expect(TransitionFlag.SpriteSwap).toBe(2);
+ expect(TransitionFlag.Scale).toBe(4);
+
+ const combined = TransitionFlag.ColorTint | TransitionFlag.Scale;
+ expect(combined & TransitionFlag.ColorTint).toBeTruthy();
+ expect(combined & TransitionFlag.Scale).toBeTruthy();
+ expect(combined & TransitionFlag.SpriteSwap).toBeFalsy();
+ });
+ });
+
+ describe('re-exported behaviors', () => {
+ it('Interactable points at the existing builtin', () => {
+ expect(Interactable._builtin).toBe(true);
+ expect(Interactable._name).toBe('Interactable');
+ });
+
+ it('UIInteraction points at the existing builtin', () => {
+ expect(UIInteraction._builtin).toBe(true);
+ expect(UIInteraction._name).toBe('UIInteraction');
+ });
+
+ it('Focusable is a user component (ts-side)', () => {
+ expect(Focusable._builtin).toBe(false);
+ expect(Focusable._name).toBe('Focusable');
+ });
+
+ it('Draggable is a user component (ts-side)', () => {
+ expect(Draggable._builtin).toBe(false);
+ expect(Draggable._name).toBe('Draggable');
+ });
+ });
+});
diff --git a/sdk/wasm.generated.ts b/sdk/wasm.generated.ts
index 54303a307..2af47760c 100644
--- a/sdk/wasm.generated.ts
+++ b/sdk/wasm.generated.ts
@@ -394,6 +394,49 @@ export interface Sprite {
enabled: boolean;
}
+export interface StateMachine {
+ current: string;
+ previous: string;
+}
+
+export interface StateVisuals {
+ targetGraphic: number;
+ transitionFlags: number;
+ fadeDuration: number;
+ slot0Name: string;
+ slot0Color: Vec4;
+ slot0Sprite: number;
+ slot0Scale: number;
+ slot1Name: string;
+ slot1Color: Vec4;
+ slot1Sprite: number;
+ slot1Scale: number;
+ slot2Name: string;
+ slot2Color: Vec4;
+ slot2Sprite: number;
+ slot2Scale: number;
+ slot3Name: string;
+ slot3Color: Vec4;
+ slot3Sprite: number;
+ slot3Scale: number;
+ slot4Name: string;
+ slot4Color: Vec4;
+ slot4Sprite: number;
+ slot4Scale: number;
+ slot5Name: string;
+ slot5Color: Vec4;
+ slot5Sprite: number;
+ slot5Scale: number;
+ slot6Name: string;
+ slot6Color: Vec4;
+ slot6Sprite: number;
+ slot6Scale: number;
+ slot7Name: string;
+ slot7Color: Vec4;
+ slot7Sprite: number;
+ slot7Scale: number;
+}
+
export interface Transform {
position: Vec3;
rotation: Quat;
@@ -535,6 +578,14 @@ export interface Registry {
getSprite(entity: Entity): Sprite;
addSprite(entity: Entity, component: Sprite): void;
removeSprite(entity: Entity): void;
+ hasStateMachine(entity: Entity): boolean;
+ getStateMachine(entity: Entity): StateMachine;
+ addStateMachine(entity: Entity, component: StateMachine): void;
+ removeStateMachine(entity: Entity): void;
+ hasStateVisuals(entity: Entity): boolean;
+ getStateVisuals(entity: Entity): StateVisuals;
+ addStateVisuals(entity: Entity, component: StateVisuals): void;
+ removeStateVisuals(entity: Entity): void;
hasTransform(entity: Entity): boolean;
getTransform(entity: Entity): Transform;
addTransform(entity: Entity, component: Transform): void;
@@ -589,6 +640,8 @@ export interface ESEngineModule {
ShapeRenderer: new () => ShapeRenderer;
SpineAnimation: new () => SpineAnimation;
Sprite: new () => Sprite;
+ StateMachine: new () => StateMachine;
+ StateVisuals: new () => StateVisuals;
Transform: new () => Transform;
UIInteraction: new () => UIInteraction;
UIMask: new () => UIMask;
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 9e0b972ee..deb8e2780 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -28,6 +28,8 @@
#include "../ecs/components/ShapeRenderer.hpp"
#include "../ecs/components/SpineAnimation.hpp"
#include "../ecs/components/Sprite.hpp"
+#include "../ecs/components/StateMachine.hpp"
+#include "../ecs/components/StateVisuals.hpp"
#include "../ecs/components/Transform.hpp"
#include "../ecs/components/UIInteraction.hpp"
#include "../ecs/components/UIMask.hpp"
@@ -74,6 +76,8 @@ std::vector<std::string> editor_getComponentNames() {
"ShapeRenderer",
"SpineAnimation",
"Sprite",
+ "StateMachine",
+ "StateVisuals",
"Transform",
"UIInteraction",
"UIMask",
@@ -383,6 +387,73 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"material","type":"asset","group":"Sprite"},
{"key":"enabled","type":"bool","group":"Sprite"}
])JSON";
+ } else if (name == "StateMachine") {
+ return R"JSON([
+ {"key":"current","type":"string","group":"StateMachine"},
+ {"key":"previous","type":"string","group":"StateMachine"}
+ ])JSON";
+ } else if (name == "StateVisuals") {
+ return R"JSON([
+ {"key":"targetGraphic","type":"entity","group":"StateVisuals"},
+ {"key":"transitionFlags","type":"int","group":"StateVisuals"},
+ {"key":"fadeDuration","type":"float","group":"StateVisuals"},
+ {"key":"slot0Name","type":"string","group":"StateVisuals"},
+ {"key":"slot0Color.r","type":"color","group":"StateVisuals"},
+ {"key":"slot0Color.g","type":"color","group":"StateVisuals"},
+ {"key":"slot0Color.b","type":"color","group":"StateVisuals"},
+ {"key":"slot0Color.a","type":"color","group":"StateVisuals"},
+ {"key":"slot0Sprite","type":"asset","group":"StateVisuals"},
+ {"key":"slot0Scale","type":"float","group":"StateVisuals"},
+ {"key":"slot1Name","type":"string","group":"StateVisuals"},
+ {"key":"slot1Color.r","type":"color","group":"StateVisuals"},
+ {"key":"slot1Color.g","type":"color","group":"StateVisuals"},
+ {"key":"slot1Color.b","type":"color","group":"StateVisuals"},
+ {"key":"slot1Color.a","type":"color","group":"StateVisuals"},
+ {"key":"slot1Sprite","type":"asset","group":"StateVisuals"},
+ {"key":"slot1Scale","type":"float","group":"StateVisuals"},
+ {"key":"slot2Name","type":"string","group":"StateVisuals"},
+ {"key":"slot2Color.r","type":"color","group":"StateVisuals"},
+ {"key":"slot2Color.g","type":"color","group":"StateVisuals"},
+ {"key":"slot2Color.b","type":"color","group":"StateVisuals"},
+ {"key":"slot2Color.a","type":"color","group":"StateVisuals"},
+ {"key":"slot2Sprite","type":"asset","group":"StateVisuals"},
+ {"key":"slot2Scale","type":"float","group":"StateVisuals"},
+ {"key":"slot3Name","type":"string","group":"StateVisuals"},
+ {"key":"slot3Color.r","type":"color","group":"StateVisuals"},
+ {"key":"slot3Color.g","type":"color","group":"StateVisuals"},
+ {"key":"slot3Color.b","type":"color","group":"StateVisuals"},
+ {"key":"slot3Color.a","type":"color","group":"StateVisuals"},
+ {"key":"slot3Sprite","type":"asset","group":"StateVisuals"},
+ {"key":"slot3Scale","type":"float","group":"StateVisuals"},
+ {"key":"slot4Name","type":"string","group":"StateVisuals"},
+ {"key":"slot4Color.r","type":"color","group":"StateVisuals"},
+ {"key":"slot4Color.g","type":"color","group":"StateVisuals"},
+ {"key":"slot4Color.b","type":"color","group":"StateVisuals"},
+ {"key":"slot4Color.a","type":"color","group":"StateVisuals"},
+ {"key":"slot4Sprite","type":"asset","group":"StateVisuals"},
+ {"key":"slot4Scale","type":"float","group":"StateVisuals"},
+ {"key":"slot5Name","type":"string","group":"StateVisuals"},
+ {"key":"slot5Color.r","type":"color","group":"StateVisuals"},
+ {"key":"slot5Color.g","type":"color","group":"StateVisuals"},
+ {"key":"slot5Color.b","type":"color","group":"StateVisuals"},
+ {"key":"slot5Color.a","type":"color","group":"StateVisuals"},
+ {"key":"slot5Sprite","type":"asset","group":"StateVisuals"},
+ {"key":"slot5Scale","type":"float","group":"StateVisuals"},
+ {"key":"slot6Name","type":"string","group":"StateVisuals"},
+ {"key":"slot6Color.r","type":"color","group":"StateVisuals"},
+ {"key":"slot6Color.g","type":"color","group":"StateVisuals"},
+ {"key":"slot6Color.b","type":"color","group":"StateVisuals"},
+ {"key":"slot6Color.a","type":"color","group":"StateVisuals"},
+ {"key":"slot6Sprite","type":"asset","group":"StateVisuals"},
+ {"key":"slot6Scale","type":"float","group":"StateVisuals"},
+ {"key":"slot7Name","type":"string","group":"StateVisuals"},
+ {"key":"slot7Color.r","type":"color","group":"StateVisuals"},
+ {"key":"slot7Color.g","type":"color","group":"StateVisuals"},
+ {"key":"slot7Color.b","type":"color","group":"StateVisuals"},
+ {"key":"slot7Color.a","type":"color","group":"StateVisuals"},
+ {"key":"slot7Sprite","type":"asset","group":"StateVisuals"},
+ {"key":"slot7Scale","type":"float","group":"StateVisuals"}
+ ])JSON";
} else if (name == "Transform") {
return R"JSON([
{"key":"position.x","type":"float","group":"Transform"},
@@ -522,6 +593,12 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {
} else if (name == "Sprite") {
if (!reg.has<esengine::ecs::Sprite>(entity)) reg.emplace<esengine::ecs::Sprite>(entity);
return true;
+ } else if (name == "StateMachine") {
+ if (!reg.has<esengine::ecs::StateMachine>(entity)) reg.emplace<esengine::ecs::StateMachine>(entity);
+ return true;
+ } else if (name == "StateVisuals") {
+ if (!reg.has<esengine::ecs::StateVisuals>(entity)) reg.emplace<esengine::ecs::StateVisuals>(entity);
+ return true;
} else if (name == "Transform") {
if (!reg.has<esengine::ecs::Transform>(entity)) reg.emplace<esengine::ecs::Transform>(entity);
return true;
@@ -589,6 +666,10 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {
if (reg.has<esengine::ecs::SpineAnimation>(entity)) { reg.remove<esengine::ecs::SpineAnimation>(entity); return true; }
} else if (name == "Sprite") {
if (reg.has<esengine::ecs::Sprite>(entity)) { reg.remove<esengine::ecs::Sprite>(entity); return true; }
+ } else if (name == "StateMachine") {
+ if (reg.has<esengine::ecs::StateMachine>(entity)) { reg.remove<esengine::ecs::StateMachine>(entity); return true; }
+ } else if (name == "StateVisuals") {
+ if (reg.has<esengine::ecs::StateVisuals>(entity)) { reg.remove<esengine::ecs::StateVisuals>(entity); return true; }
} else if (name == "Transform") {
if (reg.has<esengine::ecs::Transform>(entity)) { reg.remove<esengine::ecs::Transform>(entity); return true; }
} else if (name == "UIInteraction") {
@@ -629,6 +710,8 @@ bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {
if (name == "ShapeRenderer") return reg.has<esengine::ecs::ShapeRenderer>(entity);
if (name == "SpineAnimation") return reg.has<esengine::ecs::SpineAnimation>(entity);
if (name == "Sprite") return reg.has<esengine::ecs::Sprite>(entity);
+ if (name == "StateMachine") return reg.has<esengine::ecs::StateMachine>(entity);
+ if (name == "StateVisuals") return reg.has<esengine::ecs::StateVisuals>(entity);
if (name == "Transform") return reg.has<esengine::ecs::Transform>(entity);
if (name == "UIInteraction") return reg.has<esengine::ecs::UIInteraction>(entity);
if (name == "UIMask") return reg.has<esengine::ecs::UIMask>(entity);
@@ -665,6 +748,8 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {
if (reg.has<esengine::ecs::ShapeRenderer>(entity)) result.push_back("ShapeRenderer");
if (reg.has<esengine::ecs::SpineAnimation>(entity)) result.push_back("SpineAnimation");
if (reg.has<esengine::ecs::Sprite>(entity)) result.push_back("Sprite");
+ if (reg.has<esengine::ecs::StateMachine>(entity)) result.push_back("StateMachine");
+ if (reg.has<esengine::ecs::StateVisuals>(entity)) result.push_back("StateVisuals");
if (reg.has<esengine::ecs::Transform>(entity)) result.push_back("Transform");
if (reg.has<esengine::ecs::UIInteraction>(entity)) result.push_back("UIInteraction");
if (reg.has<esengine::ecs::UIMask>(entity)) result.push_back("UIMask");
@@ -910,6 +995,52 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "tileSpacing.y") { c.tileSpacing.y = value; }
else { return false; }
return true;
+ } else if (comp == "StateVisuals") {
+ if (!reg.has<esengine::ecs::StateVisuals>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::StateVisuals>(entity);
+ if (field == "fadeDuration") { c.fadeDuration = value; }
+ else if (field == "slot0Color.r") { c.slot0Color.r = value; }
+ else if (field == "slot0Color.g") { c.slot0Color.g = value; }
+ else if (field == "slot0Color.b") { c.slot0Color.b = value; }
+ else if (field == "slot0Color.a") { c.slot0Color.a = value; }
+ else if (field == "slot0Scale") { c.slot0Scale = value; }
+ else if (field == "slot1Color.r") { c.slot1Color.r = value; }
+ else if (field == "slot1Color.g") { c.slot1Color.g = value; }
+ else if (field == "slot1Color.b") { c.slot1Color.b = value; }
+ else if (field == "slot1Color.a") { c.slot1Color.a = value; }
+ else if (field == "slot1Scale") { c.slot1Scale = value; }
+ else if (field == "slot2Color.r") { c.slot2Color.r = value; }
+ else if (field == "slot2Color.g") { c.slot2Color.g = value; }
+ else if (field == "slot2Color.b") { c.slot2Color.b = value; }
+ else if (field == "slot2Color.a") { c.slot2Color.a = value; }
+ else if (field == "slot2Scale") { c.slot2Scale = value; }
+ else if (field == "slot3Color.r") { c.slot3Color.r = value; }
+ else if (field == "slot3Color.g") { c.slot3Color.g = value; }
+ else if (field == "slot3Color.b") { c.slot3Color.b = value; }
+ else if (field == "slot3Color.a") { c.slot3Color.a = value; }
+ else if (field == "slot3Scale") { c.slot3Scale = value; }
+ else if (field == "slot4Color.r") { c.slot4Color.r = value; }
+ else if (field == "slot4Color.g") { c.slot4Color.g = value; }
+ else if (field == "slot4Color.b") { c.slot4Color.b = value; }
+ else if (field == "slot4Color.a") { c.slot4Color.a = value; }
+ else if (field == "slot4Scale") { c.slot4Scale = value; }
+ else if (field == "slot5Color.r") { c.slot5Color.r = value; }
+ else if (field == "slot5Color.g") { c.slot5Color.g = value; }
+ else if (field == "slot5Color.b") { c.slot5Color.b = value; }
+ else if (field == "slot5Color.a") { c.slot5Color.a = value; }
+ else if (field == "slot5Scale") { c.slot5Scale = value; }
+ else if (field == "slot6Color.r") { c.slot6Color.r = value; }
+ else if (field == "slot6Color.g") { c.slot6Color.g = value; }
+ else if (field == "slot6Color.b") { c.slot6Color.b = value; }
+ else if (field == "slot6Color.a") { c.slot6Color.a = value; }
+ else if (field == "slot6Scale") { c.slot6Scale = value; }
+ else if (field == "slot7Color.r") { c.slot7Color.r = value; }
+ else if (field == "slot7Color.g") { c.slot7Color.g = value; }
+ else if (field == "slot7Color.b") { c.slot7Color.b = value; }
+ else if (field == "slot7Color.a") { c.slot7Color.a = value; }
+ else if (field == "slot7Scale") { c.slot7Scale = value; }
+ else { return false; }
+ return true;
} else if (comp == "Transform") {
if (!reg.has<esengine::ecs::Transform>(entity)) return false;
auto& c = reg.get<esengine::ecs::Transform>(entity);
@@ -1187,6 +1318,50 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "tileSize.y") { return c.tileSize.y; }
else if (field == "tileSpacing.x") { return c.tileSpacing.x; }
else if (field == "tileSpacing.y") { return c.tileSpacing.y; }
+ } else if (comp == "StateVisuals") {
+ if (!reg.has<esengine::ecs::StateVisuals>(entity)) return 0.0f;
+ const auto& c = reg.get<esengine::ecs::StateVisuals>(entity);
+ if (field == "fadeDuration") { return c.fadeDuration; }
+ else if (field == "slot0Color.r") { return c.slot0Color.r; }
+ else if (field == "slot0Color.g") { return c.slot0Color.g; }
+ else if (field == "slot0Color.b") { return c.slot0Color.b; }
+ else if (field == "slot0Color.a") { return c.slot0Color.a; }
+ else if (field == "slot0Scale") { return c.slot0Scale; }
+ else if (field == "slot1Color.r") { return c.slot1Color.r; }
+ else if (field == "slot1Color.g") { return c.slot1Color.g; }
+ else if (field == "slot1Color.b") { return c.slot1Color.b; }
+ else if (field == "slot1Color.a") { return c.slot1Color.a; }
+ else if (field == "slot1Scale") { return c.slot1Scale; }
+ else if (field == "slot2Color.r") { return c.slot2Color.r; }
+ else if (field == "slot2Color.g") { return c.slot2Color.g; }
+ else if (field == "slot2Color.b") { return c.slot2Color.b; }
+ else if (field == "slot2Color.a") { return c.slot2Color.a; }
+ else if (field == "slot2Scale") { return c.slot2Scale; }
+ else if (field == "slot3Color.r") { return c.slot3Color.r; }
+ else if (field == "slot3Color.g") { return c.slot3Color.g; }
+ else if (field == "slot3Color.b") { return c.slot3Color.b; }
+ else if (field == "slot3Color.a") { return c.slot3Color.a; }
+ else if (field == "slot3Scale") { return c.slot3Scale; }
+ else if (field == "slot4Color.r") { return c.slot4Color.r; }
+ else if (field == "slot4Color.g") { return c.slot4Color.g; }
+ else if (field == "slot4Color.b") { return c.slot4Color.b; }
+ else if (field == "slot4Color.a") { return c.slot4Color.a; }
+ else if (field == "slot4Scale") { return c.slot4Scale; }
+ else if (field == "slot5Color.r") { return c.slot5Color.r; }
+ else if (field == "slot5Color.g") { return c.slot5Color.g; }
+ else if (field == "slot5Color.b") { return c.slot5Color.b; }
+ else if (field == "slot5Color.a") { return c.slot5Color.a; }
+ else if (field == "slot5Scale") { return c.slot5Scale; }
+ else if (field == "slot6Color.r") { return c.slot6Color.r; }
+ else if (field == "slot6Color.g") { return c.slot6Color.g; }
+ else if (field == "slot6Color.b") { return c.slot6Color.b; }
+ else if (field == "slot6Color.a") { return c.slot6Color.a; }
+ else if (field == "slot6Scale") { return c.slot6Scale; }
+ else if (field == "slot7Color.r") { return c.slot7Color.r; }
+ else if (field == "slot7Color.g") { return c.slot7Color.g; }
+ else if (field == "slot7Color.b") { return c.slot7Color.b; }
+ else if (field == "slot7Color.a") { return c.slot7Color.a; }
+ else if (field == "slot7Scale") { return c.slot7Scale; }
} else if (comp == "Transform") {
if (!reg.has<esengine::ecs::Transform>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::Transform>(entity);
@@ -1385,6 +1560,13 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
if (field == "layer") { c.layer = static_cast<i32>(value); }
else { return false; }
return true;
+ } else if (comp == "StateVisuals") {
+ if (!reg.has<esengine::ecs::StateVisuals>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::StateVisuals>(entity);
+ if (field == "targetGraphic") { c.targetGraphic = static_cast<Entity>(value); }
+ else if (field == "transitionFlags") { c.transitionFlags = static_cast<u32>(value); }
+ else { return false; }
+ return true;
} else if (comp == "UIMask") {
if (!reg.has<esengine::ecs::UIMask>(entity)) return false;
auto& c = reg.get<esengine::ecs::UIMask>(entity);
@@ -1506,6 +1688,11 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
if (!reg.has<esengine::ecs::Sprite>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::Sprite>(entity);
if (field == "layer") { return static_cast<i32>(c.layer); }
+ } else if (comp == "StateVisuals") {
+ if (!reg.has<esengine::ecs::StateVisuals>(entity)) return 0;
+ const auto& c = reg.get<esengine::ecs::StateVisuals>(entity);
+ if (field == "targetGraphic") { return static_cast<i32>(static_cast<u32>(c.targetGraphic)); }
+ else if (field == "transitionFlags") { return static_cast<i32>(c.transitionFlags); }
} else if (comp == "UIMask") {
if (!reg.has<esengine::ecs::UIMask>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::UIMask>(entity);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 712735a95..dcf544009 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -29,6 +29,8 @@
#include "../ecs/components/ShapeRenderer.hpp"
#include "../ecs/components/SpineAnimation.hpp"
#include "../ecs/components/Sprite.hpp"
+#include "../ecs/components/StateMachine.hpp"
+#include "../ecs/components/StateVisuals.hpp"
#include "../ecs/components/Transform.hpp"
#include "../ecs/components/UIInteraction.hpp"
#include "../ecs/components/UIMask.hpp"
@@ -722,6 +724,124 @@ SpriteJS spriteToJS(const esengine::ecs::Sprite& c) {
return js;
}
+struct StateVisualsJS {
+ u32 targetGraphic;
+ u32 transitionFlags;
+ f32 fadeDuration;
+ std::string slot0Name;
+ glm::vec4 slot0Color;
+ u32 slot0Sprite;
+ f32 slot0Scale;
+ std::string slot1Name;
+ glm::vec4 slot1Color;
+ u32 slot1Sprite;
+ f32 slot1Scale;
+ std::string slot2Name;
+ glm::vec4 slot2Color;
+ u32 slot2Sprite;
+ f32 slot2Scale;
+ std::string slot3Name;
+ glm::vec4 slot3Color;
+ u32 slot3Sprite;
+ f32 slot3Scale;
+ std::string slot4Name;
+ glm::vec4 slot4Color;
+ u32 slot4Sprite;
+ f32 slot4Scale;
+ std::string slot5Name;
+ glm::vec4 slot5Color;
+ u32 slot5Sprite;
+ f32 slot5Scale;
+ std::string slot6Name;
+ glm::vec4 slot6Color;
+ u32 slot6Sprite;
+ f32 slot6Scale;
+ std::string slot7Name;
+ glm::vec4 slot7Color;
+ u32 slot7Sprite;
+ f32 slot7Scale;
+};
+
+esengine::ecs::StateVisuals statevisualsFromJS(const StateVisualsJS& js) {
+ esengine::ecs::StateVisuals c;
+ c.targetGraphic = Entity(js.targetGraphic);
+ c.transitionFlags = js.transitionFlags;
+ c.fadeDuration = js.fadeDuration;
+ c.slot0Name = js.slot0Name;
+ c.slot0Color = js.slot0Color;
+ c.slot0Sprite = resource::TextureHandle(js.slot0Sprite);
+ c.slot0Scale = js.slot0Scale;
+ c.slot1Name = js.slot1Name;
+ c.slot1Color = js.slot1Color;
+ c.slot1Sprite = resource::TextureHandle(js.slot1Sprite);
+ c.slot1Scale = js.slot1Scale;
+ c.slot2Name = js.slot2Name;
+ c.slot2Color = js.slot2Color;
+ c.slot2Sprite = resource::TextureHandle(js.slot2Sprite);
+ c.slot2Scale = js.slot2Scale;
+ c.slot3Name = js.slot3Name;
+ c.slot3Color = js.slot3Color;
+ c.slot3Sprite = resource::TextureHandle(js.slot3Sprite);
+ c.slot3Scale = js.slot3Scale;
+ c.slot4Name = js.slot4Name;
+ c.slot4Color = js.slot4Color;
+ c.slot4Sprite = resource::TextureHandle(js.slot4Sprite);
+ c.slot4Scale = js.slot4Scale;
+ c.slot5Name = js.slot5Name;
+ c.slot5Color = js.slot5Color;
+ c.slot5Sprite = resource::TextureHandle(js.slot5Sprite);
+ c.slot5Scale = js.slot5Scale;
+ c.slot6Name = js.slot6Name;
+ c.slot6Color = js.slot6Color;
+ c.slot6Sprite = resource::TextureHandle(js.slot6Sprite);
+ c.slot6Scale = js.slot6Scale;
+ c.slot7Name = js.slot7Name;
+ c.slot7Color = js.slot7Color;
+ c.slot7Sprite = resource::TextureHandle(js.slot7Sprite);
+ c.slot7Scale = js.slot7Scale;
+ return c;
+}
+
+StateVisualsJS statevisualsToJS(const esengine::ecs::StateVisuals& c) {
+ StateVisualsJS js;
+ js.targetGraphic = static_cast<u32>(c.targetGraphic);
+ js.transitionFlags = c.transitionFlags;
+ js.fadeDuration = c.fadeDuration;
+ js.slot0Name = c.slot0Name;
+ js.slot0Color = c.slot0Color;
+ js.slot0Sprite = c.slot0Sprite.id();
+ js.slot0Scale = c.slot0Scale;
+ js.slot1Name = c.slot1Name;
+ js.slot1Color = c.slot1Color;
+ js.slot1Sprite = c.slot1Sprite.id();
+ js.slot1Scale = c.slot1Scale;
+ js.slot2Name = c.slot2Name;
+ js.slot2Color = c.slot2Color;
+ js.slot2Sprite = c.slot2Sprite.id();
+ js.slot2Scale = c.slot2Scale;
+ js.slot3Name = c.slot3Name;
+ js.slot3Color = c.slot3Color;
+ js.slot3Sprite = c.slot3Sprite.id();
+ js.slot3Scale = c.slot3Scale;
+ js.slot4Name = c.slot4Name;
+ js.slot4Color = c.slot4Color;
+ js.slot4Sprite = c.slot4Sprite.id();
+ js.slot4Scale = c.slot4Scale;
+ js.slot5Name = c.slot5Name;
+ js.slot5Color = c.slot5Color;
+ js.slot5Sprite = c.slot5Sprite.id();
+ js.slot5Scale = c.slot5Scale;
+ js.slot6Name = c.slot6Name;
+ js.slot6Color = c.slot6Color;
+ js.slot6Sprite = c.slot6Sprite.id();
+ js.slot6Scale = c.slot6Scale;
+ js.slot7Name = c.slot7Name;
+ js.slot7Color = c.slot7Color;
+ js.slot7Sprite = c.slot7Sprite.id();
+ js.slot7Scale = c.slot7Scale;
+ return js;
+}
+
struct UIMaskJS {
bool enabled;
i32 mode;
@@ -1007,6 +1127,47 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("material", &SpriteJS::material)
.field("enabled", &SpriteJS::enabled);
+ value_object<esengine::ecs::StateMachine>("StateMachine")
+ .field("current", &esengine::ecs::StateMachine::current)
+ .field("previous", &esengine::ecs::StateMachine::previous);
+
+ value_object<StateVisualsJS>("StateVisuals")
+ .field("targetGraphic", &StateVisualsJS::targetGraphic)
+ .field("transitionFlags", &StateVisualsJS::transitionFlags)
+ .field("fadeDuration", &StateVisualsJS::fadeDuration)
+ .field("slot0Name", &StateVisualsJS::slot0Name)
+ .field("slot0Color", &StateVisualsJS::slot0Color)
+ .field("slot0Sprite", &StateVisualsJS::slot0Sprite)
+ .field("slot0Scale", &StateVisualsJS::slot0Scale)
+ .field("slot1Name", &StateVisualsJS::slot1Name)
+ .field("slot1Color", &StateVisualsJS::slot1Color)
+ .field("slot1Sprite", &StateVisualsJS::slot1Sprite)
+ .field("slot1Scale", &StateVisualsJS::slot1Scale)
+ .field("slot2Name", &StateVisualsJS::slot2Name)
+ .field("slot2Color", &StateVisualsJS::slot2Color)
+ .field("slot2Sprite", &StateVisualsJS::slot2Sprite)
+ .field("slot2Scale", &StateVisualsJS::slot2Scale)
+ .field("slot3Name", &StateVisualsJS::slot3Name)
+ .field("slot3Color", &StateVisualsJS::slot3Color)
+ .field("slot3Sprite", &StateVisualsJS::slot3Sprite)
+ .field("slot3Scale", &StateVisualsJS::slot3Scale)
+ .field("slot4Name", &StateVisualsJS::slot4Name)
+ .field("slot4Color", &StateVisualsJS::slot4Color)
+ .field("slot4Sprite", &StateVisualsJS::slot4Sprite)
+ .field("slot4Scale", &StateVisualsJS::slot4Scale)
+ .field("slot5Name", &StateVisualsJS::slot5Name)
+ .field("slot5Color", &StateVisualsJS::slot5Color)
+ .field("slot5Sprite", &StateVisualsJS::slot5Sprite)
+ .field("slot5Scale", &StateVisualsJS::slot5Scale)
+ .field("slot6Name", &StateVisualsJS::slot6Name)
+ .field("slot6Color", &StateVisualsJS::slot6Color)
+ .field("slot6Sprite", &StateVisualsJS::slot6Sprite)
+ .field("slot6Scale", &StateVisualsJS::slot6Scale)
+ .field("slot7Name", &StateVisualsJS::slot7Name)
+ .field("slot7Color", &StateVisualsJS::slot7Color)
+ .field("slot7Sprite", &StateVisualsJS::slot7Sprite)
+ .field("slot7Scale", &StateVisualsJS::slot7Scale);
+
value_object<esengine::ecs::Transform>("Transform")
.field("position", &esengine::ecs::Transform::position)
.field("rotation", &esengine::ecs::Transform::rotation)
@@ -1516,6 +1677,47 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
r.remove<esengine::ecs::Sprite>(entity);
}))
+ // StateMachine
+ .function("hasStateMachine", optional_override([](Registry& r, u32 e) {
+ return r.has<esengine::ecs::StateMachine>(static_cast<Entity>(e));
+ }))
+ .function("getStateMachine", optional_override([](Registry& r, u32 e) -> esengine::ecs::StateMachine& {
+ auto entity = static_cast<Entity>(e);
+ static esengine::ecs::StateMachine s_dummy{};
+ if (!r.valid(entity) || !r.has<esengine::ecs::StateMachine>(entity)) return s_dummy;
+ return r.get<esengine::ecs::StateMachine>(entity);
+ }), allow_raw_pointers())
+ .function("addStateMachine", optional_override([](Registry& r, u32 e, const esengine::ecs::StateMachine& c) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity)) return;
+ r.emplaceOrReplace<esengine::ecs::StateMachine>(entity, c);
+ }))
+ .function("removeStateMachine", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::StateMachine>(entity)) return;
+ r.remove<esengine::ecs::StateMachine>(entity);
+ }))
+
+ // StateVisuals
+ .function("hasStateVisuals", optional_override([](Registry& r, u32 e) {
+ return r.has<esengine::ecs::StateVisuals>(static_cast<Entity>(e));
+ }))
+ .function("getStateVisuals", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::StateVisuals>(entity)) return StateVisualsJS{};
+ return statevisualsToJS(r.get<esengine::ecs::StateVisuals>(entity));
+ }))
+ .function("addStateVisuals", optional_override([](Registry& r, u32 e, const StateVisualsJS& js) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity)) return;
+ r.emplaceOrReplace<esengine::ecs::StateVisuals>(entity, statevisualsFromJS(js));
+ }))
+ .function("removeStateVisuals", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::StateVisuals>(entity)) return;
+ r.remove<esengine::ecs::StateVisuals>(entity);
+ }))
+
// Transform
.function("hasTransform", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::Transform>(static_cast<Entity>(e));
diff --git a/src/esengine/ecs/components/StateMachine.hpp b/src/esengine/ecs/components/StateMachine.hpp
new file mode 100644
index 000000000..39d73524c
--- /dev/null
+++ b/src/esengine/ecs/components/StateMachine.hpp
@@ -0,0 +1,29 @@
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "../../core/Reflection.hpp"
+
+#include <string>
+
+namespace esengine::ecs {
+
+/**
+ * @brief Generic named-state field for an entity.
+ *
+ * @details Holds the current state as a free-form string. State names are
+ * user-defined (e.g. "normal", "hover", "pressed", "loading").
+ * A StateMachine system compares `current` against `previous`
+ * each frame and raises a transition event when they differ.
+ */
+ES_COMPONENT()
+struct StateMachine {
+ /** @brief Active state name. Written by drivers (Interactable, user code). */
+ ES_PROPERTY()
+ std::string current;
+
+ /** @brief State as of the last processed frame; consumed by transition diffing. */
+ ES_PROPERTY()
+ std::string previous;
+};
+
+} // namespace esengine::ecs
diff --git a/src/esengine/ecs/components/StateVisuals.hpp b/src/esengine/ecs/components/StateVisuals.hpp
new file mode 100644
index 000000000..cf59e02cd
--- /dev/null
+++ b/src/esengine/ecs/components/StateVisuals.hpp
@@ -0,0 +1,93 @@
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "../../core/Reflection.hpp"
+#include "../../math/Math.hpp"
+#include "../../resource/Handle.hpp"
+
+#include <string>
+
+namespace esengine::ecs {
+
+/**
+ * @brief Bitmask flags for `StateVisuals::transitionFlags`.
+ *
+ * @details Multiple transition modes may be combined. Values are bit
+ * positions, not exclusive, so the field is stored as `u32`
+ * rather than an ES_ENUM.
+ */
+namespace StateVisualsTransition {
+ constexpr u32 None = 0;
+ constexpr u32 ColorTint = 1u << 0; // write color to targetGraphic UIRenderer
+ constexpr u32 SpriteSwap = 1u << 1; // write texture to targetGraphic UIRenderer
+ constexpr u32 Scale = 1u << 2; // multiply targetGraphic Transform scale
+}
+
+/**
+ * @brief Maps state names to visual overrides on a target entity.
+ *
+ * @details Eight open slots, each labelled by `slotNName`. The visual
+ * system reads the owning entity's StateMachine.current, looks
+ * up the matching slot (empty names are treated as unused), and
+ * applies `color` / `sprite` / `scale` to `targetGraphic`
+ * according to `transitionFlags`.
+ *
+ * `targetGraphic == INVALID_ENTITY` means "apply to self".
+ */
+ES_COMPONENT()
+struct StateVisuals {
+ ES_PROPERTY(entity_ref)
+ Entity targetGraphic = INVALID_ENTITY;
+
+ /** @brief Bitmask of StateVisualsTransition constants. */
+ ES_PROPERTY()
+ u32 transitionFlags{0};
+
+ /** @brief Seconds over which to lerp color/scale on state change. 0 = snap. Sprite swap is always instant. */
+ ES_PROPERTY()
+ f32 fadeDuration{0.0f};
+
+ // -- slots (8 × 4 = 32 fields) --
+
+ ES_PROPERTY() std::string slot0Name;
+ ES_PROPERTY() glm::vec4 slot0Color{1.0f, 1.0f, 1.0f, 1.0f};
+ ES_PROPERTY(asset = texture) resource::TextureHandle slot0Sprite;
+ ES_PROPERTY() f32 slot0Scale{1.0f};
+
+ ES_PROPERTY() std::string slot1Name;
+ ES_PROPERTY() glm::vec4 slot1Color{1.0f, 1.0f, 1.0f, 1.0f};
+ ES_PROPERTY(asset = texture) resource::TextureHandle slot1Sprite;
+ ES_PROPERTY() f32 slot1Scale{1.0f};
+
+ ES_PROPERTY() std::string slot2Name;
+ ES_PROPERTY() glm::vec4 slot2Color{1.0f, 1.0f, 1.0f, 1.0f};
+ ES_PROPERTY(asset = texture) resource::TextureHandle slot2Sprite;
+ ES_PROPERTY() f32 slot2Scale{1.0f};
+
+ ES_PROPERTY() std::string slot3Name;
+ ES_PROPERTY() glm::vec4 slot3Color{1.0f, 1.0f, 1.0f, 1.0f};
+ ES_PROPERTY(asset = texture) resource::TextureHandle slot3Sprite;
+ ES_PROPERTY() f32 slot3Scale{1.0f};
+
+ ES_PROPERTY() std::string slot4Name;
+ ES_PROPERTY() glm::vec4 slot4Color{1.0f, 1.0f, 1.0f, 1.0f};
+ ES_PROPERTY(asset = texture) resource::TextureHandle slot4Sprite;
+ ES_PROPERTY() f32 slot4Scale{1.0f};
+
+ ES_PROPERTY() std::string slot5Name;
+ ES_PROPERTY() glm::vec4 slot5Color{1.0f, 1.0f, 1.0f, 1.0f};
+ ES_PROPERTY(asset = texture) resource::TextureHandle slot5Sprite;
+ ES_PROPERTY() f32 slot5Scale{1.0f};
+
+ ES_PROPERTY() std::string slot6Name;
+ ES_PROPERTY() glm::vec4 slot6Color{1.0f, 1.0f, 1.0f, 1.0f};
+ ES_PROPERTY(asset = texture) resource::TextureHandle slot6Sprite;
+ ES_PROPERTY() f32 slot6Scale{1.0f};
+
+ ES_PROPERTY() std::string slot7Name;
+ ES_PROPERTY() glm::vec4 slot7Color{1.0f, 1.0f, 1.0f, 1.0f};
+ ES_PROPERTY(asset = texture) resource::TextureHandle slot7Sprite;
+ ES_PROPERTY() f32 slot7Scale{1.0f};
+};
+
+} // namespace esengine::ecs