M4: engine.audio — miniaudio, same narrow-shim shape as engine.physics

native/audio-native/lingua_audio.c wraps miniaudio (vendored at pinned
release 0.11.25 — dual public domain/MIT-0, confirmed from the license
statement in the file itself) the same way lingua_physics.c wraps Box3D:
ma_engine_config/ma_sound_config are large structs with optional
callbacks, so nothing but plain int/float/bool/UTF-8-path scalars crosses
the P/Invoke boundary, and handles are this shim's own array-index
handles into a fixed ma_sound table, not miniaudio's own pointer types.
Same DllImport-not-LibraryImport choice too, for the same reason: zero
AllowUnsafeBlocks needed anywhere in this plugin.

One real addition beyond mirroring the physics shim: Lingua_Audio_Init
takes a useNullBackend flag. miniaudio's null backend runs the exact same
load/decode/mix/loop pipeline against a device that discards its output —
real coverage of this shim's logic without depending on real audio
hardware being present (most CI runners have none) or making an
automated test run produce actual sound, which nobody expects. Real
gameplay (AudioPlugin) always requests the real backend; only
Engine.Audio.Tests asks for the null one.

engine.audio adds an AudioSource component (ClipPath/Volume/Loop/
PlayOnAwake) and AudioWorld, which — same shape as PhysicsWorld, same
reason: no destruction event exists to hook — diffs Query<AudioSource>()
against its own tracked set every Stage.Update, loading a clip the first
time it sees one, applying Volume/Loop changes only when they actually
changed, and unloading sounds whose GameObject is gone. IAudioService
exposes Play/Stop/IsPlaying for gameplay code to trigger a sound instead
of it only ever firing on PlayOnAwake.

5 new tests, all against the null backend, all passed after fixing one
real bug they caught: AudioWorld originally re-attempted loading (and
re-warned about) a missing clip on every single Sync call instead of
once — MissingClip_WarnsAndDoesNotThrow failed on the first run with 2
warnings instead of 1, fixed by tracking failed-load GameObjects the same
way PhysicsWorld already tracks missing-collider ones.

Full suite: 86 tests. Not yet verified: actual audible playback through a
real device — the null-backend tests prove this plugin's own logic, but
nobody has listened to real output yet. Worth doing deliberately, not as
a surprise mid-session — flagging rather than just doing it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N1qPfzq8TDCUMFMV3UwV5N

plugins/engine.audio/Engine.Audio/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("Engine.Audio.Tests")]

plugins/engine.audio/Engine.Audio/AudioPlugin.cs

@@ -0,0 +1,38 @@
+using Engine.Audio.Contracts;
+using Engine.Kernel.Plugins;
+using Engine.Kernel.Scheduling;
+using Engine.Kernel.World;
+
+namespace Engine.Audio;
+
+/// <summary>
+/// M4's audio plugin: miniaudio, over the shim in native/audio-native/ —
+/// see that file's own doc comment for why nothing but scalars and a UTF-8
+/// path string cross the P/Invoke boundary. One system, on Stage.Update
+/// (not FixedUpdate — nothing about audio is physics-timed): sync new/
+/// changed/removed AudioSources every frame.
+/// </summary>
+public sealed class AudioPlugin : IPlugin
+{
+    private AudioWorld? _world;
+
+    public void Configure(IPluginContext ctx)
+    {
+        _world = new AudioWorld(ctx.Log, useNullBackend: false);
+        ctx.Services.Provide<IAudioService>(new AudioService(_world));
+
+        ctx.Schedule.Add(Stage.Update, Sync).Reads<AudioSource>();
+
+        ctx.Log.Info("audio engine ready (miniaudio)");
+    }
+
+    public void Shutdown(IPluginContext ctx)
+    {
+        ctx.Schedule.RemoveAllFrom("engine.audio");
+        ctx.Services.Revoke<IAudioService>();
+        _world?.Dispose();
+        _world = null;
+    }
+
+    private void Sync(IWorld world) => _world!.Sync(world);
+}

plugins/engine.audio/Engine.Audio/AudioService.cs

@@ -0,0 +1,13 @@
+using Engine.Audio.Contracts;
+using Engine.Kernel.World;
+
+namespace Engine.Audio;
+
+internal sealed class AudioService(AudioWorld world) : IAudioService
+{
+    public void Play(GameObject go) => world.Play(go);
+
+    public void Stop(GameObject go) => world.Stop(go);
+
+    public bool IsPlaying(GameObject go) => world.IsPlaying(go);
+}

plugins/engine.audio/Engine.Audio/AudioWorld.cs

@@ -0,0 +1,111 @@
+using Engine.Audio.Contracts;
+using Engine.Kernel.Diagnostics;
+using Engine.Kernel.World;
+
+namespace Engine.Audio;
+
+/// <summary>
+/// Owns the one native miniaudio engine this plugin creates, and the
+/// GameObject &lt;-&gt; loaded-sound handle mapping. <see cref="Sync"/> loads a
+/// clip the first time it sees a GameObject's AudioSource, applies
+/// Volume/Loop changes without re-touching the native side when nothing
+/// changed, fires PlayOnAwake exactly once, and — same no-destruction-event
+/// problem PhysicsWorld has — unloads sounds for GameObjects that no
+/// longer have an AudioSource.
+///
+/// useNullBackend exists for exactly one reason: Engine.Audio.Tests uses
+/// it. Real gameplay always gets a real device (see AudioPlugin) — nothing
+/// about the null backend belongs in a shipped build's own choice.
+/// </summary>
+internal sealed class AudioWorld : IDisposable
+{
+    private readonly ILogger _log;
+    private readonly Dictionary<GameObject, int> _handles = [];
+    private readonly Dictionary<GameObject, (float Volume, bool Loop)> _lastSynced = [];
+    private readonly HashSet<GameObject> _warnedFailedToLoad = [];
+
+    public AudioWorld(ILogger log, bool useNullBackend)
+    {
+        _log = log;
+
+        if (Native.Lingua_Audio_Init(useNullBackend ? 1 : 0) == 0)
+            _log.Error("Failed to initialize the audio engine — no sounds will play.");
+    }
+
+    public void Sync(IWorld world)
+    {
+        var live = new HashSet<GameObject>();
+
+        foreach (var go in world.Query<AudioSource>())
+        {
+            live.Add(go);
+            var src = go.GetComponent<AudioSource>()!;
+
+            if (_warnedFailedToLoad.Contains(go))
+                continue;
+
+            if (!_handles.TryGetValue(go, out var handle))
+            {
+                handle = Native.Lingua_Audio_LoadSound(src.ClipPath);
+                if (handle < 0)
+                {
+                    _log.Warn($"'{go.Name}' AudioSource failed to load '{src.ClipPath}'.");
+                    _warnedFailedToLoad.Add(go);
+                    continue;
+                }
+
+                _handles[go] = handle;
+                Native.Lingua_Audio_SetVolume(handle, src.Volume);
+                Native.Lingua_Audio_SetLooping(handle, src.Loop);
+                _lastSynced[go] = (src.Volume, src.Loop);
+
+                if (src.PlayOnAwake)
+                    Native.Lingua_Audio_Play(handle);
+
+                continue;
+            }
+
+            var last = _lastSynced[go];
+            if (last.Volume != src.Volume)
+                Native.Lingua_Audio_SetVolume(handle, src.Volume);
+            if (last.Loop != src.Loop)
+                Native.Lingua_Audio_SetLooping(handle, src.Loop);
+
+            _lastSynced[go] = (src.Volume, src.Loop);
+        }
+
+        foreach (var stale in _handles.Keys.Where(go => !live.Contains(go)).ToList())
+        {
+            Native.Lingua_Audio_UnloadSound(_handles[stale]);
+            _handles.Remove(stale);
+            _lastSynced.Remove(stale);
+        }
+
+        _warnedFailedToLoad.RemoveWhere(go => !live.Contains(go));
+    }
+
+    public void Play(GameObject go)
+    {
+        if (_handles.TryGetValue(go, out var handle))
+            Native.Lingua_Audio_Play(handle);
+    }
+
+    public void Stop(GameObject go)
+    {
+        if (_handles.TryGetValue(go, out var handle))
+            Native.Lingua_Audio_Stop(handle);
+    }
+
+    public bool IsPlaying(GameObject go) =>
+        _handles.TryGetValue(go, out var handle) && Native.Lingua_Audio_IsPlaying(handle);
+
+    public void Dispose()
+    {
+        foreach (var handle in _handles.Values)
+            Native.Lingua_Audio_UnloadSound(handle);
+
+        _handles.Clear();
+        _lastSynced.Clear();
+        Native.Lingua_Audio_Shutdown();
+    }
+}

plugins/engine.audio/Engine.Audio/Engine.Audio.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <EnableDynamicLoading>true</EnableDynamicLoading>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Same reasoning as engine.physics' own native Content item: default
+         DllImport probing already checks the calling assembly's directory,
+         so this is copied straight alongside Engine.Audio.dll rather than
+         through a runtimes/<rid>/native/ path. -->
+    <Content Include="native/liblingua_audio.so">
+      <Link>liblingua_audio.so</Link>
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Engine.Kernel\Engine.Kernel.csproj" />
+    <ProjectReference Include="..\Engine.Audio.Contracts\Engine.Audio.Contracts.csproj" />
+  </ItemGroup>
+
+</Project>

plugins/engine.audio/Engine.Audio/Native.cs

@@ -0,0 +1,43 @@
+using System.Runtime.InteropServices;
+
+namespace Engine.Audio;
+
+/// <summary>
+/// Matches native/audio-native/lingua_audio.c's exports one-to-one. Same
+/// choice as engine.physics' Native.cs: classic DllImport, not
+/// LibraryImport, so no AllowUnsafeBlocks is needed anywhere in this
+/// plugin — every parameter here is a plain scalar or a UTF-8 string,
+/// nothing that needs unsafe marshalling code.
+/// </summary>
+internal static class Native
+{
+    private const string Lib = "lingua_audio";
+
+    [DllImport(Lib)]
+    public static extern int Lingua_Audio_Init(int useNullBackend);
+
+    [DllImport(Lib)]
+    public static extern void Lingua_Audio_Shutdown();
+
+    [DllImport(Lib)]
+    public static extern int Lingua_Audio_LoadSound([MarshalAs(UnmanagedType.LPUTF8Str)] string path);
+
+    [DllImport(Lib)]
+    public static extern void Lingua_Audio_UnloadSound(int handle);
+
+    [DllImport(Lib)]
+    public static extern void Lingua_Audio_Play(int handle);
+
+    [DllImport(Lib)]
+    public static extern void Lingua_Audio_Stop(int handle);
+
+    [DllImport(Lib)]
+    public static extern void Lingua_Audio_SetVolume(int handle, float volume);
+
+    [DllImport(Lib)]
+    public static extern void Lingua_Audio_SetLooping(int handle, [MarshalAs(UnmanagedType.U1)] bool loop);
+
+    [DllImport(Lib)]
+    [return: MarshalAs(UnmanagedType.U1)]
+    public static extern bool Lingua_Audio_IsPlaying(int handle);
+}