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 terrain and a streamed world run on a device with no wasm heap and no AbortController

yhhceceac06cbab
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e4e928ce3..e91a49ce0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,10 @@ published separately; it ships inside the editor.
- **The profiler's tables sort by their column header.** Click a column of the cost tree or the systems list to order it by name or by time, and again to reverse it; the choice is remembered. Ranking by time moved a name whenever two systems passed each other, which is every few frames on a live window, so a reader could not follow one; by name the rows stay where they are. The systems list names twelve systems instead of five, so the members change less often too.
+### Fixed
+
+- **A terrain and a streamed world run on the Android and iOS templates.** The terrain's layer textures were refused on a device (it has no wasm heap to copy them through), and a chunked world's maker threw on every tick because QuickJS has no `AbortController`. The layers now go over as bytes, as every other texture does, and the world uses a handle of its own where the host has none.
+
## [0.96.0] - 2026-10-27
### Added
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 83a838e15..cbad5951a 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -8054,7 +8054,7 @@ ReadonlyMap<string, string>
## RESOURCE_BINDINGS — const @experimental
```
-{ readonly createTexture: "es_rm_createTextureEx"; readonly createTextureKTX2: "es_createTextureKTX2"; readonly releaseTexture: "es_rm_releaseTexture"; readonly registerTextureWithPath: "es_rm_registerTextureWithPath"; readonly getTextureDimensions: "es_getTextureDimensions"; }
+{ readonly createTexture: "es_rm_createTextureEx"; readonly createTextureArray: "es_rm_createTextureArray"; readonly createTextureKTX2: "es_createTextureKTX2"; readonly releaseTexture: "es_rm_releaseTexture"; readonly registerTextureWithPath: "es_rm_registerTextureWithPath"; readonly getTextureDimensions: "es_getTextureDimensions"; }
```
## RETIRED_COMPONENT_TYPES — const @experimental
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 9fedc07fb..ae33ddfe1 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -245,6 +245,7 @@ createLabelAtlasFont: (textureHandle: number, texWidth: number, texHeight: numbe
createShader: (vertSrc: string, fragSrc: string) => number
createTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, content: TextureContent) => number
createTextureArray: ((width: number, height: number, layers: number, pixels: number, pixelsLen: number, format: number, filterMode: number, wrapMode: number, content: TextureContent) => number) | undefined
+createTextureArrayFromBytes: ((width: number, height: number, layers: number, pixels: Uint8Array, format: number, filterMode: number, wrapMode: number, content: TextureContent) => number) | undefined
createTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number, content: TextureContent) => number
createTextureFromBytes: ((width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, content: TextureContent, filterMode?: number, wrapMode?: number) => number) | undefined
createTextureFromKTX2: ((bytes: Uint8Array, srgb: boolean) => { handle: number; width: number; height: number; format?: number; blockRefused?: boolean; } | null) | undefined
diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.ts
index a7e2c69e1..b30919f80 100644
--- a/sdk/src/ecs/bridge/nativeBindings.ts
+++ b/sdk/src/ecs/bridge/nativeBindings.ts
@@ -85,6 +85,7 @@ export const COMPOSITION_BINDINGS = {
*/
export const RESOURCE_BINDINGS = {
createTexture: 'es_rm_createTextureEx',
+ createTextureArray: 'es_rm_createTextureArray',
createTextureKTX2: 'es_createTextureKTX2',
releaseTexture: 'es_rm_releaseTexture',
registerTextureWithPath: 'es_rm_registerTextureWithPath',
diff --git a/sdk/src/ecs/bridge/nativeResourceManager.ts b/sdk/src/ecs/bridge/nativeResourceManager.ts
index e23c530f8..194132119 100644
--- a/sdk/src/ecs/bridge/nativeResourceManager.ts
+++ b/sdk/src/ecs/bridge/nativeResourceManager.ts
@@ -76,6 +76,12 @@ export function createNativeResourceManager(
[width, height, pixels, pixels.length, format, flipY,
filterMode ?? FILTER_LINEAR, wrapMode ?? WRAP_CLAMP_TO_EDGE, content]) as number,
+ // A texture array from its layers back to back, as the engine's `rm_createTextureArray` takes them: the host copies the bytes, as it does
+ // for `createTextureFromBytes`, so the terrain's layer arrays exist on a device with no wasm heap.
+ createTextureArrayFromBytes: (width, height, layers, pixels, format, filterMode, wrapMode, content): number =>
+ hostCall(scope, RESOURCE_BINDINGS.createTextureArray,
+ [width, height, layers, pixels, pixels.length, format, filterMode, wrapMode, content]) as number,
+
// The host transcodes KTX2 (basis) and uploads the blocks:
// { id, width, height, format, blockRefused } → { handle, ... }. A host
// without the last two leaves them undefined, never a compressed answer.
diff --git a/sdk/src/residency/chunks.ts b/sdk/src/residency/chunks.ts
index f8c0b3350..7e20915c6 100644
--- a/sdk/src/residency/chunks.ts
+++ b/sdk/src/residency/chunks.ts
@@ -19,6 +19,7 @@
* provider still working on the planet just left) is thrown away, never published.
* - A chunk whose making throws is failed until the generation changes, and says why.
*/
+import { createAbort, type AbortHandle } from '../util/abort';
import type { App } from '../app/app';
import { defineResource } from '../ecs/resource';
import { defineSystem, Schedule } from '../ecs/system';
@@ -83,7 +84,7 @@ interface Chunk<T> {
value: T | null;
publishedFor: number | string | null;
/** Being made: for which generation, and how to stop it. */
- making: { generation: number | string; abort: AbortController } | null;
+ making: { generation: number | string; abort: AbortHandle } | null;
failedFor: number | string | null;
reason?: string;
}
@@ -250,7 +251,7 @@ export class ProceduralChunks {
}
const chunk = c;
const generation = layer.def.generation;
- const abort = new AbortController();
+ const abort = createAbort();
let made: unknown;
try {
made = layer.def.make(cx, cz, abort.signal);
diff --git a/sdk/src/runtime/runtimeAssets.ts b/sdk/src/runtime/runtimeAssets.ts
index 03086a874..47090f0b9 100644
--- a/sdk/src/runtime/runtimeAssets.ts
+++ b/sdk/src/runtime/runtimeAssets.ts
@@ -199,13 +199,19 @@ export function createTextureArrayFromPixels(
throw new Error(`createTextureArrayFromPixels: every layer must be ${width}x${height} RGBA8 (${layerBytes} bytes)`);
}
const rm = owner ?? requireResourceManager();
- if (!rm.createTextureArray || !module) {
- throw new Error('createTextureArrayFromPixels: needs the wasm ResourceManager and its heap');
- }
const format = samplesAsSrgb(params?.srgb) ? 2 : 1;
const filter = params ? textureFilterCode(params) : -1;
const wrap = WRAP_MODE_MAP[params?.wrapMode ?? 'clamp'] ?? 1;
const total = layerBytes * layers.length;
+ // Native path: no wasm heap, so the layers go over as one run of bytes and the host copies them.
+ if (rm.createTextureArrayFromBytes) {
+ const bytes = new Uint8Array(total);
+ layers.forEach((layer, i) => bytes.set(layer, i * layerBytes));
+ return rm.createTextureArrayFromBytes(width, height, layers.length, bytes, format, filter, wrap, content);
+ }
+ if (!rm.createTextureArray || !module) {
+ throw new Error('createTextureArrayFromPixels: needs the wasm ResourceManager and its heap');
+ }
return withMalloc(module, total, ptr => {
if (!ptr) return 0;
layers.forEach((layer, i) => module.HEAPU8.set(layer, ptr + i * layerBytes));
diff --git a/sdk/src/util/abort.ts b/sdk/src/util/abort.ts
new file mode 100644
index 000000000..db4fa2617
--- /dev/null
+++ b/sdk/src/util/abort.ts
@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file abort.ts
+ * @brief An abort handle that does not assume a browser.
+ *
+ * @details `AbortController` is a web platform API, not a JavaScript one, and QuickJS
+ * (the engine's native host) does not have it: a system that built one threw
+ * on every tick there. The platform's is used where it exists; elsewhere this
+ * one does the part a maker of chunks reads: `aborted`, `reason`, `onabort`
+ * and listeners, and `throwIfAborted`.
+ */
+
+export interface AbortHandle {
+ readonly signal: AbortSignal;
+ abort(reason?: unknown): void;
+}
+
+class FallbackSignal {
+ aborted = false;
+ reason: unknown = undefined;
+ onabort: ((event: { type: 'abort' }) => void) | null = null;
+ private listeners_: Array<(event: { type: 'abort' }) => void> = [];
+
+ addEventListener(type: string, listener: (event: { type: 'abort' }) => void): void {
+ if (type === 'abort') this.listeners_.push(listener);
+ }
+
+ removeEventListener(type: string, listener: (event: { type: 'abort' }) => void): void {
+ if (type !== 'abort') return;
+ const i = this.listeners_.indexOf(listener);
+ if (i >= 0) this.listeners_.splice(i, 1);
+ }
+
+ throwIfAborted(): void {
+ if (this.aborted) throw this.reason;
+ }
+
+ fire(reason: unknown): void {
+ if (this.aborted) return;
+ this.aborted = true;
+ this.reason = reason ?? Object.assign(new Error('This operation was aborted'), { name: 'AbortError' });
+ const event = { type: 'abort' as const };
+ this.onabort?.(event);
+ for (const listener of this.listeners_.slice()) listener(event);
+ }
+}
+
+export function createAbort(): AbortHandle {
+ if (typeof AbortController !== 'undefined') return new AbortController();
+ const signal = new FallbackSignal();
+ return { signal: signal as unknown as AbortSignal, abort: (reason) => signal.fire(reason) };
+}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 7beb7c658..7ca1b0023 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -91,6 +91,8 @@ export interface CppResourceManager {
* wasm heap to marshal into); the wasm embind object does not implement it, so
* the upload helpers fall through to the heap path and web stays byte-identical.
* `filterMode`/`wrapMode` mirror {@link createTextureEx}'s codes (optional). */
+ /** {@link createTextureArray} without a wasm heap: the layers back to back as bytes. Present only on the native ResourceManager. */
+ createTextureArrayFromBytes?(width: number, height: number, layers: number, pixels: Uint8Array, format: number, filterMode: number, wrapMode: number, content: TextureContent): number;
createTextureFromBytes?(width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, content: TextureContent, filterMode?: number, wrapMode?: number): number;
/** Transcode + upload a KTX2/Basis container to a device-supported compressed
* format (or RGBA32). Native only (the basis transcoder lives in the host);
diff --git a/sdk/tests/abort-handle.test.ts b/sdk/tests/abort-handle.test.ts
new file mode 100644
index 000000000..1000f966e
--- /dev/null
+++ b/sdk/tests/abort-handle.test.ts
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { it, expect, vi, afterEach } from 'vitest';
+import { createAbort } from '../src/util/abort';
+
+afterEach(() => { vi.unstubAllGlobals(); });
+
+it('uses the platform controller where there is one', () => {
+ const handle = createAbort();
+ expect(handle).toBeInstanceOf(AbortController);
+});
+
+it('has a handle of its own where the host (QuickJS) has no AbortController', () => {
+ vi.stubGlobal('AbortController', undefined);
+ const handle = createAbort();
+ const heard: string[] = [];
+ handle.signal.addEventListener('abort', () => heard.push('listener'));
+ handle.signal.onabort = () => heard.push('onabort');
+ expect(handle.signal.aborted).toBe(false);
+ expect(() => handle.signal.throwIfAborted()).not.toThrow();
+ handle.abort();
+ handle.abort();
+ expect(handle.signal.aborted).toBe(true);
+ expect(heard).toEqual(['onabort', 'listener']);
+ expect(() => handle.signal.throwIfAborted()).toThrow(/aborted/);
+});
diff --git a/sdk/tests/binding-surface.test.ts b/sdk/tests/binding-surface.test.ts
index 84bf11056..4a62f220e 100644
--- a/sdk/tests/binding-surface.test.ts
+++ b/sdk/tests/binding-surface.test.ts
@@ -529,6 +529,7 @@ describe('WASM binding surface: embind class methods', () => {
// web ResourceManager. Optional + native-only by construction — exempt from
// the web mirror the way embind's implicit `delete` is below.
ts.delete('createTextureFromBytes');
+ ts.delete('createTextureArrayFromBytes');
ts.delete('updateTextureSubregionFromBytes');
ts.delete('createTextureFromKTX2'); // KTX2 transcode lives in the native host, not embind
expect(sorted(ts)).toEqual(sorted(cpp.keys()));
diff --git a/sdk/tests/native-assets.test.ts b/sdk/tests/native-assets.test.ts
index 9377b346c..46f5ad316 100644
--- a/sdk/tests/native-assets.test.ts
+++ b/sdk/tests/native-assets.test.ts
@@ -104,6 +104,22 @@ describe('createNativeResourceManager', () => {
expect(rm.getTextureDimensions(handle)).toBeNull();
});
+ it('makes a texture array from its layers as bytes, without a wasm heap', async () => {
+ const calls: unknown[][] = [];
+ const rm = createNativeResourceManager({
+ es_rm_createTextureArray: (...args: unknown[]) => { calls.push(args); return 7; },
+ });
+ const { createTextureArrayFromPixels } = await import('../src/runtime/runtimeAssets');
+ const a = new Uint8Array(16).fill(1);
+ const b = new Uint8Array(16).fill(2);
+ // No module, no heap: the device has neither, and used to refuse the terrain's layer arrays for it.
+ const handle = createTextureArrayFromPixels(null, { width: 2, height: 2, layers: [a, b] }, TextureContent.Asset, undefined, rm);
+ expect(handle).toBe(7);
+ const [w, h, layers, bytes, len] = calls[0] as [number, number, number, Uint8Array, number];
+ expect([w, h, layers, len]).toEqual([2, 2, 2, 32]);
+ expect([...bytes]).toEqual([...a, ...b]);
+ });
+
it('fails loud on the wasm/GL-only surface (no heap or GL on native)', () => {
const rm = createNativeResourceManager({});
expect(() => rm.createTexture(1, 1, 0, 4, 1, true, TextureContent.Asset)).toThrow(/not supported/);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 9b6bc8735..d6d665ce7 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -3102,6 +3102,8 @@ export const NOTED = {
{"note":"The profiler's tables sort by their column header."},
"fix(editor): the profiler's sort header keeps to the theme's grid and icon sizes":
{"internal":"Spacing and icon size of the sort header added in the same release."},
+ "fix(native): a terrain and a streamed world run on a device with no wasm heap and no AbortController":
+ {"note":"A terrain and a streamed world run on the Android and iOS templates."},
"fix(ci): the ledger names its own repair":
{"internal":"Repairs the release-notes ledger; no creator can observe it."},
"feat(render): the medium quality level smooths edges temporally by default":