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): a text field can be skinned, aligned, and drawn in the game's font
yhh50cd0f926bd1
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 607efca11..fbb93aa3c 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -6781,6 +6781,7 @@ color: ColorcursorPos: numberdirty: booleanfocused: boolean+font: numberfontFamily: stringfontSize: numbermaxLength: number@@ -6791,6 +6792,7 @@ placeholder: stringplaceholderColor: ColorreadOnly: booleanrenderMode: TextRenderMode+textAlign: TextAlignvalue: string```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex dc3f54739..a03ef42e2 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -6945,6 +6945,7 @@ color: ColorcursorPos: numberdirty: booleanfocused: boolean+font: numberfontFamily: stringfontSize: numbermaxLength: number@@ -6955,6 +6956,7 @@ placeholder: stringplaceholderColor: ColorreadOnly: booleanrenderMode: TextRenderMode+textAlign: TextAlignvalue: string```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex be4c816d2..965f2b12a 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -6776,6 +6776,7 @@ color: ColorcursorPos: numberdirty: booleanfocused: boolean+font: numberfontFamily: stringfontSize: numbermaxLength: number@@ -6786,6 +6787,7 @@ placeholder: stringplaceholderColor: ColorreadOnly: booleanrenderMode: TextRenderMode+textAlign: TextAlignvalue: string```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 53e3bcce7..04cd57d45 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -6991,6 +6991,7 @@ color: ColorcursorPos: numberdirty: booleanfocused: boolean+font: numberfontFamily: stringfontSize: numbermaxLength: number@@ -7001,6 +7002,7 @@ placeholder: stringplaceholderColor: ColorreadOnly: booleanrenderMode: TextRenderMode+textAlign: TextAlignvalue: string```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 1865dfe78..52e1ced45 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -6783,6 +6783,7 @@ color: ColorcursorPos: numberdirty: booleanfocused: boolean+font: numberfontFamily: stringfontSize: numbermaxLength: number@@ -6793,6 +6794,7 @@ placeholder: stringplaceholderColor: ColorreadOnly: booleanrenderMode: TextRenderMode+textAlign: TextAlignvalue: string```diff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.tsindex 191a42dc2..0af369c49 100644--- a/sdk/src/ui/text/text-input-plugin.ts+++ b/sdk/src/ui/text/text-input-plugin.ts@@ -23,9 +23,11 @@ import { px } from '../core/dimension';import { SdfTextRenderer } from './text-renderer';import type { ESEngineModule } from '../../wasm';import { measureWidth } from './layout';+import { resolveTextFamily } from './font-registry';import {textFieldDisplay, maskedPrefix, fieldSelection, nearestCaretIndex,- splitLines, caretLineCol, lineSelections, imeAnchorCss, type TextFieldDisplay,+ splitLines, caretLineCol, lineSelections, imeAnchorCss, alignOffset,+ type TextFieldDisplay,} from './text-input-view';import { uiWorldToScreen } from '../util/ui-pick';import { platformCreateTextEditor, platformDevicePixelRatio } from '../../platform';@@ -82,6 +84,10 @@ export class TextInputPlugin implements Plugin {// The render system's horizontal scroll per field, read by click-to-caret// (Update) to map a pointer x back to a character index under the scroll.const scrollXOf = new Map<Entity, number>();+ // And the alignment offset it drew at, for the same reason: a click in a+ // centred field lands on the glyph that is there, not on the one that+ // would have been there had the value been left-aligned.+ const alignOffsetOf = new Map<Entity, number>();let measureRenderer: SdfTextRenderer | null = null;const ensureMeasure = (): SdfTextRenderer => {if (!measureRenderer) measureRenderer = new SdfTextRenderer(module);@@ -189,7 +195,13 @@ export class TextInputPlugin implements Plugin {const fieldLeft = tr.worldPosition.x - width / 2;const val = editor!.read().value; // focused ⇒ the surface is the value sourceconst atlas = ensureMeasure().atlas;- const mw = (s: string): number => measureWidth(s, atlas, ti.fontFamily, ti.fontSize, 0);+ // The family the child Text will actually rasterize with. The caret is+ // placed by measuring, so measuring with a different font than the one on+ // screen puts it between the wrong glyphs.+ const family = resolveTextFamily(ti.font, ti.fontFamily);+ const mw = (s: string): number => measureWidth(s, atlas, family, ti.fontSize, 0);++ const innerW = Math.max(0, width - 2 * ti.padding);if (ti.multiline) {const height = getUINodeHeight(entity);@@ -199,14 +211,20 @@ export class TextInputPlugin implements Plugin {const lines = splitLines(val);const li = Math.max(0, Math.min(Math.floor(localY / lineH), lines.length - 1));const line = lines[li];- const textX = cam.worldMouseX - fieldLeft - ti.padding;+ // Each line carries its own alignment offset, so undo THIS line's.+ const textX = cam.worldMouseX - fieldLeft - ti.padding+ - alignOffset(ti.textAlign, innerW, mw(line.text));const prefixes: number[] = [];for (let i = 0; i <= line.text.length; i++) prefixes.push(mw(line.text.slice(0, i)));return line.start + nearestCaretIndex(prefixes, textX);}const scrollX = scrollXOf.get(entity) ?? 0;- const textX = cam.worldMouseX - fieldLeft - ti.padding + scrollX;+ // The offset the render pass actually drew at, not one recomputed here:+ // a focused field's value can differ from what was last drawn, and a+ // guess about the offset lands the caret on the wrong glyph.+ const ao = alignOffsetOf.get(entity) ?? 0;+ const textX = cam.worldMouseX - fieldLeft - ti.padding - ao + scrollX;const prefixes: number[] = [];for (let i = 0; i <= val.length; i++) {prefixes.push(mw(maskedPrefix(val, i, ti.password, PASSWORD_CHAR)));@@ -340,6 +358,8 @@ export class TextInputPlugin implements Plugin {if (world.valid(ch.text)) world.despawn(ch.text);if (world.valid(ch.caret)) world.despawn(ch.caret);childrenOf.delete(e);+ scrollXOf.delete(e);+ alignOffsetOf.delete(e);}}@@ -368,7 +388,8 @@ export class TextInputPlugin implements Plugin {const disp = textFieldDisplay(val, ti.password, ti.placeholder, PASSWORD_CHAR);const atlas = ensureMeasure().atlas;- const mw = (s: string): number => measureWidth(s, atlas, ti.fontFamily, ti.fontSize, 0);+ const family = resolveTextFamily(ti.font, ti.fontFamily);+ const mw = (s: string): number => measureWidth(s, atlas, family, ti.fontSize, 0);const innerW = Math.max(0, w - 2 * ti.padding);const vCenter = Math.max(0, (h - ti.fontSize) / 2);@@ -377,20 +398,26 @@ export class TextInputPlugin implements Plugin {// vertically; multiline stacks lines from the top (no h-scroll)// and positions the caret on its \n-broken line. A selection that// spans multiple visual lines shows the caret only for now.- let caretX: number, caretTop: number, scrollX: number;+ let caretX: number, caretTop: number, scrollX: number, ao: number;let sshow = false, sx = 0, stop = 0, sw = 0;if (ti.multiline) {const lineH = ti.fontSize * TEXT_INPUT_LINE_HEIGHT_RATIO;scrollX = 0;+ // Every line aligns in the box on its own, so the child Text+ // does it and there is nothing to shift the whole block by.+ // The caret follows its own line's offset.+ ao = 0;const lc = caretLineCol(val, sel.caret);- caretX = ti.padding + mw(val.slice(lc.lineStart, sel.caret));+ const lineOf = (i: number): string => splitLines(val)[i]?.text ?? '';+ const lineAo = (i: number): number => alignOffset(ti.textAlign, innerW, mw(lineOf(i)));+ caretX = ti.padding + lineAo(lc.line) + mw(val.slice(lc.lineStart, sel.caret));caretTop = lc.line * lineH;// Highlight a selection that stays on one visual line; a// multi-line range shows the caret only for now.const rows = sel.hasRange ? lineSelections(val, sel.lo, sel.hi) : [];if (rows.length === 1) {const line = splitLines(val)[rows[0].line];- sx = ti.padding + mw(line.text.slice(0, rows[0].from));+ sx = ti.padding + lineAo(rows[0].line) + mw(line.text.slice(0, rows[0].from));sw = mw(line.text.slice(rows[0].from, rows[0].to));stop = rows[0].line * lineH;sshow = true;@@ -398,20 +425,22 @@ export class TextInputPlugin implements Plugin {} else {const caretRaw = mw(maskedPrefix(val, sel.caret, ti.password, PASSWORD_CHAR));scrollX = Math.max(0, caretRaw - innerW);- caretX = ti.padding + caretRaw - scrollX;+ ao = alignOffset(ti.textAlign, innerW, mw(disp.text));+ caretX = ti.padding + ao + caretRaw - scrollX;caretTop = vCenter;if (sel.hasRange) {const lo = mw(maskedPrefix(val, sel.lo, ti.password, PASSWORD_CHAR));- sx = ti.padding + lo - scrollX;+ sx = ti.padding + ao + lo - scrollX;sw = mw(maskedPrefix(val, sel.hi, ti.password, PASSWORD_CHAR)) - lo;stop = vCenter;sshow = true;}}scrollXOf.set(entity, scrollX);+ alignOffsetOf.set(entity, ao);syncSelChild(ch.sel, ti, sshow, sx, stop, sw);- syncTextChild(ch.text, ti, disp, innerW, scrollX);+ syncTextChild(ch.text, ti, disp, innerW, scrollX, ao);// The blinking caret hides while a highlight is drawn.syncCaretChild(ch.caret, ti, caretX, caretTop, ti.focused && cursorVisible && !sshow);@@ -442,10 +471,15 @@ export class TextInputPlugin implements Plugin {return;}const bg = world.get(entity, UIVisual) as UIVisualData;+ // A visual that is not a plain fill was put there on purpose — the+ // 9-sliced frame every skinned input field in every UI pack is drawn+ // with. `backgroundColor` is the fallback for a field nobody skinned,+ // so it stops at the fill it owns instead of flattening the art every+ // frame. A field authored with a frame keeps its frame.+ if (bg.visualType !== UIVisualType.SolidColor) return;const c = ti.backgroundColor;- if (bg.visualType !== UIVisualType.SolidColor || !bg.enabled+ if (!bg.enabled|| bg.color.r !== c.r || bg.color.g !== c.g || bg.color.b !== c.b || bg.color.a !== c.a) {- bg.visualType = UIVisualType.SolidColor;bg.color = { ...c };bg.enabled = true;world.insert(entity, UIVisual, bg);@@ -469,7 +503,7 @@ export class TextInputPlugin implements Plugin {// under the Scissor mask instead of being pinned to the box.node: { position: UIPositionType.Absolute, insetLeft: pad, insetTop: px(0), insetBottom: px(0), width: px(0) },text: {- content: '', fontFamily: ti.fontFamily, fontSize: ti.fontSize,+ content: '', font: ti.font, fontFamily: ti.fontFamily, fontSize: ti.fontSize,align: TextAlign.Left, verticalAlign: TextVerticalAlign.Middle, wordWrap: ti.multiline,renderMode: ti.renderMode,},@@ -502,29 +536,37 @@ export class TextInputPlugin implements Plugin {}}- function syncTextChild(textEntity: Entity, ti: TextInputData, disp: TextFieldDisplay, innerW: number, scrollX: number): void {+ function syncTextChild(textEntity: Entity, ti: TextInputData, disp: TextFieldDisplay, innerW: number, scrollX: number, ao: number): void {const t = world.get(textEntity, Text) as TextData;const show = disp.text;const col = disp.isPlaceholder ? ti.placeholderColor : ti.color;// Multiline stacks lines from the top so caret line math lines up;// single-line centers the one line in the box.const vAlign = ti.multiline ? TextVerticalAlign.Top : TextVerticalAlign.Middle;- if (t.content !== show || t.fontFamily !== ti.fontFamily || t.fontSize !== ti.fontSize+ // Multiline aligns per line, which only the text layout can do, so it+ // owns the alignment there. A single line is aligned by the offset the+ // caret and the hit-test share, so its box stays Left.+ const hAlign = ti.multiline ? ti.textAlign : TextAlign.Left;+ if (t.content !== show || t.font !== ti.font || t.fontFamily !== ti.fontFamily || t.fontSize !== ti.fontSize|| t.wordWrap !== ti.multiline || t.renderMode !== ti.renderMode || t.verticalAlign !== vAlign+ || t.align !== hAlign|| t.color.r !== col.r || t.color.g !== col.g || t.color.b !== col.b || t.color.a !== col.a) {t.content = show;+ t.font = ti.font;t.fontFamily = ti.fontFamily;t.fontSize = ti.fontSize;t.wordWrap = ti.multiline;t.verticalAlign = vAlign;+ t.align = hAlign;t.renderMode = ti.renderMode;t.color = { ...col };world.insert(textEntity, Text, t);}- // Slide the text box by the scroll offset; width = the inner box (a- // single line overflows it rightward and the Scissor mask clips).+ // Slide the text box by the alignment offset and the scroll; width = the+ // inner box (a single line overflows it rightward and the Scissor mask+ // clips).const node = world.get(textEntity, UINode) as UINodeData;- const left = ti.padding - scrollX;+ const left = ti.padding + ao - scrollX;if (node.insetLeft.value !== left || node.width.value !== innerW) {node.insetLeft = px(left);node.width = px(innerW);diff --git a/sdk/src/ui/text/text-input-view.ts b/sdk/src/ui/text/text-input-view.tsindex aac5b64fb..1798aa5c4 100644--- a/sdk/src/ui/text/text-input-view.ts+++ b/sdk/src/ui/text/text-input-view.ts@@ -152,3 +152,22 @@ export function lineSelections(value: string, lo: number, hi: number): Array<{ l}return out;}++/**+ * How far into the inner box a line of `textW` starts, for `align` in `innerW`.+ *+ * A single-line field realizes its alignment through this offset rather than+ * through its child Text's own `align`, because the text layout aligns WITHOUT a+ * clamp: a value wider than the box would be centred and overflow both edges,+ * fighting the horizontal scroll that exists to keep the caret in view. Clamped+ * at zero, a field holds its alignment while the value is short and behaves+ * exactly as a left-aligned one once the value fills the box.+ *+ * It lives here because three things have to agree about it — where the glyphs+ * are drawn, where the caret and selection rect go, and which character a click+ * lands on. Align is 0 left / 1 center / 2 right, matching TextAlign.+ */+export function alignOffset(align: number, innerW: number, textW: number): number {+ const slack = Math.max(0, innerW - textW);+ return align === 1 ? slack / 2 : align === 2 ? slack : 0;+}diff --git a/sdk/src/ui/text/text-input.ts b/sdk/src/ui/text/text-input.tsindex 83e216ca3..dafecdcbc 100644--- a/sdk/src/ui/text/text-input.ts+++ b/sdk/src/ui/text/text-input.ts@@ -2,12 +2,16 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { defineComponent, enumOptions } from '../../ecs/component';import type { Color } from '../../types';-import { TextRenderMode } from '../core/text';+import { TextAlign, TextRenderMode } from '../core/text';export interface TextInputData {value: string;placeholder: string;placeholderColor: Color;+ /** A font asset the game SHIPS. When set it wins over {@link fontFamily},+ * exactly as `Text.font` does — a field on a skinned panel is drawn in the+ * game's own typeface, not in whatever the host happens to have. */+ font: number;fontFamily: string;fontSize: number;color: Color;@@ -20,6 +24,10 @@ export interface TextInputData {focused: boolean;cursorPos: number;dirty: boolean;+ /** Where the value sits in the field: Left, Center or Right. A single line+ * keeps the alignment only while it fits — past that the field scrolls to+ * follow the caret, as a left-aligned one always has. */+ textAlign: TextAlign;/** Glyph pipeline for the field text — mirrors Text.renderMode, propagated to* the child Text the input plugin renders through (Auto / Bitmap / Sdf). */renderMode: TextRenderMode;@@ -29,6 +37,7 @@ export const TextInput = defineComponent<TextInputData>('TextInput', {value: '',placeholder: '',placeholderColor: { r: 0.6, g: 0.6, b: 0.6, a: 1 },+ font: 0,fontFamily: 'Arial',fontSize: 16,color: { r: 1, g: 1, b: 1, a: 1 },@@ -41,9 +50,17 @@ export const TextInput = defineComponent<TextInputData>('TextInput', {focused: false,cursorPos: 0,dirty: true,+ textAlign: TextAlign.Left,renderMode: TextRenderMode.Auto,}, {+ assetFields: [{ field: 'font', type: 'font' }],fields: {+ font: { label: 'Font', tooltip: 'A font file this project ships (.ttf / .otf). Overrides Font Family when set; leave empty to use a font the host already has.' },+ fontFamily: { tooltip: 'A font the HOST already has (system or page-loaded). Ignored when Font is set.' },+ textAlign: {+ enum: enumOptions(TextAlign),+ tooltip: 'Where the value sits in the field. A single line holds the alignment while it fits, then scrolls to follow the caret.',+ },renderMode: {enum: enumOptions(TextRenderMode),tooltip: 'Glyph pipeline for the field text — Auto (hinted bitmap when unscaled, SDF once scaled), always Bitmap, or always SDF.',diff --git a/sdk/tests/ui-text-input-view.test.ts b/sdk/tests/ui-text-input-view.test.tsindex ce657806d..b1266ec6e 100644--- a/sdk/tests/ui-text-input-view.test.ts+++ b/sdk/tests/ui-text-input-view.test.ts@@ -11,7 +11,7 @@*/import { describe, it, expect } from 'vitest';import {- textFieldDisplay, maskedPrefix, fieldSelection, nearestCaretIndex,+ textFieldDisplay, maskedPrefix, fieldSelection, nearestCaretIndex, alignOffset,splitLines, caretLineCol, lineSelections, imeAnchorCss,} from '../src/ui/text/text-input-view';@@ -190,3 +190,28 @@ describe('imeAnchorCss', () => {expect(imeAnchorCss(200, 100, 600, 0)).toEqual({ left: 200, top: 500 });});});++describe('alignOffset', () => {+ it('leaves a left-aligned line at the start of the box', () => {+ expect(alignOffset(0, 200, 40)).toBe(0);+ expect(alignOffset(0, 200, 400)).toBe(0);+ });++ it('splits the slack for center and hands it all over for right', () => {+ expect(alignOffset(1, 200, 40)).toBe(80);+ expect(alignOffset(2, 200, 40)).toBe(160);+ });++ it('collapses to zero once the line fills the box, so the scroll takes over', () => {+ // The caret has to stay reachable: past the box width the field scrolls,+ // and an offset that kept centring would drag the text off both edges.+ expect(alignOffset(1, 200, 200)).toBe(0);+ expect(alignOffset(1, 200, 500)).toBe(0);+ expect(alignOffset(2, 200, 500)).toBe(0);+ });++ it('survives a degenerate box', () => {+ expect(alignOffset(1, 0, 40)).toBe(0);+ expect(alignOffset(2, -10, 40)).toBe(0);+ });+});