@bornengine/engine 0.4.16

package/native/shared/src/audio/spsc.rs

@@ -0,0 +1,156 @@
+//! Fixed-capacity lock-free single-producer/single-consumer ring buffer.
+//!
+//! Purpose-built for the audio command queue: the main (FFI) thread is the
+//! only producer, the platform audio thread the only consumer, and the
+//! consumer must never block, allocate, or take a lock — an audio callback
+//! that waits on a mutex held across a frame hitch produces an audible
+//! glitch, and a poisoned lock would kill sound for the rest of the
+//! session (both observed failure modes of the old shared-mutable mixer).
+//!
+//! Standard two-counter ring: `tail` is written only by the producer,
+//! `head` only by the consumer; each side reads the other's counter with
+//! Acquire and publishes its own with Release. One slot is sacrificed to
+//! distinguish full from empty.
+
+use std::cell::UnsafeCell;
+use std::mem::MaybeUninit;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+
+struct Ring<T> {
+    buf: Box<[UnsafeCell<MaybeUninit<T>>]>,
+    /// next slot to read; owned by the consumer
+    head: AtomicUsize,
+    /// next slot to write; owned by the producer
+    tail: AtomicUsize,
+}
+
+// The ring itself is shared between exactly two threads with disjoint
+// roles; the unsafe impls are sound because Producer and Consumer are
+// each !Clone and only touch their own counter + the slots their
+// protocol entitles them to.
+unsafe impl<T: Send> Send for Ring<T> {}
+unsafe impl<T: Send> Sync for Ring<T> {}
+
+impl<T> Drop for Ring<T> {
+    fn drop(&mut self) {
+        // By the time the last Arc drops we have exclusive access; drain
+        // any unconsumed items so their destructors (Arc<SoundData>!) run.
+        let mut head = *self.head.get_mut();
+        let tail = *self.tail.get_mut();
+        while head != tail {
+            unsafe { (*self.buf[head].get()).assume_init_drop() };
+            head = (head + 1) % self.buf.len();
+        }
+    }
+}
+
+pub struct Producer<T> {
+    ring: Arc<Ring<T>>,
+}
+
+pub struct Consumer<T> {
+    ring: Arc<Ring<T>>,
+}
+
+pub fn channel<T: Send>(capacity: usize) -> (Producer<T>, Consumer<T>) {
+    assert!(capacity >= 2);
+    let buf: Box<[UnsafeCell<MaybeUninit<T>>]> = (0..capacity)
+        .map(|_| UnsafeCell::new(MaybeUninit::uninit()))
+        .collect();
+    let ring = Arc::new(Ring {
+        buf,
+        head: AtomicUsize::new(0),
+        tail: AtomicUsize::new(0),
+    });
+    (Producer { ring: ring.clone() }, Consumer { ring })
+}
+
+impl<T> Producer<T> {
+    /// Push an item; returns it back if the ring is full (the caller
+    /// decides whether dropping the command is acceptable).
+    pub fn push(&mut self, item: T) -> Result<(), T> {
+        let ring = &*self.ring;
+        let tail = ring.tail.load(Ordering::Relaxed);
+        let next = (tail + 1) % ring.buf.len();
+        if next == ring.head.load(Ordering::Acquire) {
+            return Err(item); // full
+        }
+        unsafe { (*ring.buf[tail].get()).write(item) };
+        ring.tail.store(next, Ordering::Release);
+        Ok(())
+    }
+}
+
+impl<T> Consumer<T> {
+    /// Pop the oldest item, if any. Wait-free; safe to call from a
+    /// real-time audio callback.
+    pub fn pop(&mut self) -> Option<T> {
+        let ring = &*self.ring;
+        let head = ring.head.load(Ordering::Relaxed);
+        if head == ring.tail.load(Ordering::Acquire) {
+            return None; // empty
+        }
+        let item = unsafe { (*ring.buf[head].get()).assume_init_read() };
+        ring.head.store((head + 1) % ring.buf.len(), Ordering::Release);
+        Some(item)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn push_pop_order() {
+        let (mut tx, mut rx) = channel::<u32>(4);
+        assert!(tx.push(1).is_ok());
+        assert!(tx.push(2).is_ok());
+        assert!(tx.push(3).is_ok()); // capacity 4 → 3 usable slots
+        assert!(tx.push(4).is_err()); // full
+        assert_eq!(rx.pop(), Some(1));
+        assert_eq!(rx.pop(), Some(2));
+        assert!(tx.push(4).is_ok());
+        assert_eq!(rx.pop(), Some(3));
+        assert_eq!(rx.pop(), Some(4));
+        assert_eq!(rx.pop(), None);
+    }
+
+    #[test]
+    fn cross_thread_stream() {
+        let (mut tx, mut rx) = channel::<u64>(64);
+        let producer = std::thread::spawn(move || {
+            for i in 0..100_000u64 {
+                loop {
+                    match tx.push(i) {
+                        Ok(()) => break,
+                        Err(_) => std::hint::spin_loop(),
+                    }
+                }
+            }
+        });
+        let mut expected = 0u64;
+        while expected < 100_000 {
+            if let Some(v) = rx.pop() {
+                assert_eq!(v, expected, "out-of-order or corrupted item");
+                expected += 1;
+            } else {
+                std::hint::spin_loop();
+            }
+        }
+        producer.join().unwrap();
+    }
+
+    #[test]
+    fn drop_drains_unconsumed_items() {
+        let flag = Arc::new(());
+        let (mut tx, rx) = channel::<Arc<()>>(8);
+        for _ in 0..5 {
+            tx.push(flag.clone()).unwrap();
+        }
+        assert_eq!(Arc::strong_count(&flag), 6);
+        drop(tx);
+        drop(rx);
+        assert_eq!(Arc::strong_count(&flag), 1, "ring leaked queued items");
+    }
+}

package/native/shared/src/audio/stream.rs

@@ -0,0 +1,226 @@
+//! Streamed music decode: a background worker decodes OGG/MP3 into PCM
+//! chunks and feeds them over the lock-free SPSC ring; the audio thread's
+//! MusicVoice consumes chunks instead of holding the whole decoded track.
+//!
+//! Memory math that motivates this: a 5-minute 44.1 kHz stereo track is
+//! ~57 MB as f32 PCM but ~5 MB as OGG/MP3 bytes. Streaming keeps only the
+//! compressed bytes (shared `Arc`) plus ~1.5 s of decoded ring buffer
+//! resident. WAV stays full-decode (it IS PCM — nothing to win), and so
+//! does wasm32 (no threads without COOP/COEP; the full-decode path is the
+//! documented fallback there).
+//!
+//! Worker lifecycle: spawned per play_music on a streamed track, killed
+//! by `stop` (AtomicBool) when the track is stopped/replaced/unloaded.
+//! Looping restarts the decoder from byte 0 inside the worker, so a loop
+//! seam never underruns the ring.
+
+use super::spsc::Consumer;
+#[cfg(not(target_arch = "wasm32"))]
+use super::spsc::{self, Producer};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+/// Compressed source format of a streamed track.
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum StreamKind {
+    Ogg,
+    #[cfg(feature = "mp3")]
+    Mp3,
+}
+
+/// One message from the decode worker to the render-side voice.
+pub enum StreamMsg {
+    /// Interleaved f32 PCM at the track's native sample rate/channels.
+    Chunk(Vec<f32>),
+    /// Non-looping track fully delivered.
+    End,
+}
+
+/// ~0.37 s of stereo 44.1 kHz per chunk; the ring holds four — enough to
+/// ride out >1 s of decoder starvation before an audible underrun.
+#[cfg(not(target_arch = "wasm32"))]
+const CHUNK_SAMPLES: usize = 32 * 1024;
+#[cfg(not(target_arch = "wasm32"))]
+const RING_CHUNKS: usize = 4;
+
+/// Render-side handle to a running stream.
+pub struct StreamConsumer {
+    pub rx: Consumer<StreamMsg>,
+    /// Set to stop the worker (dropped voice, stop_music, engine teardown).
+    pub stop: Arc<AtomicBool>,
+}
+
+impl Drop for StreamConsumer {
+    fn drop(&mut self) {
+        self.stop.store(true, Ordering::Relaxed);
+    }
+}
+
+/// Probe an OGG/MP3 byte buffer for (sample_rate, channels) without
+/// decoding the whole track. Returns None if the data doesn't parse.
+pub fn probe(kind: StreamKind, bytes: &[u8]) -> Option<(u32, u16)> {
+    match kind {
+        StreamKind::Ogg => {
+            let reader =
+                lewton::inside_ogg::OggStreamReader::new(std::io::Cursor::new(bytes)).ok()?;
+            Some((
+                reader.ident_hdr.audio_sample_rate,
+                reader.ident_hdr.audio_channels as u16,
+            ))
+        }
+        #[cfg(feature = "mp3")]
+        StreamKind::Mp3 => {
+            let mut decoder = minimp3::Decoder::new(std::io::Cursor::new(bytes));
+            let frame = decoder.next_frame().ok()?;
+            Some((frame.sample_rate as u32, frame.channels as u16))
+        }
+    }
+}
+
+/// Spawn the decode worker for one playback of a streamed track.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn start(kind: StreamKind, bytes: Arc<Vec<u8>>, looping: bool) -> StreamConsumer {
+    let (tx, rx) = spsc::channel(RING_CHUNKS + 1);
+    let stop = Arc::new(AtomicBool::new(false));
+    let stop_worker = stop.clone();
+    std::thread::Builder::new()
+        .name("bloom-music-decode".into())
+        .spawn(move || run_worker(kind, &bytes, looping, tx, &stop_worker))
+        .expect("spawn music decode worker");
+    StreamConsumer { rx, stop }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+fn run_worker(
+    kind: StreamKind,
+    bytes: &[u8],
+    looping: bool,
+    mut tx: Producer<StreamMsg>,
+    stop: &AtomicBool,
+) {
+    // Push with backpressure: the ring fills ~1.5s ahead, then we sleep.
+    // 20ms poll keeps the worker essentially idle while the ring is full.
+    let mut push = |msg: StreamMsg| -> bool {
+        let mut m = msg;
+        loop {
+            if stop.load(Ordering::Relaxed) {
+                return false;
+            }
+            match tx.push(m) {
+                Ok(()) => return true,
+                Err(back) => {
+                    m = back;
+                    std::thread::sleep(std::time::Duration::from_millis(20));
+                }
+            }
+        }
+    };
+
+    loop {
+        let completed = match kind {
+            StreamKind::Ogg => decode_ogg(bytes, stop, &mut push),
+            #[cfg(feature = "mp3")]
+            StreamKind::Mp3 => decode_mp3(bytes, stop, &mut push),
+        };
+        if !completed || !looping {
+            break;
+        }
+        // looping: restart the decoder from the top
+    }
+    let _ = push(StreamMsg::End);
+}
+
+/// Decode one full pass of the track, pushing chunks. Returns false if
+/// stopped early (stop flag / consumer gone).
+#[cfg(not(target_arch = "wasm32"))]
+fn decode_ogg(bytes: &[u8], stop: &AtomicBool, push: &mut dyn FnMut(StreamMsg) -> bool) -> bool {
+    let Ok(mut reader) = lewton::inside_ogg::OggStreamReader::new(std::io::Cursor::new(bytes))
+    else {
+        return false;
+    };
+    let mut chunk: Vec<f32> = Vec::with_capacity(CHUNK_SAMPLES);
+    while let Ok(Some(packet)) = reader.read_dec_packet_itl() {
+        if stop.load(Ordering::Relaxed) {
+            return false;
+        }
+        for &s in &packet {
+            chunk.push(s as f32 / 32768.0);
+        }
+        if chunk.len() >= CHUNK_SAMPLES {
+            let full = std::mem::replace(&mut chunk, Vec::with_capacity(CHUNK_SAMPLES));
+            if !push(StreamMsg::Chunk(full)) {
+                return false;
+            }
+        }
+    }
+    if !chunk.is_empty() && !push(StreamMsg::Chunk(chunk)) {
+        return false;
+    }
+    true
+}
+
+#[cfg(all(feature = "mp3", not(target_arch = "wasm32")))]
+fn decode_mp3(bytes: &[u8], stop: &AtomicBool, push: &mut dyn FnMut(StreamMsg) -> bool) -> bool {
+    let mut decoder = minimp3::Decoder::new(std::io::Cursor::new(bytes));
+    let mut chunk: Vec<f32> = Vec::with_capacity(CHUNK_SAMPLES);
+    loop {
+        if stop.load(Ordering::Relaxed) {
+            return false;
+        }
+        match decoder.next_frame() {
+            Ok(frame) => {
+                for &s in &frame.data {
+                    chunk.push(s as f32 / 32768.0);
+                }
+                if chunk.len() >= CHUNK_SAMPLES {
+                    let full = std::mem::replace(&mut chunk, Vec::with_capacity(CHUNK_SAMPLES));
+                    if !push(StreamMsg::Chunk(full)) {
+                        return false;
+                    }
+                }
+            }
+            Err(minimp3::Error::Eof) => break,
+            Err(_) => break,
+        }
+    }
+    if !chunk.is_empty() && !push(StreamMsg::Chunk(chunk)) {
+        return false;
+    }
+    true
+}
+
+#[cfg(test)]
+#[cfg(not(target_arch = "wasm32"))]
+mod tests {
+    use super::*;
+
+    /// Tiny synthetic WAV→OGG isn't practical here; instead exercise the
+    /// worker plumbing with MP3 when available, and always exercise the
+    /// stop/backpressure logic with a hand-rolled pusher.
+    #[test]
+    fn stop_flag_terminates_backpressure_wait() {
+        let (tx, _rx) = spsc::channel::<StreamMsg>(2);
+        let stop = Arc::new(AtomicBool::new(false));
+        let stop2 = stop.clone();
+        let h = std::thread::spawn(move || {
+            let mut tx = tx;
+            // fill the ring, then keep pushing — blocks on backpressure
+            let mut pushed = 0;
+            loop {
+                match tx.push(StreamMsg::Chunk(vec![0.0; 4])) {
+                    Ok(()) => pushed += 1,
+                    Err(_) => {
+                        if stop2.load(Ordering::Relaxed) {
+                            return pushed;
+                        }
+                        std::thread::sleep(std::time::Duration::from_millis(5));
+                    }
+                }
+            }
+        });
+        std::thread::sleep(std::time::Duration::from_millis(30));
+        stop.store(true, Ordering::Relaxed);
+        let pushed = h.join().unwrap();
+        assert_eq!(pushed, 1, "ring of capacity 2 holds exactly 1 item");
+    }
+}

package/native/shared/src/custom_shaders.rs

@@ -0,0 +1,104 @@
+//! Custom WGSL shaders for Pascal Editor effects.
+//!
+//! These are hand-ported equivalents of the Three.js TSL (Texture Shading Language)
+//! node materials used in the Pascal Editor:
+//! - Wall cutaway dot pattern
+//! - Zone gradient
+//! - Item preview shimmer
+//!
+//! In the browser, these are defined as JavaScript function calls (TSL nodes) that
+//! compile to WGSL at runtime. Since we compile natively, we write the WGSL directly.
+
+/// Wall cutaway dot pattern — shows dots that fade with height when a wall
+/// is in "cutaway" mode. Replaces the TSL `Fn(() => { ... fract ... step ... })`.
+pub const WALL_CUTAWAY_SHADER: &str = "
+struct CutawayParams {
+    dot_scale: vec4<f32>,      // [scale, dot_size, fade_height, opacity]
+    base_color: vec4<f32>,     // rgba
+};
+
+@group(0) @binding(0) var<uniform> params: CutawayParams;
+
+struct VertexOutput {
+    @builtin(position) clip_position: vec4<f32>,
+    @location(0) local_pos: vec3<f32>,
+    @location(1) color: vec4<f32>,
+};
+
+@fragment
+fn fs_wall_cutaway(in: VertexOutput) -> @location(0) vec4<f32> {
+    let scale = params.dot_scale.x;
+    let dot_size = params.dot_scale.y;
+    let fade_height = params.dot_scale.z;
+
+    // Create repeating dot grid
+    let uv = vec2<f32>(in.local_pos.x, in.local_pos.y) / scale;
+    let grid_uv = fract(uv);
+    let dist = length(grid_uv - vec2<f32>(0.5));
+    let dots = step(dist, dot_size * 0.5);
+
+    // Vertical fade (transparent near bottom, opaque at top)
+    let y_fade = 1.0 - smoothstep(0.0, fade_height, in.local_pos.y);
+
+    let alpha = dots * y_fade * params.dot_scale.w;
+    if (alpha < 0.01) { discard; }
+
+    return vec4<f32>(params.base_color.rgb * in.color.rgb, alpha);
+}
+";
+
+/// Zone gradient — vertical gradient for zone visualization walls.
+/// Replaces the TSL `uv().y → mul(opacity)` with uniform.
+pub const ZONE_GRADIENT_SHADER: &str = "
+struct ZoneParams {
+    base_color: vec4<f32>,    // rgba
+    opacity: vec4<f32>,       // [max_opacity, 0, 0, 0]
+};
+
+@group(0) @binding(0) var<uniform> zone_params: ZoneParams;
+
+struct VertexOutput {
+    @builtin(position) clip_position: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+    @location(1) color: vec4<f32>,
+};
+
+@fragment
+fn fs_zone_gradient(in: VertexOutput) -> @location(0) vec4<f32> {
+    // Gradient: fully opaque at bottom, transparent at top
+    let gradient_t = in.uv.y;
+    let alpha = zone_params.opacity.x * (1.0 - gradient_t) * 0.6;
+    return vec4<f32>(zone_params.base_color.rgb, alpha);
+}
+";
+
+/// Item preview shimmer — animated shimmer effect for item placement preview.
+/// Replaces the TSL `positionLocal.y + time → fract → smoothstep`.
+pub const PREVIEW_SHIMMER_SHADER: &str = "
+struct ShimmerParams {
+    time: vec4<f32>,          // [time, speed, 0, 0]
+    base_color: vec4<f32>,    // rgba
+};
+
+@group(0) @binding(0) var<uniform> shimmer_params: ShimmerParams;
+
+struct VertexOutput {
+    @builtin(position) clip_position: vec4<f32>,
+    @location(0) local_pos: vec3<f32>,
+    @location(1) color: vec4<f32>,
+};
+
+@fragment
+fn fs_preview_shimmer(in: VertexOutput) -> @location(0) vec4<f32> {
+    let time = shimmer_params.time.x;
+    let speed = shimmer_params.time.y;
+
+    // Scrolling shimmer band
+    let shimmer_y = fract((in.local_pos.y + time * speed) * 10.0);
+    let shimmer = smoothstep(0.0, 0.1, shimmer_y) * smoothstep(0.3, 0.2, shimmer_y);
+
+    let base = shimmer_params.base_color;
+    let brightness = 1.0 + shimmer * 0.3;
+    return vec4<f32>(base.rgb * brightness, base.a * 0.7);
+}
+";