rakata_formats/mdl/

ascii_writer.rs

//! ASCII MDL writer.
//!
//! Serializes an [`Mdl`] model into the human-readable ASCII MDL format
//! used by the KotOR engine's text-mode model parser. The output is
//! compatible with mdledit, kotorblender, and the engine's native
//! `ParseNode` / `InternalParseField` dispatch pipeline.
//!
//! The writer emits a deterministic representation: geometry header,
//! recursive DFS node tree, then animations. Controller values are
//! converted from binary quaternion to ASCII axis-angle for orientation
//! data, and unknown controller codes get a `controller_<N>` fallback name.

use std::collections::HashMap;
use std::io::Write;

use super::ascii_names::{
    classification_to_ascii, controller_ascii_name, node_type_ascii_name, node_type_context,
};
use super::controllers::{MdlController, MdlControllerType, MdlKey, CTRL_FLAG_BEZIER};
use super::orientation::quat_to_axis_angle;
use super::types::{AabbNode, MdlNodeData};
use super::{collect_geo_positions, Mdl, MdlAnimNode, MdlAnimation, MdlNode};

/// Errors specific to ASCII MDL serialization and parsing.
#[derive(Debug)]
pub enum MdlAsciiError {
    /// I/O error.
    Io(std::io::Error),
    /// Invalid data preventing serialization.
    InvalidData(String),
    /// Parse error at a specific line.
    Parse {
        /// 1-based line number in the source text.
        line: usize,
        /// Description of the parse failure.
        message: String,
    },
}

impl std::fmt::Display for MdlAsciiError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Io(e) => write!(f, "I/O error: {e}"),
            Self::InvalidData(msg) => write!(f, "invalid data: {msg}"),
            Self::Parse { line, message } => write!(f, "line {line}: {message}"),
        }
    }
}

impl std::error::Error for MdlAsciiError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Io(e) => Some(e),
            Self::InvalidData(_) | Self::Parse { .. } => None,
        }
    }
}

impl From<std::io::Error> for MdlAsciiError {
    fn from(e: std::io::Error) -> Self {
        Self::Io(e)
    }
}

/// Writes an ASCII MDL representation to a writer.
///
/// The output follows the engine's native ASCII MDL grammar and is compatible
/// with mdledit, kotorblender, and the engine's own text-mode parser.
///
/// # Errors
///
/// [`MdlAsciiError::Io`] when the writer fails, and
/// [`MdlAsciiError::InvalidData`] when the model holds something the ASCII
/// grammar cannot express.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(w, mdl))
)]
pub fn write_mdl_ascii<W: Write>(w: &mut W, mdl: &Mdl) -> Result<(), MdlAsciiError> {
    let name = &mdl.root_node.name;
    let super_name = if mdl.supermodel_name.is_empty() {
        "NULL"
    } else {
        &mdl.supermodel_name
    };

    // Model header
    writeln!(w, "newmodel {name}")?;
    writeln!(w, "setsupermodel {name} {super_name}")?;
    writeln!(
        w,
        "classification {}",
        classification_to_ascii(mdl.classification)
    )?;
    writeln!(w, "classification_unk1 {}", mdl.subclassification)?;
    let ignore_fog = if mdl.affected_by_fog != 0 { 0 } else { 1 };
    writeln!(w, "ignorefog {ignore_fog}")?;
    writeln!(w, "setanimationscale {}", format_float(mdl.animation_scale))?;

    // compress_quaternions: derived from whether any orientation controller
    // uses compressed quaternion encoding (raw_column_count == 2).
    let has_compressed_quats = has_compressed_quaternions(mdl);
    writeln!(
        w,
        "compress_quaternions {}",
        i32::from(has_compressed_quats)
    )?;

    // headlink: derived from whether the model has a separate animation root
    // (typically neck_g for head models).
    let is_headlinked = mdl.anim_root_node.is_some();
    writeln!(w, "headlink {}", i32::from(is_headlinked))?;

    // Geometry block
    writeln!(w, "beginmodelgeom {name}")?;
    writeln!(
        w,
        "  bmin {} {} {}",
        format_float(mdl.bounding_box[0]),
        format_float(mdl.bounding_box[1]),
        format_float(mdl.bounding_box[2])
    )?;
    writeln!(
        w,
        "  bmax {} {} {}",
        format_float(mdl.bounding_box[3]),
        format_float(mdl.bounding_box[4]),
        format_float(mdl.bounding_box[5])
    )?;
    writeln!(w, "  radius {}", format_float(mdl.radius))?;

    // Recursive DFS node tree
    write_node(w, &mdl.root_node, None, &mdl.root_node)?;

    writeln!(w, "endmodelgeom {name}")?;

    // Build geometry node position map for animation position offsetting.
    // Binary animation position controllers store deltas from the geometry
    // rest pose; ASCII format uses absolute positions. mdledit adds the
    // geometry node's position to each animation keyframe value.
    let geo_positions = collect_geo_positions(&mdl.root_node);

    // Animations
    for anim in &mdl.animations {
        write_animation(w, anim, name, &geo_positions)?;
    }

    writeln!(w, "donemodel {name}")?;
    Ok(())
}

/// Serializes an MDL to an ASCII string.
///
/// # Errors
///
/// The same as [`write_mdl_ascii`] apart from the I/O arm, which writing into
/// a `String` cannot reach.
#[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip(mdl)))]
pub fn write_mdl_ascii_to_string(mdl: &Mdl) -> Result<String, MdlAsciiError> {
    let mut buf = Vec::new();
    write_mdl_ascii(&mut buf, mdl)?;
    String::from_utf8(buf)
        .map_err(|e| MdlAsciiError::InvalidData(format!("output is not valid UTF-8: {e}")))
}

// ---------------------------------------------------------------------------
// Node writing
// ---------------------------------------------------------------------------

/// Writes a geometry node and its children recursively.
fn write_node<W: Write>(
    w: &mut W,
    node: &MdlNode,
    parent_name: Option<&str>,
    model_root: &MdlNode,
) -> Result<(), MdlAsciiError> {
    let type_str = node_type_ascii_name(&node.node_data);
    let parent_str = parent_name.unwrap_or("NULL");

    writeln!(w, "node {type_str} {}", node.name)?;
    writeln!(w, "  parent {parent_str}")?;

    // A position or orientation controller writes its own values below, so
    // the header defaults are skipped wherever one exists.
    let has_pos_ctrl = node
        .controllers
        .iter()
        .any(|c| c.controller_type == MdlControllerType::POSITION);
    let has_ori_ctrl = node
        .controllers
        .iter()
        .any(|c| c.controller_type == MdlControllerType::ORIENTATION);

    // Position (from header, unless overridden by controller).
    // Skip identity values for the root node (matching mdledit behavior).
    if !has_pos_ctrl {
        let [px, py, pz] = node.position;
        if px != 0.0 || py != 0.0 || pz != 0.0 {
            writeln!(
                w,
                "  position {} {} {}",
                format_float(px),
                format_float(py),
                format_float(pz)
            )?;
        }
    }

    // Orientation (from header, unless overridden by controller).
    // Skip identity values (matching mdledit behavior).
    if !has_ori_ctrl {
        let aa = quat_to_axis_angle(node.rotation);
        if aa[3] != 0.0 {
            writeln!(
                w,
                "  orientation {} {} {} {}",
                format_float(aa[0]),
                format_float(aa[1]),
                format_float(aa[2]),
                format_float(aa[3])
            )?;
        }
    }

    // Controllers (written before type-specific fields, matching mdledit order).
    // Single-key inline format appears as e.g. "position x y z", multi-key
    // uses "positionkey" block format.
    let ctx = node_type_context(&node.node_data);
    for ctrl in &node.controllers {
        write_controller(w, ctrl, ctx, "  ")?;
    }

    // Type-specific fields
    write_node_data(w, &node.node_data, model_root)?;

    writeln!(w, "endnode")?;

    // Children follow after endnode (DFS preorder)
    for child in &node.children {
        write_node(w, child, Some(&node.name), model_root)?;
    }

    Ok(())
}

/// Writes type-specific node fields.
fn write_node_data<W: Write>(
    w: &mut W,
    data: &MdlNodeData,
    model_root: &MdlNode,
) -> Result<(), MdlAsciiError> {
    match data {
        MdlNodeData::Base | MdlNodeData::Camera(_) => {}
        MdlNodeData::Mesh(mesh) => write_mesh_fields(w, mesh)?,
        MdlNodeData::Skin(skin) => {
            write_mesh_fields(w, &skin.mesh)?;
            write_skin_fields(w, skin, model_root)?;
        }
        MdlNodeData::AnimMesh(am) => {
            write_mesh_fields(w, &am.mesh)?;
            write_animmesh_fields(w, am)?;
        }
        MdlNodeData::Dangly(dangly) => {
            write_mesh_fields(w, &dangly.mesh)?;
            write_dangly_fields(w, dangly)?;
        }
        MdlNodeData::Aabb(aabb) => {
            write_mesh_fields(w, &aabb.mesh)?;
            write_aabb_fields(w, aabb)?;
        }
        MdlNodeData::Saber(saber) => {
            write_mesh_fields(w, &saber.mesh)?;
        }
        MdlNodeData::Light(light) => write_light_fields(w, light)?,
        MdlNodeData::Emitter(emitter) => write_emitter_fields(w, emitter)?,
        MdlNodeData::Reference(reference) => write_reference_fields(w, reference)?,
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Mesh fields
// ---------------------------------------------------------------------------

/// Writes mesh-specific fields (trimesh and all mesh subtypes).
///
/// Field ordering matches mdledit's asciiwrite.cpp for interoperability.
fn write_mesh_fields<W: Write>(
    w: &mut W,
    mesh: &super::types::MdlMesh,
) -> Result<(), MdlAsciiError> {
    // Colors
    writeln!(
        w,
        "  diffuse {} {} {}",
        format_float(mesh.diffuse_color[0]),
        format_float(mesh.diffuse_color[1]),
        format_float(mesh.diffuse_color[2])
    )?;
    writeln!(
        w,
        "  ambient {} {} {}",
        format_float(mesh.ambient_color[0]),
        format_float(mesh.ambient_color[1]),
        format_float(mesh.ambient_color[2])
    )?;
    writeln!(w, "  transparencyhint {}", mesh.transparency_hint)?;

    // UV animation (always written, even when zero)
    writeln!(w, "  animateuv {}", mesh.animate_uv)?;
    writeln!(w, "  uvdirectionx {}", format_float(mesh.uv_direction_x))?;
    writeln!(w, "  uvdirectiony {}", format_float(mesh.uv_direction_y))?;
    writeln!(w, "  uvjitter {}", format_float(mesh.uv_jitter))?;
    writeln!(w, "  uvjitterspeed {}", format_float(mesh.uv_jitter_speed))?;

    // Boolean flags
    writeln!(w, "  lightmapped {}", i32::from(mesh.light_mapped))?;
    writeln!(w, "  rotatetexture {}", i32::from(mesh.rotate_texture))?;
    writeln!(
        w,
        "  m_bIsBackgroundGeometry {}",
        i32::from(mesh.is_background_geometry)
    )?;
    writeln!(w, "  shadow {}", i32::from(mesh.shadow))?;
    writeln!(w, "  beaming {}", i32::from(mesh.beaming))?;
    writeln!(w, "  render {}", i32::from(mesh.render))?;

    // K1 defaults (not stored in binary, written for mdledit interop)
    writeln!(w, "  dirt_enabled 0")?;
    writeln!(w, "  dirt_texture 1")?;
    writeln!(w, "  dirt_worldspace 1")?;
    writeln!(w, "  hologram_donotdraw 0")?;

    // Tangent space flag (derived from vertex data)
    let has_tangent = !mesh.tangent_space.is_empty();
    writeln!(w, "  tangentspace {}", i32::from(has_tangent))?;

    // Inverted counter (mesh sequence value)
    writeln!(w, "  inv_count {}", mesh.inverted_counter)?;

    // Textures
    if mesh.texture_0.is_empty() {
        writeln!(w, "  bitmap NULL")?;
    } else {
        writeln!(w, "  bitmap {}", mesh.texture_0)?;
    }
    if !mesh.texture_1.is_empty() {
        writeln!(w, "  bitmap2 {}", mesh.texture_1)?;
    }

    // Vertex positions
    let vert_count = mesh.positions.len();
    if vert_count > 0 {
        writeln!(w, "  verts {vert_count}")?;
        for pos in &mesh.positions {
            writeln!(
                w,
                "    {} {} {}",
                format_float(pos[0]),
                format_float(pos[1]),
                format_float(pos[2])
            )?;
        }
    }

    // Faces (written before tverts, matching mdledit order)
    if !mesh.faces.is_empty() {
        let has_uvs = !mesh.uv1.is_empty();
        writeln!(w, "  faces {}", mesh.faces.len())?;
        for face in &mesh.faces {
            let [v0, v1, v2] = face.vertex_indices;
            // Face format: v0 v1 v2 smoothgroup tv0 tv1 tv2 material
            // Binary doesn't store smoothgroups; use 1 as default.
            // TV indices mirror vertex indices when UVs present, else 0 0 0.
            let (tv0, tv1, tv2) = if has_uvs { (v0, v1, v2) } else { (0, 0, 0) };
            writeln!(
                w,
                "    {v0} {v1} {v2}  1  {tv0} {tv1} {tv2}  {}",
                face.surface_id
            )?;
        }
    }

    // UV channels (written after faces, matching mdledit order)
    write_tverts(w, &mesh.uv1, "tverts")?;
    write_tverts(w, &mesh.uv2, "tverts1")?;
    write_tverts(w, &mesh.uv3, "tverts2")?;
    write_tverts(w, &mesh.uv4, "tverts3")?;

    // Vertex colors
    if !mesh.vertex_colors.is_empty() {
        writeln!(w, "  colors {}", mesh.vertex_colors.len())?;
        for c in &mesh.vertex_colors {
            writeln!(
                w,
                "    {} {} {}",
                format_float(f32::from(c[0]) / 255.0),
                format_float(f32::from(c[1]) / 255.0),
                format_float(f32::from(c[2]) / 255.0)
            )?;
        }
    }

    Ok(())
}

/// Writes a texture vertex array (2 values per line: u, v).
fn write_tverts<W: Write>(w: &mut W, uvs: &[[f32; 2]], keyword: &str) -> Result<(), MdlAsciiError> {
    if !uvs.is_empty() {
        writeln!(w, "  {keyword} {}", uvs.len())?;
        for uv in uvs {
            writeln!(w, "    {} {}", format_float(uv[0]), format_float(uv[1]))?;
        }
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Skin fields
// ---------------------------------------------------------------------------

/// Writes skin-specific fields (bone weights).
fn write_skin_fields<W: Write>(
    w: &mut W,
    skin: &super::types::MdlSkin,
    model_root: &MdlNode,
) -> Result<(), MdlAsciiError> {
    let vert_count = skin.mesh.positions.len();
    if vert_count == 0 || skin.bone_weights.is_empty() || skin.bone_indices.is_empty() {
        return Ok(());
    }

    // Build MDX bone index -> node name mapping from the bonemap.
    //
    // The bonemap has one entry per node (in tree order). Each entry is a float
    // (stored as u32 bits) giving the MDX bone index that maps to that tree
    // position. -1.0 marks unused slots. So bonemap[tree_pos] = mdx_bone_idx.
    // The reverse is what is wanted here: mdx_bone_idx -> node_name[tree_pos].
    let node_names = collect_node_names(model_root);
    let mut bone_index_to_name: Vec<Option<String>> = Vec::new();
    for (tree_pos, &raw) in skin.bonemap.iter().enumerate() {
        let mdx_bone_idx_f = f32::from_bits(raw);
        if mdx_bone_idx_f >= 0.0 {
            // MDX bone indices are small non-negative integers stored as f32
            // by engine convention. No safe f32->usize path exists in std.
            #[allow(
                clippy::cast_possible_truncation,
                clippy::cast_sign_loss,
                clippy::as_conversions
            )]
            let mdx_bone_idx = mdx_bone_idx_f as usize;
            if mdx_bone_idx >= bone_index_to_name.len() {
                bone_index_to_name.resize(mdx_bone_idx + 1, None);
            }
            bone_index_to_name[mdx_bone_idx] = node_names.get(tree_pos).cloned();
        }
    }

    writeln!(w, "  weights {vert_count}")?;
    for (weights, indices) in skin.bone_weights.iter().zip(&skin.bone_indices) {
        let mut parts = Vec::new();
        for j in 0..4 {
            let weight = weights[j];
            let bone_idx_f = indices[j];

            if weight > 0.0 && bone_idx_f >= 0.0 {
                // MDX bone indices are small non-negative f32 by engine convention.
                // No safe f32->usize path exists in std.
                #[allow(
                    clippy::cast_possible_truncation,
                    clippy::cast_sign_loss,
                    clippy::as_conversions
                )]
                let bone_idx = bone_idx_f as usize;
                let bone_name = bone_index_to_name
                    .get(bone_idx)
                    .and_then(|opt| opt.as_ref())
                    .cloned()
                    .unwrap_or_else(|| format!("bone_{bone_idx}"));
                parts.push(format!("{bone_name} {}", format_float(weight)));
            }
        }

        if parts.is_empty() {
            writeln!(w, "    ")?;
        } else {
            writeln!(w, "    {}", parts.join(" "))?;
        }
    }

    Ok(())
}

/// Returns true if any orientation controller in the model uses compressed
/// quaternion encoding (raw_column_count == 2).
fn has_compressed_quaternions(mdl: &Mdl) -> bool {
    // Check geometry node controllers.
    if node_has_compressed_quats(&mdl.root_node) {
        return true;
    }
    // Check animation node controllers.
    for anim in &mdl.animations {
        if anim_node_has_compressed_quats(&anim.root_node) {
            return true;
        }
    }
    false
}

fn node_has_compressed_quats(node: &MdlNode) -> bool {
    for ctrl in &node.controllers {
        if ctrl.controller_type == MdlControllerType::ORIENTATION && ctrl.raw_column_count == 2 {
            return true;
        }
    }
    node.children.iter().any(node_has_compressed_quats)
}

fn anim_node_has_compressed_quats(node: &MdlAnimNode) -> bool {
    for ctrl in &node.controllers {
        if ctrl.controller_type == MdlControllerType::ORIENTATION && ctrl.raw_column_count == 2 {
            return true;
        }
    }
    node.children.iter().any(anim_node_has_compressed_quats)
}

/// Collects all node names in DFS order from a geometry node tree.
fn collect_node_names(node: &MdlNode) -> Vec<String> {
    let mut names = Vec::new();
    collect_names_recursive(node, &mut names);
    names
}

fn collect_names_recursive(node: &MdlNode, names: &mut Vec<String>) {
    names.push(node.name.clone());
    for child in &node.children {
        collect_names_recursive(child, names);
    }
}

// ---------------------------------------------------------------------------
// AnimMesh fields
// ---------------------------------------------------------------------------

/// Writes animmesh-specific fields.
fn write_animmesh_fields<W: Write>(
    w: &mut W,
    am: &super::types::MdlAnimMesh,
) -> Result<(), MdlAsciiError> {
    writeln!(w, "  sampleperiod {}", format_float(am.sample_period))?;

    if !am.anim_verts.is_empty() {
        writeln!(w, "  animverts {}", am.anim_verts.len())?;
        for v in &am.anim_verts {
            writeln!(
                w,
                "    {} {} {}",
                format_float(v[0]),
                format_float(v[1]),
                format_float(v[2])
            )?;
        }
    }

    if !am.anim_t_verts.is_empty() {
        writeln!(w, "  animtverts {}", am.anim_t_verts.len())?;
        for v in &am.anim_t_verts {
            writeln!(
                w,
                "    {} {} {}",
                format_float(v[0]),
                format_float(v[1]),
                format_float(v[2])
            )?;
        }
    }

    Ok(())
}

// ---------------------------------------------------------------------------
// Dangly fields
// ---------------------------------------------------------------------------

/// Writes dangly-specific fields.
fn write_dangly_fields<W: Write>(
    w: &mut W,
    dangly: &super::types::MdlDangly,
) -> Result<(), MdlAsciiError> {
    writeln!(w, "  displacement {}", format_float(dangly.displacement))?;
    writeln!(w, "  tightness {}", format_float(dangly.tightness))?;
    writeln!(w, "  period {}", format_float(dangly.period))?;

    if !dangly.constraints.is_empty() {
        writeln!(w, "  constraints {}", dangly.constraints.len())?;
        for c in &dangly.constraints {
            writeln!(w, "    {}", format_float(*c))?;
        }
    }

    Ok(())
}

// ---------------------------------------------------------------------------
// AABB fields
// ---------------------------------------------------------------------------

/// Writes AABB walkmesh-specific fields.
fn write_aabb_fields<W: Write>(
    w: &mut W,
    aabb: &super::types::MdlAabb,
) -> Result<(), MdlAsciiError> {
    if let Some(tree) = &aabb.aabb_tree {
        // Collect leaf entries in DFS preorder
        let mut leaves = Vec::new();
        collect_aabb_leaves(tree, &mut leaves);

        if !leaves.is_empty() {
            writeln!(w, "  aabb")?;
            for leaf in &leaves {
                writeln!(
                    w,
                    "    {} {} {} {} {} {} {}",
                    format_float(leaf.box_min[0]),
                    format_float(leaf.box_min[1]),
                    format_float(leaf.box_min[2]),
                    format_float(leaf.box_max[0]),
                    format_float(leaf.box_max[1]),
                    format_float(leaf.box_max[2]),
                    leaf.face_index
                )?;
            }
        }
    }
    Ok(())
}

/// Collects AABB leaf entries in DFS preorder.
fn collect_aabb_leaves<'a>(node: &'a AabbNode, leaves: &mut Vec<&'a AabbNode>) {
    if node.face_index >= 0 {
        // Leaf node
        leaves.push(node);
    }
    if let Some(left) = &node.left {
        collect_aabb_leaves(left, leaves);
    }
    if let Some(right) = &node.right {
        collect_aabb_leaves(right, leaves);
    }
}

// ---------------------------------------------------------------------------
// Light fields
// ---------------------------------------------------------------------------

/// Writes light-specific fields.
fn write_light_fields<W: Write>(
    w: &mut W,
    light: &super::types::MdlLight,
) -> Result<(), MdlAsciiError> {
    writeln!(w, "  lightpriority {}", light.priority)?;
    writeln!(w, "  ambientonly {}", light.ambientonly)?;
    writeln!(w, "  ndynamictype {}", light.num_dynamic_types)?;
    writeln!(w, "  affectdynamic {}", light.affectdynamic)?;
    writeln!(w, "  shadow {}", light.shadow)?;
    writeln!(w, "  generateflare {}", light.generateflare)?;
    writeln!(w, "  fadingLight {}", light.fading_light)?;
    writeln!(w, "  flareradius {}", format_float(light.flare_radius))?;

    // Flare data
    let flare_count = light.flare_sizes.len();
    if flare_count > 0 {
        writeln!(w, "  lensflares {flare_count}")?;
    }

    if !light.flare_texture_names.is_empty() {
        writeln!(w, "  texturenames {}", light.flare_texture_names.len())?;
        for name in &light.flare_texture_names {
            writeln!(w, "    {name}")?;
        }
    }

    if !light.flare_positions.is_empty() {
        writeln!(w, "  flarepositions {}", light.flare_positions.len())?;
        for p in &light.flare_positions {
            writeln!(w, "    {}", format_float(*p))?;
        }
    }

    if !light.flare_sizes.is_empty() {
        writeln!(w, "  flaresizes {}", light.flare_sizes.len())?;
        for s in &light.flare_sizes {
            writeln!(w, "    {}", format_float(*s))?;
        }
    }

    if !light.flare_color_shifts.is_empty() {
        writeln!(w, "  flarecolorshifts {}", light.flare_color_shifts.len())?;
        for c in &light.flare_color_shifts {
            writeln!(
                w,
                "    {} {} {}",
                format_float(c[0]),
                format_float(c[1]),
                format_float(c[2])
            )?;
        }
    }

    Ok(())
}

// ---------------------------------------------------------------------------
// Emitter fields
// ---------------------------------------------------------------------------

/// Writes emitter-specific fields.
fn write_emitter_fields<W: Write>(
    w: &mut W,
    e: &super::types::MdlEmitter,
) -> Result<(), MdlAsciiError> {
    writeln!(w, "  deadspace {}", format_float(e.deadspace))?;
    writeln!(w, "  blastRadius {}", format_float(e.blast_radius))?;
    writeln!(w, "  blastLength {}", format_float(e.blast_length))?;
    writeln!(w, "  numBranches {}", e.num_branches)?;
    writeln!(w, "  controlptsmoothing {}", e.control_pt_smoothing)?;
    writeln!(w, "  xgrid {}", e.x_grid)?;
    writeln!(w, "  ygrid {}", e.y_grid)?;
    writeln!(w, "  spawntype {}", e.spawn_type)?;

    if !e.update.is_empty() {
        writeln!(w, "  update {}", e.update)?;
    }
    if !e.render.is_empty() {
        writeln!(w, "  render {}", e.render)?;
    }
    if !e.blend.is_empty() {
        writeln!(w, "  blend {}", e.blend)?;
    }
    if !e.texture.is_empty() {
        writeln!(w, "  texture {}", e.texture)?;
    }
    if !e.chunk_name.is_empty() {
        writeln!(w, "  chunkName {}", e.chunk_name)?;
    }

    writeln!(w, "  twosidedtex {}", e.two_sided_tex)?;
    writeln!(w, "  loop {}", e.loop_emitter)?;
    writeln!(w, "  renderorder {}", e.render_order)?;
    writeln!(w, "  m_bFrameBlending {}", i32::from(e.frame_blending))?;

    if !e.depth_texture_name.is_empty() {
        writeln!(w, "  m_sDepthTextureName {}", e.depth_texture_name)?;
    }

    Ok(())
}

// ---------------------------------------------------------------------------
// Reference fields
// ---------------------------------------------------------------------------

/// Writes reference-specific fields.
fn write_reference_fields<W: Write>(
    w: &mut W,
    r: &super::types::MdlReference,
) -> Result<(), MdlAsciiError> {
    writeln!(w, "  refModel {}", r.ref_model)?;
    writeln!(w, "  reattachable {}", r.reattachable)?;
    Ok(())
}

// ---------------------------------------------------------------------------
// Controller writing
// ---------------------------------------------------------------------------

/// Writes a controller as either inline (single key) or keyed block.
fn write_controller<W: Write>(
    w: &mut W,
    ctrl: &MdlController,
    ctx: super::ascii_names::NodeTypeContext,
    indent: &str,
) -> Result<(), MdlAsciiError> {
    let name = controller_name(ctrl.controller_type, ctx);
    let is_bezier = (ctrl.raw_column_count & CTRL_FLAG_BEZIER) != 0;
    let is_orientation = ctrl.controller_type == MdlControllerType::ORIENTATION;
    let is_compressed = is_orientation && ctrl.raw_column_count == 2;

    if ctrl.keys.len() == 1 && ctrl.keys[0].time == 0.0 {
        // Single-key inline format
        write!(w, "{indent}{name} ")?;
        write_key_values(w, &ctrl.keys[0], is_orientation, is_compressed)?;
        writeln!(w)?;
    } else {
        // Multi-key block format
        let suffix = if is_bezier { "bezierkey" } else { "key" };
        writeln!(w, "{indent}{name}{suffix}")?;
        for key in &ctrl.keys {
            write!(w, "{indent}  {} ", format_float(key.time))?;
            write_key_values(w, key, is_orientation, is_compressed)?;
            writeln!(w)?;
        }
        writeln!(w, "{indent}endlist")?;
    }

    Ok(())
}

/// Writes the value portion of a keyframe.
fn write_key_values<W: Write>(
    w: &mut W,
    key: &MdlKey,
    is_orientation: bool,
    is_compressed: bool,
) -> Result<(), MdlAsciiError> {
    if is_orientation && !is_compressed && key.values.len() >= 4 {
        // Controller data stores quaternion as [x,y,z,w] (binary layout),
        // but quat_to_axis_angle expects [w,x,y,z]. Reorder.
        let q = [key.values[3], key.values[0], key.values[1], key.values[2]];
        let aa = quat_to_axis_angle(q);
        write!(
            w,
            "{} {} {} {}",
            format_float(aa[0]),
            format_float(aa[1]),
            format_float(aa[2]),
            format_float(aa[3])
        )?;
    } else {
        // Generic float output
        let formatted: Vec<String> = key.values.iter().map(|v| format_float(*v)).collect();
        write!(w, "{}", formatted.join(" "))?;
    }
    Ok(())
}

/// Returns the ASCII name for a controller type, with fallback.
fn controller_name(code: MdlControllerType, ctx: super::ascii_names::NodeTypeContext) -> String {
    controller_ascii_name(code, ctx)
        .map(String::from)
        .unwrap_or_else(|| format!("controller_{}", code.raw()))
}

// ---------------------------------------------------------------------------
// Animation writing
// ---------------------------------------------------------------------------

/// Writes an animation block.
fn write_animation<W: Write>(
    w: &mut W,
    anim: &MdlAnimation,
    model_name: &str,
    geo_positions: &HashMap<&str, [f32; 3]>,
) -> Result<(), MdlAsciiError> {
    writeln!(w, "newanim {} {model_name}", anim.name)?;
    writeln!(w, "  length {}", format_float(anim.length))?;
    writeln!(w, "  transtime {}", format_float(anim.transition_time))?;
    writeln!(w, "  animroot {}", anim.anim_root)?;

    // Events
    for event in &anim.events {
        writeln!(w, "  event {} {}", format_float(event.time), event.name)?;
    }

    // Animation node tree
    write_anim_node(w, &anim.root_node, None, geo_positions)?;

    writeln!(w, "doneanim {} {model_name}", anim.name)?;
    Ok(())
}

/// Writes an animation node and its children recursively.
fn write_anim_node<W: Write>(
    w: &mut W,
    node: &MdlAnimNode,
    parent_name: Option<&str>,
    geo_positions: &HashMap<&str, [f32; 3]>,
) -> Result<(), MdlAsciiError> {
    let parent_str = parent_name.unwrap_or("NULL");
    writeln!(w, "    node dummy {}", node.name)?;
    writeln!(w, "      parent {parent_str}")?;

    // Look up the corresponding geometry node's rest position for this
    // animation node. Position controller values in binary are deltas
    // from this rest pose.
    let geo_pos = geo_positions
        .get(node.name.as_str())
        .copied()
        .unwrap_or([0.0, 0.0, 0.0]);

    // Animation node controllers are always keyed (multi-key block)
    // Use Base context since anim nodes are type-agnostic.
    // Name resolution still checks every context, since animation nodes
    // can carry light, emitter and mesh controllers.
    for ctrl in &node.controllers {
        write_anim_controller(w, ctrl, geo_pos)?;
    }

    writeln!(w, "    endnode")?;

    for child in &node.children {
        write_anim_node(w, child, Some(&node.name), geo_positions)?;
    }

    Ok(())
}

/// Writes an animation controller (always keyed format).
///
/// Position controllers have `geo_pos` added to each keyframe value,
/// converting binary deltas to the absolute positions used in ASCII.
fn write_anim_controller<W: Write>(
    w: &mut W,
    ctrl: &MdlController,
    geo_pos: [f32; 3],
) -> Result<(), MdlAsciiError> {
    // Try all contexts for name resolution (anim nodes can carry any controller type)
    let name = controller_ascii_name(
        ctrl.controller_type,
        super::ascii_names::NodeTypeContext::Base,
    )
    .or_else(|| {
        controller_ascii_name(
            ctrl.controller_type,
            super::ascii_names::NodeTypeContext::Mesh,
        )
    })
    .or_else(|| {
        controller_ascii_name(
            ctrl.controller_type,
            super::ascii_names::NodeTypeContext::Light,
        )
    })
    .or_else(|| {
        controller_ascii_name(
            ctrl.controller_type,
            super::ascii_names::NodeTypeContext::Emitter,
        )
    })
    .map(String::from)
    .unwrap_or_else(|| format!("controller_{}", ctrl.controller_type.raw()));

    let is_bezier = (ctrl.raw_column_count & CTRL_FLAG_BEZIER) != 0;
    let is_orientation = ctrl.controller_type == MdlControllerType::ORIENTATION;
    let is_position = ctrl.controller_type == MdlControllerType::POSITION;
    let is_compressed = is_orientation && ctrl.raw_column_count == 2;
    let suffix = if is_bezier { "bezierkey" } else { "key" };

    writeln!(w, "      {name}{suffix}")?;
    for key in &ctrl.keys {
        write!(w, "        {} ", format_float(key.time))?;
        if is_position && key.values.len() >= 3 {
            // Add geometry rest position to convert delta -> absolute.
            // For bezier keys, only offset the first 3 values (the position);
            // control points (values 3..8) are written as-is.
            let mut offset_key = key.clone();
            offset_key.values[0] += geo_pos[0];
            offset_key.values[1] += geo_pos[1];
            offset_key.values[2] += geo_pos[2];
            write_key_values(w, &offset_key, false, false)?;
        } else {
            write_key_values(w, key, is_orientation, is_compressed)?;
        }
        writeln!(w)?;
    }
    writeln!(w, "      endlist")?;

    Ok(())
}

// ---------------------------------------------------------------------------
// Float formatting
// ---------------------------------------------------------------------------

/// Formats an f32 for ASCII MDL output, matching mdledit conventions.
///
/// - Integers always get a `.0` suffix (e.g., `1.0`, `0.0`, `-5.0`)
/// - Small values (|v| < 0.0001) use scientific notation (e.g., `7.84e-06`)
/// - Trailing zeros are trimmed but at least one decimal digit is kept
/// - Negative zero is normalized to `0.0`
fn format_float(v: f32) -> String {
    if v.is_nan() {
        return "0.0".into();
    }
    if v.is_infinite() {
        return if v > 0.0 {
            "3.4028235e+38".into()
        } else {
            "-3.4028235e+38".into()
        };
    }
    if v == 0.0 {
        // Avoid "-0.0"
        return "0.0".into();
    }

    let abs = v.abs();

    // Small values get scientific notation (matches C %g behavior: exp < -4).
    if abs < 1e-4 && abs > 0.0 {
        // Use Rust's built-in {:e} and reformat. Manual log10/powi fails for
        // subnormals (10^-39 underflows to 0, producing inf mantissa).
        let raw = format!("{v:e}");
        if let Some(e_pos) = raw.find('e') {
            let mantissa = &raw[..e_pos];
            let exp: i32 = raw[e_pos + 1..]
                .parse()
                .expect("Rust {:e} formatting always produces a valid exponent");
            let trimmed_m = trim_trailing_zeros_keep_one(mantissa);
            return format!("{trimmed_m}e{exp:+03}");
        }
        return raw;
    }

    let s = v.to_string();

    // Rust's Display may output scientific notation for edge cases;
    // normalize to the ASCII grammar's decimal form.
    if let Some(e_pos) = s.find('e') {
        let mantissa = &s[..e_pos];
        let exp_str = &s[e_pos + 1..];
        let exp: i32 = exp_str
            .parse()
            .expect("Rust Display formatting always produces a valid exponent");
        let trimmed_m = trim_trailing_zeros_keep_one(mantissa);
        return format!("{trimmed_m}e{exp:+03}");
    }

    trim_trailing_zeros_keep_one(&s)
}

/// Trims trailing zeros from a decimal string, keeping at least one digit
/// after the decimal point. If no decimal point, appends `.0`.
fn trim_trailing_zeros_keep_one(s: &str) -> String {
    if !s.contains('.') {
        // Integer -- add .0
        return format!("{s}.0");
    }
    let trimmed = s.trim_end_matches('0');
    if trimmed.ends_with('.') {
        // e.g., "5." -> "5.0"
        format!("{trimmed}0")
    } else {
        trimmed.into()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn format_float_integers() {
        assert_eq!(format_float(0.0), "0.0");
        assert_eq!(format_float(1.0), "1.0");
        assert_eq!(format_float(-1.0), "-1.0");
        assert_eq!(format_float(42.0), "42.0");
    }

    #[test]
    fn format_float_negative_zero() {
        assert_eq!(format_float(-0.0), "0.0");
    }

    #[test]
    fn format_float_decimals() {
        assert_eq!(format_float(0.5), "0.5");
        assert_eq!(format_float(1.5), "1.5");
        assert_eq!(format_float(-2.75), "-2.75");
    }

    #[test]
    fn format_float_no_trailing_zeros() {
        // 0.25 should not produce "0.250000..."
        let s = format_float(0.25);
        // Should be "0.25" -- no unnecessary trailing zeros
        assert_eq!(s, "0.25");
    }

    #[test]
    fn format_float_scientific_notation() {
        // Small values should use scientific notation
        let v: f32 = 7.84e-06;
        let s = format_float(v);
        assert!(s.contains("e-"), "expected scientific notation: {s}");
    }

    #[test]
    fn minimal_model_roundtrip() {
        // Build a minimal model with just a root dummy node.
        let mdl = Mdl {
            root_node: MdlNode {
                name: "test_model".into(),
                parent_index: None,
                position: [0.0, 0.0, 0.0],
                rotation: [1.0, 0.0, 0.0, 0.0],
                node_data: MdlNodeData::Base,
                controllers: Vec::new(),
                children: Vec::new(),
                orphan_controller_data: Vec::new(),
                header_padding_02: [0, 0],
                header_padding_06: [0, 0],
            },
            geometry_fn_ptr1: 0,
            geometry_fn_ptr2: 0,
            model_type: 0,
            classification: 0,
            subclassification: 0,
            affected_by_fog: 1,
            supermodel_name: String::new(),
            node_count: 1,
            bounding_box: [0.0; 6],
            radius: 0.0,
            animation_scale: 1.0,
            animations: Vec::new(),
            anim_root_node: None,
        };

        let ascii = write_mdl_ascii_to_string(&mdl).unwrap();
        assert!(ascii.contains("newmodel test_model"));
        assert!(ascii.contains("setsupermodel test_model NULL"));
        assert!(ascii.contains("classification other"));
        assert!(ascii.contains("node dummy test_model"));
        assert!(ascii.contains("parent NULL"));
        // Identity orientation and zero position are omitted (matching mdledit).
        assert!(!ascii.contains("orientation 0.0 0.0 0.0 0.0"));
        assert!(!ascii.contains("position 0.0 0.0 0.0"));
        assert!(ascii.contains("endnode"));
        assert!(ascii.contains("endmodelgeom test_model"));
        assert!(ascii.contains("donemodel test_model"));
    }

    /// Returns the K1 Override directory from `KOTOR_GAME_DIR` env var,
    /// or None if not set (tests should skip).
    fn k1_override_dir() -> Option<String> {
        std::env::var("KOTOR_GAME_DIR")
            .ok()
            .map(|d| format!("{d}/Override"))
    }

    #[test]
    fn smoke_test_vanilla_model() {
        // Try to read a vanilla binary MDL and write it as ASCII.
        // Skip if KOTOR_GAME_DIR isn't set.
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        let path = format!("{base}/3dgui.mdl");
        let data = match std::fs::read(&path) {
            Ok(d) => d,
            Err(_) => return,
        };
        let mdl = super::super::reader::read_mdl_from_bytes(&data, None).unwrap();
        let ascii = write_mdl_ascii_to_string(&mdl).unwrap();

        // Basic structure checks
        assert!(ascii.starts_with("newmodel "));
        assert!(ascii.contains("beginmodelgeom"));
        assert!(ascii.contains("endmodelgeom"));
        assert!(ascii.contains("donemodel"));

        // Should have nodes
        let node_count =
            ascii.matches("\nnode ").count() + if ascii.starts_with("node ") { 1 } else { 0 };
        assert!(node_count > 0, "expected at least one node");

        eprintln!(
            "3dgui.mdl: {} bytes ASCII, {} nodes",
            ascii.len(),
            node_count
        );
    }

    #[test]
    fn smoke_test_character_model() {
        // Character model with skins, animations.
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        let mdl_path = format!("{base}/p_bastilabb.mdl");
        let mdx_path = format!("{base}/p_bastilabb.mdx");
        let mdl_data = match std::fs::read(&mdl_path) {
            Ok(d) => d,
            Err(_) => return,
        };
        let mdx_data = std::fs::read(&mdx_path).ok();
        let mdl =
            super::super::reader::read_mdl_from_bytes(&mdl_data, mdx_data.as_deref()).unwrap();
        let ascii = write_mdl_ascii_to_string(&mdl).unwrap();

        assert!(ascii.contains("newmodel"));
        assert!(ascii.contains("donemodel"));

        // Should have skin nodes with weights
        let has_skin = ascii.contains("node skin ");
        let has_weights = ascii.contains("weights ");
        let has_anim = ascii.contains("newanim ");

        eprintln!(
            "p_bastilabb.mdl: {} bytes ASCII, skin={has_skin}, weights={has_weights}, anims={has_anim}",
            ascii.len()
        );
    }

    #[test]
    fn smoke_test_animated_model() {
        // Supermodel with animations.
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        let mdl_path = format!("{base}/s_female03.mdl");
        let mdx_path = format!("{base}/s_female03.mdx");
        let mdl_data = match std::fs::read(&mdl_path) {
            Ok(d) => d,
            Err(_) => return,
        };
        let mdx_data = std::fs::read(&mdx_path).ok();
        let mdl =
            super::super::reader::read_mdl_from_bytes(&mdl_data, mdx_data.as_deref()).unwrap();
        let ascii = write_mdl_ascii_to_string(&mdl).unwrap();

        assert!(ascii.contains("newmodel"));
        assert!(ascii.contains("donemodel"));
        assert!(ascii.contains("newanim "));
        assert!(ascii.contains("doneanim "));

        let anim_count = ascii.matches("newanim ").count();
        eprintln!(
            "s_female03.mdl: {} bytes ASCII, {} animations",
            ascii.len(),
            anim_count
        );
    }

    #[test]
    fn smoke_test_effect_model() {
        // FX model with emitter nodes.
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        let mdl_path = format!("{base}/fx_carbref.mdl");
        let mdl_data = match std::fs::read(&mdl_path) {
            Ok(d) => d,
            Err(_) => return,
        };
        let mdl = super::super::reader::read_mdl_from_bytes(&mdl_data, None).unwrap();
        let ascii = write_mdl_ascii_to_string(&mdl).unwrap();

        assert!(ascii.contains("newmodel"));
        assert!(ascii.contains("donemodel"));

        let has_emitter = ascii.contains("node emitter ");
        let has_light = ascii.contains("node light ");
        eprintln!(
            "fx_carbref.mdl: {} bytes ASCII, emitter={has_emitter}, light={has_light}",
            ascii.len()
        );

        // Print first emitter node if present
        if let Some(pos) = ascii.find("node emitter ") {
            let snippet = &ascii[pos..ascii.len().min(pos + 800)];
            for line in snippet.lines().take(30) {
                eprintln!("  {line}");
            }
        }
    }
}