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(cocos): EditBox is a component over the platform text editor (mode and length rules, hint, password bullets, the four editing events), and the importer maps it
yhha66980ab42b2
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.tsindex 7aaf83315..5bcb125a4 100644--- a/pipeline/src/import/cocos/components.ts+++ b/pipeline/src/import/cocos/components.ts@@ -638,6 +638,23 @@ function graphics(c: CocosComponent): ComponentData {};}+/** `cc.EditBox`: the box and its two labels are the scene's own nodes; what is typed goes through the platform's text editor. */+function editBox(c: CocosComponent, ctx: ComponentContext): ComponentData {+ return {+ type: `${LAYER}EditBox`,+ data: {+ ...renamed(c, {+ _string: 'string_', _maxLength: 'maxLength', _inputMode: 'inputMode', _inputFlag: 'inputFlag', _returnType: 'returnType', _tabIndex: 'tabIndex',+ _textLabel: 'textLabel', _placeholderLabel: 'placeholderLabel',+ }),+ ...handlerLists(c.data.editingDidBegan, 'editingDidBegan', ctx),+ ...handlerLists(c.data.textChanged, 'textChanged', ctx),+ ...handlerLists(c.data.editingDidEnded, 'editingDidEnded', ctx),+ ...handlerLists(c.data.editingReturn, 'editingReturn', ctx),+ },+ };+}+/** `cc.UIOpacity`: the alpha of the node and everything under it, which the engine's GroupOpacity is. */function uiOpacity(c: CocosComponent, ctx: ComponentContext): ComponentData {ctx.report.component('cc.UIOpacity', 'mapped');@@ -761,6 +778,9 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strincase 'cc.SkeletalAnimation':out = skeletalAnimation(c, node, ctx, where);break;+ case 'cc.EditBox':+ out = editBox(c, ctx);+ break;case 'cc.Graphics':out = graphics(c);break;diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.tsindex b5f2b555f..8431b25c4 100644--- a/sdk/src/cocos/index.ts+++ b/sdk/src/cocos/index.ts@@ -26,7 +26,7 @@ export {AnimationClip, SceneAsset, EffectAsset, Mesh,} from './assets';export { registerBuiltinComponent, type BuiltinAdapter } from './builtins';-export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, Graphics, getVisibleSize, setVisibleSize } from './ui';+export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, Graphics, EditBox, getVisibleSize, setVisibleSize } from './ui';export { Touch, EventTouch } from './input';export { tween, Tween, tweenUtil, easing, updateTweens } from './tween';export { instantiate, loadPrefab, providePrefab } from './prefabs';diff --git a/sdk/src/cocos/ui/editBox.ts b/sdk/src/cocos/ui/editBox.tsnew file mode 100644index 000000000..115b2a4a7--- /dev/null+++ b/sdk/src/cocos/ui/editBox.ts@@ -0,0 +1,195 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/ui/editBox.ts+ * @brief `EditBox`: a text field whose box and labels are nodes of the scene, typed into through the platform's own text editor.+ *+ * The engine's `TextInput` composes its own flex-laid-out children, and an imported scene is world-space nodes: an EditBox here is the box a+ * scene already drew, a `Label` that shows what was typed and one that shows the hint. A click on the box takes focus on the OS editing surface+ * (a hidden textarea on the web, the soft keyboard and its IME on a device), whose value the labels follow. A host with no such surface shows the+ * box and does not type, as the engine's own fields do.+ */+import { Component } from '../component';+import { Node } from '../node';+import { declareClass } from '../host';+import type { EventTouch } from '../input';+import { Label } from './label';+import { UITransform } from './uiTransform';+import { EventHandler, joinHandlers } from './button';+import { platformCreateTextEditor } from '../../platform';+import type { PlatformTextEditor } from '../../platform/types';++type Handlers = Array<{ component: string; handler: string; customEventData: string }>;++const InputMode = Object.freeze({ ANY: 0, EMAIL: 1, NUMERIC: 2, PHONE_NUMBER: 3, URL: 4, DECIMAL: 5, SINGLE_LINE: 6 });+const InputFlag = Object.freeze({ PASSWORD: 0, SENSITIVE: 1, INITIAL_CAPS_WORD: 2, INITIAL_CAPS_SENTENCE: 3, INITIAL_CAPS_ALL_CHARACTERS: 4, DEFAULT: 5 });+const KeyboardReturnType = Object.freeze({ DEFAULT: 0, DONE: 1, SEND: 2, SEARCH: 3, GO: 4, NEXT: 5 });+const EventType = Object.freeze({+ EDITING_DID_BEGAN: 'editing-did-began', EDITING_DID_ENDED: 'editing-did-ended', TEXT_CHANGED: 'text-changed', EDITING_RETURN: 'editing-return',+});++/** The characters a field of this input mode takes. */+function allowed(mode: number, value: string): string {+ switch (mode) {+ case InputMode.NUMERIC: return value.replace(/[^0-9]/g, '');+ case InputMode.DECIMAL: return value.replace(/[^0-9.\-]/g, '');+ case InputMode.PHONE_NUMBER: return value.replace(/[^0-9+*#\-]/g, '');+ case InputMode.EMAIL:+ case InputMode.URL:+ case InputMode.SINGLE_LINE: return value.replace(/[\r\n]/g, '');+ default: return value;+ }+}++const BULLET = '●';++export class EditBox extends Component {+ static readonly EventType = EventType;+ static readonly InputMode = InputMode;+ static readonly InputFlag = InputFlag;+ static readonly KeyboardReturnType = KeyboardReturnType;++ maxLength = 20;+ inputMode: number = InputMode.ANY;+ inputFlag: number = InputFlag.DEFAULT;+ returnType: number = KeyboardReturnType.DEFAULT;+ tabIndex = 0;+ textLabel: Label | null = null;+ placeholderLabel: Label | null = null;++ editingDidBeganTargets: Array<Node | null> = [];+ editingDidBeganHandlers: Handlers = [];+ textChangedTargets: Array<Node | null> = [];+ textChangedHandlers: Handlers = [];+ editingDidEndedTargets: Array<Node | null> = [];+ editingDidEndedHandlers: Handlers = [];+ editingReturnTargets: Array<Node | null> = [];+ editingReturnHandlers: Handlers = [];+ editingDidBegan: EventHandler[] = [];+ textChanged: EventHandler[] = [];+ editingDidEnded: EventHandler[] = [];+ editingReturn: EventHandler[] = [];++ private string_ = '';+ private editor_: PlatformTextEditor | null = null;+ private unsubscribe_: (() => void) | null = null;++ get string(): string { return this.string_; }+ set string(value: string) {+ this.string_ = this.fit_(value);+ this.refresh_();+ }++ /** The hint shown while the field is empty. */+ get placeholder(): string { return this.placeholderLabel?.string ?? ''; }+ set placeholder(value: string) { if (this.placeholderLabel) this.placeholderLabel.string = value; }++ isFocused(): boolean { return this.editor_ !== null; }++ onLoad(): void {+ if (this.editingDidBegan.length === 0) this.editingDidBegan = joinHandlers(this.editingDidBeganTargets, this.editingDidBeganHandlers);+ if (this.textChanged.length === 0) this.textChanged = joinHandlers(this.textChangedTargets, this.textChangedHandlers);+ if (this.editingDidEnded.length === 0) this.editingDidEnded = joinHandlers(this.editingDidEndedTargets, this.editingDidEndedHandlers);+ if (this.editingReturn.length === 0) this.editingReturn = joinHandlers(this.editingReturnTargets, this.editingReturnHandlers);+ }++ onEnable(): void {+ this.node.on(Node.EventType.TOUCH_END, this.onTouchEnd_, this);+ this.refresh_();+ }++ onDisable(): void {+ this.node.off(Node.EventType.TOUCH_END, this.onTouchEnd_, this);+ this.blur();+ }++ private onTouchEnd_(event: EventTouch): void {+ const inside = this.node.getComponent(UITransform)?.isHit(event.getUILocation()) ?? true;+ if (inside) this.focus();+ event.stopPropagation();+ }++ /** Take the keyboard, as a click on the box does. */+ focus(): void {+ if (this.editor_ || !this.enabledInHierarchy) return;+ const editor = platformCreateTextEditor();+ if (!editor) return; // a host with no text surface shows the field and does not type+ this.editor_ = editor;+ const end = this.string_.length;+ editor.focus(+ { value: this.string_, selectionStart: end, selectionEnd: end, backward: false },+ { multiline: this.inputMode === InputMode.ANY, maxLength: this.maxLength > 0 ? this.maxLength : 0, password: this.inputFlag === InputFlag.PASSWORD },+ );+ this.unsubscribe_ = editor.subscribe((event) => {+ if (event.kind === 'change') this.onChange_();+ else if (event.kind === 'submit') { this.fire_(this.editingReturn, EventType.EDITING_RETURN); this.blur(); }+ else if (event.kind === 'cancel' || event.kind === 'blur') this.blur();+ });+ this.refresh_();+ this.fire_(this.editingDidBegan, EventType.EDITING_DID_BEGAN);+ }++ /** Give the keyboard back. */+ blur(): void {+ const editor = this.editor_;+ if (!editor) return;+ this.editor_ = null;+ this.unsubscribe_?.();+ this.unsubscribe_ = null;+ editor.blur();+ editor.dispose();+ this.refresh_();+ this.fire_(this.editingDidEnded, EventType.EDITING_DID_ENDED);+ }++ private onChange_(): void {+ const editor = this.editor_;+ if (!editor) return;+ const state = editor.read();+ const value = this.fit_(state.value);+ if (value !== state.value) editor.write({ ...state, value, selectionStart: Math.min(state.selectionStart, value.length), selectionEnd: Math.min(state.selectionEnd, value.length) });+ if (value === this.string_) return;+ this.string_ = value;+ this.refresh_();+ EventHandler.emitEvents(this.textChanged, value, this);+ this.node.emit(EventType.TEXT_CHANGED, this);+ }++ private fit_(value: string): string {+ const text = allowed(this.inputMode, value);+ return this.maxLength > 0 && text.length > this.maxLength ? text.slice(0, this.maxLength) : text;+ }++ private fire_(handlers: EventHandler[], type: string): void {+ EventHandler.emitEvents(handlers, this);+ this.node.emit(type, this);+ }++ /** What the labels show: the text (as bullets for a password), or the hint while there is none. */+ private refresh_(): void {+ const shown = this.inputFlag === InputFlag.PASSWORD ? BULLET.repeat(this.string_.length) : this.string_;+ if (this.textLabel) this.textLabel.string = shown;+ if (this.placeholderLabel) this.placeholderLabel.node.active = this.string_ === '';+ }+}++export function declareEditBox(): void {+ declareClass(EditBox as never, 'EditBox', [+ { name: 'string_', kind: 'string' },+ { name: 'maxLength', kind: 'number' },+ { name: 'inputMode', kind: 'number' },+ { name: 'inputFlag', kind: 'number' },+ { name: 'returnType', kind: 'number' },+ { name: 'tabIndex', kind: 'number' },+ { name: 'textLabel', kind: 'component', type: Label },+ { name: 'placeholderLabel', kind: 'component', type: Label },+ { name: 'editingDidBeganTargets', kind: 'node', array: true },+ { name: 'editingDidBeganHandlers', kind: 'json' },+ { name: 'textChangedTargets', kind: 'node', array: true },+ { name: 'textChangedHandlers', kind: 'json' },+ { name: 'editingDidEndedTargets', kind: 'node', array: true },+ { name: 'editingDidEndedHandlers', kind: 'json' },+ { name: 'editingReturnTargets', kind: 'node', array: true },+ { name: 'editingReturnHandlers', kind: 'json' },+ ]);+}diff --git a/sdk/src/cocos/ui/index.ts b/sdk/src/cocos/ui/index.tsindex f820f8563..2986eb8c3 100644--- a/sdk/src/cocos/ui/index.ts+++ b/sdk/src/cocos/ui/index.ts@@ -17,3 +17,4 @@ export { Camera } from './camera';export { RichText } from './richText';export { Mask } from './mask';export { Graphics } from './graphics';+export { EditBox } from './editBox';diff --git a/sdk/src/cocos/ui/pass.ts b/sdk/src/cocos/ui/pass.tsindex 758180889..5743f8627 100644--- a/sdk/src/cocos/ui/pass.ts+++ b/sdk/src/cocos/ui/pass.ts@@ -17,6 +17,7 @@ import { alignAllWidgets, declareWidget } from './widget';import { layoutAll, declareLayout } from './layout';import { declareControls } from './controls';import { declareGraphics } from './graphics';+import { declareEditBox } from './editBox';import { declareScrollView } from './scrollView';import { setUiCameraData, setVisibleSize, setWindowPixels } from './screen';@@ -25,6 +26,7 @@ export function declareUiPass(): void {declareLayout();declareControls();declareGraphics();+ declareEditBox();declareScrollView();const system = defineSystem([Res(UICameraInfo), Res(ScreenLayout), GetWorld()],diff --git a/sdk/tests/cocos/editbox-wasm.test.ts b/sdk/tests/cocos/editbox-wasm.test.tsnew file mode 100644index 000000000..c5325a35a--- /dev/null+++ b/sdk/tests/cocos/editbox-wasm.test.ts@@ -0,0 +1,136 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file EditBox: a click takes the platform's text editor, what is typed lands in the labels, and the field's rules (mode, length, hint) hold.+ */+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';+import type { ESEngineModule } from '../../src/wasm';+import { Transform, ensureBuiltinComponentsRegistered } from '../../src/ecs/component';+import { EditBox, Label, Node, UITransform } from '../../src/cocos';+import type { PlatformTextEditor, TextEditorEvent, TextEditorState } from '../../src/platform/types';+import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';+import { pointerApp, type PointerApp } from './helpers/pointerApp';++/** A text surface the test types into. */+class FakeEditor implements PlatformTextEditor {+ state: TextEditorState = { value: '', selectionStart: 0, selectionEnd: 0, backward: false };+ options: unknown = null;+ focused = false;+ disposed = false;+ private handlers: Array<(e: TextEditorEvent) => void> = [];+ focus(state: TextEditorState, options: unknown): void { this.state = { ...state }; this.options = options; this.focused = true; }+ blur(): void { this.focused = false; }+ read(): TextEditorState { return { ...this.state }; }+ write(state: TextEditorState): void { this.state = { ...state }; }+ subscribe(h: (e: TextEditorEvent) => void): () => void { this.handlers.push(h); return () => { this.handlers = this.handlers.filter((x) => x !== h); }; }+ dispose(): void { this.disposed = true; }+ type(value: string): void { this.state = { ...this.state, value, selectionStart: value.length, selectionEnd: value.length }; this.emit({ kind: 'change' }); }+ emit(e: TextEditorEvent): void { for (const h of [...this.handlers]) h(e); }+}++let editor: FakeEditor | null;+vi.mock('../../src/platform', async (importOriginal) => ({+ ...(await importOriginal<typeof import('../../src/platform')>()),+ platformCreateTextEditor: () => editor,+}));++describe.skipIf(!HAS_WASM)('EditBox', () => {+ let module: ESEngineModule;+ let P: PointerApp | undefined;++ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });+ beforeEach(() => { editor = new FakeEditor(); });+ afterEach(() => { P?.dispose(); P = undefined; });++ function box(name: string, x: number, y: number, w: number, h: number, parent?: Node): Node {+ const n = new Node(name);+ P!.app.world.insert(n._entity, Transform);+ n.addComponent(UITransform)!.setContentSize(w, h);+ n.setPosition(x, y, 0);+ parent?.addChild(n);+ return n;+ }++ async function field(configure: (e: EditBox) => void = () => {}): Promise<{ node: Node; edit: EditBox; text: Label; hint: Label }> {+ P = pointerApp(module);+ const node = box('input', 200, 200, 160, 40);+ const text = box('text', 0, 0, 150, 30, node).addComponent(Label)!;+ const hint = box('hint', 0, 0, 150, 30, node).addComponent(Label)!;+ hint.string = 'type here';+ const edit = node.addComponent<EditBox>('EditBox')!;+ edit.textLabel = text;+ edit.placeholderLabel = hint;+ configure(edit);+ await P.frame(1);+ return { node, edit, text, hint };+ }++ it('takes the text editor on a click, and tells the field\'s listeners', async () => {+ const { node, edit } = await field();+ const seen: string[] = [];+ node.on(EditBox.EventType.EDITING_DID_BEGAN, () => seen.push('began'));+ await P!.tap(200, 200);+ expect(editor!.focused).toBe(true);+ expect(edit.isFocused()).toBe(true);+ expect(seen).toEqual(['began']);+ });++ it('shows what is typed in its label and hides the hint, and brings the hint back when it is emptied', async () => {+ const { node, edit, text, hint } = await field();+ const changed: string[] = [];+ node.on(EditBox.EventType.TEXT_CHANGED, (e: EditBox) => changed.push(e.string));+ expect(hint.node.active).toBe(true);+ await P!.tap(200, 200);+ editor!.type('hello');+ expect(edit.string).toBe('hello');+ expect(text.string).toBe('hello');+ expect(hint.node.active).toBe(false);+ editor!.type('');+ expect(hint.node.active).toBe(true);+ expect(changed).toEqual(['hello', '']);+ });++ it('holds to the length and the characters its mode takes, writing the fit text back to the surface', async () => {+ const { edit } = await field((e) => { e.maxLength = 4; e.inputMode = EditBox.InputMode.NUMERIC; });+ await P!.tap(200, 200);+ editor!.type('12ab3456');+ expect(edit.string).toBe('1234');+ expect(editor!.state.value).toBe('1234');+ });++ it('shows bullets for a password and keeps the real text', async () => {+ const { edit, text } = await field((e) => { e.inputFlag = EditBox.InputFlag.PASSWORD; });+ await P!.tap(200, 200);+ editor!.type('secret');+ expect(edit.string).toBe('secret');+ expect(text.string).toBe('●●●●●●');+ expect((editor!.options as { password: boolean }).password).toBe(true);+ });++ it('ends on submit with a return event and then an end event, giving the surface back', async () => {+ const { node, edit } = await field();+ const seen: string[] = [];+ node.on(EditBox.EventType.EDITING_RETURN, () => seen.push('return'));+ node.on(EditBox.EventType.EDITING_DID_ENDED, () => seen.push('ended'));+ await P!.tap(200, 200);+ editor!.emit({ kind: 'submit' });+ expect(seen).toEqual(['return', 'ended']);+ expect(edit.isFocused()).toBe(false);+ expect(editor!.focused).toBe(false);+ expect(editor!.disposed).toBe(true);+ });++ it('can be set from a script without an event, and shows the hint when empty', async () => {+ const { edit, text, hint } = await field();+ edit.string = 'preset';+ expect(text.string).toBe('preset');+ expect(hint.node.active).toBe(false);+ });++ it('does nothing on a host with no text editor', async () => {+ editor = null;+ const { edit } = await field();+ await P!.tap(200, 200);+ expect(edit.isFocused()).toBe(false);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 81bdaeb2d..6c300712b 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 = {+ 'feat(cocos): EditBox is a component over the platform text editor (mode and length rules, hint, password bullets, the four editing events), and the importer maps it':+ {"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},'feat(cocos): Graphics is a component over the engine Draw (rect, circle and stroked paths kept until clear), UIMeshRenderer folds into its host, and a Node has worldScale and worldRotation':{"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},'feat(animation): an animator state can play at the speed of a float parameter (speedParameter), and the Cocos animation graph is converted to an animator controller':