rakata_formats/mdl/

ascii_reader.rs

//! ASCII MDL reader.
//!
//! Parses human-readable ASCII MDL text into an [`Mdl`] model struct,
//! producing the same representation as the binary reader. The parser is
//! line-oriented and case-insensitive, matching the engine's `FuncInterp` /
//! `InternalParseField` dispatch pipeline.
//!
//! Derived fields (bounding box, bounding sphere, face planes, adjacency,
//! surface area) are computed automatically via
//! [`MdlMesh::recompute_derived_fields`] after parsing.

use std::collections::HashMap;
use std::io::BufRead;

use super::ascii_names::{
    classification_from_ascii, controller_from_ascii_name, is_non_controller_keyword,
    node_data_from_ascii_name, node_type_context, NodeTypeContext,
};
use super::ascii_writer::MdlAsciiError;
use super::controllers::{MdlController, MdlControllerType, MdlKey, CTRL_FLAG_BEZIER};
use super::orientation::axis_angle_to_quat;
use super::types::{
    AabbNode, MdlAabb, MdlAnimMesh, MdlDangly, MdlEmitter, MdlFace, MdlLight, MdlMesh, MdlNodeData,
    MdlReference, MdlSkin,
};
use super::{
    collect_geo_positions, count_anim_nodes, count_nodes, Mdl, MdlAnimEvent, MdlAnimNode,
    MdlAnimation, MdlNode,
};

// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------

/// Reads an ASCII MDL model from a buffered reader.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader))
)]
pub fn read_mdl_ascii<R: BufRead>(reader: R) -> Result<Mdl, MdlAsciiError> {
    let mut raw_lines = Vec::new();
    for (i, line) in reader.lines().enumerate() {
        let line = line.map_err(MdlAsciiError::Io)?;
        let trimmed = line.trim();
        if !trimmed.is_empty() && !trimmed.starts_with('#') {
            raw_lines.push((i + 1, trimmed.to_string()));
        }
    }
    let mut parser = AsciiParser {
        lines: raw_lines,
        pos: 0,
    };
    parse_model(&mut parser)
}

/// Reads an ASCII MDL model from a string.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(s), fields(bytes_len = s.len()))
)]
pub fn read_mdl_ascii_from_str(s: &str) -> Result<Mdl, MdlAsciiError> {
    read_mdl_ascii(std::io::Cursor::new(s))
}

// ---------------------------------------------------------------------------
// Line-oriented tokenizer
// ---------------------------------------------------------------------------

struct AsciiParser {
    lines: Vec<(usize, String)>,
    pos: usize,
}

impl AsciiParser {
    /// Advances and returns the (line_number, content) pair.
    ///
    /// Takes ownership of the line string via `mem::take`, avoiding a clone.
    /// The parser only moves forward so consumed lines are never revisited.
    fn next_line(&mut self) -> Option<(usize, String)> {
        if self.pos < self.lines.len() {
            let (ln, ref mut s) = self.lines[self.pos];
            self.pos += 1;
            Some((ln, std::mem::take(s)))
        } else {
            None
        }
    }

    fn peek_line(&self) -> Option<(usize, &str)> {
        if self.pos < self.lines.len() {
            let (ln, ref s) = self.lines[self.pos];
            Some((ln, s.as_str()))
        } else {
            None
        }
    }

    fn parse_err(&self, line: usize, msg: impl Into<String>) -> MdlAsciiError {
        MdlAsciiError::Parse {
            line,
            message: msg.into(),
        }
    }
}

fn tokens(line: &str) -> Vec<&str> {
    line.split_whitespace().collect()
}

fn parse_f32(s: &str, line: usize) -> Result<f32, MdlAsciiError> {
    s.parse::<f32>().map_err(|_| MdlAsciiError::Parse {
        line,
        message: format!("invalid float: {s}"),
    })
}

fn parse_u32(s: &str, line: usize) -> Result<u32, MdlAsciiError> {
    s.parse::<u32>().map_err(|_| MdlAsciiError::Parse {
        line,
        message: format!("invalid u32: {s}"),
    })
}

fn parse_i32(s: &str, line: usize) -> Result<i32, MdlAsciiError> {
    s.parse::<i32>().map_err(|_| MdlAsciiError::Parse {
        line,
        message: format!("invalid i32: {s}"),
    })
}

fn parse_u16(s: &str, line: usize) -> Result<u16, MdlAsciiError> {
    s.parse::<u16>().map_err(|_| MdlAsciiError::Parse {
        line,
        message: format!("invalid u16: {s}"),
    })
}

fn parse_u8(s: &str, line: usize) -> Result<u8, MdlAsciiError> {
    s.parse::<u8>().map_err(|_| MdlAsciiError::Parse {
        line,
        message: format!("invalid u8: {s}"),
    })
}

fn eq_ci(a: &str, b: &str) -> bool {
    a.eq_ignore_ascii_case(b)
}

// ---------------------------------------------------------------------------
// Intermediate flat node for tree assembly
// ---------------------------------------------------------------------------

struct FlatNode {
    name: String,
    parent_name: String, // "NULL" for root
    position: [f32; 3],
    rotation: [f32; 4], // quaternion [w, x, y, z]
    node_data: MdlNodeData,
    controllers: Vec<MdlController>,
}

struct FlatAnimNode {
    name: String,
    parent_name: String,
    controllers: Vec<MdlController>,
}

// ---------------------------------------------------------------------------
// Top-level model parser
// ---------------------------------------------------------------------------

fn parse_model(p: &mut AsciiParser) -> Result<Mdl, MdlAsciiError> {
    let mut _model_name = String::new();
    let mut supermodel_name = String::new();
    let mut classification: u8 = 0;
    let mut subclassification: u8 = 0;
    let mut affected_by_fog: u8 = 1;
    let mut animation_scale: f32 = 1.0;
    let mut headlink = false;
    let mut bounding_box = [0.0f32; 6];
    let mut radius: f32 = 0.0;
    let mut geo_nodes: Vec<FlatNode> = Vec::new();
    let mut animations: Vec<MdlAnimation> = Vec::new();

    while let Some((ln, line)) = p.next_line() {
        let toks = tokens(&line);
        if toks.is_empty() {
            continue;
        }
        let kw = toks[0];

        if eq_ci(kw, "newmodel") {
            if toks.len() >= 2 {
                _model_name = toks[1].to_string();
            }
        } else if eq_ci(kw, "setsupermodel") {
            if toks.len() >= 3 {
                supermodel_name = toks[2].to_string();
            }
        } else if eq_ci(kw, "classification") && toks.len() >= 2 {
            classification = classification_from_ascii(toks[1]).unwrap_or(0);
        } else if eq_ci(kw, "classification_unk1") && toks.len() >= 2 {
            subclassification = parse_u8(toks[1], ln)?;
        } else if eq_ci(kw, "ignorefog") && toks.len() >= 2 {
            let v = parse_i32(toks[1], ln)?;
            affected_by_fog = if v != 0 { 0 } else { 1 };
        } else if eq_ci(kw, "setanimationscale") && toks.len() >= 2 {
            animation_scale = parse_f32(toks[1], ln)?;
        } else if eq_ci(kw, "compress_quaternions") {
            // Informational only -- not stored.
        } else if eq_ci(kw, "headlink") && toks.len() >= 2 {
            headlink = parse_i32(toks[1], ln)? != 0;
        } else if eq_ci(kw, "beginmodelgeom") {
            // Parse geometry block.
            parse_geometry_block(p, &mut bounding_box, &mut radius, &mut geo_nodes)?;
        } else if eq_ci(kw, "newanim") && toks.len() >= 3 {
            let anim = parse_animation(p, toks[1], toks[2], ln)?;
            animations.push(anim);
        } else if eq_ci(kw, "donemodel") {
            break;
        }
        // Skip unknown top-level keywords (filedependancy, etc.)
    }

    // Assemble geometry node tree.
    let root_node = assemble_node_tree(geo_nodes)?;
    let mut node_count = count_nodes(&root_node);

    // Build geometry position map for animation position delta conversion.
    let geo_positions = collect_geo_positions(&root_node);

    // Build name->DFS-index map for animation node_number resolution.
    let name_to_index = build_name_index_map(&root_node);

    // Post-process animations: subtract geometry rest positions from
    // animation position keyframes (ASCII stores absolute, binary stores
    // deltas).
    for anim in &mut animations {
        subtract_geo_positions_from_anim(&mut anim.root_node, &geo_positions);
        assign_anim_node_numbers(&mut anim.root_node, &name_to_index);
    }

    // Include animation nodes in total (binary header stores total across
    // geometry + all animation trees).
    for anim in &animations {
        node_count += count_anim_nodes(&anim.root_node);
    }

    // Determine anim_root_node from headlink flag.
    let anim_root_node = if headlink {
        animations
            .first()
            .map(|a| a.anim_root.clone())
            .filter(|s| !s.is_empty())
    } else {
        None
    };

    Ok(Mdl {
        root_node,
        geometry_fn_ptr1: 0,
        geometry_fn_ptr2: 0,
        model_type: 2,
        classification,
        subclassification,
        affected_by_fog,
        supermodel_name,
        node_count,
        bounding_box,
        radius,
        animation_scale,
        animations,
        anim_root_node,
    })
}

// ---------------------------------------------------------------------------
// Geometry block parser
// ---------------------------------------------------------------------------

fn parse_geometry_block(
    p: &mut AsciiParser,
    bbox: &mut [f32; 6],
    radius: &mut f32,
    nodes: &mut Vec<FlatNode>,
) -> Result<(), MdlAsciiError> {
    while let Some((ln, line)) = p.next_line() {
        let toks = tokens(&line);
        if toks.is_empty() {
            continue;
        }
        let kw = toks[0];

        if eq_ci(kw, "bmin") && toks.len() >= 4 {
            bbox[0] = parse_f32(toks[1], ln)?;
            bbox[1] = parse_f32(toks[2], ln)?;
            bbox[2] = parse_f32(toks[3], ln)?;
        } else if eq_ci(kw, "bmax") && toks.len() >= 4 {
            bbox[3] = parse_f32(toks[1], ln)?;
            bbox[4] = parse_f32(toks[2], ln)?;
            bbox[5] = parse_f32(toks[3], ln)?;
        } else if eq_ci(kw, "radius") && toks.len() >= 2 {
            *radius = parse_f32(toks[1], ln)?;
        } else if eq_ci(kw, "node") && toks.len() >= 3 {
            let flat = parse_geometry_node(p, toks[1], toks[2], ln)?;
            nodes.push(flat);
        } else if eq_ci(kw, "endmodelgeom") {
            break;
        }
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Geometry node parser
// ---------------------------------------------------------------------------

fn parse_geometry_node(
    p: &mut AsciiParser,
    type_str: &str,
    name: &str,
    _node_line: usize,
) -> Result<FlatNode, MdlAsciiError> {
    let mut flat = FlatNode {
        name: name.to_string(),
        parent_name: "NULL".into(),
        position: [0.0; 3],
        rotation: [1.0, 0.0, 0.0, 0.0],
        node_data: node_data_from_type_str(type_str),
        controllers: Vec::new(),
    };

    let ctx = node_type_context(&flat.node_data);

    while let Some((ln, line)) = p.next_line() {
        let toks = tokens(&line);
        if toks.is_empty() {
            continue;
        }
        let kw = toks[0];

        if eq_ci(kw, "endnode") {
            break;
        } else if eq_ci(kw, "parent") && toks.len() >= 2 {
            flat.parent_name = toks[1].to_string();
        } else if eq_ci(kw, "position") && toks.len() >= 4 {
            // Could be header position or single-key controller.
            // If exactly 4 tokens (position x y z), treat as header position
            // AND as a single-key controller (matching engine behavior).
            flat.position = [
                parse_f32(toks[1], ln)?,
                parse_f32(toks[2], ln)?,
                parse_f32(toks[3], ln)?,
            ];
        } else if eq_ci(kw, "orientation") && toks.len() >= 5 {
            let aa = [
                parse_f32(toks[1], ln)?,
                parse_f32(toks[2], ln)?,
                parse_f32(toks[3], ln)?,
                parse_f32(toks[4], ln)?,
            ];
            flat.rotation = axis_angle_to_quat(aa);
        } else if try_parse_controller_line(p, &toks, ln, ctx, &mut flat.controllers)? {
            // Handled by controller parser.
        } else {
            // Try type-specific fields.
            parse_node_field(&toks, ln, p, &mut flat.node_data)?;
        }
    }

    // Post-process mesh derived fields.
    if let Some(mesh) = flat.node_data.mesh_mut() {
        mesh.vertex_count = u16::try_from(mesh.positions.len())
            .map_err(|_| MdlAsciiError::InvalidData("vertex count exceeds u16".into()))?;
        mesh.indices_per_face = 3;
        // Count UV channels present.
        let mut tc: u16 = 0;
        if !mesh.uv1.is_empty() {
            tc += 1;
        }
        if !mesh.uv2.is_empty() {
            tc += 1;
        }
        if !mesh.uv3.is_empty() {
            tc += 1;
        }
        if !mesh.uv4.is_empty() {
            tc += 1;
        }
        mesh.texture_channel_count = tc;
        mesh.recompute_derived_fields();
    }

    Ok(flat)
}

fn node_data_from_type_str(s: &str) -> MdlNodeData {
    node_data_from_ascii_name(s)
}

// ---------------------------------------------------------------------------
// Controller parsing
// ---------------------------------------------------------------------------

/// Attempts to parse a controller from the current line tokens.
/// Returns true if the line was consumed as a controller.
fn try_parse_controller_line(
    p: &mut AsciiParser,
    toks: &[&str],
    ln: usize,
    ctx: NodeTypeContext,
    controllers: &mut Vec<MdlController>,
) -> Result<bool, MdlAsciiError> {
    if toks.is_empty() {
        return Ok(false);
    }

    let kw = toks[0];

    // Check for keyed block: "positionkey", "orientationbezierkey", etc.
    let (base_name, is_bezier) = if let Some(base) = strip_suffix_ci(kw, "bezierkey") {
        (base, true)
    } else if let Some(base) = strip_suffix_ci(kw, "key") {
        (base, false)
    } else {
        // Check for single-value inline controller.
        return try_parse_inline_controller(toks, ln, ctx, controllers);
    };

    // Resolve controller type from name.
    let ctrl_type = resolve_controller_type(base_name, ctx)?;

    // Parse keyed block until "endlist".
    let is_orientation = ctrl_type == MdlControllerType::ORIENTATION;
    let mut keys = Vec::new();

    while let Some((kln, kline)) = p.next_line() {
        let ktoks = tokens(&kline);
        if ktoks.is_empty() {
            continue;
        }
        if eq_ci(ktoks[0], "endlist") {
            break;
        }
        if ktoks.len() < 2 {
            continue;
        }

        let time = parse_f32(ktoks[0], kln)?;
        let mut values: Vec<f32> = Vec::new();
        for t in &ktoks[1..] {
            values.push(parse_f32(t, kln)?);
        }

        // Orientation: convert axis-angle -> quaternion [x,y,z,w] storage order.
        if is_orientation && values.len() >= 4 {
            let aa = [values[0], values[1], values[2], values[3]];
            let q = axis_angle_to_quat(aa); // [w, x, y, z]
                                            // Store as [x, y, z, w] (binary storage order).
            values[0] = q[1];
            values[1] = q[2];
            values[2] = q[3];
            values[3] = q[0];
        }

        keys.push(MdlKey { time, values });
    }

    let col_count = if let Some(first_key) = keys.first() {
        u8::try_from(first_key.values.len()).map_err(|_| MdlAsciiError::Parse {
            line: ln,
            message: "column count exceeds u8".into(),
        })?
    } else {
        0
    };
    let raw_column_count = if is_bezier {
        col_count | CTRL_FLAG_BEZIER
    } else {
        col_count
    };

    controllers.push(MdlController {
        controller_type: ctrl_type,
        raw_column_count,
        key_unknown_04: [0; 2],
        key_unknown_0d: [0; 3],
        keys,
    });

    Ok(true)
}

/// Attempts to parse a single-value inline controller (e.g., "scale 1.0").
fn try_parse_inline_controller(
    toks: &[&str],
    ln: usize,
    ctx: NodeTypeContext,
    controllers: &mut Vec<MdlController>,
) -> Result<bool, MdlAsciiError> {
    if toks.len() < 2 {
        return Ok(false);
    }

    let name = toks[0];

    // Skip known non-controller keywords to avoid misinterpreting them.
    // The caller handles these as type-specific fields.
    if is_non_controller_keyword(name) {
        return Ok(false);
    }

    // Try to resolve as a controller name.
    let ctrl_type = match resolve_controller_type_optional(name, ctx) {
        Some(ct) => ct,
        None => return Ok(false),
    };

    // Parse values.
    let is_orientation = ctrl_type == MdlControllerType::ORIENTATION;
    let mut values: Vec<f32> = Vec::new();
    for t in &toks[1..] {
        match t.parse::<f32>() {
            Ok(v) => values.push(v),
            Err(_) => return Ok(false), // Not a controller line.
        }
    }

    if values.is_empty() {
        return Ok(false);
    }

    // Orientation: convert axis-angle -> quaternion [x,y,z,w].
    if is_orientation && values.len() >= 4 {
        let aa = [values[0], values[1], values[2], values[3]];
        let q = axis_angle_to_quat(aa);
        values[0] = q[1];
        values[1] = q[2];
        values[2] = q[3];
        values[3] = q[0];
    }

    let raw_column_count = u8::try_from(values.len()).map_err(|_| MdlAsciiError::Parse {
        line: ln,
        message: "column count exceeds u8".into(),
    })?;

    controllers.push(MdlController {
        controller_type: ctrl_type,
        raw_column_count,
        key_unknown_04: [0; 2],
        key_unknown_0d: [0; 3],
        keys: vec![MdlKey { time: 0.0, values }],
    });

    Ok(true)
}

/// Resolves a controller name to a type code, trying all contexts for
/// animation nodes and falling back to `controller_N` pattern.
fn resolve_controller_type(
    name: &str,
    ctx: NodeTypeContext,
) -> Result<MdlControllerType, MdlAsciiError> {
    resolve_controller_type_optional(name, ctx)
        .ok_or_else(|| MdlAsciiError::InvalidData(format!("unknown controller: {name}")))
}

fn resolve_controller_type_optional(name: &str, ctx: NodeTypeContext) -> Option<MdlControllerType> {
    // Try the node's own context first.
    if let Some(ct) = controller_from_ascii_name(name, ctx) {
        return Some(ct);
    }
    // Try all other contexts.
    for alt_ctx in &[
        NodeTypeContext::Base,
        NodeTypeContext::Mesh,
        NodeTypeContext::Light,
        NodeTypeContext::Emitter,
    ] {
        if let Some(ct) = controller_from_ascii_name(name, *alt_ctx) {
            return Some(ct);
        }
    }
    // Try controller_N pattern.
    let lower = name.to_ascii_lowercase();
    if let Some(num_str) = lower.strip_prefix("controller_") {
        if let Ok(code) = num_str.parse::<u32>() {
            return Some(MdlControllerType::from_raw(code));
        }
    }
    None
}

// ---------------------------------------------------------------------------
// Type-specific field parsing
// ---------------------------------------------------------------------------

fn parse_node_field(
    toks: &[&str],
    ln: usize,
    p: &mut AsciiParser,
    data: &mut MdlNodeData,
) -> Result<(), MdlAsciiError> {
    // Mesh fields (shared by all mesh subtypes).
    if let Some(mesh) = data.mesh_mut() {
        if parse_mesh_field(toks, ln, p, mesh)? {
            return Ok(());
        }
    }

    // Type-specific fields.
    match data {
        MdlNodeData::Skin(skin) => {
            if parse_skin_field(toks, ln, p, skin)? {
                return Ok(());
            }
        }
        MdlNodeData::Dangly(dangly) => {
            if parse_dangly_field(toks, ln, p, dangly)? {
                return Ok(());
            }
        }
        MdlNodeData::Aabb(aabb) => {
            if parse_aabb_field(toks, ln, p, aabb)? {
                return Ok(());
            }
        }
        MdlNodeData::Light(light) => {
            if parse_light_field(toks, ln, p, light)? {
                return Ok(());
            }
        }
        MdlNodeData::Emitter(emitter) => {
            if parse_emitter_field(toks, ln, p, emitter)? {
                return Ok(());
            }
        }
        MdlNodeData::Reference(reference) => {
            if parse_reference_field(toks, ln, reference)? {
                return Ok(());
            }
        }
        MdlNodeData::AnimMesh(animmesh) => {
            if parse_animmesh_field(toks, ln, p, animmesh)? {
                return Ok(());
            }
        }
        _ => {}
    }

    // Unknown fields silently skipped (matching engine behavior).
    Ok(())
}

// ---------------------------------------------------------------------------
// Mesh field parsing
// ---------------------------------------------------------------------------

fn parse_mesh_field(
    toks: &[&str],
    ln: usize,
    p: &mut AsciiParser,
    mesh: &mut MdlMesh,
) -> Result<bool, MdlAsciiError> {
    let kw = toks[0];

    if eq_ci(kw, "diffuse") && toks.len() >= 4 {
        mesh.diffuse_color = [
            parse_f32(toks[1], ln)?,
            parse_f32(toks[2], ln)?,
            parse_f32(toks[3], ln)?,
        ];
    } else if eq_ci(kw, "ambient") && toks.len() >= 4 {
        mesh.ambient_color = [
            parse_f32(toks[1], ln)?,
            parse_f32(toks[2], ln)?,
            parse_f32(toks[3], ln)?,
        ];
    } else if eq_ci(kw, "transparencyhint") && toks.len() >= 2 {
        mesh.transparency_hint = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "animateuv") && toks.len() >= 2 {
        mesh.animate_uv = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "uvdirectionx") && toks.len() >= 2 {
        mesh.uv_direction_x = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "uvdirectiony") && toks.len() >= 2 {
        mesh.uv_direction_y = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "uvjitter") && toks.len() >= 2 {
        mesh.uv_jitter = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "uvjitterspeed") && toks.len() >= 2 {
        mesh.uv_jitter_speed = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "lightmapped") && toks.len() >= 2 {
        mesh.light_mapped = parse_i32(toks[1], ln)? != 0;
    } else if eq_ci(kw, "rotatetexture") && toks.len() >= 2 {
        mesh.rotate_texture = parse_i32(toks[1], ln)? != 0;
    } else if eq_ci(kw, "m_bIsBackgroundGeometry") && toks.len() >= 2 {
        mesh.is_background_geometry = parse_i32(toks[1], ln)? != 0;
    } else if eq_ci(kw, "shadow") && toks.len() >= 2 {
        mesh.shadow = parse_i32(toks[1], ln)? != 0;
    } else if eq_ci(kw, "beaming") && toks.len() >= 2 {
        mesh.beaming = parse_i32(toks[1], ln)? != 0;
    } else if eq_ci(kw, "render") && toks.len() >= 2 {
        mesh.render = parse_i32(toks[1], ln)? != 0;
    } else if (eq_ci(kw, "bitmap") || eq_ci(kw, "texture0")) && toks.len() >= 2 {
        let val = toks[1];
        mesh.texture_0 = if eq_ci(val, "NULL") {
            String::new()
        } else {
            val.to_string()
        };
    } else if (eq_ci(kw, "bitmap2") || eq_ci(kw, "texture1")) && toks.len() >= 2 {
        let val = toks[1];
        mesh.texture_1 = if eq_ci(val, "NULL") {
            String::new()
        } else {
            val.to_string()
        };
    } else if eq_ci(kw, "inv_count") && toks.len() >= 2 {
        mesh.inverted_counter = parse_u32(toks[1], ln)?;
    } else if eq_ci(kw, "verts") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        mesh.positions = parse_vec3_block(p, count)?;
    } else if eq_ci(kw, "faces") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        mesh.faces = parse_face_block(p, count)?;
    } else if (eq_ci(kw, "tverts") || eq_ci(kw, "tverts0")) && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        mesh.uv1 = parse_uv_block(p, count)?;
    } else if eq_ci(kw, "tverts1") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        mesh.uv2 = parse_uv_block(p, count)?;
    } else if eq_ci(kw, "tverts2") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        mesh.uv3 = parse_uv_block(p, count)?;
    } else if eq_ci(kw, "tverts3") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        mesh.uv4 = parse_uv_block(p, count)?;
    } else if eq_ci(kw, "colors") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        mesh.vertex_colors = parse_color_block(p, count)?;
    } else if eq_ci(kw, "tangentspace")
        || eq_ci(kw, "dirt_enabled")
        || eq_ci(kw, "dirt_texture")
        || eq_ci(kw, "dirt_worldspace")
        || eq_ci(kw, "hologram_donotdraw")
    {
        // Informational fields -- parsed and ignored.
    } else {
        return Ok(false);
    }

    Ok(true)
}

fn parse_vec3_block(p: &mut AsciiParser, count: usize) -> Result<Vec<[f32; 3]>, MdlAsciiError> {
    let mut result = Vec::with_capacity(count);
    for _ in 0..count {
        let (ln, line) = p
            .next_line()
            .ok_or_else(|| MdlAsciiError::InvalidData("unexpected EOF in vec3 block".into()))?;
        let toks = tokens(&line);
        if toks.len() < 3 {
            return Err(p.parse_err(ln, "expected 3 floats"));
        }
        result.push([
            parse_f32(toks[0], ln)?,
            parse_f32(toks[1], ln)?,
            parse_f32(toks[2], ln)?,
        ]);
    }
    Ok(result)
}

fn parse_face_block(p: &mut AsciiParser, count: usize) -> Result<Vec<MdlFace>, MdlAsciiError> {
    let mut faces = Vec::with_capacity(count);
    for _ in 0..count {
        let (ln, line) = p
            .next_line()
            .ok_or_else(|| MdlAsciiError::InvalidData("unexpected EOF in face block".into()))?;
        let toks = tokens(&line);
        if toks.len() < 8 {
            return Err(p.parse_err(ln, "expected 8 values in face line"));
        }
        let v0 = parse_u16(toks[0], ln)?;
        let v1 = parse_u16(toks[1], ln)?;
        let v2 = parse_u16(toks[2], ln)?;
        // toks[3] = smoothgroup (ignored)
        // toks[4..7] = tv indices (ignored)
        let surface_id = parse_u32(toks[7], ln)?;

        faces.push(MdlFace {
            plane_normal: [0.0; 3], // computed later
            plane_distance: 0.0,    // computed later
            surface_id,
            adjacent: [0xFFFF; 3], // computed later
            vertex_indices: [v0, v1, v2],
        });
    }
    Ok(faces)
}

fn parse_uv_block(p: &mut AsciiParser, count: usize) -> Result<Vec<[f32; 2]>, MdlAsciiError> {
    let mut uvs = Vec::with_capacity(count);
    for _ in 0..count {
        let (ln, line) = p
            .next_line()
            .ok_or_else(|| MdlAsciiError::InvalidData("unexpected EOF in UV block".into()))?;
        let toks = tokens(&line);
        if toks.len() < 2 {
            return Err(p.parse_err(ln, "expected at least 2 floats in UV line"));
        }
        // Accept 2 or 3 values (3rd is legacy trailing zero).
        uvs.push([parse_f32(toks[0], ln)?, parse_f32(toks[1], ln)?]);
    }
    Ok(uvs)
}

fn parse_color_block(p: &mut AsciiParser, count: usize) -> Result<Vec<[u8; 4]>, MdlAsciiError> {
    let mut colors = Vec::with_capacity(count);
    for _ in 0..count {
        let (ln, line) = p
            .next_line()
            .ok_or_else(|| MdlAsciiError::InvalidData("unexpected EOF in color block".into()))?;
        let toks = tokens(&line);
        if toks.len() < 3 {
            return Err(p.parse_err(ln, "expected 3 floats in color line"));
        }
        // Clamped to [0, 255] before cast -- truncation is impossible.
        #[allow(
            clippy::cast_possible_truncation,
            clippy::cast_sign_loss,
            clippy::as_conversions
        )]
        let r = (parse_f32(toks[0], ln)? * 255.0).round().clamp(0.0, 255.0) as u8;
        #[allow(
            clippy::cast_possible_truncation,
            clippy::cast_sign_loss,
            clippy::as_conversions
        )]
        let g = (parse_f32(toks[1], ln)? * 255.0).round().clamp(0.0, 255.0) as u8;
        #[allow(
            clippy::cast_possible_truncation,
            clippy::cast_sign_loss,
            clippy::as_conversions
        )]
        let b = (parse_f32(toks[2], ln)? * 255.0).round().clamp(0.0, 255.0) as u8;
        colors.push([r, g, b, 255]);
    }
    Ok(colors)
}

// ---------------------------------------------------------------------------
// Skin field parsing
// ---------------------------------------------------------------------------

fn parse_skin_field(
    toks: &[&str],
    ln: usize,
    p: &mut AsciiParser,
    skin: &mut MdlSkin,
) -> Result<bool, MdlAsciiError> {
    let kw = toks[0];
    if (eq_ci(kw, "weights") || eq_ci(kw, "skinweights")) && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        parse_skin_weights(p, count, skin)?;
        Ok(true)
    } else {
        Ok(false)
    }
}

/// Parsed bone weight entry for a single vertex.
struct VertexWeights {
    /// (bone_name, weight) pairs, up to 4.
    pairs: Vec<(String, f32)>,
}

fn parse_skin_weights(
    p: &mut AsciiParser,
    count: usize,
    skin: &mut MdlSkin,
) -> Result<(), MdlAsciiError> {
    let mut vertex_weights: Vec<VertexWeights> = Vec::with_capacity(count);

    for _ in 0..count {
        let (ln, line) = p
            .next_line()
            .ok_or_else(|| MdlAsciiError::InvalidData("unexpected EOF in weights block".into()))?;
        let toks = tokens(&line);
        let mut pairs = Vec::new();
        let mut i = 0;
        while i + 1 < toks.len() && pairs.len() < 4 {
            let bone_name = toks[i].to_string();
            let weight = parse_f32(toks[i + 1], ln)?;
            if weight > 0.0 {
                pairs.push((bone_name, weight));
            }
            i += 2;
        }
        vertex_weights.push(VertexWeights { pairs });
    }

    // Collect unique bone names and assign MDX bone indices.
    let mut bone_name_to_idx: HashMap<String, usize> = HashMap::new();
    for vw in &vertex_weights {
        for (name, _) in &vw.pairs {
            let next_idx = bone_name_to_idx.len();
            bone_name_to_idx.entry(name.clone()).or_insert(next_idx);
        }
    }

    // Populate typed bone weight/index arrays. The binary writer will compute
    // canonical MDX byte offsets at serialization time - the offset fields here
    // are placeholders that get backpatched during MDX layout computation.
    skin.mdx_bone_weights_offset = 0;
    skin.mdx_bone_indices_offset = 0;

    let mut bone_weights_vec = Vec::with_capacity(count);
    let mut bone_indices_vec = Vec::with_capacity(count);
    for vw in &vertex_weights {
        let mut weights = [0.0f32; 4];
        let mut indices = [0.0f32; 4];
        for (j, (name, weight)) in vw.pairs.iter().enumerate().take(4) {
            let idx = *bone_name_to_idx.get(name).unwrap_or(&0);
            weights[j] = *weight;
            // MDX stores bone indices as f32 (engine convention). KotOR bone
            // counts are always < 256, so usize->f32 is lossless in practice.
            #[allow(clippy::cast_precision_loss, clippy::as_conversions)]
            let idx_f32 = idx as f32;
            indices[j] = idx_f32;
        }
        bone_weights_vec.push(weights);
        bone_indices_vec.push(indices);
    }
    skin.bone_weights = bone_weights_vec;
    skin.bone_indices = bone_indices_vec;

    // Bonemap requires the full geometry tree (name -> DFS index) to build.
    // Left empty here; populated during tree assembly post-processing.
    skin.bonemap = Vec::new();

    Ok(())
}

// ---------------------------------------------------------------------------
// Dangly field parsing
// ---------------------------------------------------------------------------

fn parse_dangly_field(
    toks: &[&str],
    ln: usize,
    p: &mut AsciiParser,
    dangly: &mut MdlDangly,
) -> Result<bool, MdlAsciiError> {
    let kw = toks[0];

    if eq_ci(kw, "displacement") && toks.len() >= 2 {
        dangly.displacement = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "tightness") && toks.len() >= 2 {
        dangly.tightness = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "period") && toks.len() >= 2 {
        dangly.period = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "constraints") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        dangly.constraints = parse_float_block(p, count)?;
    } else {
        return Ok(false);
    }
    Ok(true)
}

fn parse_float_block(p: &mut AsciiParser, count: usize) -> Result<Vec<f32>, MdlAsciiError> {
    let mut result = Vec::with_capacity(count);
    for _ in 0..count {
        let (ln, line) = p
            .next_line()
            .ok_or_else(|| MdlAsciiError::InvalidData("unexpected EOF in float block".into()))?;
        let toks = tokens(&line);
        if toks.is_empty() {
            return Err(p.parse_err(ln, "expected float value"));
        }
        result.push(parse_f32(toks[0], ln)?);
    }
    Ok(result)
}

// ---------------------------------------------------------------------------
// AABB field parsing
// ---------------------------------------------------------------------------

fn parse_aabb_field(
    toks: &[&str],
    _ln: usize,
    p: &mut AsciiParser,
    aabb: &mut MdlAabb,
) -> Result<bool, MdlAsciiError> {
    if !eq_ci(toks[0], "aabb") {
        return Ok(false);
    }

    // Read leaf entries until a line doesn't have 7 numeric tokens.
    let mut leaves: Vec<AabbLeaf> = Vec::new();
    while let Some((ln, line)) = p.peek_line() {
        let toks = tokens(line);
        if toks.len() < 7 {
            break;
        }
        // Try to parse all 7 as numbers.
        let vals: Result<Vec<f32>, _> = toks[..7].iter().map(|t| parse_f32(t, ln)).collect();
        match vals {
            Ok(v) => {
                p.next_line(); // consume
                leaves.push(AabbLeaf {
                    box_min: [v[0], v[1], v[2]],
                    box_max: [v[3], v[4], v[5]],
                    // AABB face indices are small non-negative integers stored as f32
                    // in ASCII MDL. Truncation to i32 is intentional and lossless.
                    #[allow(clippy::cast_possible_truncation, clippy::as_conversions)]
                    face_index: v[6] as i32,
                });
            }
            Err(_) => break,
        }
    }

    if !leaves.is_empty() {
        aabb.aabb_tree = Some(Box::new(build_aabb_tree(&leaves)));
    }

    Ok(true)
}

struct AabbLeaf {
    box_min: [f32; 3],
    box_max: [f32; 3],
    face_index: i32,
}

/// Builds a BVH tree from AABB leaf entries using median-split.
fn build_aabb_tree(leaves: &[AabbLeaf]) -> AabbNode {
    if leaves.len() == 1 {
        return AabbNode {
            box_min: leaves[0].box_min,
            box_max: leaves[0].box_max,
            face_index: leaves[0].face_index,
            split_direction_flags: 0,
            left: None,
            right: None,
        };
    }

    // Compute combined bbox.
    let mut combined_min = [f32::MAX; 3];
    let mut combined_max = [f32::MIN; 3];
    for leaf in leaves {
        for i in 0..3 {
            combined_min[i] = combined_min[i].min(leaf.box_min[i]);
            combined_max[i] = combined_max[i].max(leaf.box_max[i]);
        }
    }

    // Find longest axis of combined bbox.
    let extents = [
        combined_max[0] - combined_min[0],
        combined_max[1] - combined_min[1],
        combined_max[2] - combined_min[2],
    ];
    let axis = if extents[0] >= extents[1] && extents[0] >= extents[2] {
        0
    } else if extents[1] >= extents[2] {
        1
    } else {
        2
    };

    // Sort by centroid along the chosen axis.
    let mut sorted: Vec<usize> = (0..leaves.len()).collect();
    sorted.sort_by(|&a, &b| {
        let ca = (leaves[a].box_min[axis] + leaves[a].box_max[axis]) * 0.5;
        let cb = (leaves[b].box_min[axis] + leaves[b].box_max[axis]) * 0.5;
        ca.partial_cmp(&cb).unwrap_or(std::cmp::Ordering::Equal)
    });

    // Split at median.
    let mid = sorted.len() / 2;
    let left_leaves: Vec<AabbLeaf> = sorted[..mid]
        .iter()
        .map(|&i| AabbLeaf {
            box_min: leaves[i].box_min,
            box_max: leaves[i].box_max,
            face_index: leaves[i].face_index,
        })
        .collect();
    let right_leaves: Vec<AabbLeaf> = sorted[mid..]
        .iter()
        .map(|&i| AabbLeaf {
            box_min: leaves[i].box_min,
            box_max: leaves[i].box_max,
            face_index: leaves[i].face_index,
        })
        .collect();

    let left = build_aabb_tree(&left_leaves);
    let right = build_aabb_tree(&right_leaves);

    // Split direction flags: 1=+X, 2=+Y, 4=+Z.
    let split_flags = 1u32 << axis;

    AabbNode {
        box_min: combined_min,
        box_max: combined_max,
        face_index: -1,
        split_direction_flags: split_flags,
        left: Some(Box::new(left)),
        right: Some(Box::new(right)),
    }
}

// ---------------------------------------------------------------------------
// Light field parsing
// ---------------------------------------------------------------------------

fn parse_light_field(
    toks: &[&str],
    ln: usize,
    p: &mut AsciiParser,
    light: &mut MdlLight,
) -> Result<bool, MdlAsciiError> {
    let kw = toks[0];

    if eq_ci(kw, "lightpriority") && toks.len() >= 2 {
        light.priority = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "ambientonly") && toks.len() >= 2 {
        light.ambientonly = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "ndynamictype") && toks.len() >= 2 {
        light.num_dynamic_types = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "affectdynamic") && toks.len() >= 2 {
        light.affectdynamic = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "shadow") && toks.len() >= 2 {
        light.shadow = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "generateflare") && toks.len() >= 2 {
        light.generateflare = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "fadingLight") && toks.len() >= 2 {
        light.fading_light = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "flareradius") && toks.len() >= 2 {
        light.flare_radius = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "lensflares") {
        // Count-only header, no data lines.
    } else if eq_ci(kw, "texturenames") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        light.flare_texture_names = parse_string_block(p, count)?;
    } else if eq_ci(kw, "flarepositions") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        light.flare_positions = parse_float_block(p, count)?;
    } else if eq_ci(kw, "flaresizes") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        light.flare_sizes = parse_float_block(p, count)?;
    } else if eq_ci(kw, "flarecolorshifts") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        light.flare_color_shifts = parse_vec3_block(p, count)?;
    } else {
        return Ok(false);
    }
    Ok(true)
}

fn parse_string_block(p: &mut AsciiParser, count: usize) -> Result<Vec<String>, MdlAsciiError> {
    let mut result = Vec::with_capacity(count);
    for _ in 0..count {
        let (_ln, line) = p
            .next_line()
            .ok_or_else(|| MdlAsciiError::InvalidData("unexpected EOF in string block".into()))?;
        result.push(line.trim().to_string());
    }
    Ok(result)
}

// ---------------------------------------------------------------------------
// Emitter field parsing
// ---------------------------------------------------------------------------

fn parse_emitter_field(
    toks: &[&str],
    ln: usize,
    _p: &mut AsciiParser,
    em: &mut MdlEmitter,
) -> Result<bool, MdlAsciiError> {
    let kw = toks[0];

    if eq_ci(kw, "deadspace") && toks.len() >= 2 {
        em.deadspace = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "blastRadius") && toks.len() >= 2 {
        em.blast_radius = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "blastLength") && toks.len() >= 2 {
        em.blast_length = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "numBranches") && toks.len() >= 2 {
        em.num_branches = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "controlptsmoothing") && toks.len() >= 2 {
        em.control_pt_smoothing = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "xgrid") && toks.len() >= 2 {
        em.x_grid = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "ygrid") && toks.len() >= 2 {
        em.y_grid = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "spawntype") && toks.len() >= 2 {
        em.spawn_type = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "update") && toks.len() >= 2 {
        em.update = toks[1].to_string();
    } else if eq_ci(kw, "render") && toks.len() >= 2 {
        em.render = toks[1].to_string();
    } else if eq_ci(kw, "blend") && toks.len() >= 2 {
        em.blend = toks[1].to_string();
    } else if eq_ci(kw, "texture") && toks.len() >= 2 {
        em.texture = toks[1].to_string();
    } else if eq_ci(kw, "chunkName") && toks.len() >= 2 {
        em.chunk_name = toks[1].to_string();
    } else if eq_ci(kw, "twosidedtex") && toks.len() >= 2 {
        em.two_sided_tex = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "loop") && toks.len() >= 2 {
        em.loop_emitter = parse_i32(toks[1], ln)?;
    } else if eq_ci(kw, "renderorder") && toks.len() >= 2 {
        em.render_order = parse_u16(toks[1], ln)?;
    } else if eq_ci(kw, "m_bFrameBlending") && toks.len() >= 2 {
        em.frame_blending = parse_i32(toks[1], ln)? != 0;
    } else if eq_ci(kw, "m_sDepthTextureName") && toks.len() >= 2 {
        em.depth_texture_name = toks[1].to_string();
    } else if eq_ci(kw, "p2p")
        || eq_ci(kw, "p2p_sel")
        || eq_ci(kw, "affectedByWind")
        || eq_ci(kw, "m_isTinted")
        || eq_ci(kw, "bounce")
        || eq_ci(kw, "random")
        || eq_ci(kw, "inherit")
        || eq_ci(kw, "inheritvel")
        || eq_ci(kw, "inherit_local")
        || eq_ci(kw, "splat")
        || eq_ci(kw, "inherit_part")
        || eq_ci(kw, "depth_texture")
    {
        // Controller-driven flags -- not stored in the binary struct.
        // Silently ignored (matching engine behavior).
    } else {
        return Ok(false);
    }
    Ok(true)
}

// ---------------------------------------------------------------------------
// Reference field parsing
// ---------------------------------------------------------------------------

fn parse_reference_field(
    toks: &[&str],
    ln: usize,
    reference: &mut MdlReference,
) -> Result<bool, MdlAsciiError> {
    let kw = toks[0];

    if eq_ci(kw, "refModel") && toks.len() >= 2 {
        reference.ref_model = toks[1].to_string();
    } else if eq_ci(kw, "reattachable") && toks.len() >= 2 {
        reference.reattachable = parse_i32(toks[1], ln)?;
    } else {
        return Ok(false);
    }
    Ok(true)
}

// ---------------------------------------------------------------------------
// AnimMesh field parsing
// ---------------------------------------------------------------------------

fn parse_animmesh_field(
    toks: &[&str],
    ln: usize,
    p: &mut AsciiParser,
    am: &mut MdlAnimMesh,
) -> Result<bool, MdlAsciiError> {
    let kw = toks[0];

    if eq_ci(kw, "sampleperiod") && toks.len() >= 2 {
        am.sample_period = parse_f32(toks[1], ln)?;
    } else if eq_ci(kw, "animverts") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        am.anim_verts = parse_vec3_block(p, count)?;
    } else if eq_ci(kw, "animtverts") && toks.len() >= 2 {
        let count = usize::try_from(parse_u32(toks[1], ln)?).expect("count fits in usize");
        am.anim_t_verts = parse_vec3_block(p, count)?;
    } else {
        return Ok(false);
    }
    Ok(true)
}

// ---------------------------------------------------------------------------
// Animation parsing
// ---------------------------------------------------------------------------

fn parse_animation(
    p: &mut AsciiParser,
    anim_name: &str,
    _model_name: &str,
    _start_line: usize,
) -> Result<MdlAnimation, MdlAsciiError> {
    let mut length: f32 = 0.0;
    let mut transition_time: f32 = 0.0;
    let mut anim_root = String::new();
    let mut events: Vec<MdlAnimEvent> = Vec::new();
    let mut flat_nodes: Vec<FlatAnimNode> = Vec::new();

    while let Some((ln, line)) = p.next_line() {
        let toks = tokens(&line);
        if toks.is_empty() {
            continue;
        }
        let kw = toks[0];

        if eq_ci(kw, "length") && toks.len() >= 2 {
            length = parse_f32(toks[1], ln)?;
        } else if eq_ci(kw, "transtime") && toks.len() >= 2 {
            transition_time = parse_f32(toks[1], ln)?;
        } else if eq_ci(kw, "animroot") && toks.len() >= 2 {
            anim_root = toks[1].to_string();
        } else if eq_ci(kw, "event") && toks.len() >= 3 {
            let time = parse_f32(toks[1], ln)?;
            let name = toks[2].to_string();
            events.push(MdlAnimEvent { time, name });
        } else if eq_ci(kw, "node") && toks.len() >= 3 {
            let flat = parse_anim_node(p, toks[2], ln)?;
            flat_nodes.push(flat);
        } else if eq_ci(kw, "doneanim") {
            break;
        }
    }

    let root_node = assemble_anim_node_tree(flat_nodes)?;

    Ok(MdlAnimation {
        name: anim_name.to_string(),
        length,
        transition_time,
        anim_root,
        events,
        root_node,
        fn_ptr1: 0,
        fn_ptr2: 0,
    })
}

fn parse_anim_node(
    p: &mut AsciiParser,
    name: &str,
    _node_line: usize,
) -> Result<FlatAnimNode, MdlAsciiError> {
    let mut parent_name = "NULL".into();
    let mut controllers = Vec::new();

    while let Some((ln, line)) = p.next_line() {
        let toks = tokens(&line);
        if toks.is_empty() {
            continue;
        }
        let kw = toks[0];

        if eq_ci(kw, "endnode") {
            break;
        } else if eq_ci(kw, "parent") && toks.len() >= 2 {
            parent_name = toks[1].to_string();
        } else {
            // Try all contexts for animation nodes.
            try_parse_controller_line(p, &toks, ln, NodeTypeContext::Base, &mut controllers)?;
        }
    }

    Ok(FlatAnimNode {
        name: name.to_string(),
        parent_name,
        controllers,
    })
}

// ---------------------------------------------------------------------------
// Node tree assembly
// ---------------------------------------------------------------------------

fn assemble_node_tree(flat_nodes: Vec<FlatNode>) -> Result<MdlNode, MdlAsciiError> {
    if flat_nodes.is_empty() {
        return Err(MdlAsciiError::InvalidData("no geometry nodes found".into()));
    }

    // Find root (parent == "NULL").
    let root_idx = flat_nodes
        .iter()
        .position(|n| eq_ci(&n.parent_name, "NULL"))
        .ok_or_else(|| MdlAsciiError::InvalidData("no root node (parent NULL) found".into()))?;

    // Nodes are in DFS preorder. Use a stack to track the current ancestor
    // chain, correctly handling duplicate names (e.g., parent and child both
    // named "lhand_g"). Each stack entry is (flat_index, name).
    let mut children_of_idx: HashMap<usize, Vec<usize>> = HashMap::new();
    let mut stack: Vec<(usize, String)> = Vec::new();

    for (i, node) in flat_nodes.iter().enumerate() {
        if i == root_idx {
            stack.push((i, node.name.clone()));
            continue;
        }

        // Pop the stack back to the parent: find the topmost stack entry
        // whose name matches this node's parent_name.
        let parent_pos = stack.iter().rposition(|(_, n)| eq_ci(n, &node.parent_name));
        if let Some(pos) = parent_pos {
            // Pop everything above the parent (sibling subtrees that ended).
            stack.truncate(pos + 1);
            let parent_idx = stack[pos].0;
            children_of_idx.entry(parent_idx).or_default().push(i);
        }
        // Push this node onto the stack.
        stack.push((i, node.name.clone()));
    }

    fn build_node(
        idx: usize,
        flat: &[FlatNode],
        children_of_idx: &HashMap<usize, Vec<usize>>,
    ) -> MdlNode {
        let f = &flat[idx];
        let children: Vec<MdlNode> = children_of_idx
            .get(&idx)
            .cloned()
            .unwrap_or_default()
            .iter()
            .map(|&ci| build_node(ci, flat, children_of_idx))
            .collect();

        MdlNode {
            name: f.name.clone(),
            parent_index: None, // Not used for ASCII-sourced.
            children,
            position: f.position,
            rotation: f.rotation,
            node_data: f.node_data.clone(),
            controllers: f.controllers.clone(),
            orphan_controller_data: Vec::new(),
            header_padding_02: [0, 0],
            header_padding_06: [0, 0],
        }
    }

    Ok(build_node(root_idx, &flat_nodes, &children_of_idx))
}

fn assemble_anim_node_tree(flat_nodes: Vec<FlatAnimNode>) -> Result<MdlAnimNode, MdlAsciiError> {
    if flat_nodes.is_empty() {
        // Empty animation -- create a dummy root.
        return Ok(MdlAnimNode {
            name: String::new(),
            node_number: 0,
            controllers: Vec::new(),
            orphan_controller_data: Vec::new(),
            children: Vec::new(),
        });
    }

    let root_idx = flat_nodes
        .iter()
        .position(|n| eq_ci(&n.parent_name, "NULL"))
        .unwrap_or(0);

    // Same DFS-order stack-based parent resolution as assemble_node_tree.
    let mut children_of_idx: HashMap<usize, Vec<usize>> = HashMap::new();
    let mut stack: Vec<(usize, String)> = Vec::new();
    for (i, node) in flat_nodes.iter().enumerate() {
        if i == root_idx {
            stack.push((i, node.name.clone()));
            continue;
        }
        let parent_pos = stack.iter().rposition(|(_, n)| eq_ci(n, &node.parent_name));
        if let Some(pos) = parent_pos {
            stack.truncate(pos + 1);
            let parent_idx = stack[pos].0;
            children_of_idx.entry(parent_idx).or_default().push(i);
        }
        stack.push((i, node.name.clone()));
    }

    fn build_anim(
        idx: usize,
        flat: &[FlatAnimNode],
        children_of_idx: &HashMap<usize, Vec<usize>>,
    ) -> MdlAnimNode {
        let f = &flat[idx];
        let children: Vec<MdlAnimNode> = children_of_idx
            .get(&idx)
            .cloned()
            .unwrap_or_default()
            .iter()
            .map(|&ci| build_anim(ci, flat, children_of_idx))
            .collect();

        MdlAnimNode {
            name: f.name.clone(),
            node_number: 0, // Set during post-processing.
            controllers: f.controllers.clone(),
            orphan_controller_data: Vec::new(),
            children,
        }
    }

    Ok(build_anim(root_idx, &flat_nodes, &children_of_idx))
}

// ---------------------------------------------------------------------------
// Post-processing helpers
// ---------------------------------------------------------------------------

fn build_name_index_map(node: &MdlNode) -> HashMap<String, u16> {
    let mut map = HashMap::new();
    let mut idx = 0u16;
    build_name_idx_recursive(node, &mut map, &mut idx);
    map
}

fn build_name_idx_recursive(node: &MdlNode, map: &mut HashMap<String, u16>, idx: &mut u16) {
    map.insert(node.name.clone(), *idx);
    *idx += 1;
    for child in &node.children {
        build_name_idx_recursive(child, map, idx);
    }
}

fn subtract_geo_positions_from_anim(
    node: &mut MdlAnimNode,
    geo_positions: &HashMap<&str, [f32; 3]>,
) {
    if let Some(geo_pos) = geo_positions.get(node.name.as_str()) {
        for ctrl in &mut node.controllers {
            if ctrl.controller_type == MdlControllerType::POSITION {
                for key in &mut ctrl.keys {
                    if key.values.len() >= 3 {
                        key.values[0] -= geo_pos[0];
                        key.values[1] -= geo_pos[1];
                        key.values[2] -= geo_pos[2];
                    }
                }
            }
        }
    }
    for child in &mut node.children {
        subtract_geo_positions_from_anim(child, geo_positions);
    }
}

fn assign_anim_node_numbers(node: &mut MdlAnimNode, name_to_index: &HashMap<String, u16>) {
    node.node_number = name_to_index.get(&node.name).copied().unwrap_or(0);
    for child in &mut node.children {
        assign_anim_node_numbers(child, name_to_index);
    }
}

// ---------------------------------------------------------------------------
// Utility: case-insensitive suffix stripping
// ---------------------------------------------------------------------------

fn strip_suffix_ci<'a>(s: &'a str, suffix: &str) -> Option<&'a str> {
    let s_lower = s.to_ascii_lowercase();
    let suffix_lower = suffix.to_ascii_lowercase();
    if s_lower.ends_with(&suffix_lower) {
        Some(&s[..s.len() - suffix.len()])
    } else {
        None
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::mdl::ascii_writer::write_mdl_ascii_to_string;

    #[test]
    fn minimal_model_parse() {
        let input = "\
newmodel test
setsupermodel test NULL
classification other
classification_unk1 0
ignorefog 0
setanimationscale 1.0
compress_quaternions 0
headlink 0
beginmodelgeom test
  bmin -1.0 -1.0 -1.0
  bmax 1.0 1.0 1.0
  radius 1.73
  node dummy test
    parent NULL
  endnode
endmodelgeom test
donemodel test
";
        let mdl = read_mdl_ascii_from_str(input).unwrap();
        assert_eq!(mdl.root_node.name, "test");
        assert_eq!(mdl.supermodel_name, "NULL");
        assert_eq!(mdl.classification, 0);
        assert_eq!(mdl.affected_by_fog, 1);
        assert_eq!(mdl.node_count, 1);
    }

    #[test]
    fn mesh_node_parse() {
        let input = "\
newmodel m
setsupermodel m NULL
classification other
beginmodelgeom m
  node trimesh mesh1
    parent NULL
    diffuse 0.8 0.8 0.8
    ambient 0.2 0.2 0.2
    bitmap texture_a
    render 1
    verts 3
      0.0 0.0 0.0
      1.0 0.0 0.0
      0.0 1.0 0.0
    faces 1
      0 1 2  1  0 1 2  0
    tverts 3
      0.0 0.0
      1.0 0.0
      0.0 1.0
  endnode
endmodelgeom m
donemodel m
";
        let mdl = read_mdl_ascii_from_str(input).unwrap();
        let mesh = mdl.root_node.node_data.mesh().unwrap();
        assert_eq!(mesh.positions.len(), 3);
        assert_eq!(mesh.faces.len(), 1);
        assert_eq!(mesh.uv1.len(), 3);
        assert_eq!(mesh.texture_0, "texture_a");
        assert_eq!(mesh.faces[0].vertex_indices, [0, 1, 2]);
        assert_eq!(mesh.vertex_count, 3);
    }

    #[test]
    fn controller_keyed_parse() {
        let input = "\
newmodel m
setsupermodel m NULL
classification other
beginmodelgeom m
  node dummy root
    parent NULL
    positionkey
      0.0 1.0 2.0 3.0
      0.5 4.0 5.0 6.0
    endlist
  endnode
endmodelgeom m
donemodel m
";
        let mdl = read_mdl_ascii_from_str(input).unwrap();
        assert_eq!(mdl.root_node.controllers.len(), 1);
        let ctrl = &mdl.root_node.controllers[0];
        assert_eq!(ctrl.controller_type, MdlControllerType::POSITION);
        assert_eq!(ctrl.keys.len(), 2);
        assert_eq!(ctrl.keys[0].time, 0.0);
        assert_eq!(ctrl.keys[0].values, vec![1.0, 2.0, 3.0]);
        assert_eq!(ctrl.keys[1].time, 0.5);
        assert_eq!(ctrl.keys[1].values, vec![4.0, 5.0, 6.0]);
    }

    #[test]
    fn orientation_conversion() {
        let input = "\
newmodel m
setsupermodel m NULL
classification other
beginmodelgeom m
  node dummy root
    parent NULL
    orientation 0.0 0.0 1.0 1.5707963
  endnode
endmodelgeom m
donemodel m
";
        let mdl = read_mdl_ascii_from_str(input).unwrap();
        // Should be a ~90 degree rotation around Z.
        let q = mdl.root_node.rotation;
        // q = [w, x, y, z] -- w should be ~cos(pi/4) = ~0.707
        let expected_half = std::f32::consts::FRAC_1_SQRT_2;
        assert!((q[0] - expected_half).abs() < 0.01, "w = {}", q[0]);
        assert!(q[1].abs() < 0.01, "x = {}", q[1]);
        assert!(q[2].abs() < 0.01, "y = {}", q[2]);
        assert!((q[3] - expected_half).abs() < 0.01, "z = {}", q[3]);
    }

    #[test]
    fn animation_parse() {
        let input = "\
newmodel m
setsupermodel m NULL
classification other
beginmodelgeom m
  node dummy root
    parent NULL
    position 10.0 20.0 30.0
  endnode
endmodelgeom m
newanim walk m
  length 1.0
  transtime 0.25
  animroot root
  event 0.5 footstep
  node dummy root
    parent NULL
    positionkey
      0.0 10.0 20.0 30.0
      1.0 11.0 21.0 31.0
    endlist
  endnode
doneanim walk m
donemodel m
";
        let mdl = read_mdl_ascii_from_str(input).unwrap();
        assert_eq!(mdl.animations.len(), 1);
        let anim = &mdl.animations[0];
        assert_eq!(anim.name, "walk");
        assert_eq!(anim.length, 1.0);
        assert_eq!(anim.anim_root, "root");
        assert_eq!(anim.events.len(), 1);
        assert_eq!(anim.events[0].name, "footstep");

        // Position values should be deltas (absolute - geometry rest pose).
        // ASCII: [10, 20, 30] and [11, 21, 31], geo_pos = [10, 20, 30]
        // -> binary deltas: [0, 0, 0] and [1, 1, 1]
        let ctrl = &anim.root_node.controllers[0];
        assert_eq!(ctrl.controller_type, MdlControllerType::POSITION);
        assert!((ctrl.keys[0].values[0]).abs() < 0.001);
        assert!((ctrl.keys[0].values[1]).abs() < 0.001);
        assert!((ctrl.keys[0].values[2]).abs() < 0.001);
        assert!((ctrl.keys[1].values[0] - 1.0).abs() < 0.001);
        assert!((ctrl.keys[1].values[1] - 1.0).abs() < 0.001);
        assert!((ctrl.keys[1].values[2] - 1.0).abs() < 0.001);
    }

    #[test]
    fn aabb_tree_reconstruction() {
        // 4 leaf entries should produce a balanced tree.
        let input = "\
newmodel m
setsupermodel m NULL
classification other
beginmodelgeom m
  node aabb walkmesh
    parent NULL
    verts 4
      0.0 0.0 0.0
      1.0 0.0 0.0
      1.0 1.0 0.0
      0.0 1.0 0.0
    faces 2
      0 1 2  1  0 1 2  0
      0 2 3  1  0 2 3  0
    aabb
      0.0 0.0 0.0 1.0 0.5 0.0 0
      0.0 0.5 0.0 1.0 1.0 0.0 1
  endnode
endmodelgeom m
donemodel m
";
        let mdl = read_mdl_ascii_from_str(input).unwrap();
        if let MdlNodeData::Aabb(ref aabb) = mdl.root_node.node_data {
            assert!(aabb.aabb_tree.is_some());
            let tree = aabb.aabb_tree.as_ref().unwrap();
            // Root should be internal (face_index == -1).
            assert_eq!(tree.face_index, -1);
            assert!(tree.left.is_some());
            assert!(tree.right.is_some());
        } else {
            panic!("expected AABB node");
        }
    }

    // ---------------------------------------------------------------
    // ASCII self round-trip: write -> read -> write, compare strings
    // ---------------------------------------------------------------

    fn ascii_self_roundtrip(input: &str) {
        let mdl = read_mdl_ascii_from_str(input).unwrap();
        let ascii1 = write_mdl_ascii_to_string(&mdl).unwrap();
        let mdl2 = read_mdl_ascii_from_str(&ascii1).unwrap();
        let ascii2 = write_mdl_ascii_to_string(&mdl2).unwrap();
        if ascii1 != ascii2 {
            // Find first differing line for diagnostics.
            for (i, (a, b)) in ascii1.lines().zip(ascii2.lines()).enumerate() {
                if a != b {
                    panic!(
                        "ASCII self round-trip mismatch at line {}:\n  pass 1: {}\n  pass 2: {}",
                        i + 1,
                        a,
                        b
                    );
                }
            }
            let c1 = ascii1.lines().count();
            let c2 = ascii2.lines().count();
            if c1 != c2 {
                panic!("ASCII self round-trip: line count differs ({c1} vs {c2})");
            }
        }
    }

    #[test]
    fn self_roundtrip_minimal() {
        let input = "\
newmodel test
setsupermodel test NULL
classification other
classification_unk1 0
ignorefog 0
setanimationscale 1.0
compress_quaternions 0
headlink 0
beginmodelgeom test
  bmin -1.0 -1.0 -1.0
  bmax 1.0 1.0 1.0
  radius 1.73
  node dummy test
    parent NULL
  endnode
endmodelgeom test
donemodel test
";
        ascii_self_roundtrip(input);
    }

    #[test]
    fn self_roundtrip_mesh_with_controllers() {
        let input = "\
newmodel m
setsupermodel m NULL
classification other
classification_unk1 0
ignorefog 0
setanimationscale 1.0
compress_quaternions 0
headlink 0
beginmodelgeom m
  bmin -1.0 -1.0 -1.0
  bmax 1.0 1.0 1.0
  radius 1.73
  node trimesh mesh1
    parent NULL
    diffuse 0.8 0.8 0.8
    ambient 0.2 0.2 0.2
    bitmap texture_a
    render 1
    shadow 0
    verts 3
      0.0 0.0 0.0
      1.0 0.0 0.0
      0.0 1.0 0.0
    faces 1
      0 1 2  1  0 1 2  0
    tverts 3
      0.0 0.0
      1.0 0.0
      0.0 1.0
  endnode
endmodelgeom m
donemodel m
";
        ascii_self_roundtrip(input);
    }

    #[test]
    fn self_roundtrip_animation() {
        let input = "\
newmodel m
setsupermodel m NULL
classification character
classification_unk1 0
ignorefog 0
setanimationscale 1.0
compress_quaternions 0
headlink 0
beginmodelgeom m
  bmin -1.0 -1.0 -1.0
  bmax 1.0 1.0 1.0
  radius 1.73
  node dummy root
    parent NULL
    position 10.0 20.0 30.0
  endnode
endmodelgeom m
newanim walk m
  length 1.0
  transtime 0.25
  animroot root
  event 0.5 footstep
  node dummy root
    parent NULL
    positionkey
      0.0 10.0 20.0 30.0
      1.0 11.0 21.0 31.0
    endlist
  endnode
doneanim walk m
donemodel m
";
        ascii_self_roundtrip(input);
    }

    // ---------------------------------------------------------------
    // Binary -> ASCII -> read back round-trip (vanilla models)
    // ---------------------------------------------------------------

    /// Compare two node trees structurally (names, types, children, positions,
    /// faces, controllers). Ignores binary-only metadata.
    fn assert_nodes_equivalent(a: &super::super::MdlNode, b: &super::super::MdlNode, path: &str) {
        assert_eq!(a.name, b.name, "{path}: name mismatch");
        assert_eq!(
            std::mem::discriminant(&a.node_data),
            std::mem::discriminant(&b.node_data),
            "{path}: node type mismatch"
        );
        // Positions (allow small float rounding).
        for i in 0..3 {
            assert!(
                (a.position[i] - b.position[i]).abs() < 1e-4,
                "{path}: position[{i}] {:.6} vs {:.6}",
                a.position[i],
                b.position[i]
            );
        }
        // Rotation (wider tolerance: axis-angle round-trip loses precision
        // for near-identity orientations).
        for i in 0..4 {
            assert!(
                (a.rotation[i] - b.rotation[i]).abs() < 2e-3,
                "{path}: rotation[{i}] {:.6} vs {:.6}",
                a.rotation[i],
                b.rotation[i]
            );
        }
        // Controller comparison: the ASCII writer skips identity position/
        // orientation, so the roundtripped model may have fewer controllers.
        // Check that every controller in b exists in a with the same key count.
        for cb in &b.controllers {
            if let Some(ca) = a
                .controllers
                .iter()
                .find(|c| c.controller_type == cb.controller_type)
            {
                assert_eq!(
                    ca.keys.len(),
                    cb.keys.len(),
                    "{path}: controller {:?} key count ({} vs {})",
                    cb.controller_type,
                    ca.keys.len(),
                    cb.keys.len()
                );
            } else {
                panic!(
                    "{path}: roundtripped has controller {:?} not in original",
                    cb.controller_type
                );
            }
        }
        // Mesh fields.
        if let (Some(ma), Some(mb)) = (a.node_data.mesh(), b.node_data.mesh()) {
            assert_eq!(
                ma.positions.len(),
                mb.positions.len(),
                "{path}: vertex count"
            );
            assert_eq!(ma.faces.len(), mb.faces.len(), "{path}: face count");
            assert_eq!(ma.uv1.len(), mb.uv1.len(), "{path}: uv1 count");
        }
        // Children.
        assert_eq!(
            a.children.len(),
            b.children.len(),
            "{path}: child count ({} vs {})",
            a.children.len(),
            b.children.len()
        );
        for (ca, cb) in a.children.iter().zip(b.children.iter()) {
            assert_nodes_equivalent(ca, cb, &format!("{path}/{}", ca.name));
        }
    }

    fn assert_anims_equivalent(a: &[super::super::MdlAnimation], b: &[super::super::MdlAnimation]) {
        assert_eq!(a.len(), b.len(), "animation count");
        for (i, (aa, ab)) in a.iter().zip(b.iter()).enumerate() {
            assert_eq!(aa.name, ab.name, "anim[{i}] name");
            assert!((aa.length - ab.length).abs() < 1e-4, "anim[{i}] length");
            assert_eq!(aa.anim_root, ab.anim_root, "anim[{i}] anim_root");
            assert_eq!(aa.events.len(), ab.events.len(), "anim[{i}] event count");
        }
    }

    /// 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"))
    }

    /// Full binary -> ASCII -> read back round-trip for a vanilla model.
    fn binary_ascii_roundtrip(mdl_path: &str, mdx_path: Option<&str>) {
        let mdl_data = match std::fs::read(mdl_path) {
            Ok(d) => d,
            Err(_) => return,
        };
        let mdx_data = mdx_path.and_then(|p| std::fs::read(p).ok());
        let original =
            super::super::reader::read_mdl_from_bytes(&mdl_data, mdx_data.as_deref()).unwrap();

        let ascii = write_mdl_ascii_to_string(&original).unwrap();
        let roundtripped = read_mdl_ascii_from_str(&ascii).unwrap();

        // Header fields.
        assert_eq!(
            original.root_node.name, roundtripped.root_node.name,
            "model_name"
        );
        assert_eq!(
            original.supermodel_name, roundtripped.supermodel_name,
            "supermodel_name"
        );
        assert_eq!(
            original.classification, roundtripped.classification,
            "classification"
        );
        assert_eq!(
            original.affected_by_fog, roundtripped.affected_by_fog,
            "affected_by_fog"
        );
        assert!(
            (original.animation_scale - roundtripped.animation_scale).abs() < 1e-4,
            "animation_scale"
        );
        // node_count is derived differently (binary header value vs computed
        // from tree), so just sanity check it's reasonable.
        assert!(roundtripped.node_count > 0, "node_count should be > 0");

        // Node tree.
        assert_nodes_equivalent(
            &original.root_node,
            &roundtripped.root_node,
            &original.root_node.name,
        );

        // Animations.
        assert_anims_equivalent(&original.animations, &roundtripped.animations);
    }

    #[test]
    fn roundtrip_vanilla_item() {
        // Item model with duplicate node names (root and child share same name).
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        binary_ascii_roundtrip(
            &format!("{base}/i_adrnaline_001.mdl"),
            Some(&format!("{base}/i_adrnaline_001.mdx")),
        );
    }

    #[test]
    fn roundtrip_vanilla_placeable() {
        // 3dgui.mdl -- simple placeable, no MDX needed.
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        binary_ascii_roundtrip(&format!("{base}/3dgui.mdl"), None);
    }

    #[test]
    fn roundtrip_vanilla_character() {
        // Character model with skins and animations.
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        binary_ascii_roundtrip(
            &format!("{base}/p_bastilabb.mdl"),
            Some(&format!("{base}/p_bastilabb.mdx")),
        );
    }

    #[test]
    fn roundtrip_vanilla_supermodel() {
        // Supermodel with many animations.
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        binary_ascii_roundtrip(
            &format!("{base}/s_female03.mdl"),
            Some(&format!("{base}/s_female03.mdx")),
        );
    }

    #[test]
    fn roundtrip_vanilla_effect() {
        // FX model with emitters/lights.
        let base = match k1_override_dir() {
            Some(d) => d,
            None => return,
        };
        binary_ascii_roundtrip(&format!("{base}/fx_carbref.mdl"), None);
    }
}