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.

feat(ui): click-to-position caret in a text field

yhh6b9b9aa8a759
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdx
index 19cf56848..028b911be 100644
--- a/docs/astro/src/content/docs/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/guides/ui-components.mdx
@@ -341,11 +341,11 @@ Click (or Tab to) the field to focus it; **Escape** blurs, **Enter** fires
horizontally** so the caret stays in view as you type.
Editing is backed by a hidden native `<textarea>`, so caret movement and
-**selection come for free**: arrows / Home / End move the caret, **Shift +
-arrows** (or **Ctrl/⌘ + A**) select a range — drawn as a highlight behind the
-text — and the platform clipboard (cut / copy / paste) works. The field mirrors
-that native selection each frame, so it always matches what a native input would
-do.
+**selection come for free**: **click** to place the caret at that character,
+arrows / Home / End move it, **Shift + arrows** (or **Ctrl/⌘ + A**) select a
+range — drawn as a highlight behind the text — and the platform clipboard (cut /
+copy / paste) works. The field mirrors that native selection each frame, so it
+always matches what a native input would do.
**IME / CJK input** works: the field drives a hidden native `<textarea>`, so a
Chinese/Japanese/Korean composition renders **live in the field** (the preedit
diff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.ts
index 677b352c8..d58e3a6e3 100644
--- a/sdk/src/ui/text/text-input-plugin.ts
+++ b/sdk/src/ui/text/text-input-plugin.ts
@@ -10,8 +10,10 @@ import { UIVisual, UIVisualType } from '../core/ui-visual';
import type { UIVisualData } from '../core/ui-visual';
import { UIMask, MaskMode } from '../core/ui-mask';
import { Text, TextAlign, TextVerticalAlign, type TextData } from '../core/text';
-import { Interactable } from '../input/interactable';
+import { Interactable, UIInteraction, type UIInteractionData } from '../input/interactable';
import { Focusable, FocusManager, FocusManagerState } from '../input/focusable';
+import { UICameraInfo, type UICameraData } from '../core/ui-camera-info';
+import { Transform, type TransformData } from '../../component';
import { UIEvents, UIEventQueue } from '../core/events';
import { Res } from '../../resource';
import { playModeOnly } from '../../env';
@@ -20,7 +22,7 @@ import { spawnUIEntity } from '../core/compose';
import { px } from '../core/dimension';
import { SdfTextRenderer } from './text-renderer';
import { measureWidth } from './layout';
-import { textFieldDisplay, maskedPrefix, fieldSelection, type TextFieldDisplay } from './text-input-view';
+import { textFieldDisplay, maskedPrefix, fieldSelection, nearestCaretIndex, type TextFieldDisplay } from './text-input-view';
import { CURSOR_BLINK_INTERVAL } from '../util/constants';
import { SystemLabel, PluginName } from '../../systemLabels';
import { log } from '../../logger';
@@ -65,6 +67,9 @@ export class TextInputPlugin implements Plugin {
// owns an atlas used only to position the caret (measureWidth); its glyph
// advances match the child Text's atlas (same font config).
const childrenOf = new Map<Entity, { sel: Entity; text: Entity; caret: Entity }>();
+ // 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>();
let measureRenderer: SdfTextRenderer | null = null;
const ensureMeasure = (): SdfTextRenderer => {
if (!measureRenderer) measureRenderer = new SdfTextRenderer(module);
@@ -198,6 +203,34 @@ export class TextInputPlugin implements Plugin {
resetCursorBlink();
}
+ // Map the current pointer to a caret index inside `entity` (single-line):
+ // pointer world-x → the field's local text space (undo the box center,
+ // padding and horizontal scroll) → nearest character boundary. null when
+ // it can't be resolved (no camera / multiline / zero-width).
+ function caretIndexFromPointer(entity: Entity): number | null {
+ const cam = app.getResource(UICameraInfo) as UICameraData | undefined;
+ if (!cam || !cam.valid) return null;
+ if (!world.has(entity, Transform) || !world.has(entity, UINode)) return null;
+ const ti = world.get(entity, TextInput) as TextInputData;
+ if (ti.multiline) return null;
+ const width = getUINodeWidth(entity);
+ if (width <= 0) return null;
+ // The layout centers the box on its Transform (pivot 0.5), so the left
+ // edge is half a width to the left; text starts `padding` in, scrolled.
+ const tr = world.get(entity, Transform) as TransformData;
+ const fieldLeft = tr.worldPosition.x - width / 2;
+ const scrollX = scrollXOf.get(entity) ?? 0;
+ const textX = cam.worldMouseX - fieldLeft - ti.padding + scrollX;
+ // Focused ⇒ the textarea is the source of truth for the value.
+ const val = textarea.value;
+ const atlas = ensureMeasure().atlas;
+ const prefixes: number[] = [];
+ for (let i = 0; i <= val.length; i++) {
+ prefixes.push(measureWidth(maskedPrefix(val, i, ti.password, PASSWORD_CHAR), atlas, ti.fontFamily, ti.fontSize, 0));
+ }
+ return nearestCaretIndex(prefixes, textX);
+ }
+
function activateTextarea(entity: Entity): void {
const ti = world.get(entity, TextInput) as TextInputData;
if (ti.readOnly) return;
@@ -256,6 +289,25 @@ export class TextInputPlugin implements Plugin {
prevFocusedTextInput = currentFocused;
}
+
+ // Click-to-caret: a pointer press inside the focused field moves
+ // the caret to the character boundary nearest the pointer (runs
+ // after the focus change above, so it overrides the restored caret
+ // on the same click that focused the field).
+ if (currentFocused !== null && world.has(currentFocused, UIInteraction)) {
+ const inter = world.get(currentFocused, UIInteraction) as UIInteractionData;
+ if (inter.justPressed) {
+ const idx = caretIndexFromPointer(currentFocused);
+ if (idx !== null) {
+ textarea.selectionStart = idx;
+ textarea.selectionEnd = idx;
+ const ti = world.get(currentFocused, TextInput) as TextInputData;
+ ti.cursorPos = idx;
+ ti.dirty = true;
+ resetCursorBlink();
+ }
+ }
+ }
},
{ name: 'TextInputFocusSystem' }
), { runAfter: [SystemLabel.Focus] });
@@ -326,6 +378,7 @@ export class TextInputPlugin implements Plugin {
// multiline wraps within the box and clips (no h-scroll).
const innerW = Math.max(0, w - 2 * ti.padding);
const scrollX = ti.multiline ? 0 : Math.max(0, caretRaw - innerW);
+ scrollXOf.set(entity, scrollX);
// Selection highlight (single-line only): a quad spanning the
// masked range, drawn behind the text. A multiline selection
diff --git a/sdk/src/ui/text/text-input-view.ts b/sdk/src/ui/text/text-input-view.ts
index 0036d97b8..bda86d295 100644
--- a/sdk/src/ui/text/text-input-view.ts
+++ b/sdk/src/ui/text/text-input-view.ts
@@ -68,3 +68,22 @@ export function fieldSelection(selStart: number, selEnd: number, backward: boole
const hi = Math.max(a, b);
return { lo, hi, caret: backward ? lo : hi, hasRange: hi > lo };
}
+
+/**
+ * The caret index whose position is closest to text-space offset `x`, given
+ * `prefixWidths[i]` = the measured width of the first `i` characters
+ * (`prefixWidths[0] === 0`, length = value length + 1). Used to place the caret
+ * where a pointer clicks inside the field. Pure. Returns 0 for an empty field.
+ */
+export function nearestCaretIndex(prefixWidths: readonly number[], x: number): number {
+ let best = 0;
+ let bestDist = Infinity;
+ for (let i = 0; i < prefixWidths.length; i++) {
+ const d = Math.abs(prefixWidths[i] - x);
+ if (d < bestDist) {
+ bestDist = d;
+ best = i;
+ }
+ }
+ return best;
+}
diff --git a/sdk/tests/ui-text-input-view.test.ts b/sdk/tests/ui-text-input-view.test.ts
index e558c2ebc..653dffe49 100644
--- a/sdk/tests/ui-text-input-view.test.ts
+++ b/sdk/tests/ui-text-input-view.test.ts
@@ -10,7 +10,7 @@
* the caret / preedit / selection render paths.
*/
import { describe, it, expect } from 'vitest';
-import { textFieldDisplay, maskedPrefix, fieldSelection } from '../src/ui/text/text-input-view';
+import { textFieldDisplay, maskedPrefix, fieldSelection, nearestCaretIndex } from '../src/ui/text/text-input-view';
const BULLET = '●';
@@ -78,3 +78,27 @@ describe('fieldSelection', () => {
expect(fieldSelection(0, 8, false, 8)).toEqual({ lo: 0, hi: 8, caret: 8, hasRange: true });
});
});
+
+describe('nearestCaretIndex', () => {
+ // Prefix widths for a 4-char field where each char is 10px wide.
+ const widths = [0, 10, 20, 30, 40];
+
+ it('snaps a click to the nearest character boundary', () => {
+ expect(nearestCaretIndex(widths, 0)).toBe(0);
+ expect(nearestCaretIndex(widths, 12)).toBe(1); // closest to 10
+ expect(nearestCaretIndex(widths, 16)).toBe(2); // closest to 20
+ expect(nearestCaretIndex(widths, 40)).toBe(4);
+ });
+
+ it('clamps a click past the end to the last boundary', () => {
+ expect(nearestCaretIndex(widths, 999)).toBe(4);
+ });
+
+ it('clamps a click before the start to 0', () => {
+ expect(nearestCaretIndex(widths, -50)).toBe(0);
+ });
+
+ it('returns 0 for an empty field', () => {
+ expect(nearestCaretIndex([0], 25)).toBe(0);
+ });
+});