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(native): honor texture import settings + memory warning (Stage C)
esengineaca827d47b81
diff --git a/native/README.md b/native/README.mdindex 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 thebytes 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 theweb 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 abackground/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.jsindex 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.cppindex 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* aint32_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 eshostdiff --git a/native/host_js/host_core.hpp b/native/host_js/host_core.hppindex 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 isdiff --git a/native/host_js/main_android.cpp b/native/host_js/main_android.cppindex 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.mmindex 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)+}@endextern "C" int EstellaRunApp(int argc, char** argv) {diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 2df34fc07..d3bcea87f 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -3952,6 +3952,7 @@ language: (() => string) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>now: (() => number) | undefinedonHide: ((callback: () => void) => () => void) | undefined+onMemoryWarning: ((callback: () => void) => () => void) | undefinedonShow: ((callback: () => void) => () => void) | undefinedreadCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefinedreadFile: (path: string) => Promise<ArrayBuffer>@@ -4053,6 +4054,7 @@ name: "native"now: () => numberonAppHide: (callback: () => void) => () => voidonAppShow: (callback: () => void) => () => void+onMemoryWarning: (callback: () => void) => () => voidreadCacheFile: (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.tsindex 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 thediff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.tsindex 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.tsindex 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.tsindex 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 subscribeconst without = new NativePlatformAdapter(bridgeWith(undefined, false));expect(() => without.onAppHide(() => {})()).not.toThrow();+ expect(() => without.onMemoryWarning(() => {})()).not.toThrow();});});