rakata_generics/git/

blocks.rs

//! Field blocks more than one GIT object type declares.
//!
//! Each of these is one declaration reached from several paths, and each was
//! checked axis by axis against every copy before it became one. Where a copy
//! diverged on any axis the block was not made: a saved trigger's trap fields
//! and a saved door's overlap in concept and differ in label set, so they stay
//! apart. The doc on each type records what was compared.

use rakata_core::ResRef;
use rakata_formats::gff::upsert_field;
use rakata_formats::gff_label;
use rakata_formats::schema::GffScalar;
use rakata_formats::{GffModel, GffStruct, GffValue};

use crate::shared::PORTRAIT_ID_USE_RESREF;

/// Where a door or placeable sits in the area and which way it faces.
///
/// The consumer set is the four door and placeable types, blueprint-side
/// placements and saved forms alike. Every one of them reads all four labels
/// with the same zero fallback and writes all four unconditionally, so the
/// block takes no per-consumer parameter.
///
/// Encounter and geometry points carry `X`, `Y` and `Z` identically and are
/// still not consumers. A spawn point faces through `Orientation` rather than
/// `Bearing`, so what counts as three of four shared labels is a position
/// triple beside a differently-named field. Same shape that keeps a saved
/// trigger's trap fields off a saved door's: shared concept, different label
/// set. Sharing the triple alone across all eight is a real extraction and a
/// wider one than this block.
///
/// What blocks it is that none of those paths has an audited absent value.
/// All twenty declarations across the six schema tables are `Unexamined`, so
/// merging would assert a sameness nobody has measured. Six of them, the
/// coordinates under `Ute.Geometry` and `Ute.SpawnPointList`, are populated
/// by no file in either corpus, which is why no further sweep can settle
/// them and reading the pages is the only thing that can.
///
/// That condition covers the four labels this block already shares. Nothing
/// moved when it was introduced, since all four consumers were already
/// reading identical zeros, but an audit giving one path a different absent
/// value now lands here rather than at four separate sites.
#[derive(Debug, Clone, Copy, PartialEq, GffModel)]
pub struct Placement {
    /// X position (`X`).
    #[gff(X, unexamined)]
    pub x: f32,
    /// Y position (`Y`).
    #[gff(Y, unexamined)]
    pub y: f32,
    /// Z position (`Z`).
    #[gff(Z, unexamined)]
    pub z: f32,
    /// Facing angle in radians (`Bearing`).
    #[gff(Bearing, unexamined)]
    pub bearing: f32,
}

/// Saving throws shared by doors and placeables, blueprint and saved alike.
///
/// All three are recorded divergences on the absent axis, and all three are
/// the mechanism-only kind: a door constructs its saving throws and carries
/// them over where a placeable stamps a literal, and both land on zero. What
/// differs is how the default arises, not what it is, so the block needs no
/// per-consumer parameter. See [`LockState`] for the same reading applied to
/// a group where two of the pairs are weaker than that.
#[derive(Debug, Clone, Copy, PartialEq, Eq, GffModel)]
pub struct SavingThrows {
    /// Fortitude save (`Fort`).
    #[gff(Fort, unexamined)]
    pub fortitude: u8,
    /// Reflex save (`Ref`).
    #[gff(Ref, unexamined)]
    pub reflex: u8,
    /// Will save (`Will`).
    #[gff(Will, unexamined)]
    pub will: u8,
}

/// Lock state shared by doors and placeables, blueprint and saved forms alike.
///
/// `SecretDoorDC` is not here. Only the two door types read it, so it stays a
/// loose door field rather than a placeable's eighth label that never applies.
///
/// The block takes no per-consumer defaults, and that is a measured claim
/// rather than an assumption. Five of the seven are recorded divergences on
/// the absent axis: a door constructs its lock group and carries it over
/// where a placeable stamps an unconditional literal. Both sides land on the
/// same value every time, so what differs is how the default arises, not what
/// it is, and a shared read fallback is the value all four consumers were
/// already reading. Contrast the trap fields, which resolve to genuinely
/// different values per consumer and so were never shared. Same test,
/// opposite answer.
///
/// Two labels are weaker than that. `Lockable` and `KeyName` are `Unexamined`
/// on the door side against a populated placeable declaration, so those two
/// pairs are one opinion and one blank rather than a measured agreement. The
/// block does not assert them: it shares the fallback the door reader already
/// used, and an audit giving the door path a different value would land here.
#[derive(Debug, Clone, PartialEq, Eq, GffModel)]
pub struct LockState {
    /// Whether the object is locked (`Locked`).
    #[gff(Locked, unexamined)]
    pub locked: bool,
    /// Whether it can be locked at all (`Lockable`).
    #[gff(Lockable, unexamined)]
    pub lockable: bool,
    /// Whether opening needs a key (`KeyRequired`).
    #[gff(KeyRequired, unexamined)]
    pub key_required: bool,
    /// Tag of the key that opens it (`KeyName`).
    #[gff(KeyName, unexamined)]
    pub key_name: String,
    /// Whether the key is consumed on use (`AutoRemoveKey`).
    #[gff(AutoRemoveKey, unexamined)]
    pub auto_remove_key: bool,
    /// Difficulty of picking it open (`OpenLockDC`).
    #[gff(OpenLockDC, unexamined)]
    pub open_lock_dc: u8,
    /// Difficulty of locking it (`CloseLockDC`).
    #[gff(CloseLockDC, unexamined)]
    pub close_lock_dc: u8,
}

/// The two labels a saved placeable or trigger carries its portrait under.
///
/// Declared apart from [`SavedPortrait`] because the value is one thing and
/// the labels are two: an object carries `Portrait` or `PortraitId`, never
/// both, so no member maps to a label and the codec is the owner's.
///
/// Placeables and triggers share this; a door does not. `Portrait` is stamped
/// on those two and unexamined on the door, which is one measured axis and
/// enough to part them.
#[derive(Debug, Clone, PartialEq, Eq, GffModel)]
#[gff_entry(Portrait, wire = ResRef, stamped)]
#[gff_entry(PortraitId, wire = u16, stamped = PORTRAIT_ID_USE_RESREF)]
pub struct SavedPortraitLabels {}

/// The same two labels on a door, whose `Portrait` the audit records as
/// unexamined rather than stamped.
#[derive(Debug, Clone, PartialEq, Eq, GffModel)]
#[gff_entry(Portrait, wire = ResRef, unexamined)]
#[gff_entry(PortraitId, wire = u16, stamped = PORTRAIT_ID_USE_RESREF)]
pub struct DoorPortraitLabels {}

/// A saved object's portrait, as whichever of the two labels it carries.
///
/// Across every placeable and trigger in the fixture saves the two are
/// exactly complementary: never both on one object, and never neither.
/// Modelling them as one value rather than two [`Option`]s means the state
/// where an object claims both, or claims neither, cannot be built.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SavedPortrait {
    /// `Portrait`: a resref naming the portrait image.
    ResRef(ResRef),
    /// `PortraitId`: a row index into `portraits.2da`.
    Id(u16),
}

impl Default for SavedPortrait {
    /// The `PortraitId` sentinel the engine stamps when the field is absent.
    ///
    /// `0xFFFF` fails the engine's `< 0xFFFE` check, so it goes on to the
    /// `Portrait` resref instead of looking up a row. The sentinel is kept
    /// rather than resolved to the empty resref it eventually reaches: what
    /// the engine's member holds is `0xFFFF`, and which branch that selects
    /// is resolution, which a typed view does not run.
    fn default() -> Self {
        Self::Id(PORTRAIT_ID_USE_RESREF)
    }
}

impl SavedPortrait {
    /// Reads whichever of the two labels the object carries.
    ///
    /// Prefers `Portrait` when both somehow appear, since a resref names an
    /// image outright and a row index still has to be looked up.
    pub(crate) fn read(structure: &GffStruct) -> Self {
        match (
            structure
                .field("Portrait")
                .and_then(<ResRef as GffScalar>::from_gff_value),
            structure
                .field("PortraitId")
                .and_then(<u16 as GffScalar>::from_gff_value),
        ) {
            (Some(resref), _) => Self::ResRef(resref),
            (None, Some(id)) => Self::Id(id),
            (None, None) => Self::default(),
        }
    }

    /// Writes back the one label this portrait uses, and only that one.
    pub(crate) fn write(&self, structure: &mut GffStruct) {
        match self {
            Self::ResRef(resref) => {
                upsert_field(structure, gff_label!("Portrait"), GffValue::ResRef(*resref))
            }
            Self::Id(id) => {
                upsert_field(structure, gff_label!("PortraitId"), GffValue::UInt16(*id))
            }
        }
    }
}

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

    /// The absent-both state, which the reader-defaults guard cannot reach.
    ///
    /// That guard drops one label per probe, so dropping `PortraitId` leaves
    /// `Portrait` in the file and the read takes the resref branch rather
    /// than its own fallback. A fallback that only fires when two labels are
    /// missing together needs a test that omits both.
    #[test]
    fn neither_portrait_field_present_gives_the_engine_sentinel() {
        let portrait = SavedPortrait::read(&GffStruct::new(0));

        assert_eq!(portrait, SavedPortrait::Id(PORTRAIT_ID_USE_RESREF));
    }

    #[test]
    fn an_explicit_portrait_id_is_kept() {
        let mut structure = GffStruct::new(0);
        upsert_field(
            &mut structure,
            gff_label!("PortraitId"),
            GffValue::UInt16(42),
        );
        let portrait = SavedPortrait::read(&structure);

        assert_eq!(portrait, SavedPortrait::Id(42));
    }
}