rakata_generics/

fac.rs

//! FAC (`.fac`) typed generic wrapper.
//!
//! A FAC resource is the whole session's faction table: the roster of factions
//! and how each one feels about every other. There is one per session, keyed on
//! the resref `REPUTE`, not one per creature. Objects (`.utc`, `.utd`, ...)
//! carry only a faction id that indexes into this table.
//!
//! ## Field Layout
//! ```text
//! FAC root struct
//! +-- FactionList (List<Struct>)
//! |   +-- FactionName / FactionParentID / FactionGlobal
//! +-- RepList     (List<Struct>)
//!     +-- FactionID1 / FactionID2 / FactionRep
//! ```
//!
//! ## The sparse matrix
//!
//! Reputation is stored sparsely, and this is the one thing to get right.
//! **An absent pair means `100`, which is friendly, not `0`, which is
//! hostile.** Reading `RepList` directly and treating misses as zero turns the
//! entire galaxy against the player. Use [`Fac::reputation`], which applies the
//! baseline.
//!
//! That baseline applies to a pair with no entry at all. A present entry
//! missing only its `FactionRep` is a different case and lands on `0`, which
//! is what [`FacReputation::standing`] declares.
//!
//! `docs/src/formats/gff/fac.md` has the rule and how the engine rebuilds the
//! full matrix from it.

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

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, GffModel, GffStruct, GffValue,
};
use thiserror::Error;

/// Standing applied to any faction pair with no stored `RepList` entry.
///
/// The top of the friendly band, not a midpoint.
pub const DEFAULT_REPUTATION: u8 = 100;

/// Highest standing the engine will hold after its load-time clamp.
const MAX_REPUTATION: i64 = 100;

/// Typed FAC model built from/to [`Gff`] data.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct Fac {
    /// Faction roster (`FactionList`). A faction's id is its index here.
    #[gff(FactionList, unexamined, list = FacFaction, element_id = positional)]
    pub factions: Vec<FacFaction>,
    /// Stored pairwise standings (`RepList`). Sparse: see [`Fac::reputation`].
    ///
    /// The write is hand-written because the filter runs on the typed element,
    /// where the standing it tests is reachable. The read generates, and
    /// reaches the element's own hand-written codec through it.
    #[gff(
        RepList,
        not_a_constant,
        list = FacReputation,
        element_id = positional,
        omit = elements(
            "a pair already at the friendly baseline says nothing, since it \
             overrides that baseline with itself, and CFactionManager::SaveReputations \
             emits an entry only for a pair that is not at it. A toolset-authored \
             .fac carries entries the engine would never have written",
            16
        ),
        manual_write
    )]
    pub reputations: Vec<FacReputation>,
}

impl Fac {
    /// Creates an empty faction table.
    pub fn new() -> Self {
        Self::default()
    }

    /// Returns how `source` regards `target`.
    ///
    /// Applies the sparse-matrix rule: a pair with no stored entry is
    /// [`DEFAULT_REPUTATION`]. Ids are faction indices into
    /// [`Self::factions`]; an id no faction occupies still answers with the
    /// baseline, matching the engine rebuilding its matrix before applying
    /// overrides.
    pub fn reputation(&self, source: u32, target: u32) -> u8 {
        self.reputations
            .iter()
            .find(|entry| entry.source == source && entry.target == target)
            .map_or(DEFAULT_REPUTATION, FacReputation::effective_standing)
    }

    /// Returns how `source` reacts to `target`.
    pub fn reaction(&self, source: u32, target: u32) -> FacReaction {
        FacReaction::from_standing(self.reputation(source, target))
    }

    /// Returns the faction at `id`, when the roster has one.
    pub fn faction(&self, id: u32) -> Option<&FacFaction> {
        usize::try_from(id).ok().and_then(|i| self.factions.get(i))
    }

    /// Builds typed FAC data from a parsed GFF container.
    ///
    /// # Errors
    ///
    /// Returns an error when the container is not a FAC (or generic GFF).
    pub fn from_gff(gff: &Gff) -> Result<Self, FacError> {
        if gff.file_type != <Fac as FromGff>::MAGIC && gff.file_type != GENERIC_FILE_TYPE {
            return Err(FacError::UnsupportedFileType(gff.file_type));
        }

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

    /// Converts this typed FAC value into a GFF container.
    ///
    /// Writes the table the way the engine's own writer does, which means
    /// pairs at the default standing are dropped rather than emitted. The two
    /// forms are identical to the engine, but other tools read these files
    /// too, and a diff against a vanilla save should not show pairs the game
    /// would never have written.
    ///
    /// Only pairs whose *effective* standing is the default are dropped, so a
    /// deliberately out-of-range value is still written out.
    ///
    /// # Panics
    ///
    /// Panics where the reputation list holds more than [`i32::MAX`] entries,
    /// since an element's struct id is its own index. A table that large
    /// cannot be built from any file this crate reads.
    pub fn to_gff(&self) -> Gff {
        let mut root = GffStruct::new(-1);
        self.write_declared(&mut root);

        upsert_field(
            &mut root,
            gff_label!("RepList"),
            GffValue::List(
                self.reputations
                    .iter()
                    .filter(|entry| entry.effective_standing() != DEFAULT_REPUTATION)
                    .enumerate()
                    .map(|(index, entry)| {
                        let mut structure = GffStruct::new(
                            i32::try_from(index).expect("reputation index fits i32"),
                        );
                        entry.write_element(&mut structure);
                        structure
                    })
                    .collect(),
            ),
        );

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

/// One faction from the `FactionList`.
///
/// The faction's own id is its position in the list and is not stored on the
/// element.
#[derive(Debug, Clone, PartialEq, Eq, GffModel)]
pub struct FacFaction {
    /// Display/lookup name (`FactionName`).
    #[gff(FactionName, stamped)]
    pub name: String,
    /// Parent faction id (`FactionParentID`).
    ///
    /// Kept as a raw id. Every one of the factions in all four committed save
    /// fixtures carries `0xFFFFFFFF`, which looks like a no-parent sentinel,
    /// but that reading has not been confirmed against the binary and the
    /// engine audit does not record a meaning for it. Modelling this as an
    /// absent parent would encode the guess; widening to an `Option` later
    /// costs nothing if an audit confirms it.
    #[gff(FactionParentID, stamped)]
    pub parent_id: u32,
    /// Whether this is one of the standard shared factions (`FactionGlobal`).
    ///
    /// Absent on load means `true`. The file holds it as a `WORD`, which is
    /// the one case the declared Rust type does not settle the encoding.
    #[gff(FactionGlobal, stamped = true, wire = u16)]
    pub global: bool,
}

/// One stored standing from the `RepList`.
#[derive(Debug, Clone, PartialEq, Eq, GffModel)]
pub struct FacReputation {
    /// Source faction id (`FactionID1`).
    #[gff(FactionID1, stamped)]
    pub source: u32,
    /// Target faction id (`FactionID2`).
    #[gff(FactionID2, stamped)]
    pub target: u32,
    /// How `source` regards `target` (`FactionRep`), as stored.
    ///
    /// Kept as written rather than clamped, so a file carrying an
    /// out-of-range value still shows it. The engine clamps to `0`-`100` when
    /// it loads; [`Self::effective_standing`] applies that.
    ///
    /// Both halves are hand-written: the file holds a `DWORD` and the engine
    /// reads it signed, so neither direction is one call.
    #[gff(FactionRep, required, stamped, wire = u32, manual_read, manual_write)]
    pub standing: i32,
}

impl FacReputation {
    /// Returns the standing the engine would hold after its load-time clamp.
    ///
    /// Values at or above `101` become `100`, negatives become `0`.
    pub fn effective_standing(&self) -> u8 {
        u8::try_from(i64::from(self.standing).clamp(0, MAX_REPUTATION))
            .unwrap_or(DEFAULT_REPUTATION)
    }

    /// Reads one `RepList` element.
    ///
    /// The derive supplies no `read_element` for a type with a hand-written
    /// read half, so this is where a list of these picks the hatch up.
    fn read_element(structure: &GffStruct) -> Self {
        let mut entry = Self::read_declared(structure);
        if let Some(standing) = read_standing(structure) {
            entry.standing = standing;
        }
        entry
    }

    /// Writes one `RepList` element.
    fn write_element(&self, structure: &mut GffStruct) {
        self.write_declared(structure);
        upsert_field(
            structure,
            gff_label!("FactionRep"),
            // Back to the bit pattern it was read from, so a stored negative
            // survives the trip unchanged.
            GffValue::UInt32(u32::from_ne_bytes(self.standing.to_ne_bytes())),
        );
    }
}

/// Reads `FactionRep` with the engine's signedness.
///
/// The field is written as a DWORD, but the engine interprets it as signed.
/// That distinction changes the answer: a stored `-1` reaches us as
/// `0xFFFFFFFF`, and reading it unsigned would make it four billion, which
/// clamps *up* to `100` (friendly) when the engine clamps it *down* to `0`
/// (hostile). Signedness is how the field is read correctly; the range clamp
/// is a separate step and belongs to [`FacReputation::effective_standing`].
///
/// `None` where the label is absent, which leaves the entry at the `0` its
/// declaration carries. `fac.md` is explicit that this is not the `100`
/// baseline: that one applies to a pair with no entry at all, and a present
/// entry missing only its standing writes hostile.
fn read_standing(structure: &GffStruct) -> Option<i32> {
    match structure.field("FactionRep")? {
        GffValue::UInt32(value) => Some(i32::from_ne_bytes(value.to_ne_bytes())),
        GffValue::Int32(value) => Some(*value),
        GffValue::UInt16(value) => Some(i32::from(*value)),
        GffValue::Int16(value) => Some(i32::from(*value)),
        GffValue::UInt8(value) => Some(i32::from(*value)),
        GffValue::Int8(value) => Some(i32::from(*value)),
        _ => None,
    }
}

/// How a standing reads at the script layer.
///
/// The same `10` and `90` boundaries decide whether an NPC treats you as an
/// enemy, whether a mine arms against you, and whether a faction-owned
/// placeable, door or trigger is usable.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum FacReaction {
    /// `0`-`10`: treated as an enemy.
    Hostile,
    /// `11`-`89`: neither friend nor enemy.
    Neutral,
    /// `90`-`100`: treated as a friend.
    Friendly,
}

impl FacReaction {
    /// Classifies a `0`-`100` standing into its reaction band.
    pub fn from_standing(standing: u8) -> Self {
        match standing {
            0..=10 => Self::Hostile,
            11..=89 => Self::Neutral,
            _ => Self::Friendly,
        }
    }
}

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

/// Reads typed FAC data from a reader at the current stream position.
///
/// # Errors
///
/// [`FacError::Gff`] when the stream is not a readable GFF, and
/// [`FacError::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_fac<R: Read>(reader: &mut R) -> Result<Fac, FacError> {
    let gff = read_gff(reader)?;
    Fac::from_gff(&gff)
}

/// Reads typed FAC data directly from bytes.
///
/// # Errors
///
/// [`FacError::Gff`] when `bytes` are not a readable GFF, and
/// [`FacError::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_fac_from_bytes(bytes: &[u8]) -> Result<Fac, FacError> {
    let gff = read_gff_from_bytes(bytes)?;
    Fac::from_gff(&gff)
}

/// Authors the FAC file the typed view describes, into a writer.
///
/// # Errors
///
/// [`FacError::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, fac))
)]
pub fn author_fac<W: Write>(writer: &mut W, fac: &Fac) -> Result<(), FacError> {
    let gff = fac.to_gff();
    write_gff(writer, &gff)?;
    Ok(())
}

/// Authors the FAC file the typed view describes, as bytes.
///
/// # Errors
///
/// [`FacError::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(fac)))]
pub fn author_fac_to_vec(fac: &Fac) -> Result<Vec<u8>, FacError> {
    let mut cursor = Cursor::new(Vec::new());
    author_fac(&mut cursor, fac)?;
    Ok(cursor.into_inner())
}

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

    fn sample() -> Fac {
        Fac {
            factions: vec![
                FacFaction {
                    name: "PLAYER".to_string(),
                    ..FacFaction::default()
                },
                FacFaction {
                    name: "Hostile".to_string(),
                    parent_id: 0,
                    global: false,
                },
            ],
            reputations: vec![FacReputation {
                source: 0,
                target: 1,
                standing: 5,
            }],
        }
    }

    #[test]
    fn round_trips_through_gff() {
        let fac = sample();

        let bytes = author_fac_to_vec(&fac).expect("writes");
        let parsed = read_fac_from_bytes(&bytes).expect("reads back");

        assert_eq!(parsed, fac);
    }

    #[test]
    fn an_absent_pair_is_friendly_not_hostile() {
        let fac = sample();

        // Stored the other way round only; 1 -> 0 has no entry.
        assert_eq!(fac.reputation(0, 1), 5);
        assert_eq!(fac.reputation(1, 0), DEFAULT_REPUTATION);
        assert_eq!(fac.reaction(1, 0), FacReaction::Friendly);
        assert_eq!(fac.reaction(0, 1), FacReaction::Hostile);
    }

    #[test]
    fn an_unknown_faction_id_still_answers_with_the_baseline() {
        let fac = sample();

        assert_eq!(fac.reputation(99, 42), DEFAULT_REPUTATION);
        assert!(fac.faction(99).is_none());
    }

    #[test]
    fn reaction_bands_match_the_documented_boundaries() {
        assert_eq!(FacReaction::from_standing(0), FacReaction::Hostile);
        assert_eq!(FacReaction::from_standing(10), FacReaction::Hostile);
        assert_eq!(FacReaction::from_standing(11), FacReaction::Neutral);
        assert_eq!(FacReaction::from_standing(89), FacReaction::Neutral);
        assert_eq!(FacReaction::from_standing(90), FacReaction::Friendly);
        assert_eq!(FacReaction::from_standing(100), FacReaction::Friendly);
    }

    #[test]
    fn a_missing_faction_global_defaults_to_true() {
        let mut structure = GffStruct::new(0);
        structure.push_field(gff_label!("FactionName"), GffValue::String("X".to_string()));

        assert!(FacFaction::read_declared(&structure).global);
    }

    #[test]
    fn a_negative_standing_reads_as_negative_not_as_four_billion() {
        // Written as a DWORD, -1 arrives as 0xFFFFFFFF. Read unsigned it would
        // become u32::MAX and clamp up to friendly.
        let mut structure = GffStruct::new(0);
        structure.push_field(gff_label!("FactionRep"), GffValue::UInt32(u32::MAX));

        assert_eq!(read_standing(&structure), Some(-1));

        // An absent label is not a value, so the entry keeps the 0 its
        // declaration carries rather than the 100 sparse-matrix baseline.
        assert_eq!(read_standing(&GffStruct::new(0)), None);
        assert_eq!(FacReputation::default().standing, 0);
    }

    #[test]
    fn out_of_range_standings_are_kept_but_clamp_when_asked() {
        let hostile = FacReputation {
            source: 0,
            target: 1,
            standing: -1,
        };
        let over = FacReputation {
            source: 0,
            target: 2,
            standing: 500,
        };

        // Stored as written...
        assert_eq!(hostile.standing, -1);
        assert_eq!(over.standing, 500);
        // ...and clamped only where the engine would.
        assert_eq!(hostile.effective_standing(), 0);
        assert_eq!(over.effective_standing(), 100);
    }

    #[test]
    fn a_pair_at_the_default_is_not_written() {
        let fac = Fac {
            factions: vec![FacFaction::default()],
            reputations: vec![
                FacReputation {
                    source: 0,
                    target: 0,
                    standing: i32::from(DEFAULT_REPUTATION),
                },
                FacReputation {
                    source: 0,
                    target: 1,
                    standing: 5,
                },
            ],
        };

        let bytes = author_fac_to_vec(&fac).expect("writes");
        let parsed = read_fac_from_bytes(&bytes).expect("reads back");

        // The default pair is dropped the way the engine's writer drops it;
        // reading it back still answers with the baseline.
        assert_eq!(parsed.reputations.len(), 1);
        assert_eq!(parsed.reputations[0].target, 1);
        assert_eq!(parsed.reputation(0, 0), DEFAULT_REPUTATION);
    }

    #[test]
    fn an_out_of_range_standing_survives_a_round_trip() {
        let fac = Fac {
            factions: vec![FacFaction::default()],
            reputations: vec![FacReputation {
                source: 0,
                target: 0,
                standing: -12,
            }],
        };

        let bytes = author_fac_to_vec(&fac).expect("writes");
        let parsed = read_fac_from_bytes(&bytes).expect("reads back");

        assert_eq!(parsed.reputations[0].standing, -12);
    }

    #[test]
    fn a_non_list_faction_field_reads_as_empty() {
        let mut root = GffStruct::new(-1);
        root.push_field(gff_label!("FactionList"), GffValue::UInt32(7));
        let gff = Gff::new(*b"FAC ", root);

        let fac = Fac::from_gff(&gff).expect("a mistyped list is not a read failure");

        assert!(fac.factions.is_empty());
    }

    #[test]
    fn an_unrelated_file_type_is_rejected() {
        let gff = Gff::new(*b"UTC ", GffStruct::new(-1));

        assert!(matches!(
            Fac::from_gff(&gff),
            Err(FacError::UnsupportedFileType(_))
        ));
    }

    #[test]
    fn an_empty_table_reads_as_empty_rather_than_failing() {
        let gff = Gff::new(*b"FAC ", GffStruct::new(-1));

        let fac = Fac::from_gff(&gff).expect("empty FAC is valid");

        assert!(fac.factions.is_empty());
        assert!(fac.reputations.is_empty());
    }
}