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(native): a device's soft keyboard is the field's editing surface

esenginec91de5fe7f9d
diff --git a/build-tools/tasks/nativePackage.js b/build-tools/tasks/nativePackage.js
index 8bd56c5fd..d26d3a175 100644
--- a/build-tools/tasks/nativePackage.js
+++ b/build-tools/tasks/nativePackage.js
@@ -8,7 +8,7 @@
import path from 'path';
import { existsSync, readFileSync } from 'fs';
-import { mkdir, copyFile, cp, rm, writeFile } from 'fs/promises';
+import { mkdir, copyFile, cp, rm, writeFile, readdir } from 'fs/promises';
import config from '../build.config.js';
import * as logger from '../utils/logger.js';
import { runCommand } from '../utils/emscripten.js';
@@ -27,6 +27,11 @@ const HOST_LIBRARY = 'libestella_js_host.so';
export const BYTECODE_FILE = 'esengine.native.qjsbc';
const MANIFEST_TEMPLATE = path.join('native', 'android', 'host', 'AndroidManifest.xml.in');
+/** The Java shim's sources — the IME's own side of an editable field, which has
+ * to be Java because only a Java View gets an InputConnection to compose into
+ * (see native/android/java/.../TextEditor.java). */
+const JAVA_DIR = path.join('native', 'android', 'java');
+
/** The APK is named after the app it contains, so packaging a second project does
* not quietly replace the first one's file. */
const apkName = (appId) => `${appId.split('.').pop() || 'estella'}.apk`;
@@ -55,6 +60,41 @@ async function debugKeystore(jdk) {
// a zip entry name must use forward slashes — so AAssetManager could not open
// anything in a subdirectory. Invisible while the packaged content was a handful
// of flat files; every real project export has directories.
+/**
+ * Compile the Java shim to a classes.dex in `staging`. javac + d8 are already
+ * beside the tools packaging uses (the JDK apksigner needs, the build-tools aapt2
+ * comes from), so this stays a plain APK build with no Gradle. Returns false when
+ * there is nothing to compile, which leaves an APK whose host reports no editing
+ * surface rather than one that fails to build.
+ */
+async function compileJavaShim(staging, sdk, platform, jdk, rootDir) {
+ const sourceDir = path.join(rootDir, JAVA_DIR);
+ if (!existsSync(sourceDir)) return false;
+ const sources = (await readdir(sourceDir, { recursive: true }))
+ .filter((f) => String(f).endsWith('.java'))
+ .map((f) => path.join(sourceDir, String(f)));
+ if (sources.length === 0) return false;
+
+ const classes = path.join(staging, 'classes');
+ await mkdir(classes, { recursive: true });
+ // Java 8 bytecode: d8 accepts it everywhere, and the shim uses nothing newer.
+ await runCommand(jdkTool('javac', jdk), [
+ // The sources are UTF-8; javac otherwise reads them in the platform's
+ // default charset, which on a Windows build machine is not.
+ '-encoding', 'UTF-8', '-source', '8', '-target', '8', '-nowarn',
+ '-bootclasspath', platformJar(sdk, platform),
+ '-d', classes, ...sources,
+ ]);
+ const classFiles = (await readdir(classes, { recursive: true }))
+ .filter((f) => String(f).endsWith('.class'))
+ .map((f) => path.join(classes, String(f)));
+ await runCommand(buildTool(sdk, 'd8'), [
+ '--lib', platformJar(sdk, platform),
+ '--output', staging, ...classFiles,
+ ]);
+ return existsSync(path.join(staging, 'classes.dex'));
+}
+
async function addToApk(apk, stagingDir, entries, jdk) {
await runCommand(jdkTool('jar', jdk), ['ufM', apk, ...entries.flatMap((e) => ['-C', stagingDir, e])]);
}
@@ -127,6 +167,10 @@ export async function packageNativeApk(options = {}) {
// The app the content asks to be: identity, version, and the orientation the
// OS must lock the window to. The manifest is a template because all four vary
// per project — a static one is why every example installed over the last.
+ logger.step('Compiling the Java shim (javac + d8)...');
+ const hasDex = await compileJavaShim(staging, sdk, platform, options.jdk, rootDir);
+ if (!hasDex) logger.warn('No classes.dex: the app will have no soft keyboard (typing is off).');
+
const app = readAppConfig(content, (m) => logger.warn(m));
const manifest = path.join(staging, 'AndroidManifest.xml');
await writeFile(manifest, fillTemplate(readFileSync(path.join(rootDir, MANIFEST_TEMPLATE), 'utf8'), {
@@ -135,6 +179,7 @@ export async function packageNativeApk(options = {}) {
VERSION_NAME: app.version,
VERSION_CODE: app.versionCode,
SCREEN_ORIENTATION: androidScreenOrientation(app.orientation),
+ HAS_CODE: hasDex ? 'true' : 'false',
}));
logger.info(`App: ${app.name} (${app.id}) v${app.version} — ${app.orientation}`);
@@ -151,7 +196,7 @@ export async function packageNativeApk(options = {}) {
]);
logger.step('Adding the native libraries and the game...');
- await addToApk(unsigned, staging, ['lib', 'assets'], options.jdk);
+ await addToApk(unsigned, staging, ['lib', 'assets', ...(hasDex ? ['classes.dex'] : [])], options.jdk);
logger.step('Aligning + signing...');
await rm(aligned, { force: true });
diff --git a/build-tools/utils/android.js b/build-tools/utils/android.js
index 32cd27e6a..fe1b0b8a6 100644
--- a/build-tools/utils/android.js
+++ b/build-tools/utils/android.js
@@ -42,8 +42,10 @@ const exe = process.platform === 'win32' ? '.exe' : '';
export function buildTool(sdk, name) {
const dir = newest(path.join(sdk, 'build-tools'));
if (!dir) throw new Error(`No build-tools under ${sdk}/build-tools. Install them via the SDK Manager.`);
- // apksigner is a script (.bat on Windows), the rest are native binaries.
- const suffix = name === 'apksigner' ? (process.platform === 'win32' ? '.bat' : '') : exe;
+ // apksigner and d8 are JVM launchers — a shell script, or a .bat on Windows;
+ // the rest are native binaries.
+ const script = name === 'apksigner' || name === 'd8';
+ const suffix = script ? (process.platform === 'win32' ? '.bat' : '') : exe;
const tool = path.join(dir, name + suffix);
if (!existsSync(tool)) throw new Error(`${name} not found at ${tool}.`);
return tool;
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
index b34f5ce41..2a8bf2895 100644
--- a/native/CMakeLists.txt
+++ b/native/CMakeLists.txt
@@ -207,6 +207,7 @@ if(ESTELLA_QUICKJS_DIR)
host/bindings/AssetBindings.cpp
host/bindings/AudioBindings.cpp
host/bindings/NetBindings.cpp
+ host/bindings/TextEditorBindings.cpp
host/media/native_audio.cpp
host/media/ktx2_decode.cpp
host/media/glyph_raster.cpp
diff --git a/native/android/host/AndroidManifest.xml.in b/native/android/host/AndroidManifest.xml.in
index abf7f6515..19738a07e 100644
--- a/native/android/host/AndroidManifest.xml.in
+++ b/native/android/host/AndroidManifest.xml.in
@@ -4,9 +4,10 @@
the exported project's app.config.json: an installed app has one identity, one
version and one orientation, and none of them can be decided here.
- Everything left alone is the host itself: a NativeActivity (no Java, so hasCode
- is false), Vulkan 1.0.3 as a hard requirement, and the config changes the host
- handles rather than being restarted for.
+ Everything left alone is the host itself: a NativeActivity, Vulkan 1.0.3 as a
+ hard requirement, and the config changes the host handles rather than being
+ restarted for. `hasCode` follows whether the Java shim compiled — the game is
+ native, and the only Java in the package is the IME's side of a text field.
-->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="@APP_ID@"
@@ -14,7 +15,7 @@
android:versionName="@VERSION_NAME@">
<uses-sdk android:minSdkVersion="26" android:targetSdkVersion="33" />
<uses-feature android:name="android.hardware.vulkan.version" android:version="0x400003" android:required="true" />
- <application android:label="@APP_NAME@" android:hasCode="false" android:extractNativeLibs="true">
+ <application android:label="@APP_NAME@" android:hasCode="@HAS_CODE@" android:extractNativeLibs="true">
<!-- A game's window, stated before any code runs: no title, no status bar.
The host asks for the rest (navigation bar, display cutout) once it
has the UI thread — see onWindowFocusChanged in platform/android.cpp. -->
diff --git a/native/android/java/com/estella/host/TextEditor.java b/native/android/java/com/estella/host/TextEditor.java
new file mode 100644
index 000000000..ef7ca5aaa
--- /dev/null
+++ b/native/android/java/com/estella/host/TextEditor.java
@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+package com.estella.host;
+
+import android.app.Activity;
+import android.text.Editable;
+import android.text.InputType;
+import android.text.TextWatcher;
+import android.view.Gravity;
+import android.view.KeyEvent;
+import android.view.View;
+import android.view.ViewGroup;
+import android.view.inputmethod.BaseInputConnection;
+import android.view.inputmethod.EditorInfo;
+import android.view.inputmethod.InputMethodManager;
+import android.widget.EditText;
+import android.widget.TextView;
+
+/**
+ * The app's editing surface: one real EditText, invisible, that the IME talks to.
+ *
+ * An IME does not deliver composed text (Chinese, Japanese, prediction) as key
+ * events -- it commits through an InputConnection, which only a Java View has.
+ * That is the whole reason this class exists: everything else about the field --
+ * how it looks, where the caret is, what it does with the text -- is engine code
+ * on the other side of the JNI, and this holds only what the platform insists on
+ * owning.
+ *
+ * Every method that touches the view runs on the UI thread; the native side calls
+ * in from the game thread, and reports go back the other way through the static
+ * natives, whose C++ queues them for the next frame.
+ */
+public final class TextEditor implements TextWatcher {
+
+ private final Activity activity;
+ private EditText field;
+ /** Set while the native side is writing, so its own write is not reported back. */
+ private boolean writing;
+
+ public TextEditor(Activity activity) {
+ this.activity = activity;
+ }
+
+ /** Open the keyboard on `value`, with the caret/selection where the field has it. */
+ public void focus(final String value, final int selectionStart, final int selectionEnd,
+ final boolean multiline, final int maxLength, final boolean password) {
+ activity.runOnUiThread(new Runnable() {
+ @Override public void run() {
+ ensureField();
+ writing = true;
+ field.setInputType(inputType(multiline, password));
+ field.setImeOptions(multiline ? EditorInfo.IME_ACTION_NONE : EditorInfo.IME_ACTION_DONE);
+ field.setFilters(maxLength > 0
+ ? new android.text.InputFilter[] { new android.text.InputFilter.LengthFilter(maxLength) }
+ : new android.text.InputFilter[0]);
+ field.setText(value);
+ setSelection(selectionStart, selectionEnd);
+ writing = false;
+ field.setVisibility(View.VISIBLE);
+ field.requestFocus();
+ imm().showSoftInput(field, InputMethodManager.SHOW_IMPLICIT);
+ }
+ });
+ }
+
+ /** Close the keyboard and give up focus. */
+ public void blur() {
+ activity.runOnUiThread(new Runnable() {
+ @Override public void run() {
+ if (field == null) return;
+ imm().hideSoftInputFromWindow(field.getWindowToken(), 0);
+ field.clearFocus();
+ // Gone, not invisible: a focusable view left in the tree can take
+ // focus back from the game's own surface on the next layout.
+ field.setVisibility(View.GONE);
+ }
+ });
+ }
+
+ /** Adopt a value + selection the app decided (setValue, a tap that moved the caret). */
+ public void write(final String value, final int selectionStart, final int selectionEnd) {
+ activity.runOnUiThread(new Runnable() {
+ @Override public void run() {
+ if (field == null) return;
+ writing = true;
+ if (!field.getText().toString().equals(value)) field.setText(value);
+ setSelection(selectionStart, selectionEnd);
+ writing = false;
+ }
+ });
+ }
+
+ // -- TextWatcher: the IME's commits and the user's typing --------------------
+
+ @Override public void beforeTextChanged(CharSequence s, int start, int count, int after) {}
+
+ @Override public void onTextChanged(CharSequence s, int start, int before, int count) {}
+
+ @Override public void afterTextChanged(Editable s) {
+ report();
+ }
+
+ /** Hand the field's whole state to the engine. Composing is asked of the
+ * Editable itself: a preedit is a span the IME put there, not a flag. */
+ private void report() {
+ if (writing || field == null) return;
+ final Editable text = field.getText();
+ final boolean composing = BaseInputConnection.getComposingSpanStart(text) >= 0
+ && BaseInputConnection.getComposingSpanEnd(text) >= 0;
+ nativeState(text.toString(), field.getSelectionStart(), field.getSelectionEnd(), composing);
+ }
+
+ private void setSelection(int start, int end) {
+ final int len = field.getText().length();
+ field.setSelection(clamp(start, len), clamp(end, len));
+ }
+
+ private static int clamp(int index, int length) {
+ return index < 0 ? 0 : (index > length ? length : index);
+ }
+
+ private static int inputType(boolean multiline, boolean password) {
+ if (password) return InputType.TYPE_CLASS_TEXT | InputType.TYPE_TEXT_VARIATION_PASSWORD;
+ int type = InputType.TYPE_CLASS_TEXT;
+ if (multiline) type |= InputType.TYPE_TEXT_FLAG_MULTI_LINE;
+ return type;
+ }
+
+ private InputMethodManager imm() {
+ return (InputMethodManager) activity.getSystemService(Activity.INPUT_METHOD_SERVICE);
+ }
+
+ /** The view, created on first use and left in the tree. 1x1 and transparent:
+ * it must be a real, laid-out, focusable view for the IME to attach to it,
+ * but the game draws the field itself. */
+ private void ensureField() {
+ if (field != null) return;
+ field = new EditText(activity) {
+ @Override protected void onSelectionChanged(int start, int end) {
+ super.onSelectionChanged(start, end);
+ report(); // a caret move is state too, and TextWatcher never sees it
+ }
+ };
+ field.setBackgroundColor(0);
+ field.setTextColor(0);
+ field.setCursorVisible(false);
+ field.setSingleLine(false);
+ field.addTextChangedListener(this);
+ field.setOnEditorActionListener(new TextView.OnEditorActionListener() {
+ @Override public boolean onEditorAction(TextView v, int actionId, KeyEvent event) {
+ if (actionId == EditorInfo.IME_ACTION_DONE || actionId == EditorInfo.IME_ACTION_GO
+ || actionId == EditorInfo.IME_ACTION_SEND
+ || (event != null && event.getKeyCode() == KeyEvent.KEYCODE_ENTER)) {
+ nativeSubmit();
+ return true;
+ }
+ return false;
+ }
+ });
+ // Back dismisses the keyboard without committing — the field should lose
+ // focus, exactly as Escape does on the web.
+ field.setOnKeyListener(new View.OnKeyListener() {
+ @Override public boolean onKey(View v, int keyCode, KeyEvent event) {
+ if (keyCode == KeyEvent.KEYCODE_BACK && event.getAction() == KeyEvent.ACTION_UP) {
+ nativeCancel();
+ return true;
+ }
+ return false;
+ }
+ });
+ final ViewGroup.LayoutParams params = new ViewGroup.LayoutParams(1, 1);
+ field.setGravity(Gravity.TOP | Gravity.START);
+ activity.addContentView(field, params);
+ }
+
+ // -- Into the engine (registered from C++ with RegisterNatives) --------------
+
+ private static native void nativeState(String value, int selectionStart, int selectionEnd, boolean composing);
+ private static native void nativeSubmit();
+ private static native void nativeCancel();
+}
diff --git a/native/host/Bindings.hpp b/native/host/Bindings.hpp
index a861d8afa..86b35b246 100644
--- a/native/host/Bindings.hpp
+++ b/native/host/Bindings.hpp
@@ -51,8 +51,17 @@ void registerAudioBindings(HostState& h, JSValue global);
/** es_fetch over the platform's native networking. */
void registerNetBindings(HostState& h, JSValue global);
+/** es_textEditor_* over the platform's soft keyboard — bound ONLY when the
+ * platform has one, so the SDK gates its editing surface on real availability
+ * exactly as it does audio. */
+void registerTextEditorBindings(HostState& h, JSValue global);
+
/** Run the JS callbacks for HTTP replies that arrived since the last frame. JS
* thread only; {@link deliverFetch} queued them from the completion thread. */
void drainFetches(HostState& h);
+/** Push what the editing surface did since the last frame into JS. JS thread
+ * only; the deliverTextEditor* calls queued it from the platform's UI thread. */
+void drainTextEditor(HostState& h);
+
} // namespace eshost
diff --git a/native/host/Host.hpp b/native/host/Host.hpp
index 0494c6267..6c60b560a 100644
--- a/native/host/Host.hpp
+++ b/native/host/Host.hpp
@@ -110,6 +110,25 @@ struct Platform {
* with the same `req.id`. The OS owns the TLS stack, so this is where native
* networking necessarily differs between iOS and Android. */
virtual void startFetch(const FetchRequest& req) = 0;
+
+ /**
+ * The OS text-editing surface: a soft keyboard with its IME. A platform that
+ * has one overrides these and reports what the user did through
+ * {@link deliverTextEditorState} / Submit / Cancel; one that does not leaves
+ * the defaults, `hasTextEditor()` stays false, the es_textEditor_* entry
+ * points are never bound, and the SDK sees a realm where fields render but
+ * cannot be typed into.
+ *
+ * The surface OWNS the value and the selection while a field is focused —
+ * an IME composes into it, and the app's own edits go through `write`.
+ */
+ virtual bool hasTextEditor() const { return false; }
+ virtual void textEditorFocus(const std::string& /*value*/, int /*selectionStart*/,
+ int /*selectionEnd*/, bool /*multiline*/,
+ int /*maxLength*/, bool /*password*/) {}
+ virtual void textEditorBlur() {}
+ virtual void textEditorWrite(const std::string& /*value*/, int /*selectionStart*/,
+ int /*selectionEnd*/) {}
};
/** Deliver an HTTP reply for a {@link Platform::startFetch}. Thread-safe: the
@@ -117,6 +136,16 @@ struct Platform {
* queued and the JS callback runs on the next frame, on the JS thread. */
void deliverFetch(FetchResult result);
+/** The editing surface's whole state, after the user (or its IME) changed it.
+ * Thread-safe, like {@link deliverFetch}: the platform calls it from its UI
+ * thread and the JS side is told on the next frame. `composing` is true while an
+ * IME preedit sits inside `value`. */
+void deliverTextEditorState(std::string value, int selectionStart, int selectionEnd, bool composing);
+/** The keyboard's done/go key on a single-line field. Thread-safe. */
+void deliverTextEditorSubmit();
+/** The keyboard was dismissed without committing (back gesture, done). Thread-safe. */
+void deliverTextEditorCancel();
+
/** @brief Boots Dawn, EstellaContext, QuickJS, the SDK bundle and the packaged
* project. Call once, when a window first exists; @p platform must
* outlive the host.
diff --git a/native/host/Runtime.cpp b/native/host/Runtime.cpp
index f7869519f..4e9754acc 100644
--- a/native/host/Runtime.cpp
+++ b/native/host/Runtime.cpp
@@ -378,6 +378,7 @@ void initRuntime(HostState& h) {
registerAssetBindings(h, global);
registerAudioBindings(h, global);
registerNetBindings(h, global);
+ registerTextEditorBindings(h, global);
// The generated halves: per-component accessors, then the engine's binding
// entry points — both from the same reflection the web's embind bindings come
diff --git a/native/host/bindings/TextEditorBindings.cpp b/native/host/bindings/TextEditorBindings.cpp
new file mode 100644
index 000000000..120b4d977
--- /dev/null
+++ b/native/host/bindings/TextEditorBindings.cpp
@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file TextEditorBindings.cpp
+ * @brief es_textEditor_* over the platform's soft keyboard, and the
+ * thread-safe hand-back that makes it usable from JS.
+ * @details Host-owned, and for the same reason networking is: the editing surface
+ * IS the OS — its keyboard layouts, its IME, its candidate window. The
+ * SDK asks for one through a single contract (PlatformTextEditor); this
+ * is the device's side of it.
+ *
+ * The keyboard reports on the OS UI thread, which is not the JS thread,
+ * so a report is queued as POD and drained in the frame loop — the same
+ * shape {@link deliverFetch} uses, and for the same reason: no JS value
+ * is ever touched off-thread.
+ *
+ * @author ESEngine Team
+ * @date 2026
+ *
+ * @copyright Copyright (c) 2026 ESEngine Team
+ * Licensed under the Apache License, Version 2.0.
+ */
+#include "Bindings.hpp"
+
+#include <mutex>
+#include <queue>
+#include <string>
+#include <utility>
+
+using namespace esengine;
+
+namespace eshost {
+namespace {
+
+/** One thing the surface did, as POD — what crosses the thread boundary. */
+struct EditorPush {
+ enum class Kind { State, Submit, Cancel };
+ Kind kind = Kind::State;
+ std::string value;
+ int selectionStart = 0;
+ int selectionEnd = 0;
+ bool composing = false;
+};
+
+// Namespace-scope, so the deliver* functions (which the glue calls from the UI
+// thread) are safe before boot and after teardown alike.
+std::mutex g_mutex;
+std::queue<EditorPush> g_queue;
+
+void push(EditorPush item) {
+ std::lock_guard<std::mutex> lk(g_mutex);
+ g_queue.push(std::move(item));
+}
+
+std::string argString(JSContext* ctx, JSValueConst v) {
+ std::string out;
+ if (const char* s = JS_ToCString(ctx, v)) {
+ out = s;
+ JS_FreeCString(ctx, s);
+ }
+ return out;
+}
+
+int argInt(JSContext* ctx, JSValueConst v) {
+ int32_t out = 0;
+ JS_ToInt32(ctx, &out, v);
+ return out;
+}
+
+// es_textEditor_focus(value, selectionStart, selectionEnd, multiline, maxLength, password)
+JSValue js_textEditor_focus(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {
+ if (argc < 6 || !hostAlive() || !host().platform) return JS_UNDEFINED;
+ host().platform->textEditorFocus(argString(ctx, argv[0]), argInt(ctx, argv[1]),
+ argInt(ctx, argv[2]), JS_ToBool(ctx, argv[3]) != 0,
+ argInt(ctx, argv[4]), JS_ToBool(ctx, argv[5]) != 0);
+ return JS_UNDEFINED;
+}
+
+JSValue js_textEditor_blur(JSContext*, JSValueConst, int, JSValueConst*) {
+ if (hostAlive() && host().platform) host().platform->textEditorBlur();
+ return JS_UNDEFINED;
+}
+
+// es_textEditor_write(value, selectionStart, selectionEnd)
+JSValue js_textEditor_write(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {
+ if (argc < 3 || !hostAlive() || !host().platform) return JS_UNDEFINED;
+ host().platform->textEditorWrite(argString(ctx, argv[0]), argInt(ctx, argv[1]),
+ argInt(ctx, argv[2]));
+ return JS_UNDEFINED;
+}
+
+/** The push as the SDK's `es_onNativeTextEditor` reads it. */
+JSValue makePush(HostState& h, const EditorPush& item) {
+ JSValue obj = JS_NewObject(h.js);
+ switch (item.kind) {
+ case EditorPush::Kind::State:
+ JS_SetPropertyStr(h.js, obj, "kind", JS_NewString(h.js, "state"));
+ JS_SetPropertyStr(h.js, obj, "value", JS_NewString(h.js, item.value.c_str()));
+ JS_SetPropertyStr(h.js, obj, "selectionStart", JS_NewInt32(h.js, item.selectionStart));
+ JS_SetPropertyStr(h.js, obj, "selectionEnd", JS_NewInt32(h.js, item.selectionEnd));
+ JS_SetPropertyStr(h.js, obj, "composing", JS_NewBool(h.js, item.composing));
+ break;
+ case EditorPush::Kind::Submit:
+ JS_SetPropertyStr(h.js, obj, "kind", JS_NewString(h.js, "submit"));
+ break;
+ case EditorPush::Kind::Cancel:
+ JS_SetPropertyStr(h.js, obj, "kind", JS_NewString(h.js, "cancel"));
+ break;
+ }
+ return obj;
+}
+
+} // namespace
+
+void drainTextEditor(HostState& h) {
+ std::queue<EditorPush> pending;
+ { std::lock_guard<std::mutex> lk(g_mutex); pending.swap(g_queue); }
+ if (pending.empty()) return;
+
+ JSValue global = JS_GetGlobalObject(h.js);
+ JSValue fn = JS_GetPropertyStr(h.js, global, "es_onNativeTextEditor");
+ while (!pending.empty()) {
+ const EditorPush item = std::move(pending.front());
+ pending.pop();
+ if (!JS_IsFunction(h.js, fn)) continue; // the SDK has not installed it (yet)
+ JSValue arg = makePush(h, item);
+ JSValue ret = JS_Call(h.js, fn, JS_UNDEFINED, 1, &arg);
+ if (JS_IsException(ret)) logJsError(h.js, "es_onNativeTextEditor");
+ JS_FreeValue(h.js, ret);
+ JS_FreeValue(h.js, arg);
+ }
+ JS_FreeValue(h.js, fn);
+ JS_FreeValue(h.js, global);
+}
+
+void registerTextEditorBindings(HostState& h, JSValue global) {
+ // Only when the platform has a keyboard: the SDK treats the entry points as
+ // an all-or-nothing group, so a half-bound host has no surface at all rather
+ // than one that opens a keyboard nobody reads.
+ if (!h.platform || !h.platform->hasTextEditor()) return;
+ bindGlobal(h, global, "es_textEditor_focus", js_textEditor_focus, 6);
+ bindGlobal(h, global, "es_textEditor_blur", js_textEditor_blur, 0);
+ bindGlobal(h, global, "es_textEditor_write", js_textEditor_write, 3);
+}
+
+// Thread-safe: the platform reports from its UI thread, the frame loop delivers.
+void deliverTextEditorState(std::string value, int selectionStart, int selectionEnd, bool composing) {
+ push({EditorPush::Kind::State, std::move(value), selectionStart, selectionEnd, composing});
+}
+
+void deliverTextEditorSubmit() {
+ push({EditorPush::Kind::Submit, {}, 0, 0, false});
+}
+
+void deliverTextEditorCancel() {
+ push({EditorPush::Kind::Cancel, {}, 0, 0, false});
+}
+
+} // namespace eshost
diff --git a/native/host/platform/android.cpp b/native/host/platform/android.cpp
index 432846b9a..942565df4 100644
--- a/native/host/platform/android.cpp
+++ b/native/host/platform/android.cpp
@@ -246,10 +246,140 @@ struct AndroidPlatform final : eshost::Platform {
eshost::deliverFetch(std::move(r));
}).detach();
}
+
+ // -- The editing surface: com.estella.host.TextEditor ---------------------
+ //
+ // An IME commits composed text through an InputConnection, which only a Java
+ // View has — so the keyboard's own side of a field is a small Java class in
+ // the APK, and this is the call across. The class handles its own threading
+ // (every method posts to the UI thread), so these can be called from the
+ // frame loop like any other platform call.
+
+ /** Set once the shim class is loaded and its natives registered (UI thread). */
+ jobject editor = nullptr; // global ref to the TextEditor instance
+ jmethodID editorFocus = nullptr;
+ jmethodID editorBlur = nullptr;
+ jmethodID editorWrite = nullptr;
+
+ bool hasTextEditor() const override { return editor != nullptr; }
+
+ void textEditorFocus(const std::string& value, int selectionStart, int selectionEnd,
+ bool multiline, int maxLength, bool password) override {
+ withEditor([&](JNIEnv* env) {
+ jstring text = env->NewStringUTF(value.c_str());
+ env->CallVoidMethod(editor, editorFocus, text, (jint)selectionStart, (jint)selectionEnd,
+ (jboolean)multiline, (jint)maxLength, (jboolean)password);
+ env->DeleteLocalRef(text);
+ });
+ }
+
+ void textEditorBlur() override {
+ withEditor([&](JNIEnv* env) { env->CallVoidMethod(editor, editorBlur); });
+ }
+
+ void textEditorWrite(const std::string& value, int selectionStart, int selectionEnd) override {
+ withEditor([&](JNIEnv* env) {
+ jstring text = env->NewStringUTF(value.c_str());
+ env->CallVoidMethod(editor, editorWrite, text, (jint)selectionStart, (jint)selectionEnd);
+ env->DeleteLocalRef(text);
+ });
+ }
+
+ /** Run `body` with a JNIEnv for THIS thread (the frame loop's, which is not
+ * the UI thread — the shim posts from there). */
+ template <typename F>
+ void withEditor(F&& body) {
+ if (!editor || !vm) return;
+ JNIEnv* env = nullptr;
+ if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
+ if (vm->AttachCurrentThread(&env, nullptr) != JNI_OK || !env) return;
+ }
+ body(env);
+ if (env->ExceptionCheck()) {
+ env->ExceptionDescribe();
+ env->ExceptionClear();
+ }
+ }
};
AndroidPlatform g_platform;
+// -- The shim's reports, on the UI thread -------------------------------------
+// Queued as POD; the frame loop hands them to JS (see TextEditorBindings.cpp).
+
+void jniTextState(JNIEnv* env, jclass, jstring value, jint selectionStart, jint selectionEnd,
+ jboolean composing) {
+ const char* utf8 = value ? env->GetStringUTFChars(value, nullptr) : nullptr;
+ eshost::deliverTextEditorState(utf8 ? utf8 : "", (int)selectionStart, (int)selectionEnd,
+ composing != JNI_FALSE);
+ if (utf8) env->ReleaseStringUTFChars(value, utf8);
+}
+
+void jniTextSubmit(JNIEnv*, jclass) { eshost::deliverTextEditorSubmit(); }
+void jniTextCancel(JNIEnv*, jclass) { eshost::deliverTextEditorCancel(); }
+
+/**
+ * Load com.estella.host.TextEditor, register its natives and construct it.
+ *
+ * Runs on the frame-loop thread, before boot binds the es_textEditor_* entry
+ * points — the surface has to exist by then or the SDK correctly concludes there
+ * is none. FindClass would fail here (off the UI thread it resolves through the
+ * SYSTEM class loader, which knows nothing of the APK), so the app's own loader
+ * is asked by name instead. Nothing touches a View: the shim posts all of that
+ * to the UI thread itself.
+ */
+void attachTextEditor(ANativeActivity* activity) {
+ if (g_platform.editor || !activity->vm) return;
+ JNIEnv* env = nullptr;
+ if (activity->vm->AttachCurrentThread(&env, nullptr) != JNI_OK || !env) return;
+
+ jclass activityCls = env->GetObjectClass(activity->clazz);
+ const jmethodID getClassLoader =
+ env->GetMethodID(activityCls, "getClassLoader", "()Ljava/lang/ClassLoader;");
+ env->DeleteLocalRef(activityCls);
+ if (!getClassLoader) { env->ExceptionClear(); return; }
+ jobject loader = env->CallObjectMethod(activity->clazz, getClassLoader);
+ jclass loaderCls = env->FindClass("java/lang/ClassLoader");
+ const jmethodID loadClass =
+ env->GetMethodID(loaderCls, "loadClass", "(Ljava/lang/String;)Ljava/lang/Class;");
+ env->DeleteLocalRef(loaderCls);
+ jstring name = env->NewStringUTF("com.estella.host.TextEditor");
+ jclass cls = (jclass)env->CallObjectMethod(loader, loadClass, name);
+ env->DeleteLocalRef(name);
+ env->DeleteLocalRef(loader);
+ if (!cls || env->ExceptionCheck()) {
+ env->ExceptionClear();
+ __android_log_print(ANDROID_LOG_WARN, LOG_TAG,
+ "text editor: com.estella.host.TextEditor not in the APK — typing is off");
+ return;
+ }
+ const JNINativeMethod natives[] = {
+ {"nativeState", "(Ljava/lang/String;IIZ)V", (void*)jniTextState},
+ {"nativeSubmit", "()V", (void*)jniTextSubmit},
+ {"nativeCancel", "()V", (void*)jniTextCancel},
+ };
+ if (env->RegisterNatives(cls, natives, 3) != JNI_OK) {
+ env->ExceptionClear();
+ env->DeleteLocalRef(cls);
+ return;
+ }
+
+ const jmethodID ctor = env->GetMethodID(cls, "<init>", "(Landroid/app/Activity;)V");
+ g_platform.editorFocus = env->GetMethodID(cls, "focus", "(Ljava/lang/String;IIZIZ)V");
+ g_platform.editorBlur = env->GetMethodID(cls, "blur", "()V");
+ g_platform.editorWrite = env->GetMethodID(cls, "write", "(Ljava/lang/String;II)V");
+ if (!ctor || !g_platform.editorFocus || !g_platform.editorBlur || !g_platform.editorWrite) {
+ env->ExceptionClear();
+ env->DeleteLocalRef(cls);
+ return;
+ }
+ jobject instance = env->NewObject(cls, ctor, activity->clazz);
+ if (instance) g_platform.editor = env->NewGlobalRef(instance);
+ if (instance) env->DeleteLocalRef(instance);
+ env->DeleteLocalRef(cls);
+ __android_log_print(ANDROID_LOG_INFO, LOG_TAG, "text editor: soft keyboard up (IME)");
+}
+
int32_t onInput(android_app*, AInputEvent* ev) {
if (!eshost::booted() || AInputEvent_getType(ev) != AINPUT_EVENT_TYPE_MOTION) return 0;
const int32_t action = AMotionEvent_getAction(ev) & AMOTION_EVENT_ACTION_MASK;
@@ -476,6 +606,9 @@ void onWindowFocusChanged(ANativeActivity* activity, int hasFocus) {
void android_main(android_app* app) {
g_platform.assets = app->activity->assetManager; // APK assets/ (the exported project)
g_platform.vm = app->activity->vm; // for JNI HttpURLConnection (es_fetch)
+ // Before boot: whether there is an editing surface decides whether the
+ // es_textEditor_* entry points are bound at all.
+ attachTextEditor(app->activity);
if (app->activity->internalDataPath) g_platform.cache = app->activity->internalDataPath;
app->onAppCmd = onAppCmd;
app->onInputEvent = onInput;
diff --git a/native/host/platform/ios.mm b/native/host/platform/ios.mm
index aedf8843f..836b0fa4b 100644
--- a/native/host/platform/ios.mm
+++ b/native/host/platform/ios.mm
@@ -33,10 +33,40 @@ using esengine::WebGPUDevice;
@class EstellaViewController;
+/** What the platform needs of whoever owns the keyboard's responder. A role, not
+ * a class, so the C++ side names no view controller. */
+@protocol EstellaTextEditorHost <NSObject>
+- (void)textEditorFocus:(NSString*)value selectionStart:(NSInteger)selectionStart
+ selectionEnd:(NSInteger)selectionEnd multiline:(BOOL)multiline
+ maxLength:(NSInteger)maxLength password:(BOOL)password;
+- (void)textEditorBlur;
+- (void)textEditorWrite:(NSString*)value selectionStart:(NSInteger)selectionStart
+ selectionEnd:(NSInteger)selectionEnd;
+@end
+
namespace {
struct IOSPlatform final : eshost::Platform {
CAMetalLayer* layer = nil;
+ // Whoever owns the responder the keyboard talks to (the view controller); set
+ // once it has loaded, which is also what makes hasTextEditor() true.
+ __weak id<EstellaTextEditorHost> editorHost = nil;
+
+ bool hasTextEditor() const override { return editorHost != nil; }
+
+ void textEditorFocus(const std::string& value, int selectionStart, int selectionEnd,
+ bool multiline, int maxLength, bool password) override {
+ NSString* text = [NSString stringWithUTF8String:value.c_str()] ?: @"";
+ [editorHost textEditorFocus:text selectionStart:selectionStart selectionEnd:selectionEnd
+ multiline:multiline maxLength:maxLength password:password];
+ }
+
+ void textEditorBlur() override { [editorHost textEditorBlur]; }
+
+ void textEditorWrite(const std::string& value, int selectionStart, int selectionEnd) override {
+ NSString* text = [NSString stringWithUTF8String:value.c_str()] ?: @"";
+ [editorHost textEditorWrite:text selectionStart:selectionStart selectionEnd:selectionEnd];
+ }
// A file shipped inside the .app bundle — the packaged-asset analog of the
// APK's assets/. Paths are project-relative ("game.config.json", "logo.png"),
@@ -197,12 +227,19 @@ IOSPlatform g_platform;
+ (Class)layerClass { return [CAMetalLayer class]; }
@end
-@interface EstellaViewController : UIViewController
+// The app's editing surface: a real UITextView, invisible, that the keyboard and
+// its IME talk to. Core Text draws the field itself, but composition (pinyin,
+// kana, prediction) is delivered only to a UIKit responder — so the responder is
+// what this holds, and nothing else about the field lives here.
+@interface EstellaViewController : UIViewController <UITextViewDelegate, EstellaTextEditorHost>
@end
@implementation EstellaViewController {
CADisplayLink* _displayLink;
BOOL _booted;
+ UITextView* _editor;
+ BOOL _multiline;
+ BOOL _writing; // set while adopting a value the app decided, so it is not echoed back
}
- (void)loadView {
@@ -212,6 +249,9 @@ IOSPlatform g_platform;
- (void)viewDidLoad {
[super viewDidLoad];
+ // Before boot: whether there is an editing surface decides whether the
+ // es_textEditor_* entry points are bound at all.
+ g_platform.editorHost = self;
_displayLink = [CADisplayLink displayLinkWithTarget:self selector:@selector(step:)];
[_displayLink addToRunLoop:NSRunLoop.mainRunLoop forMode:NSRunLoopCommonModes];
@@ -285,6 +325,92 @@ IOSPlatform g_platform;
- (BOOL)prefersStatusBarHidden { return YES; }
+// -- The editing surface ------------------------------------------------------
+
+/** The responder, created on first use. Off-screen and clear: it must be a real,
+ * attached view for the keyboard to attach to, but the game draws the field. */
+- (UITextView*)ensureEditor {
+ if (_editor) return _editor;
+ _editor = [[UITextView alloc] initWithFrame:CGRectMake(-100, -100, 1, 1)];
+ _editor.delegate = self;
+ _editor.backgroundColor = UIColor.clearColor;
+ _editor.textColor = UIColor.clearColor;
+ _editor.tintColor = UIColor.clearColor; // no system caret; the game draws its own
+ _editor.autocorrectionType = UITextAutocorrectionTypeNo;
+ _editor.autocapitalizationType = UITextAutocapitalizationTypeNone;
+ [self.view addSubview:_editor];
+ return _editor;
+}
+
+- (void)textEditorFocus:(NSString*)value selectionStart:(NSInteger)selectionStart
+ selectionEnd:(NSInteger)selectionEnd multiline:(BOOL)multiline
+ maxLength:(NSInteger)maxLength password:(BOOL)password {
+ UITextView* editor = [self ensureEditor];
+ _multiline = multiline;
+ _writing = YES;
+ editor.text = value;
+ editor.returnKeyType = multiline ? UIReturnKeyDefault : UIReturnKeyDone;
+ // The field renders its own bullets; this is for the keyboard's benefit — no
+ // suggestion strip or autocorrect over a password.
+ editor.textContentType = password ? UITextContentTypePassword : nil;
+ editor.secureTextEntry = password;
+ [self setEditorSelectionStart:selectionStart end:selectionEnd];
+ _writing = NO;
+ [editor becomeFirstResponder];
+}
+
+- (void)textEditorBlur {
+ [_editor resignFirstResponder];
+}
+
+- (void)textEditorWrite:(NSString*)value selectionStart:(NSInteger)selectionStart
+ selectionEnd:(NSInteger)selectionEnd {
+ if (!_editor) return;
+ _writing = YES;
+ if (![_editor.text isEqualToString:value]) _editor.text = value;
+ [self setEditorSelectionStart:selectionStart end:selectionEnd];
+ _writing = NO;
+}
+
+- (void)setEditorSelectionStart:(NSInteger)start end:(NSInteger)end {
+ const NSInteger length = (NSInteger)_editor.text.length;
+ const NSInteger lo = MAX(0, MIN(start, length));
+ const NSInteger hi = MAX(lo, MIN(end, length));
+ _editor.selectedRange = NSMakeRange((NSUInteger)lo, (NSUInteger)(hi - lo));
+}
+
+/** Hand the responder's whole state to the engine. A marked range IS the IME
+ * preedit, so that is what `composing` asks about. */
+- (void)reportEditorState {
+ if (_writing || !_editor) return;
+ const NSRange selection = _editor.selectedRange;
+ const BOOL composing = _editor.markedTextRange != nil;
+ eshost::deliverTextEditorState(_editor.text.UTF8String ?: "",
+ (int)selection.location,
+ (int)(selection.location + selection.length), composing);
+}
+
+- (void)textViewDidChange:(UITextView*)textView { [self reportEditorState]; }
+
+- (void)textViewDidChangeSelection:(UITextView*)textView { [self reportEditorState]; }
+
+- (BOOL)textView:(UITextView*)textView shouldChangeTextInRange:(NSRange)range
+ replacementText:(NSString*)text {
+ // Return on a single-line field submits instead of inserting a newline —
+ // the same rule the web's Enter follows.
+ if (!_multiline && [text isEqualToString:@"\n"]) {
+ eshost::deliverTextEditorSubmit();
+ return NO;
+ }
+ return YES;
+}
+
+- (void)textViewDidEndEditing:(UITextView*)textView {
+ // The keyboard went away (done, or another responder took over): for a UI
+ // field that is losing focus, which is what Escape does on the web.
+ eshost::deliverTextEditorCancel();
+}
+
@end
@interface EstellaAppDelegate : UIResponder <UIApplicationDelegate>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index b401324f3..58e1e42a6 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -4088,6 +4088,7 @@ registerInput: (listener: NativeInputListener) => () => void
removeStorageItem: (key: string) => void
setStorageItem: (key: string, value: string) => void
storageKeys: () => string[]
+textEditor: NativeTextEditorBridge | undefined
writeCacheFile: ((key: string, bytes: ArrayBuffer) => Promise<void>) | undefined
```
@@ -4146,6 +4147,9 @@ es_readCacheFile: ((key: string) => ArrayBuffer | null) | undefined
es_removeStorageItem: ((key: string) => void) | undefined
es_setStorageItem: ((key: string, value: string) => void) | undefined
es_storageKeys: (() => string[]) | undefined
+es_textEditor_blur: (() => void) | undefined
+es_textEditor_focus: ((value: string, selectionStart: number, selectionEnd: number, multiline: boolean, maxLength: number, password: boolean) => void) | undefined
+es_textEditor_write: ((value: string, selectionStart: number, selectionEnd: number) => void) | undefined
es_writeCacheFile: ((key: string, bytes: ArrayBuffer | Uint8Array | string) => boolean) | undefined
```
@@ -4173,6 +4177,7 @@ clearStorage: (prefix: string) => void
createAudioBackend: (() => PlatformAudioBackend) | undefined
createCanvas: (_width: number, _height: number) => PlatformCanvas
createImage: () => PlatformImage
+createTextEditor: () => PlatformTextEditor | null
createVideoBackend: (ctx: VideoBackendContext) => PlatformVideoBackend
devicePixelRatio: () => number
fetch: (url: string, options?: PlatformRequestOptions) => Promise<PlatformResponse>
diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.ts
index 6d6bbb04b..73cbd4783 100644
--- a/sdk/src/platform/native/adapter.ts
+++ b/sdk/src/platform/native/adapter.ts
@@ -25,6 +25,7 @@ import type {
PlatformImage,
PlatformGlyph,
PlatformGlyphRequest,
+ PlatformTextEditor,
} from '../types';
import type { PlatformAudioBackend } from '../../audio/PlatformAudioBackend';
import type { PlatformVideoBackend, VideoBackendContext } from '../../video/PlatformVideoBackend';
@@ -32,6 +33,7 @@ import { WasmVideoBackend } from '../../video/WasmVideoBackend';
import { setPlatform } from '../base';
import { createPrimaryPointer } from '../primaryPointer';
import { NativeAudioBackend } from '../../audio/NativeAudioBackend';
+import { createNativeTextEditor } from './textEditor';
import type { NativeBridge, NativeInputListener } from './bridge';
export class NativePlatformAdapter implements PlatformAdapter {
@@ -117,6 +119,13 @@ export class NativePlatformAdapter implements PlatformAdapter {
throw new Error('[native] no DOM images — decode via loadImagePixels');
}
+ /** The OS soft keyboard + IME, when the host wired one. Null → editable
+ * fields render but cannot be typed into (platform/native/textEditor.ts). */
+ createTextEditor(): PlatformTextEditor | null {
+ const editor = this.bridge_.textEditor;
+ return editor ? createNativeTextEditor(editor) : null;
+ }
+
now(): number {
return this.bridge_.now?.() ?? Date.now();
}
diff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.ts
index e45243663..ae23c0471 100644
--- a/sdk/src/platform/native/bridge.ts
+++ b/sdk/src/platform/native/bridge.ts
@@ -49,6 +49,41 @@ export interface NativeInputListener {
onKeyUp?(code: string): void;
}
+/** What the OS editing surface reports back. `state` carries the surface's whole
+ * value + selection (it is the owner while focused); `composing` is absent on a
+ * host that cannot tell whether an IME preedit is in flight. */
+export type NativeTextEditorPush =
+ | {
+ kind: 'state';
+ value: string;
+ selectionStart: number;
+ selectionEnd: number;
+ composing?: boolean;
+ }
+ | { kind: 'submit' }
+ | { kind: 'cancel' };
+
+/**
+ * The host's text-editing surface: the OS soft keyboard and its IME. Present only
+ * when the host bound it — a host without one omits `NativeBridge.textEditor`
+ * and editable fields render but do not type, the way a host without a sound
+ * device stays silent.
+ *
+ * `focus` opens the keyboard on the field's current value; `write` pushes an edit
+ * the app made (a programmatic setValue, a tap that moved the caret); everything
+ * the user does comes back through `subscribe`.
+ */
+export interface NativeTextEditorBridge {
+ focus(
+ value: string, selectionStart: number, selectionEnd: number,
+ multiline: boolean, maxLength: number, password: boolean,
+ ): void;
+ blur(): void;
+ write(value: string, selectionStart: number, selectionEnd: number): void;
+ /** Returns an unsubscribe. */
+ subscribe(handler: (push: NativeTextEditorPush) => void): () => void;
+}
+
/**
* The host's native audio engine, wrapped as a small object so {@link
* NativeAudioBackend} stays a thin adapter over it (mirroring the WeChat backend
@@ -139,6 +174,11 @@ export interface NativeBridge {
* Null backend. See {@link NativeAudioBridge}. */
audio?: NativeAudioBridge;
+ /** The OS text-editing surface (soft keyboard + IME), when the host has wired
+ * one. Absent → fields render but cannot be typed into, exactly as a host
+ * with no audio device stays silent. See {@link NativeTextEditorBridge}. */
+ textEditor?: NativeTextEditorBridge;
+
/** App foreground/background signals (no DOM visibility on native): the shell
* pushes them, the adapter surfaces them as `onAppShow`/`onAppHide`, and the
* Lifecycle plugin auto-pauses on hide. Each returns an unsubscribe. Optional —
diff --git a/sdk/src/platform/native/hostBridge.ts b/sdk/src/platform/native/hostBridge.ts
index 6eeb86dde..590f17b96 100644
--- a/sdk/src/platform/native/hostBridge.ts
+++ b/sdk/src/platform/native/hostBridge.ts
@@ -13,7 +13,10 @@
*/
import { log } from '../../logger';
-import type { NativeAudioBridge, NativeBridge, NativeFetchResult, NativeInputListener } from './bridge';
+import type {
+ NativeAudioBridge, NativeBridge, NativeFetchResult, NativeInputListener,
+ NativeTextEditorBridge, NativeTextEditorPush,
+} from './bridge';
import type { PlatformGlyph, PlatformGlyphRequest, PlatformRequestOptions } from '../types';
import { assertHostEnvironment } from './hostEnvironment';
import { hasAudioBindings } from '../../ecs/nativeBindings';
@@ -73,6 +76,17 @@ export interface NativeHostBindings {
/** The native audio engine, all-or-nothing (see {@link AUDIO_BINDINGS}). A
* host without a sound device binds none and stays silent. */
+ // The OS text-editing surface (soft keyboard + IME). Optional as a group:
+ // hasTextEditorBindings gates them, so a host that wired none simply has no
+ // editing surface. The host pushes what the user did through
+ // es_onNativeTextEditor, installed here.
+ es_textEditor_focus?(
+ value: string, selectionStart: number, selectionEnd: number,
+ multiline: boolean, maxLength: number, password: boolean,
+ ): void;
+ es_textEditor_blur?(): void;
+ es_textEditor_write?(value: string, selectionStart: number, selectionEnd: number): void;
+
es_audioLoad?(bytes: ArrayBuffer): { id: number; duration: number; bytes: number } | null;
es_audioUnload?(bufferId: number): void;
es_audioPlay?(bufferId: number, volume: number, pan: number, loop: boolean, rate: number): number;
@@ -120,6 +134,7 @@ export function createHostBridge(
const storage = hostStorage(bindings);
const audio = hostAudio(bindings, scope);
+ const textEditor = hostTextEditor(bindings, scope);
const lifecycle = hostLifecycle(scope);
return {
@@ -156,6 +171,7 @@ export function createHostBridge(
},
devicePixelRatio: () => bindings.es_devicePixelRatio?.() ?? 1,
...(audio ? { audio } : {}),
+ ...(textEditor ? { textEditor } : {}),
...lifecycle,
};
}
@@ -247,6 +263,37 @@ function hostAudio(
};
}
+/**
+ * The host's editing surface, when it bound one: calls out through its
+ * `es_textEditor_*` entry points, and takes what the user did through
+ * `es_onNativeTextEditor`, installed here the way the lifecycle signals are.
+ * All-or-nothing — a host with only some of the entry points has no surface,
+ * rather than one that opens a keyboard it cannot read.
+ */
+function hostTextEditor(
+ bindings: NativeHostBindings,
+ scope: Record<string, unknown>,
+): NativeTextEditorBridge | undefined {
+ if (!bindings.es_textEditor_focus || !bindings.es_textEditor_blur || !bindings.es_textEditor_write) {
+ return undefined;
+ }
+ let subs: ((push: NativeTextEditorPush) => void)[] = [];
+ scope.es_onNativeTextEditor = (push: NativeTextEditorPush): void => {
+ for (const cb of subs) cb(push);
+ };
+ return {
+ focus: (value, selectionStart, selectionEnd, multiline, maxLength, password) =>
+ bindings.es_textEditor_focus!(value, selectionStart, selectionEnd, multiline, maxLength, password),
+ blur: () => bindings.es_textEditor_blur!(),
+ write: (value, selectionStart, selectionEnd) =>
+ bindings.es_textEditor_write!(value, selectionStart, selectionEnd),
+ subscribe: (handler) => {
+ subs.push(handler);
+ return () => { subs = subs.filter((s) => s !== handler); };
+ },
+ };
+}
+
/**
* The lifecycle signals the host pushes (like touch), each installed as an
* `es_onNative*` entry the shell calls and exposed as a subscribe/unsubscribe on
diff --git a/sdk/src/platform/native/textEditor.ts b/sdk/src/platform/native/textEditor.ts
new file mode 100644
index 000000000..aefec3f49
--- /dev/null
+++ b/sdk/src/platform/native/textEditor.ts
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file platform/native/textEditor.ts
+ * @brief The device's editing surface — the OS soft keyboard and its IME —
+ * behind the platform's {@link PlatformTextEditor} contract.
+ *
+ * The keyboard lives on the OS side of the boundary and reports asynchronously
+ * (a UI-thread callback, drained into the frame), while a field reads its value
+ * synchronously while rendering. So this keeps a MIRROR of the surface's state,
+ * refreshed by every push from the host, and answers `read()` from it. The host
+ * remains the owner: an edit the app makes goes out through `write` and comes
+ * back as a push, so there is one order of events and never two truths.
+ */
+import type {
+ PlatformTextEditor, TextEditorEvent, TextEditorOptions, TextEditorState,
+} from '../types';
+import type { NativeTextEditorBridge } from './bridge';
+
+export function createNativeTextEditor(bridge: NativeTextEditorBridge): PlatformTextEditor {
+ let state: TextEditorState = { value: '', selectionStart: 0, selectionEnd: 0, backward: false };
+ let focused = false;
+ let composingNow = false;
+ const handlers = new Set<(event: TextEditorEvent) => void>();
+ const emit = (event: TextEditorEvent): void => {
+ for (const handler of handlers) handler(event);
+ };
+
+ const unsubscribe = bridge.subscribe((next) => {
+ switch (next.kind) {
+ case 'state': {
+ const composing = next.composing;
+ state = {
+ value: next.value,
+ selectionStart: next.selectionStart,
+ selectionEnd: next.selectionEnd,
+ backward: false, // no platform keyboard reports a selection's direction
+ };
+ if (composing !== undefined && composing !== composingNow) {
+ composingNow = composing;
+ emit({ kind: 'composition', composing });
+ }
+ emit({ kind: 'change' });
+ break;
+ }
+ case 'submit':
+ emit({ kind: 'submit' });
+ break;
+ case 'cancel':
+ // The keyboard was dismissed (back gesture / done): the field is no
+ // longer being edited, which for a UI field means losing focus.
+ focused = false;
+ emit({ kind: 'blur' });
+ break;
+ }
+ });
+
+ return {
+ focus(next: TextEditorState, options: TextEditorOptions): void {
+ state = { ...next };
+ focused = true;
+ bridge.focus(next.value, next.selectionStart, next.selectionEnd,
+ options.multiline, options.maxLength, options.password);
+ },
+ blur(): void {
+ if (!focused) return;
+ focused = false;
+ bridge.blur();
+ },
+ read(): TextEditorState {
+ return state;
+ },
+ write(next: TextEditorState): void {
+ state = { ...next };
+ bridge.write(next.value, next.selectionStart, next.selectionEnd);
+ },
+ subscribe(handler: (event: TextEditorEvent) => void): () => void {
+ handlers.add(handler);
+ return () => { handlers.delete(handler); };
+ },
+ dispose(): void {
+ unsubscribe();
+ handlers.clear();
+ if (focused) bridge.blur();
+ focused = false;
+ },
+ };
+}