rakata_formats/mdl/

writer.rs

//! MDL binary writer.
//!
//! Serializes an [`Mdl`] struct back into the binary MDL+MDX format used by
//! the Odyssey engine. The writer uses a single-pass cursor approach: it
//! reserves placeholder space for headers and arrays, writes child data
//! forward, then backpatches pointers and counts using seek-back helpers.
//!
//! MDX vertex data is written separately via [`write_mdl_with_mdx_to_vec`] or
//! deferred to a second buffer. Non-skin meshes are emitted first (DFS order),
//! then skin meshes (DFS order), matching the vanilla engine layout.

use std::collections::HashMap;
use std::io::{Cursor, Write};

use crate::binary::{write_f32, write_i32, write_u16, write_u32};

use super::controllers::MdlController;
use super::types::MdlNodeData;
use super::{
    aabb_offsets, anim_mesh_offsets, dangly_offsets, header_offsets, light_offsets, mesh_offsets,
    node_offsets, saber_offsets, skin_offsets, Mdl, MdlError, MdlNode, AABB_EXTRA_SIZE,
    ANIM_MESH_EXTRA_SIZE, DANGLY_EXTRA_SIZE, LIGHT_EXTRA_SIZE, MDL_WRAPPER_SIZE, MESH_EXTRA_SIZE,
    NODE_HEADER_SIZE, SABER_EXTRA_SIZE, SKIN_EXTRA_SIZE,
};

/// Mesh reference collected during DFS traversal for deferred MDX writing.
struct MeshRef<'a> {
    /// The base mesh data.
    mesh: &'a super::MdlMesh,
    /// Skin wrapper (if this is a skin node), carrying bone weight/index data.
    skin: Option<&'a super::MdlSkin>,
    /// Whether this node is a skin mesh.
    is_skin: bool,
}

/// Writes an MDL file structure to a writer.
///
/// # Errors
///
/// [`MdlError::ValueOverflow`] when a node count, offset or array length will
/// not fit its on-disk width, and [`MdlError::InvalidData`] when the node tree
/// does not describe a writable model. [`MdlError::Io`] when the writer fails,
/// which can leave a partial file.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(writer, mdl))
)]
pub fn write_mdl<W: Write>(writer: &mut W, mdl: &Mdl) -> Result<(), MdlError> {
    let bytes = write_mdl_to_vec(mdl)?;
    crate::trace_debug!(bytes_len = bytes.len(), "wrote mdl to writer");
    writer.write_all(&bytes)?;
    Ok(())
}

/// Writes an MDL file structure to a byte vector.
///
/// # Errors
///
/// Every non-I/O failure [`write_mdl`] describes. The `Vec` target has no I/O
/// to fail at.
#[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip(mdl)))]
pub fn write_mdl_to_vec(mdl: &Mdl) -> Result<Vec<u8>, MdlError> {
    let writer = MdlWriter::new();
    let (bytes, _) = writer.write(mdl)?;
    crate::trace_debug!(bytes_len = bytes.len(), "serialized mdl to vec");
    Ok(bytes)
}

/// Writes an MDL model and its companion MDX vertex data to byte vectors.
///
/// Unlike [`write_mdl_to_vec`], this function computes the MDX vertex buffer
/// layout (stride, flags, per-attribute offsets) from the mesh vertex data and
/// writes interleaved vertex attributes into a separate MDX buffer.
///
/// # Errors
///
/// Everything [`write_mdl_to_vec`] reports, plus the MDX layout's own
/// [`MdlError::ValueOverflow`] and [`MdlError::InvalidData`]: a mesh declaring
/// more vertices than it has attribute data for is the case vanilla K1 item
/// models actually hit.
#[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip(mdl)))]
pub fn write_mdl_with_mdx_to_vec(mdl: &Mdl) -> Result<super::MdlWriteResult, MdlError> {
    let writer = MdlWriter::new_with_mdx();
    let (mdl_bytes, mdx_bytes) = writer.write(mdl)?;
    crate::trace_debug!(
        mdl_bytes_len = mdl_bytes.len(),
        mdx_bytes_len = mdx_bytes.len(),
        "serialized mdl+mdx to vec"
    );
    Ok(super::MdlWriteResult {
        mdl_bytes,
        mdx_bytes,
    })
}

/// Checked narrowing cast from `usize` to `u32`.
fn count_u32(len: usize, field: &'static str) -> Result<u32, MdlError> {
    u32::try_from(len).map_err(|_| MdlError::ValueOverflow(field))
}

/// Checked narrowing cast from `usize` to `u16`.
fn count_u16(len: usize, field: &'static str) -> Result<u16, MdlError> {
    u16::try_from(len).map_err(|_| MdlError::ValueOverflow(field))
}

/// Entry for deferred MDX writing. Collected during the node DFS traversal,
/// then flushed in non-skin-first/skin-second order to match the BioWare
/// engine's canonical MDX layout.
struct DeferredMdxEntry {
    /// Position of the mesh extra header in the MDL buffer (for backpatching).
    mesh_header_pos: u64,
    /// Position of the skin extra header (for backpatching bone offsets), if skin.
    skin_header_pos: Option<u64>,
    /// Whether this mesh belongs to a Skin node.
    is_skin: bool,
    /// DFS encounter index (for stable sort within each group).
    dfs_index: usize,
}

struct MdlWriter {
    buffer: Cursor<Vec<u8>>,
    mdx_buffer: Cursor<Vec<u8>>,
    write_mdx: bool,
    names: Vec<String>,
    name_map: HashMap<String, u16>,
    /// Content-relative byte offset of each name string (indexed by node_id).
    name_string_offsets: Vec<u32>,
    /// MDX position right after the last terminator, before alignment padding.
    /// Used to trim trailing alignment from the final mesh.
    mdx_pre_align_pos: u64,
    /// Deferred MDX write entries, collected during DFS node traversal.
    deferred_mdx: Vec<DeferredMdxEntry>,
    /// Map of geometry node name -> written content-relative offset.
    /// Used to resolve `anim_root_node` during header backpatch.
    node_offset_map: HashMap<String, u32>,
}

impl MdlWriter {
    fn new() -> Self {
        MdlWriter {
            buffer: Cursor::new(Vec::new()),
            mdx_buffer: Cursor::new(Vec::new()),
            write_mdx: false,
            names: Vec::new(),
            name_map: HashMap::new(),
            name_string_offsets: Vec::new(),
            mdx_pre_align_pos: 0,
            deferred_mdx: Vec::new(),
            node_offset_map: HashMap::new(),
        }
    }

    fn new_with_mdx() -> Self {
        MdlWriter {
            buffer: Cursor::new(Vec::new()),
            mdx_buffer: Cursor::new(Vec::new()),
            write_mdx: true,
            names: Vec::new(),
            name_map: HashMap::new(),
            name_string_offsets: Vec::new(),
            mdx_pre_align_pos: 0,
            deferred_mdx: Vec::new(),
            node_offset_map: HashMap::new(),
        }
    }

    /// Returns current buffer position as content-relative u32 offset.
    /// Content byte 0 = on-disk byte 12 (after the 12-byte MDL wrapper).
    fn content_position(&self) -> Result<u32, MdlError> {
        let pos = self.buffer.position();
        let content = pos
            .checked_sub(MDL_WRAPPER_SIZE)
            .ok_or(MdlError::ValueOverflow("content_position underflow"))?;
        u32::try_from(content).map_err(|_| MdlError::ValueOverflow("content_position"))
    }

    /// Returns current MDX buffer position as u32.
    fn mdx_position(&self) -> Result<u32, MdlError> {
        u32::try_from(self.mdx_buffer.position())
            .map_err(|_| MdlError::ValueOverflow("mdx_position"))
    }

    /// Seeks the MDL buffer to `base + offset`.
    fn seek_to(&mut self, base: u64, offset: usize) {
        self.buffer
            .set_position(base + u64::try_from(offset).expect("offset fits in u64"));
    }

    fn write(mut self, mdl: &Mdl) -> Result<(Vec<u8>, Vec<u8>), MdlError> {
        // 1. Gather Names via DFS tree walk (geometry + animation nodes).
        self.collect_names(&mdl.root_node);
        for anim in &mdl.animations {
            self.collect_anim_names(&anim.root_node);
        }

        // 2. Write Wrapper placeholder (12 bytes, backpatched at end).
        #[allow(clippy::as_conversions)]
        const WRAPPER_BYTES: usize = MDL_WRAPPER_SIZE as usize;
        // Static assert: MDL_WRAPPER_SIZE fits in usize without truncation.
        #[allow(clippy::as_conversions)]
        const _: () = assert!(MDL_WRAPPER_SIZE == WRAPPER_BYTES as u64);
        self.buffer.write_all(&[0u8; WRAPPER_BYTES])?;

        // 3. Reserve Header (196 bytes: 80-byte geometry + 116-byte model).
        let header_start = self.buffer.position();
        self.buffer.write_all(&[0u8; 196])?;

        // 4. Write Name Table.
        let name_offsets_ptr = self.content_position()?;
        let name_count = count_u32(self.names.len(), "name_count")?;

        // Reserve name offsets array.
        let name_offsets_start = self.buffer.position();
        for _ in 0..name_count {
            write_u32(&mut self.buffer, 0)?;
        }

        // Write strings and record offsets.
        self.name_string_offsets = Vec::with_capacity(self.names.len());
        let mut current_offset_pos = name_offsets_start;
        for name in &self.names {
            let str_start = self.content_position()?;
            self.name_string_offsets.push(str_start);

            // Go back and write the offset for this string.
            let save_pos = self.buffer.position();
            self.buffer.set_position(current_offset_pos);
            write_u32(&mut self.buffer, str_start)?;
            self.buffer.set_position(save_pos);
            current_offset_pos += 4;

            // Write string + null terminator.
            self.buffer.write_all(name.as_bytes())?;
            self.buffer.write_all(&[0u8])?;
        }

        // 5. Write Nodes Recursively
        let root_node_offset = self.write_node(&mdl.root_node, None)?;

        // 5b. Flush deferred MDX writes in canonical order:
        // non-skin meshes first (DFS order), then skin meshes (DFS order).
        // See mdl_mdx.md §MDX Per-Mesh Terminator Rows (Finding 4).
        if self.write_mdx && !self.deferred_mdx.is_empty() {
            self.write_deferred_mdx(&mdl.root_node)?;
        }

        // 5c. Write Animations (after geometry nodes, before header backpatch).
        let (anim_arr_ptr, anim_arr_count) = self.write_animations(&mdl.animations)?;

        // 6. Backpatch Header - write all fields explicitly.

        // --- Geometry header (+0x00..+0x4F) ---
        self.seek_to(header_start, header_offsets::FN_PTR1);
        write_u32(&mut self.buffer, mdl.geometry_fn_ptr1)?;

        self.seek_to(header_start, header_offsets::FN_PTR2);
        write_u32(&mut self.buffer, mdl.geometry_fn_ptr2)?;

        // Model name at +0x08 (32-byte null-terminated, same as root node name).
        self.seek_to(header_start, header_offsets::MODEL_NAME);
        let model_name = mdl.root_node.name.as_bytes();
        let model_name_len = model_name.len().min(header_offsets::MODEL_NAME_SIZE - 1);
        self.buffer.write_all(&model_name[..model_name_len])?;
        self.buffer.write_all(&[0])?;

        self.seek_to(header_start, header_offsets::ROOT_NODE_PTR);
        write_u32(&mut self.buffer, root_node_offset)?;

        self.seek_to(header_start, header_offsets::NODE_COUNT);
        write_u32(&mut self.buffer, mdl.node_count)?;

        // Runtime arrays at +0x30..+0x47 stay zero (written at init).
        // ref_count at +0x48 stays zero.

        // Model type at +0x4C (always 2 for geometry models).
        self.seek_to(header_start, header_offsets::MODEL_TYPE);
        self.buffer.write_all(&[mdl.model_type])?;

        // --- Model header (+0x50..+0xC3) ---
        self.seek_to(header_start, header_offsets::CLASSIFICATION);
        self.buffer.write_all(&[mdl.classification])?;

        self.seek_to(header_start, header_offsets::SUBCLASSIFICATION);
        self.buffer.write_all(&[mdl.subclassification])?;

        // +0x52: unknown byte, stays zero.

        self.seek_to(header_start, header_offsets::AFFECTED_BY_FOG);
        self.buffer.write_all(&[mdl.affected_by_fog])?;

        // num_child_models at +0x54: always 0 (stays zero from init).

        // Animation array CExoArrayList at +0x58 (ptr/count/alloc).
        self.seek_to(header_start, header_offsets::ANIMATION_ARR_PTR);
        write_u32(&mut self.buffer, anim_arr_ptr)?;
        write_u32(&mut self.buffer, anim_arr_count)?;
        write_u32(&mut self.buffer, anim_arr_count)?; // alloc mirrors count

        // supermodel_ref at +0x64: always 0 (stays zero from init).

        // Bounding box at +0x68 (6 floats).
        self.seek_to(header_start, header_offsets::BOUNDING_BOX_MIN);
        for &val in &mdl.bounding_box {
            write_f32(&mut self.buffer, val)?;
        }

        // Radius at +0x80.
        self.seek_to(header_start, header_offsets::RADIUS);
        write_f32(&mut self.buffer, mdl.radius)?;

        // Animation scale at +0x84.
        self.seek_to(header_start, header_offsets::ANIMATION_SCALE);
        write_f32(&mut self.buffer, mdl.animation_scale)?;

        // Supermodel name at +0x88 (null-terminated, 32-byte field).
        self.seek_to(header_start, header_offsets::SUPERMODEL_NAME);
        let name_bytes = mdl.supermodel_name.as_bytes();
        let write_len = name_bytes
            .len()
            .min(header_offsets::SUPERMODEL_NAME_SIZE - 1);
        self.buffer.write_all(&name_bytes[..write_len])?;
        self.buffer.write_all(&[0])?;

        // off_anim_root at +0xA8: points to the animation root node.
        // For most models this is the geometry root. Head models point to
        // `neck_g` so the engine applies head animations from the neck bone.
        let anim_root_offset = mdl
            .anim_root_node
            .as_ref()
            .and_then(|name| self.node_offset_map.get(name).copied())
            .unwrap_or(root_node_offset);
        self.seek_to(header_start, header_offsets::OFF_ANIM_ROOT);
        write_u32(&mut self.buffer, anim_root_offset)?;

        // +0xAC: padding, stays zero.

        // Name array at +0xB8.
        self.seek_to(header_start, header_offsets::NAME_OFFSETS_PTR);
        write_u32(&mut self.buffer, name_offsets_ptr)?;

        self.seek_to(header_start, header_offsets::NAME_COUNT);
        write_u32(&mut self.buffer, name_count)?;

        let mut mdl_bytes = self.buffer.into_inner();
        let mut mdx_bytes = self.mdx_buffer.into_inner();

        // Trim trailing 16-byte alignment padding from the last mesh's
        // terminator. The MDX file ends right after the last terminator,
        // without alignment padding. The writer tracks the pre-alignment
        // position to truncate precisely.
        // See mdl_mdx.md §MDX Per-Mesh Terminator Rows (Finding 3).
        let trim_to =
            usize::try_from(self.mdx_pre_align_pos).expect("mdx_pre_align_pos fits in usize");
        if trim_to > 0 && trim_to < mdx_bytes.len() {
            mdx_bytes.truncate(trim_to);
        }

        // Backpatch wrapper sizes:
        // +0x00 zero marker (always 0), +0x04 MDL content size, +0x08 MDX file size.
        let mdl_content_size = mdl_bytes
            .len()
            .checked_sub(WRAPPER_BYTES)
            .ok_or_else(|| MdlError::InvalidData("serialized MDL shorter than wrapper".into()))?;
        let mdl_content_size_u32 = u32::try_from(mdl_content_size)
            .map_err(|_| MdlError::ValueOverflow("mdl_content_size"))?;
        let mdx_size_u32 =
            u32::try_from(mdx_bytes.len()).map_err(|_| MdlError::ValueOverflow("mdx_file_size"))?;
        mdl_bytes[0..4].copy_from_slice(&0u32.to_le_bytes());
        mdl_bytes[4..8].copy_from_slice(&mdl_content_size_u32.to_le_bytes());
        mdl_bytes[8..12].copy_from_slice(&mdx_size_u32.to_le_bytes());

        // Backpatch MDX size in model header (+0xB0).
        let mdx_size_offset = WRAPPER_BYTES + header_offsets::MDX_SIZE;
        mdl_bytes[mdx_size_offset..mdx_size_offset + 4]
            .copy_from_slice(&mdx_size_u32.to_le_bytes());

        Ok((mdl_bytes, mdx_bytes))
    }

    /// Flush deferred MDX writes in canonical order: non-skin meshes first
    /// (DFS order), then skin meshes (DFS order). Each mesh gets its vertex
    /// data written followed by a terminator row with 16-byte alignment
    /// (except the very last mesh, whose trailing alignment is trimmed by
    /// the caller).
    ///
    /// The DFS-order mesh references are obtained by walking the node tree
    /// in the same pre-order traversal used by `write_node`.
    fn write_deferred_mdx(&mut self, root: &MdlNode) -> Result<(), MdlError> {
        // Collect mesh node references in DFS order.
        let mut mesh_refs: Vec<MeshRef<'_>> = Vec::new();
        Self::collect_mesh_refs(root, &mut mesh_refs);

        // Sanity check: deferred entries must match mesh refs 1:1.
        debug_assert_eq!(mesh_refs.len(), self.deferred_mdx.len());

        // Build ordered indices: non-skin first, then skin (both in DFS order).
        // DFS order is preserved because `deferred_mdx` was populated in DFS
        // order and we use a stable partition.
        let entries: Vec<DeferredMdxEntry> = std::mem::take(&mut self.deferred_mdx);
        let (non_skin, skin): (Vec<usize>, Vec<usize>) =
            (0..entries.len()).partition(|&i| !entries[i].is_skin);
        let ordered: Vec<usize> = non_skin.into_iter().chain(skin).collect();

        for idx in &ordered {
            let entry = &entries[*idx];
            let mesh_ref = &mesh_refs[entry.dfs_index];

            // Record MDX file offset BEFORE writing vertex data -- this is
            // where the engine will find this mesh's vertices in the MDX buffer.
            let mdx_offset = self.mdx_position()?;

            let stride = self.write_mesh_mdx_data(
                mesh_ref.mesh,
                mesh_ref.skin,
                entry.mesh_header_pos,
                entry.skin_header_pos,
            )?;
            self.write_mdx_terminator(stride, mesh_ref.is_skin)?;

            // Backpatch mesh header +0x144 with the MDX file offset.
            // Community tools (mdlops, kotorblender) write this value and the
            // engine uses it to locate per-mesh vertex data within the bulk
            // MDX GL vertex buffer.
            let save = self.buffer.position();
            self.seek_to(entry.mesh_header_pos, mesh_offsets::MDX_DATA_OFFSET);
            write_u32(&mut self.buffer, mdx_offset)?;
            self.buffer.set_position(save);
        }

        Ok(())
    }

    /// Collect mesh references from the node tree in pre-order DFS, matching
    /// the traversal order of `write_node`. Returns mesh, optional skin, and
    /// whether the node is a skin.
    ///
    /// Saber nodes are excluded because they have no MDX vertex data (stride=0).
    fn collect_mesh_refs<'a>(node: &'a MdlNode, out: &mut Vec<MeshRef<'a>>) {
        if !node.is_saber() {
            if let Some(mesh) = node.node_data.mesh() {
                let skin = if let MdlNodeData::Skin(s) = &node.node_data {
                    Some(s)
                } else {
                    None
                };
                out.push(MeshRef {
                    mesh,
                    skin,
                    is_skin: node.is_skin(),
                });
            }
        }
        for child in &node.children {
            Self::collect_mesh_refs(child, out);
        }
    }

    fn collect_names(&mut self, node: &MdlNode) {
        if !self.name_map.contains_key(&node.name) {
            let index = count_u16(self.names.len(), "name_index")
                .expect("name table must not exceed u16::MAX entries during collect_names");
            // Both the name table (Vec) and the lookup map (HashMap) need owned
            // copies of the name. The double clone is unavoidable without an
            // index-based refactor; model name tables are small (~100 entries).
            self.name_map.insert(node.name.clone(), index);
            self.names.push(node.name.clone());
        }
        for child in &node.children {
            self.collect_names(child);
        }
    }

    fn collect_anim_names(&mut self, node: &super::MdlAnimNode) {
        if !self.name_map.contains_key(&node.name) {
            let index = count_u16(self.names.len(), "name_index")
                .expect("name table must not exceed u16::MAX entries during collect_anim_names");
            self.name_map.insert(node.name.clone(), index);
            self.names.push(node.name.clone());
        }
        for child in &node.children {
            self.collect_anim_names(child);
        }
    }

    // -----------------------------------------------------------------------
    // Animation writer
    // -----------------------------------------------------------------------

    /// Writes all animations and returns `(anim_arr_ptr, anim_count)` for
    /// backpatching into the model header's CExoArrayList at +0x58.
    fn write_animations(
        &mut self,
        animations: &[super::MdlAnimation],
    ) -> Result<(u32, u32), MdlError> {
        if animations.is_empty() {
            return Ok((0, 0));
        }

        // Write the offset array (one u32 per animation, content-relative).
        let arr_ptr = self.content_position()?;
        let arr_count = count_u32(animations.len(), "animation_count")?;

        // Reserve the offset array, backpatch after writing each animation.
        let arr_start = self.buffer.position();
        for _ in 0..arr_count {
            write_u32(&mut self.buffer, 0)?;
        }

        let mut anim_offsets = Vec::with_capacity(animations.len());
        for anim in animations {
            let offset = self.write_animation(anim)?;
            anim_offsets.push(offset);
        }

        // Backpatch the offset array.
        let save_pos = self.buffer.position();
        self.buffer.set_position(arr_start);
        for &offset in &anim_offsets {
            write_u32(&mut self.buffer, offset)?;
        }
        self.buffer.set_position(save_pos);

        Ok((arr_ptr, arr_count))
    }

    /// Writes a single animation: header (136 bytes) + events + node tree.
    /// Returns the content-relative offset of the animation header.
    fn write_animation(&mut self, anim: &super::MdlAnimation) -> Result<u32, MdlError> {
        let anim_offset = self.content_position()?;

        // Reserve 136-byte animation header (backpatched below).
        let header_pos = self.buffer.position();
        self.buffer
            .write_all(&[0u8; super::ANIMATION_HEADER_SIZE])?;

        // Write events.
        let events_ptr = if anim.events.is_empty() {
            0u32
        } else {
            let ptr = self.content_position()?;
            for event in &anim.events {
                write_f32(&mut self.buffer, event.time)?;
                self.write_fixed_string(&event.name, 32)?;
            }
            ptr
        };
        let event_count = count_u32(anim.events.len(), "event_count")?;

        // Write animation node tree recursively.
        let root_node_offset = self.write_anim_node(&anim.root_node, anim_offset, None)?;

        // Count total animation nodes.
        let total_nodes = super::count_anim_nodes(&anim.root_node);

        // Backpatch animation header.
        let save_pos = self.buffer.position();
        self.buffer.set_position(header_pos);

        // fn_ptr1, fn_ptr2 at +0x00, +0x04
        write_u32(&mut self.buffer, anim.fn_ptr1)?;
        write_u32(&mut self.buffer, anim.fn_ptr2)?;

        // name at +0x08 (32 bytes)
        self.write_fixed_string(&anim.name, super::anim_header_offsets::NAME_SIZE)?;

        // root_node_ptr at +0x28
        write_u32(&mut self.buffer, root_node_offset)?;

        // total_num_nodes at +0x2C
        write_u32(&mut self.buffer, total_nodes)?;

        // runtime_arr1 at +0x30 (12 bytes zeros) - already zero from init
        self.buffer.write_all(&[0u8; 12])?;
        // runtime_arr2 at +0x3C (12 bytes zeros) - already zero from init
        self.buffer.write_all(&[0u8; 12])?;
        // ref_count at +0x48
        write_u32(&mut self.buffer, 0)?;

        // model_type at +0x4C (u8 = 5 for animations, + 3 padding)
        self.buffer.write_all(&[5, 0, 0, 0])?;

        // length at +0x50
        write_f32(&mut self.buffer, anim.length)?;

        // transition at +0x54
        write_f32(&mut self.buffer, anim.transition_time)?;

        // anim_root at +0x58 (32 bytes)
        self.write_fixed_string(&anim.anim_root, super::anim_header_offsets::ANIM_ROOT_SIZE)?;

        // event_arr at +0x78 (ptr/count/alloc)
        write_u32(&mut self.buffer, events_ptr)?;
        write_u32(&mut self.buffer, event_count)?;
        write_u32(&mut self.buffer, event_count)?;

        // padding at +0x84 (4 bytes, stays zero from init)
        write_u32(&mut self.buffer, 0)?;

        self.buffer.set_position(save_pos);
        Ok(anim_offset)
    }

    /// Writes a single animation node (80-byte base header) and its children.
    /// Returns the content-relative offset.
    fn write_anim_node(
        &mut self,
        node: &super::MdlAnimNode,
        anim_header_offset: u32,
        parent_node_offset: Option<u32>,
    ) -> Result<u32, MdlError> {
        let node_offset = self.content_position()?;

        // Reserve 80-byte node header.
        let header_pos = self.buffer.position();
        self.buffer.write_all(&[0u8; NODE_HEADER_SIZE])?;

        // Write children array.
        let child_arr_ptr = if node.children.is_empty() {
            0u32
        } else {
            let ptr = self.content_position()?;
            // Reserve child offset array.
            let children_start = self.buffer.position();
            for _ in 0..node.children.len() {
                write_u32(&mut self.buffer, 0)?;
            }

            // Write each child and collect offsets.
            let mut child_offsets = Vec::with_capacity(node.children.len());
            for child in &node.children {
                let child_off =
                    self.write_anim_node(child, anim_header_offset, Some(node_offset))?;
                child_offsets.push(child_off);
            }

            // Backpatch child offsets.
            let save = self.buffer.position();
            self.buffer.set_position(children_start);
            for &off in &child_offsets {
                write_u32(&mut self.buffer, off)?;
            }
            self.buffer.set_position(save);

            ptr
        };
        let child_count = count_u32(node.children.len(), "anim_child_count")?;

        // Write controllers.
        let (ctrl_key_ptr, ctrl_key_count, ctrl_data_ptr, ctrl_data_count) =
            self.write_controllers(&node.controllers, &node.orphan_controller_data)?;

        // Backpatch node header.
        let save_pos = self.buffer.position();
        self.buffer.set_position(header_pos);

        // +0x00: type_flags (u16) -- animation nodes are always NODE_BASE (0x0001)
        write_u16(
            &mut self.buffer,
            u16::try_from(super::node_flags::HEADER)
                .map_err(|_| MdlError::ValueOverflow("anim_node_flags"))?,
        )?;

        // +0x02: node_number (u16) -- maps to the geometry node index
        write_u16(&mut self.buffer, node.node_number)?;

        // +0x04: name_index (u16) -- index into model name table
        let name_index = *self.name_map.get(&node.name).unwrap_or(&0);
        write_u16(&mut self.buffer, name_index)?;

        // +0x06: padding (2 bytes)
        self.buffer.write_all(&[0u8; 2])?;

        // +0x08: root pointer (content-relative offset to animation header)
        write_u32(&mut self.buffer, anim_header_offset)?;

        // +0x0C: parent pointer
        write_u32(&mut self.buffer, parent_node_offset.unwrap_or(0))?;

        // +0x10: position (3 × f32) - animation nodes use identity transform
        write_f32(&mut self.buffer, 0.0)?;
        write_f32(&mut self.buffer, 0.0)?;
        write_f32(&mut self.buffer, 0.0)?;

        // +0x1C: orientation quaternion (w, x, y, z)
        write_f32(&mut self.buffer, 1.0)?;
        write_f32(&mut self.buffer, 0.0)?;
        write_f32(&mut self.buffer, 0.0)?;
        write_f32(&mut self.buffer, 0.0)?;

        // +0x2C: children array (ptr/count/alloc)
        write_u32(&mut self.buffer, child_arr_ptr)?;
        write_u32(&mut self.buffer, child_count)?;
        write_u32(&mut self.buffer, child_count)?;

        // +0x38: controller key array (ptr/count/alloc)
        write_u32(&mut self.buffer, ctrl_key_ptr)?;
        write_u32(&mut self.buffer, ctrl_key_count)?;
        write_u32(&mut self.buffer, ctrl_key_count)?;

        // +0x44: controller data array (ptr/count/alloc)
        write_u32(&mut self.buffer, ctrl_data_ptr)?;
        write_u32(&mut self.buffer, ctrl_data_count)?;
        write_u32(&mut self.buffer, ctrl_data_count)?;

        self.buffer.set_position(save_pos);
        Ok(node_offset)
    }

    // -----------------------------------------------------------------------
    // Geometry node writer
    // -----------------------------------------------------------------------

    fn write_node(
        &mut self,
        node: &MdlNode,
        parent_node_offset: Option<u32>,
    ) -> Result<u32, MdlError> {
        // Current position relative to wrapper end (byte 12 is offset 0)
        let node_start_offset = self.content_position()?;

        // Record this node's written offset for anim_root_node resolution.
        self.node_offset_map
            .insert(node.name.clone(), node_start_offset);

        // Reserve Node Header (0x44 = 68 bytes)
        let header_pos = self.buffer.position();
        self.buffer.write_all(&[0u8; NODE_HEADER_SIZE])?;

        // Write type-specific headers based on node_data variant.
        // Non-mesh types with stub headers come first (matching binary packing order),
        // then mesh header if this is a mesh-derived variant.
        let light_header_pos = match &node.node_data {
            MdlNodeData::Light(light) => Some(self.write_light_header(light)?),
            _ => None,
        };
        match &node.node_data {
            MdlNodeData::Light(_) => {} // header already written above
            MdlNodeData::Emitter(emitter) => {
                self.write_emitter_header(emitter)?;
            }
            MdlNodeData::Camera(_) => {
                // Camera: 0 extra bytes (Ghidra-verified, mdl_mdx.md Non-Mesh Node Type Structs)
            }
            MdlNodeData::Reference(reference) => {
                self.write_reference_header(reference)?;
            }
            _ => {}
        }

        // Phase 1: Write all headers contiguously (mesh + subtype).
        // The binary format requires headers to be contiguous, with array
        // data following separately (pointed to by CExoArrayList pointers).
        let mesh_header_pos = if let Some(mesh) = node.node_data.mesh() {
            Some(self.write_mesh_header(mesh)?)
        } else {
            None
        };

        // Write mesh subtype extra headers (immediately after TriMesh header).
        let skin_header_pos = if let MdlNodeData::Skin(skin) = &node.node_data {
            Some(self.write_skin_header(skin)?)
        } else {
            None
        };
        let anim_header_pos = if let MdlNodeData::AnimMesh(anim) = &node.node_data {
            Some(self.write_anim_mesh_header(anim)?)
        } else {
            None
        };
        let dangly_header_pos = if let MdlNodeData::Dangly(dangly) = &node.node_data {
            Some(self.write_dangly_header(dangly)?)
        } else {
            None
        };
        let aabb_header_pos = if let MdlNodeData::Aabb(_) = &node.node_data {
            Some(self.write_aabb_header()?)
        } else {
            None
        };
        let saber_header_pos = if let MdlNodeData::Saber(saber) = &node.node_data {
            Some(self.write_saber_header(saber)?)
        } else {
            None
        };

        // Phase 2: Write array data (faces, constraints, bones, verts, etc.) after all headers.
        //
        // Light flare arrays are written first (non-mesh type with CExoArrayList data).
        if let (MdlNodeData::Light(light), Some(lhp)) = (&node.node_data, light_header_pos) {
            self.write_light_arrays(light, lhp)?;
        }
        // Skin nodes are ordered specially: skin-bone arrays are emitted before
        // TriMesh internal arrays in vanilla binaries. This ordering affects
        // TriMesh pointer fields (+0xB0/+0xBC/+0xC8) and must match for
        // roundtrip parity.
        if let (MdlNodeData::Skin(skin), Some(shp)) = (&node.node_data, skin_header_pos) {
            self.write_skin_arrays(skin, shp)?;
        }
        if let (MdlNodeData::Saber(saber), Some(shp)) = (&node.node_data, saber_header_pos) {
            self.write_saber_arrays(saber, shp)?;
        }
        if let (MdlNodeData::Dangly(dangly), Some(dhp)) = (&node.node_data, dangly_header_pos) {
            self.write_dangly_arrays(dangly, dhp)?;
            self.write_dangly_pre_mesh_payload(dangly, dhp)?;
        }
        if let (MdlNodeData::Aabb(aabb), Some(ahp)) = (&node.node_data, aabb_header_pos) {
            self.write_aabb_arrays(aabb, ahp)?;
        }
        let embedded_pos_ptr =
            if let (Some(mesh), Some(mhp)) = (node.node_data.mesh(), mesh_header_pos) {
                self.write_mesh_arrays(mesh, mhp)?
            } else {
                None
            };
        if let (MdlNodeData::AnimMesh(anim), Some(ahp)) = (&node.node_data, anim_header_pos) {
            self.write_anim_mesh_arrays(anim, ahp)?;
        }
        // Phase 2b: Write position-only vertex data into MDL content blob.
        //
        // Embedded vertex positions are ALWAYS written (even when MDX is also
        // being generated). The vert_array_offset field (+0x148) is a
        // content-relative pointer to this data, and the engine relocates it
        // during Reset. The separate mdx_data_offset (+0x144) points into the
        // MDX file for the full interleaved vertex buffer.
        if let (Some(mesh), Some(mhp)) = (node.node_data.mesh(), mesh_header_pos) {
            self.write_mesh_content_positions(mesh, mhp, embedded_pos_ptr)?;
        }

        // Phase 3: Defer MDX vertex data (if enabled).
        // MDX data is written after all MDL nodes are complete, in canonical
        // order: non-skin meshes first, then skin meshes (both in DFS order).
        // See mdl_mdx.md §MDX Per-Mesh Terminator Rows (Finding 4).
        //
        // Saber nodes are excluded: they have stride=0 and no MDX vertex data.
        // Saber vertex positions live in the MDL content blob (vert_array_offset),
        // not in the MDX file.
        if self.write_mdx && !node.is_saber() {
            if let Some(mhp) = mesh_header_pos {
                if node.node_data.mesh().is_some() {
                    let dfs_index = self.deferred_mdx.len();
                    self.deferred_mdx.push(DeferredMdxEntry {
                        mesh_header_pos: mhp,
                        skin_header_pos,
                        is_skin: node.is_skin(),
                        dfs_index,
                    });
                }
            }
        }

        // Write Children (pointer table + recursive child payloads) before
        // controller arrays to match vanilla binary node packing.
        let child_count = count_u32(node.children.len(), "child_count")?;
        let mut child_array_ptr = 0;

        if child_count > 0 {
            // Reserve Child Pointer Array
            let array_start = self.buffer.position();
            child_array_ptr = self.content_position()?;
            let child_arr_bytes =
                usize::try_from(child_count).expect("child_count fits in usize") * 4;
            self.buffer.write_all(&vec![0u8; child_arr_bytes])?;

            // Recurse for each child
            for (i, child) in node.children.iter().enumerate() {
                let child_offset = self.write_node(child, Some(node_start_offset))?;

                // Backpatch pointer
                let save = self.buffer.position();
                // i is bounded by child_count (verified to fit u32 above).
                self.seek_to(array_start, i * 4);
                write_u32(&mut self.buffer, child_offset)?;
                self.buffer.set_position(save);
            }
        }

        // Write Controllers after child payloads.
        let (key_ptr, key_count, data_ptr, data_count) =
            self.write_controllers(&node.controllers, &node.orphan_controller_data)?;

        // Backpatch Node Header
        let save_end = self.buffer.position();
        self.buffer.set_position(header_pos);

        write_u16(
            &mut self.buffer,
            u16::try_from(node.node_data.flags())
                .map_err(|_| MdlError::ValueOverflow("node_flags"))?,
        )?; // 0x00
        self.buffer.write_all(&node.header_padding_02)?; // 0x02..0x03

        let node_id = *self.name_map.get(&node.name).unwrap_or(&0);
        write_u16(&mut self.buffer, node_id)?; // 0x04

        // +0x06: struct alignment padding.
        self.buffer.write_all(&node.header_padding_06)?; // 0x06..0x07

        // +0x08: binary MDL files preserve this slot as 0 in vanilla assets.
        // Node naming is resolved via node_id + global name table.
        write_u32(&mut self.buffer, 0)?; // 0x08..0x0B

        // +0x0C: parent node offset (content-relative, relocated if non-zero).
        // Root nodes have no parent (0). See mdl_mdx.md §MdlNode Binary Layout.
        write_u32(&mut self.buffer, parent_node_offset.unwrap_or(0))?; // 0x0C..0x0F

        self.seek_to(header_pos, node_offsets::POS_X);
        write_f32(&mut self.buffer, node.position[0])?;
        write_f32(&mut self.buffer, node.position[1])?;
        write_f32(&mut self.buffer, node.position[2])?;

        // Orientation quaternion (w, x, y, z) - direct, no swizzle
        self.seek_to(header_pos, node_offsets::ORIENTATION_W);
        write_f32(&mut self.buffer, node.rotation[0])?; // w
        write_f32(&mut self.buffer, node.rotation[1])?; // x
        write_f32(&mut self.buffer, node.rotation[2])?; // y
        write_f32(&mut self.buffer, node.rotation[3])?; // z

        // 3-field arrays: ptr, count_used, count_allocated (alloc = used on disk)
        self.seek_to(header_pos, node_offsets::CHILD_ARRAY_PTR);
        let child_ptr_field = if child_count > 0 {
            child_array_ptr
        } else if key_count > 0 {
            // Vanilla binaries often mirror controller-key pointer here even
            // when child_count is zero.
            key_ptr
        } else {
            0
        };
        write_u32(&mut self.buffer, child_ptr_field)?;
        write_u32(&mut self.buffer, child_count)?; // used
        write_u32(&mut self.buffer, child_count)?; // allocated

        self.seek_to(header_pos, node_offsets::CONTROLLER_KEY_PTR);
        write_u32(&mut self.buffer, key_ptr)?;
        write_u32(&mut self.buffer, key_count)?; // used
        write_u32(&mut self.buffer, key_count)?; // allocated

        self.seek_to(header_pos, node_offsets::CONTROLLER_DATA_PTR);
        write_u32(&mut self.buffer, data_ptr)?;
        write_u32(&mut self.buffer, data_count)?; // used
        write_u32(&mut self.buffer, data_count)?; // allocated

        self.buffer.set_position(save_end);
        Ok(node_start_offset)
    }

    /// Writes a f32 at `header_pos + field_offset` without moving the cursor.
    fn write_f32_at(
        &mut self,
        header_pos: u64,
        field_offset: usize,
        val: f32,
    ) -> Result<(), MdlError> {
        let save = self.buffer.position();
        self.seek_to(header_pos, field_offset);
        write_f32(&mut self.buffer, val)?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Writes a u32 at `header_pos + field_offset` without moving the cursor.
    fn write_u32_at(
        &mut self,
        header_pos: u64,
        field_offset: usize,
        val: u32,
    ) -> Result<(), MdlError> {
        let save = self.buffer.position();
        self.seek_to(header_pos, field_offset);
        write_u32(&mut self.buffer, val)?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Writes an i32 at `header_pos + field_offset` without moving the cursor.
    fn write_i32_at(
        &mut self,
        header_pos: u64,
        field_offset: usize,
        val: i32,
    ) -> Result<(), MdlError> {
        let save = self.buffer.position();
        self.seek_to(header_pos, field_offset);
        write_i32(&mut self.buffer, val)?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Writes a u16 at `header_pos + field_offset` without moving the cursor.
    fn write_u16_at(
        &mut self,
        header_pos: u64,
        field_offset: usize,
        val: u16,
    ) -> Result<(), MdlError> {
        let save = self.buffer.position();
        self.seek_to(header_pos, field_offset);
        write_u16(&mut self.buffer, val)?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Writes a u8 at `header_pos + field_offset` without moving the cursor.
    fn write_u8_at(
        &mut self,
        header_pos: u64,
        field_offset: usize,
        val: u8,
    ) -> Result<(), MdlError> {
        let save = self.buffer.position();
        self.seek_to(header_pos, field_offset);
        self.buffer.write_all(&[val])?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Writes a 3×f32 vector at `header_pos + field_offset` without moving the cursor.
    fn write_vec3_at(
        &mut self,
        header_pos: u64,
        field_offset: usize,
        v: &[f32; 3],
    ) -> Result<(), MdlError> {
        let save = self.buffer.position();
        self.seek_to(header_pos, field_offset);
        write_f32(&mut self.buffer, v[0])?;
        write_f32(&mut self.buffer, v[1])?;
        write_f32(&mut self.buffer, v[2])?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Writes a null-terminated string at `header_pos + field_offset`,
    /// padded with zeros to `max_len` bytes.
    fn write_string_at(
        &mut self,
        header_pos: u64,
        field_offset: usize,
        s: &str,
        max_len: usize,
    ) -> Result<(), MdlError> {
        let save = self.buffer.position();
        self.seek_to(header_pos, field_offset);
        crate::binary::write_fixed_c_string(&mut self.buffer, s, max_len)?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Writes the 332-byte mesh extra header from typed fields.
    ///
    /// Returns the header position for deferred backpatching by
    /// [`write_mesh_arrays`].
    fn write_mesh_header(&mut self, mesh: &super::MdlMesh) -> Result<u64, MdlError> {
        let header_pos = self.buffer.position();
        // Zero-filled 332-byte mesh extra header; typed fields are overlaid below.
        self.buffer.write_all(&[0u8; MESH_EXTRA_SIZE])?;

        // Toolset function pointer stubs (extra +0x00, +0x04).
        self.write_u32_at(
            header_pos,
            mesh_offsets::FN_PTR_GEN_VERTICES,
            mesh.fn_ptr_gen_vertices,
        )?;
        self.write_u32_at(
            header_pos,
            mesh_offsets::FN_PTR_REMOVE_TEMP_ARRAY,
            mesh.fn_ptr_remove_temp_array,
        )?;

        // Bounding box and sphere.
        self.write_vec3_at(header_pos, mesh_offsets::BOUNDING_MIN, &mesh.bounding_min)?;
        self.write_vec3_at(header_pos, mesh_offsets::BOUNDING_MAX, &mesh.bounding_max)?;
        self.write_f32_at(
            header_pos,
            mesh_offsets::BSPHERE_RADIUS,
            mesh.bsphere_radius,
        )?;
        self.write_vec3_at(
            header_pos,
            mesh_offsets::BSPHERE_CENTER,
            &mesh.bsphere_center,
        )?;

        // Colors.
        self.write_vec3_at(header_pos, mesh_offsets::DIFFUSE_COLOR, &mesh.diffuse_color)?;
        self.write_vec3_at(header_pos, mesh_offsets::AMBIENT_COLOR, &mesh.ambient_color)?;

        // Transparency.
        self.write_i32_at(
            header_pos,
            mesh_offsets::TRANSPARENCY_HINT,
            mesh.transparency_hint,
        )?;

        // Texture names.
        self.write_string_at(
            header_pos,
            mesh_offsets::TEXTURE_0,
            &mesh.texture_0,
            mesh_offsets::TEXTURE_NAME_SIZE,
        )?;
        self.write_string_at(
            header_pos,
            mesh_offsets::TEXTURE_1,
            &mesh.texture_1,
            mesh_offsets::TEXTURE_NAME_SIZE,
        )?;

        // Shared index scalars.
        {
            let save = self.buffer.position();
            self.seek_to(header_pos, mesh_offsets::SHARED_INDEX_OFFSET);
            write_i32(&mut self.buffer, mesh.shared_index_offset)?;
            write_i32(&mut self.buffer, mesh.shared_index_pool)?;
            write_i32(&mut self.buffer, mesh.shared_index_size)?;
            write_u32(&mut self.buffer, mesh.indices_per_face)?;
            self.buffer.set_position(save);
        }

        // UV animation.
        self.write_i32_at(header_pos, mesh_offsets::ANIMATE_UV, mesh.animate_uv)?;
        self.write_f32_at(
            header_pos,
            mesh_offsets::UV_DIRECTION_X,
            mesh.uv_direction_x,
        )?;
        self.write_f32_at(
            header_pos,
            mesh_offsets::UV_DIRECTION_Y,
            mesh.uv_direction_y,
        )?;
        self.write_f32_at(header_pos, mesh_offsets::UV_JITTER, mesh.uv_jitter)?;
        self.write_f32_at(
            header_pos,
            mesh_offsets::UV_JITTER_SPEED,
            mesh.uv_jitter_speed,
        )?;

        // Vertex count and channel count.
        self.write_u16_at(header_pos, mesh_offsets::VERTEX_COUNT, mesh.vertex_count)?;
        self.write_u16_at(
            header_pos,
            mesh_offsets::TEXTURE_CHANNEL_COUNT,
            mesh.texture_channel_count,
        )?;

        // Boolean flags.
        self.write_u8_at(
            header_pos,
            mesh_offsets::LIGHT_MAPPED,
            u8::from(mesh.light_mapped),
        )?;
        self.write_u8_at(
            header_pos,
            mesh_offsets::ROTATE_TEXTURE,
            u8::from(mesh.rotate_texture),
        )?;
        self.write_u8_at(
            header_pos,
            mesh_offsets::IS_BACKGROUND_GEOMETRY,
            u8::from(mesh.is_background_geometry),
        )?;
        self.write_u8_at(header_pos, mesh_offsets::SHADOW, u8::from(mesh.shadow))?;
        self.write_u8_at(header_pos, mesh_offsets::BEAMING, u8::from(mesh.beaming))?;
        self.write_u8_at(header_pos, mesh_offsets::RENDER, u8::from(mesh.render))?;

        // Total surface area.
        self.write_f32_at(
            header_pos,
            mesh_offsets::TOTAL_SURFACE_AREA,
            mesh.total_surface_area,
        )?;

        // MDX layout sentinel defaults for offset slots that are always -1
        // in vanilla. The active slots (+0xFC stride, +0x100 flags,
        // +0x104..+0x120 attribute offsets) are filled by write_mesh_mdx_data.
        // The 3 reserved slots at +0x124..+0x12C are never used by K1 but
        // the constructor initializes them to -1.
        {
            let save = self.buffer.position();
            // 8 active attribute offset slots (+0x104..+0x120) default to -1.
            // write_mesh_mdx_data overwrites the ones it uses.
            self.seek_to(header_pos, mesh_offsets::MDX_POSITION_OFFSET);
            for _ in 0..8 {
                write_u32(&mut self.buffer, 0xFFFF_FFFF)?;
            }
            // 3 reserved slots at +0x124..+0x12C: always -1.
            for _ in 0..3 {
                write_u32(&mut self.buffer, 0xFFFF_FFFF)?;
            }
            self.buffer.set_position(save);
        }

        Ok(header_pos)
    }

    /// Writes a raw CExoArrayList payload and backpatches the ptr/count/alloc
    /// Writes face array data and backpatches the mesh header's face pointer.
    ///
    /// Must be called after all contiguous headers (mesh + subtype) are written,
    /// so the array data sits after the header block - matching the binary format
    /// layout where headers are contiguous and data follows.
    fn write_mesh_arrays(
        &mut self,
        mesh: &super::MdlMesh,
        mesh_header_pos: u64,
    ) -> Result<Option<u32>, MdlError> {
        let face_count = count_u32(mesh.faces.len(), "face_count")?;
        let mut face_offset = 0u32;

        if face_count > 0 {
            face_offset = self.content_position()?;
            for face in &mesh.faces {
                write_f32(&mut self.buffer, face.plane_normal[0])?;
                write_f32(&mut self.buffer, face.plane_normal[1])?;
                write_f32(&mut self.buffer, face.plane_normal[2])?;
                write_f32(&mut self.buffer, face.plane_distance)?;
                write_u32(&mut self.buffer, face.surface_id)?;
                write_u16(&mut self.buffer, face.adjacent[0])?;
                write_u16(&mut self.buffer, face.adjacent[1])?;
                write_u16(&mut self.buffer, face.adjacent[2])?;
                write_u16(&mut self.buffer, face.vertex_indices[0])?;
                write_u16(&mut self.buffer, face.vertex_indices[1])?;
                write_u16(&mut self.buffer, face.vertex_indices[2])?;
            }
        }

        // Backpatch face CExoArrayList: ptr, count, alloc
        let save_end = self.buffer.position();
        self.seek_to(mesh_header_pos, mesh_offsets::FACE_ARRAY_OFFSET);
        write_u32(&mut self.buffer, face_offset)?;
        write_u32(&mut self.buffer, face_count)?;
        write_u32(&mut self.buffer, face_count)?; // alloc = count on disk
        self.buffer.set_position(save_end);

        // --- Write TriMesh internal CExoArrayList data payloads ---
        //
        // The 5 CExoArrayLists at +0x98..+0xC8:
        //   +0x98 vertex_indices - dead in KotOR, always zeros
        //   +0xA4 left_over_faces - always empty in vanilla (ptr=0, count=0)
        //   +0xB0 vertex_indices_count - single u32 (face_count*3) or embedded positions
        //   +0xBC mdx_offsets - single u32 content pointer -> packed u16 face indices
        //   +0xC8 index_buffer_pools - single u32 inverted counter
        //
        // Corpus analysis (76,767 meshes): vertex_indices and left_over_faces
        // are ALWAYS ptr=0 in vanilla. Only the last 3 have data payloads.
        //
        // Write ordering for the 3 active arrays: sort by source pointers when
        // available (vanilla-backed), otherwise use default order.
        // Packed u16 face indices are written after all CExoArrayList payloads,
        // then the mdx_offsets placeholder is backpatched to point to them.
        //
        // See `docs/src/formats/models/mesh_derived_fields.md` for full documentation.

        // +0x98: vertex_indices - dead field, always zeros (already zeroed from init).

        // +0xA4: left_over_faces - always empty in vanilla binary files.
        self.backpatch_cexolist(
            mesh_header_pos,
            mesh_offsets::LEFT_OVER_FACES_ARRAY_PTR,
            0,
            0,
            0,
        )?;

        // Write the 3 active CExoArrayList data payloads in canonical order.
        let vertex_count = usize::from(mesh.vertex_count);
        let can_embed_positions = mesh.has_embedded_positions
            && !mesh.positions.is_empty()
            && mesh.positions.len() >= vertex_count;

        let mut vertex_indices_count_data_ptr = 0u32;

        // +0xB0: vertex_indices_count - single u32 (face_count*3) or embedded positions.
        if can_embed_positions {
            let ptr = self.content_position()?;
            vertex_indices_count_data_ptr = ptr;
            write_u32(&mut self.buffer, face_count * 3)?;
            for pos in mesh.positions.iter().take(vertex_count) {
                write_f32(&mut self.buffer, pos[0])?;
                write_f32(&mut self.buffer, pos[1])?;
                write_f32(&mut self.buffer, pos[2])?;
            }
            self.backpatch_cexolist(
                mesh_header_pos,
                mesh_offsets::VERTEX_INDICES_COUNT_ARRAY_PTR,
                ptr,
                1,
                1,
            )?;
        } else if face_count > 0 {
            let ptr = self.content_position()?;
            vertex_indices_count_data_ptr = ptr;
            write_u32(&mut self.buffer, face_count * 3)?;
            self.backpatch_cexolist(
                mesh_header_pos,
                mesh_offsets::VERTEX_INDICES_COUNT_ARRAY_PTR,
                ptr,
                1,
                1,
            )?;
        } else {
            self.backpatch_cexolist(
                mesh_header_pos,
                mesh_offsets::VERTEX_INDICES_COUNT_ARRAY_PTR,
                0,
                0,
                0,
            )?;
        }

        // +0xBC: mdx_offsets - single u32 content pointer to packed u16 face indices.
        if face_count > 0 {
            let ptr = self.content_position()?;
            write_u32(&mut self.buffer, 0)?; // placeholder, backpatched below
            self.backpatch_cexolist(
                mesh_header_pos,
                mesh_offsets::MDX_OFFSETS_ARRAY_PTR,
                ptr,
                1,
                1,
            )?;
        } else {
            self.backpatch_cexolist(
                mesh_header_pos,
                mesh_offsets::MDX_OFFSETS_ARRAY_PTR,
                0,
                0,
                0,
            )?;
        }

        // +0xC8: index_buffer_pools - inverted counter value.
        if mesh.inverted_counter > 0 || face_count > 0 {
            let ptr = self.content_position()?;
            write_u32(&mut self.buffer, mesh.inverted_counter)?;
            self.backpatch_cexolist(
                mesh_header_pos,
                mesh_offsets::INDEX_BUFFER_POOLS_ARRAY_PTR,
                ptr,
                1,
                1,
            )?;
        } else {
            self.backpatch_cexolist(
                mesh_header_pos,
                mesh_offsets::INDEX_BUFFER_POOLS_ARRAY_PTR,
                0,
                0,
                0,
            )?;
        }

        // Write packed u16 face indices after all CExoArrayList payloads,
        // then backpatch the mdx_offsets placeholder to point here.
        if face_count > 0 {
            let packed_ptr = self.content_position()?;
            for face in &mesh.faces {
                write_u16(&mut self.buffer, face.vertex_indices[0])?;
                write_u16(&mut self.buffer, face.vertex_indices[1])?;
                write_u16(&mut self.buffer, face.vertex_indices[2])?;
            }
            self.backpatch_mdx_offsets_data(mesh_header_pos, packed_ptr)?;
        }

        // NOTE: shared_index_offset/pool/size/indices_per_face already written
        // in write_mesh_header() - no need to repeat here.

        let embedded_pos_ptr = if can_embed_positions && vertex_indices_count_data_ptr > 0 {
            Some(vertex_indices_count_data_ptr.saturating_add(4))
        } else {
            None
        };

        Ok(embedded_pos_ptr)
    }

    /// Backpatch a CExoArrayList header (ptr, count, alloc) at a mesh header offset.
    fn backpatch_cexolist(
        &mut self,
        mesh_header_pos: u64,
        ptr_field: usize,
        ptr: u32,
        count: u32,
        alloc: u32,
    ) -> Result<(), MdlError> {
        let save = self.buffer.position();
        self.seek_to(mesh_header_pos, ptr_field);
        write_u32(&mut self.buffer, ptr)?;
        write_u32(&mut self.buffer, count)?;
        write_u32(&mut self.buffer, alloc)?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Backpatch the mdx_offsets (+0xBC) data value to point to packed face indices.
    ///
    /// The mdx_offsets CExoArrayList data is a single u32 containing a
    /// content-relative pointer to the packed u16 face vertex indices.
    /// The data payload was written as a placeholder 0 during the ordering loop.
    fn backpatch_mdx_offsets_data(
        &mut self,
        mesh_header_pos: u64,
        packed_ptr: u32,
    ) -> Result<(), MdlError> {
        // Read the mdx_offsets data pointer from the header.
        let save = self.buffer.position();
        self.seek_to(mesh_header_pos, mesh_offsets::MDX_OFFSETS_ARRAY_PTR);
        let mut ptr_bytes = [0u8; 4];
        std::io::Read::read_exact(&mut self.buffer, &mut ptr_bytes)?;
        let data_ptr = u32::from_le_bytes(ptr_bytes);
        if data_ptr > 0 {
            // Backpatch the placeholder u32 at the data location.
            self.buffer
                .set_position(u64::from(data_ptr) + MDL_WRAPPER_SIZE);
            write_u32(&mut self.buffer, packed_ptr)?;
        }
        self.buffer.set_position(save);
        Ok(())
    }

    /// Writes position-only vertex data into the MDL content blob and backpatches
    /// the mesh header's `mdx_data_offset` field (+0x148) to point to it.
    ///
    /// The binary format stores position data (12 bytes/vertex = 3×f32) within
    /// the MDL content blob, referenced by `mdx_data_offset` which is an MDL
    /// content-relative offset (NOT an MDX file offset). The engine relocates
    /// this pointer against the MDL content base during Reset.
    ///
    /// See `docs/src/internals/mdl_deep_dive.md` "What this means for `mdx_data_offset`".
    fn write_mesh_content_positions(
        &mut self,
        mesh: &super::MdlMesh,
        mesh_header_pos: u64,
        embedded_pos_ptr: Option<u32>,
    ) -> Result<(), MdlError> {
        if let Some(pos_ptr) = embedded_pos_ptr {
            let save = self.buffer.position();
            self.seek_to(mesh_header_pos, mesh_offsets::VERT_ARRAY_OFFSET);
            write_u32(&mut self.buffer, pos_ptr)?;
            self.buffer.set_position(save);
            return Ok(());
        }

        if mesh.positions.is_empty() {
            return Ok(());
        }

        // Write position data into MDL content buffer.
        let pos_start = self.content_position()?; // content-relative

        for pos in &mesh.positions {
            write_f32(&mut self.buffer, pos[0])?;
            write_f32(&mut self.buffer, pos[1])?;
            write_f32(&mut self.buffer, pos[2])?;
        }

        // Backpatch vert_array_offset at mesh header +0x148.
        let save = self.buffer.position();
        self.seek_to(mesh_header_pos, mesh_offsets::VERT_ARRAY_OFFSET);
        write_u32(&mut self.buffer, pos_start)?;
        self.buffer.set_position(save);

        Ok(())
    }

    /// Writes vertex attribute data into the MDX buffer and backpatches the mesh
    /// header's MDX-related fields (stride, flags, attribute offsets).
    ///
    /// Returns the computed stride (bytes per vertex). Returns 0 if no vertex
    /// data was written.
    ///
    /// The canonical layout order follows the engine's `InternalPostProcess`:
    /// position -> normal -> vertex_colors -> UV1 -> UV2 -> UV3 -> UV4 -> tangent_space.
    fn write_mesh_mdx_data(
        &mut self,
        mesh: &super::MdlMesh,
        skin: Option<&super::MdlSkin>,
        mesh_header_pos: u64,
        skin_header_pos: Option<u64>,
    ) -> Result<u32, MdlError> {
        #[derive(Clone, Copy)]
        struct MdxLayout {
            stride: u32,
            flags: u32,
            pos_off: i32,
            norm_off: i32,
            color_off: i32,
            uv1_off: i32,
            uv2_off: i32,
            uv3_off: i32,
            uv4_off: i32,
            tangent_off: i32,
            bone_weights_off: i32,
            bone_indices_off: i32,
        }

        let vertex_count = usize::from(mesh.vertex_count);
        if vertex_count == 0 {
            return Ok(0);
        }

        // Determine the effective vertex count for MDX output.
        //
        // The mesh header declares `vertex_count` which may be larger than
        // the number of vertices there is data for. This happens in vanilla
        // K1 item models such as `i_adrnaline_001`, where the MDX offset
        // points deep into a shared MDX buffer and the reader truncates when
        // data runs out. The writer emits only the vertices with data.
        //
        // All populated attribute arrays must have the same length - if they
        // disagree, that's an actual data error.
        let mut effective_vertex_count = vertex_count;
        macro_rules! clamp_attr {
            ($arr:expr, $name:expr) => {
                if !$arr.is_empty() {
                    if effective_vertex_count == vertex_count {
                        // First populated attribute sets the bound
                        effective_vertex_count = $arr.len();
                    } else if $arr.len() != effective_vertex_count {
                        return Err(MdlError::InvalidData(format!(
                            "mesh {}: {} has {} elements but {} has {}",
                            $name,
                            stringify!($arr),
                            $arr.len(),
                            "other attribute",
                            effective_vertex_count
                        )));
                    }
                }
            };
        }
        clamp_attr!(mesh.positions, "positions");
        clamp_attr!(mesh.normals, "normals");
        clamp_attr!(mesh.vertex_colors, "vertex_colors");
        clamp_attr!(mesh.uv1, "uv1");
        clamp_attr!(mesh.uv2, "uv2");
        clamp_attr!(mesh.uv3, "uv3");
        clamp_attr!(mesh.uv4, "uv4");
        clamp_attr!(mesh.tangent_space, "tangent_space");
        if let Some(s) = skin {
            clamp_attr!(s.bone_weights, "bone_weights");
            clamp_attr!(s.bone_indices, "bone_indices");
        }

        // Determine which attributes are present.
        let has_pos = !mesh.positions.is_empty();
        let has_norm = !mesh.normals.is_empty();
        let has_color = !mesh.vertex_colors.is_empty();
        let has_uv1 = !mesh.uv1.is_empty();
        let has_uv2 = !mesh.uv2.is_empty();
        let has_uv3 = !mesh.uv3.is_empty();
        let has_uv4 = !mesh.uv4.is_empty();
        let has_tangent = !mesh.tangent_space.is_empty();
        let has_bone_weights = skin.is_some_and(|s| !s.bone_weights.is_empty());
        let has_bone_indices = skin.is_some_and(|s| !s.bone_indices.is_empty());

        // Compute canonical layout: position -> normal -> color -> UV1..4 -> tangent -> bone weights -> bone indices.
        // Each attribute gets a byte offset within the per-vertex stride.
        let mut current_byte = 0u32;

        let pos_off: i32 = if has_pos {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 12;
            o
        } else {
            -1
        };
        let norm_off: i32 = if has_norm {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 12;
            o
        } else {
            -1
        };
        let color_off: i32 = if has_color {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 4;
            o
        } else {
            -1
        };
        let uv1_off: i32 = if has_uv1 {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 8;
            o
        } else {
            -1
        };
        let uv2_off: i32 = if has_uv2 {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 8;
            o
        } else {
            -1
        };
        let uv3_off: i32 = if has_uv3 {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 8;
            o
        } else {
            -1
        };
        let uv4_off: i32 = if has_uv4 {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 8;
            o
        } else {
            -1
        };
        let tangent_off: i32 = if has_tangent {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 36;
            o
        } else {
            -1
        };
        let bone_weights_off: i32 = if has_bone_weights {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 16;
            o
        } else {
            -1
        };
        let bone_indices_off: i32 = if has_bone_indices {
            let o = i32::try_from(current_byte)
                .map_err(|_| MdlError::ValueOverflow("mdx_attribute_offset"))?;
            current_byte += 16;
            o
        } else {
            -1
        };

        let canonical_stride = current_byte;

        // Compute flags (vertex colors have no flag bit - presence is
        // determined by offset != -1, per InternalPostProcess evidence).
        let mut canonical_flags = 0u32;
        if has_pos {
            canonical_flags |= 0x01;
        }
        if has_norm {
            canonical_flags |= 0x20;
        }
        if has_uv1 {
            canonical_flags |= 0x02;
        }
        if has_uv2 {
            canonical_flags |= 0x04;
        }
        if has_uv3 {
            canonical_flags |= 0x08;
        }
        if has_uv4 {
            canonical_flags |= 0x10;
        }
        if has_tangent {
            canonical_flags |= 0x80;
        }

        let layout = MdxLayout {
            stride: canonical_stride,
            flags: canonical_flags,
            pos_off,
            norm_off,
            color_off,
            uv1_off,
            uv2_off,
            uv3_off,
            uv4_off,
            tangent_off,
            bone_weights_off,
            bone_indices_off,
        };

        if layout.stride == 0 {
            return Ok(0); // No attributes to write
        }

        // Canonical interleaved write: position -> normal -> color -> UV1..4 -> tangent -> bone weights -> bone indices.
        for i in 0..effective_vertex_count {
            if has_pos {
                let p = &mesh.positions[i];
                write_f32(&mut self.mdx_buffer, p[0])?;
                write_f32(&mut self.mdx_buffer, p[1])?;
                write_f32(&mut self.mdx_buffer, p[2])?;
            }
            if has_norm {
                let n = &mesh.normals[i];
                write_f32(&mut self.mdx_buffer, n[0])?;
                write_f32(&mut self.mdx_buffer, n[1])?;
                write_f32(&mut self.mdx_buffer, n[2])?;
            }
            if has_color {
                let c = &mesh.vertex_colors[i];
                self.mdx_buffer.write_all(c)?;
            }
            if has_uv1 {
                let u = &mesh.uv1[i];
                write_f32(&mut self.mdx_buffer, u[0])?;
                write_f32(&mut self.mdx_buffer, u[1])?;
            }
            if has_uv2 {
                let u = &mesh.uv2[i];
                write_f32(&mut self.mdx_buffer, u[0])?;
                write_f32(&mut self.mdx_buffer, u[1])?;
            }
            if has_uv3 {
                let u = &mesh.uv3[i];
                write_f32(&mut self.mdx_buffer, u[0])?;
                write_f32(&mut self.mdx_buffer, u[1])?;
            }
            if has_uv4 {
                let u = &mesh.uv4[i];
                write_f32(&mut self.mdx_buffer, u[0])?;
                write_f32(&mut self.mdx_buffer, u[1])?;
            }
            if has_tangent {
                let t = &mesh.tangent_space[i];
                for row in t {
                    write_f32(&mut self.mdx_buffer, row[0])?;
                    write_f32(&mut self.mdx_buffer, row[1])?;
                    write_f32(&mut self.mdx_buffer, row[2])?;
                }
            }
            if has_bone_weights {
                // skin is guaranteed Some when has_bone_weights is true.
                let bw = &skin
                    .expect("has_bone_weights implies skin is Some")
                    .bone_weights[i];
                write_f32(&mut self.mdx_buffer, bw[0])?;
                write_f32(&mut self.mdx_buffer, bw[1])?;
                write_f32(&mut self.mdx_buffer, bw[2])?;
                write_f32(&mut self.mdx_buffer, bw[3])?;
            }
            if has_bone_indices {
                // skin is guaranteed Some when has_bone_indices is true.
                let bi = &skin
                    .expect("has_bone_indices implies skin is Some")
                    .bone_indices[i];
                write_f32(&mut self.mdx_buffer, bi[0])?;
                write_f32(&mut self.mdx_buffer, bi[1])?;
                write_f32(&mut self.mdx_buffer, bi[2])?;
                write_f32(&mut self.mdx_buffer, bi[3])?;
            }
        }

        // Backpatch mesh header with MDX layout fields.
        let save = self.buffer.position();

        // Stride at +0xFC
        self.seek_to(mesh_header_pos, mesh_offsets::VERTEX_STRUCT_SIZE);
        write_u32(&mut self.buffer, layout.stride)?;

        // Flags at +0x100
        self.seek_to(mesh_header_pos, mesh_offsets::MDX_VERTEX_FLAGS);
        write_u32(&mut self.buffer, layout.flags)?;

        // Per-attribute byte offsets at +0x104..+0x120 (contiguous)
        self.seek_to(mesh_header_pos, mesh_offsets::MDX_POSITION_OFFSET);
        write_i32(&mut self.buffer, layout.pos_off)?;
        write_i32(&mut self.buffer, layout.norm_off)?;
        write_i32(&mut self.buffer, layout.color_off)?;
        write_i32(&mut self.buffer, layout.uv1_off)?;
        write_i32(&mut self.buffer, layout.uv2_off)?;
        write_i32(&mut self.buffer, layout.uv3_off)?;
        write_i32(&mut self.buffer, layout.uv4_off)?;
        write_i32(&mut self.buffer, layout.tangent_off)?;

        // NOTE: mdx_data_offset (+0x148) is backpatched by write_deferred_mdx()
        // with the MDX file offset, not set here. When not writing MDX, it's
        // backpatched by write_mesh_content_positions() with MDL content offset.

        // Backpatch skin header bone weight/index offsets with the canonical
        // layout values computed above (the initial values from write_skin_header
        // may differ when the source model used a different attribute ordering).
        if let Some(shp) = skin_header_pos {
            self.write_i32_at(
                shp,
                skin_offsets::MDX_BONE_WEIGHTS_OFFSET,
                layout.bone_weights_off,
            )?;
            self.write_i32_at(
                shp,
                skin_offsets::MDX_BONE_INDICES_OFFSET,
                layout.bone_indices_off,
            )?;
        }

        self.buffer.set_position(save);
        Ok(layout.stride)
    }

    /// Writes a per-mesh terminator row into the MDX buffer.
    ///
    /// BioWare's build tools emit one stride-sized row of sentinel floats after
    /// each mesh's vertex data, followed by zero-padding to the next 16-byte
    /// boundary. Non-skin meshes use 10,000,000.0 as the sentinel; skin meshes
    /// use 1,000,000.0.
    ///
    /// See `docs/src/internals/mdl_deep_dive.md` "Per-mesh terminators and alignment".
    fn write_mdx_terminator(&mut self, stride: u32, is_skin: bool) -> Result<(), MdlError> {
        if stride == 0 {
            return Ok(());
        }

        let stride = usize::try_from(stride).expect("u32 stride fits in usize");
        let sentinel: f32 = if is_skin { 1_000_000.0 } else { 10_000_000.0 };

        // Write 3× sentinel float (position-like xyz), then zero-fill remaining bytes.
        write_f32(&mut self.mdx_buffer, sentinel)?;
        write_f32(&mut self.mdx_buffer, sentinel)?;
        write_f32(&mut self.mdx_buffer, sentinel)?;

        // Fill the rest of the stride with zeros.
        let remaining = stride.saturating_sub(12);
        if remaining > 0 {
            let zeros = vec![0u8; remaining];
            self.mdx_buffer.write_all(&zeros)?;
        }

        // Save position before alignment - the final mesh's padding will be
        // trimmed by truncating to this position after all nodes are written.
        self.mdx_pre_align_pos = self.mdx_buffer.position();

        // Pad to 16-byte alignment (will be trimmed for the last mesh).
        let pos =
            usize::try_from(self.mdx_buffer.position()).expect("mdx buffer position fits in usize");
        let aligned = (pos + 15) & !15;
        let pad = aligned - pos;
        if pad > 0 {
            let zeros = vec![0u8; pad];
            self.mdx_buffer.write_all(&zeros)?;
        }

        Ok(())
    }

    /// Writes the 100-byte Skin extra header from typed fields.
    ///
    /// Emits 100 zero bytes then backpatches the inline scalar fields:
    /// MDX bone weight/index offsets (+0x0C/+0x10) and bone_node_numbers (+0x40).
    /// CExoArrayList pointers are backpatched later by [`write_skin_arrays`].
    fn write_skin_header(&mut self, skin: &super::MdlSkin) -> Result<u64, MdlError> {
        let header_pos = self.buffer.position();
        self.buffer.write_all(&[0u8; SKIN_EXTRA_SIZE])?;

        let save = self.buffer.position();

        // MDX bone weight/index offsets at +0x0C/+0x10.
        self.write_i32_at(
            header_pos,
            skin_offsets::MDX_BONE_WEIGHTS_OFFSET,
            skin.mdx_bone_weights_offset,
        )?;
        self.write_i32_at(
            header_pos,
            skin_offsets::MDX_BONE_INDICES_OFFSET,
            skin.mdx_bone_indices_offset,
        )?;

        // bone_node_numbers: 16 × u16 at +0x40.
        self.seek_to(header_pos, skin_offsets::BONE_NODE_NUMBERS);
        for &n in &skin.bone_node_numbers {
            write_u16(&mut self.buffer, n)?;
        }

        // +0x60..+0x63: Padding - write zeros (vanilla has leaked pointers here
        // in ~74 models, but the engine never reads this field).

        self.buffer.set_position(save);
        Ok(header_pos)
    }

    /// Writes the skin data arrays and backpatches the skin header pointers.
    fn write_skin_arrays(
        &mut self,
        skin: &super::MdlSkin,
        skin_header_pos: u64,
    ) -> Result<(), MdlError> {
        // Write bonemap (+0x14 pointer, +0x18 count).
        let bonemap_count = count_u32(skin.bonemap.len(), "bonemap_count")?;
        let mut bonemap_ptr = 0u32;
        if bonemap_count > 0 {
            bonemap_ptr = self.content_position()?;
            for &idx in &skin.bonemap {
                write_u32(&mut self.buffer, idx)?;
            }
        }

        // Write qbone_ref_inv (Quaternion = 4 × f32 each)
        let qbone_count = count_u32(skin.qbone_ref_inv.len(), "qbone_count")?;
        let mut qbone_ptr = 0u32;
        if qbone_count > 0 {
            qbone_ptr = self.content_position()?;
            for q in &skin.qbone_ref_inv {
                write_f32(&mut self.buffer, q[0])?;
                write_f32(&mut self.buffer, q[1])?;
                write_f32(&mut self.buffer, q[2])?;
                write_f32(&mut self.buffer, q[3])?;
            }
        }

        // Write tbone_ref_inv (Vector = 3 × f32 each)
        let tbone_count = count_u32(skin.tbone_ref_inv.len(), "tbone_count")?;
        let mut tbone_ptr = 0u32;
        if tbone_count > 0 {
            tbone_ptr = self.content_position()?;
            for t in &skin.tbone_ref_inv {
                write_f32(&mut self.buffer, t[0])?;
                write_f32(&mut self.buffer, t[1])?;
                write_f32(&mut self.buffer, t[2])?;
            }
        }

        // Write bone_constant_indices (i32 each)
        let bone_idx_count = count_u32(skin.bone_constant_indices.len(), "bone_idx_count")?;
        let mut bone_idx_ptr = 0u32;
        if bone_idx_count > 0 {
            bone_idx_ptr = self.content_position()?;
            for &idx in &skin.bone_constant_indices {
                write_i32(&mut self.buffer, idx)?;
            }
        }

        // Backpatch CExoArrayList headers: ptr, count, alloc
        let save_end = self.buffer.position();

        // Weights CExoArrayList at +0x00: always zeros in binary files (already zeroed from init).

        // bonemap pointer/count at +0x14/+0x18
        self.seek_to(skin_header_pos, skin_offsets::BONEMAP_PTR);
        write_u32(&mut self.buffer, bonemap_ptr)?;
        write_u32(&mut self.buffer, bonemap_count)?;

        // qbone_ref_inv at skin extra +0x1C
        self.seek_to(skin_header_pos, skin_offsets::QBONE_REF_INV_PTR);
        write_u32(&mut self.buffer, qbone_ptr)?;
        write_u32(&mut self.buffer, qbone_count)?;
        write_u32(&mut self.buffer, qbone_count)?; // alloc = count on disk

        // tbone_ref_inv at skin extra +0x28
        self.seek_to(skin_header_pos, skin_offsets::TBONE_REF_INV_PTR);
        write_u32(&mut self.buffer, tbone_ptr)?;
        write_u32(&mut self.buffer, tbone_count)?;
        write_u32(&mut self.buffer, tbone_count)?; // alloc = count on disk

        // bone_constant_indices at skin extra +0x34
        self.seek_to(skin_header_pos, skin_offsets::BONE_CONSTANT_INDICES_PTR);
        write_u32(&mut self.buffer, bone_idx_ptr)?;
        write_u32(&mut self.buffer, bone_idx_count)?;
        write_u32(&mut self.buffer, bone_idx_count)?; // alloc = count on disk

        self.buffer.set_position(save_end);
        Ok(())
    }

    /// Writes the 56-byte AnimMesh extra header from typed fields.
    ///
    /// Returns the header position for deferred backpatching of the two
    /// CExoArrayList pointers by [`write_anim_mesh_arrays`].
    fn write_anim_mesh_header(&mut self, anim: &super::MdlAnimMesh) -> Result<u64, MdlError> {
        let header_pos = self.buffer.position();

        // Write 56 zero bytes as base, then backpatch typed fields.
        self.buffer.write_all(&[0u8; ANIM_MESH_EXTRA_SIZE])?;
        let save = self.buffer.position();

        // sample_period at +0x00
        self.write_f32_at(
            header_pos,
            anim_mesh_offsets::SAMPLE_PERIOD,
            anim.sample_period,
        )?;
        // CExoArrayList pointers at +0x04 and +0x10 are backpatched by write_anim_mesh_arrays.

        // Runtime-only fields at +0x1C..+0x37 (always zero in authored files,
        // preserved for roundtrip fidelity).
        self.write_u32_at(header_pos, anim_mesh_offsets::DATA_PTR_1, anim.data_ptr_1)?;
        self.write_u32_at(
            header_pos,
            anim_mesh_offsets::DATA_COUNT_1,
            anim.data_count_1,
        )?;
        self.write_u32_at(header_pos, anim_mesh_offsets::PADDING_24, anim.padding_24)?;
        self.write_u32_at(
            header_pos,
            anim_mesh_offsets::ANIM_VERTICES_PTR,
            anim.anim_vertices_ptr,
        )?;
        self.write_u32_at(
            header_pos,
            anim_mesh_offsets::ANIM_TEX_VERTICES_PTR,
            anim.anim_tex_vertices_ptr,
        )?;
        self.write_u32_at(
            header_pos,
            anim_mesh_offsets::ANIM_VERTICES_COUNT,
            anim.anim_vertices_count,
        )?;
        self.write_u32_at(
            header_pos,
            anim_mesh_offsets::ANIM_TEX_VERTICES_COUNT,
            anim.anim_tex_vertices_count,
        )?;

        self.buffer.set_position(save);
        Ok(header_pos)
    }

    /// Writes the two animated vertex arrays and backpatches the anim header pointers.
    fn write_anim_mesh_arrays(
        &mut self,
        anim: &super::MdlAnimMesh,
        anim_header_pos: u64,
    ) -> Result<(), MdlError> {
        // Write anim_verts (Vector = 3 × f32 each)
        let anim_verts_count = count_u32(anim.anim_verts.len(), "anim_verts_count")?;
        let mut anim_verts_ptr = 0u32;
        if anim_verts_count > 0 {
            anim_verts_ptr = self.content_position()?;
            for v in &anim.anim_verts {
                write_f32(&mut self.buffer, v[0])?;
                write_f32(&mut self.buffer, v[1])?;
                write_f32(&mut self.buffer, v[2])?;
            }
        }

        // Write anim_t_verts (Vector = 3 × f32 each)
        let anim_t_verts_count = count_u32(anim.anim_t_verts.len(), "anim_t_verts_count")?;
        let mut anim_t_verts_ptr = 0u32;
        if anim_t_verts_count > 0 {
            anim_t_verts_ptr = self.content_position()?;
            for v in &anim.anim_t_verts {
                write_f32(&mut self.buffer, v[0])?;
                write_f32(&mut self.buffer, v[1])?;
                write_f32(&mut self.buffer, v[2])?;
            }
        }

        // Backpatch CExoArrayList headers: ptr, count, alloc
        let save_end = self.buffer.position();

        // anim_verts at anim extra +0x04
        self.seek_to(anim_header_pos, anim_mesh_offsets::ANIM_VERTS_PTR);
        write_u32(&mut self.buffer, anim_verts_ptr)?;
        write_u32(&mut self.buffer, anim_verts_count)?;
        write_u32(&mut self.buffer, anim_verts_count)?; // alloc = count on disk

        // anim_t_verts at anim extra +0x10
        self.seek_to(anim_header_pos, anim_mesh_offsets::ANIM_T_VERTS_PTR);
        write_u32(&mut self.buffer, anim_t_verts_ptr)?;
        write_u32(&mut self.buffer, anim_t_verts_count)?;
        write_u32(&mut self.buffer, anim_t_verts_count)?; // alloc = count on disk

        self.buffer.set_position(save_end);
        Ok(())
    }

    fn write_controllers(
        &mut self,
        controllers: &[MdlController],
        orphan_data: &[f32],
    ) -> Result<(u32, u32, u32, u32), MdlError> {
        if controllers.is_empty() && orphan_data.is_empty() {
            return Ok((0, 0, 0, 0));
        }

        // Orphan data: key_count=0 but data_count>0. Write the data array
        // only so the engine sees the same data_ptr/data_count header values.
        if controllers.is_empty() {
            let data_ptr = self.content_position()?;
            for &val in orphan_data {
                write_f32(&mut self.buffer, val)?;
            }
            return Ok((
                0,
                0,
                data_ptr,
                count_u32(orphan_data.len(), "orphan_data_count")?,
            ));
        }

        let key_ptr = self.content_position()?;
        let key_count = count_u32(controllers.len(), "controller_count")?;

        // Reserve headers
        let headers_start = self.buffer.position();
        self.buffer.write_all(&vec![
            0u8;
            usize::try_from(key_count)
                .expect("key_count fits in usize")
                * 16
        ])?;

        // Build flat data array
        let mut master_float_data = Vec::new();
        let mut controller_indices = Vec::new(); // (time_idx, data_idx)

        for c in controllers {
            let time_idx = master_float_data.len();
            for key in &c.keys {
                master_float_data.push(key.time);
            }

            let data_idx = master_float_data.len();
            for key in &c.keys {
                master_float_data.extend_from_slice(&key.values);
            }

            controller_indices.push((time_idx, data_idx));
        }

        // Write Float Data
        let data_start_pos = headers_start + u64::from(key_count) * 16;
        self.buffer.set_position(data_start_pos);

        let real_data_ptr = u32::try_from(
            data_start_pos
                .checked_sub(MDL_WRAPPER_SIZE)
                .ok_or(MdlError::ValueOverflow("ctrl_data_position underflow"))?,
        )
        .map_err(|_| MdlError::ValueOverflow("ctrl_data_position"))?;

        for val in &master_float_data {
            write_f32(&mut self.buffer, *val)?;
        }
        let real_data_count = count_u32(master_float_data.len(), "controller_data_count")?;

        // Fill Headers
        let final_end = self.buffer.position();
        self.buffer.set_position(headers_start);

        for (i, c) in controllers.iter().enumerate() {
            let row_count = count_u16(c.keys.len(), "key_row_count")?;
            let (t_idx, d_idx) = controller_indices[i];

            write_u32(&mut self.buffer, c.controller_type.raw())?; // 0x00

            // 0x04: Unknown(2) + RowCount(2)
            self.buffer.write_all(&c.key_unknown_04)?;
            write_u16(&mut self.buffer, row_count)?;

            // 0x08: TimeIndex(2) + DataIndex(2)
            write_u16(
                &mut self.buffer,
                u16::try_from(t_idx).map_err(|_| MdlError::ValueOverflow("time_index"))?,
            )?;
            write_u16(
                &mut self.buffer,
                u16::try_from(d_idx).map_err(|_| MdlError::ValueOverflow("data_index"))?,
            )?;

            // 0x0C: ColumnCount(1) + Unknown(3)
            // Use the raw column_count byte (preserves Bezier flag and
            // integral orientation encoding) rather than deriving from
            // values.len(), which would lose the flag bits.
            self.buffer.write_all(&[c.raw_column_count])?;
            self.buffer.write_all(&c.key_unknown_0d)?;
        }

        self.buffer.set_position(final_end);

        Ok((key_ptr, key_count, real_data_ptr, real_data_count))
    }

    /// Writes a Light node header (92 bytes) with placeholder CExoArray pointers.
    ///
    /// Returns the header start position for backpatching by `write_light_arrays`.
    /// The 5 CExoArrayList headers at +0x04..+0x3F are written as zeros here;
    /// the actual data pointers are backpatched after array payloads are emitted.
    fn write_light_header(&mut self, light: &super::MdlLight) -> Result<u64, MdlError> {
        let header_pos = self.buffer.position();

        // Write 92 bytes of zeros as base, then backpatch typed fields.
        self.buffer.write_all(&[0u8; LIGHT_EXTRA_SIZE])?;

        // flare_radius: f32 at +0x00
        self.write_f32_at(header_pos, light_offsets::FLARE_RADIUS, light.flare_radius)?;

        // texture_safe_ptrs: 3×u32 at +0x04 (runtime-only, preserved for roundtrip)
        let sp_off = light_offsets::TEXTURE_SAFE_PTRS_PTR;
        self.write_u32_at(header_pos, sp_off, light.texture_safe_ptrs[0])?;
        self.write_u32_at(header_pos, sp_off + 4, light.texture_safe_ptrs[1])?;
        self.write_u32_at(header_pos, sp_off + 8, light.texture_safe_ptrs[2])?;

        // CExoArrayList headers at +0x10..+0x3F left as zeros (backpatched in write_light_arrays)

        // Scalar fields at +0x40..+0x5C
        self.write_i32_at(header_pos, light_offsets::PRIORITY, light.priority)?;
        self.write_i32_at(
            header_pos,
            light_offsets::NUM_DYNAMIC_TYPES,
            light.num_dynamic_types,
        )?;
        self.write_i32_at(
            header_pos,
            light_offsets::AFFECTDYNAMIC,
            light.affectdynamic,
        )?;
        self.write_i32_at(header_pos, light_offsets::SHADOW, light.shadow)?;
        self.write_i32_at(header_pos, light_offsets::AMBIENTONLY, light.ambientonly)?;
        self.write_i32_at(
            header_pos,
            light_offsets::GENERATEFLARE,
            light.generateflare,
        )?;
        self.write_i32_at(header_pos, light_offsets::FADING_LIGHT, light.fading_light)?;

        Ok(header_pos)
    }

    /// Writes Light flare data arrays and backpatches CExoArrayList pointers.
    ///
    /// Four CExoArrayList payloads are written:
    /// - flare_sizes: `Vec<f32>` (4 bytes each)
    /// - flare_positions: `Vec<f32>` (4 bytes each)
    /// - flare_color_shifts: `Vec<[f32; 3]>` (12 bytes each)
    /// - flare_texture_names: `Vec<String>` as pointer-to-pointer chain
    ///
    /// Each payload writes data, then backpatches the CExoArrayList header
    /// (ptr, count, alloc=count) in the light extra header.
    fn write_light_arrays(
        &mut self,
        light: &super::MdlLight,
        header_pos: u64,
    ) -> Result<(), MdlError> {
        // Helper: write a CExoArrayList header (ptr + count + alloc) into the light header.
        let write_cexo_header = |writer: &mut Self,
                                 ptr_offset: usize,
                                 data_ptr: u32,
                                 count: u32|
         -> Result<(), MdlError> {
            writer.write_u32_at(header_pos, ptr_offset, data_ptr)?;
            writer.write_u32_at(header_pos, ptr_offset + 4, count)?;
            // alloc = count (ptr_offset + 8)
            writer.write_u32_at(header_pos, ptr_offset + 8, count)?;
            Ok(())
        };

        // Flare sizes: CExoArrayList<float> at +0x10
        let count = count_u32(light.flare_sizes.len(), "flare_sizes_count")?;
        if count > 0 {
            let data_ptr = self.content_position()?; // content-relative
            for &size in &light.flare_sizes {
                write_f32(&mut self.buffer, size)?;
            }
            write_cexo_header(self, light_offsets::FLARE_SIZES_PTR, data_ptr, count)?;
        }

        // Flare positions: CExoArrayList<float> at +0x1C
        let count = count_u32(light.flare_positions.len(), "flare_positions_count")?;
        if count > 0 {
            let data_ptr = self.content_position()?; // content-relative
            for &pos in &light.flare_positions {
                write_f32(&mut self.buffer, pos)?;
            }
            write_cexo_header(self, light_offsets::FLARE_POSITIONS_PTR, data_ptr, count)?;
        }

        // Flare color shifts: CExoArrayList<Vector> at +0x28
        let count = count_u32(light.flare_color_shifts.len(), "flare_color_shifts_count")?;
        if count > 0 {
            let data_ptr = self.content_position()?; // content-relative
            for shift in &light.flare_color_shifts {
                write_f32(&mut self.buffer, shift[0])?;
                write_f32(&mut self.buffer, shift[1])?;
                write_f32(&mut self.buffer, shift[2])?;
            }
            write_cexo_header(self, light_offsets::FLARE_COLOR_SHIFTS_PTR, data_ptr, count)?;
        }

        // Flare texture names: CExoArrayList<char*> at +0x34
        // Each entry is a u32 content-relative pointer to a null-terminated string.
        let count = count_u32(light.flare_texture_names.len(), "flare_tex_names_count")?;
        if count > 0 {
            // Phase 1: Write the pointer array (u32 per name)
            let ptr_array_pos = self.buffer.position();
            let ptr_array_content_rel = self.content_position()?;
            // Write placeholder pointers
            for _ in 0..count {
                write_u32(&mut self.buffer, 0)?;
            }

            // Phase 2: Write each string and backpatch its pointer
            for (i, name) in light.flare_texture_names.iter().enumerate() {
                let str_ptr = self.content_position()?; // content-relative
                                                        // Write null-terminated string
                self.buffer.write_all(name.as_bytes())?;
                self.buffer.write_all(&[0])?; // null terminator

                // Backpatch the pointer
                let save = self.buffer.position();
                self.seek_to(ptr_array_pos, i * 4);
                write_u32(&mut self.buffer, str_ptr)?;
                self.buffer.set_position(save);
            }

            write_cexo_header(
                self,
                light_offsets::FLARE_TEX_NAMES_PTR,
                ptr_array_content_rel,
                count,
            )?;
        }

        Ok(())
    }

    /// Writes a Reference node header (36 bytes).
    fn write_reference_header(&mut self, reference: &super::MdlReference) -> Result<(), MdlError> {
        // ref_model: char[32] at +0x00
        self.write_fixed_string(&reference.ref_model, 32)?;
        // reattachable: i32 at +0x20
        write_i32(&mut self.buffer, reference.reattachable)?;
        Ok(())
    }

    /// Writes an Emitter node header (224 bytes).
    fn write_emitter_header(&mut self, emitter: &super::MdlEmitter) -> Result<(), MdlError> {
        // Scalars: +0x00..+0x20 (8 fields × 4 bytes = 32 bytes)
        write_f32(&mut self.buffer, emitter.deadspace)?;
        write_f32(&mut self.buffer, emitter.blast_radius)?;
        write_f32(&mut self.buffer, emitter.blast_length)?;
        write_i32(&mut self.buffer, emitter.num_branches)?;
        write_i32(&mut self.buffer, emitter.control_pt_smoothing)?;
        write_i32(&mut self.buffer, emitter.x_grid)?;
        write_i32(&mut self.buffer, emitter.y_grid)?;
        write_i32(&mut self.buffer, emitter.spawn_type)?;

        // Strings: 4 × char[32] + 1 × char[16] = 144 bytes
        self.write_fixed_string(&emitter.update, 32)?; // +0x20
        self.write_fixed_string(&emitter.render, 32)?; // +0x40
        self.write_fixed_string(&emitter.blend, 32)?; // +0x60
        self.write_fixed_string(&emitter.texture, 32)?; // +0x80
        self.write_fixed_string(&emitter.chunk_name, 16)?; // +0xA0

        // Trailing scalars: +0xB0..+0xBB (10 bytes)
        write_i32(&mut self.buffer, emitter.two_sided_tex)?;
        write_i32(&mut self.buffer, emitter.loop_emitter)?;
        write_u16(&mut self.buffer, emitter.render_order)?;
        self.buffer
            .write_all(&[if emitter.frame_blending { 1 } else { 0 }])?;

        // depth_texture_name: char[16] at +0xBB
        self.write_fixed_string(&emitter.depth_texture_name, 16)?;

        // Reserved: 21 bytes at +0xCB..+0xE0 - write verbatim
        self.buffer.write_all(&emitter.reserved)?;

        Ok(())
    }

    /// Writes the 28-byte DanglyMesh extra header (inline scalars only).
    ///
    /// Returns the header position for deferred backpatching of the constraint
    /// array pointer by [`write_dangly_arrays`].
    fn write_dangly_header(&mut self, dangly: &super::MdlDangly) -> Result<u64, MdlError> {
        let header_pos = self.buffer.position();

        // Write 28 zero bytes as base, then fill typed fields.
        // CExoArrayList (ptr/count/alloc at +0x00) and data pointer (+0x18)
        // are backpatched by write_dangly_arrays and write_dangly_pre_mesh_payload.
        self.buffer.write_all(&[0u8; DANGLY_EXTRA_SIZE])?;

        let save = self.buffer.position();
        self.seek_to(header_pos, dangly_offsets::DISPLACEMENT);
        write_f32(&mut self.buffer, dangly.displacement)?;
        write_f32(&mut self.buffer, dangly.tightness)?;
        write_f32(&mut self.buffer, dangly.period)?;
        self.buffer.set_position(save);

        Ok(header_pos)
    }

    /// Writes the dangly per-vertex positions (+0x18 pointer) before TriMesh arrays.
    ///
    /// Emits `vertex_count` vec3 positions (12 bytes each), then backpatches the
    /// content-relative pointer at dangly extra +0x18.
    fn write_dangly_pre_mesh_payload(
        &mut self,
        dangly: &super::MdlDangly,
        dangly_header_pos: u64,
    ) -> Result<(), MdlError> {
        let ptr = if !dangly.dangly_vertices.is_empty() {
            let p = self.content_position()?;
            for v in &dangly.dangly_vertices {
                write_f32(&mut self.buffer, v[0])?;
                write_f32(&mut self.buffer, v[1])?;
                write_f32(&mut self.buffer, v[2])?;
            }
            p
        } else {
            0
        };

        self.write_u32_at(dangly_header_pos, dangly_offsets::DATA_PTR, ptr)?;
        Ok(())
    }

    /// Writes the constraint float array and backpatches the dangly header pointer.
    fn write_dangly_arrays(
        &mut self,
        dangly: &super::MdlDangly,
        dangly_header_pos: u64,
    ) -> Result<(), MdlError> {
        let constraints_count = count_u32(dangly.constraints.len(), "constraints_count")?;
        let mut constraints_ptr = 0u32;

        if constraints_count > 0 {
            constraints_ptr = self.content_position()?;
            for &val in &dangly.constraints {
                write_f32(&mut self.buffer, val)?;
            }
        }

        // Backpatch CExoArrayList: ptr, count, alloc
        let save_end = self.buffer.position();
        self.seek_to(dangly_header_pos, dangly_offsets::CONSTRAINTS_PTR);
        write_u32(&mut self.buffer, constraints_ptr)?;
        write_u32(&mut self.buffer, constraints_count)?;
        write_u32(&mut self.buffer, constraints_count)?; // alloc = count on disk
        self.buffer.set_position(save_end);

        Ok(())
    }

    /// Writes the 4-byte AABB extra header (placeholder for tree root pointer).
    ///
    /// The root pointer is backpatched by [`write_aabb_arrays`] after the tree
    /// payload has been emitted.
    fn write_aabb_header(&mut self) -> Result<u64, MdlError> {
        let header_pos = self.buffer.position();
        self.buffer.write_all(&[0u8; AABB_EXTRA_SIZE])?;
        Ok(header_pos)
    }

    /// Writes the AABB tree payload and backpatches the root pointer in the header.
    fn write_aabb_arrays(
        &mut self,
        aabb: &super::MdlAabb,
        aabb_header_pos: u64,
    ) -> Result<(), MdlError> {
        let ptr = if let Some(tree) = &aabb.aabb_tree {
            self.write_aabb_tree(tree)?
        } else {
            0
        };

        let save = self.buffer.position();
        self.seek_to(aabb_header_pos, aabb_offsets::TREE_PTR);
        write_u32(&mut self.buffer, ptr)?;
        self.buffer.set_position(save);
        Ok(())
    }

    /// Recursively writes an AABB tree node in DFS preorder (matching mdledit).
    ///
    /// Returns the content-relative offset of the written node. Child pointers
    /// are backpatched after each subtree is written.
    fn write_aabb_tree(&mut self, node: &super::AabbNode) -> Result<u32, MdlError> {
        let node_ptr = self.content_position()?; // content-relative

        // Bounding box (24 bytes)
        for &v in &node.box_min {
            write_f32(&mut self.buffer, v)?;
        }
        for &v in &node.box_max {
            write_f32(&mut self.buffer, v)?;
        }

        // Placeholder child pointers: right at +0x18, left at +0x1C
        let right_ph = self.buffer.position();
        write_u32(&mut self.buffer, 0)?;
        let left_ph = self.buffer.position();
        write_u32(&mut self.buffer, 0)?;

        // Face index and split direction flags
        write_i32(&mut self.buffer, node.face_index)?;
        write_u32(&mut self.buffer, node.split_direction_flags)?;

        // Recurse left child, backpatch pointer
        if let Some(left) = &node.left {
            let left_ptr = self.write_aabb_tree(left)?;
            let save = self.buffer.position();
            self.buffer.set_position(left_ph);
            write_u32(&mut self.buffer, left_ptr)?;
            self.buffer.set_position(save);
        }

        // Recurse right child, backpatch pointer
        if let Some(right) = &node.right {
            let right_ptr = self.write_aabb_tree(right)?;
            let save = self.buffer.position();
            self.buffer.set_position(right_ph);
            write_u32(&mut self.buffer, right_ptr)?;
            self.buffer.set_position(save);
        }

        Ok(node_ptr)
    }

    /// Writes the 20-byte Saber extra header from typed fields.
    ///
    /// Data pointers are placeholders (backpatched by [`write_saber_arrays`]).
    /// GL pool IDs are preserved for roundtrip fidelity (runtime-only values).
    fn write_saber_header(&mut self, saber: &super::MdlSaber) -> Result<u64, MdlError> {
        let header_pos = self.buffer.position();

        // Write 20 zero bytes as base, then backpatch GL pool IDs.
        self.buffer.write_all(&[0u8; SABER_EXTRA_SIZE])?;
        let save = self.buffer.position();

        // Data pointers at +0x00, +0x04, +0x08 are backpatched by write_saber_arrays.
        self.write_u32_at(header_pos, saber_offsets::GL_POOL_VERT, saber.gl_pool_vert)?;
        self.write_u32_at(
            header_pos,
            saber_offsets::GL_POOL_INDEX,
            saber.gl_pool_index,
        )?;

        self.buffer.set_position(save);
        Ok(header_pos)
    }

    /// Writes the three saber vertex arrays and backpatches header pointers.
    fn write_saber_arrays(
        &mut self,
        saber: &super::MdlSaber,
        saber_header_pos: u64,
    ) -> Result<(), MdlError> {
        // Write saber_verts (vec3 × N)
        let verts_ptr = if !saber.saber_verts.is_empty() {
            let p = self.content_position()?;
            for v in &saber.saber_verts {
                write_f32(&mut self.buffer, v[0])?;
                write_f32(&mut self.buffer, v[1])?;
                write_f32(&mut self.buffer, v[2])?;
            }
            p
        } else {
            0
        };

        // Write saber_uvs (vec2 × N)
        let uvs_ptr = if !saber.saber_uvs.is_empty() {
            let p = self.content_position()?;
            for v in &saber.saber_uvs {
                write_f32(&mut self.buffer, v[0])?;
                write_f32(&mut self.buffer, v[1])?;
            }
            p
        } else {
            0
        };

        // Write saber_normals (vec3 × N)
        let normals_ptr = if !saber.saber_normals.is_empty() {
            let p = self.content_position()?;
            for v in &saber.saber_normals {
                write_f32(&mut self.buffer, v[0])?;
                write_f32(&mut self.buffer, v[1])?;
                write_f32(&mut self.buffer, v[2])?;
            }
            p
        } else {
            0
        };

        // Backpatch data pointers in the saber header.
        self.write_u32_at(saber_header_pos, saber_offsets::VERTS_PTR, verts_ptr)?;
        self.write_u32_at(saber_header_pos, saber_offsets::UVS_PTR, uvs_ptr)?;
        self.write_u32_at(saber_header_pos, saber_offsets::NORMALS_PTR, normals_ptr)?;

        Ok(())
    }

    /// Writes a null-terminated string into a fixed-size field, zero-padded.
    fn write_fixed_string(&mut self, s: &str, field_size: usize) -> Result<(), MdlError> {
        crate::binary::write_fixed_c_string(&mut self.buffer, s, field_size)?;
        Ok(())
    }
}