@bornengine/engine 0.4.16

package/native/shared/src/staging.rs

@@ -0,0 +1,102 @@
+use std::sync::{Mutex, OnceLock};
+#[cfg(feature = "models3d")]
+use crate::models::ModelData;
+use crate::audio::SoundData;
+
+pub struct StagedTexture {
+    pub data: Vec<u8>,
+    pub width: u32,
+    pub height: u32,
+    /// Normal maps need `register_texture_kind`'s linear-space + LEADR mip
+    /// path at commit time; registering them like albedo (sRGB) visibly
+    /// flattens the shading. Set by `load_gltf_staged` from the material's
+    /// `normal_texture` references, mirroring `load_gltf_with_textures`.
+    pub is_normal: bool,
+}
+
+#[cfg(feature = "models3d")]
+pub struct StagedModel {
+    pub model: ModelData,
+    pub textures: Vec<StagedTexture>,
+}
+
+// Thread-safe staging stores using Mutex<Vec<Option<T>>>.
+// The lock is only held during insert/remove (microseconds), not during decode.
+
+fn texture_store() -> &'static Mutex<Vec<Option<StagedTexture>>> {
+    static INSTANCE: OnceLock<Mutex<Vec<Option<StagedTexture>>>> = OnceLock::new();
+    INSTANCE.get_or_init(|| Mutex::new(Vec::new()))
+}
+
+#[cfg(feature = "models3d")]
+fn model_store() -> &'static Mutex<Vec<Option<StagedModel>>> {
+    static INSTANCE: OnceLock<Mutex<Vec<Option<StagedModel>>>> = OnceLock::new();
+    INSTANCE.get_or_init(|| Mutex::new(Vec::new()))
+}
+
+fn sound_store() -> &'static Mutex<Vec<Option<SoundData>>> {
+    static INSTANCE: OnceLock<Mutex<Vec<Option<SoundData>>>> = OnceLock::new();
+    INSTANCE.get_or_init(|| Mutex::new(Vec::new()))
+}
+
+fn stage_into<T>(store: &Mutex<Vec<Option<T>>>, item: T) -> f64 {
+    let mut vec = store.lock().unwrap();
+    // Reuse freed slots
+    for (i, slot) in vec.iter_mut().enumerate() {
+        if slot.is_none() {
+            *slot = Some(item);
+            return (i + 1) as f64;
+        }
+    }
+    vec.push(Some(item));
+    vec.len() as f64
+}
+
+fn take_from<T>(store: &Mutex<Vec<Option<T>>>, handle: f64) -> Option<T> {
+    let idx = handle as usize;
+    if idx == 0 { return None; }
+    let mut vec = store.lock().unwrap();
+    if idx > vec.len() { return None; }
+    vec[idx - 1].take()
+}
+
+// Public API
+
+/// Decode image bytes (PNG/JPEG/etc) and stage the result. Thread-safe.
+pub fn decode_and_stage_texture(file_data: &[u8]) -> f64 {
+    let img = match image::load_from_memory(file_data) {
+        Ok(img) => img.to_rgba8(),
+        Err(_) => return 0.0,
+    };
+    let width = img.width();
+    let height = img.height();
+    // Standalone staged textures are albedo-class; nothing routes a normal
+    // map through this path (models carry theirs inside StagedModel).
+    stage_texture(StagedTexture { data: img.into_raw(), width, height, is_normal: false })
+}
+
+pub fn stage_texture(tex: StagedTexture) -> f64 {
+    stage_into(texture_store(), tex)
+}
+
+pub fn take_texture(handle: f64) -> Option<StagedTexture> {
+    take_from(texture_store(), handle)
+}
+
+#[cfg(feature = "models3d")]
+pub fn stage_model(model: StagedModel) -> f64 {
+    stage_into(model_store(), model)
+}
+
+#[cfg(feature = "models3d")]
+pub fn take_model(handle: f64) -> Option<StagedModel> {
+    take_from(model_store(), handle)
+}
+
+pub fn stage_sound(sound: SoundData) -> f64 {
+    stage_into(sound_store(), sound)
+}
+
+pub fn take_sound(handle: f64) -> Option<SoundData> {
+    take_from(sound_store(), handle)
+}

package/native/shared/src/string_header.rs

@@ -0,0 +1,266 @@
+//! Perry string ABI: the header layout strings carry across the FFI.
+//!
+//! This mirrors `perry_runtime::string::StringHeader` (see
+//! `perry/crates/perry-runtime/src/string/mod.rs`) — defined locally so the
+//! engine doesn't pull the whole perry-runtime crate in as a dependency.
+//!
+//! ## Upgrade protocol
+//!
+//! Perry owns this layout and has changed it before (0.5.18 added `flags`;
+//! engines built against the old 16-byte header read a 4-byte garbage
+//! prefix on every string). There is no version symbol exported by the
+//! Perry runtime to handshake against, so the defenses are:
+//!
+//!   1. Compile-time size/offset assertions below — any local edit that
+//!      diverges from the documented layout fails the build.
+//!   2. [`header_looks_valid`] — invariant checks on every incoming
+//!      header. A Perry-side layout change makes these fire on the first
+//!      string the engine receives (typically the window title in
+//!      `bloom_init_window`), turning silent corruption into a loud
+//!      log-once diagnostic.
+//!   3. Checked UTF-8 conversion — a wrong `byte_len` can no longer cause
+//!      undefined behavior, only an empty string + diagnostic.
+//!
+//! When bumping Perry across a runtime-ABI change: update the struct,
+//! the assertions, and the doc reference above in the same commit.
+
+/// Header for heap-allocated Perry strings. UTF-8 payload follows
+/// immediately after the header.
+#[repr(C)]
+pub struct StringHeader {
+    /// Length in UTF-16 code units (JS `.length` semantics). At offset 0
+    /// for Perry's inline codegen.
+    pub utf16_len: u32,
+    /// Length in UTF-8 bytes.
+    pub byte_len: u32,
+    /// Capacity in bytes (allocated space for data).
+    pub capacity: u32,
+    /// Reference hint: 0=shared, 1=unique (in-place append OK).
+    pub refcount: u32,
+    /// Bit flags (STRING_FLAG_HAS_LONE_SURROGATES = 1). Added in Perry
+    /// 0.5.18.
+    pub flags: u32,
+}
+
+// Layout is an ABI contract — fail the build if the struct drifts from the
+// documented Perry layout.
+const _: () = {
+    assert!(std::mem::size_of::<StringHeader>() == 20);
+    assert!(std::mem::offset_of!(StringHeader, utf16_len) == 0);
+    assert!(std::mem::offset_of!(StringHeader, byte_len) == 4);
+    assert!(std::mem::offset_of!(StringHeader, capacity) == 8);
+    assert!(std::mem::offset_of!(StringHeader, refcount) == 12);
+    assert!(std::mem::offset_of!(StringHeader, flags) == 16);
+};
+
+/// All flag bits Perry currently defines.
+const KNOWN_FLAGS: u32 = 1; // STRING_FLAG_HAS_LONE_SURROGATES
+
+/// Sanity-check a header against invariants that hold for every string the
+/// current Perry runtime produces. A failed check means either a corrupt
+/// pointer or — the case this exists for — a Perry-side layout change
+/// shifting which u32 lands in which field.
+fn header_looks_valid(h: &StringHeader) -> bool {
+    h.byte_len <= h.capacity
+        && h.capacity < (1 << 31)
+        // utf16 length is never larger than the utf8 byte length
+        && h.utf16_len <= h.byte_len
+        && (h.flags & !KNOWN_FLAGS) == 0
+}
+
+fn abi_mismatch_warn_once(what: &str) {
+    use std::sync::atomic::{AtomicBool, Ordering};
+    static WARNED: AtomicBool = AtomicBool::new(false);
+    if !WARNED.swap(true, Ordering::Relaxed) {
+        crate::ffi::log_error(&format!(
+            "bloom: incoming Perry string failed ABI validation ({what}). \
+             This usually means the Perry runtime's StringHeader layout \
+             changed — see native/shared/src/string_header.rs for the \
+             upgrade protocol. Returning empty strings instead of reading \
+             garbage; further occurrences are suppressed."
+        ));
+    }
+}
+
+/// Extract a `&str` from a `*const StringHeader` pointer (Perry string
+/// format).
+///
+/// The returned slice borrows Perry-owned memory that is only guaranteed
+/// to live for the duration of the FFI call — copy it (`to_string`) before
+/// stashing it anywhere. The `'static` lifetime is a legacy artifact of
+/// the FFI signatures, not a promise.
+///
+/// Never causes undefined behavior: null/garbage pointers, implausible
+/// headers, and invalid UTF-8 all yield `""` plus a one-time diagnostic.
+/// Like [`str_from_header`], but says whether it FAILED rather than papering over it
+/// with an empty string.
+///
+/// The distinction is not academic. `bloom_write_file` used `str_from_header`, got
+/// `""` back when a string failed ABI validation, wrote a ZERO-BYTE FILE, and
+/// returned SUCCESS. The editor's save path therefore destroyed every world it
+/// saved and reported that it had saved it. An empty string and a failed string are
+/// not the same thing, and any FFI that *persists* its input has to know which it
+/// is holding.
+pub fn try_str_from_header(ptr: *const u8) -> Option<&'static str> {
+    if ptr.is_null() || (ptr as usize) < 0x1000 {
+        return Some("");
+    }
+    unsafe {
+        let header = &*(ptr as *const StringHeader);
+        if !header_looks_valid(header) {
+            abi_mismatch_warn_once("header invariants violated");
+            return None;
+        }
+        let len = header.byte_len as usize;
+        let data = ptr.add(std::mem::size_of::<StringHeader>());
+        match std::str::from_utf8(std::slice::from_raw_parts(data, len)) {
+            Ok(s) => Some(s),
+            Err(_) => {
+                abi_mismatch_warn_once("payload is not UTF-8");
+                None
+            }
+        }
+    }
+}
+
+pub fn str_from_header(ptr: *const u8) -> &'static str {
+    if ptr.is_null() || (ptr as usize) < 0x1000 {
+        return "";
+    }
+    unsafe {
+        let header = &*(ptr as *const StringHeader);
+        if !header_looks_valid(header) {
+            abi_mismatch_warn_once("header invariants violated");
+            return "";
+        }
+        let len = header.byte_len as usize;
+        let data = ptr.add(std::mem::size_of::<StringHeader>());
+        match std::str::from_utf8(std::slice::from_raw_parts(data, len)) {
+            Ok(s) => s,
+            Err(_) => {
+                abi_mismatch_warn_once("payload is not UTF-8");
+                ""
+            }
+        }
+    }
+}
+
+/// Allocate a Perry heap string suitable for returning across the FFI
+/// boundary (declared as `returns: "string"` in package.json).
+///
+/// Older engine code allocated the 12-byte Perry 0.4.x header by hand and
+/// Perry's 0.5.x runtime read 8 bytes into the payload. Always go through
+/// this helper — the layout comes from the `StringHeader` type, which the
+/// compile-time assertions above pin to the documented ABI.
+/// EN-020 — Perry's string scanners (`split`, `indexOf`, …) step
+/// word-at-a-time and may read up to a word past `byte_len`. With an
+/// exactly-sized allocation that lands flush against an unmapped page,
+/// that overread is an access violation (observed 3/3 in the shooter as
+/// `perry_fn_…getProfilerOverlay` / `…getProfilerFrameHistory`, faulting
+/// reads at page ends; historical EN-020 signature `main.exe+0xe8e5`,
+/// read at `0x…FFF8`). Every string this function returns is scanned by
+/// Perry, so keep a zeroed tail pad behind the payload — `capacity`
+/// still reports `byte_len`, so Perry never writes into the pad.
+const TAIL_PAD: usize = 16;
+
+pub fn alloc_perry_string(s: &str) -> *const u8 {
+    let bytes = s.as_bytes();
+    let byte_len = bytes.len();
+    // ASCII fast path: utf16_len == byte_len when every byte is < 0x80.
+    let utf16_len = if bytes.iter().all(|&b| b < 0x80) {
+        byte_len
+    } else {
+        s.encode_utf16().count()
+    };
+    let total = std::mem::size_of::<StringHeader>() + byte_len + TAIL_PAD;
+    let layout = std::alloc::Layout::from_size_align(total, 4).unwrap();
+    unsafe {
+        let ptr = std::alloc::alloc(layout);
+        if ptr.is_null() {
+            return std::ptr::null();
+        }
+        (ptr as *mut StringHeader).write(StringHeader {
+            utf16_len: utf16_len as u32,
+            byte_len: byte_len as u32,
+            capacity: byte_len as u32,
+            refcount: 1, // unique
+            flags: 0,
+        });
+        std::ptr::copy_nonoverlapping(
+            bytes.as_ptr(),
+            ptr.add(std::mem::size_of::<StringHeader>()),
+            byte_len,
+        );
+        std::ptr::write_bytes(
+            ptr.add(std::mem::size_of::<StringHeader>() + byte_len),
+            0,
+            TAIL_PAD,
+        );
+        ptr
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn round_trip_ascii() {
+        let p = alloc_perry_string("hello bloom");
+        assert_eq!(str_from_header(p), "hello bloom");
+    }
+
+    #[test]
+    fn round_trip_multibyte() {
+        let p = alloc_perry_string("héllo 🌸");
+        assert_eq!(str_from_header(p), "héllo 🌸");
+        // utf16_len: 'héllo ' = 6 units, emoji = 2 (surrogate pair)
+        let h = unsafe { &*(p as *const StringHeader) };
+        assert_eq!(h.utf16_len, 8);
+        assert_eq!(h.byte_len, "héllo 🌸".len() as u32);
+    }
+
+    #[test]
+    fn rejects_null_and_low_pointers() {
+        assert_eq!(str_from_header(std::ptr::null()), "");
+        assert_eq!(str_from_header(0x10 as *const u8), "");
+    }
+
+    #[test]
+    fn rejects_implausible_header() {
+        // byte_len > capacity — the signature of a shifted layout.
+        let bogus = StringHeader {
+            utf16_len: 7,
+            byte_len: 100,
+            capacity: 8,
+            refcount: 1,
+            flags: 0,
+        };
+        let mut buf = vec![0u8; std::mem::size_of::<StringHeader>() + 8];
+        unsafe {
+            (buf.as_mut_ptr() as *mut StringHeader).write(bogus);
+        }
+        assert_eq!(str_from_header(buf.as_ptr()), "");
+    }
+
+    #[test]
+    fn tail_pad_present_and_zeroed() {
+        // EN-020 regression guard: a word-stepping scanner may read past
+        // byte_len; the pad must exist and read as NULs.
+        let p = alloc_perry_string("abc");
+        let payload_end = std::mem::size_of::<StringHeader>() + 3;
+        for i in 0..TAIL_PAD {
+            assert_eq!(unsafe { *p.add(payload_end + i) }, 0, "pad byte {i} not zero");
+        }
+    }
+
+    #[test]
+    fn rejects_invalid_utf8() {
+        let p = alloc_perry_string("abcd") as *mut u8;
+        unsafe {
+            // stomp the payload with a bare continuation byte
+            *p.add(std::mem::size_of::<StringHeader>()) = 0xFF;
+        }
+        assert_eq!(str_from_header(p), "");
+    }
+}