rakata_generics/

utw.rs

//! UTW (`.utw`) typed generic wrapper.
//!
//! Waypoints are invisible logic markers: named static coordinates in an area
//! that patrol routes, spawn points, camera focal points and the player's map
//! pins refer to. Nothing renders them.
//!
//! ## Field Layout
//! ```text
//! UTW root struct
//! +-- TemplateResRef / Tag / LocalizedName
//! +-- Appearance / PaletteID / Comment
//! +-- HasMapNote / MapNoteEnabled / MapNote
//! +-- Description / LinkedTo
//! +-- XPosition / YPosition / ZPosition
//! +-- XOrientation / YOrientation / ZOrientation
//! ```

use std::io::{Cursor, Read, Write};

use rakata_core::ResRef;
use rakata_formats::gff::upsert_field;
use rakata_formats::gff_label;
use rakata_formats::schema::FromGff;
use rakata_formats::GENERIC_FILE_TYPE;
use rakata_formats::{
    read_gff, read_gff_from_bytes, write_gff, Gff, GffBinaryError, GffLocalizedString, GffModel,
    GffStruct, GffValue,
};
use thiserror::Error;

/// Typed UTW model built from/to [`Gff`] data.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct Utw {
    /// Waypoint template resref (`TemplateResRef`).
    #[gff(TemplateResRef)]
    pub template_resref: ResRef,
    /// Waypoint tag (`Tag`).
    #[gff(Tag, stamped)]
    pub tag: String,
    /// Localized waypoint name (`LocalizedName`).
    #[gff(LocalizedName, stamped)]
    pub name: GffLocalizedString,
    /// Waypoint appearance id (`Appearance`). Never read by the K1 engine.
    #[gff(
        Appearance,
        read_only_dead = "a placed waypoint has no rendered model to select, and LoadWaypoint's fully-decompiled field list has no room for it",
        not_a_constant
    )]
    pub appearance_id: u8,
    /// Has-map-note flag (`HasMapNote`).
    #[gff(HasMapNote, constructed)]
    pub has_map_note: bool,
    /// Map-note-enabled flag (`MapNoteEnabled`). Engine ignores this if `has_map_note` is false.
    #[gff(MapNoteEnabled, stamped)]
    pub map_note_enabled: bool,
    /// Localized map note (`MapNote`). Engine ignores this if `has_map_note` is false.
    #[gff(MapNote, constructed)]
    pub map_note: GffLocalizedString,
    /// Palette id (`PaletteID`).
    #[gff(PaletteID)]
    pub palette_id: u8,
    /// Toolset comment (`Comment`).
    #[gff(Comment)]
    pub comment: String,
    /// Deprecated linked target (`LinkedTo`).
    #[gff(LinkedTo)]
    pub linked_to: String,
    /// Deprecated localized description (`Description`).
    #[gff(Description)]
    pub description: GffLocalizedString,
    /// World X position (`XPosition`).
    #[gff(XPosition, stamped, omit = audited_constant(2058))]
    pub x_position: f32,
    /// World Y position (`YPosition`).
    #[gff(YPosition, stamped, omit = audited_constant(2058))]
    pub y_position: f32,
    /// World Z position (`ZPosition`).
    #[gff(ZPosition, stamped, omit = audited_constant(2058))]
    pub z_position: f32,
    /// Facing X component (`XOrientation`).
    ///
    /// The engine normalizes the orientation vector at runtime if its
    /// magnitude is not 1.0. The write is hand-written because the condition
    /// is the whole vector rather than any one component. It is in `to_gff`.
    #[gff(XOrientation, not_a_constant, manual_write)]
    pub x_orientation: f32,
    /// Facing Y component (`YOrientation`).
    ///
    /// Written with the rest of the vector. See [`Utw::x_orientation`].
    #[gff(YOrientation, not_a_constant, manual_write)]
    pub y_orientation: f32,
    /// Facing Z component (`ZOrientation`).
    ///
    /// Written with the rest of the vector. See [`Utw::x_orientation`].
    #[gff(ZOrientation, not_a_constant, manual_write)]
    pub z_orientation: f32,
}

impl Utw {
    /// Creates an empty UTW value.
    pub fn new() -> Self {
        Self::default()
    }

    /// Builds typed UTW data from a parsed GFF container.
    ///
    /// # Errors
    ///
    /// Returns [`UtwError::UnsupportedFileType`] for a container that is
    /// neither `UTW ` nor the generic `GFF ` form.
    pub fn from_gff(gff: &Gff) -> Result<Self, UtwError> {
        if gff.file_type != <Utw as FromGff>::MAGIC && gff.file_type != GENERIC_FILE_TYPE {
            return Err(UtwError::UnsupportedFileType(gff.file_type));
        }

        Ok(Self::read_declared(&gff.root))
    }

    /// Converts this typed UTW value into a GFF container.
    pub fn to_gff(&self) -> Gff {
        let mut root = GffStruct::new(-1);
        self.write_declared(&mut root);

        // Omitted as a group or not at all. No vanilla waypoint carries any
        // of the three, and `utw.md` records the fallback as a property of
        // the vector rather than of any component: with all three absent the
        // engine reads a zero vector, and `Vector::Normalize` refuses to
        // divide below a magnitude of 1e-9 and snaps to a sentinel facing of
        // (1, 0, 0). Dropping one component of a real orientation would
        // change the magnitude and normalize somewhere else, so the condition
        // has to be the whole vector.
        //
        // The condition is the zero vector rather than the (1, 0, 0) sentinel
        // the engine ends up with. That sentinel is what normalization
        // produces after the read, and this view projects the file: an
        // omitted component reads back as 0.0, so omitting at zero
        // round-trips and omitting at the sentinel would not.
        let facing_unset =
            self.x_orientation == 0.0 && self.y_orientation == 0.0 && self.z_orientation == 0.0;
        if !facing_unset {
            upsert_field(
                &mut root,
                gff_label!("XOrientation"),
                GffValue::Single(self.x_orientation),
            );
            upsert_field(
                &mut root,
                gff_label!("YOrientation"),
                GffValue::Single(self.y_orientation),
            );
            upsert_field(
                &mut root,
                gff_label!("ZOrientation"),
                GffValue::Single(self.z_orientation),
            );
        }

        Gff::new(*b"UTW ", root)
    }
}

/// Errors produced while reading or writing typed UTW data.
#[derive(Debug, Error)]
pub enum UtwError {
    /// Source file type is not supported by this parser.
    #[error("unsupported UTW file type: {0:?}")]
    UnsupportedFileType([u8; 4]),
    /// Underlying GFF parser/writer error.
    #[error(transparent)]
    Gff(#[from] GffBinaryError),
}

/// Reads typed UTW data from a reader at the current stream position.
///
/// # Errors
///
/// [`UtwError::Gff`] when the stream is not a readable GFF, and
/// [`UtwError::UnsupportedFileType`] when it is a GFF of some other format,
/// carrying the fourcc that was found.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader))
)]
pub fn read_utw<R: Read>(reader: &mut R) -> Result<Utw, UtwError> {
    let gff = read_gff(reader)?;
    Utw::from_gff(&gff)
}

/// Reads typed UTW data directly from bytes.
///
/// # Errors
///
/// [`UtwError::Gff`] when `bytes` are not a readable GFF, and
/// [`UtwError::UnsupportedFileType`] when they are a GFF of some other format,
/// carrying the fourcc that was found.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(bytes), fields(bytes_len = bytes.len()))
)]
pub fn read_utw_from_bytes(bytes: &[u8]) -> Result<Utw, UtwError> {
    let gff = read_gff_from_bytes(bytes)?;
    Utw::from_gff(&gff)
}

/// Authors the UTW file the typed view describes, into a writer.
///
/// # Errors
///
/// [`UtwError::Gff`] when the writer fails or a value will not encode. The
/// typed view fixes the file type, so `UnsupportedFileType` cannot arise on
/// this side.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(writer, utw))
)]
pub fn author_utw<W: Write>(writer: &mut W, utw: &Utw) -> Result<(), UtwError> {
    let gff = utw.to_gff();
    write_gff(writer, &gff)?;
    Ok(())
}

/// Authors the UTW file the typed view describes, as bytes.
///
/// # Errors
///
/// [`UtwError::Gff`] when a value will not encode. Writing into a `Vec` has no
/// I/O to fail at.
#[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip(utw)))]
pub fn author_utw_to_vec(utw: &Utw) -> Result<Vec<u8>, UtwError> {
    let mut cursor = Cursor::new(Vec::new());
    author_utw(&mut cursor, utw)?;
    Ok(cursor.into_inner())
}

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

    #[test]
    fn orientation_is_omitted_as_a_group_or_written_as_a_group() {
        // Both directions, because a joint condition that half-fires is the
        // failure worth catching: dropping one component of a real facing
        // changes the vector's magnitude and normalizes it somewhere else.
        let labels = ["XOrientation", "YOrientation", "ZOrientation"];

        let unset = Utw::default();
        assert_eq!(
            (
                unset.x_orientation,
                unset.y_orientation,
                unset.z_orientation
            ),
            (0.0, 0.0, 0.0)
        );
        let written = unset.to_gff();
        for label in labels {
            assert!(
                written.root.field(label).is_none(),
                "{label} must be omitted when the whole vector is unset"
            );
        }

        // One component set is enough to write all three. The zeroes are
        // meaningful here: they are two thirds of a real facing.
        let facing = Utw {
            x_orientation: 1.0,
            ..Utw::default()
        };
        let written = facing.to_gff();
        for label in labels {
            assert!(
                written.root.field(label).is_some(),
                "{label} must be written when any component is set"
            );
        }

        // And the round trip holds in both states, which is what makes
        // omitting at the zero vector rather than at the (1, 0, 0) sentinel
        // the correct condition for a projection.
        for view in [Utw::default(), facing] {
            let back = Utw::from_gff(&view.to_gff()).expect("a UTW round-trips");
            assert_eq!(back.x_orientation, view.x_orientation);
            assert_eq!(back.y_orientation, view.y_orientation);
            assert_eq!(back.z_orientation, view.z_orientation);
        }
    }

    const TEST_UTW: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/test.utw"
    ));
    const TAR05_UTW: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/tar05_sw05aa10.utw"
    ));

    #[test]
    fn reads_core_utw_fields_from_fixture() {
        let utw = read_utw_from_bytes(TEST_UTW).expect("fixture must parse");

        assert_eq!(utw.appearance_id, 1);
        assert_eq!(utw.linked_to, "");
        assert_eq!(utw.template_resref, "sw_mapnote011");
        assert_eq!(utw.tag, "MN_106PER2");
        assert_eq!(utw.name.string_ref.raw(), 76_857);
        assert_eq!(utw.description.string_ref.raw(), -1);
        assert!(utw.has_map_note);
        assert_eq!(utw.map_note.string_ref.raw(), 76_858);
        assert!(utw.map_note_enabled);
        assert_eq!(utw.palette_id, 5);
        assert_eq!(utw.comment, "comment");
    }

    #[test]
    fn reads_tar05_fixture_variant() {
        let utw = read_utw_from_bytes(TAR05_UTW).expect("fixture must parse");

        assert_eq!(utw.appearance_id, 0);
        assert_eq!(utw.linked_to, "");
        assert_eq!(utw.template_resref, "");
        assert_eq!(utw.tag, "");
        assert_eq!(utw.name.string_ref.raw(), -1);
        assert_eq!(utw.description.string_ref.raw(), -1);
        assert!(!utw.has_map_note);
        assert_eq!(utw.map_note.string_ref.raw(), -1);
        assert!(!utw.map_note_enabled);
        assert_eq!(utw.palette_id, 0);
        assert_eq!(utw.comment, "");
    }

    #[test]
    fn all_fields_survive_typed_roundtrip() {
        let utw = read_utw_from_bytes(TEST_UTW).expect("fixture must parse");
        let bytes = author_utw_to_vec(&utw).expect("write succeeds");
        let reparsed = read_utw_from_bytes(&bytes).expect("reparse succeeds");

        assert_eq!(reparsed, utw);
    }

    #[test]
    fn typed_edits_roundtrip_through_gff_writer() {
        let mut utw = read_utw_from_bytes(TEST_UTW).expect("fixture must parse");
        utw.tag = "MN_106PER2_Rust".into();
        utw.has_map_note = false;
        utw.map_note_enabled = false;

        let bytes = author_utw_to_vec(&utw).expect("write succeeds");
        let reparsed = read_utw_from_bytes(&bytes).expect("reparse succeeds");

        assert_eq!(reparsed.tag, "MN_106PER2_Rust");
        assert!(!reparsed.has_map_note);
        assert!(!reparsed.map_note_enabled);
    }

    #[test]
    fn read_utw_from_reader_matches_bytes_path() {
        let mut cursor = Cursor::new(TEST_UTW);
        let via_reader = read_utw(&mut cursor).expect("reader parse succeeds");
        let via_bytes = read_utw_from_bytes(TEST_UTW).expect("bytes parse succeeds");

        assert_eq!(via_reader, via_bytes);
    }

    #[test]
    fn rejects_non_utw_file_type() {
        let mut gff = read_gff_from_bytes(TEST_UTW).expect("fixture must parse");
        gff.file_type = *b"UTT ";

        let err = Utw::from_gff(&gff).expect_err("UTT must be rejected as UTW input");
        assert!(matches!(
            err,
            UtwError::UnsupportedFileType(file_type) if file_type == *b"UTT "
        ));
    }

    #[test]
    fn a_mistyped_map_note_reads_as_absent() {
        let mut gff = read_gff_from_bytes(TEST_UTW).expect("fixture must parse");
        gff.root.fields.retain(|field| field.label != "MapNote");
        gff.root
            .push_field(gff_label!("MapNote"), GffValue::UInt32(123));

        let utw = Utw::from_gff(&gff).expect("a mistyped field is not a read failure");

        assert_eq!(utw.map_note, GffLocalizedString::default());
    }

    #[test]
    fn write_utw_matches_direct_gff_writer() {
        let utw = read_utw_from_bytes(TEST_UTW).expect("fixture must parse");

        let via_typed = author_utw_to_vec(&utw).expect("typed write succeeds");

        let mut direct = Cursor::new(Vec::new());
        write_gff(&mut direct, &utw.to_gff()).expect("direct write succeeds");

        assert_eq!(via_typed, direct.into_inner());
    }

    #[test]
    fn schema_field_count() {
        assert_eq!(Utw::schema().len(), 17); // 11 engine + 6 toolset
    }

    #[test]
    fn schema_no_duplicate_labels() {
        let mut labels: Vec<&str> = Utw::schema().iter().map(|f| f.label.as_str()).collect();
        labels.sort_unstable();
        let before = labels.len();
        labels.dedup();
        assert_eq!(before, labels.len(), "duplicate labels in UTW schema");
    }
}