rakata_generics/git/

item.rs

//! Item placements in a GIT.

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

use super::GitObjectPlacement;

/// An item instance placed in the area (struct type 0).
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_manual_element]
pub struct GitItem {
    /// 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: GitObjectPlacement,
    /// Template resref (`TemplateResRef`), the one label this arm adds.
    #[gff(TemplateResRef, unexamined)]
    pub template_resref: ResRef,
}

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

// Items as stored inside a save game.
//
// A saved creature's `ItemList` and `Equip_ItemList` store the whole item
// inline, properties included, where a `.utc` would store an `InventoryRes` or
// `EquippedRes` resref and let the loader fetch the `.uti`. That is the same
// `UseTemplates = 0` rule the containing `GIT` follows, one level further down;
// see `docs/src/formats/save/index.md`.
//
// ## Saved items live in more than one list
//
// The same struct shape turns up in a creature's `ItemList` and
// `Equip_ItemList`, in a placeable's and a store's `ItemList`, and in the
// area's own loose-item `List`. Which optional fields appear depends on the
// list, not on the item:
//
// - `BodyVariation` and `TextureVar` appear on equipped creature items, and
//   on some placeable and store items. No carried creature item in the
//   fixture saves has them.
// - `Infinite` appears on every store item and on nothing else.
//
// All three are modelled as [`Option`] so an item read out of one list
// writes back into the same shape rather than gaining fields the engine
// would not have put there.
//
// ## What a blueprint has that a snapshot does not
//
// The authoring metadata a `.uti` carries is absent here, which costs nothing
// because the engine bypasses it there too -- see the legacy-artifacts row on
// `docs/src/formats/gff/uti.md`. Going the other way, a snapshot adds
// `ObjectId` and a full position and orientation, because a saved item exists
// somewhere in the world rather than in a template library.

/// One item as stored in a save.
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_manual_element]
pub struct SavedItem {
    /// Blueprint this item came from (`TemplateResRef`).
    ///
    /// On the saved type rather than the templated arm alone, because the
    /// three nested item lists reach this type directly and the baseline
    /// carries the label at all four paths.
    ///
    /// Written only where it holds something: no saved entry in the corpus
    /// carries the label, so emitting a blank would put a field on every one
    /// that never had it.
    #[gff(TemplateResRef, unexamined, manual_write)]
    pub template_resref: ResRef,
    /// Body variation (`BodyVariation`), absent on most entries.
    #[gff(BodyVariation, not_a_constant, optional = u8)]
    pub body_variation: Option<u8>,
    /// Texture variation (`TextureVar`), absent on most entries.
    #[gff(TextureVar, not_a_constant, optional = u8)]
    pub texture_var: Option<u8>,
    /// Whether the stack never depletes (`Infinite`), absent on most entries.
    #[gff(Infinite, not_a_constant, optional = bool)]
    pub infinite: Option<bool>,
    /// Equipment slot, when the list this came out of keys by slot.
    ///
    /// The element's own struct id rather than a label, and no field in the
    /// file repeats it. Only `Equip_ItemList` reads it as data; the five other
    /// lists carrying this type key by a constant or by position, and leave it
    /// zero. Carried here because a writer that cannot reproduce it moves
    /// every equipped item to slot zero.
    pub slot_id: i32,
    /// 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: GitObjectPlacement,
    /// Additional cost (`AddCost`).
    #[gff(AddCost, constructed)]
    pub add_cost: u32,
    /// Base item row (`BaseItem`).
    #[gff(BaseItem, constructed = 30)]
    pub base_item: i32,
    /// Remaining charges (`Charges`).
    #[gff(Charges, stamped = 50)]
    pub charges: u8,
    /// Base cost (`Cost`).
    #[gff(Cost, unexamined)]
    pub cost: u32,
    /// Pending-deletion flag (`DELETING`).
    #[gff(DELETING, constructed)]
    pub deleting: bool,
    /// Identified description (`DescIdentified`).
    #[gff(DescIdentified, constructed)]
    pub description_identified: GffLocalizedString,
    /// Unidentified description (`Description`).
    #[gff(Description, constructed)]
    pub description: GffLocalizedString,
    /// Droppable flag (`Dropable`).
    #[gff(Dropable, stamped)]
    pub droppable: bool,
    /// Identified flag (`Identified`).
    #[gff(Identified, stamped = true)]
    pub identified: bool,
    /// Localized name (`LocalizedName`).
    #[gff(LocalizedName, constructed)]
    pub localized_name: GffLocalizedString,
    /// Maximum charges (`MaxCharges`).
    #[gff(MaxCharges, not_a_constant)]
    pub max_charges: u8,
    /// Model variation (`ModelVariation`).
    #[gff(ModelVariation, not_a_constant)]
    pub model_variation: u8,
    /// Newly-acquired flag (`NewItem`).
    #[gff(NewItem, constructed)]
    pub new_item: bool,
    /// Non-equippable flag (`NonEquippable`).
    #[gff(NonEquippable, constructed)]
    pub non_equippable: bool,
    /// Pickpocketable flag (`Pickpocketable`).
    #[gff(Pickpocketable, stamped)]
    pub pickpocketable: bool,
    /// Plot-item flag (`Plot`).
    #[gff(Plot, constructed)]
    pub plot: bool,
    /// Item properties (`PropertiesList`). The element shape matches a
    /// blueprint's field for field, so this reuses [`UtiProperty`](crate::UtiProperty) and its
    /// conversions rather than re-deriving the same reads.
    /// Element ids are the index here, unlike a blueprint `.uti`'s own
    /// properties list, which writes zero throughout. Which list owns it
    /// decides, not the element type.
    #[gff(PropertiesList, not_a_constant, list = GitItemProperty, element_id = positional)]
    pub properties: Vec<GitItemProperty>,
    /// Stack size (`StackSize`).
    #[gff(StackSize, constructed = 1)]
    pub stack_size: u16,
    /// Stolen flag (`Stolen`).
    #[gff(Stolen, constructed)]
    pub stolen: bool,
    /// Object tag (`Tag`).
    #[gff(Tag, constructed)]
    pub tag: String,
    /// Upgrade bitfield (`Upgrades`).
    #[gff(Upgrades, constructed)]
    pub upgrades: u32,
}

impl GitItem {
    /// Reads one element, with the block the list declares as its element.
    pub fn read_element(structure: &GffStruct) -> Self {
        Self {
            common: GitObjectPlacement::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);
    }
}

impl SavedItem {
    /// Reads one element, with the block the list declares as its element.
    pub fn read_element(structure: &GffStruct) -> Self {
        Self {
            common: GitObjectPlacement::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);
        if !self.template_resref.is_blank() {
            upsert_field(
                structure,
                gff_label!("TemplateResRef"),
                GffValue::ResRef(self.template_resref),
            );
        }
        self.common.write_declared(structure);
    }
}

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

    /// 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() -> SavedItem {
        SavedItem {
            tag: "g_w_blstrpstl001".to_string(),
            common: GitObjectPlacement {
                object_id: Some(crate::shared::ObjectId::new(0x8000_0042)),
                x_position: 12.5,
                ..GitObjectPlacement::default()
            },
            base_item: 4,
            stack_size: 1,
            charges: 3,
            cost: 250,
            identified: true,
            droppable: true,
            properties: vec![GitItemProperty {
                cost_table: 2,
                cost_value: 7,
                property_name: 45,
                subtype: 3,
                chance_appear: 100,
                useable: Some(true),
                uses_per_day: 5,
                ..GitItemProperty::default()
            }],
            ..SavedItem::default()
        }
    }

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

        let parsed = SavedItem::read_element(&written!(item, 0));

        assert_eq!(parsed, item);
    }

    #[test]
    fn an_item_does_not_gain_list_specific_fields() {
        // A carried creature item has none of the three; writing zeros back
        // would add fields the engine never wrote there.
        let item = sample();
        assert_eq!(item.body_variation, None);

        let written = written!(item, 0);

        assert!(written.field("BodyVariation").is_none());
        assert!(written.field("TextureVar").is_none());
        assert!(written.field("Infinite").is_none());
    }

    #[test]
    fn a_store_item_keeps_its_infinite_flag() {
        let item = SavedItem {
            infinite: Some(true),
            ..sample()
        };

        let parsed = SavedItem::read_element(&written!(item, 0));

        assert_eq!(parsed.infinite, Some(true));
    }

    #[test]
    fn an_equipped_item_keeps_its_equip_only_fields() {
        let item = SavedItem {
            body_variation: Some(2),
            texture_var: Some(1),
            ..sample()
        };

        let parsed = SavedItem::read_element(&written!(item, 0));

        assert_eq!(parsed.body_variation, Some(2));
        assert_eq!(parsed.texture_var, Some(1));
    }

    /// `Useable` and `UpgradeType` are `Option`s the model holds the absence
    /// of, so an unset one writes nothing. `UsesPerDay` is not: the omission
    /// that makes `Uti` leave it out was measured across 993 `.uti` files and
    /// does not carry to a GIT path, so this type writes it and the schema
    /// says so.
    #[test]
    fn optional_property_fields_stay_absent_when_unset() {
        let item = SavedItem {
            properties: vec![GitItemProperty::default()],
            ..SavedItem::default()
        };

        let written = written!(item, 0);
        let GffValue::List(entries) = written.field("PropertiesList").expect("written") else {
            panic!("PropertiesList should be a list");
        };

        assert!(entries[0].field("Useable").is_none());
        assert!(entries[0].field("UpgradeType").is_none());
        assert!(entries[0].field("UsesPerDay").is_some());
    }
}

/// One entry of a placed item's `PropertiesList`.
///
/// Not shared with `Uti`'s. The two agreed on every axis until an omission
/// measured across 993 `.uti` files landed on that type; the population is
/// not GIT's, so carrying it here would answer for paths nobody measured.
#[derive(Debug, Clone, PartialEq, Eq, GffModel)]
pub struct GitItemProperty {
    /// Cost table index (`CostTable`).
    #[gff(CostTable, required, undefined)]
    pub cost_table: u8,
    /// Cost table value (`CostValue`).
    #[gff(CostValue, required, undefined)]
    pub cost_value: u16,
    /// Parameter table index (`Param1`).
    #[gff(Param1, required, undefined)]
    pub param1: u8,
    /// Parameter value (`Param1Value`).
    #[gff(Param1Value, required, undefined)]
    pub param1_value: u8,
    /// Property identifier (`PropertyName`).
    #[gff(PropertyName, required, undefined)]
    pub property_name: u16,
    /// Property subtype (`Subtype`).
    #[gff(Subtype, required, undefined)]
    pub subtype: u16,
    /// Chance the property appears (`ChanceAppear`).
    #[gff(ChanceAppear, required, undefined = 100)]
    pub chance_appear: u8,
    /// Usable flag (`Useable`), when the entry carries one.
    #[gff(Useable, not_a_constant, optional = bool)]
    pub useable: Option<bool>,
    /// Uses per day (`UsesPerDay`).
    ///
    /// No vanilla `.uti` carries this label on any property entry, across all
    /// 993 of them, so the omission stands in for the absence and the model
    /// does not have to.
    #[gff(UsesPerDay, stamped)]
    pub uses_per_day: u8,
    /// Upgrade type (`UpgradeType`), when the entry carries one.
    ///
    /// Held optionally because absence and an explicit `0` are both real: of
    /// 2040 property entries in the install, 1118 omit the label, 890 carry a
    /// value and 32 carry a zero. An omission keyed on the engine's own
    /// absent-value would drop those 32.
    ///
    /// The entry says the engine stamps `0` and our reader hands back `None`,
    /// which the vocabulary cannot express in one place: `Absent::Resolves`
    /// has no substitute slot, because it was shaped for the case where our
    /// value is the engine's. Recorded here until that is settled.
    #[gff(UpgradeType, stamped, optional = u8)]
    pub upgrade_type: Option<u8>,
}