rakata_formats/mdl/

ascii_names.rs

//! ASCII MDL name registry for controllers, classifications, and node types.
//!
//! Provides bidirectional mappings between binary format codes and the ASCII
//! field name strings used by the engine's text-mode MDL parser. Controller
//! type codes are node-type-specific -- the same numeric code has different
//! ASCII names on different node types (e.g., code 100 is `selfillumcolor`
//! on mesh, `verticaldisplacement` on light, and `drag` on emitter).
//!
//! All 58 controller codes are independently traced against `swkotor.exe`:
//! 3 base (`MdlNode::InternalParseField`, `0x00465560`), 48 emitter
//! (`MdlNodeEmitter`, `0x004658b0`), 5 light (`MdlNodeLight`, `0x00469150`)
//! and 2 mesh (`MdlNodeTriMesh`, `0x00469700`). The set is closed rather
//! than sampled: every call site of the three controller-registration sinks
//! in the whole binary falls inside those four functions, so no other node
//! type has a controller vocabulary of its own. `MdlNodeSkin` tail-calls the
//! mesh parser, which is why the mesh pair covers the whole mesh family.

use super::controllers::MdlControllerType;
use super::types::{
    MdlAabb, MdlAnimMesh, MdlDangly, MdlEmitter, MdlLight, MdlNodeData, MdlReference, MdlSaber,
    MdlSkin,
};

/// Node type context for disambiguating controller names.
///
/// The engine dispatches ASCII field parsing through type-specific
/// `InternalParseField` functions. Base controllers (position, orientation,
/// scale) are handled by the base dispatcher; type-specific controllers
/// use separate lookup tables.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NodeTypeContext {
    /// Base node (dummy, camera) -- only base controllers.
    Base,
    /// Mesh node (trimesh, skin, dangly, aabb, saber, animmesh).
    Mesh,
    /// Light node.
    Light,
    /// Emitter node.
    Emitter,
}

/// Base controller entries shared across all node types.
///
/// Traced from `MdlNode::InternalParseField` (`0x00465560`). Node types with
/// no parser of their own, such as saber and camera, get only these three.
const BASE_CONTROLLERS: &[(u32, &str)] = &[(8, "position"), (20, "orientation"), (36, "scale")];

/// Mesh-specific controller entries.
///
/// Traced from `MdlNodeTriMesh::InternalParseField` (`0x00469700`). Applies
/// to every mesh-family node: `MdlNodeSkin` tail-calls this parser rather
/// than registering its own.
const MESH_CONTROLLERS: &[(u32, &str)] = &[(100, "selfillumcolor"), (132, "alpha")];

/// Light-specific controller entries.
///
/// Traced from `MdlNodeLight::InternalParseField` (`0x00469150`).
const LIGHT_CONTROLLERS: &[(u32, &str)] = &[
    (76, "color"),
    (88, "radius"),
    (96, "shadowradius"),
    (100, "verticaldisplacement"),
    (140, "multiplier"),
];

/// Emitter-specific controller entries.
///
/// All 48 codes and their name strings traced from
/// `MdlNodeEmitter::InternalParseField` at `0x004658b0`.
const EMITTER_CONTROLLERS: &[(u32, &str)] = &[
    (80, "alphaEnd"),
    (84, "alphaStart"),
    (88, "birthrate"),
    (92, "bounce_co"),
    (96, "combinetime"),
    (100, "drag"),
    (104, "fps"),
    (108, "frameEnd"),
    (112, "frameStart"),
    (116, "grav"),
    (120, "lifeExp"),
    (124, "mass"),
    (128, "p2p_bezier2"),
    (132, "p2p_bezier3"),
    (136, "particleRot"),
    (140, "randvel"),
    (144, "sizeStart"),
    (148, "sizeEnd"),
    (152, "sizeStart_y"),
    (156, "sizeEnd_y"),
    (160, "spread"),
    (164, "threshold"),
    (168, "velocity"),
    (172, "xsize"),
    (176, "ysize"),
    (180, "blurlength"),
    (184, "lightningDelay"),
    (188, "lightningRadius"),
    (192, "lightningScale"),
    (196, "lightningSubDiv"),
    (200, "lightningZigzag"),
    (216, "alphaMid"),
    (220, "percentStart"),
    (224, "percentMid"),
    (228, "percentEnd"),
    (232, "sizeMid"),
    (236, "sizeMid_y"),
    (240, "m_fRandomBirthRate"),
    (252, "targetsize"),
    (256, "numcontrolpts"),
    (260, "controlptradius"),
    (264, "controlptdelay"),
    (268, "tangentspread"),
    (272, "tangentlength"),
    (284, "colorMid"),
    (380, "colorEnd"),
    (392, "colorStart"),
    (502, "detonate"),
];

/// Returns the ASCII name for a controller type in a given node context.
///
/// Base controllers (position, orientation, scale) are checked first, then
/// the type-specific table. Returns `None` for unknown codes -- callers
/// should use a `controller_<code>` fallback.
pub fn controller_ascii_name(
    code: MdlControllerType,
    ctx: NodeTypeContext,
) -> Option<&'static str> {
    let raw = code.raw();

    // Base controllers apply to all node types.
    for &(c, name) in BASE_CONTROLLERS {
        if c == raw {
            return Some(name);
        }
    }

    // Type-specific lookup.
    let table = match ctx {
        NodeTypeContext::Base => return None,
        NodeTypeContext::Mesh => MESH_CONTROLLERS,
        NodeTypeContext::Light => LIGHT_CONTROLLERS,
        NodeTypeContext::Emitter => EMITTER_CONTROLLERS,
    };

    for &(c, name) in table {
        if c == raw {
            return Some(name);
        }
    }

    None
}

/// Returns the controller type code for an ASCII name in a given node context.
///
/// Case-insensitive lookup. Base controllers are checked first, then
/// the type-specific table. Returns `None` for unrecognized names.
pub fn controller_from_ascii_name(name: &str, ctx: NodeTypeContext) -> Option<MdlControllerType> {
    // Base controllers apply to all node types.
    for &(code, ascii) in BASE_CONTROLLERS {
        if ascii.eq_ignore_ascii_case(name) {
            return Some(MdlControllerType::from_raw(code));
        }
    }

    // Type-specific lookup.
    let table = match ctx {
        NodeTypeContext::Base => return None,
        NodeTypeContext::Mesh => MESH_CONTROLLERS,
        NodeTypeContext::Light => LIGHT_CONTROLLERS,
        NodeTypeContext::Emitter => EMITTER_CONTROLLERS,
    };

    for &(code, ascii) in table {
        if ascii.eq_ignore_ascii_case(name) {
            return Some(MdlControllerType::from_raw(code));
        }
    }

    None
}

/// Classification byte-to-string mapping.
///
/// The eight codes are independently established: all eight are attested in
/// models indexed by a retail `chitin.key`.
///
/// The **name strings** cannot be attested, and that is a finding rather than
/// an outstanding task. `swkotor.exe` carries no ASCII name for any
/// classification bit: no `classification` string anywhere, no adjacent table
/// of eight names, and the individual words that do occur all belong to
/// unrelated subsystems. The ASCII model parser recognises four keywords and
/// none of them is this. So the names are tool-side vocabulary with no
/// engine-side term to compare against, and re-derivation from this binary is
/// not available. See `docs/src/legal.md`.
const CLASSIFICATIONS: &[(u8, &str)] = &[
    (0, "other"),
    (1, "effect"),
    (2, "tile"),
    (4, "character"),
    (8, "door"),
    (16, "lightsaber"),
    (32, "placeable"),
    (64, "flyer"),
];

/// Returns the ASCII classification string for a classification byte.
///
/// Defaults to `"Other"` for unrecognized codes.
pub fn classification_to_ascii(code: u8) -> &'static str {
    for &(c, name) in CLASSIFICATIONS {
        if c == code {
            return name;
        }
    }
    "Other"
}

/// Returns the classification byte for an ASCII classification string.
///
/// Case-insensitive. Returns `None` for unrecognized strings.
pub fn classification_from_ascii(name: &str) -> Option<u8> {
    for &(code, ascii) in CLASSIFICATIONS {
        if ascii.eq_ignore_ascii_case(name) {
            return Some(code);
        }
    }
    None
}

/// Returns the ASCII node type string for a node data variant.
///
/// These strings appear after the `node` keyword in ASCII MDL files
/// (e.g., `node trimesh torso_g`). Camera nodes use `"dummy"` since the
/// engine has no camera-specific ASCII type keyword.
pub fn node_type_ascii_name(data: &MdlNodeData) -> &'static str {
    match data {
        MdlNodeData::Base => "dummy",
        MdlNodeData::Light(_) => "light",
        MdlNodeData::Emitter(_) => "emitter",
        MdlNodeData::Camera(_) => "dummy",
        MdlNodeData::Reference(_) => "reference",
        MdlNodeData::Mesh(_) => "trimesh",
        MdlNodeData::Skin(_) => "skin",
        MdlNodeData::AnimMesh(_) => "animmesh",
        MdlNodeData::Dangly(_) => "danglymesh",
        MdlNodeData::Aabb(_) => "aabb",
        MdlNodeData::Saber(_) => "lightsaber",
    }
}

/// Returns the [`NodeTypeContext`] for a node data variant.
///
/// Used to select the correct controller name lookup table.
pub fn node_type_context(data: &MdlNodeData) -> NodeTypeContext {
    match data {
        MdlNodeData::Base | MdlNodeData::Camera(_) => NodeTypeContext::Base,
        MdlNodeData::Light(_) => NodeTypeContext::Light,
        MdlNodeData::Emitter(_) => NodeTypeContext::Emitter,
        MdlNodeData::Mesh(_)
        | MdlNodeData::Skin(_)
        | MdlNodeData::AnimMesh(_)
        | MdlNodeData::Dangly(_)
        | MdlNodeData::Aabb(_)
        | MdlNodeData::Saber(_)
        | MdlNodeData::Reference(_) => NodeTypeContext::Mesh,
    }
}

/// Returns the default [`MdlNodeData`] variant for an ASCII node type string.
///
/// Case-insensitive. Unrecognized strings (including `"dummy"`) produce
/// [`MdlNodeData::Base`].
pub fn node_data_from_ascii_name(name: &str) -> MdlNodeData {
    if name.eq_ignore_ascii_case("trimesh") {
        MdlNodeData::Mesh(Default::default())
    } else if name.eq_ignore_ascii_case("skin") {
        MdlNodeData::Skin(MdlSkin::default())
    } else if name.eq_ignore_ascii_case("danglymesh") {
        MdlNodeData::Dangly(MdlDangly::default())
    } else if name.eq_ignore_ascii_case("aabb") {
        MdlNodeData::Aabb(MdlAabb::default())
    } else if name.eq_ignore_ascii_case("lightsaber") {
        MdlNodeData::Saber(MdlSaber::default())
    } else if name.eq_ignore_ascii_case("light") {
        MdlNodeData::Light(MdlLight::default())
    } else if name.eq_ignore_ascii_case("emitter") {
        MdlNodeData::Emitter(MdlEmitter::default())
    } else if name.eq_ignore_ascii_case("reference") {
        MdlNodeData::Reference(MdlReference::default())
    } else if name.eq_ignore_ascii_case("animmesh") {
        MdlNodeData::AnimMesh(MdlAnimMesh::default())
    } else {
        MdlNodeData::Base
    }
}

/// Returns true for ASCII MDL keywords that should NOT be interpreted as
/// inline controllers, even if they could parse as float values.
///
/// This list covers all mesh, light, emitter, dangly, aabb, skin, animmesh,
/// and reference fields, plus structural keywords (node/endnode, model
/// header directives, animation directives).
pub fn is_non_controller_keyword(name: &str) -> bool {
    const KEYWORDS: &[&str] = &[
        "parent",
        "bitmap",
        "bitmap2",
        "texture0",
        "texture1",
        "diffuse",
        "ambient",
        "transparencyhint",
        "animateuv",
        "uvdirectionx",
        "uvdirectiony",
        "uvjitter",
        "uvjitterspeed",
        "lightmapped",
        "rotatetexture",
        "m_bisbackgroundgeometry",
        "shadow",
        "beaming",
        "render",
        "verts",
        "faces",
        "tverts",
        "tverts0",
        "tverts1",
        "tverts2",
        "tverts3",
        "colors",
        "tangentspace",
        "dirt_enabled",
        "dirt_texture",
        "dirt_worldspace",
        "hologram_donotdraw",
        "inv_count",
        "weights",
        "skinweights",
        "constraints",
        "displacement",
        "tightness",
        "period",
        "aabb",
        "lightpriority",
        "ambientonly",
        "ndynamictype",
        "affectdynamic",
        "generateflare",
        "fadinglight",
        "flareradius",
        "lensflares",
        "texturenames",
        "flarepositions",
        "flaresizes",
        "flarecolorshifts",
        "deadspace",
        "blastradius",
        "blastlength",
        "numbranches",
        "controlptsmoothing",
        "xgrid",
        "ygrid",
        "spawntype",
        "update",
        "blend",
        "texture",
        "chunkname",
        "twosidedtex",
        "loop",
        "renderorder",
        "m_bframeblending",
        "m_sdepthtexturename",
        "p2p",
        "p2p_sel",
        "affectedbywind",
        "m_istinted",
        "bounce",
        "random",
        "inherit",
        "inheritvel",
        "inherit_local",
        "splat",
        "inherit_part",
        "depth_texture",
        "refmodel",
        "reattachable",
        "sampleperiod",
        "animverts",
        "animtverts",
        "bmin",
        "bmax",
        "endnode",
        "endmodelgeom",
        "donemodel",
        "doneanim",
        "beginmodelgeom",
        "newmodel",
        "newanim",
        "node",
        "endlist",
        "compress_quaternions",
        "headlink",
        "setanimationscale",
        "ignorefog",
        "classification",
        "classification_unk1",
        "setsupermodel",
        "length",
        "transtime",
        "animroot",
        "event",
    ];
    let lower = name.to_ascii_lowercase();
    KEYWORDS.contains(&lower.as_str())
}

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

    #[test]
    fn base_controllers_all_contexts() {
        // Base controllers should resolve in every context.
        for ctx in [
            NodeTypeContext::Base,
            NodeTypeContext::Mesh,
            NodeTypeContext::Light,
            NodeTypeContext::Emitter,
        ] {
            assert_eq!(
                controller_ascii_name(MdlControllerType::POSITION, ctx),
                Some("position")
            );
            assert_eq!(
                controller_ascii_name(MdlControllerType::ORIENTATION, ctx),
                Some("orientation")
            );
            assert_eq!(
                controller_ascii_name(MdlControllerType::SCALE, ctx),
                Some("scale")
            );
        }
    }

    #[test]
    fn code_100_disambiguation() {
        // Code 100 means different things per node type.
        assert_eq!(
            controller_ascii_name(MdlControllerType::SELFILLUMCOLOR, NodeTypeContext::Mesh),
            Some("selfillumcolor")
        );
        assert_eq!(
            controller_ascii_name(
                MdlControllerType::VERTICAL_DISPLACEMENT,
                NodeTypeContext::Light
            ),
            Some("verticaldisplacement")
        );
        assert_eq!(
            controller_ascii_name(MdlControllerType::DRAG, NodeTypeContext::Emitter),
            Some("drag")
        );
    }

    #[test]
    fn reverse_lookup_case_insensitive() {
        assert_eq!(
            controller_from_ascii_name("Position", NodeTypeContext::Base),
            Some(MdlControllerType::POSITION)
        );
        assert_eq!(
            controller_from_ascii_name("SELFILLUMCOLOR", NodeTypeContext::Mesh),
            Some(MdlControllerType::SELFILLUMCOLOR)
        );
        assert_eq!(
            controller_from_ascii_name("birthrate", NodeTypeContext::Emitter),
            Some(MdlControllerType::BIRTHRATE)
        );
    }

    #[test]
    fn unknown_controller_returns_none() {
        assert_eq!(
            controller_ascii_name(MdlControllerType::from_raw(9999), NodeTypeContext::Mesh),
            None
        );
    }

    #[test]
    fn classification_roundtrip() {
        for &(code, name) in CLASSIFICATIONS {
            assert_eq!(classification_to_ascii(code), name);
            assert_eq!(classification_from_ascii(name), Some(code));
        }
    }

    #[test]
    fn classification_case_insensitive() {
        assert_eq!(classification_from_ascii("character"), Some(4));
        assert_eq!(classification_from_ascii("CHARACTER"), Some(4));
    }

    #[test]
    fn node_type_names() {
        assert_eq!(node_type_ascii_name(&MdlNodeData::Base), "dummy");
        assert_eq!(
            node_type_ascii_name(&MdlNodeData::Mesh(Default::default())),
            "trimesh"
        );
    }
}