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): honor texture import settings + memory warning (Stage C)

esengineaca827d47b81
diff --git a/native/README.md b/native/README.md
index 7094d37ca..c5b3ee561 100644
--- a/native/README.md
+++ b/native/README.md
@@ -220,7 +220,10 @@ System bindings landing incrementally through the real SDK surfaces:
**native ResourceManager** (`createNativeResourceManager`, over the host's
`es_createTexture` / `es_releaseTexture` / `es_getTextureDimensions`) uploads the
bytes directly — no wasm heap. `game.js` now loads its logo through this channel
- instead of a hand-rolled `es_createTexture`.
+ instead of a hand-rolled `es_createTexture`. Cooked-asset import settings (filter /
+ wrap, from a scene's `textureImporterSettings`) flow through the shared runtime
+ loader and `es_createTexture` honors them exactly as the web embind path does, so
+ pixel-art stays crisp on device.
- **Audio** (Stage C) — `ESEngine.Audio.playSFX` / `playTrack` runs the SAME Audio API the
web build uses. The engine is [miniaudio](https://miniaud.io) (CoreAudio on iOS,
AAudio/OpenSL on Android): it decodes and mixes natively, so nothing per-sample runs
@@ -232,9 +235,12 @@ System bindings landing incrementally through the real SDK surfaces:
plays (isPlaying true).
- **Lifecycle** (Stage C) — the glue pushes foreground/background (`eshost::setVisible`) →
the SDK's Lifecycle plugin auto-pauses the game, and the host suspends/resumes the audio
- device natively (correct even while the JS tick is paused). Simulator-verified across a
+ device natively (correct even while the JS tick is paused). Memory pressure
+ (`eshost::memoryWarning`, iOS `didReceiveMemoryWarning` / Android `APP_CMD_LOW_MEMORY`) →
+ the SDK's residency caches trim (the audio buffer cache). Simulator-verified across a
background/foreground cycle.
-Remaining: the cooked-asset import settings (sampler filter/wrap, KTX2/atlas nuances)
-the export pipeline will thread through, and hardening on a physical device (audio
-output, the background/foreground transition, Android's miniaudio AAudio path).
+Remaining: KTX2 / compressed textures (native decodes to RGBA only — no basis transcoder
+yet), networking (`bridge.fetch` is offline, so remote asset groups and hot-update do not
+resolve), and hardening on a physical device (audio output, the background/foreground
+transition, Android's miniaudio AAudio path).
diff --git a/native/host_js/game.js b/native/host_js/game.js
index 6b387a3d7..efef9e763 100644
--- a/native/host_js/game.js
+++ b/native/host_js/game.js
@@ -18,9 +18,12 @@ function init() {
var assets = app.getResource(ESEngine.Assets);
// Fallback 2x2 checker (a tiny inline texture) while the real image loads.
+ // Nearest filter + clamp (format 1, no flip, filter 0, wrap 1) so the scaled-up
+ // pixels stay crisp — the same import-settings path a cooked pixel-art texture
+ // takes, exercised on every boot.
var tex = es_createTexture(2, 2, [
255, 0, 0, 255, 0, 255, 0, 255,
- 0, 0, 255, 255, 255, 255, 0, 255 ]);
+ 0, 0, 255, 255, 255, 255, 0, 255 ], 1, false, 0, 1);
follower = world.spawn();
world.insert(follower, ESEngine.Transform, { position: { x: W * 0.5, y: H * 0.5, z: 0 } });
diff --git a/native/host_js/host_core.cpp b/native/host_js/host_core.cpp
index b11bfab8b..5032764c7 100644
--- a/native/host_js/host_core.cpp
+++ b/native/host_js/host_core.cpp
@@ -34,6 +34,7 @@
#include "esengine/ecs/components/Hierarchy.hpp" // Parent / Children
#include "esengine/renderer/RenderContext.hpp"
#include "esengine/renderer/RenderFrame.hpp"
+#include "esengine/renderer/Texture.hpp" // TextureSpecification + filter/wrap for import settings
#include "esengine/resource/ResourceManager.hpp"
#include "esengine/resource/ShaderParser.hpp" // linearColorSpace() — texture format at the JS boundary
@@ -276,9 +277,14 @@ TextureFormat boundaryTextureFormat(int32_t format) {
// es_createTexture(w, h, pixels, format?, flip?, filter?, wrap?) -> handle id.
// Backs the native ResourceManager's createTextureFromBytes: the SDK decodes an
-// image to RGBA (loadImagePixels) and hands the bytes here — no wasm heap. filter/
-// wrap arrive with the cooked-asset import settings (Stage C); until then only the
-// default sampler is used, matching the plain rm_createTexture path.
+// image to RGBA (loadImagePixels) and hands the bytes here — no wasm heap.
+//
+// filter/wrap carry the cooked-asset import settings (a scene's
+// textureImporterSettings, threaded through the shared runtime loader). Each is a
+// number or undefined; honor them exactly as the web embind rm_createTextureEx
+// does (filter 0=Nearest/else Linear; wrap 0=Repeat/1=ClampToEdge/2=MirroredRepeat)
+// so native sampling matches web — pixel art stays crisp. With neither, the plain
+// createTexture path is unchanged.
JSValue js_createTexture(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {
int32_t w = 0, h = 0;
JS_ToInt32(ctx, &w, argv[0]);
@@ -288,11 +294,43 @@ JSValue js_createTexture(JSContext* ctx, JSValueConst, int argc, JSValueConst* a
int32_t format = 1; // default: colour (RGBA8 / sRGB)
if (argc > 3 && !JS_IsUndefined(argv[3])) JS_ToInt32(ctx, &format, argv[3]);
- bool flip = (argc > 4 && !JS_IsUndefined(argv[4])) ? JS_ToBool(ctx, argv[4]) != 0 : false;
+ const bool flip = (argc > 4 && !JS_IsUndefined(argv[4])) ? JS_ToBool(ctx, argv[4]) != 0 : false;
+ const TextureFormat fmt = boundaryTextureFormat(format);
+ auto& rm = g_app->ctx->require<resource::ResourceManager>();
+
+ const bool hasFilter = argc > 5 && !JS_IsUndefined(argv[5]);
+ const bool hasWrap = argc > 6 && !JS_IsUndefined(argv[6]);
+ if (!hasFilter && !hasWrap) {
+ auto handle = rm.createTexture(
+ (u32)w, (u32)h, ConstSpan<u8>(pixels.data(), pixels.size()), fmt, flip);
+ return JS_NewInt64(ctx, (int64_t)handle.id());
+ }
- auto handle = g_app->ctx->require<resource::ResourceManager>().createTexture(
- (u32)w, (u32)h, ConstSpan<u8>(pixels.data(), pixels.size()),
- boundaryTextureFormat(format), flip);
+ TextureSpecification spec;
+ spec.width = (u32)w;
+ spec.height = (u32)h;
+ spec.format = fmt;
+ spec.generateMips = false; // decoded 2D sprites, like the web Ex path
+ if (hasFilter) {
+ int32_t f = 1;
+ JS_ToInt32(ctx, &f, argv[5]);
+ spec.minFilter = (f == 0) ? TextureFilter::Nearest : TextureFilter::Linear;
+ spec.magFilter = spec.minFilter;
+ }
+ if (hasWrap) {
+ int32_t wm = 1;
+ JS_ToInt32(ctx, &wm, argv[6]);
+ const TextureWrap tw = (wm == 0) ? TextureWrap::Repeat
+ : (wm == 2) ? TextureWrap::MirroredRepeat
+ : TextureWrap::ClampToEdge;
+ spec.wrapS = tw;
+ spec.wrapT = tw;
+ }
+ auto handle = rm.createTexture(spec);
+ if (auto* tex = rm.getTexture(handle); tex && !pixels.empty()) {
+ const u64 required = (u64)w * (u64)h * (fmt == TextureFormat::RGB8 ? 3 : 4);
+ if (pixels.size() >= required) tex->setDataRaw(pixels.data(), (u32)required, flip);
+ }
return JS_NewInt64(ctx, (int64_t)handle.id());
}
@@ -945,4 +983,13 @@ void setVisible(bool visible) {
pumpJs(a);
}
+// OS memory pressure — let the SDK's residency caches drop evictable entries
+// (the audio buffer cache trims). Held buffers keep playing; only re-fetch cost
+// returns for evicted ones.
+void memoryWarning() {
+ if (!g_app || !g_app->ready) return;
+ callJs(*g_app, "es_onNativeMemoryWarning", 0, nullptr);
+ pumpJs(*g_app);
+}
+
} // namespace eshost
diff --git a/native/host_js/host_core.hpp b/native/host_js/host_core.hpp
index 1374c405b..9ef3e28dd 100644
--- a/native/host_js/host_core.hpp
+++ b/native/host_js/host_core.hpp
@@ -83,6 +83,10 @@ void touch(int type, int id, float x, float y);
* where the Lifecycle plugin auto-pauses the game. No-op before boot. */
void setVisible(bool visible);
+/** @brief The OS reported memory pressure; asks the SDK's residency caches to
+ * drop evictable entries (the audio buffer cache). No-op before boot. */
+void memoryWarning();
+
bool booted();
/** Whether a surface is currently bound — false while the window is gone, which is
diff --git a/native/host_js/main_android.cpp b/native/host_js/main_android.cpp
index 9c7e54193..85050fdd2 100644
--- a/native/host_js/main_android.cpp
+++ b/native/host_js/main_android.cpp
@@ -109,6 +109,9 @@ void onAppCmd(android_app* app, int32_t cmd) {
case APP_CMD_RESUME:
eshost::setVisible(true);
break;
+ case APP_CMD_LOW_MEMORY:
+ eshost::memoryWarning(); // SDK residency caches trim
+ break;
default:
break;
}
diff --git a/native/host_js/main_ios.mm b/native/host_js/main_ios.mm
index 78e8beba6..6091c182c 100644
--- a/native/host_js/main_ios.mm
+++ b/native/host_js/main_ios.mm
@@ -190,6 +190,10 @@ IOSPlatform g_platform;
[self.window makeKeyAndVisible];
return YES;
}
+
+- (void)applicationDidReceiveMemoryWarning:(UIApplication*)application {
+ eshost::memoryWarning(); // SDK residency caches trim (the audio buffer cache)
+}
@end
extern "C" int EstellaRunApp(int argc, char** argv) {
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 2df34fc07..d3bcea87f 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -3952,6 +3952,7 @@ language: (() => string) | undefined
loadImagePixels: (path: string) => Promise<ImageLoadResult>
now: (() => number) | undefined
onHide: ((callback: () => void) => () => void) | undefined
+onMemoryWarning: ((callback: () => void) => () => void) | undefined
onShow: ((callback: () => void) => () => void) | undefined
readCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefined
readFile: (path: string) => Promise<ArrayBuffer>
@@ -4053,6 +4054,7 @@ name: "native"
now: () => number
onAppHide: (callback: () => void) => () => void
onAppShow: (callback: () => void) => () => void
+onMemoryWarning: (callback: () => void) => () => void
readCacheFile: (key: string) => Promise<ArrayBuffer | null>
readFile: (path: string) => Promise<ArrayBuffer>
readTextFile: (path: string) => Promise<string>
diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.ts
index ab8cce80f..bfa9ff380 100644
--- a/sdk/src/platform/native/adapter.ts
+++ b/sdk/src/platform/native/adapter.ts
@@ -146,6 +146,12 @@ export class NativePlatformAdapter implements PlatformAdapter {
return this.bridge_.onHide?.(callback) ?? (() => {});
}
+ // OS memory pressure → residency caches (the audio buffer cache) trim. A bridge
+ // without the signal never fires.
+ onMemoryWarning(callback: () => void): () => void {
+ return this.bridge_.onMemoryWarning?.(callback) ?? (() => {});
+ }
+
getStorageItem(key: string): string | null {
return this.bridge_.getStorageItem(key);
}
@@ -175,8 +181,8 @@ export class NativePlatformAdapter implements PlatformAdapter {
if (this.bridge_.writeCacheFile) await this.bridge_.writeCacheFile(key, bytes);
}
- // createSocket / createVideoBackend / pollGamepads / loadSubpackage /
- // onMemoryWarning are optional and deferred to the shell.
+ // createSocket / createVideoBackend / pollGamepads / loadSubpackage are
+ // optional and deferred to the shell.
}
/** Install a {@link NativePlatformAdapter} built from the host `bridge` as the
diff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.ts
index 9c5973286..7cca91226 100644
--- a/sdk/src/platform/native/bridge.ts
+++ b/sdk/src/platform/native/bridge.ts
@@ -139,4 +139,10 @@ export interface NativeBridge {
* stays always-visible. */
onShow?(callback: () => void): () => void;
onHide?(callback: () => void): () => void;
+
+ /** OS memory-pressure warning (iOS didReceiveMemoryWarning / Android
+ * onLowMemory), pushed by the shell. Residency caches (the audio buffer cache)
+ * subscribe via the adapter's `onMemoryWarning` to drop evictable entries.
+ * Returns an unsubscribe. Optional. */
+ onMemoryWarning?(callback: () => void): () => void;
}
diff --git a/sdk/src/platform/native/hostBridge.ts b/sdk/src/platform/native/hostBridge.ts
index bc0f39081..60c0a9485 100644
--- a/sdk/src/platform/native/hostBridge.ts
+++ b/sdk/src/platform/native/hostBridge.ts
@@ -90,7 +90,7 @@ export function createHostBridge(
const storage = hostStorage(bindings);
const audio = hostAudio(bindings, scope);
- const lifecycle = hostVisibility(scope);
+ const lifecycle = hostLifecycle(scope);
return {
readFile: (path) => {
@@ -162,21 +162,32 @@ function hostAudio(
}
/**
- * Foreground/background: install `es_onNativeVisibility(visible)`, the entry the
- * host calls when the app backgrounds or returns (like touch), and expose it as
- * the bridge's onShow/onHide. The Lifecycle plugin subscribes and auto-pauses.
+ * 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
+ * the bridge: foreground/background (`es_onNativeVisibility` → onShow/onHide, the
+ * Lifecycle plugin auto-pauses) and memory pressure (`es_onNativeMemoryWarning` →
+ * onMemoryWarning, residency caches trim).
*/
-function hostVisibility(
+function hostLifecycle(
scope: Record<string, unknown>,
-): Pick<NativeBridge, 'onShow' | 'onHide'> {
- let show: (() => void)[] = [];
- let hide: (() => void)[] = [];
- scope.es_onNativeVisibility = (visible: boolean): void => {
- for (const cb of visible ? show : hide) cb();
+): Pick<NativeBridge, 'onShow' | 'onHide' | 'onMemoryWarning'> {
+ /** A subscriber list installed behind a host push entry; returns its API. */
+ const signal = (install: (fire: () => void) => void): ((cb: () => void) => () => void) => {
+ let subs: (() => void)[] = [];
+ install(() => { for (const cb of subs) cb(); });
+ return (cb) => { subs.push(cb); return () => { subs = subs.filter((c) => c !== cb); }; };
};
+
+ let onShow: (() => void) | undefined;
+ let onHide: (() => void) | undefined;
+ const subShow = signal((fire) => { onShow = fire; });
+ const subHide = signal((fire) => { onHide = fire; });
+ scope.es_onNativeVisibility = (visible: boolean): void => { (visible ? onShow : onHide)?.(); };
+
return {
- onShow: (cb) => { show.push(cb); return () => { show = show.filter((c) => c !== cb); }; },
- onHide: (cb) => { hide.push(cb); return () => { hide = hide.filter((c) => c !== cb); }; },
+ onShow: subShow,
+ onHide: subHide,
+ onMemoryWarning: signal((fire) => { scope.es_onNativeMemoryWarning = fire; }),
};
}
diff --git a/sdk/tests/native-audio.test.ts b/sdk/tests/native-audio.test.ts
index ddb44a917..55dbfe599 100644
--- a/sdk/tests/native-audio.test.ts
+++ b/sdk/tests/native-audio.test.ts
@@ -171,6 +171,20 @@ describe('createHostBridge — visibility (lifecycle)', () => {
push(true);
expect(show).toHaveBeenCalledTimes(1); // detached
});
+
+ it('routes the host memory-warning push to subscribers, and detaches', () => {
+ const scope = audioScope();
+ const bridge = createHostBridge(scope);
+ const warn = vi.fn();
+ const off = bridge.onMemoryWarning!(warn);
+
+ const push = scope.es_onNativeMemoryWarning as () => void;
+ push();
+ expect(warn).toHaveBeenCalledTimes(1);
+ off();
+ push();
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
});
describe('NativePlatformAdapter — Stage C surfaces', () => {
@@ -192,6 +206,7 @@ describe('NativePlatformAdapter — Stage C surfaces', () => {
...(visibility ? {
onShow: (cb: () => void) => { shows.push(cb); return () => {}; },
onHide: (cb: () => void) => { hides.push(cb); return () => {}; },
+ onMemoryWarning: (cb: () => void) => { cb(); return () => {}; },
} : {}),
};
}
@@ -203,12 +218,16 @@ describe('NativePlatformAdapter — Stage C surfaces', () => {
expect(new NativePlatformAdapter(bridgeWith(undefined, true)).createAudioBackend).toBeUndefined();
});
- it('delegates onAppShow / onAppHide to the bridge, tolerating a bridge without them', () => {
+ it('delegates onAppShow / onAppHide / onMemoryWarning to the bridge, tolerating a bridge without them', () => {
const withVisibility = new NativePlatformAdapter(bridgeWith(undefined, true));
expect(typeof withVisibility.onAppShow(() => {})).toBe('function');
+ const warn = vi.fn();
+ withVisibility.onMemoryWarning(warn);
+ expect(warn).toHaveBeenCalledTimes(1); // the fake bridge fires on subscribe
const without = new NativePlatformAdapter(bridgeWith(undefined, false));
expect(() => without.onAppHide(() => {})()).not.toThrow();
+ expect(() => without.onMemoryWarning(() => {})()).not.toThrow();
});
});