Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(native): the audio device is watched and brought back when it stops taking sound, so a game is not left silent after the background

yhh55d65ec863a4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c79e95d77..a71121f14 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ published separately; it ships inside the editor.
### Fixed
+- **Sound comes back when a device's audio dies on its own.** On the Android and iOS hosts, a game whose audio device did not start again on returning from the background, or whose output stream was dropped while it was away, stayed silent until it was restarted. The host now checks every frame that the device is still taking sound while the game wants it; after half a second of nothing it restarts the device, and from the third try rebuilds it, retrying at growing intervals of up to 5 seconds. Sounds that were playing carry on where they were, and the log says each time it acts.
- **A render target works on a native device.** On the Android and iOS hosts `RenderTexture.create` handed back 0 for its handle and its texture, so a camera's `renderTarget` and anything painted into a texture drew nothing, and nothing was logged. The SDK asked only the web's engine module for a target; it now asks whichever engine core is running, and a device names the target's texture for a `Sprite` as the web does. A target that cannot be made is now reported once in the log.
- **A `#pragma lighting direct` surface takes a sun's shadow.** Under a directional light with a size (any `sourceAngle` above 0, the default 0.53 included) such a shader drew no shadow at all; it now draws the hard shadow the directive promises.
diff --git a/native/host/Host.cpp b/native/host/Host.cpp
index c48a6a596..aa7e71b2e 100644
--- a/native/host/Host.cpp
+++ b/native/host/Host.cpp
@@ -379,9 +379,14 @@ void frame(long long vsyncNanos) {
pumpJs(h); // run the App tick's async systems and any timers they set
benchPumpEnd();
- // Notify JS of voices that ended on their own (the audio thread never touches
- // the JS engine; we poll on this thread and push, like touch). onEnd handlers may
- // start new sounds synchronously — safe, pumpEnded iterates a snapshot.
+ const AudioEngine::Health audio = h.audio.maintain();
+ if (audio.attempt > 0) {
+ hostLog(!audio.started, "audio: no sound for %.0f ms, %s the device (attempt %d)%s",
+ audio.silentMs, audio.rebuilt ? "rebuilt" : "restarted", audio.attempt,
+ audio.started ? "" : ", which failed");
+ }
+ if (audio.recovered) hostLog(false, "audio: sound is back");
+
h.audio.pumpEnded([&h](int voiceId) {
esjs::Enter enter;
const esjs::Val arg = esjs::int32(voiceId);
diff --git a/native/host/bindings/AudioBindings.cpp b/native/host/bindings/AudioBindings.cpp
index aa12d4e91..de986a611 100644
--- a/native/host/bindings/AudioBindings.cpp
+++ b/native/host/bindings/AudioBindings.cpp
@@ -105,6 +105,9 @@ esjs::Val js_audioSuspendAll(const esjs::Args& a) {
esjs::Val js_audioResumeAll(const esjs::Args& a) {
host().audio.resumeAll(); return esjs::undefined();
}
+esjs::Val js_audioDebugFault(const esjs::Args& a) {
+ host().audio.debugFault(a.size() > 0 ? esjs::toInt32(a[0]) : 0); return esjs::undefined();
+}
} // namespace
@@ -136,6 +139,7 @@ void registerAudioBindings(HostState& h, esjs::Val global) {
bindGlobal(global, "es_audioVoiceState", js_audioVoiceState, 1);
bindGlobal(global, "es_audioSuspendAll", js_audioSuspendAll, 0);
bindGlobal(global, "es_audioResumeAll", js_audioResumeAll, 0);
+ bindGlobal(global, "es_audioDebugFault", js_audioDebugFault, 1);
}
} // namespace eshost
diff --git a/native/host/media/audio_watchdog.hpp b/native/host/media/audio_watchdog.hpp
new file mode 100644
index 000000000..2b597d42a
--- /dev/null
+++ b/native/host/media/audio_watchdog.hpp
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#pragma once
+
+#include <algorithm>
+#include <cstdint>
+
+namespace eshost {
+
+class AudioWatchdog {
+public:
+ enum class Action { None, Restart, Rebuild };
+
+ static constexpr double kGraceMs = 500.0;
+ static constexpr double kMaxBackoffMs = 5000.0;
+ static constexpr int kRestartsBeforeRebuild = 2;
+
+ void want(bool running, double nowMs) {
+ wantRunning_ = running;
+ failures_ = 0;
+ lastAliveMs_ = nowMs;
+ nextTryMs_ = nowMs + kGraceMs;
+ }
+
+ Action tick(double nowMs, uint64_t callbacks) {
+ if (!wantRunning_ || callbacks != lastCallbacks_) {
+ if (wantRunning_) {
+ lastAliveMs_ = nowMs;
+ nextTryMs_ = nowMs + kGraceMs;
+ recovered_ = failures_ > 0;
+ failures_ = 0;
+ }
+ lastCallbacks_ = callbacks;
+ return Action::None;
+ }
+ if (nowMs < nextTryMs_) return Action::None;
+ ++failures_;
+ nextTryMs_ = nowMs + std::min(kGraceMs * double(1 << std::min(failures_, 4)), kMaxBackoffMs);
+ return failures_ <= kRestartsBeforeRebuild ? Action::Restart : Action::Rebuild;
+ }
+
+ bool wantRunning() const { return wantRunning_; }
+ int failures() const { return failures_; }
+ double silentMs(double nowMs) const { return nowMs - lastAliveMs_; }
+
+ bool takeRecovered() {
+ const bool was = recovered_;
+ recovered_ = false;
+ return was;
+ }
+
+private:
+ bool wantRunning_ = false;
+ bool recovered_ = false;
+ int failures_ = 0;
+ uint64_t lastCallbacks_ = 0;
+ double lastAliveMs_ = 0.0;
+ double nextTryMs_ = 0.0;
+};
+
+} // namespace eshost
diff --git a/native/host/media/native_audio.cpp b/native/host/media/native_audio.cpp
index 6a69b0053..eb88316e7 100644
--- a/native/host/media/native_audio.cpp
+++ b/native/host/media/native_audio.cpp
@@ -17,7 +17,10 @@
#include "native_audio.hpp"
#include "audio_spectrum.hpp"
+#include "audio_watchdog.hpp"
+#include <atomic>
+#include <chrono>
#include <string>
#include <unordered_map>
#include <vector>
@@ -68,6 +71,10 @@ void spectrumTapProcess(ma_node* node, const float** framesIn, ma_uint32* frameC
struct AudioEngine::Impl {
ma_context context{};
+ ma_device device{};
+ bool deviceReady = false;
+ std::atomic<uint64_t> callbacks{0};
+ AudioWatchdog watchdog;
ma_engine engine{};
SpectrumTap tap{};
bool tapReady = false;
@@ -107,6 +114,38 @@ struct AudioEngine::Impl {
}
};
+namespace {
+
+double nowMs() {
+ return std::chrono::duration<double, std::milli>(
+ std::chrono::steady_clock::now().time_since_epoch()).count();
+}
+
+void deviceData(ma_device* device, void* out, const void*, ma_uint32 frames) {
+ auto* impl = static_cast<AudioEngine::Impl*>(device->pUserData);
+ ma_engine_read_pcm_frames(&impl->engine, out, frames, nullptr);
+ impl->callbacks.fetch_add(1, std::memory_order_relaxed);
+}
+
+bool openDevice(AudioEngine::Impl* impl) {
+ ma_device_config cfg = ma_device_config_init(ma_device_type_playback);
+ cfg.playback.format = ma_format_f32;
+ cfg.playback.channels = impl->channels;
+ cfg.sampleRate = impl->sampleRate;
+ cfg.dataCallback = deviceData;
+ cfg.pUserData = impl;
+ impl->deviceReady = ma_device_init(&impl->context, &cfg, &impl->device) == MA_SUCCESS;
+ return impl->deviceReady;
+}
+
+void closeDevice(AudioEngine::Impl* impl) {
+ if (!impl->deviceReady) return;
+ ma_device_uninit(&impl->device);
+ impl->deviceReady = false;
+}
+
+} // namespace
+
AudioEngine::~AudioEngine() { shutdown(); }
bool AudioEngine::init() {
@@ -127,9 +166,17 @@ bool AudioEngine::init() {
}
impl_->contextReady = true;
+ if (!openDevice(impl_)) {
+ ma_context_uninit(&impl_->context);
+ delete impl_;
+ impl_ = nullptr;
+ return false;
+ }
ma_engine_config cfg = ma_engine_config_init();
cfg.pContext = &impl_->context;
+ cfg.pDevice = &impl_->device;
if (ma_engine_init(&cfg, &impl_->engine) != MA_SUCCESS) {
+ closeDevice(impl_);
ma_context_uninit(&impl_->context);
delete impl_;
impl_ = nullptr;
@@ -138,6 +185,7 @@ bool AudioEngine::init() {
impl_->ready = true;
impl_->sampleRate = ma_engine_get_sample_rate(&impl_->engine);
impl_->channels = ma_engine_get_channels(&impl_->engine);
+ impl_->watchdog.want(true, nowMs());
// The analyser tap, between the voices and the endpoint. Optional: a failure
// here costs the spectrum, not the sound.
@@ -167,7 +215,9 @@ void AudioEngine::shutdown() {
for (auto& [id, voice] : impl_->voices) ma_sound_uninit(&voice.sound);
impl_->voices.clear();
if (impl_->tapReady) { ma_node_uninit(&impl_->tap.base, nullptr); impl_->tapReady = false; }
+ if (impl_->deviceReady) ma_device_stop(&impl_->device);
if (impl_->ready) ma_engine_uninit(&impl_->engine);
+ closeDevice(impl_);
if (impl_->contextReady) ma_context_uninit(&impl_->context);
for (auto& [id, buf] : impl_->buffers) ma_free(buf.pcm, nullptr);
impl_->buffers.clear();
@@ -303,11 +353,42 @@ AudioEngine::VoiceState AudioEngine::voiceState(int voiceId) {
}
void AudioEngine::suspendAll() {
- if (ready()) ma_engine_stop(&impl_->engine);
+ if (!ready()) return;
+ impl_->watchdog.want(false, nowMs());
+ if (impl_->deviceReady) ma_device_stop(&impl_->device);
}
void AudioEngine::resumeAll() {
- if (ready()) ma_engine_start(&impl_->engine);
+ if (!ready()) return;
+ impl_->watchdog.want(true, nowMs());
+ if (impl_->deviceReady) ma_device_start(&impl_->device);
+}
+
+AudioEngine::Health AudioEngine::maintain() {
+ Health health;
+ if (!ready()) return health;
+ const double now = nowMs();
+ const AudioWatchdog::Action action =
+ impl_->watchdog.tick(now, impl_->callbacks.load(std::memory_order_relaxed));
+ health.recovered = impl_->watchdog.takeRecovered();
+ if (action == AudioWatchdog::Action::None) return health;
+ health.attempt = impl_->watchdog.failures();
+ health.silentMs = impl_->watchdog.silentMs(now);
+ health.rebuilt = action == AudioWatchdog::Action::Rebuild || !impl_->deviceReady;
+ if (health.rebuilt) {
+ closeDevice(impl_);
+ health.started = openDevice(impl_) && ma_device_start(&impl_->device) == MA_SUCCESS;
+ } else {
+ ma_device_stop(&impl_->device);
+ health.started = ma_device_start(&impl_->device) == MA_SUCCESS;
+ }
+ return health;
+}
+
+void AudioEngine::debugFault(int kind) {
+ if (!ready()) return;
+ if (kind == 0) ma_device_stop(&impl_->device);
+ else closeDevice(impl_);
}
void AudioEngine::pumpEnded(const std::function<void(int)>& onEnded) {
diff --git a/native/host/media/native_audio.hpp b/native/host/media/native_audio.hpp
index 06f6b5441..8a2d507ef 100644
--- a/native/host/media/native_audio.hpp
+++ b/native/host/media/native_audio.hpp
@@ -71,14 +71,25 @@ public:
void suspendAll();
void resumeAll();
+ struct Health {
+ int attempt = 0;
+ double silentMs = 0.0;
+ bool rebuilt = false;
+ bool started = false;
+ bool recovered = false;
+ };
+ Health maintain();
+ void debugFault(int kind);
+
/** 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 the JS engine. */
void pumpEnded(const std::function<void(int)>& onEnded);
-private:
struct Impl;
+
+private:
Impl* impl_ = nullptr;
};
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index b0d7867be..aa75e3a3e 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -586,6 +586,10 @@ add_executable(test_shader_variant
target_include_directories(test_shader_variant PRIVATE ${CMAKE_SOURCE_DIR}/src)
add_test(NAME test_shader_variant COMMAND test_shader_variant)
+add_executable(test_audio_watchdog native/test_audio_watchdog.cpp)
+target_include_directories(test_audio_watchdog PRIVATE ${CMAKE_SOURCE_DIR}/native/host)
+add_test(NAME test_audio_watchdog COMMAND test_audio_watchdog)
+
# Texture + Framebuffer decoupling: compiles the converted classes against a
# MockGfxDevice. The harness stubs the (uncalled) stb file loader.
add_executable(test_texture_fb
diff --git a/tests/native/test_audio_watchdog.cpp b/tests/native/test_audio_watchdog.cpp
new file mode 100644
index 000000000..d75300ecf
--- /dev/null
+++ b/tests/native/test_audio_watchdog.cpp
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#include "media/audio_watchdog.hpp"
+
+#include <cstdio>
+
+static int g_failures = 0;
+#define CHECK(cond, msg) \
+ do { \
+ if (cond) std::printf("ok: %s\n", msg); \
+ else { std::printf("FAIL: %s\n", msg); ++g_failures; } \
+ } while (0)
+
+using eshost::AudioWatchdog;
+using Action = AudioWatchdog::Action;
+
+static void testHealthyDeviceIsLeftAlone() {
+ AudioWatchdog w;
+ w.want(true, 0);
+ uint64_t callbacks = 0;
+ bool acted = false;
+ for (double t = 0; t < 10000; t += 16) {
+ callbacks += 1;
+ acted |= w.tick(t, callbacks) != Action::None;
+ }
+ CHECK(!acted, "a device whose callback keeps running is never touched");
+}
+
+static void testSuspendedDeviceIsLeftAlone() {
+ AudioWatchdog w;
+ w.want(false, 0);
+ bool acted = false;
+ for (double t = 0; t < 60000; t += 16) acted |= w.tick(t, 7) != Action::None;
+ CHECK(!acted, "a suspended device is silent on purpose and never touched");
+}
+
+static void testResumeGivesTheDeviceGraceAfterABackground() {
+ AudioWatchdog w;
+ w.want(true, 0);
+ w.tick(16, 1);
+ w.want(false, 32);
+ w.want(true, 200000);
+ CHECK(w.tick(200016, 1) == Action::None, "the first frame back from a long background does not count the background as silence");
+ CHECK(w.tick(200000 + AudioWatchdog::kGraceMs - 1, 1) == Action::None, "nor does anything inside the grace");
+ CHECK(w.tick(200000 + AudioWatchdog::kGraceMs + 1, 1) == Action::Restart, "a device that never comes back after resuming is restarted");
+}
+
+static void testEscalatesToRebuildAndBacksOff() {
+ AudioWatchdog w;
+ w.want(true, 0);
+ double t = 0;
+ Action actions[6];
+ double times[6];
+ for (int i = 0; i < 6; ++i) {
+ Action a = Action::None;
+ while (a == Action::None) { t += 16; a = w.tick(t, 0); }
+ actions[i] = a;
+ times[i] = t;
+ }
+ CHECK(actions[0] == Action::Restart && actions[1] == Action::Restart, "the first two tries restart the device");
+ CHECK(actions[2] == Action::Rebuild && actions[5] == Action::Rebuild, "after that the device is rebuilt, and it keeps trying");
+ CHECK(times[2] - times[1] > times[1] - times[0], "tries space out");
+ CHECK(times[5] - times[4] <= AudioWatchdog::kMaxBackoffMs + 16, "but never further apart than the cap");
+}
+
+static void testRecoveryIsReportedOnceAndResets() {
+ AudioWatchdog w;
+ w.want(true, 0);
+ double t = 0;
+ while (w.tick(t += 16, 0) == Action::None) {}
+ CHECK(w.failures() == 1, "a try is counted");
+ w.tick(t += 16, 5);
+ CHECK(w.takeRecovered(), "callbacks resuming after a try is reported as a recovery");
+ CHECK(!w.takeRecovered(), "once");
+ CHECK(w.failures() == 0, "and the count starts over");
+}
+
+int main() {
+ testHealthyDeviceIsLeftAlone();
+ testSuspendedDeviceIsLeftAlone();
+ testResumeGivesTheDeviceGraceAfterABackground();
+ testEscalatesToRebuildAndBacksOff();
+ testRecoveryIsReportedOnceAndResets();
+ if (g_failures) { std::printf("%d FAILURE(S)\n", g_failures); return 1; }
+ std::printf("ALL AUDIO-WATCHDOG TESTS PASSED\n");
+ return 0;
+}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 74cca6582..dc2e7496c 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4120,4 +4120,6 @@ export const NOTED = {
{"note": "On a phone, a lit 3D scene costs about half as much."},
"fix(native): a render target is made on a device, so RenderTexture and a camera's renderTarget draw there":
{"note": "A render target works on a native device."},
+ "fix(native): the audio device is watched and brought back when it stops taking sound, so a game is not left silent after the background":
+ {"note": "Sound comes back when a device's audio dies on its own."},
};