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): audio + app lifecycle over the real SDK (Stage C)

esenginec7000dbc1cd2
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
index 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.md
index 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 and
texture 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 the
web 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 the
bytes directly — no wasm heap. `game.js` now loads its logo through this channel
instead 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.wav
new file mode 100644
index 000000000..27b4238a8
Binary files /dev/null and b/native/host_js/beep.wav differ
diff --git a/native/host_js/game.js b/native/host_js/game.js
index 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.cpp
index 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 device
std::string cacheDir; // app private dir — SDK bytecode cache
std::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* argv
return 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 = &registry;
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 eshost
diff --git a/native/host_js/host_core.hpp b/native/host_js/host_core.hpp
index 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 is
diff --git a/native/host_js/main_android.cpp b/native/host_js/main_android.cpp
index 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.mm
index 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 lags
if (_booted && eshost::bindSurface()) _displayLink.paused = NO;
}
diff --git a/native/host_js/native_audio.cpp b/native/host_js/native_audio.cpp
new file mode 100644
index 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 eshost
diff --git a/native/host_js/native_audio.hpp b/native/host_js/native_audio.hpp
new file mode 100644
index 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 eshost
diff --git a/native/ios/project.yml b/native/ios/project.yml
index 8745ac99f..9278fd0a4 100644
--- a/native/ios/project.yml
+++ b/native/ios/project.yml
@@ -27,6 +27,9 @@ targets:
- path: ../host_js/logo.png
buildPhase: resources
type: 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.framework
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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>) | undefined
name: "web" | "wechat" | "douyin" | "node" | "native"
now: () => number
+onAppHide: ((callback: () => void) => () => void) | undefined
+onAppShow: ((callback: () => void) => () => void) | undefined
onMemoryWarning: ((callback: () => void) => () => void) | undefined
pollGamepads: (() => GamepadSnapshot[]) | undefined
readCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 | undefined
devicePixelRatio: () => number
fetch: (url: string, options?: PlatformRequestOptions) => Promise<NativeFetchResult>
fileExists: (path: string) => Promise<boolean>
@@ -3950,8 +3951,8 @@ getStorageItem: (key: string) => string | null
language: (() => string) | undefined
loadImagePixels: (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) | undefined
readCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefined
readFile: (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) | undefined
es_devicePixelRatio: (() => number) | undefined
es_getStorageItem: ((key: string) => string | null) | undefined
es_loadImagePixels: (path: string) => { width: number; height: number; pixels: ArrayBuffer; } | null
@@ -4025,6 +4039,7 @@ static prototype: NativeMemoryProvider
```
bindInputEvents: (callbacks: InputEventCallbacks) => void
clearStorage: (prefix: string) => void
+createAudioBackend: (() => PlatformAudioBackend) | undefined
createCanvas: (_width: number, _height: number) => PlatformCanvas
createImage: () => PlatformImage
devicePixelRatio: () => number
@@ -4036,6 +4051,8 @@ language: () => string
loadImagePixels: (path: string) => Promise<ImageLoadResult>
name: "native"
now: () => number
+onAppHide: (callback: () => void) => () => void
+onAppShow: (callback: () => void) => () => void
readCacheFile: (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>) | undefined
name: "web" | "wechat" | "douyin" | "node" | "native"
now: () => number
+onAppHide: ((callback: () => void) => () => void) | undefined
+onAppShow: ((callback: () => void) => () => void) | undefined
onMemoryWarning: ((callback: () => void) => () => void) | undefined
pollGamepads: (() => GamepadSnapshot[]) | undefined
readCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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>) | undefined
name: "web" | "wechat" | "douyin" | "node" | "native"
now: () => number
+onAppHide: ((callback: () => void) => () => void) | undefined
+onAppShow: ((callback: () => void) => () => void) | undefined
onMemoryWarning: ((callback: () => void) => () => void) | undefined
pollGamepads: (() => GamepadSnapshot[]) | undefined
readCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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>) | undefined
name: "web" | "wechat" | "douyin" | "node" | "native"
now: () => number
+onAppHide: ((callback: () => void) => () => void) | undefined
+onAppShow: ((callback: () => void) => () => void) | undefined
onMemoryWarning: ((callback: () => void) => () => void) | undefined
pollGamepads: (() => GamepadSnapshot[]) | undefined
readCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefined
diff --git a/sdk/src/audio/NativeAudioBackend.ts b/sdk/src/audio/NativeAudioBackend.ts
new file mode 100644
index 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.ts
index 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 AudioListenerDat
export { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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();
+ });
+});