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
refactor(ui)!: sweep the StateVisuals-era dead surface + own the tween override lifecycle
esenginebc491c6174d6
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.tsindex a94237e29..75580f9c5 100644--- a/sdk/src/core-ui.ts+++ b/sdk/src/core-ui.ts@@ -7,7 +7,7 @@** This is the curated *public* UI API. The complete UI module surface — which* also includes low-level text/atlas internals and engine-internal composition- * glue (e.g. `withChildEntity`, `setEntityColor`, `EntityStateMap`) — lives in+ * glue (e.g. `EntityStateMap`, `ensureComponent`) — lives in* `./ui` and is imported module-directly by the SDK code that needs it. Those* internals are intentionally NOT re-exported here, so the public `esengine`* namespace stays a stable, intentional surface.@@ -44,10 +44,8 @@ export {quaternionToAngle2D,Interactable,UIInteraction,- AnimOverride,UIEvents,UIEventQueue,- makeInteractable,UICameraInfo,screenToUiWorld,uiWorldToScreen,@@ -59,7 +57,6 @@ export {FillOrigin,Draggable,DragState,- FillDirection,Focusable,FocusManager,FocusManagerState,diff --git a/sdk/src/ui/ARCHITECTURE.md b/sdk/src/ui/ARCHITECTURE.mdindex 7bd3358f3..42eb94396 100644--- a/sdk/src/ui/ARCHITECTURE.md+++ b/sdk/src/ui/ARCHITECTURE.md@@ -22,13 +22,13 @@ layer above it in this list; it must **not** import from a layer below it.```Layer 0 Events core/events.ts (the UI event bus)Layer 1 Primitives core/ + layout/flex.ts (components = data)-Layer 2 Behaviors input/ behavior/ (interaction, FSM, drag, focus)+Layer 2 Behaviors input/ controller/ behavior/ (interaction, controllers+gears, drag, focus)Layout/Render layout/ render/ (Yoga driver, masking, draw order)Layer 3 Collection collection/ (lists, scroll, virtualization)Layer 4 Widgets widgets/ (factory functions: button, dialog, …)Cross Text text/ (SDF/atlas/rich-text pipeline)Cross Theme theme/ (design tokens)-Cross Util util/ (pure helpers, math, types, constants)+Cross Util util/ (pure helpers, math, constants)````util/`, `text/`, and `theme/` are cross-cutting: they sit beside the layers and@@ -40,15 +40,16 @@ collection, or widgets.| Folder | Responsibility | Key files ||--------|----------------|-----------|| `core/` | Layer 0–1 primitives: the components that *are* the UI | `ui-node`, `ui-visual`, `ui-mask`, `text`, `dimension`, `events`, `ui-camera-info` |-| `layout/` | Flexbox layout + safe area + layout bookkeeping | `flex`, `layout` (Yoga driver plugin), `safe-area`, `ui-layout-generation` |+| `layout/` | Flexbox layout + safe area + layout bookkeeping | `anchor`, `flex`, `layout` (Yoga driver plugin), `safe-area`, `ui-layout-generation` || `input/` | Pointer/keyboard interaction primitives + their plugins | `interactable`, `draggable`, `focusable`, `drag`, `focus`, `interaction` |-| `behavior/` | Stateful behavior layer (FSM + visual states) | `state-machine`, `state-visuals`, `systems`, `plugin` (UIBehaviorPlugin) |+| `controller/` | The one widget-state mechanism: named pages + per-component property gears, tween-applied | `ui-controller`, `ui-gear`, `gear-apply`, `bind-page`, `ai-builtins`, `plugin` |+| `behavior/` | Runtime systems for scroll/collection ticking + theme re-resolution | `plugin` (UIBehaviorPlugin), `theme-apply` || `render/` | UI-specific render concerns | `mask`, `render-order` || `collection/` | Data-driven collections + view recycling | `list-view`, `scroll-container`, `view-pool`, `data-source`, `layout-provider` || `text/` | SDF glyph atlas, text layout, rich text, editable text | `glyph-atlas`, `text-renderer`, `layout`, `rich-text-*`, `text-input`, `image-resolver` |-| `theme/` | Design tokens | `tokens` |-| `util/` | Cross-cutting helpers (no engine state of their own) | `helpers`, `math`, `types`, `constants`, `property-path` |-| `widgets/` | Layer-3 widget **factory functions** | `button`, `toggle`, `slider`, `progress`, `dialog`, `dropdown`, `helpers` |+| `theme/` | Design tokens + per-entity role markers | `tokens`, `theme-style` |+| `util/` | Cross-cutting helpers (no engine state of their own) | `helpers`, `math`, `constants`, `property-path`, `ui-pick` |+| `widgets/` | Layer-4 widget **factory functions** + their prefab capture | `button`, `toggle`, `slider`, `progress`, `dialog`, `dropdown`, `list-view`, `helpers`, `toPrefab`, `prefabs/` |Only two files live at the module root, and that is deliberate:@@ -65,8 +66,8 @@ There are exactly two export surfaces, with distinct jobs:offers, including low-level text/atlas internals for advanced use.2. **`sdk/src/core-ui.ts`** promotes the *stable, curated* subset into thetop-level `esengine` namespace. It re-exports **only** intentional public- API — never `@internal` glue (`withChildEntity`, `setEntityColor`,- `EntityStateMap`, …). Those stay importable from `./ui` for SDK-internal use.+ API — never `@internal` glue (`EntityStateMap`, `ensureComponent`, …).+ Those stay importable from `./ui` for SDK-internal use.Rules:diff --git a/sdk/src/ui/collection/view-pool.ts b/sdk/src/ui/collection/view-pool.tsindex b447baa95..c0987ded9 100644--- a/sdk/src/ui/collection/view-pool.ts+++ b/sdk/src/ui/collection/view-pool.ts@@ -55,7 +55,7 @@ export interface ViewPoolOptions {* ```ts* const pool = new ViewPool({* world,- * setVisible: (w, e, v) => setEntityEnabled(w, e, v),+ * setVisible: (w, e, v) => w.insert(e, UIVisual, { ...w.get(e, UIVisual), enabled: v }),* });** pool.setTemplate('default', {diff --git a/sdk/src/ui/controller/index.ts b/sdk/src/ui/controller/index.tsdeleted file mode 100644index 71dcee8b0..000000000--- a/sdk/src/ui/controller/index.ts+++ /dev/null@@ -1,41 +0,0 @@-// SPDX-License-Identifier: Apache-2.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-/**- * @file ui/controller/index.ts- * @brief Barrel for the Controller + Gear layer.- */-export {- UIController,- INTERACTION_CONTROLLER,- INTERACTION_PAGES,- interactionController,- controllerState,- findControllerOwner,- getControllerPage,- setControllerPage,- type ControllerState,- type UIControllerData,-} from './ui-controller';--export {- UIGear,- gearBinding,- type GearValue,- type GearTween,- type GearBinding,- type UIGearData,-} from './ui-gear';--export {- createInteractionControllerDriverSystem,- createGearApplySystem,- readFieldPath,- writeFieldPath,- isLerpable,- lerpGearValue,-} from './gear-apply';--export { bindControllerPage } from './bind-page';-export { ensureControllerAiRegistrations } from './ai-builtins';--export { UIControllerPlugin, uiControllerPlugin } from './plugin';diff --git a/sdk/src/ui/core/ui-mask.ts b/sdk/src/ui/core/ui-mask.tsindex e942e3740..bc01f2037 100644--- a/sdk/src/ui/core/ui-mask.ts+++ b/sdk/src/ui/core/ui-mask.ts@@ -5,20 +5,15 @@ import { defineBuiltin } from '../../component';export const MaskMode = {Scissor: 0,Stencil: 1,- Alpha: 2,} as const;export type MaskMode = (typeof MaskMode)[keyof typeof MaskMode];export interface UIMaskData {enabled: boolean;mode: MaskMode;- maskTexture: number;- inverted: boolean;}export const UIMask = defineBuiltin<UIMaskData>('UIMask', {enabled: true,mode: MaskMode.Scissor,- maskTexture: 0,- inverted: false,});diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex 900888b39..f7e05b647 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -5,27 +5,12 @@* @brief UI module — public barrel.*/-// Shared Types-export {- FillDirection,- type ColorTransition,-} from './util/types';-// Shared Helpersexport {initUIHelpers,- applyColorTransition,- wrapText,nextPowerOf2,ensureComponent,- makeInteractable,- syncFillSpriteSize,walkParentChain,- withChildEntity,- setEntityColor,- setEntityEnabled,- colorScale,- colorWithAlpha,EntityStateMap,} from './util/helpers';@@ -44,9 +29,6 @@ export {SCROLL_ELASTIC_SNAP_THRESHOLD,SCROLL_MAX_OVERSCROLL_RATIO,SCROLL_MAX_VELOCITY_RATIO,- DROPDOWN_ITEM_HEIGHT,- DROPDOWN_FONT_SIZE,- DROPDOWN_HIGHLIGHT_COLOR,} from './util/constants';// ─── Layer 0: Events ────────────────────────────────────────────────────────@@ -464,11 +446,3 @@ export {export { ShelfPacker, type Packer, type PackPos } from './text/atlas-packer';export { sdfFromAlpha } from './text/sdf';export { submitTextBatch, TEXT_VERTEX_FLOATS } from './text/submit';--export const AnimOverride = {- POS_X: 1,- POS_Y: 2,- ROT_Z: 4,- SCALE_X: 8,- SCALE_Y: 16,-} as const;diff --git a/sdk/src/ui/layout/flex.ts b/sdk/src/ui/layout/flex.tsindex fa9263643..061295631 100644--- a/sdk/src/ui/layout/flex.ts+++ b/sdk/src/ui/layout/flex.ts@@ -41,6 +41,3 @@ export const FlexContainer = defineBuiltin<FlexContainerData>('FlexContainer', {padding: { left: 0, top: 0, right: 0, bottom: 0 },});-// Per-item flex properties (grow/shrink/basis/alignSelf/margin/min-max) live on-// UINode now; the standalone FlexItem component was removed.-// `AlignSelf` moved to ui/core/ui-node.ts alongside the other item properties.diff --git a/sdk/src/ui/layout/layout.ts b/sdk/src/ui/layout/layout.tsindex 271c6e1b5..b7ba73c27 100644--- a/sdk/src/ui/layout/layout.ts+++ b/sdk/src/ui/layout/layout.ts@@ -7,11 +7,7 @@* Owns the PreUpdate `UILayoutSystem` (drives the C++ Yoga pass via* `uiLayout_update` + `transform_update`) plus the PostUpdate late/final* passes that re-solve after scroll/list mutations. Co-located with the- * `flex`/`grid`/`safe-area` schemas in this module.- *- * Behaviour is byte-identical to the former flat `UILayoutPlugin.ts`, which- * now re-exports from here (strangler-fig; legacy public symbols kept as- * shims).+ * `flex`/`safe-area` schemas in this module.*/import type { App, Plugin } from '../../app';import { registerComponent } from '../../component';diff --git a/sdk/src/ui/layout/safe-area.ts b/sdk/src/ui/layout/safe-area.tsindex cd058c7e1..70d687529 100644--- a/sdk/src/ui/layout/safe-area.ts+++ b/sdk/src/ui/layout/safe-area.ts@@ -4,12 +4,6 @@* @file ui/layout/safe-area.ts* @brief Safe-area concept — component + the PreUpdate system that pushes* platform safe-area insets into UINode insets, co-located.- *- * The layout concept (Yoga driver + safe-area) is the first concept relocated- * out of the flat legacy plugins into a cohesive module. Behaviour is- * byte-identical to the former `SafeArea.ts` + `SafeAreaPlugin.ts`; those files- * now re-export from here (strangler-fig — legacy public symbols are kept as- * shims).*/import type { App, Plugin } from '../../app';import { isWeChat, platformDevicePixelRatio } from '../../platform';diff --git a/sdk/src/ui/ui-plugin.ts b/sdk/src/ui/ui-plugin.tsindex de49790e3..4641a2eb0 100644--- a/sdk/src/ui/ui-plugin.ts+++ b/sdk/src/ui/ui-plugin.ts@@ -4,8 +4,8 @@* @file ui/ui-plugin.ts* @brief UIPlugin — the single declarative UI pipeline.*- * Composes the formerly separate concept plugins (layout, mask, safe-area,- * text, interaction, behavior, drag, focus, text-input, render-order) into one+ * Composes the separate concept plugins (layout, mask, safe-area, text,+ * interaction, behavior, controller, drag, focus, text-input, render-order) into one* plugin so the app's plugin list carries a single UI entry instead of ten* hand-ordered ones. System *execution* order is still defined declaratively by* each system's runAfter/runBefore labels; composition only fixes *build* orderdiff --git a/sdk/src/ui/util/constants.ts b/sdk/src/ui/util/constants.tsindex 86fc2192d..8da4d0c60 100644--- a/sdk/src/ui/util/constants.ts+++ b/sdk/src/ui/util/constants.ts@@ -17,9 +17,3 @@ export const SCROLL_ELASTIC_SNAP_THRESHOLD = 0.5;export const SCROLL_MAX_OVERSCROLL_RATIO = 0.5;export const SCROLL_MAX_VELOCITY_RATIO = 5;export const SCROLL_POSITION_EPSILON = 0.01;--export const DROPDOWN_ITEM_HEIGHT = 30;-export const DROPDOWN_FONT_SIZE = 16;-export const DROPDOWN_HIGHLIGHT_COLOR = { r: 0.3, g: 0.5, b: 0.8, a: 1 };-export const DROPDOWN_DEFAULT_COLOR = { r: 0.9, g: 0.9, b: 0.9, a: 1 };-export const DROPDOWN_OPTION_COLOR = { r: 0.95, g: 0.95, b: 0.95, a: 1 };diff --git a/sdk/src/ui/util/helpers.ts b/sdk/src/ui/util/helpers.tsindex 8ca4cf4dd..5c4dbc805 100644--- a/sdk/src/ui/util/helpers.ts+++ b/sdk/src/ui/util/helpers.ts@@ -1,16 +1,12 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { CoreApiBridge } from '../../CoreApiBridge';-import { Sprite, Parent, Transform } from '../../component';-import type { ParentData, SpriteData, TransformData, AnyComponentDef } from '../../component';-import type { Entity, Color } from '../../types';+import { Parent } from '../../component';+import type { ParentData, AnyComponentDef } from '../../component';+import type { Entity } from '../../types';import type { World } from '../../world';import { UIVisual, UIVisualType } from '../core/ui-visual';-import type { UIVisualData } from '../core/ui-visual';-import { FillDirection } from './types';-import type { ColorTransition } from './types';import type { ESEngineModule, CppRegistry } from '../../wasm';-import { Interactable } from '../input/interactable';const bridge = new CoreApiBridge('uiHelpers');let module_: ESEngineModule | null = null;@@ -23,56 +19,6 @@ export function initUIHelpers(module: ESEngineModule, registry: CppRegistry): vo}-export function applyColorTransition(- transition: ColorTransition,- enabled: boolean,- pressed: boolean,- hovered: boolean,-): Color {- if (!enabled) return { ...transition.disabledColor };- if (pressed) return { ...transition.pressedColor };- if (hovered) return { ...transition.hoveredColor };- return { ...transition.normalColor };-}--const TINT_HOVER = 1.15;-const TINT_PRESSED = 0.75;-const TINT_DISABLED = 0.5;-const TINT_DISABLED_ALPHA = 0.6;--export function applyDefaultTint(- baseColor: Color,- enabled: boolean,- pressed: boolean,- hovered: boolean,-): Color {- if (!enabled) {- return {- r: baseColor.r * TINT_DISABLED,- g: baseColor.g * TINT_DISABLED,- b: baseColor.b * TINT_DISABLED,- a: baseColor.a * TINT_DISABLED_ALPHA,- };- }- if (pressed) {- return {- r: baseColor.r * TINT_PRESSED,- g: baseColor.g * TINT_PRESSED,- b: baseColor.b * TINT_PRESSED,- a: baseColor.a,- };- }- if (hovered) {- return {- r: Math.min(1, baseColor.r * TINT_HOVER),- g: Math.min(1, baseColor.g * TINT_HOVER),- b: Math.min(1, baseColor.b * TINT_HOVER),- a: baseColor.a,- };- }- return { ...baseColor };-}-export function isWordChar(code: number): boolean {return (code >= 0x41 && code <= 0x5A)|| (code >= 0x61 && code <= 0x7A)@@ -80,51 +26,6 @@ export function isWordChar(code: number): boolean {|| code === 0x5F;}-export function wrapText(- ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,- text: string,- maxWidth: number,-): string[] {- if (!text) return [''];- if (maxWidth <= 0) return text.split('\n');- const paragraphs = text.split('\n');- const lines: string[] = [];- for (const paragraph of paragraphs) {- if (!paragraph) { lines.push(''); continue; }- let currentLine = '';- for (let i = 0; i < paragraph.length; i++) {- const char = paragraph[i];- const testLine = currentLine + char;- if (ctx.measureText(testLine).width > maxWidth && currentLine) {- const code = char.charCodeAt(0);- if (isWordChar(code) && currentLine.length > 0 && isWordChar(currentLine.charCodeAt(currentLine.length - 1))) {- let breakPos = -1;- for (let j = currentLine.length - 1; j >= 0; j--) {- if (!isWordChar(currentLine.charCodeAt(j))) {- breakPos = j;- break;- }- }- if (breakPos >= 0) {- lines.push(currentLine.substring(0, breakPos + 1));- currentLine = currentLine.substring(breakPos + 1) + char;- } else {- lines.push(currentLine);- currentLine = char;- }- } else {- lines.push(currentLine);- currentLine = char;- }- } else {- currentLine = testLine;- }- }- if (currentLine) lines.push(currentLine);- }- return lines.length > 0 ? lines : [''];-}-export function nextPowerOf2(n: number): number {let p = 1;while (p < n) p *= 2;@@ -161,36 +62,6 @@ export function getUINodeHeight(entity: Entity): number {}-export function syncFillSpriteSize(- world: World,- fillEntity: Entity,- direction: number,- normalizedValue: number,- sliderW: number,- sliderH: number,-): void {- if (!world.has(fillEntity, Sprite)) return;- const sprite = world.get(fillEntity, Sprite) as SpriteData;- let w: number;- let h: number;- switch (direction) {- case FillDirection.BottomToTop:- case FillDirection.TopToBottom:- w = sliderW;- h = sliderH * normalizedValue;- break;- default:- w = sliderW * normalizedValue;- h = sliderH;- break;- }- if (sprite.size.x !== w || sprite.size.y !== h) {- sprite.size.x = w;- sprite.size.y = h;- world.insert(fillEntity, Sprite, sprite);- }-}-export function walkParentChain(world: World, entity: Entity,callback: (ancestor: Entity) => boolean,@@ -233,77 +104,6 @@ export function ensureUIVisual(world: World, entity: Entity): void {}}-export function makeInteractable(world: World, entity: Entity): void {- ensureComponent(world, entity, Interactable, {- enabled: true,- blockRaycast: true,- raycastTarget: true,- });-}--export function withChildEntity(- world: World,- childId: Entity,- callback: (entity: Entity) => void,-): void {- if (childId !== 0 && world.valid(childId)) {- callback(childId);- }-}--function colorEquals(a: Color, b: Color): boolean {- return a.r === b.r && a.g === b.g && a.b === b.b && a.a === b.a;-}--export function setEntityColor(world: World, entity: Entity, color: Color): void {- if (world.has(entity, Sprite)) {- const s = world.get(entity, Sprite) as SpriteData;- if (!colorEquals(s.color, color)) {- s.color = color;- world.insert(entity, Sprite, s);- }- } else if (world.has(entity, UIVisual)) {- const r = world.get(entity, UIVisual) as UIVisualData;- if (!colorEquals(r.color, color)) {- r.color = color;- world.insert(entity, UIVisual, r);- }- }-}--export function setEntityEnabled(world: World, entity: Entity, enabled: boolean): void {- if (world.has(entity, Sprite)) {- const s = world.get(entity, Sprite) as SpriteData;- if (s.enabled !== enabled) {- s.enabled = enabled;- world.insert(entity, Sprite, s);- }- } else if (world.has(entity, UIVisual)) {- const r = world.get(entity, UIVisual) as UIVisualData;- if (r.enabled !== enabled) {- r.enabled = enabled;- world.insert(entity, UIVisual, r);- }- }-}--export function colorScale(c: Color, factor: number): Color {- return {- r: Math.min(1, c.r * factor),- g: Math.min(1, c.g * factor),- b: Math.min(1, c.b * factor),- a: c.a,- };-}--export function colorWithAlpha(c: Color, alpha: number): Color {- return { r: c.r, g: c.g, b: c.b, a: alpha };-}--export function colorToRgba(c: Color): string {- return `rgba(${Math.round(c.r * 255)}, ${Math.round(c.g * 255)}, ${Math.round(c.b * 255)}, ${c.a})`;-}-export class EntityStateMap<T> {private map_ = new Map<Entity, T>();diff --git a/sdk/src/ui/util/types.ts b/sdk/src/ui/util/types.tsdeleted file mode 100644index f08a8789a..000000000--- a/sdk/src/ui/util/types.ts+++ /dev/null@@ -1,19 +0,0 @@-// SPDX-License-Identifier: Apache-2.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import type { Color } from '../../types';--export interface ColorTransition {- normalColor: Color;- hoveredColor: Color;- pressedColor: Color;- disabledColor: Color;-}--export const FillDirection = {- LeftToRight: 0,- RightToLeft: 1,- BottomToTop: 2,- TopToBottom: 3,-} as const;--export type FillDirection = (typeof FillDirection)[keyof typeof FillDirection];diff --git a/sdk/src/ui/widgets/list-view.ts b/sdk/src/ui/widgets/list-view.tsindex 0015da3c3..b07837cba 100644--- a/sdk/src/ui/widgets/list-view.ts+++ b/sdk/src/ui/widgets/list-view.ts@@ -169,7 +169,7 @@ export function createListView<T>(opts: CreateListViewOptions<T>): ListViewHandlnode: { width: px(viewportSize.x), height: px(viewportSize.y), ...opts.node },visual: opts.background ?? { color: { r: 0, g: 0, b: 0, a: 0 } },});- world.insert(viewport, UIMask, { enabled: true, mode: MaskMode.Scissor, maskTexture: 0, inverted: false });+ world.insert(viewport, UIMask, { enabled: true, mode: MaskMode.Scissor });world.insert(viewport, Interactable, { enabled: true, blockRaycast: true, raycastTarget: true });world.insert(viewport, UIInteraction, { hovered: false, pressed: false, justPressed: false, justReleased: false });diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 3f0de0293..a8ae0d4fc 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -422,10 +422,6 @@ export interface ESEngineModule {uiTree_markDirty(entity: number): void;uiTree_markAllDirty(): void;transform_update(registry: CppRegistry): void;- // Layout anim-override flags (function names predate the UINode rename; they- // now operate on UINode.anim_override_).- uiRect_clearAnimOverrides(registry: CppRegistry): void;- uiRect_setAnimOverride(registry: CppRegistry, entity: number, flags: number): void;transform_patchPosition(registry: CppRegistry, entity: number, x: number, y: number, z: number): void;// Animation (Tween) APIdiff --git a/sdk/tests/default-tint.test.ts b/sdk/tests/default-tint.test.tsdeleted file mode 100644index c454471a4..000000000--- a/sdk/tests/default-tint.test.ts+++ /dev/null@@ -1,80 +0,0 @@-// SPDX-License-Identifier: Apache-2.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import { describe, it, expect } from 'vitest';-import { applyDefaultTint } from '../src/ui/util/helpers';-import type { Color } from '../src/types';--const WHITE: Color = { r: 1, g: 1, b: 1, a: 1 };-const RED: Color = { r: 1, g: 0, b: 0, a: 1 };-const HALF_GRAY: Color = { r: 0.5, g: 0.5, b: 0.5, a: 0.8 };--describe('applyDefaultTint', () => {- it('returns base color unchanged in normal state', () => {- const result = applyDefaultTint(WHITE, true, false, false);- expect(result).toEqual(WHITE);- });-- it('returns a copy, not the same reference', () => {- const result = applyDefaultTint(WHITE, true, false, false);- expect(result).not.toBe(WHITE);- });-- it('brightens on hover', () => {- const result = applyDefaultTint(HALF_GRAY, true, false, true);- expect(result.r).toBeCloseTo(0.5 * 1.15);- expect(result.g).toBeCloseTo(0.5 * 1.15);- expect(result.b).toBeCloseTo(0.5 * 1.15);- expect(result.a).toBe(HALF_GRAY.a);- });-- it('clamps hover tint to 1.0', () => {- const result = applyDefaultTint(WHITE, true, false, true);- expect(result.r).toBe(1);- expect(result.g).toBe(1);- expect(result.b).toBe(1);- });-- it('darkens on press', () => {- const result = applyDefaultTint(WHITE, true, true, false);- expect(result.r).toBeCloseTo(0.75);- expect(result.g).toBeCloseTo(0.75);- expect(result.b).toBeCloseTo(0.75);- expect(result.a).toBe(1);- });-- it('pressed takes priority over hovered', () => {- const result = applyDefaultTint(WHITE, true, true, true);- expect(result.r).toBeCloseTo(0.75);- expect(result.g).toBeCloseTo(0.75);- expect(result.b).toBeCloseTo(0.75);- });-- it('dims and reduces alpha when disabled', () => {- const result = applyDefaultTint(WHITE, false, false, false);- expect(result.r).toBeCloseTo(0.5);- expect(result.g).toBeCloseTo(0.5);- expect(result.b).toBeCloseTo(0.5);- expect(result.a).toBeCloseTo(0.6);- });-- it('disabled takes priority over pressed and hovered', () => {- const result = applyDefaultTint(WHITE, false, true, true);- expect(result.r).toBeCloseTo(0.5);- expect(result.a).toBeCloseTo(0.6);- });-- it('applies multiplicatively to non-white base color', () => {- const result = applyDefaultTint(RED, true, true, false);- expect(result.r).toBeCloseTo(0.75);- expect(result.g).toBe(0);- expect(result.b).toBe(0);- });-- it('applies disabled tint multiplicatively to dark color', () => {- const result = applyDefaultTint(HALF_GRAY, false, false, false);- expect(result.r).toBeCloseTo(0.25);- expect(result.g).toBeCloseTo(0.25);- expect(result.b).toBeCloseTo(0.25);- expect(result.a).toBeCloseTo(0.48);- });-});diff --git a/sdk/tests/ui-util-helpers.test.ts b/sdk/tests/ui-util-helpers.test.tsindex a2647e72b..93cd05271 100644--- a/sdk/tests/ui-util-helpers.test.ts+++ b/sdk/tests/ui-util-helpers.test.ts@@ -1,26 +1,17 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file The pure, world-free helpers in ui/util/helpers: word-aware text- * wrapping, power-of-two rounding, colour math, and the entity/state map- * cleanup. wrapText in particular carries real branching (word boundary- * vs. hard break vs. paragraph split) that nothing exercised directly.+ * @file The pure, world-free helpers in ui/util/helpers: word-boundary+ * classification, power-of-two rounding, and the entity/state map+ * cleanup.*/import { describe, it, expect } from 'vitest';import {isWordChar,- wrapText,nextPowerOf2,- colorScale,- colorWithAlpha,- colorToRgba,EntityStateMap,} from '../src/ui/util/helpers';-import type { Color, Entity } from '../src/types';--// A deterministic text metric: every glyph is 10 units wide, so a maxWidth of N-// means "at most N/10 characters per line" — no real font or canvas required.-const ctx = { measureText: (s: string) => ({ width: s.length * 10 }) } as unknown as CanvasRenderingContext2D;+import type { Entity } from '../src/types';describe('isWordChar', () => {it('accepts letters, digits and underscore; rejects space and punctuation', () => {@@ -34,38 +25,6 @@ describe('isWordChar', () => {});});-describe('wrapText', () => {- it('returns a single empty line for empty input', () => {- expect(wrapText(ctx, '', 100)).toEqual(['']);- });-- it('does not wrap when everything fits', () => {- expect(wrapText(ctx, 'abc', 100)).toEqual(['abc']); // 30 < 100- });-- it('splits on hard newlines, preserving blank paragraphs', () => {- expect(wrapText(ctx, 'ab\ncd', 100)).toEqual(['ab', 'cd']);- expect(wrapText(ctx, 'ab\n\ncd', 100)).toEqual(['ab', '', 'cd']);- });-- it('treats maxWidth <= 0 as "newlines only", never measuring', () => {- expect(wrapText(ctx, 'abcdef', 0)).toEqual(['abcdef']);- expect(wrapText(ctx, 'ab\ncd', -5)).toEqual(['ab', 'cd']);- });-- it('hard-breaks a single word with no break opportunity', () => {- // 8 glyphs, 3 per line → 3/3/2.- expect(wrapText(ctx, 'aaaaaaaa', 30)).toEqual(['aaa', 'aaa', 'aa']);- });-- it('breaks at a word boundary and keeps every character', () => {- const lines = wrapText(ctx, 'alpha beta', 50); // 5 glyphs/line- expect(lines.length).toBeGreaterThan(1);- expect(lines.join('').replace(/\s/g, '')).toBe('alphabeta'); // no glyph lost- expect(lines[0]).toBe('alpha'); // the first word survives intact on line 1- });-});-describe('nextPowerOf2', () => {it('rounds up to the next power of two (and is idempotent on exact powers)', () => {expect(nextPowerOf2(1)).toBe(1);@@ -77,24 +36,6 @@ describe('nextPowerOf2', () => {});});-describe('colour helpers', () => {- const c: Color = { r: 0.4, g: 0.5, b: 0.6, a: 0.8 };-- it('colorScale multiplies rgb, clamps to 1, and preserves alpha', () => {- expect(colorScale(c, 0.5)).toEqual({ r: 0.2, g: 0.25, b: 0.3, a: 0.8 });- const bright = colorScale({ r: 0.8, g: 0.9, b: 1, a: 0.5 }, 2);- expect(bright).toEqual({ r: 1, g: 1, b: 1, a: 0.5 }); // clamped, alpha untouched- });-- it('colorWithAlpha replaces only alpha', () => {- expect(colorWithAlpha(c, 0.1)).toEqual({ r: 0.4, g: 0.5, b: 0.6, a: 0.1 });- });-- it('colorToRgba rounds rgb to 0..255 and passes alpha through raw', () => {- expect(colorToRgba({ r: 1, g: 0, b: 0.5, a: 0.25 })).toBe('rgba(255, 0, 128, 0.25)');- });-});-describe('EntityStateMap', () => {it('stores and retrieves per-entity state', () => {const m = new EntityStateMap<string>();diff --git a/src/esengine/animation/TweenSystem.cpp b/src/esengine/animation/TweenSystem.cppindex 6bf8c16dc..84f73760e 100644--- a/src/esengine/animation/TweenSystem.cpp+++ b/src/esengine/animation/TweenSystem.cpp@@ -16,6 +16,11 @@ namespace esengine::animation {void TweenSystem::update(ecs::Registry& registry, f32 deltaTime) {pending_remove_.clear();+ for (auto entity : ui_flagged_) {+ if (auto* n = registry.tryGet<ecs::UINode>(entity)) n->anim_override_ = 0;+ }+ ui_flagged_.clear();+for (auto entity : registry.view<TweenData>()) {auto& tween = registry.get<TweenData>(entity);@@ -133,23 +138,28 @@ void TweenSystem::resumeTween(ecs::Registry& registry, Entity tweenEntity) {// per-field semantics exactly: rotation.z → half-angle quaternion, and the UINode// `anim_override_` flags so UI layout doesn't clobber animated Transform fields.// Flag the entity's UINode so the layout pass leaves the tween-driven Transform-// field alone this frame.-static void markUIAnimOverride(ecs::Registry& registry, Entity entity, u8 flag) {- if (auto* n = registry.tryGet<ecs::UINode>(entity)) n->anim_override_ |= flag;+// field alone this frame; `flagged` remembers the entity for next frame's clear.+static void markUIAnimOverride(ecs::Registry& registry, Entity entity, u8 flag,+ std::vector<Entity>& flagged) {+ if (auto* n = registry.tryGet<ecs::UINode>(entity)) {+ if (n->anim_override_ == 0) flagged.push_back(entity);+ n->anim_override_ |= flag;+ }}-static void applyTweenValue(ecs::Registry& registry, Entity entity, TweenTarget target, f32 value) {+static void applyTweenValue(ecs::Registry& registry, Entity entity, TweenTarget target, f32 value,+ std::vector<Entity>& flagged) {switch (target) {case TweenTarget::TransformPositionX:if (auto* c = registry.tryGet<ecs::Transform>(entity)) {c->position.x = value;- markUIAnimOverride(registry, entity, ecs::UINode::ANIM_POS_X);+ markUIAnimOverride(registry, entity, ecs::UINode::ANIM_POS_X, flagged);}break;case TweenTarget::TransformPositionY:if (auto* c = registry.tryGet<ecs::Transform>(entity)) {c->position.y = value;- markUIAnimOverride(registry, entity, ecs::UINode::ANIM_POS_Y);+ markUIAnimOverride(registry, entity, ecs::UINode::ANIM_POS_Y, flagged);}break;case TweenTarget::TransformPositionZ:@@ -158,20 +168,20 @@ static void applyTweenValue(ecs::Registry& registry, Entity entity, TweenTargetcase TweenTarget::TransformScaleX:if (auto* c = registry.tryGet<ecs::Transform>(entity)) {c->scale.x = value;- markUIAnimOverride(registry, entity, ecs::UINode::ANIM_SCALE_X);+ markUIAnimOverride(registry, entity, ecs::UINode::ANIM_SCALE_X, flagged);}break;case TweenTarget::TransformScaleY:if (auto* c = registry.tryGet<ecs::Transform>(entity)) {c->scale.y = value;- markUIAnimOverride(registry, entity, ecs::UINode::ANIM_SCALE_Y);+ markUIAnimOverride(registry, entity, ecs::UINode::ANIM_SCALE_Y, flagged);}break;case TweenTarget::TransformRotationZ:if (auto* c = registry.tryGet<ecs::Transform>(entity)) {f32 h = value * 0.5f;c->rotation = glm::quat(std::cos(h), 0.0f, 0.0f, std::sin(h));- markUIAnimOverride(registry, entity, ecs::UINode::ANIM_ROT_Z);+ markUIAnimOverride(registry, entity, ecs::UINode::ANIM_ROT_Z, flagged);}break;case TweenTarget::SpriteColorR:@@ -205,7 +215,7 @@ void TweenSystem::applyValue(ecs::Registry& registry, const TweenData& tween, f3if (!registry.valid(target)) {return;}- applyTweenValue(registry, target, tween.target_property, value);+ applyTweenValue(registry, target, tween.target_property, value, ui_flagged_);}f32 TweenSystem::evaluateEasing(const TweenData& tween, f32 t) {diff --git a/src/esengine/animation/TweenSystem.hpp b/src/esengine/animation/TweenSystem.hppindex 4674c22b3..938cb65a4 100644--- a/src/esengine/animation/TweenSystem.hpp+++ b/src/esengine/animation/TweenSystem.hpp@@ -28,6 +28,9 @@ private:f32 evaluateEasing(const TweenData& tween, f32 t);std::vector<Entity> pending_remove_;+ // UINode entities whose anim_override_ flags were set this frame; cleared at+ // the start of the next update so layout regains the field once a tween ends.+ std::vector<Entity> ui_flagged_;};} // namespace esengine::animationdiff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex c5440466f..1da8b58da 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -798,20 +798,6 @@ void transform_update(ecs::Registry& registry) {}}-// Per-frame clear of UINode tween anim-override flags (set by the tween system,-// read by the layout pass). Name kept (ui_*) for the TS binding.-void uiRect_clearAnimOverrides(ecs::Registry& registry) {- for (auto entity : registry.view<ecs::UINode>()) {- registry.get<ecs::UINode>(entity).anim_override_ = 0;- }-}--void uiRect_setAnimOverride(ecs::Registry& registry, u32 entity, u8 flags) {- if (auto* n = registry.tryGet<ecs::UINode>(Entity::fromRaw(entity))) {- n->anim_override_ |= flags;- }-}-void transform_patchPosition(ecs::Registry& registry, u32 entity,f32 x, f32 y, f32 z) {auto* transform = registry.tryGet<ecs::Transform>(Entity::fromRaw(entity));@@ -840,8 +826,6 @@ EMSCRIPTEN_BINDINGS(esengine_ui_systems) {emscripten::function("uiTree_markDirty", &esengine::uiTree_markDirty);emscripten::function("uiTree_markAllDirty", &esengine::uiTree_markAllDirty);emscripten::function("transform_update", &esengine::transform_update);- emscripten::function("uiRect_clearAnimOverrides", &esengine::uiRect_clearAnimOverrides);- emscripten::function("uiRect_setAnimOverride", &esengine::uiRect_setAnimOverride);emscripten::function("transform_patchPosition", &esengine::transform_patchPosition);}