rakata_generics/git/

door.rs

//! Door placements in a GIT.

use rakata_core::ResRef;
use rakata_formats::{GffLocalizedString, GffModel, GffStruct};

use crate::git::blocks::{DoorPortraitLabels, LockState, Placement, SavedPortrait, SavingThrows};
use crate::shared::ObjectId;
/// A door instance placed in the area (struct type 8).
///
/// Doors use `Bearing` for orientation and `X`/`Y`/`Z` for position (not
/// `XPosition`/`YPosition`/`ZPosition`).
///
/// Unlike [`GitWaypoint`](super::GitWaypoint), a static door placement genuinely does resolve its
/// `TemplateResRef` against a `.utd` blueprint, and it carries the same
/// transition group a trigger does. This type modelled neither for a while,
/// which meant round-tripping any vanilla module returned doors with no
/// blueprint to instantiate from and no tag to reference. See
/// `docs/src/formats/gff/utd.md`'s "Save versus Template Load Paths".
///
/// ## `Tag` is dead here, and deliberately unmodelled
///
/// A templated door takes its tag from the `.utd` blueprint and the
/// placement's copy has no overlay to win through, so setting one is a modder
/// trap rather than a harmless leftover: nothing happens, silently.
///
/// `docs/src/architecture.md` uses exactly this field as its worked example of
/// the projection rule's "at that path is the whole test", and
/// `docs/src/formats/gff/git.md` covers the consequence, that two placements
/// sharing a blueprint end up with the same tag -- for every templated object
/// The part of a `door` entry that is what every door entry carries, whichever form it takes.
///
/// Both arms flatten it and the list's element is it, so the labels here
/// are one declaration reached from both forms rather than two copies.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct GitDoorCommon {
    /// Visual model override (`Appearance`).
    ///
    /// Read on a sparse placement as well as a saved one: `LoadDoor` and
    /// `LoadPlaceable` are the same field readers whichever path calls them,
    /// so a template-referencing placement carrying its own `Appearance` has
    /// that value read as an override on top of the blueprint's. Read as a
    /// DWORD and truncated to a byte, which for a door keys `doortypes.2da`'s
    /// model columns. Defaults to `0` when absent.
    /// Read by `LoadDoor` and truncated to a byte, then used to key
    /// `doortypes.2da`. The absent value is the door struct's own
    /// zero-initialized member rather than a literal, which is where this
    /// parts from the placeable's otherwise identical field.
    #[gff(Appearance, live, constructed, omit = audited_constant(117))]
    pub appearance: u32,
    /// Destination object tag within that module (`LinkedTo`).
    #[gff(LinkedTo, not_a_constant)]
    pub linked_to: String,
    /// What [`Self::linked_to`] names (`LinkedToFlags`).
    #[gff(LinkedToFlags, not_a_constant)]
    pub linked_to_flags: u8,
    /// Destination module for a transition door (`LinkedToModule`).
    #[gff(LinkedToModule, not_a_constant)]
    pub linked_to_module: ResRef,
    /// Runtime object ID (`ObjectId`). Save-game only.
    /// Runtime object id (`ObjectId`), which only a saved form carries.
    ///
    /// The area-level dispatcher reads it once per element ahead of the
    /// static-versus-saved branch, so the engine reads it on both forms and
    /// the liveness below is right. What it does not do is author it: every
    /// element the engine saves carries one and no element the toolset shipped
    /// does. Held as the absence so writing a static placement back does not
    /// invent a runtime id for it.
    #[gff(ObjectId, stamped = ObjectId::INVALID, optional = ObjectId)]
    pub object_id: Option<ObjectId>,
    /// Player-facing name of the destination (`TransitionDestin`).
    #[gff(TransitionDestin, constructed)]
    pub transition_destination: GffLocalizedString,
}

/// type, not only doors. Filed as #46.
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_manual_element]
pub struct GitDoor {
    /// Placement, whose four labels sit at this object's own level.
    #[gff(flatten = Placement)]
    pub placement: Placement,
    /// The block both forms carry, which the list declares as its element.
    ///
    /// No `#[gff]`: the arm contributes its parts to the split, and the
    /// element is this block, so declaring it here too would make one label
    /// two declarations. The arm's own codec reads and writes it.
    pub common: GitDoorCommon,
    /// Template resref (`TemplateResRef`), resolved against a `.utd`.
    #[gff(TemplateResRef, unexamined)]
    pub template_resref: ResRef,
}

// =========================================================================
// The saved form
// =========================================================================

// Doors as stored inside a save game.
//
// A savegame door carries the whole object inline rather than pointing at a
// `.utd`, so the fields here are the ones a blueprint would have supplied plus
// the runtime state it has no place for. See
// `docs/src/formats/save/index.md` for the template-versus-snapshot rule, and
// its object position table for why doors spell position `X`/`Y`/`Z` with a
// `Bearing` where creatures and triggers use `XPosition` and a three-component
// orientation. That page lists all four naming styles; each saved type carries
// its own rather than sharing a position block that would need telling which
// dialect to write.
//
// ## What is not modelled
//
// `ActionList`, `EffectList`, `VarTable` and `SWVarTable` are live runtime
// state whose layouts are only partly audited, and they are skipped for the
// same reason [`SavedCreature`](crate::git::creature::SavedCreature) skips
// them: a typed view models what it enumerates and drops the rest, and
// byte-exact preservation stays with the raw
// [`Gff`](rakata_formats::Gff) tree.

/// A door as stored inside a save game's module `GIT`.
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_manual_element]
pub struct SavedDoor {
    /// Placement, whose four labels sit at this object's own level.
    #[gff(flatten = Placement)]
    pub placement: Placement,
    /// Saving throws, likewise flat on the object.
    #[gff(flatten = SavingThrows)]
    pub saves: SavingThrows,
    /// Lock state, likewise flat on the object.
    #[gff(flatten = LockState)]
    pub lock: LockState,
    /// Portrait, as whichever of the two labels the object carries.
    ///
    /// Declared per owner rather than shared: the audit parts `Portrait` and
    /// `PortraitId` across doors, placeables and triggers on the absent axis.
    /// Both halves are this type's, because one member stands for two labels
    /// and which one is written depends on the variant.
    #[gff(flatten = DoorPortraitLabels, manual_read, manual_write)]
    pub portrait: SavedPortrait,

    // Trap settings, per owner: every label parts from the other
    // owners on the absent axis, so no block spans them.
    /// Whether the trap can be spotted (`TrapDetectable`).
    #[gff(TrapDetectable, constructed = true)]
    pub trap_detectable: bool,
    /// Whether the trap can be disarmed (`TrapDisarmable`).
    #[gff(TrapDisarmable, constructed = true)]
    pub trap_disarmable: bool,
    /// Whether the trap fires once and clears (`TrapOneShot`).
    #[gff(TrapOneShot, constructed = true)]
    pub trap_one_shot: bool,
    /// Trap row in `traps.2da` (`TrapType`).
    #[gff(TrapType, constructed = 255)]
    pub trap_type: u8,
    /// Difficulty of spotting the trap (`TrapDetectDC`).
    #[gff(TrapDetectDC, constructed)]
    pub trap_detect_dc: u8,
    /// Difficulty of disarming it (`DisarmDC`).
    #[gff(DisarmDC, constructed)]
    pub trap_disarm_dc: u8,
    /// Whether a trap is present at all (`TrapFlag`).
    #[gff(TrapFlag, constructed)]
    pub trap_flag: u8,
    // Trap and lock scripts, per owner for the same reason.
    /// Fired when the object closes (`OnClosed`).
    #[gff(OnClosed, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_closed: ResRef,
    /// Fired when it takes damage (`OnDamaged`).
    #[gff(OnDamaged, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_damaged: ResRef,
    /// Fired when it is destroyed (`OnDeath`).
    #[gff(OnDeath, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_death: ResRef,
    /// Fired when its trap is disarmed (`OnDisarm`).
    #[gff(OnDisarm, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_disarm: ResRef,
    /// Fired on the object heartbeat (`OnHeartbeat`).
    #[gff(OnHeartbeat, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_heartbeat: ResRef,
    /// Fired when it is locked (`OnLock`).
    #[gff(OnLock, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_lock: ResRef,
    /// Fired when it is struck in melee (`OnMeleeAttacked`).
    #[gff(OnMeleeAttacked, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_melee_attacked: ResRef,
    /// Fired when it opens (`OnOpen`).
    #[gff(OnOpen, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_open: ResRef,
    /// Fired when a spell targets it (`OnSpellCastAt`).
    #[gff(OnSpellCastAt, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_spell_cast_at: ResRef,
    /// Fired when its trap goes off (`OnTrapTriggered`).
    #[gff(OnTrapTriggered, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_trap_triggered: ResRef,
    /// Fired when it is unlocked (`OnUnlock`).
    #[gff(OnUnlock, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_unlock: ResRef,
    /// Fired on a user-defined event (`OnUserDefined`).
    #[gff(OnUserDefined, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_user_defined: ResRef,
    /// The block both forms carry, which the list declares as its element.
    ///
    /// No `#[gff]`: the arm contributes its parts to the split, and the
    /// element is this block, so declaring it here too would make one label
    /// two declarations. The arm's own codec reads and writes it.
    pub common: GitDoorCommon,
    /// Object tag (`Tag`).
    #[gff(
        Tag,
        read_only_dead = "a templated placement takes its tag from the blueprint, which the placement cannot override",
        unexamined
    )]
    pub tag: String,
    /// Accepts scripted commands (`Commandable`).
    #[gff(Commandable, unexamined)]
    pub commandable: bool,
    /// Attached conversation (`Conversation`).
    #[gff(Conversation, unexamined)]
    pub conversation: ResRef,
    /// Current hit points (`CurrentHP`).
    #[gff(CurrentHP, unexamined)]
    pub current_hp: i16,
    /// Description (`Description`).
    #[gff(Description, unexamined)]
    pub description: GffLocalizedString,
    /// Faction id (`Faction`).
    #[gff(Faction, unexamined)]
    pub faction: u32,
    /// Generic door type (`GenericType`).
    #[gff(GenericType, unexamined)]
    pub generic_type: u8,
    /// Maximum hit points (`HP`).
    #[gff(HP, unexamined)]
    pub hp: i16,
    /// Damage reduction (`Hardness`).
    #[gff(Hardness, unexamined)]
    pub hardness: u8,
    /// Load screen shown across the transition (`LoadScreenID`).
    #[gff(LoadScreenID, unexamined)]
    pub load_screen_id: u16,
    /// Displayed name (`LocName`).
    #[gff(LocName, unexamined)]
    pub loc_name: GffLocalizedString,
    /// Cannot be reduced below 1 HP (`Min1HP`).
    #[gff(Min1HP, unexamined)]
    pub min1_hp: bool,
    /// `OnClick`.
    #[gff(OnClick, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_click: ResRef,
    /// `OnDialog`.
    #[gff(OnDialog, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_dialog: ResRef,
    /// `OnFailToOpen`.
    #[gff(OnFailToOpen, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_fail_to_open: ResRef,
    /// Open / closed / destroyed state (`OpenState`).
    #[gff(OpenState, unexamined)]
    pub open_state: u8,
    /// Plot flag (`Plot`).
    #[gff(Plot, unexamined)]
    pub plot: bool,
    /// DC to spot a secret door (`SecretDoorDC`). Doors only.
    #[gff(SecretDoorDC, unexamined)]
    pub secret_door_dc: u8,
    /// Static, non-interactive geometry (`Static`).
    #[gff(Static, unexamined)]
    pub is_static: bool,
}

impl SavedDoor {
    /// Reads one element, resolving the portrait's two labels into one value.
    pub fn read_element(structure: &GffStruct) -> Self {
        Self {
            common: GitDoorCommon::read_declared(structure),
            portrait: SavedPortrait::read(structure),
            ..Self::read_declared(structure)
        }
    }

    /// Writes one element, emitting whichever portrait label the value uses.
    pub fn write_element(&self, structure: &mut GffStruct) {
        self.write_declared(structure);
        self.common.write_declared(structure);
        self.portrait.write(structure);
    }
}

impl GitDoor {
    /// Reads one element, with the block the list declares as its element.
    pub fn read_element(structure: &GffStruct) -> Self {
        Self {
            common: GitDoorCommon::read_declared(structure),
            ..Self::read_declared(structure)
        }
    }

    /// Writes one element, the common block included.
    pub fn write_element(&self, structure: &mut GffStruct) {
        self.write_declared(structure);
        self.common.write_declared(structure);
    }
}

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

    /// One door written into an element struct of its own.
    fn written(door: &SavedDoor) -> GffStruct {
        let mut element = GffStruct::new(8);
        door.write_element(&mut element);
        element
    }

    fn sample() -> SavedDoor {
        SavedDoor {
            tag: "sec_door_01".to_string(),
            common: GitDoorCommon {
                object_id: Some(ObjectId::new(0x8000_0031)),
                appearance: 12,
                ..GitDoorCommon::default()
            },
            generic_type: 3,
            portrait: SavedPortrait::Id(42),
            placement: Placement {
                x: 12.5,
                y: -3.0,
                bearing: 1.57,
                ..Placement::default()
            },
            current_hp: 40,
            hp: 60,
            lock: LockState {
                locked: true,
                open_lock_dc: 25,
                key_name: "sec_key".to_string(),
                ..LockState::default()
            },
            trap_detectable: true,
            trap_type: 4,
            trap_detect_dc: 15,
            load_screen_id: 7,
            on_open: ResRef::new("k_door_open").expect("valid resref"),
            ..SavedDoor::default()
        }
    }

    #[test]
    fn round_trips_through_a_list_element() {
        let door = sample();

        let parsed = SavedDoor::read_element(&written(&door));

        assert_eq!(parsed, door);
    }

    #[test]
    fn a_portrait_id_does_not_gain_a_portrait_resref() {
        // The two fields are complementary in every save; writing both back
        // would put a field on the object the engine never wrote there.
        let written = written(&sample());

        assert!(written.field("PortraitId").is_some());
        assert!(written.field("Portrait").is_none());
    }

    #[test]
    fn a_portrait_resref_survives_the_round_trip() {
        let door = SavedDoor {
            portrait: SavedPortrait::ResRef(ResRef::new("po_pdoor").expect("valid resref")),
            ..sample()
        };

        let written = written(&door);
        assert!(written.field("PortraitId").is_none());
        assert_eq!(SavedDoor::read_element(&written).portrait, door.portrait);
    }

    #[test]
    fn an_absent_portrait_reads_as_the_engine_default() {
        // Both fields absent, which is the one state the absent-defaults
        // guard cannot reach: it drops a single label per probe, so dropping
        // `PortraitId` leaves `Portrait` behind and the reader takes the
        // resref branch instead of its fallback.
        let parsed = SavedDoor::read_element(&GffStruct::new(0));

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