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.

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.ts
index 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.md
index 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 the
top-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.ts
index 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
index 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 Helpers
export {
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.ts
index 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.ts
index 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.ts
index 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.ts
index 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* order
diff --git a/sdk/src/ui/util/constants.ts b/sdk/src/ui/util/constants.ts
index 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.ts
index 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 Team
import { 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.ts
deleted file mode 100644
index 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.ts
index 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>): ListViewHandl
node: { 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.ts
index 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) API
diff --git a/sdk/tests/default-tint.test.ts b/sdk/tests/default-tint.test.ts
deleted file mode 100644
index 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.ts
index 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.cpp
index 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, TweenTarget
case 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, f3
if (!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.hpp
index 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::animation
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 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);
}