rakata_generics/git/

placeable.rs

//! Placeable placements in a GIT.

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

use super::item::SavedItem;
use super::GitObjectPlacement;
use crate::git::blocks::{LockState, Placement, SavedPortrait, SavedPortraitLabels, SavingThrows};
use crate::shared::ObjectId;
/// The part of a `placeable` entry that is what every placeable 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 GitPlaceableCommon {
    /// 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 `LoadPlaceable` and truncated to a byte, and the absent value
    /// is a literal applied at the read site. Vanilla leaves the label out
    /// when it would be zero.
    #[gff(Appearance, live, stamped, omit = audited_constant(117))]
    pub appearance: u32,
    /// 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>,
}

/// A placeable instance placed in the area (struct type 9).
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_manual_element]
pub struct GitPlaceable {
    /// 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: GitPlaceableCommon,
    /// Template resref (`TemplateResRef`).
    #[gff(TemplateResRef, unexamined)]
    pub template_resref: ResRef,
}

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

// Placeables as stored inside a save game.
//
// A savegame placeable carries the whole object inline rather than referencing
// a `.utp`, container contents included. See
// `docs/src/formats/save/index.md` for the template-versus-snapshot rule.
//
// ## `ItemList` tracks contents, not capacity
//
// The engine writes a placeable's `ItemList` only when the container
// actually holds something. Across the fixture saves no `ItemList` is
// present-but-empty, and plenty of placeables flag `HasInventory` while
// carrying no `ItemList` at all, so presence follows the contents rather
// than the flag. An empty [`Vec`] therefore writes no field, which is what
// keeps an empty footlocker from gaining one it never had.
//
// ## 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 placeable as stored inside a save game's module `GIT`.
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_manual_element]
pub struct SavedPlaceable {
    /// Inventory the placeable holds (`ItemList`).
    ///
    /// Struct id `0` throughout, like a creature's own inventory and unlike a
    /// store's, which really is positional. The id a list of items takes is
    /// decided by the list that owns it rather than by the element type.
    #[gff(
        ItemList,
        not_a_constant,
        list = SavedItem,
        element_extra = GitObjectPlacement,
        element_id = 0,
        omit = empty(50)
    )]
    pub items: Vec<SavedItem>,
    /// 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 = SavedPortraitLabels, 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, stamped)]
    pub trap_detectable: bool,
    /// Whether the trap can be disarmed (`TrapDisarmable`).
    #[gff(TrapDisarmable, stamped)]
    pub trap_disarmable: bool,
    /// Whether the trap fires once and clears (`TrapOneShot`).
    #[gff(TrapOneShot, stamped)]
    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, stamped)]
    pub trap_detect_dc: u8,
    /// Difficulty of disarming it (`DisarmDC`).
    #[gff(DisarmDC, stamped)]
    pub trap_disarm_dc: u8,
    /// Whether a trap is present at all (`TrapFlag`).
    #[gff(TrapFlag, stamped)]
    pub trap_flag: u8,
    // Trap and lock scripts, per owner for the same reason.
    /// Fired when the object closes (`OnClosed`).
    #[gff(OnClosed, stamped)]
    pub on_closed: ResRef,
    /// Fired when it takes damage (`OnDamaged`).
    #[gff(OnDamaged, stamped)]
    pub on_damaged: ResRef,
    /// Fired when it is destroyed (`OnDeath`).
    #[gff(OnDeath, stamped)]
    pub on_death: ResRef,
    /// Fired when its trap is disarmed (`OnDisarm`).
    #[gff(OnDisarm, stamped)]
    pub on_disarm: ResRef,
    /// Fired on the object heartbeat (`OnHeartbeat`).
    #[gff(OnHeartbeat, stamped)]
    pub on_heartbeat: ResRef,
    /// Fired when it is locked (`OnLock`).
    #[gff(OnLock, stamped)]
    pub on_lock: ResRef,
    /// Fired when it is struck in melee (`OnMeleeAttacked`).
    #[gff(OnMeleeAttacked, stamped)]
    pub on_melee_attacked: ResRef,
    /// Fired when it opens (`OnOpen`).
    #[gff(OnOpen, stamped)]
    pub on_open: ResRef,
    /// Fired when a spell targets it (`OnSpellCastAt`).
    #[gff(OnSpellCastAt, stamped)]
    pub on_spell_cast_at: ResRef,
    /// Fired when its trap goes off (`OnTrapTriggered`).
    #[gff(OnTrapTriggered, stamped)]
    pub on_trap_triggered: ResRef,
    /// Fired when it is unlocked (`OnUnlock`).
    #[gff(OnUnlock, stamped)]
    pub on_unlock: ResRef,
    /// Fired on a user-defined event (`OnUserDefined`).
    #[gff(OnUserDefined, stamped)]
    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: GitPlaceableCommon,
    /// Current animation state (`Animation`).
    #[gff(Animation, unexamined)]
    pub animation: i32,
    /// Body-bag row (`BodyBag`).
    #[gff(BodyBag, unexamined)]
    pub body_bag: u8,
    /// 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,
    /// Destroy the object once emptied (`DieWhenEmpty`).
    #[gff(DieWhenEmpty, unexamined)]
    pub die_when_empty: bool,
    /// Faction id (`Faction`).
    #[gff(Faction, unexamined)]
    pub faction: u32,
    /// Renders as a loose pile rather than a container (`GroundPile`).
    #[gff(GroundPile, unexamined)]
    pub ground_pile: bool,
    /// Maximum hit points (`HP`).
    #[gff(HP, unexamined)]
    pub hp: i16,
    /// Damage reduction (`Hardness`).
    #[gff(Hardness, unexamined)]
    pub hardness: u8,
    /// Holds an inventory (`HasInventory`).
    #[gff(HasInventory, unexamined)]
    pub has_inventory: bool,
    /// Is a body bag (`IsBodyBag`).
    #[gff(IsBodyBag, unexamined)]
    pub is_body_bag: bool,
    /// Body bag is visible (`IsBodyBagVisible`).
    #[gff(IsBodyBagVisible, unexamined)]
    pub is_body_bag_visible: bool,
    /// Is a corpse (`IsCorpse`).
    #[gff(IsCorpse, unexamined)]
    pub is_corpse: bool,
    /// Light state (`LightState`).
    #[gff(LightState, unexamined)]
    pub light_state: u8,
    /// Displayed name (`LocName`).
    #[gff(LocName, unexamined)]
    pub loc_name: GffLocalizedString,
    /// Cannot be reduced below 1 HP (`Min1HP`).
    #[gff(Min1HP, unexamined)]
    pub min1_hp: bool,
    /// `OnDialog`.
    #[gff(OnDialog, stamped)]
    pub on_dialog: ResRef,
    /// `OnEndDialogue`.
    #[gff(OnEndDialogue, stamped)]
    pub on_end_dialogue: ResRef,
    /// `OnInvDisturbed`.
    #[gff(OnInvDisturbed, stamped)]
    pub on_inv_disturbed: ResRef,
    /// `OnUsed`.
    #[gff(OnUsed, stamped)]
    pub on_used: ResRef,
    /// Currently open (`Open`).
    #[gff(Open, unexamined)]
    pub open: bool,
    /// Party members may use it directly (`PartyInteract`).
    #[gff(PartyInteract, unexamined)]
    pub party_interact: bool,
    /// Plot flag (`Plot`).
    #[gff(Plot, unexamined)]
    pub plot: bool,
    /// Static, non-interactive geometry (`Static`).
    #[gff(Static, unexamined)]
    pub is_static: bool,
    /// Object tag (`Tag`).
    #[gff(Tag, unexamined)]
    pub tag: String,
    /// Can be interacted with at all (`Useable`).
    #[gff(Useable, unexamined)]
    pub useable: bool,
}

impl SavedPlaceable {
    /// Reads one element, resolving the portrait's two labels into one value.
    pub fn read_element(structure: &GffStruct) -> Self {
        Self {
            common: GitPlaceableCommon::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 GitPlaceable {
    /// Reads one element, with the block the list declares as its element.
    pub fn read_element(structure: &GffStruct) -> Self {
        Self {
            common: GitPlaceableCommon::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::*;

    /// One value written into an element struct carrying the list's own id.
    macro_rules! written {
        ($value:expr, $id:expr) => {{
            let mut element = GffStruct::new($id);
            $value.write_element(&mut element);
            element
        }};
    }

    fn sample() -> SavedPlaceable {
        SavedPlaceable {
            tag: "footlocker01".to_string(),
            common: GitPlaceableCommon {
                appearance: 68,
                object_id: Some(ObjectId::new(0x8000_0077)),
            },
            portrait: SavedPortrait::Id(0),
            placement: Placement {
                x: 4.25,
                bearing: 2.5,
                ..Placement::default()
            },
            current_hp: 15,
            hp: 15,
            useable: true,
            has_inventory: true,
            lock: LockState {
                locked: true,
                open_lock_dc: 20,
                ..LockState::default()
            },
            trap_detectable: true,
            trap_type: 4,
            on_open: ResRef::new("k_plc_open").expect("a legal resref"),
            ..SavedPlaceable::default()
        }
    }

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

        let parsed = SavedPlaceable::read_element(&written!(placeable, 0));

        assert_eq!(parsed, placeable);
    }

    #[test]
    fn an_empty_container_writes_no_item_list() {
        // The engine writes ItemList only when the container holds something,
        // so a flag with no contents must not conjure an empty list.
        let placeable = sample();
        assert!(placeable.has_inventory);
        assert!(placeable.items.is_empty());

        let written = written!(placeable, 0);

        assert!(written.field("ItemList").is_none());
    }

    #[test]
    fn contents_survive_the_round_trip() {
        let placeable = SavedPlaceable {
            items: vec![SavedItem {
                tag: "g_i_credits001".to_string(),
                stack_size: 250,
                ..SavedItem::default()
            }],
            ..sample()
        };

        let parsed = SavedPlaceable::read_element(&written!(placeable, 0));

        assert_eq!(parsed.items, placeable.items);
    }
}