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): 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.mdxindex 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** fireshorizontally** 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 aChinese/Japanese/Korean composition renders **live in the field** (the preeditdiff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.tsindex 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 selectiondiff --git a/sdk/src/ui/text/text-input-view.ts b/sdk/src/ui/text/text-input-view.tsindex 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: booleconst 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.tsindex 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);+ });+});