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.

perf(ui): measure text caret prefixes in one pass

yhh18b4233046b2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b67926b81..42ea6a7a7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Text caret picking measures long strings once.** Pointer placement in single-line, multiline and password fields accumulates glyph advances in linear time instead of repeatedly measuring every prefix. UTF-16 caret boundaries, glyph scaling, missing glyphs and masked password widths retain their existing positions.
+
- **Disabled text fields reject queued input.** Text input checks effective entity activity and interaction state before accepting editor events, including disabled ancestors, and releases the editing surface on the next update.
- **Removed text fields release OS input focus.** Deleting the focused entity or removing its TextInput component closes the editing surface even though the old component can no longer be updated.
diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.ts
index 98ae68b58..7c14df889 100644
--- a/sdk/src/ui/text/layout.ts
+++ b/sdk/src/ui/text/layout.ts
@@ -229,6 +229,37 @@ export function measureWidth(
return w;
}
+/** UTF-16 prefix widths for caret placement, measured in one pass. */
+export function measurePrefixWidths(
+ text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number, style: number, letterSpacing = 0,
+): number[] {
+ const pixelSize = atlas.pixelSizeFor(fontSizePx);
+ const scale = fontSizePx / pixelSize;
+ const advance = (cp: number): number => {
+ const glyph = atlas.getGlyph(cp, fontFamily, style, pixelSize);
+ return glyph ? glyph.advance * scale + letterSpacing : 0;
+ };
+ const widths = new Array<number>(text.length + 1);
+ widths[0] = 0;
+ let width = 0;
+ for (let i = 0; i < text.length;) {
+ const cp = text.codePointAt(i)!;
+ if (cp > 0xffff) {
+ // A textarea can address the boundary between a surrogate pair.
+ // Match measuring that truncated prefix, without adding it to the
+ // complete code point's advance.
+ widths[i + 1] = width + advance(text.charCodeAt(i));
+ width += advance(cp);
+ i += 2;
+ } else {
+ width += advance(cp);
+ i++;
+ }
+ widths[i] = width;
+ }
+ return widths;
+}
+
/**
* Greedy word-wrap using an arbitrary width `measure` (display px). Breaks at
* spaces; a token wider than the line (long word, or CJK runs with no spaces) is
diff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.ts
index 7fc038006..52ac410de 100644
--- a/sdk/src/ui/text/text-input-plugin.ts
+++ b/sdk/src/ui/text/text-input-plugin.ts
@@ -23,7 +23,7 @@ import { spawnUIEntity } from '../core/compose';
import { px } from '../core/dimension';
import { SdfTextRenderer } from './text-renderer';
import type { ESEngineModule } from '../../wasm';
-import { measureWidth } from './layout';
+import { measureWidth, measurePrefixWidths } from './layout';
import { resolveTextFamily } from './font-registry';
import {
textFieldDisplay, maskedPrefix, fieldSelection, nearestCaretIndex,
@@ -233,8 +233,7 @@ export class TextInputPlugin implements Plugin {
// Each line carries its own alignment offset, so undo THIS line's.
const textX = pointer.x - 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)));
+ const prefixes = measurePrefixWidths(line.text, atlas, family, ti.fontSize, 0);
return line.start + nearestCaretIndex(prefixes, textX);
}
@@ -244,10 +243,8 @@ export class TextInputPlugin implements Plugin {
// guess about the offset lands the caret on the wrong glyph.
const ao = alignOffsetOf.get(entity) ?? 0;
const textX = pointer.x - 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)));
- }
+ const display = ti.password ? PASSWORD_CHAR.repeat(val.length) : val;
+ const prefixes = measurePrefixWidths(display, atlas, family, ti.fontSize, 0);
return nearestCaretIndex(prefixes, textX);
}
diff --git a/sdk/tests/text-caret-prefix-widths.test.ts b/sdk/tests/text-caret-prefix-widths.test.ts
new file mode 100644
index 000000000..7068b7e6c
--- /dev/null
+++ b/sdk/tests/text-caret-prefix-widths.test.ts
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { expect, it, vi } from 'vitest';
+import type { GlyphAtlas } from '../src/ui/text/glyph-atlas';
+import { measurePrefixWidths, measureWidth } from '../src/ui/text/layout';
+import { maskedPrefix, nearestCaretIndex } from '../src/ui/text/text-input-view';
+
+function makeAtlas() {
+ const getGlyph = vi.fn((cp: number) => cp === 0xffff ? null : { advance: cp % 13 + 3 });
+ const atlas = { pixelSizeFor: () => 48, getGlyph } as unknown as GlyphAtlas;
+ return { atlas, getGlyph };
+}
+
+it.each(['', 'Variable widths', '中文输入', 'a😀中🚀b', '\ud83da\ude00', 'a\uffffb', 'e\u0301\t x'])
+('matches every independently measured UTF-16 prefix: %j', text => {
+ const { atlas } = makeAtlas();
+ const actual = measurePrefixWidths(text, atlas, 'test', 24, 1, 0.5);
+ const expected = Array.from({ length: text.length + 1 }, (_, i) =>
+ measureWidth(text.slice(0, i), atlas, 'test', 24, 1, 0.5));
+ expect(actual).toEqual(expected);
+ for (let x = -5; x <= expected.at(-1)! + 5; x += 0.25) {
+ expect(nearestCaretIndex(actual, x)).toBe(nearestCaretIndex(expected, x));
+ }
+});
+
+it('preserves password widths at every textarea index including emoji', () => {
+ const { atlas } = makeAtlas(), value = '密😀码';
+ const actual = measurePrefixWidths('●'.repeat(value.length), atlas, 'test', 24, 0);
+ expect(actual).toEqual(Array.from({ length: value.length + 1 }, (_, i) =>
+ measureWidth(maskedPrefix(value, i, true, '●'), atlas, 'test', 24, 0)));
+});
+
+it.each(['a', '😀'])('bounds glyph reads by UTF-16 length for long %j text', glyph => {
+ const { atlas, getGlyph } = makeAtlas(), text = glyph.repeat(4000);
+ const widths = measurePrefixWidths(text, atlas, 'test', 24, 0);
+ expect(getGlyph).toHaveBeenCalledTimes(text.length);
+ expect(widths).toHaveLength(text.length + 1);
+ expect(widths.at(-1)).toBe(measureWidth(text, atlas, 'test', 24, 0));
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index e59f7dea6..fcd1ed441 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'perf(ui): measure text caret prefixes in one pass':
+ { note: 'Text caret picking measures long strings once.' },
'fix(ui): reject input on disabled text fields':
{ note: 'Disabled text fields reject queued input.' },
'fix(ui): blur removed text input surfaces':