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.

fix(ui): spawnUIEntity keeps every Text field the init names - letterSpacing was dropped (#127)

yhhf66e06c34abb
diff --git a/sdk/src/ui/core/compose.ts b/sdk/src/ui/core/compose.ts
index e494632d4..6c8e04b04 100644
--- a/sdk/src/ui/core/compose.ts
+++ b/sdk/src/ui/core/compose.ts
@@ -11,6 +11,7 @@
*/
import {
Transform,
+ mergeIntoDefaults,
type TransformData,
} from '../../ecs/component';
import type { Entity, Vec2 } from '../../types';
@@ -19,7 +20,7 @@ import type { World } from '../../ecs/world';
import { UINode, UIPositionType, UIDisplay, UIPointerEvents, type UINodeData } from './ui-node';
import { px, auto, type Dimension } from './dimension';
import { UIVisual, UIVisualType, UIVisualFit, FillMethod, FillOrigin, type UIVisualData } from './ui-visual';
-import { Text, TextAlign, TextVerticalAlign, TextRenderMode, type TextData } from './text';
+import { Text, TextAlign, TextVerticalAlign, type TextData } from './text';
/** Identity Transform. Fresh object per call — safe to insert into ECS. */
export function identityTransform(): TransformData {
@@ -141,35 +142,26 @@ export const FILL_AXIS: Record<LinearFillDirection, readonly [FillMethod, FillOr
export interface TextInit extends Partial<TextData> {}
+/**
+ * Where a composed label differs from a bare `Text`: a widget's caption sits
+ * centred in its box on one line at 14px, while an authored `Text` starts as a
+ * top-left paragraph. Everything else is the component's own default.
+ */
+const COMPOSED_TEXT_DEFAULTS: Partial<TextData> = {
+ fontSize: 14,
+ align: TextAlign.Center,
+ verticalAlign: TextVerticalAlign.Middle,
+ wordWrap: false,
+};
+
+/**
+ * Build a full `Text` from a sparse init. It goes through the component's own
+ * `create`, so every field of `TextData` - one added later included - is taken
+ * from the init when given and from the component's defaults when not; nested
+ * records (colours, the box pivot) are fresh copies, never the caller's object.
+ */
export function buildText(init: TextInit = {}): TextData {
- return {
- content: init.content ?? '',
- i18nKey: init.i18nKey ?? '',
- font: init.font ?? 0,
- fontFamily: init.fontFamily ?? '',
- fontSize: init.fontSize ?? 14,
- color: init.color ?? { r: 1, g: 1, b: 1, a: 1 },
- align: init.align ?? TextAlign.Center,
- verticalAlign: init.verticalAlign ?? TextVerticalAlign.Middle,
- wordWrap: init.wordWrap ?? false,
- overflow: init.overflow ?? 0,
- lineHeight: init.lineHeight ?? 1.2,
- bold: init.bold ?? false,
- italic: init.italic ?? false,
- strokeColor: init.strokeColor ?? { r: 0, g: 0, b: 0, a: 1 },
- strokeWidth: init.strokeWidth ?? 0,
- shadowColor: init.shadowColor ?? { r: 0, g: 0, b: 0, a: 1 },
- shadowBlur: init.shadowBlur ?? 0,
- shadowOffsetX: init.shadowOffsetX ?? 0,
- shadowOffsetY: init.shadowOffsetY ?? 0,
- richText: init.richText ?? false,
- renderMode: init.renderMode ?? TextRenderMode.Auto,
- layer: init.layer ?? 0,
- boxWidth: init.boxWidth ?? 0,
- boxHeight: init.boxHeight ?? 0,
- boxPivot: init.boxPivot ?? { x: 0.5, y: 0.5 },
- enabled: init.enabled ?? true,
- };
+ return Text.create(mergeIntoDefaults(COMPOSED_TEXT_DEFAULTS, init));
}
export interface UIEntityInit {
diff --git a/sdk/tests/ui-build-text-fields.test.ts b/sdk/tests/ui-build-text-fields.test.ts
new file mode 100644
index 000000000..e378da85c
--- /dev/null
+++ b/sdk/tests/ui-build-text-fields.test.ts
@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ui-build-text-fields.test.ts
+ * @brief buildText / spawnUIEntity carry every Text field the init names.
+ *
+ * buildText used to list Text's fields by hand, and the list fell behind
+ * the component: letterSpacing and underline were accepted by TextInit,
+ * shown in the inspector, and silently dropped (issue #127). It now goes
+ * through Text.create, so a field added to Text cannot be left out.
+ */
+import { describe, it, expect } from 'vitest';
+import { World } from '../src/ecs/world';
+import { ensureBuiltinComponentsRegistered } from '../src/ecs/component';
+import { createMockModule } from './mocks/wasm';
+import { Text, TextAlign, TextVerticalAlign, buildText, spawnUIEntity, type TextData } from '../src/ui';
+
+describe('buildText', () => {
+ it('keeps letterSpacing through spawnUIEntity (issue #127)', () => {
+ ensureBuiltinComponentsRegistered();
+ const module = createMockModule();
+ const world = new World();
+ world.connectCpp(module.getRegistry(), module);
+ const e = spawnUIEntity({ world, text: { content: 'PERFECT MOMENT', fontSize: 40, letterSpacing: 8 } });
+ const t = world.get(e, Text) as TextData;
+ expect(t.letterSpacing).toBe(8);
+ expect(t.fontSize).toBe(40);
+ });
+
+ it('produces every field of Text, and takes each one from the init', () => {
+ const fields = Object.keys(Text._default as object).sort();
+ expect(Object.keys(buildText()).sort()).toEqual(fields);
+ // A value unlike the default for every field: none may come back as the default.
+ const def = Text._default as unknown as Record<string, unknown>;
+ const init: Record<string, unknown> = {};
+ for (const k of fields) {
+ const v = def[k];
+ if (typeof v === 'number') init[k] = v + 3;
+ else if (typeof v === 'boolean') init[k] = !v;
+ else if (typeof v === 'string') init[k] = `${v}x`;
+ else init[k] = Object.fromEntries(Object.keys(v as object).map((c) => [c, 0.25]));
+ }
+ expect(buildText(init as Partial<TextData>)).toEqual(init);
+ });
+
+ it('keeps the composed label defaults: centred, one line, 14px', () => {
+ const t = buildText();
+ expect(t.fontSize).toBe(14);
+ expect(t.align).toBe(TextAlign.Center);
+ expect(t.verticalAlign).toBe(TextVerticalAlign.Middle);
+ expect(t.wordWrap).toBe(false);
+ expect(t.letterSpacing).toBe(0);
+ expect(t.underline).toBe(false);
+ });
+
+ it('copies nested records instead of holding the caller\'s object', () => {
+ const color = { r: 1, g: 0, b: 0, a: 1 };
+ const t = buildText({ color });
+ expect(t.color).toEqual(color);
+ expect(t.color).not.toBe(color);
+ expect(buildText().color).not.toBe(buildText().color);
+ });
+
+ it('treats an undefined field as not given', () => {
+ expect(buildText({ fontSize: undefined, letterSpacing: undefined }).fontSize).toBe(14);
+ });
+});