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): audio + app lifecycle over the real SDK (Stage C)
esenginec7000dbc1cd2
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txtindex f4e996742..db7645945 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -125,9 +125,17 @@ if(ESTELLA_QUICKJS_DIR)if(ESTELLA_IOS)# Static: the thin Xcode app (native/ios) links this plus the libraries# below. -ObjC on the app keeps the Obj-C classes in main_ios.mm alive.- add_library(estella_js_host STATIC host_js/host_core.cpp host_js/main_ios.mm "${NATIVE_BINDINGS}")+ add_library(estella_js_host STATIC host_js/host_core.cpp host_js/main_ios.mm+ host_js/native_audio.cpp "${NATIVE_BINDINGS}")+ # miniaudio's CoreAudio backend uses AVAudioSession (Obj-C), so its TU must+ # be Objective-C++ on Apple; it also forces MA_NO_RUNTIME_LINKING there, so+ # the audio frameworks are linked at build time (the app links the merged+ # archive, so these also live in native/ios/project.yml).+ set_source_files_properties(host_js/native_audio.cpp PROPERTIES+ COMPILE_OPTIONS "-x;objective-c++")target_link_libraries(estella_js_host esengine qjs- "-framework UIKit" "-framework QuartzCore" "-framework Foundation")+ "-framework UIKit" "-framework QuartzCore" "-framework Foundation"+ "-framework AVFoundation" "-framework CoreAudio" "-framework AudioToolbox")# Merge host + engine + deps + Dawn into ONE archive, so the Xcode app is a# thin shell that links a single library at a fixed path (native/ios).add_custom_command(TARGET estella_js_host POST_BUILD@@ -136,12 +144,16 @@ if(ESTELLA_QUICKJS_DIR)$<TARGET_FILE:qjs> $<TARGET_FILE:yogacore> "${ESTELLA_DAWN_LIB}"COMMENT "Merging the iOS host, engine and Dawn into libestella_ios.a")else()- add_library(estella_js_host SHARED host_js/host_core.cpp host_js/main_android.cpp "${NATIVE_BINDINGS}")+ # Android: plain C++; miniaudio dlopens AAudio/OpenSL at runtime (no extra+ # link libs). native_audio.cpp's Obj-C paths are __APPLE__-guarded out.+ add_library(estella_js_host SHARED host_js/host_core.cpp host_js/main_android.cpp+ host_js/native_audio.cpp "${NATIVE_BINDINGS}")target_link_libraries(estella_js_host esengine qjs native_app_glue android log)set_target_properties(estella_js_host PROPERTIES LINK_FLAGS "-u ANativeActivity_onCreate")endif()# host_js/ holds esn_shim.hpp + host_core.hpp (the generated TU includes the shim);- # the gen dir holds ptraccessors_js.h and the embedded SDK bundle.+ # the gen dir holds ptraccessors_js.h and the embedded SDK bundle; third_party/miniaudio+ # is the audio engine header.target_include_directories(estella_js_host PRIVATE- "${CMAKE_CURRENT_SOURCE_DIR}/host_js" "${ESTELLA_NATIVE_GEN_DIR}")+ "${CMAKE_CURRENT_SOURCE_DIR}/host_js" "${ESTELLA_NATIVE_GEN_DIR}" "${TP}/miniaudio")endif()diff --git a/native/README.md b/native/README.mdindex b406ee89b..7094d37ca 100644--- a/native/README.md+++ b/native/README.md@@ -212,16 +212,29 @@ through the generated registry + memory backend; the host binds the entity /hierarchy / component functions the SDK reads off `globalThis`, plus the input andtexture bindings.-System bindings (Stage B) landing incrementally through the real SDK surfaces:+System bindings landing incrementally through the real SDK surfaces:-- **Input** — host touch → the SDK's `inputPlugin` → the `Input` resource (device-verified).-- **Assets** — `ESEngine.Assets.loadTexture(path)` runs the SAME asset pipeline the+- **Input** (Stage B) — host touch → the SDK's `inputPlugin` → the `Input` resource (device-verified).+- **Assets** (Stage B) — `ESEngine.Assets.loadTexture(path)` runs the SAME asset pipeline theweb build uses: the platform decodes the image (`bridge.loadImagePixels`) and the**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 channelinstead of a hand-rolled `es_createTexture`.--Remaining: audio, lifecycle, and the cooked-asset manifest (import settings / KTX2 /-atlases) that the editor's native-export pipeline will ship (Stage C); then the iOS-shell (the Metal surface seam is already in place).+- **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+ in JS — the no-JIT budget forbids that. `NativeAudioBackend` is a thin SDK shell over the+ host's `es_audio*` engine (`native_audio.cpp`), mirroring the WeChat backend over+ InnerAudioContext; `mixer` is null (per-voice volume/pan/rate/loop, no JS DSP graph).+ The engine is playback-only (no microphone). Bound only when a device comes up, so a+ host without one stays silent (the Null backend). Simulator-verified: a clip decodes and+ 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+ 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).diff --git a/native/host_js/beep.wav b/native/host_js/beep.wavnew file mode 100644index 000000000..27b4238a8Binary files /dev/null and b/native/host_js/beep.wav differdiff --git a/native/host_js/game.js b/native/host_js/game.jsindex e0a5e9784..6b387a3d7 100644--- a/native/host_js/game.js+++ b/native/host_js/game.js@@ -44,6 +44,22 @@ function init() {world.insert(orbit, ESEngine.Transform, { position: { x: W * 0.5, y: H * 0.75, z: 0 } });world.insert(orbit, ESEngine.ShapeRenderer, {shapeType: 0, color: { r: 1, g: 0.2, b: 0.9, a: 1 }, size: { x: S * 0.12, y: S * 0.12 } });++ // Stage C: a startup chime through the REAL SDK Audio API. The native audio+ // backend decodes beep.wav and plays it in the host's miniaudio engine — the+ // audio pillar on device, the same Audio API a web game calls.+ var audio = ESEngine.Audio && app.getResource(ESEngine.Audio);+ if (audio) {+ audio.playTrack('beep.wav', { volume: 0.4 }).then(function (h) {+ console.log('[demo] audio: ' + (h+ ? 'playing (isPlaying=' + h.isPlaying + ', duration=' + h.duration.toFixed(2) + 's)'+ : 'null handle — no native audio backend'));+ }, function (e) {+ console.error('[demo] audio failed:', e && e.message ? e.message : e);+ });+ } else {+ console.log('[demo] audio: no Audio resource');+ }}function update(dt) {diff --git a/native/host_js/host_core.cpp b/native/host_js/host_core.cppindex 78d940236..b11bfab8b 100644--- a/native/host_js/host_core.cpp+++ b/native/host_js/host_core.cpp@@ -26,6 +26,7 @@#include "esn_shim.hpp" // quickjs + the esn_* plumbing decls (+ esn_register)#include "esengine_bundle.h" // the real SDK, bundled: installs globalThis.ESEngine+#include "native_audio.hpp" // the miniaudio-backed engine behind es_audio*#include "esengine/core/EstellaContext.hpp"#include "esengine/core/World.hpp"@@ -110,6 +111,7 @@ struct App {ecs::Registry* registry = nullptr;JSRuntime* rt = nullptr;JSContext* js = nullptr;+ eshost::AudioEngine audio; // native sound (miniaudio); silent if no devicestd::string cacheDir; // app private dir — SDK bytecode cachestd::vector<Timer> timers;int64_t next_timer_id = 1;@@ -224,10 +226,18 @@ JSValue js_setClear(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {g_app->clear = {(f32)r, (f32)g, (f32)b, 1.0f};return JS_UNDEFINED;}-// Read an RGBA byte source into `out`. Fast path: a Uint8Array (what the SDK's-// createTextureFromBytes hands us) — copy straight from its ArrayBuffer. Fallback:-// a plain JS number array (the tiny inline checker some scripts build) — index it.+// Read a byte source into `out`, whatever shape the SDK handed us: a raw+// ArrayBuffer (audio clip bytes, cache writes), a Uint8Array (texture pixels), or+// a plain JS number array (the tiny inline checker some scripts build).void readByteSource(JSContext* ctx, JSValueConst v, std::vector<u8>& out) {+ // Raw ArrayBuffer first — a typed-array view is not one, so it falls through.+ size_t rawSize = 0;+ if (uint8_t* raw = JS_GetArrayBuffer(ctx, &rawSize, v)) {+ out.assign(raw, raw + rawSize);+ return;+ }+ JS_FreeValue(ctx, JS_GetException(ctx)); // not a raw ArrayBuffer — try a view+size_t byteOffset = 0, byteLen = 0, bytesPerEl = 0;JSValue ab = JS_GetTypedArrayBuffer(ctx, v, &byteOffset, &byteLen, &bytesPerEl);if (!JS_IsException(ab)) {@@ -343,6 +353,87 @@ JSValue js_loadImagePixels(JSContext* ctx, JSValueConst, int, JSValueConst* argvreturn obj;}+// ---- audio: es_audio* over the native AudioEngine (miniaudio) ----------------+// Bound only when the engine has a device (see initJS); a host without one binds+// none, so the SDK's hasAudioBindings() is false and audio stays the Null backend.++// es_audioLoad(ArrayBuffer | TypedArray) -> { id, duration, bytes } | null. The+// SDK hands the compressed clip bytes; the engine decodes + registers them.+JSValue js_audioLoad(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 1) return JS_NULL;+ std::vector<u8> bytes;+ readByteSource(ctx, argv[0], bytes);+ if (bytes.empty()) return JS_NULL;+ auto r = g_app->audio.load(bytes.data(), bytes.size());+ if (r.id < 0) return JS_NULL;+ JSValue o = JS_NewObject(ctx);+ JS_SetPropertyStr(ctx, o, "id", JS_NewInt32(ctx, r.id));+ JS_SetPropertyStr(ctx, o, "duration", JS_NewFloat64(ctx, r.duration));+ JS_SetPropertyStr(ctx, o, "bytes", JS_NewInt64(ctx, r.bytes));+ return o;+}+JSValue js_audioUnload(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ int32_t id = 0; JS_ToInt32(ctx, &id, argv[0]);+ g_app->audio.unload(id);+ return JS_UNDEFINED;+}++// es_audioPlay(bufferId, volume, pan, loop, rate) -> voiceId (-1 if unknown).+JSValue js_audioPlay(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ int32_t buf = 0; JS_ToInt32(ctx, &buf, argv[0]);+ double vol = 1, pan = 0, rate = 1;+ if (argc > 1) JS_ToFloat64(ctx, &vol, argv[1]);+ if (argc > 2) JS_ToFloat64(ctx, &pan, argv[2]);+ const bool loop = argc > 3 && JS_ToBool(ctx, argv[3]);+ if (argc > 4) JS_ToFloat64(ctx, &rate, argv[4]);+ return JS_NewInt32(ctx, g_app->audio.play(buf, (f32)vol, (f32)pan, loop, (f32)rate));+}++// The voice-scoped commands all take the voice id as argv[0].+int32_t voiceArg(JSContext* ctx, JSValueConst* argv) {+ int32_t v = 0; JS_ToInt32(ctx, &v, argv[0]); return v;+}+JSValue js_audioStop(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ g_app->audio.stop(voiceArg(ctx, argv)); return JS_UNDEFINED;+}+JSValue js_audioPause(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ g_app->audio.pause(voiceArg(ctx, argv)); return JS_UNDEFINED;+}+JSValue js_audioResume(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ g_app->audio.resume(voiceArg(ctx, argv)); return JS_UNDEFINED;+}+JSValue js_audioSetVolume(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ double v = 1; JS_ToFloat64(ctx, &v, argv[1]);+ g_app->audio.setVolume(voiceArg(ctx, argv), (f32)v); return JS_UNDEFINED;+}+JSValue js_audioSetPan(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ double p = 0; JS_ToFloat64(ctx, &p, argv[1]);+ g_app->audio.setPan(voiceArg(ctx, argv), (f32)p); return JS_UNDEFINED;+}+JSValue js_audioSetLoop(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ g_app->audio.setLoop(voiceArg(ctx, argv), JS_ToBool(ctx, argv[1]) != 0); return JS_UNDEFINED;+}+JSValue js_audioSetRate(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ double r = 1; JS_ToFloat64(ctx, &r, argv[1]);+ g_app->audio.setRate(voiceArg(ctx, argv), (f32)r); return JS_UNDEFINED;+}++// es_audioVoiceState(voiceId) -> { playing, currentTime } | null (null once ended).+JSValue js_audioVoiceState(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ auto st = g_app->audio.voiceState(voiceArg(ctx, argv));+ if (!st.valid) return JS_NULL;+ JSValue o = JS_NewObject(ctx);+ JS_SetPropertyStr(ctx, o, "playing", JS_NewBool(ctx, st.playing));+ JS_SetPropertyStr(ctx, o, "currentTime", JS_NewFloat64(ctx, st.currentTime));+ return o;+}+JSValue js_audioSuspendAll(JSContext* ctx, JSValueConst, int, JSValueConst*) {+ g_app->audio.suspendAll(); return JS_UNDEFINED;+}+JSValue js_audioResumeAll(JSContext* ctx, JSValueConst, int, JSValueConst*) {+ g_app->audio.resumeAll(); return JS_UNDEFINED;+}+// console.* — QuickJS ships no console at all, so without this a game script's// first console.log is a ReferenceError and every rejected promise is silent.JSValue jsConsoleWrite(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv, bool error) {@@ -654,6 +745,24 @@ void initJS(App& a) {bindGlobal(a, global, "es_getTextureDimensions", js_getTextureDimensions, 1);bindGlobal(a, global, "es_readAsset", js_readAsset, 1);bindGlobal(a, global, "es_loadImagePixels", js_loadImagePixels, 1);+ // Audio (es_audio*): bound only when a device came up, so the SDK's+ // hasAudioBindings() gates the native audio backend on real availability —+ // a host with no sound device binds none and falls back to the Null backend.+ if (a.audio.ready()) {+ bindGlobal(a, global, "es_audioLoad", js_audioLoad, 1);+ bindGlobal(a, global, "es_audioUnload", js_audioUnload, 1);+ bindGlobal(a, global, "es_audioPlay", js_audioPlay, 5);+ bindGlobal(a, global, "es_audioStop", js_audioStop, 1);+ bindGlobal(a, global, "es_audioPause", js_audioPause, 1);+ bindGlobal(a, global, "es_audioResume", js_audioResume, 1);+ bindGlobal(a, global, "es_audioSetVolume", js_audioSetVolume, 2);+ bindGlobal(a, global, "es_audioSetPan", js_audioSetPan, 2);+ bindGlobal(a, global, "es_audioSetLoop", js_audioSetLoop, 2);+ bindGlobal(a, global, "es_audioSetRate", js_audioSetRate, 2);+ bindGlobal(a, global, "es_audioVoiceState", js_audioVoiceState, 1);+ bindGlobal(a, global, "es_audioSuspendAll", js_audioSuspendAll, 0);+ bindGlobal(a, global, "es_audioResumeAll", js_audioResumeAll, 0);+ }// Per-component bindings (EHT-generated): es_set_<C> / es_<C>_buffer / _has / _remove.esn_register(a.js, global);JS_FreeValue(a.js, global);@@ -764,6 +873,7 @@ bool boot(Platform& platform) {static ecs::Registry registry;a.registry = ®istry;LOGI("boot ms — Dawn instance/adapter/device + EstellaContext: %.0f", nowMs() - te0);+ LOGI("audio: %s", a.audio.init() ? "native engine up (miniaudio)" : "no device — silent");initJS(a);a.ready = true;LOGI("real SDK up (%dx%d) — esengine World over native Dawn", (int)a.w, (int)a.h);@@ -779,6 +889,15 @@ void frame() {JS_FreeValue(a.js, dt);pumpJs(a); // run the App tick's async systems and any timers they set+ // Notify JS of voices that ended on their own (the audio thread never touches+ // QuickJS; we poll on this thread and push, like touch). onEnd handlers may+ // start new sounds synchronously — safe, pumpEnded iterates a snapshot.+ a.audio.pumpEnded([&a](int voiceId) {+ JSValue arg = JS_NewInt32(a.js, voiceId);+ callJs(a, "es_onNativeAudioEnded", 1, &arg);+ JS_FreeValue(a.js, arg);+ });+ctx.require<RenderContext>().setFrameTime((f32)a.frame / 60.0f, (u32)a.w, (u32)a.h);World world{*a.registry, ctx.services(), 1.0f / 60.0f};ctx.require<ecs::TransformSystem>().update(world);@@ -813,4 +932,17 @@ void touch(int type, int id, float x, float y) {JS_FreeValue(a.js, global);}+// The app went to background (visible=false) or returned. Suspend/resume the+// audio device at the native layer — correct even while the JS tick is paused —+// then push the signal to JS, where the Lifecycle plugin auto-pauses the game.+void setVisible(bool visible) {+ if (!g_app || !g_app->ready) return;+ App& a = *g_app;+ if (visible) a.audio.resumeAll(); else a.audio.suspendAll();+ JSValue arg = JS_NewBool(a.js, visible);+ callJs(a, "es_onNativeVisibility", 1, &arg);+ JS_FreeValue(a.js, arg);+ pumpJs(a);+}+} // namespace eshostdiff --git a/native/host_js/host_core.hpp b/native/host_js/host_core.hppindex 2f0561c34..1374c405b 100644--- a/native/host_js/host_core.hpp+++ b/native/host_js/host_core.hpp@@ -78,6 +78,11 @@ void frame();* Coordinates are in surface pixels, top-left origin (as on the web). */void touch(int type, int id, float x, float y);+/** @brief The app went to background (@p visible false) or returned to foreground.+ * Suspends/resumes the audio device natively and pushes the signal to JS,+ * where the Lifecycle plugin auto-pauses the game. No-op before boot. */+void setVisible(bool visible);+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 ad75e5099..9c7e54193 100644--- a/native/host_js/main_android.cpp+++ b/native/host_js/main_android.cpp@@ -103,6 +103,12 @@ void onAppCmd(android_app* app, int32_t cmd) {eshost::surfaceLost();g_platform.window = nullptr;break;+ case APP_CMD_PAUSE:+ eshost::setVisible(false); // suspend audio + auto-pause the game+ break;+ case APP_CMD_RESUME:+ eshost::setVisible(true);+ break;default:break;}diff --git a/native/host_js/main_ios.mm b/native/host_js/main_ios.mmindex 1f16f1a35..78e8beba6 100644--- a/native/host_js/main_ios.mm+++ b/native/host_js/main_ios.mm@@ -143,9 +143,11 @@ IOSPlatform g_platform;- (void)appBackgrounded {_displayLink.paused = YES;eshost::surfaceLost();+ eshost::setVisible(false); // suspend audio + auto-pause the game}- (void)appForegrounded {+ eshost::setVisible(true); // resume audio even if the surface rebind lagsif (_booted && eshost::bindSurface()) _displayLink.paused = NO;}diff --git a/native/host_js/native_audio.cpp b/native/host_js/native_audio.cppnew file mode 100644index 000000000..28a25c3f2--- /dev/null+++ b/native/host_js/native_audio.cpp@@ -0,0 +1,264 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file native_audio.cpp+ * @brief AudioEngine (see native_audio.hpp), backed by miniaudio.+ * @details This TU owns the miniaudio implementation (like host_core.cpp owns+ * stb_image). On iOS it is compiled as Objective-C++ (the CMake build+ * adds `-x objective-c++`) because miniaudio's CoreAudio backend touches+ * AVAudioSession; on Android it is plain C++ and miniaudio dlopens+ * AAudio/OpenSL at runtime. The Obj-C paths are __APPLE__-guarded inside+ * miniaudio, so the same source compiles on both.+ */+#define MINIAUDIO_IMPLEMENTATION+#define MA_NO_ENCODING // playback only; no encoders needed+#include "miniaudio.h"++#include "native_audio.hpp"++#include <string>+#include <unordered_map>+#include <vector>++namespace eshost {++// A decoded clip. register_decoded_data() does NOT copy the PCM, so `pcm` must+// outlive every voice playing it — freed only once unloaded AND no voice remains+// (`refs` == 0), or a still-playing sound would read freed memory.+struct Buffer {+ std::string name; // "buf://<id>", the resource-manager key+ void* pcm = nullptr; // owned; f32 interleaved at the engine's rate/channels+ int refs = 0; // live voices playing this buffer+ bool unloaded = false; // SDK dropped it; free when the last voice releases+};++// One playing instance. ma_sound is a node in the engine graph and must not move,+// so voices live in a node-stable unordered_map (never reallocated on rehash).+struct Voice {+ ma_sound sound{};+ int bufferId = -1;+ bool loop = false;+};++struct AudioEngine::Impl {+ ma_context context{};+ ma_engine engine{};+ bool contextReady = false;+ bool ready = false;+ ma_uint32 sampleRate = 0;+ ma_uint32 channels = 0;+ std::unordered_map<int, Buffer> buffers;+ std::unordered_map<int, Voice> voices;+ int nextBuffer = 1;+ int nextVoice = 1;++ ma_sound* soundOf(int voiceId) {+ auto it = voices.find(voiceId);+ return it == voices.end() ? nullptr : &it->second.sound;+ }++ // Drop one reference to a buffer; free its PCM once it is both unloaded and+ // unreferenced. The resource-manager registration is released at unload().+ void releaseBuffer(int bufferId) {+ auto it = buffers.find(bufferId);+ if (it == buffers.end()) return;+ if (--it->second.refs <= 0 && it->second.unloaded) {+ ma_free(it->second.pcm, nullptr);+ buffers.erase(it);+ }+ }++ void destroyVoice(int voiceId) {+ auto it = voices.find(voiceId);+ if (it == voices.end()) return;+ const int bufferId = it->second.bufferId;+ ma_sound_uninit(&it->second.sound);+ voices.erase(it);+ releaseBuffer(bufferId);+ }+};++AudioEngine::~AudioEngine() { shutdown(); }++bool AudioEngine::init() {+ if (impl_) return impl_->ready;+ impl_ = new Impl();++ // Own the context so the iOS audio session is playback-only. miniaudio+ // defaults to PlayAndRecord, which opens the microphone — that needs a usage+ // permission and, on the simulator, deadlocks AURemoteIO's Initialize. A game+ // only plays out; Playback also sounds through the silent switch. Ignored by+ // the Android backends.+ ma_context_config ctxCfg = ma_context_config_init();+ ctxCfg.coreaudio.sessionCategory = ma_ios_session_category_playback;+ if (ma_context_init(nullptr, 0, &ctxCfg, &impl_->context) != MA_SUCCESS) {+ delete impl_;+ impl_ = nullptr;+ return false;+ }+ impl_->contextReady = true;++ ma_engine_config cfg = ma_engine_config_init();+ cfg.pContext = &impl_->context;+ if (ma_engine_init(&cfg, &impl_->engine) != MA_SUCCESS) {+ ma_context_uninit(&impl_->context);+ delete impl_;+ impl_ = nullptr;+ return false;+ }+ impl_->ready = true;+ impl_->sampleRate = ma_engine_get_sample_rate(&impl_->engine);+ impl_->channels = ma_engine_get_channels(&impl_->engine);+ return true;+}++void AudioEngine::shutdown() {+ if (!impl_) return;+ for (auto& [id, voice] : impl_->voices) ma_sound_uninit(&voice.sound);+ impl_->voices.clear();+ if (impl_->ready) ma_engine_uninit(&impl_->engine);+ if (impl_->contextReady) ma_context_uninit(&impl_->context);+ for (auto& [id, buf] : impl_->buffers) ma_free(buf.pcm, nullptr);+ impl_->buffers.clear();+ delete impl_;+ impl_ = nullptr;+}++bool AudioEngine::ready() const { return impl_ && impl_->ready; }++AudioEngine::Loaded AudioEngine::load(const uint8_t* bytes, size_t n) {+ const Loaded fail{-1, 0.0, 0};+ if (!ready() || !bytes || n == 0) return fail;++ // Decode straight to the engine's format so playback never resamples.+ ma_decoder_config dcfg = ma_decoder_config_init(ma_format_f32, impl_->channels, impl_->sampleRate);+ ma_uint64 frames = 0;+ void* pcm = nullptr;+ if (ma_decode_memory(bytes, n, &dcfg, &frames, &pcm) != MA_SUCCESS || !pcm) return fail;++ // Insert first so the name registered with the manager is the map entry's own+ // (node-stable) string — never a moved-from temporary whose SSO buffer relocates.+ const int id = impl_->nextBuffer++;+ Buffer& buf = impl_->buffers[id];+ buf.name = "buf://" + std::to_string(id);+ buf.pcm = pcm;+ if (ma_resource_manager_register_decoded_data(+ ma_engine_get_resource_manager(&impl_->engine), buf.name.c_str(),+ pcm, frames, ma_format_f32, impl_->channels, impl_->sampleRate) != MA_SUCCESS) {+ impl_->buffers.erase(id);+ ma_free(pcm, nullptr);+ return fail;+ }++ const double duration = impl_->sampleRate ? static_cast<double>(frames) / impl_->sampleRate : 0.0;+ const long long decodedBytes =+ static_cast<long long>(frames) * impl_->channels * static_cast<long long>(sizeof(float));+ return Loaded{id, duration, decodedBytes};+}++void AudioEngine::unload(int bufferId) {+ if (!impl_) return;+ auto it = impl_->buffers.find(bufferId);+ if (it == impl_->buffers.end() || it->second.unloaded) return;+ // Release the manager's own reference; live voices keep their own until they+ // end, so the PCM is freed by releaseBuffer() once the last one does.+ ma_resource_manager_unregister_data(+ ma_engine_get_resource_manager(&impl_->engine), it->second.name.c_str());+ it->second.unloaded = true;+ if (it->second.refs <= 0) {+ ma_free(it->second.pcm, nullptr);+ impl_->buffers.erase(it);+ }+}++int AudioEngine::play(int bufferId, float volume, float pan, bool loop, float rate) {+ if (!ready()) return -1;+ auto bit = impl_->buffers.find(bufferId);+ if (bit == impl_->buffers.end() || bit->second.unloaded) return -1;++ const int id = impl_->nextVoice++;+ Voice& voice = impl_->voices[id]; // node-stable: &voice.sound is fixed+ voice.bufferId = bufferId;+ voice.loop = loop;+ // Data is already decoded + registered, so init just wraps it (no decode).+ // NO_SPATIALIZATION: 2D games pan explicitly; the 3D positioner would fight it.+ if (ma_sound_init_from_file(&impl_->engine, bit->second.name.c_str(),+ MA_SOUND_FLAG_NO_SPATIALIZATION, nullptr, nullptr,+ &voice.sound) != MA_SUCCESS) {+ impl_->voices.erase(id);+ return -1;+ }+ ma_sound_set_volume(&voice.sound, volume);+ ma_sound_set_pan(&voice.sound, pan);+ ma_sound_set_pitch(&voice.sound, rate > 0 ? rate : 1.0f);+ ma_sound_set_looping(&voice.sound, loop ? MA_TRUE : MA_FALSE);+ ma_sound_start(&voice.sound);+ bit->second.refs++;+ return id;+}++void AudioEngine::stop(int voiceId) {+ if (impl_) impl_->destroyVoice(voiceId);+}++void AudioEngine::pause(int voiceId) {+ // ma_sound_stop pauses in place (keeps the cursor); start() resumes.+ if (ma_sound* s = impl_ ? impl_->soundOf(voiceId) : nullptr) ma_sound_stop(s);+}++void AudioEngine::resume(int voiceId) {+ if (ma_sound* s = impl_ ? impl_->soundOf(voiceId) : nullptr) ma_sound_start(s);+}++void AudioEngine::setVolume(int voiceId, float volume) {+ if (ma_sound* s = impl_ ? impl_->soundOf(voiceId) : nullptr) ma_sound_set_volume(s, volume);+}++void AudioEngine::setPan(int voiceId, float pan) {+ if (ma_sound* s = impl_ ? impl_->soundOf(voiceId) : nullptr) ma_sound_set_pan(s, pan);+}++void AudioEngine::setLoop(int voiceId, bool loop) {+ if (!impl_) return;+ auto it = impl_->voices.find(voiceId);+ if (it == impl_->voices.end()) return;+ it->second.loop = loop;+ ma_sound_set_looping(&it->second.sound, loop ? MA_TRUE : MA_FALSE);+}++void AudioEngine::setRate(int voiceId, float rate) {+ if (ma_sound* s = impl_ ? impl_->soundOf(voiceId) : nullptr) {+ ma_sound_set_pitch(s, rate > 0 ? rate : 1.0f);+ }+}++AudioEngine::VoiceState AudioEngine::voiceState(int voiceId) {+ if (!impl_) return {false, false, 0.0};+ auto it = impl_->voices.find(voiceId);+ if (it == impl_->voices.end()) return {false, false, 0.0};+ float cursor = 0;+ ma_sound_get_cursor_in_seconds(&it->second.sound, &cursor);+ return {true, ma_sound_is_playing(&it->second.sound) == MA_TRUE, static_cast<double>(cursor)};+}++void AudioEngine::suspendAll() {+ if (ready()) ma_engine_stop(&impl_->engine);+}++void AudioEngine::resumeAll() {+ if (ready()) ma_engine_start(&impl_->engine);+}++void AudioEngine::pumpEnded(const std::function<void(int)>& onEnded) {+ if (!ready()) return;+ std::vector<int> ended;+ for (auto& [id, voice] : impl_->voices) {+ if (!voice.loop && ma_sound_at_end(&voice.sound) == MA_TRUE) ended.push_back(id);+ }+ for (const int id : ended) {+ onEnded(id); // may synchronously play() new voices — safe (iterating a copy)+ impl_->destroyVoice(id);+ }+}++} // namespace eshostdiff --git a/native/host_js/native_audio.hpp b/native/host_js/native_audio.hppnew file mode 100644index 000000000..98eba8a0e--- /dev/null+++ b/native/host_js/native_audio.hpp@@ -0,0 +1,78 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file native_audio.hpp+ * @brief The native audio engine behind the host's es_audio* bindings.+ * @details One cross-platform implementation (miniaudio: CoreAudio on iOS,+ * AAudio/OpenSL on Android) — decode, mixing and output all run here in+ * C, never per-sample in the JS engine (the no-JIT budget forbids that).+ * The SDK's NativeAudioBackend is a thin shell over the es_audio*+ * bindings, which in turn are a thin shell over this.+ *+ * A buffer id names a decoded clip; a voice id names one playing+ * instance. The miniaudio header is kept out of this interface (pimpl),+ * so host_core.cpp does not pay to compile it.+ */+#pragma once++#include <cstddef>+#include <cstdint>+#include <functional>++namespace eshost {++class AudioEngine {+public:+ AudioEngine() = default;+ ~AudioEngine();+ AudioEngine(const AudioEngine&) = delete;+ AudioEngine& operator=(const AudioEngine&) = delete;++ /** Bring up the audio device. Returns false (and stays silent) if none is+ * available — a game with no sound still runs. */+ bool init();+ void shutdown();+ bool ready() const;++ struct Loaded {+ int id; ///< < 0 on decode failure.+ double duration; ///< Seconds.+ long long bytes; ///< Decoded PCM size, for the residency budget.+ };+ /** Decode a compressed clip to PCM and register it. */+ Loaded load(const uint8_t* bytes, size_t n);+ void unload(int bufferId);++ /** Start a voice on a loaded buffer. Returns its id, or -1 if unknown. */+ int play(int bufferId, float volume, float pan, bool loop, float rate);+ void stop(int voiceId);+ void pause(int voiceId);+ void resume(int voiceId);+ void setVolume(int voiceId, float volume);+ void setPan(int voiceId, float pan);+ void setLoop(int voiceId, bool loop);+ void setRate(int voiceId, float rate);++ struct VoiceState {+ bool valid; ///< False once the voice has ended or was never known.+ bool playing;+ double currentTime; ///< Seconds.+ };+ VoiceState voiceState(int voiceId);++ /** Pause / resume the whole device — the app backgrounding and returning. */+ void suspendAll();+ void resumeAll();++ /** Report every non-looping voice that ended on its own since the last call,+ * then free it. Runs on the game thread each frame — miniaudio's public API+ * is game-thread safe, so the notification reaches JS with no cross-thread+ * hop into QuickJS. */+ void pumpEnded(const std::function<void(int)>& onEnded);++private:+ struct Impl;+ Impl* impl_ = nullptr;+};++} // namespace eshostdiff --git a/native/ios/project.yml b/native/ios/project.ymlindex 8745ac99f..9278fd0a4 100644--- a/native/ios/project.yml+++ b/native/ios/project.yml@@ -27,6 +27,9 @@ targets:- path: ../host_js/logo.pngbuildPhase: resourcestype: file+ - path: ../host_js/beep.wav+ buildPhase: resources+ type: file# An exported project, staged by `cli native --target ios --content <dir>`.# A folder reference (not a group) so cooked subdirectories keep their# shape — the host reads Content/ first, the bundle root second.@@ -59,3 +62,8 @@ targets:- sdk: IOSurface.framework- sdk: CoreGraphics.framework- sdk: Foundation.framework+ # miniaudio's CoreAudio backend (native_audio.cpp), linked at build time+ # because it forces MA_NO_RUNTIME_LINKING on Apple.+ - sdk: AVFoundation.framework+ - sdk: CoreAudio.framework+ - sdk: AudioToolbox.frameworkdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 4e7243430..9dabbb3b9 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -4491,6 +4491,8 @@ loadImagePixels: (path: string) => Promise<ImageLoadResult>loadSubpackage: ((name: string) => Promise<void>) | undefinedname: "web" | "wechat" | "douyin" | "node" | "native"now: () => number+onAppHide: ((callback: () => void) => () => void) | undefined+onAppShow: ((callback: () => void) => () => void) | undefinedonMemoryWarning: ((callback: () => void) => () => void) | undefinedpollGamepads: (() => GamepadSnapshot[]) | undefinedreadCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 3a202dd9c..2df34fc07 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -3943,6 +3943,7 @@ value: string## NativeBridge — interface @beta```+audio: NativeAudioBridge | undefineddevicePixelRatio: () => numberfetch: (url: string, options?: PlatformRequestOptions) => Promise<NativeFetchResult>fileExists: (path: string) => Promise<boolean>@@ -3950,8 +3951,8 @@ getStorageItem: (key: string) => string | nulllanguage: (() => string) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>now: (() => number) | undefined-onHide: ((callback: () => void) => void) | undefined-onShow: ((callback: () => void) => void) | undefined+onHide: ((callback: () => void) => () => void) | undefined+onShow: ((callback: () => void) => () => void) | undefinedreadCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefinedreadFile: (path: string) => Promise<ArrayBuffer>registerInput: (listener: NativeInputListener) => () => void@@ -3993,6 +3994,19 @@ width: number## NativeHostBindings — interface```+es_audioLoad: ((bytes: ArrayBuffer) => { id: number; duration: number; bytes: number; } | null) | undefined+es_audioPause: ((voiceId: number) => void) | undefined+es_audioPlay: ((bufferId: number, volume: number, pan: number, loop: boolean, rate: number) => number) | undefined+es_audioResume: ((voiceId: number) => void) | undefined+es_audioResumeAll: (() => void) | undefined+es_audioSetLoop: ((voiceId: number, loop: boolean) => void) | undefined+es_audioSetPan: ((voiceId: number, pan: number) => void) | undefined+es_audioSetRate: ((voiceId: number, rate: number) => void) | undefined+es_audioSetVolume: ((voiceId: number, volume: number) => void) | undefined+es_audioStop: ((voiceId: number) => void) | undefined+es_audioSuspendAll: (() => void) | undefined+es_audioUnload: ((bufferId: number) => void) | undefined+es_audioVoiceState: ((voiceId: number) => { playing: boolean; currentTime: number; } | null) | undefinedes_devicePixelRatio: (() => number) | undefinedes_getStorageItem: ((key: string) => string | null) | undefinedes_loadImagePixels: (path: string) => { width: number; height: number; pixels: ArrayBuffer; } | null@@ -4025,6 +4039,7 @@ static prototype: NativeMemoryProvider```bindInputEvents: (callbacks: InputEventCallbacks) => voidclearStorage: (prefix: string) => void+createAudioBackend: (() => PlatformAudioBackend) | undefinedcreateCanvas: (_width: number, _height: number) => PlatformCanvascreateImage: () => PlatformImagedevicePixelRatio: () => number@@ -4036,6 +4051,8 @@ language: () => stringloadImagePixels: (path: string) => Promise<ImageLoadResult>name: "native"now: () => number+onAppHide: (callback: () => void) => () => void+onAppShow: (callback: () => void) => () => voidreadCacheFile: (key: string) => Promise<ArrayBuffer | null>readFile: (path: string) => Promise<ArrayBuffer>readTextFile: (path: string) => Promise<string>@@ -4615,6 +4632,8 @@ loadImagePixels: (path: string) => Promise<ImageLoadResult>loadSubpackage: ((name: string) => Promise<void>) | undefinedname: "web" | "wechat" | "douyin" | "node" | "native"now: () => number+onAppHide: ((callback: () => void) => () => void) | undefined+onAppShow: ((callback: () => void) => () => void) | undefinedonMemoryWarning: ((callback: () => void) => () => void) | undefinedpollGamepads: (() => GamepadSnapshot[]) | undefinedreadCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex fc8223aee..600342ec4 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -4486,6 +4486,8 @@ loadImagePixels: (path: string) => Promise<ImageLoadResult>loadSubpackage: ((name: string) => Promise<void>) | undefinedname: "web" | "wechat" | "douyin" | "node" | "native"now: () => number+onAppHide: ((callback: () => void) => () => void) | undefined+onAppShow: ((callback: () => void) => () => void) | undefinedonMemoryWarning: ((callback: () => void) => () => void) | undefinedpollGamepads: (() => GamepadSnapshot[]) | undefinedreadCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d06f283bc..447d36809 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -4493,6 +4493,8 @@ loadImagePixels: (path: string) => Promise<ImageLoadResult>loadSubpackage: ((name: string) => Promise<void>) | undefinedname: "web" | "wechat" | "douyin" | "node" | "native"now: () => number+onAppHide: ((callback: () => void) => () => void) | undefined+onAppShow: ((callback: () => void) => () => void) | undefinedonMemoryWarning: ((callback: () => void) => () => void) | undefinedpollGamepads: (() => GamepadSnapshot[]) | undefinedreadCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefineddiff --git a/sdk/src/audio/NativeAudioBackend.ts b/sdk/src/audio/NativeAudioBackend.tsnew file mode 100644index 000000000..f5f123ed8--- /dev/null+++ b/sdk/src/audio/NativeAudioBackend.ts@@ -0,0 +1,126 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file NativeAudioBackend.ts+ * @brief A PlatformAudioBackend over the native host's audio engine (embedded+ * Dawn + JS engine on iOS/Android).+ * @details A thin adapter over {@link NativeAudioBridge}, exactly as the WeChat+ * backend is over InnerAudioContext: decode, mixing and output all run+ * in the host's native engine (miniaudio), so nothing per-sample touches+ * JS — the no-JIT budget forbids it. `mixer` is therefore null (no JS+ * DSP graph), like WeChat; per-voice volume / pan / rate / loop are the+ * full control surface.+ */+import type { AudioMixer } from './AudioMixer';+import type {+ AudioBackendInitOptions, AudioBufferHandle, AudioHandle,+ PlatformAudioBackend, PlayConfig,+} from './PlatformAudioBackend';+import type { NativeAudioBridge } from '../platform/native/bridge';+import { platformReadFile } from '../platform/base';+import { scalar } from '../math/scalar';++class NativeAudioHandle implements AudioHandle {+ onEnd?: () => void;+ private done_ = false;++ constructor(+ readonly id: number,+ private readonly audio_: NativeAudioBridge,+ private readonly duration_: number,+ private readonly onDispose_: () => void,+ ) {}++ stop(): void {+ if (this.done_) return;+ this.done_ = true;+ this.audio_.stop(this.id);+ this.onDispose_();+ }++ /** @internal The host reported this voice ended on its own (pushed through+ * {@link NativeAudioBridge.onEnded}). Fire onEnd once; a later stop() no-ops. */+ handleEnded_(): void {+ if (this.done_) return;+ this.done_ = true;+ this.onEnd?.();+ this.onDispose_();+ }++ pause(): void { this.audio_.pause(this.id); }+ resume(): void { this.audio_.resume(this.id); }+ setVolume(volume: number): void { this.audio_.setVolume(this.id, volume); }+ setPan(pan: number): void { this.audio_.setPan(this.id, scalar.clamp(pan, -1, 1)); }+ setLoop(loop: boolean): void { this.audio_.setLoop(this.id, loop); }+ setPlaybackRate(rate: number): void { this.audio_.setRate(this.id, rate); }++ get isPlaying(): boolean { return this.audio_.voiceState(this.id)?.playing ?? false; }+ get currentTime(): number { return this.audio_.voiceState(this.id)?.currentTime ?? 0; }+ get duration(): number { return this.duration_; }+}++export class NativeAudioBackend implements PlatformAudioBackend {+ readonly name = 'native';+ readonly mixer: AudioMixer | null = null;+ readonly isReady = true;++ private readonly voices_ = new Map<number, NativeAudioHandle>();+ private readonly offEnded_: () => void;++ constructor(private readonly audio_: NativeAudioBridge) {+ // The host pushes a voice-ended id (like touch); route it to that handle.+ this.offEnded_ = audio_.onEnded((voiceId) => {+ this.voices_.get(voiceId)?.handleEnded_();+ });+ }++ // The native engine is brought up by the host at boot; nothing to initialize+ // or resume here (no user-gesture requirement, unlike a browser AudioContext).+ async initialize(_options?: AudioBackendInitOptions): Promise<void> {}+ async ensureResumed(): Promise<void> {}++ async loadBuffer(url: string): Promise<AudioBufferHandle> {+ // On native the audio ref resolver hands back a packaged path (not bytes),+ // so read the file through the same platform channel as every other asset,+ // then let the native engine decode it.+ return this.loadFromBytes_(await platformReadFile(url));+ }++ async loadBufferFromData(_url: string, data: ArrayBuffer): Promise<AudioBufferHandle> {+ return this.loadFromBytes_(data);+ }++ private loadFromBytes_(bytes: ArrayBuffer): AudioBufferHandle {+ const decoded = this.audio_.load(bytes);+ if (!decoded) throw new Error('[native] audio decode failed');+ return { id: decoded.id, duration: decoded.duration, bytes: decoded.bytes };+ }++ unloadBuffer(handle: AudioBufferHandle): void {+ this.audio_.unload(handle.id);+ }++ play(buffer: AudioBufferHandle, config: PlayConfig): AudioHandle {+ const voiceId = this.audio_.play(+ buffer.id,+ config.volume ?? 1,+ scalar.clamp(config.pan ?? 0, -1, 1),+ config.loop ?? false,+ config.playbackRate ?? 1,+ );+ const handle = new NativeAudioHandle(+ voiceId, this.audio_, buffer.duration, () => this.voices_.delete(voiceId),+ );+ this.voices_.set(voiceId, handle);+ return handle;+ }++ suspend(): void { this.audio_.suspendAll(); }+ resume(): void { this.audio_.resumeAll(); }++ dispose(): void {+ for (const handle of this.voices_.values()) handle.stop();+ this.voices_.clear();+ this.offEnded_();+ }+}diff --git a/sdk/src/audio/index.ts b/sdk/src/audio/index.tsindex 8a2192500..e7bd01f1e 100644--- a/sdk/src/audio/index.ts+++ b/sdk/src/audio/index.ts@@ -18,4 +18,5 @@ export { AudioSource, AudioListener, type AudioSourceData, type AudioListenerDatexport { AttenuationModel, calculateAttenuation, calculatePanning, type SpatialAudioConfig } from './SpatialAudio';export { WebAudioBackend } from './WebAudioBackend';export { WeChatAudioBackend } from './WeChatAudioBackend';+export { NativeAudioBackend } from './NativeAudioBackend';export type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend, AudioBackendInitOptions } from './PlatformAudioBackend';diff --git a/sdk/src/ecs/nativeBindings.ts b/sdk/src/ecs/nativeBindings.tsindex d2199ebc1..e9f0a475d 100644--- a/sdk/src/ecs/nativeBindings.ts+++ b/sdk/src/ecs/nativeBindings.ts@@ -40,6 +40,38 @@ export const PLATFORM_BINDINGS = {utf8Decode: 'es_utf8Decode',} as const;+/**+ * The native audio engine surface (a host with a sound device binds it). Unlike+ * the sets above this one is OPTIONAL: a host with no audio omits every name and+ * the audio system falls back to the silent Null backend, so it is not part of+ * {@link assertNativeBindings}' required set — {@link hasAudioBindings} decides+ * whether {@link NativeAudioBackend} is wired at all.+ */+export const AUDIO_BINDINGS = {+ load: 'es_audioLoad',+ unload: 'es_audioUnload',+ play: 'es_audioPlay',+ stop: 'es_audioStop',+ pause: 'es_audioPause',+ resume: 'es_audioResume',+ setVolume: 'es_audioSetVolume',+ setPan: 'es_audioSetPan',+ setLoop: 'es_audioSetLoop',+ setRate: 'es_audioSetRate',+ voiceState: 'es_audioVoiceState',+ suspendAll: 'es_audioSuspendAll',+ resumeAll: 'es_audioResumeAll',+} as const;++/** Whether a host bound the whole audio surface — the gate for the native audio+ * backend (all-or-nothing, so a partially-implemented host stays silent rather+ * than half-playing). */+export function hasAudioBindings(+ scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,+): boolean {+ return Object.values(AUDIO_BINDINGS).every((name) => typeof scope[name] === 'function');+}+/*** Verify a host bound everything before anything calls it.*diff --git a/sdk/src/lifecycle.ts b/sdk/src/lifecycle.tsindex 80fda54fa..7fe213392 100644--- a/sdk/src/lifecycle.ts+++ b/sdk/src/lifecycle.ts@@ -7,7 +7,7 @@import { defineResource } from './resource';import type { App, Plugin } from './app';-import { getPlatformType } from './platform';+import { getPlatformType, platformOnAppShow, platformOnAppHide } from './platform';import { log } from './logger';// =============================================================================@@ -112,12 +112,14 @@ export class LifecyclePlugin implements Plugin {if (platformType === 'wechat') {this.cleanupFn_ = setupWeChatLifecycle_(manager, app);- } else if (platformType !== 'native' && typeof document !== 'undefined' && typeof window !== 'undefined') {+ } else if (platformType === 'native') {+ this.cleanupFn_ = setupNativeLifecycle_(manager, app);+ } else if (typeof document !== 'undefined' && typeof window !== 'undefined') {this.cleanupFn_ = setupWebLifecycle_(manager, app);}- // Headless hosts (node server, workers) and native (no DOM visibility/focus- // signal — a bridge.onShow/onHide seam lands with the shell) keep the- // Lifecycle resource, always visible.+ // Headless hosts (node server, workers) keep the Lifecycle resource and+ // stay always-visible; a native shell that never wired the show/hide+ // signal degrades to the same (setupNativeLifecycle_ just never fires).}cleanup(): void {@@ -210,3 +212,42 @@ function setupWeChatLifecycle_(manager: LifecycleManager, app: AppLike): (() =>manager.removeAllListeners();};}++// =============================================================================+// Native Platform (embedded Dawn + JS engine)+// =============================================================================++/**+ * Native has no DOM visibility event; the shell pushes foreground/background+ * through the platform adapter (onAppShow/onAppHide, backed by the bridge). Same+ * auto-pause contract as WeChat. The audio device is suspended by the host+ * directly on background — correct even while the JS tick is paused — so this+ * only drives the game tick and the lifecycle events.+ */+function setupNativeLifecycle_(manager: LifecycleManager, app: AppLike): () => void {+ let pausedByLifecycle = false;++ const offShow = platformOnAppShow(() => {+ manager.setVisible_(true);+ if (pausedByLifecycle) {+ app.setPaused(false);+ pausedByLifecycle = false;+ manager.emit_('resume');+ }+ });++ const offHide = platformOnAppHide(() => {+ manager.setVisible_(false);+ if (manager.autoPause && !app.isPaused()) {+ app.setPaused(true);+ pausedByLifecycle = true;+ manager.emit_('pause');+ }+ });++ return (): void => {+ offShow();+ offHide();+ manager.removeAllListeners();+ };+}diff --git a/sdk/src/platform/base.ts b/sdk/src/platform/base.tsindex 5fbe25ff3..e231fc8f1 100644--- a/sdk/src/platform/base.ts+++ b/sdk/src/platform/base.ts@@ -194,6 +194,22 @@ export function platformOnMemoryWarning(callback: () => void): () => void {return p.onMemoryWarning ? p.onMemoryWarning(callback) : () => {};}+/** Subscribe to the app returning to foreground / going to background — the+ * native shell's push signals (no DOM visibility on native). Return an+ * unsubscribe; a platform without the signal never fires. Tolerates an+ * uninitialized platform (tests). */+export function platformOnAppShow(callback: () => void): () => void {+ if (!isPlatformInitialized()) return () => {};+ const p = getPlatform();+ return p.onAppShow ? p.onAppShow(callback) : () => {};+}++export function platformOnAppHide(callback: () => void): () => void {+ if (!isPlatformInitialized()) return () => {};+ const p = getPlatform();+ return p.onAppHide ? p.onAppHide(callback) : () => {};+}+/** Read a persisted string by key (adapter storage: localStorage on web,* `wx.getStorageSync` on WeChat). Returns null when the key is absent OR the* platform is uninitialized (tests) — callers treat both as "nothing stored". */diff --git a/sdk/src/platform/index.ts b/sdk/src/platform/index.tsindex 26a2b474e..f7f92b171 100644--- a/sdk/src/platform/index.ts+++ b/sdk/src/platform/index.ts@@ -43,6 +43,8 @@ export {platformReadCacheFile,platformWriteCacheFile,platformOnMemoryWarning,+ platformOnAppShow,+ platformOnAppHide,platformGetStorageItem,platformSetStorageItem,platformDevicePixelRatio,diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.tsindex 58db1d0ff..ab8cce80f 100644--- a/sdk/src/platform/native/adapter.ts+++ b/sdk/src/platform/native/adapter.ts@@ -24,15 +24,28 @@ import type {PlatformCanvas,PlatformImage,} from '../types';+import type { PlatformAudioBackend } from '../../audio/PlatformAudioBackend';import { setPlatform } from '../base';import { createPrimaryPointer } from '../primaryPointer';+import { NativeAudioBackend } from '../../audio/NativeAudioBackend';import type { NativeBridge, NativeInputListener } from './bridge';export class NativePlatformAdapter implements PlatformAdapter {readonly name = 'native' as const;private inputCleanup_: (() => void) | null = null;- constructor(private readonly bridge_: NativeBridge) {}+ constructor(private readonly bridge_: NativeBridge) {+ // Only advertise audio when the host bound an engine; otherwise the base+ // helper falls back to the silent Null backend (createAudioBackend stays+ // undefined), exactly as on a host with no sound device.+ if (bridge_.audio) {+ const audio = bridge_.audio;+ this.createAudioBackend = () => new NativeAudioBackend(audio);+ }+ }++ /** Assigned in the constructor only when the host bound an audio engine. */+ createAudioBackend?: () => PlatformAudioBackend;async fetch(url: string, options?: PlatformRequestOptions): Promise<PlatformResponse> {const r = await this.bridge_.fetch(url, options);@@ -122,9 +135,16 @@ export class NativePlatformAdapter implements PlatformAdapter {this.inputCleanup_ = null;}- // No createAudioBackend: audio ships with the shell, so the adapter omits it- // and the audio system falls back to the silent Null backend (like the Node- // host and the optional video backend) until the shell provides one.+ // Foreground/background: the shell has no DOM visibility event, so the+ // Lifecycle plugin's native branch subscribes here and the host pushes the+ // signal through the bridge. A bridge without them → the app stays visible.+ onAppShow(callback: () => void): () => void {+ return this.bridge_.onShow?.(callback) ?? (() => {});+ }++ onAppHide(callback: () => void): () => void {+ return this.bridge_.onHide?.(callback) ?? (() => {});+ }getStorageItem(key: string): string | null {return this.bridge_.getStorageItem(key);diff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.tsindex ce6d51324..9c5973286 100644--- a/sdk/src/platform/native/bridge.ts+++ b/sdk/src/platform/native/bridge.ts@@ -49,6 +49,44 @@ export interface NativeInputListener {onKeyUp?(code: string): 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+ * over InnerAudioContext). The engine owns decode + mixing + output natively —+ * nothing per-sample runs in JS, which the no-JIT budget forbids. Present only+ * when the host bound the audio primitives; a host without a sound device omits+ * `NativeBridge.audio` and the audio system stays silent (the Null backend).+ *+ * A `bufferId` names a decoded clip; a `voiceId` names one playing instance of+ * it. Both are non-negative host handles; a failed load or play returns null / -1.+ */+export interface NativeAudioBridge {+ /** Decode + register a clip from its (compressed) file bytes. Returns the+ * buffer handle, its length in seconds and its decoded size in bytes (for the+ * residency budget), or null on decode failure. */+ load(bytes: ArrayBuffer): { id: number; duration: number; bytes: number } | null;+ unload(bufferId: number): void;+ /** Start a voice on a loaded buffer. Returns its voice id, or -1 if the buffer+ * is unknown. */+ play(bufferId: number, volume: number, pan: number, loop: boolean, rate: number): number;+ stop(voiceId: number): void;+ pause(voiceId: number): void;+ resume(voiceId: number): void;+ setVolume(voiceId: number, volume: number): void;+ setPan(voiceId: number, pan: number): void;+ setLoop(voiceId: number, loop: boolean): void;+ setRate(voiceId: number, rate: number): void;+ /** `{ playing, currentTime }` for a live voice, or null once it has ended (or+ * was never known) — the SDK derives isPlaying / currentTime from it. */+ voiceState(voiceId: number): { playing: boolean; currentTime: number } | null;+ /** Pause / resume the whole device — the app going to background and back. */+ suspendAll(): void;+ resumeAll(): void;+ /** Register the sink the host notifies when a voice ends on its own (pushed,+ * like touch); returns an unsubscribe. */+ onEnded(callback: (voiceId: number) => void): () => void;+}+/*** The host functions the native shell injects. Async where the call crosses to* the OS (files, network, image decode); sync where the native API is sync@@ -90,8 +128,15 @@ export interface NativeBridge {/** Host UI language ('zh-CN', 'en-US', …). Optional — falls back to 'en'. */language?(): string;- /** App foreground/background signals. Reserved for the native Lifecycle seam- * (not wired this round). */- onShow?(callback: () => void): void;- onHide?(callback: () => void): void;+ /** The native audio engine, when the host has a sound device. Absent → silent+ * Null backend. See {@link NativeAudioBridge}. */+ audio?: NativeAudioBridge;++ /** 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 —+ * a shell that never backgrounds (or has not wired it) omits them and the app+ * stays always-visible. */+ onShow?(callback: () => void): () => void;+ onHide?(callback: () => void): () => void;}diff --git a/sdk/src/platform/native/hostBridge.ts b/sdk/src/platform/native/hostBridge.tsindex f6218e3b0..bc0f39081 100644--- a/sdk/src/platform/native/hostBridge.ts+++ b/sdk/src/platform/native/hostBridge.ts@@ -13,8 +13,9 @@*/import { log } from '../../logger';-import type { NativeBridge, NativeInputListener } from './bridge';+import type { NativeAudioBridge, NativeBridge, NativeInputListener } from './bridge';import { assertHostEnvironment } from './hostEnvironment';+import { hasAudioBindings } from '../../ecs/nativeBindings';/** Touch phases the host reports, matching the order it dispatches. */const TOUCH_START = 0;@@ -39,6 +40,22 @@ export interface NativeHostBindings {es_storageKeys?(): string[];/** Screen scale (1 when the host reports surface pixels directly). */es_devicePixelRatio?(): number;++ /** The native audio engine, all-or-nothing (see {@link AUDIO_BINDINGS}). A+ * host without a sound device binds none and stays silent. */+ 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;+ es_audioStop?(voiceId: number): void;+ es_audioPause?(voiceId: number): void;+ es_audioResume?(voiceId: number): void;+ es_audioSetVolume?(voiceId: number, volume: number): void;+ es_audioSetPan?(voiceId: number, pan: number): void;+ es_audioSetLoop?(voiceId: number, loop: boolean): void;+ es_audioSetRate?(voiceId: number, rate: number): void;+ es_audioVoiceState?(voiceId: number): { playing: boolean; currentTime: number } | null;+ es_audioSuspendAll?(): void;+ es_audioResumeAll?(): void;}/**@@ -72,6 +89,8 @@ export function createHostBridge(};const storage = hostStorage(bindings);+ const audio = hostAudio(bindings, scope);+ const lifecycle = hostVisibility(scope);return {readFile: (path) => {@@ -107,6 +126,57 @@ export function createHostBridge(return () => { listener = null; };},devicePixelRatio: () => bindings.es_devicePixelRatio?.() ?? 1,+ ...(audio ? { audio } : {}),+ ...lifecycle,+ };+}++/**+ * Assemble the audio bridge from the host's es_audio* primitives, or undefined+ * when the host bound none (→ silent Null backend). Also installs+ * `es_onNativeAudioEnded`, the entry point the host calls when a voice ends on+ * its own, fanning out to the backend that subscribed.+ */+function hostAudio(+ bindings: NativeHostBindings, scope: Record<string, unknown>,+): NativeAudioBridge | undefined {+ if (!hasAudioBindings(scope)) return undefined;+ let ended: ((voiceId: number) => void) | null = null;+ scope.es_onNativeAudioEnded = (voiceId: number): void => { ended?.(voiceId); };+ return {+ load: (bytes) => bindings.es_audioLoad!(bytes),+ unload: (id) => bindings.es_audioUnload!(id),+ play: (buf, vol, pan, loop, rate) => bindings.es_audioPlay!(buf, vol, pan, loop, rate),+ stop: (v) => bindings.es_audioStop!(v),+ pause: (v) => bindings.es_audioPause!(v),+ resume: (v) => bindings.es_audioResume!(v),+ setVolume: (v, x) => bindings.es_audioSetVolume!(v, x),+ setPan: (v, x) => bindings.es_audioSetPan!(v, x),+ setLoop: (v, on) => bindings.es_audioSetLoop!(v, on),+ setRate: (v, x) => bindings.es_audioSetRate!(v, x),+ voiceState: (v) => bindings.es_audioVoiceState!(v),+ suspendAll: () => bindings.es_audioSuspendAll!(),+ resumeAll: () => bindings.es_audioResumeAll!(),+ onEnded: (cb) => { ended = cb; return () => { if (ended === cb) ended = null; }; },+ };+}++/**+ * 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.+ */+function hostVisibility(+ 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();+ };+ 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); }; },};}diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.tsindex 1ebe61295..c3bf68529 100644--- a/sdk/src/platform/types.ts+++ b/sdk/src/platform/types.ts@@ -315,6 +315,13 @@ export interface PlatformAdapter {* omit it. Residency caches subscribe to drop their evictable entries. */onMemoryWarning?(callback: () => void): () => void;+ /** App foreground/background signals, for platforms with no DOM visibility+ * event. The native shell pushes them through its bridge; the Lifecycle+ * plugin subscribes and auto-pauses on hide. Web/WeChat read visibility from+ * their own globals (document/wx) and omit these. Each returns an unsubscribe. */+ onAppShow?(callback: () => void): () => void;+ onAppHide?(callback: () => void): () => void;+/** The host's UI language tag ('zh-CN', 'en-US', …). WeChat reports* 'zh_CN'-style tags — `platformLanguage()` normalizes underscores.* Optional; web falls through to navigator.language. */diff --git a/sdk/tests/native-audio.test.ts b/sdk/tests/native-audio.test.tsnew file mode 100644index 000000000..ddb44a917--- /dev/null+++ b/sdk/tests/native-audio.test.ts@@ -0,0 +1,226 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Stage C: the native audio + lifecycle seams. Audio is a thin SDK shell+ * over the host's es_audio* engine (miniaudio), assembled onto the bridge+ * like storage; foreground/background is a pushed signal (like touch). Both+ * are optional — a host without them stays silent / always-visible, and+ * assertNativeHost must still pass.+ */+import { describe, it, expect, vi } from 'vitest';+import { createHostBridge, NativePlatformAdapter, assertNativeHost } from '../src/platform/native';+import type { NativeBridge } from '../src/platform/native';+import { NativeAudioBackend } from '../src/audio/NativeAudioBackend';+import {+ AUDIO_BINDINGS, hasAudioBindings,+ REGISTRY_BINDINGS, RESOURCE_BINDINGS, PLATFORM_BINDINGS,+} from '../src/ecs/nativeBindings';++function hostGlobals(): Record<string, unknown> {+ return {+ console: { log: () => {}, error: () => {}, warn: () => {} },+ setTimeout: () => 0,+ clearTimeout: () => {},+ performance: { now: () => 0 },+ TextDecoder,+ };+}++/** A fake native audio engine, installed as the host's es_audio* primitives. */+function installAudioHost(scope: Record<string, unknown>) {+ const calls = { play: [] as unknown[][], stop: [] as number[], setVolume: [] as unknown[][], suspend: 0, resume: 0 };+ let nextBuffer = 1;+ let nextVoice = 100;+ const voices = new Map<number, { playing: boolean; time: number; loop: boolean }>();++ scope.es_audioLoad = (bytes: ArrayBuffer) => ({ id: nextBuffer++, duration: 2, bytes: bytes.byteLength * 4 });+ scope.es_audioUnload = () => {};+ scope.es_audioPlay = (buf: number, vol: number, pan: number, loop: boolean, rate: number) => {+ const id = nextVoice++;+ voices.set(id, { playing: true, time: 0, loop });+ calls.play.push([buf, vol, pan, loop, rate]);+ return id;+ };+ scope.es_audioStop = (v: number) => { voices.delete(v); calls.stop.push(v); };+ scope.es_audioPause = (v: number) => { const s = voices.get(v); if (s) s.playing = false; };+ scope.es_audioResume = (v: number) => { const s = voices.get(v); if (s) s.playing = true; };+ scope.es_audioSetVolume = (v: number, x: number) => calls.setVolume.push([v, x]);+ scope.es_audioSetPan = () => {};+ scope.es_audioSetLoop = () => {};+ scope.es_audioSetRate = () => {};+ scope.es_audioVoiceState = (v: number) => {+ const s = voices.get(v);+ return s ? { playing: s.playing, currentTime: s.time } : null;+ };+ scope.es_audioSuspendAll = () => { calls.suspend++; };+ scope.es_audioResumeAll = () => { calls.resume++; };+ return { calls, voices };+}++function audioScope(): Record<string, unknown> {+ const scope = {+ ...hostGlobals(),+ es_readAsset: () => new ArrayBuffer(4),+ es_loadImagePixels: () => ({ width: 1, height: 1, pixels: new ArrayBuffer(4) }),+ };+ installAudioHost(scope);+ return scope;+}++describe('hasAudioBindings', () => {+ it('is true only when the whole surface is bound (all-or-nothing)', () => {+ const scope = audioScope();+ expect(hasAudioBindings(scope)).toBe(true);+ delete scope[AUDIO_BINDINGS.play];+ expect(hasAudioBindings(scope)).toBe(false);+ });+});++describe('createHostBridge — audio assembly', () => {+ it('assembles bridge.audio when the host bound the engine', () => {+ expect(createHostBridge(audioScope()).audio).toBeDefined();+ });++ it('omits bridge.audio when the host bound no engine', () => {+ const scope = {+ ...hostGlobals(),+ es_readAsset: () => new ArrayBuffer(4),+ es_loadImagePixels: () => ({ width: 1, height: 1, pixels: new ArrayBuffer(4) }),+ };+ expect(createHostBridge(scope).audio).toBeUndefined();+ });+});++describe('NativeAudioBackend', () => {+ it('loads, plays and reports state through the bridge', async () => {+ const scope = audioScope();+ const host = installAudioHost(scope); // capture the same closure the bridge will use+ const bridge = createHostBridge(scope);+ const backend = new NativeAudioBackend(bridge.audio!);+ expect(backend.mixer).toBeNull();++ const buffer = await backend.loadBufferFromData('sfx', new ArrayBuffer(16));+ expect(buffer).toMatchObject({ duration: 2 });+ expect(buffer.bytes).toBe(64);++ const handle = backend.play(buffer, { volume: 0.5, loop: true, pan: 2 });+ // pan is clamped to [-1, 1] before it reaches the host.+ expect(host.calls.play[0]).toEqual([buffer.id, 0.5, 1, true, 1]);+ expect(handle.isPlaying).toBe(true);+ expect(handle.duration).toBe(2);++ handle.setVolume(0.25);+ expect(host.calls.setVolume[0]).toEqual([handle.id, 0.25]);+ });++ it('fires onEnd from the host push, then a later stop() is a no-op', () => {+ const scope = audioScope();+ const host = installAudioHost(scope);+ const bridge = createHostBridge(scope);+ const backend = new NativeAudioBackend(bridge.audio!);+ const handle = backend.play({ id: 1, duration: 1 }, {});+ handle.onEnd = vi.fn();++ // The host reports the voice ended on its own.+ (scope.es_onNativeAudioEnded as (v: number) => void)(handle.id);+ expect(handle.onEnd).toHaveBeenCalledTimes(1);++ const stopsBefore = host.calls.stop.length;+ handle.stop(); // guarded — the voice is already gone+ expect(host.calls.stop.length).toBe(stopsBefore);+ });++ it('stop() tears the voice down through the bridge', () => {+ const scope = audioScope();+ const host = installAudioHost(scope);+ const bridge = createHostBridge(scope);+ const backend = new NativeAudioBackend(bridge.audio!);+ const handle = backend.play({ id: 1, duration: 1 }, {});+ handle.stop();+ expect(host.calls.stop).toContain(handle.id);+ expect(handle.isPlaying).toBe(false);+ });++ it('suspend/resume drive the whole device', () => {+ const scope = audioScope();+ const host = installAudioHost(scope);+ const backend = new NativeAudioBackend(createHostBridge(scope).audio!);+ backend.suspend();+ backend.resume();+ expect(host.calls.suspend).toBe(1);+ expect(host.calls.resume).toBe(1);+ });+});++describe('createHostBridge — visibility (lifecycle)', () => {+ it('routes the host visibility push to onShow / onHide', () => {+ const scope = audioScope();+ const bridge = createHostBridge(scope);+ const show = vi.fn();+ const hide = vi.fn();+ const offShow = bridge.onShow!(show);+ bridge.onHide!(hide);++ const push = scope.es_onNativeVisibility as (visible: boolean) => void;+ push(false);+ push(true);+ expect(hide).toHaveBeenCalledTimes(1);+ expect(show).toHaveBeenCalledTimes(1);++ offShow();+ push(true);+ expect(show).toHaveBeenCalledTimes(1); // detached+ });+});++describe('NativePlatformAdapter — Stage C surfaces', () => {+ function bridgeWith(audio: NativeBridge['audio'], visibility: boolean): NativeBridge {+ const shows: (() => void)[] = [];+ const hides: (() => void)[] = [];+ return {+ readFile: async () => new ArrayBuffer(0),+ fileExists: async () => false,+ fetch: async () => ({ ok: false, status: 404 }),+ loadImagePixels: async () => ({ width: 1, height: 1, pixels: new Uint8Array(4) }),+ getStorageItem: () => null,+ setStorageItem: () => {},+ removeStorageItem: () => {},+ storageKeys: () => [],+ registerInput: () => () => {},+ devicePixelRatio: () => 1,+ audio,+ ...(visibility ? {+ onShow: (cb: () => void) => { shows.push(cb); return () => {}; },+ onHide: (cb: () => void) => { hides.push(cb); return () => {}; },+ } : {}),+ };+ }++ it('advertises createAudioBackend only when the bridge has audio', () => {+ const scope = audioScope();+ const audio = createHostBridge(scope).audio;+ expect(new NativePlatformAdapter(bridgeWith(audio, true)).createAudioBackend?.()?.name).toBe('native');+ expect(new NativePlatformAdapter(bridgeWith(undefined, true)).createAudioBackend).toBeUndefined();+ });++ it('delegates onAppShow / onAppHide to the bridge, tolerating a bridge without them', () => {+ const withVisibility = new NativePlatformAdapter(bridgeWith(undefined, true));+ expect(typeof withVisibility.onAppShow(() => {})).toBe('function');++ const without = new NativePlatformAdapter(bridgeWith(undefined, false));+ expect(() => without.onAppHide(() => {})()).not.toThrow();+ });+});++describe('assertNativeHost — audio stays optional', () => {+ it('passes on a host with no audio engine', () => {+ const scope = hostGlobals();+ for (const name of [+ ...Object.values(REGISTRY_BINDINGS),+ ...Object.values(RESOURCE_BINDINGS),+ ...Object.values(PLATFORM_BINDINGS),+ ]) scope[name] = () => undefined;+ expect(hasAudioBindings(scope)).toBe(false);+ expect(() => assertNativeHost(scope)).not.toThrow();+ });+});