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): implement fadeDuration on StateVisuals (color + scale lerp)
esengine05396d437f21
diff --git a/sdk/src/ui/behavior/systems.ts b/sdk/src/ui/behavior/systems.tsindex 7adf279c2..007ebe779 100644--- a/sdk/src/ui/behavior/systems.ts+++ b/sdk/src/ui/behavior/systems.ts@@ -1,5 +1,7 @@import { defineSystem, type SystemDef } from '../../system';import { Transform, type TransformData } from '../../component';+import { Res, Time, type TimeData } from '../../resource';+import type { Entity, Color } from '../../types';import type { World } from '../../world';import { Interactable, UIInteraction, type InteractableData, type UIInteractionData } from './interactable';@@ -96,44 +98,122 @@ export function createStateMachineDiffSystem(}, { name: 'StateMachineDiffSystem' });}+/**+ * Per-entity transition bookkeeping for StateVisualsApplySystem.+ *+ * Kept in a closure Map rather than an ECS component so the state is+ * invisible to serialization and GC'd naturally when an entity's+ * StateVisuals row disappears (stale entries are purged lazily via+ * `world.valid` and slot-change checks). Color and scalar scale fade+ * continuously over `sv.fadeDuration`; sprite swaps snap (can't lerp+ * between two discrete texture handles).+ */+interface VisualTransitionState {+ readonly toSlot: number;+ elapsed: number;+ /** Snapshot of the target's color at the moment the transition started. */+ readonly startColor: Color;+ /** Snapshot of the target's uniform scale at the moment the transition started. */+ readonly startScale: number;+}++function lerp(a: number, b: number, t: number): number {+ return a + (b - a) * t;+}++function lerpColor(from: Color, to: Color, t: number): Color {+ return {+ r: lerp(from.r, to.r, t),+ g: lerp(from.g, to.g, t),+ b: lerp(from.b, to.b, t),+ a: lerp(from.a, to.a, t),+ };+}+/*** 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.+ * When `fadeDuration > 0` and the target slot changed from the last+ * frame's, color and scale continuously interpolate from whatever value+ * the target already had over `fadeDuration` seconds. Sprite swaps are+ * discrete and still snap (no meaningful interpolation between textures).*/export function createStateVisualsApplySystem(world: World): SystemDef {- return defineSystem([], () => {+ const transitions = new Map<Entity, VisualTransitionState>();++ return defineSystem([Res(Time)], (time: TimeData) => {+ const dt = time.delta;const entities = world.getEntitiesWithComponents([StateMachine, StateVisuals]);+ const seen = new Set<Entity>();+for (const e of entities) {+ seen.add(e);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;+ if (slot < 0) {+ transitions.delete(e);+ continue;+ }const target = sv.targetGraphic !== 0 ? sv.targetGraphic : e;const flags = sv.transitionFlags;const record = sv as unknown as Record<string, unknown>;+ const targetColor = record[`slot${slot}Color`] as Color;+ const targetScale = record[`slot${slot}Scale`] as number;+ const fade = Math.max(0, sv.fadeDuration);++ // Detect a slot change. If we have no prior entry OR the entry+ // points at a different slot, seed a new transition with the+ // target's *current* values as the "from" endpoint so the fade+ // blends from whatever the user/driver left there.+ let tx = transitions.get(e);+ if (!tx || tx.toSlot !== slot) {+ const startColor = (flags & TransitionFlag.ColorTint) && world.has(target, UIRenderer)+ ? { ...(world.get(target, UIRenderer) as UIRendererData).color }+ : { ...targetColor };+ const startScale = (flags & TransitionFlag.Scale) && world.has(target, Transform)+ ? (world.get(target, Transform) as TransformData).scale.x+ : targetScale;+ tx = { toSlot: slot, elapsed: 0, startColor, startScale };+ transitions.set(e, tx);+ } else {+ tx.elapsed += dt;+ }++ const t = fade > 0 ? Math.min(tx.elapsed / fade, 1) : 1;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'];+ r.color = t >= 1 ? targetColor : lerpColor(tx.startColor, targetColor, t);world.insert(target, UIRenderer, r);}if ((flags & TransitionFlag.SpriteSwap) && world.has(target, UIRenderer)) {+ // Sprite swap is discrete: apply immediately at the slot change.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);+ const tr = world.get(target, Transform) as TransformData;+ const s = t >= 1 ? targetScale : lerp(tx.startScale, targetScale, t);+ tr.scale = { x: s, y: s, z: 1 };+ world.insert(target, Transform, tr);+ }++ if (t >= 1) {+ transitions.delete(e);+ }+ }++ // Purge entries whose entity vanished or no longer carries the components.+ if (transitions.size > 0) {+ for (const e of transitions.keys()) {+ if (!seen.has(e) || !world.valid(e)) transitions.delete(e);}}}, { name: 'StateVisualsApplySystem' });diff --git a/sdk/tests/ui-state-visuals-fade.test.ts b/sdk/tests/ui-state-visuals-fade.test.tsnew file mode 100644index 000000000..982e817b0--- /dev/null+++ b/sdk/tests/ui-state-visuals-fade.test.ts@@ -0,0 +1,235 @@+/**+ * @file ui-state-visuals-fade.test.ts+ * @brief StateVisualsApplySystem interpolates color/scale when+ * fadeDuration > 0, and snaps otherwise.+ */+import { describe, expect, it, beforeEach, vi } from 'vitest';+import { Transform, type TransformData } from '../src/component';+import { StateMachine, type StateMachineData } from '../src/ui/behavior/state-machine';+import {+ StateVisuals,+ TransitionFlag,+ type StateVisualsData,+} from '../src/ui/behavior/state-visuals';+import { UIRenderer, type UIRendererData } from '../src/ui/core/ui-renderer';+import { createStateVisualsApplySystem } from '../src/ui/behavior/systems';+import type { Entity } from '../src/types';+import type { SystemDef } from '../src/system';+import type { AnyComponentDef } from '../src/component';++/**+ * Minimal World surface the apply system uses. Backed by per-component+ * Maps so builtin components (Transform, UIRenderer, StateVisuals) don't+ * need a real C++ registry. Enough for behavior-level testing of the+ * fade logic.+ */+function makeMockWorld() {+ 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) { s = new Map(); storage.set(c, s); }+ return s;+ };++ return {+ spawn: () => { const e = next++ as Entity; alive.add(e); return 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),+ insert: (e: Entity, c: AnyComponentDef, d: unknown) => { storeFor(c).set(e, d); },+ set: (e: Entity, c: AnyComponentDef, d: unknown) => { storeFor(c).set(e, d); },+ remove: (e: Entity, c: AnyComponentDef) => storeFor(c).delete(e),+ getEntitiesWithComponents: (required: AnyComponentDef[]) => {+ const out: Entity[] = [];+ outer: for (const e of alive) {+ for (const c of required) if (!storeFor(c).has(e)) continue outer;+ out.push(e);+ }+ return out;+ },+ };+}++function makeVisuals(overrides: Partial<StateVisualsData>): StateVisualsData {+ return {+ targetGraphic: 0 as Entity,+ 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,+ } as StateVisualsData;+}++function runSystem(system: SystemDef, dt: number): void {+ (system._fn as (...a: unknown[]) => void)({ delta: dt, elapsed: 0, frameCount: 0 });+}++function makeTransform(scale = 1): TransformData {+ return {+ position: { x: 0, y: 0, z: 0 },+ rotation: { x: 0, y: 0, z: 0, w: 1 },+ scale: { x: scale, y: scale, z: 1 },+ worldPosition: { x: 0, y: 0, z: 0 },+ worldRotation: { x: 0, y: 0, z: 0, w: 1 },+ worldScale: { x: scale, y: scale, z: 1 },+ };+}++function makeRenderer(color = { r: 1, g: 1, b: 1, a: 1 }, texture = 0): UIRendererData {+ return {+ texture, color, size: { x: 10, y: 10 },+ pivot: { x: 0.5, y: 0.5 }, layer: 0, enabled: true,+ } as UIRendererData;+}++describe('StateVisualsApplySystem — color fade', () => {+ let world: ReturnType<typeof makeMockWorld>;+ let entity: Entity;++ beforeEach(() => {+ world = makeMockWorld();+ entity = world.spawn();+ world.insert(entity, Transform, makeTransform());+ world.insert(entity, UIRenderer, makeRenderer());+ });++ it('snaps immediately when fadeDuration is 0', () => {+ world.insert(entity, StateMachine, { current: 'pressed', previous: '' } as StateMachineData);+ world.insert(entity, StateVisuals, makeVisuals({+ transitionFlags: TransitionFlag.ColorTint,+ fadeDuration: 0,+ slot0Name: 'pressed',+ slot0Color: { r: 0, g: 0, b: 1, a: 1 },+ }));++ const sys = createStateVisualsApplySystem(world as never);+ runSystem(sys, 1 / 60);++ const r = world.get(entity, UIRenderer) as UIRendererData;+ expect(r.color).toEqual({ r: 0, g: 0, b: 1, a: 1 });+ });++ it('interpolates color halfway at t = duration/2', () => {+ world.insert(entity, StateMachine, { current: 'pressed', previous: '' } as StateMachineData);+ world.insert(entity, StateVisuals, makeVisuals({+ transitionFlags: TransitionFlag.ColorTint,+ fadeDuration: 1.0,+ slot0Name: 'pressed',+ slot0Color: { r: 0, g: 0, b: 0, a: 1 },+ }));++ const sys = createStateVisualsApplySystem(world as never);+ runSystem(sys, 0); // seed transition, t=0+ let r = world.get(entity, UIRenderer) as UIRendererData;+ expect(r.color.r).toBeCloseTo(1);++ runSystem(sys, 0.5); // advance to t=0.5+ r = world.get(entity, UIRenderer) as UIRendererData;+ expect(r.color.r).toBeCloseTo(0.5, 2);+ expect(r.color.g).toBeCloseTo(0.5, 2);+ expect(r.color.b).toBeCloseTo(0.5, 2);+ });++ it('clamps to target at t >= duration', () => {+ world.insert(entity, StateMachine, { current: 'pressed', previous: '' } as StateMachineData);+ world.insert(entity, StateVisuals, makeVisuals({+ transitionFlags: TransitionFlag.ColorTint,+ fadeDuration: 0.5,+ slot0Name: 'pressed',+ slot0Color: { r: 0, g: 0, b: 0, a: 1 },+ }));++ const sys = createStateVisualsApplySystem(world as never);+ runSystem(sys, 0);+ runSystem(sys, 1.0);++ const r = world.get(entity, UIRenderer) as UIRendererData;+ expect(r.color).toEqual({ r: 0, g: 0, b: 0, a: 1 });+ });++ it('restarts the fade when the target slot changes mid-transition', () => {+ world.insert(entity, StateMachine, { current: 'a', previous: '' } as StateMachineData);+ world.insert(entity, StateVisuals, makeVisuals({+ transitionFlags: TransitionFlag.ColorTint,+ fadeDuration: 1.0,+ slot0Name: 'a', slot0Color: { r: 0, g: 0, b: 0, a: 1 },+ slot1Name: 'b', slot1Color: { r: 1, g: 0, b: 0, a: 1 },+ }));++ const sys = createStateVisualsApplySystem(world as never);+ runSystem(sys, 0);+ runSystem(sys, 0.5);+ let r = world.get(entity, UIRenderer) as UIRendererData;+ expect(r.color.r).toBeCloseTo(0.5, 1);++ const sm = world.get(entity, StateMachine) as StateMachineData;+ sm.current = 'b';+ world.insert(entity, StateMachine, sm);++ runSystem(sys, 0);+ r = world.get(entity, UIRenderer) as UIRendererData;+ expect(r.color.r).toBeCloseTo(0.5, 1);++ runSystem(sys, 1.0);+ r = world.get(entity, UIRenderer) as UIRendererData;+ expect(r.color).toEqual({ r: 1, g: 0, b: 0, a: 1 });+ });+});++describe('StateVisualsApplySystem — scale fade', () => {+ it('lerps uniform scale across the fade window', () => {+ const world = makeMockWorld();+ const entity = world.spawn();+ world.insert(entity, Transform, makeTransform(1));+ world.insert(entity, UIRenderer, makeRenderer());+ world.insert(entity, StateMachine, { current: 'pressed', previous: '' } as StateMachineData);+ world.insert(entity, StateVisuals, makeVisuals({+ transitionFlags: TransitionFlag.Scale,+ fadeDuration: 1.0,+ slot0Name: 'pressed',+ slot0Scale: 2,+ }));++ const sys = createStateVisualsApplySystem(world as never);+ runSystem(sys, 0);+ runSystem(sys, 0.25);++ const t = world.get(entity, Transform) as TransformData;+ expect(t.scale.x).toBeCloseTo(1.25, 2);+ expect(t.scale.y).toBeCloseTo(1.25, 2);+ });+});++describe('StateVisualsApplySystem — sprite swap', () => {+ it('always snaps (never lerps) because textures are discrete', () => {+ const world = makeMockWorld();+ const entity = world.spawn();+ world.insert(entity, UIRenderer, makeRenderer({ r: 1, g: 1, b: 1, a: 1 }, 7));+ world.insert(entity, StateMachine, { current: 'pressed', previous: '' } as StateMachineData);+ world.insert(entity, StateVisuals, makeVisuals({+ transitionFlags: TransitionFlag.SpriteSwap,+ fadeDuration: 1.0,+ slot0Name: 'pressed',+ slot0Sprite: 42,+ }));++ const sys = createStateVisualsApplySystem(world as never);+ runSystem(sys, 0);++ const r = world.get(entity, UIRenderer) as UIRendererData;+ expect(r.texture).toBe(42);+ });+});++// Silence any unused-import warnings+void vi;