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.

fix(native): a phone runs the scripts a browser runs — V8 with Intl, and TextEncoder

yhha7045dc2fd1b
diff --git a/bench/aot-native/README.md b/bench/aot-native/README.md
index ffb9afd65..9801c549f 100644
--- a/bench/aot-native/README.md
+++ b/bench/aot-native/README.md
@@ -74,8 +74,11 @@ system properties there (`adb shell setprop debug.estella.bench_frames 300`, lik
| thin | interpreted | 63.68 ms | **13.97 ms** |
| thin | compiled | 5.01 ms | **4.15 ms** |
-4.6x on the phone for a project that changes nothing. The V8 APK is 11.5 MB larger
-(44.4 vs 32.9 MB): `libv8android.so` is 15.5 MB, stored uncompressed.
+4.6x on the phone for a project that changes nothing. Those numbers are the nointl V8;
+the shipped one carries Intl (a game script with a Unicode property escape did not
+parse without it) and measures the same (14.32 / 4.78 ms). Its APK is 20.9 MB larger
+than the QuickJS one (53.8 vs 32.9 MB): `libv8android.so` is 24.9 MB, stored
+uncompressed.
## What was measured (2026-08-27, i5-14600K, Windows, QuickJS-ng in the native host)
diff --git a/docs/astro/src/content/docs/publishing/android-ios.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdx
index f1ca8c88c..8ae917072 100644
--- a/docs/astro/src/content/docs/publishing/android-ios.mdx
+++ b/docs/astro/src/content/docs/publishing/android-ios.mdx
@@ -270,8 +270,10 @@ The engine runs native at full speed everywhere. Your game script does too on
is compiled to machine code as it would be in a browser, with nothing to change in
the project. On a Snapdragon 8 Elite phone, a frame of 5,000 scripted entities that
took 64 ms on the interpreter takes 14 ms on V8 (on a desktop CPU: 76 ms → 8 ms).
-V8 adds about 11 MB to a package (`libv8android.so` per ABI, stored uncompressed as
-Android prefers for native libraries).
+V8 adds about 21 MB to a package: `libv8android.so` per ABI, with the Unicode data
+`Intl` and Unicode regular expressions (`/\p{L}/u`) need, stored uncompressed as
+Android prefers for native libraries. Scripts see the same language a browser runs;
+`TextEncoder` / `TextDecoder` are provided by the host.
On **iOS** your game script is interpreted, by QuickJS: Apple's rules allow no JIT
outside its own browser. A per-entity loop written in TypeScript is the one thing
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
index 622abf3e8..89da98308 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
@@ -226,8 +226,9 @@ Android 的下限是 29,因为引擎的字体路径调用 `AFontMatcher_create`,
引擎在各平台都以原生全速运行。**Android** 上游戏脚本也一样:它跑在带 JIT 的 V8 上,
和 Chrome 是同一个引擎——同一份脚本会像在浏览器里那样编译成机器码,项目里什么都不用改。
在骁龙 8 Elite 手机上:5000 个脚本实体的一帧,解释器要 64 毫秒,V8 上是 14 毫秒
-(桌面 CPU 上是 76 → 8 毫秒)。V8 让包体大约增加 11 MB(每个 ABI 一份 `libv8android.so`,
-按 Android 对原生库的偏好不压缩存放)。
+(桌面 CPU 上是 76 → 8 毫秒)。V8 让包体大约增加 21 MB:每个 ABI 一份 `libv8android.so`,
+带上 `Intl` 与 Unicode 正则(`/\p{L}/u`)要用的 Unicode 数据,按 Android 对原生库的偏好不压缩存放。
+脚本看到的是和浏览器一样的语言;`TextEncoder` / `TextDecoder` 由宿主提供。
**iOS** 上游戏脚本由 QuickJS 解释执行:Apple 不允许自家浏览器以外的 JIT。
用 TypeScript 写的逐实体循环,是那里比浏览器里明显更贵的那一样东西——
diff --git a/native/host/bootstrap.js b/native/host/bootstrap.js
index a9ec2a4f4..cffbb5c26 100644
--- a/native/host/bootstrap.js
+++ b/native/host/bootstrap.js
@@ -8,15 +8,78 @@
// Deliberately small. The bridge itself is assembled by the SDK
// (createHostBridge) from the es_* primitives the host binds — typed there
// against the interface it must satisfy — so what is left here is only what a JS
-// string in the host can do: the TextDecoder shim, and the default entry points.
+// string in the host can do: the TextDecoder / TextEncoder shims, and the default entry points.
// The platform layer decodes packaged JSON through TextDecoder; QuickJS has none,
// so route it to the host's UTF-8 decoder. Only utf-8 is meaningful here.
globalThis.TextDecoder = function TextDecoder() {};
+globalThis.TextDecoder.prototype.encoding = 'utf-8';
globalThis.TextDecoder.prototype.decode = function (buf) {
return buf == null ? '' : es_utf8Decode(buf);
};
+// Its other half, which neither engine ships either (V8 and QuickJS are languages;
+// TextEncoder is the browser's): a game encoding a protocol message or a save as
+// UTF-8 bytes stopped at "TextEncoder is not defined" on a device. Plain JS — the
+// WHATWG algorithm, a lone surrogate becoming U+FFFD as it does in a browser.
+if (typeof globalThis.TextEncoder !== 'function') {
+ var utf8Into = function (str, out, at) {
+ var n = str.length;
+ for (var i = 0; i < n; i++) {
+ var c = str.charCodeAt(i);
+ if (c >= 0xd800 && c <= 0xdbff && i + 1 < n) {
+ var d = str.charCodeAt(i + 1);
+ if (d >= 0xdc00 && d <= 0xdfff) { c = 0x10000 + ((c - 0xd800) << 10) + (d - 0xdc00); i++; }
+ else c = 0xfffd;
+ } else if (c >= 0xd800 && c <= 0xdfff) {
+ c = 0xfffd;
+ }
+ if (c < 0x80) {
+ if (out) out[at] = c;
+ at += 1;
+ } else if (c < 0x800) {
+ if (out) { out[at] = 0xc0 | (c >> 6); out[at + 1] = 0x80 | (c & 63); }
+ at += 2;
+ } else if (c < 0x10000) {
+ if (out) { out[at] = 0xe0 | (c >> 12); out[at + 1] = 0x80 | ((c >> 6) & 63); out[at + 2] = 0x80 | (c & 63); }
+ at += 3;
+ } else {
+ if (out) {
+ out[at] = 0xf0 | (c >> 18); out[at + 1] = 0x80 | ((c >> 12) & 63);
+ out[at + 2] = 0x80 | ((c >> 6) & 63); out[at + 3] = 0x80 | (c & 63);
+ }
+ at += 4;
+ }
+ }
+ return at;
+ };
+ globalThis.TextEncoder = function TextEncoder() {};
+ globalThis.TextEncoder.prototype.encoding = 'utf-8';
+ globalThis.TextEncoder.prototype.encode = function (input) {
+ var str = input === undefined ? '' : String(input);
+ var out = new Uint8Array(utf8Into(str, null, 0));
+ utf8Into(str, out, 0);
+ return out;
+ };
+ globalThis.TextEncoder.prototype.encodeInto = function (input, dest) {
+ var bytes = this.encode(input);
+ var written = Math.min(bytes.length, dest.length);
+ // Never half a character: back off to the last whole one that fits.
+ while (written > 0 && written < bytes.length && (bytes[written] & 0xc0) === 0x80) written--;
+ dest.set(bytes.subarray(0, written));
+ var read = 0, w = 0;
+ for (var i = 0; i < String(input).length && w < written; i++) {
+ var c = String(input).charCodeAt(i);
+ var size = c < 0x80 ? 1 : c < 0x800 ? 2 : (c >= 0xd800 && c <= 0xdbff) ? 4 : 3;
+ if (w + size > written) break;
+ w += size;
+ read += size === 4 ? 2 : 1;
+ if (size === 4) i++;
+ }
+ return { read: read, written: written };
+ };
+}
+
// The whole host contract in one check — the JS globals a bare engine lacks and
// the es_* bindings this shell binds — so a gap is named here, not downstream.
ESEngine.assertNativeHost(globalThis);
diff --git a/toolchain.manifest.json b/toolchain.manifest.json
index 7d6065959..3d5a77e13 100644
--- a/toolchain.manifest.json
+++ b/toolchain.manifest.json
@@ -78,9 +78,13 @@
}
],
"android": {
- "$comment": "v8-android-jit-nointl 11.1000.4 is V8 10.0.139.9 built for the NDK's libc++ (react-native's prebuilt).",
- "url": "https://registry.npmjs.org/v8-android-jit-nointl/-/v8-android-jit-nointl-11.1000.4.tgz",
- "sha256": "46870658adfe0f6eaa4819226af37a25663bd54599304dd7d7c91ed1089dae9e"
+ "$comment": [
+ "v8-android-jit 11.1000.4 is V8 10.0.139.9 built for the NDK's libc++ (react-native's",
+ "prebuilt), WITH Intl: the nointl build has no Unicode property escapes in regular",
+ "expressions, so a game script that a browser and QuickJS both run failed to parse."
+ ],
+ "url": "https://registry.npmjs.org/v8-android-jit/-/v8-android-jit-11.1000.4.tgz",
+ "sha256": "9948d0ea2600b762254a49281bbd73df81840cc17afc3e30c00df136e0467d50"
}
}
},