rakata_generics/git/

creature.rs

//! Creature placements in a GIT.

use rakata_core::ResRef;
use rakata_formats::{
    gff_schema::{AbsentDefault, FieldLife, FieldSchema, GffType},
    GffLocalizedString, GffStruct, GffValue,
};

use super::item::SavedItem;
use super::object_id_or_invalid;
use crate::gff_helpers::{
    get_f32, get_i16, get_i32, get_i8, get_locstring, get_resref, get_string, get_u16, get_u32,
    get_u8, upsert_field,
};
use crate::shared::ObjectId;
use crate::utc::UtcSkills;

/// A creature instance placed in the area (struct type 4).
#[derive(Debug, Clone, PartialEq, Default)]
pub struct GitCreature {
    /// Template resref (`TemplateResRef`).
    pub template_resref: ResRef,
    /// X position (`XPosition`).
    pub x_position: f32,
    /// Y position (`YPosition`).
    pub y_position: f32,
    /// Z position (`ZPosition`).
    pub z_position: f32,
    /// X orientation (`XOrientation`).
    pub x_orientation: f32,
    /// Y orientation (`YOrientation`).
    pub y_orientation: f32,
    /// Z orientation (`ZOrientation`).
    pub z_orientation: f32,
}

// `ObjectId` is modelled on `SavedCreature` below and deliberately not here,
// which reads as an oversight now that the two forms share a file.
//
// The static creature path never reads the label. The constructor takes the
// placeholder as a bare literal with no lookup against `ObjectId` anywhere in
// that branch, which is the same never-looked-up status as `.utc`'s `Tail`
// and `Wings` rather than a read with a default behind it.
//
// This is creature-specific. Every other object type reads the label once
// before the static-versus-saved branch, so their static forms are genuinely
// read-with-default and keep the field.
//
// The label stays declared in the schema, so a static creature carrying one
// is legitimate content rather than an unrecognized field. Saying it is dead
// *here* and live on the saved form is not something `FieldLife` can express,
// since it is one path with two lives, and that gap is recorded with the
// wider schema question rather than worked around.
impl GitCreature {
    pub(crate) fn from_gff_struct(s: &GffStruct) -> Self {
        Self {
            template_resref: get_resref(s, "TemplateResRef").unwrap_or_default(),
            x_position: get_f32(s, "XPosition").unwrap_or(0.0),
            y_position: get_f32(s, "YPosition").unwrap_or(0.0),
            z_position: get_f32(s, "ZPosition").unwrap_or(0.0),
            x_orientation: get_f32(s, "XOrientation").unwrap_or(0.0),
            y_orientation: get_f32(s, "YOrientation").unwrap_or(0.0),
            z_orientation: get_f32(s, "ZOrientation").unwrap_or(0.0),
        }
    }

    pub(crate) fn to_gff_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(4);
        upsert_field(
            &mut s,
            "TemplateResRef",
            GffValue::ResRef(self.template_resref),
        );
        upsert_field(&mut s, "XPosition", GffValue::Single(self.x_position));
        upsert_field(&mut s, "YPosition", GffValue::Single(self.y_position));
        upsert_field(&mut s, "ZPosition", GffValue::Single(self.z_position));
        upsert_field(&mut s, "XOrientation", GffValue::Single(self.x_orientation));
        upsert_field(&mut s, "YOrientation", GffValue::Single(self.y_orientation));
        upsert_field(&mut s, "ZOrientation", GffValue::Single(self.z_orientation));
        s
    }
}

/// GIT `Creature List` entry child schema (struct type 4).
pub(crate) static CREATURE_LIST_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "ObjectId",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "TemplateResRef",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "XPosition",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "YPosition",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "ZPosition",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "XOrientation",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "YOrientation",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "ZOrientation",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

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

// Saved creature snapshots from a save game's module `GIT`.
//
// A module `GIT` inside a save sets `UseTemplates = 0`, which makes each
// creature element a full self-contained snapshot rather than a placement
// that points at a `.utc` blueprint. There is no `TemplateResRef` to follow
// and no blueprint load: every field the engine needs is on the element, and
// a field that is missing falls back to the engine's hardcoded default rather
// than to a template value.
//
// ## Why this is not built on [`Utc`](crate::utc::Utc)
//
// The two serializations overlap heavily but neither contains the other, and
// the fields they do not share are not a tidy category. A handful are genuine
// authoring metadata that a runtime snapshot has no use for
// (`TemplateResRef`, `PaletteID`, `Comment`). The rest are ordinary character
// data that the save writer either drops or stores differently: a blueprint
// carries both `Portrait` and `PortraitId` while a snapshot carries only
// `PortraitId`; a blueprint's `SaveWill` / `SaveFortitude` are the documented
// dead fields while a snapshot carries computed `WillSaveThrow` /
// `FortSaveThrow` totals plus round-tripping `willbonus` / `fortbonus`
// inputs; `WalkRate` becomes `MovementRate`.
//
// Sharing a "creature core" between the two would therefore draw a line
// through the middle of character data based on which representation the save
// writer happened to pick, which describes no real concept. So the overlapping
// fields are spelled out here as well as in [`Utc`](crate::utc::Utc). The cost
// is duplication; the benefit is that each type writes exactly the field set
// it enumerates, with no hand-maintained list of exceptions.
//
// If you go looking to quantify that overlap, note that "a root-level field of
// [`Utc`](crate::utc::Utc)" is not a well-defined set. Its list helpers handle
// both the list's own label and the labels of the elements inside it, so
// whether `Spell`, `Feat` or `Rank` counts as root or nested depends entirely
// on how you slice the source. Counts derived that way do not reconcile and
// are not worth deriving. The field *names* on either side are exact; the
// arithmetic over them is not, and nothing here depends on it.
//
// ## What is not modelled yet
//
// Progression and inventory are covered: `ClassList`, `FeatList`,
// `SkillList`, `ItemList` and `Equip_ItemList` all read and write.
//
// `ActionList`, `EffectList`, `ExpressionList`, `PerceptionList`, `VarTable`
// and the `CombatInfo` / `CombatRoundData` / `SWVarTable` structs are live
// runtime state whose layouts are only partly audited.
//
// Neither group is read or written here. That follows the projection rule: 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 creature as stored inside a save game's module `GIT`.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct SavedCreature {
    // --- Identity ---
    /// Object tag (`Tag`).
    pub tag: String,
    /// Localized first name (`FirstName`).
    pub first_name: GffLocalizedString,
    /// Localized last name (`LastName`).
    pub last_name: GffLocalizedString,
    /// Localized description (`Description`).
    pub description: GffLocalizedString,
    /// Runtime object id (`ObjectId`).
    pub object_id: ObjectId,
    /// Runtime area id the creature belongs to (`AreaId`).
    pub area_id: u32,
    /// Dialogue this creature opens (`Conversation`). Not a script hook.
    pub conversation: ResRef,

    // --- Placement ---
    /// World X position (`XPosition`).
    pub x_position: f32,
    /// World Y position (`YPosition`).
    pub y_position: f32,
    /// World Z position (`ZPosition`).
    pub z_position: f32,
    /// Facing X component (`XOrientation`).
    pub x_orientation: f32,
    /// Facing Y component (`YOrientation`).
    pub y_orientation: f32,
    /// Facing Z component (`ZOrientation`).
    pub z_orientation: f32,

    // --- Appearance ---
    /// Appearance row (`Appearance_Type`).
    pub appearance_type: u16,
    /// Head appearance (`Appearance_Head`).
    pub appearance_head: u8,
    /// Portrait row (`PortraitId`). A snapshot carries only the id; a
    /// blueprint additionally carries a `Portrait` resref.
    pub portrait_id: u16,
    /// Body-model phenotype (`Phenotype`).
    pub phenotype: i32,
    /// Skin colour index (`Color_Skin`).
    pub color_skin: u8,
    /// Hair colour index (`Color_Hair`).
    pub color_hair: u8,
    /// First tattoo colour index (`Color_Tattoo1`).
    pub color_tattoo1: u8,
    /// Second tattoo colour index (`Color_Tattoo2`).
    pub color_tattoo2: u8,
    /// Head-duplication flag (`DuplicatingHead`).
    pub duplicating_head: u8,
    /// Backup-head flag (`UseBackupHead`).
    pub use_backup_head: u8,
    /// Party-member disguise flag (`PM_IsDisguised`).
    pub is_disguised: u8,
    /// Corpse body-bag appearance (`BodyBag`).
    pub body_bag: u8,

    // --- Abilities ---
    /// Strength (`Str`).
    pub strength: u8,
    /// Dexterity (`Dex`).
    pub dexterity: u8,
    /// Constitution (`Con`).
    pub constitution: u8,
    /// Intelligence (`Int`).
    pub intelligence: u8,
    /// Wisdom (`Wis`).
    pub wisdom: u8,
    /// Charisma (`Cha`).
    pub charisma: u8,

    // --- Vitals ---
    /// Live hit points (`CurrentHitPoints`).
    pub current_hit_points: i16,
    /// Base hit points carried from the template (`HitPoints`).
    pub hit_points: i16,
    /// Computed maximum hit points (`MaxHitPoints`). Rebuilt on load from
    /// class levels and the Constitution modifier, so an edit here does
    /// nothing.
    pub max_hit_points: i16,
    /// Current-HP mirror (`PregameCurrent`). Written on every save and read
    /// by nothing.
    pub pregame_current: i16,
    /// Live Force points (`ForcePoints`).
    pub force_points: i16,
    /// Current Force pool (`CurrentForce`).
    pub current_force: i16,
    /// Computed maximum Force points (`MaxForcePoints`).
    pub max_force_points: i16,

    // --- Computed combat totals ---
    /// Computed armour class (`ArmorClass`). Rebuilt on load from armour
    /// tables, natural AC, the Dexterity modifier, feats and active effects.
    pub armor_class: i16,
    /// Computed Reflex save total (`RefSaveThrow`). Rebuilt on load.
    pub ref_save_throw: i8,
    /// Computed Will save total (`WillSaveThrow`). Rebuilt on load.
    pub will_save_throw: i8,
    /// Computed Fortitude save total (`FortSaveThrow`). Rebuilt on load.
    pub fort_save_throw: i8,
    /// Permanent Reflex bonus (`refbonus`). Unlike the total above, this is
    /// an input the engine reads back.
    pub ref_bonus: i16,
    /// Permanent Will bonus (`willbonus`). Read back on load.
    pub will_bonus: i16,
    /// Permanent Fortitude bonus (`fortbonus`). Read back on load.
    pub fort_bonus: i16,
    /// Natural armour class (`NaturalAC`).
    pub natural_ac: u8,

    // --- Progression ---
    /// Accumulated experience (`Experience`).
    pub experience: u32,
    /// Carried gold (`Gold`). Skipped on load for creatures currently in the
    /// party, whose wealth lives in the shared party pool instead.
    pub gold: u32,
    /// Unspent skill points (`SkillPoints`).
    pub skill_points: u16,
    /// Multiclass level-up bookkeeping (`MClassLevUpIn`). Written on every
    /// save and read by nothing.
    pub multiclass_level_up_in: u8,
    /// Joining experience (`JoiningXP`). Read only by the fresh-spawn path,
    /// so it resets to zero when a save is continued.
    pub joining_xp: i32,
    /// Starting package row (`StartingPackage`).
    pub starting_package: u8,
    /// Challenge rating (`ChallengeRating`).
    pub challenge_rating: f32,
    /// Age (`Age`).
    pub age: i32,

    // --- Identity tables ---
    /// Race row (`Race`).
    pub race: u8,
    /// Subrace name (`Subrace`).
    pub subrace: String,
    /// Subrace row (`SubraceIndex`).
    pub subrace_index: u8,
    /// Deity name (`Deity`).
    pub deity: String,
    /// Gender row (`Gender`).
    pub gender: u8,
    /// Alignment on the light/dark axis (`GoodEvil`). The engine clamps this
    /// to a maximum of 100.
    pub good_evil: u8,
    /// Faction id indexing the session faction table (`FactionID`).
    pub faction_id: u16,
    /// Sound-set row (`SoundSetFile`).
    pub sound_set_file: u16,

    // --- Runtime behaviour ---
    /// AI state (`AIState`).
    pub ai_state: i32,
    /// Orientation-lock flag (`NotReorienting`).
    pub not_reorienting: u8,
    /// Detect mode (`DetectMode`). The loader reads the byte only to step
    /// past it and resets every restored creature to mode 1.
    pub detect_mode: u8,
    /// Stealth mode (`StealthMode`).
    pub stealth_mode: u8,
    /// Player-commandable flag (`Commandable`).
    pub commandable: u8,
    /// Listening flag (`Listening`).
    pub listening: u8,
    /// Party-interaction flag (`PartyInteract`).
    pub party_interact: u8,
    /// Plot-protection flag (`Plot`).
    pub plot: u8,
    /// Minimum-one-hit-point flag (`Min1HP`).
    pub min1_hp: u8,
    /// Interruptable flag (`Interruptable`).
    pub interruptable: u8,
    /// Disarmable flag (`Disarmable`).
    pub disarmable: u8,
    /// Destroyable flag (`IsDestroyable`).
    pub is_destroyable: u8,
    /// Raiseable flag (`IsRaiseable`).
    pub is_raiseable: u8,
    /// Corpse-selectable flag (`DeadSelectable`).
    pub dead_selectable: u8,
    /// Player-character flag (`IsPC`).
    pub is_pc: u8,
    /// Spawn-script-fired flag (`CreatnScrptFird`).
    pub creation_script_fired: u8,
    /// Ambient animation state (`AmbientAnimState`).
    pub ambient_anim_state: u8,
    /// Current animation (`Animation`).
    pub animation: i32,
    /// Creature size row (`CreatureSize`).
    pub creature_size: i32,
    /// Movement rate row (`MovementRate`). A blueprint spells this `WalkRate`.
    pub movement_rate: u8,

    // --- Progression lists ---
    /// Class levels and known powers (`ClassList`).
    pub classes: Vec<SavedClass>,
    /// Feat ids (`FeatList`).
    pub feats: Vec<u16>,
    /// Skill ranks (`SkillList`), positional as the engine stores them.
    pub skills: UtcSkills,
    /// Carried inventory (`ItemList`).
    pub inventory: Vec<SavedItem>,
    /// Equipped items (`Equip_ItemList`).
    pub equipment: Vec<SavedItem>,

    // --- Legacy ---
    /// Tail appearance (`Tail`). Hardcoded to zero on read; written anyway.
    pub tail: u8,
    /// Wing appearance (`Wings`). Hardcoded to zero on read; written anyway.
    pub wings: u8,

    // --- Scripts ---
    /// On-attacked script (`ScriptAttacked`).
    pub on_attacked: ResRef,
    /// On-damaged script (`ScriptDamaged`).
    pub on_damaged: ResRef,
    /// On-death script (`ScriptDeath`).
    pub on_death: ResRef,
    /// On-dialogue script (`ScriptDialogue`).
    pub on_dialog: ResRef,
    /// On-disturbed script (`ScriptDisturbed`).
    pub on_disturbed: ResRef,
    /// On-end-dialog script (`ScriptEndDialogu`).
    pub on_end_dialog: ResRef,
    /// On-end-round script (`ScriptEndRound`).
    pub on_end_round: ResRef,
    /// On-heartbeat script (`ScriptHeartbeat`).
    pub on_heartbeat: ResRef,
    /// On-blocked script (`ScriptOnBlocked`).
    pub on_blocked: ResRef,
    /// On-notice script (`ScriptOnNotice`).
    pub on_notice: ResRef,
    /// On-rested script (`ScriptRested`).
    pub on_rested: ResRef,
    /// On-spawn script (`ScriptSpawn`).
    pub on_spawn: ResRef,
    /// On-spell-at script (`ScriptSpellAt`).
    pub on_spell: ResRef,
    /// On-user-defined script (`ScriptUserDefine`).
    pub on_user_defined: ResRef,
}

impl SavedCreature {
    /// Creates an empty snapshot.
    pub fn new() -> Self {
        Self::default()
    }

    /// Reads a snapshot from one `Creature List` element.
    ///
    /// Every field is optional: a `UseTemplates = 0` element that omits one
    /// resolves to the engine's hardcoded default, which is what the
    /// per-field fallbacks here reproduce.
    pub fn from_struct(structure: &GffStruct) -> Self {
        Self {
            tag: get_string(structure, "Tag").unwrap_or_default(),
            first_name: get_locstring(structure, "FirstName")
                .cloned()
                .unwrap_or_default(),
            last_name: get_locstring(structure, "LastName")
                .cloned()
                .unwrap_or_default(),
            description: get_locstring(structure, "Description")
                .cloned()
                .unwrap_or_default(),
            object_id: object_id_or_invalid(structure),
            area_id: get_u32(structure, "AreaId").unwrap_or(0),
            conversation: get_resref(structure, "Conversation").unwrap_or_default(),

            x_position: get_f32(structure, "XPosition").unwrap_or(0.0),
            y_position: get_f32(structure, "YPosition").unwrap_or(0.0),
            z_position: get_f32(structure, "ZPosition").unwrap_or(0.0),
            x_orientation: get_f32(structure, "XOrientation").unwrap_or(0.0),
            y_orientation: get_f32(structure, "YOrientation").unwrap_or(0.0),
            z_orientation: get_f32(structure, "ZOrientation").unwrap_or(0.0),

            appearance_type: get_u16(structure, "Appearance_Type").unwrap_or(0),
            appearance_head: get_u8(structure, "Appearance_Head").unwrap_or(0),
            portrait_id: get_u16(structure, "PortraitId").unwrap_or(0),
            phenotype: get_i32(structure, "Phenotype").unwrap_or(0),
            color_skin: get_u8(structure, "Color_Skin").unwrap_or(0),
            color_hair: get_u8(structure, "Color_Hair").unwrap_or(0),
            color_tattoo1: get_u8(structure, "Color_Tattoo1").unwrap_or(0),
            color_tattoo2: get_u8(structure, "Color_Tattoo2").unwrap_or(0),
            duplicating_head: get_u8(structure, "DuplicatingHead").unwrap_or(0),
            use_backup_head: get_u8(structure, "UseBackupHead").unwrap_or(0),
            is_disguised: get_u8(structure, "PM_IsDisguised").unwrap_or(0),
            body_bag: get_u8(structure, "BodyBag").unwrap_or(0),

            strength: get_u8(structure, "Str").unwrap_or(0),
            dexterity: get_u8(structure, "Dex").unwrap_or(0),
            constitution: get_u8(structure, "Con").unwrap_or(0),
            intelligence: get_u8(structure, "Int").unwrap_or(0),
            wisdom: get_u8(structure, "Wis").unwrap_or(0),
            charisma: get_u8(structure, "Cha").unwrap_or(0),

            current_hit_points: get_i16(structure, "CurrentHitPoints").unwrap_or(0),
            hit_points: get_i16(structure, "HitPoints").unwrap_or(0),
            max_hit_points: get_i16(structure, "MaxHitPoints").unwrap_or(0),
            pregame_current: get_i16(structure, "PregameCurrent").unwrap_or(0),
            force_points: get_i16(structure, "ForcePoints").unwrap_or(0),
            current_force: get_i16(structure, "CurrentForce").unwrap_or(0),
            max_force_points: get_i16(structure, "MaxForcePoints").unwrap_or(0),

            armor_class: get_i16(structure, "ArmorClass").unwrap_or(0),
            ref_save_throw: get_i8(structure, "RefSaveThrow").unwrap_or(0),
            will_save_throw: get_i8(structure, "WillSaveThrow").unwrap_or(0),
            fort_save_throw: get_i8(structure, "FortSaveThrow").unwrap_or(0),
            ref_bonus: get_i16(structure, "refbonus").unwrap_or(0),
            will_bonus: get_i16(structure, "willbonus").unwrap_or(0),
            fort_bonus: get_i16(structure, "fortbonus").unwrap_or(0),
            natural_ac: get_u8(structure, "NaturalAC").unwrap_or(0),

            experience: get_u32(structure, "Experience").unwrap_or(0),
            gold: get_u32(structure, "Gold").unwrap_or(0),
            skill_points: get_u16(structure, "SkillPoints").unwrap_or(0),
            multiclass_level_up_in: get_u8(structure, "MClassLevUpIn").unwrap_or(0),
            joining_xp: get_i32(structure, "JoiningXP").unwrap_or(0),
            starting_package: get_u8(structure, "StartingPackage").unwrap_or(0),
            challenge_rating: get_f32(structure, "ChallengeRating").unwrap_or(0.0),
            age: get_i32(structure, "Age").unwrap_or(0),

            race: get_u8(structure, "Race").unwrap_or(0),
            subrace: get_string(structure, "Subrace").unwrap_or_default(),
            subrace_index: get_u8(structure, "SubraceIndex").unwrap_or(0),
            deity: get_string(structure, "Deity").unwrap_or_default(),
            gender: get_u8(structure, "Gender").unwrap_or(0),
            good_evil: get_u8(structure, "GoodEvil").unwrap_or(0),
            faction_id: get_u16(structure, "FactionID").unwrap_or(0),
            sound_set_file: get_u16(structure, "SoundSetFile").unwrap_or(0),

            ai_state: get_i32(structure, "AIState").unwrap_or(0),
            not_reorienting: get_u8(structure, "NotReorienting").unwrap_or(0),
            detect_mode: get_u8(structure, "DetectMode").unwrap_or(0),
            stealth_mode: get_u8(structure, "StealthMode").unwrap_or(0),
            commandable: get_u8(structure, "Commandable").unwrap_or(0),
            listening: get_u8(structure, "Listening").unwrap_or(0),
            party_interact: get_u8(structure, "PartyInteract").unwrap_or(0),
            plot: get_u8(structure, "Plot").unwrap_or(0),
            min1_hp: get_u8(structure, "Min1HP").unwrap_or(0),
            interruptable: get_u8(structure, "Interruptable").unwrap_or(0),
            disarmable: get_u8(structure, "Disarmable").unwrap_or(0),
            is_destroyable: get_u8(structure, "IsDestroyable").unwrap_or(0),
            is_raiseable: get_u8(structure, "IsRaiseable").unwrap_or(0),
            dead_selectable: get_u8(structure, "DeadSelectable").unwrap_or(0),
            is_pc: get_u8(structure, "IsPC").unwrap_or(0),
            creation_script_fired: get_u8(structure, "CreatnScrptFird").unwrap_or(0),
            ambient_anim_state: get_u8(structure, "AmbientAnimState").unwrap_or(0),
            animation: get_i32(structure, "Animation").unwrap_or(0),
            creature_size: get_i32(structure, "CreatureSize").unwrap_or(0),
            movement_rate: get_u8(structure, "MovementRate").unwrap_or(0),

            classes: read_list(structure, "ClassList", SavedClass::from_struct),
            feats: read_list(structure, "FeatList", |e| get_u16(e, "Feat").unwrap_or(0)),
            skills: read_skills(structure),
            inventory: read_list(structure, "ItemList", SavedItem::from_struct),
            equipment: read_list(structure, "Equip_ItemList", SavedItem::from_struct),

            tail: get_u8(structure, "Tail").unwrap_or(0),
            wings: get_u8(structure, "Wings").unwrap_or(0),

            on_attacked: get_resref(structure, "ScriptAttacked").unwrap_or_default(),
            on_damaged: get_resref(structure, "ScriptDamaged").unwrap_or_default(),
            on_death: get_resref(structure, "ScriptDeath").unwrap_or_default(),
            on_dialog: get_resref(structure, "ScriptDialogue").unwrap_or_default(),
            on_disturbed: get_resref(structure, "ScriptDisturbed").unwrap_or_default(),
            on_end_dialog: get_resref(structure, "ScriptEndDialogu").unwrap_or_default(),
            on_end_round: get_resref(structure, "ScriptEndRound").unwrap_or_default(),
            on_heartbeat: get_resref(structure, "ScriptHeartbeat").unwrap_or_default(),
            on_blocked: get_resref(structure, "ScriptOnBlocked").unwrap_or_default(),
            on_notice: get_resref(structure, "ScriptOnNotice").unwrap_or_default(),
            on_rested: get_resref(structure, "ScriptRested").unwrap_or_default(),
            on_spawn: get_resref(structure, "ScriptSpawn").unwrap_or_default(),
            on_spell: get_resref(structure, "ScriptSpellAt").unwrap_or_default(),
            on_user_defined: get_resref(structure, "ScriptUserDefine").unwrap_or_default(),
        }
    }

    /// Writes this snapshot into a `Creature List` element.
    ///
    /// Emits exactly the fields this type models; the runtime lists and nested
    /// structs named in the module docs are not written because they are not
    /// read.
    pub fn to_struct(&self, index: usize) -> GffStruct {
        let mut s = GffStruct::new(i32::try_from(index).expect("creature index fits i32"));

        upsert_field(&mut s, "Tag", GffValue::String(self.tag.clone()));
        upsert_field(
            &mut s,
            "FirstName",
            GffValue::LocalizedString(self.first_name.clone()),
        );
        upsert_field(
            &mut s,
            "LastName",
            GffValue::LocalizedString(self.last_name.clone()),
        );
        upsert_field(
            &mut s,
            "Description",
            GffValue::LocalizedString(self.description.clone()),
        );
        upsert_field(&mut s, "ObjectId", GffValue::UInt32(self.object_id.get()));
        upsert_field(&mut s, "AreaId", GffValue::UInt32(self.area_id));
        upsert_field(&mut s, "Conversation", GffValue::ResRef(self.conversation));

        upsert_field(&mut s, "XPosition", GffValue::Single(self.x_position));
        upsert_field(&mut s, "YPosition", GffValue::Single(self.y_position));
        upsert_field(&mut s, "ZPosition", GffValue::Single(self.z_position));
        upsert_field(&mut s, "XOrientation", GffValue::Single(self.x_orientation));
        upsert_field(&mut s, "YOrientation", GffValue::Single(self.y_orientation));
        upsert_field(&mut s, "ZOrientation", GffValue::Single(self.z_orientation));

        upsert_field(
            &mut s,
            "Appearance_Type",
            GffValue::UInt16(self.appearance_type),
        );
        upsert_field(
            &mut s,
            "Appearance_Head",
            GffValue::UInt8(self.appearance_head),
        );
        upsert_field(&mut s, "PortraitId", GffValue::UInt16(self.portrait_id));
        upsert_field(&mut s, "Phenotype", GffValue::Int32(self.phenotype));
        upsert_field(&mut s, "Color_Skin", GffValue::UInt8(self.color_skin));
        upsert_field(&mut s, "Color_Hair", GffValue::UInt8(self.color_hair));
        upsert_field(&mut s, "Color_Tattoo1", GffValue::UInt8(self.color_tattoo1));
        upsert_field(&mut s, "Color_Tattoo2", GffValue::UInt8(self.color_tattoo2));
        upsert_field(
            &mut s,
            "DuplicatingHead",
            GffValue::UInt8(self.duplicating_head),
        );
        upsert_field(
            &mut s,
            "UseBackupHead",
            GffValue::UInt8(self.use_backup_head),
        );
        upsert_field(&mut s, "PM_IsDisguised", GffValue::UInt8(self.is_disguised));
        upsert_field(&mut s, "BodyBag", GffValue::UInt8(self.body_bag));

        upsert_field(&mut s, "Str", GffValue::UInt8(self.strength));
        upsert_field(&mut s, "Dex", GffValue::UInt8(self.dexterity));
        upsert_field(&mut s, "Con", GffValue::UInt8(self.constitution));
        upsert_field(&mut s, "Int", GffValue::UInt8(self.intelligence));
        upsert_field(&mut s, "Wis", GffValue::UInt8(self.wisdom));
        upsert_field(&mut s, "Cha", GffValue::UInt8(self.charisma));

        upsert_field(
            &mut s,
            "CurrentHitPoints",
            GffValue::Int16(self.current_hit_points),
        );
        upsert_field(&mut s, "HitPoints", GffValue::Int16(self.hit_points));
        upsert_field(&mut s, "MaxHitPoints", GffValue::Int16(self.max_hit_points));
        upsert_field(
            &mut s,
            "PregameCurrent",
            GffValue::Int16(self.pregame_current),
        );
        upsert_field(&mut s, "ForcePoints", GffValue::Int16(self.force_points));
        upsert_field(&mut s, "CurrentForce", GffValue::Int16(self.current_force));
        upsert_field(
            &mut s,
            "MaxForcePoints",
            GffValue::Int16(self.max_force_points),
        );

        upsert_field(&mut s, "ArmorClass", GffValue::Int16(self.armor_class));
        upsert_field(&mut s, "RefSaveThrow", GffValue::Int8(self.ref_save_throw));
        upsert_field(
            &mut s,
            "WillSaveThrow",
            GffValue::Int8(self.will_save_throw),
        );
        upsert_field(
            &mut s,
            "FortSaveThrow",
            GffValue::Int8(self.fort_save_throw),
        );
        upsert_field(&mut s, "refbonus", GffValue::Int16(self.ref_bonus));
        upsert_field(&mut s, "willbonus", GffValue::Int16(self.will_bonus));
        upsert_field(&mut s, "fortbonus", GffValue::Int16(self.fort_bonus));
        upsert_field(&mut s, "NaturalAC", GffValue::UInt8(self.natural_ac));

        upsert_field(&mut s, "Experience", GffValue::UInt32(self.experience));
        upsert_field(&mut s, "Gold", GffValue::UInt32(self.gold));
        upsert_field(&mut s, "SkillPoints", GffValue::UInt16(self.skill_points));
        upsert_field(
            &mut s,
            "MClassLevUpIn",
            GffValue::UInt8(self.multiclass_level_up_in),
        );
        upsert_field(&mut s, "JoiningXP", GffValue::Int32(self.joining_xp));
        upsert_field(
            &mut s,
            "StartingPackage",
            GffValue::UInt8(self.starting_package),
        );
        upsert_field(
            &mut s,
            "ChallengeRating",
            GffValue::Single(self.challenge_rating),
        );
        upsert_field(&mut s, "Age", GffValue::Int32(self.age));

        upsert_field(&mut s, "Race", GffValue::UInt8(self.race));
        upsert_field(&mut s, "Subrace", GffValue::String(self.subrace.clone()));
        upsert_field(&mut s, "SubraceIndex", GffValue::UInt8(self.subrace_index));
        upsert_field(&mut s, "Deity", GffValue::String(self.deity.clone()));
        upsert_field(&mut s, "Gender", GffValue::UInt8(self.gender));
        upsert_field(&mut s, "GoodEvil", GffValue::UInt8(self.good_evil));
        upsert_field(&mut s, "FactionID", GffValue::UInt16(self.faction_id));
        upsert_field(
            &mut s,
            "SoundSetFile",
            GffValue::UInt16(self.sound_set_file),
        );

        upsert_field(&mut s, "AIState", GffValue::Int32(self.ai_state));
        upsert_field(
            &mut s,
            "NotReorienting",
            GffValue::UInt8(self.not_reorienting),
        );
        upsert_field(&mut s, "DetectMode", GffValue::UInt8(self.detect_mode));
        upsert_field(&mut s, "StealthMode", GffValue::UInt8(self.stealth_mode));
        upsert_field(&mut s, "Commandable", GffValue::UInt8(self.commandable));
        upsert_field(&mut s, "Listening", GffValue::UInt8(self.listening));
        upsert_field(
            &mut s,
            "PartyInteract",
            GffValue::UInt8(self.party_interact),
        );
        upsert_field(&mut s, "Plot", GffValue::UInt8(self.plot));
        upsert_field(&mut s, "Min1HP", GffValue::UInt8(self.min1_hp));
        upsert_field(&mut s, "Interruptable", GffValue::UInt8(self.interruptable));
        upsert_field(&mut s, "Disarmable", GffValue::UInt8(self.disarmable));
        upsert_field(
            &mut s,
            "IsDestroyable",
            GffValue::UInt8(self.is_destroyable),
        );
        upsert_field(&mut s, "IsRaiseable", GffValue::UInt8(self.is_raiseable));
        upsert_field(
            &mut s,
            "DeadSelectable",
            GffValue::UInt8(self.dead_selectable),
        );
        upsert_field(&mut s, "IsPC", GffValue::UInt8(self.is_pc));
        upsert_field(
            &mut s,
            "CreatnScrptFird",
            GffValue::UInt8(self.creation_script_fired),
        );
        upsert_field(
            &mut s,
            "AmbientAnimState",
            GffValue::UInt8(self.ambient_anim_state),
        );
        upsert_field(&mut s, "Animation", GffValue::Int32(self.animation));
        upsert_field(&mut s, "CreatureSize", GffValue::Int32(self.creature_size));
        upsert_field(&mut s, "MovementRate", GffValue::UInt8(self.movement_rate));

        upsert_field(
            &mut s,
            "ClassList",
            GffValue::List(
                self.classes
                    .iter()
                    .enumerate()
                    .map(|(i, c)| c.to_struct(i))
                    .collect(),
            ),
        );
        upsert_field(
            &mut s,
            "FeatList",
            GffValue::List(
                self.feats
                    .iter()
                    .enumerate()
                    .map(|(i, feat)| {
                        let mut e = GffStruct::new(i32::try_from(i).expect("feat index fits i32"));
                        upsert_field(&mut e, "Feat", GffValue::UInt16(*feat));
                        e
                    })
                    .collect(),
            ),
        );
        upsert_field(
            &mut s,
            "SkillList",
            GffValue::List(write_skills(&self.skills)),
        );
        upsert_field(
            &mut s,
            "ItemList",
            GffValue::List(
                self.inventory
                    .iter()
                    .enumerate()
                    .map(|(index, item)| item.to_struct(index))
                    .collect(),
            ),
        );
        upsert_field(
            &mut s,
            "Equip_ItemList",
            GffValue::List(
                self.equipment
                    .iter()
                    .enumerate()
                    .map(|(index, item)| item.to_struct(index))
                    .collect(),
            ),
        );

        upsert_field(&mut s, "Tail", GffValue::UInt8(self.tail));
        upsert_field(&mut s, "Wings", GffValue::UInt8(self.wings));

        upsert_field(&mut s, "ScriptAttacked", GffValue::ResRef(self.on_attacked));
        upsert_field(&mut s, "ScriptDamaged", GffValue::ResRef(self.on_damaged));
        upsert_field(&mut s, "ScriptDeath", GffValue::ResRef(self.on_death));
        upsert_field(&mut s, "ScriptDialogue", GffValue::ResRef(self.on_dialog));
        upsert_field(
            &mut s,
            "ScriptDisturbed",
            GffValue::ResRef(self.on_disturbed),
        );
        upsert_field(
            &mut s,
            "ScriptEndDialogu",
            GffValue::ResRef(self.on_end_dialog),
        );
        upsert_field(
            &mut s,
            "ScriptEndRound",
            GffValue::ResRef(self.on_end_round),
        );
        upsert_field(
            &mut s,
            "ScriptHeartbeat",
            GffValue::ResRef(self.on_heartbeat),
        );
        upsert_field(&mut s, "ScriptOnBlocked", GffValue::ResRef(self.on_blocked));
        upsert_field(&mut s, "ScriptOnNotice", GffValue::ResRef(self.on_notice));
        upsert_field(&mut s, "ScriptRested", GffValue::ResRef(self.on_rested));
        upsert_field(&mut s, "ScriptSpawn", GffValue::ResRef(self.on_spawn));
        upsert_field(&mut s, "ScriptSpellAt", GffValue::ResRef(self.on_spell));
        upsert_field(
            &mut s,
            "ScriptUserDefine",
            GffValue::ResRef(self.on_user_defined),
        );

        s
    }
}

/// One entry from a saved creature's `ClassList`.
///
/// Distinct from [`UtcClass`](crate::utc::UtcClass): a saved class also
/// carries `SpellsPerDayList`, which a blueprint does not.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct SavedClass {
    /// Class row (`Class`).
    pub class_id: i32,
    /// Level in this class (`ClassLevel`).
    pub class_level: i16,
    /// Known power ids from `KnownList0` (`Spell`).
    pub powers: Vec<u16>,
    /// Remaining casts per level from `SpellsPerDayList` (`NumSpellsLeft`).
    pub spells_per_day: Vec<u8>,
}

impl SavedClass {
    fn from_struct(structure: &GffStruct) -> Self {
        Self {
            class_id: get_i32(structure, "Class").unwrap_or(0),
            class_level: get_i16(structure, "ClassLevel").unwrap_or(0),
            powers: read_list(structure, "KnownList0", |e| {
                get_u16(e, "Spell").unwrap_or(0)
            }),
            spells_per_day: read_list(structure, "SpellsPerDayList", |e| {
                get_u8(e, "NumSpellsLeft").unwrap_or(0)
            }),
        }
    }

    fn to_struct(&self, index: usize) -> GffStruct {
        let mut s = GffStruct::new(i32::try_from(index).expect("class index fits i32"));
        upsert_field(&mut s, "Class", GffValue::Int32(self.class_id));
        upsert_field(&mut s, "ClassLevel", GffValue::Int16(self.class_level));
        upsert_field(
            &mut s,
            "KnownList0",
            GffValue::List(
                self.powers
                    .iter()
                    .enumerate()
                    .map(|(i, spell)| {
                        let mut e = GffStruct::new(i32::try_from(i).expect("power index fits i32"));
                        upsert_field(&mut e, "Spell", GffValue::UInt16(*spell));
                        e
                    })
                    .collect(),
            ),
        );
        upsert_field(
            &mut s,
            "SpellsPerDayList",
            GffValue::List(
                self.spells_per_day
                    .iter()
                    .enumerate()
                    .map(|(i, left)| {
                        let mut e = GffStruct::new(i32::try_from(i).expect("spell level fits i32"));
                        upsert_field(&mut e, "NumSpellsLeft", GffValue::UInt8(*left));
                        e
                    })
                    .collect(),
            ),
        );
        s
    }
}

/// Maps each element of a list field through `build`, or yields nothing when
/// the field is absent or not a list.
fn read_list<T>(structure: &GffStruct, label: &str, build: impl Fn(&GffStruct) -> T) -> Vec<T> {
    match structure.field(label) {
        Some(GffValue::List(entries)) => entries.iter().map(build).collect(),
        _ => Vec::new(),
    }
}

/// Reads `SkillList`, which the engine stores positionally: one `Rank` per
/// skill row, in `skills.2da` order.
fn read_skills(structure: &GffStruct) -> UtcSkills {
    let ranks = read_list(structure, "SkillList", |e| get_u8(e, "Rank").unwrap_or(0));
    let at = |index: usize| ranks.get(index).copied().unwrap_or(0);
    UtcSkills {
        computer_use: at(0),
        demolitions: at(1),
        stealth: at(2),
        awareness: at(3),
        persuade: at(4),
        repair: at(5),
        security: at(6),
        treat_injury: at(7),
    }
}

/// Writes the eight skill ranks back in engine order.
fn write_skills(skills: &UtcSkills) -> Vec<GffStruct> {
    [
        skills.computer_use,
        skills.demolitions,
        skills.stealth,
        skills.awareness,
        skills.persuade,
        skills.repair,
        skills.security,
        skills.treat_injury,
    ]
    .iter()
    .enumerate()
    .map(|(index, rank)| {
        let mut e = GffStruct::new(i32::try_from(index).expect("skill index fits i32"));
        upsert_field(&mut e, "Rank", GffValue::UInt8(*rank));
        e
    })
    .collect()
}

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

    #[test]
    fn round_trips_through_a_gff_struct() {
        let mut creature = SavedCreature::new();
        creature.tag = "bastila".to_string();
        creature.current_hit_points = 42;
        creature.gold = 1250;
        creature.good_evil = 75;
        creature.ref_bonus = -3;
        creature.on_death = ResRef::new("k_hen_death").expect("valid resref");
        creature.conversation = ResRef::new("k_hen_dlg").expect("valid resref");

        let parsed = SavedCreature::from_struct(&creature.to_struct(0));

        assert_eq!(parsed, creature);
    }

    #[test]
    fn an_absent_field_falls_back_to_the_engine_default() {
        // A UseTemplates = 0 element that omits a field gets the engine's
        // hardcoded default, not a blueprint value.
        let empty = SavedCreature::from_struct(&GffStruct::new(0));

        assert_eq!(empty.current_hit_points, 0);
        assert_eq!(empty.gold, 0);
        assert!(empty.tag.is_empty());
    }

    #[test]
    fn progression_lists_round_trip() {
        let mut creature = SavedCreature::new();
        creature.classes = vec![SavedClass {
            class_id: 3,
            class_level: 7,
            powers: vec![10, 22, 41],
            spells_per_day: vec![0, 2, 1],
        }];
        creature.feats = vec![1, 5, 9, 44];
        creature.skills.stealth = 6;
        creature.skills.treat_injury = 12;

        let parsed = SavedCreature::from_struct(&creature.to_struct(0));

        assert_eq!(parsed.classes, creature.classes);
        assert_eq!(parsed.feats, creature.feats);
        assert_eq!(parsed.skills, creature.skills);
    }

    #[test]
    fn skill_ranks_keep_their_engine_order() {
        // SkillList is positional: rank N belongs to skills.2da row N.
        let mut creature = SavedCreature::new();
        creature.skills.computer_use = 1;
        creature.skills.persuade = 4;

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

        assert_eq!(entries.len(), 8);
        assert_eq!(get_u8(&entries[0], "Rank"), Some(1));
        assert_eq!(get_u8(&entries[4], "Rank"), Some(4));
    }

    #[test]
    fn a_class_without_powers_still_round_trips() {
        let mut creature = SavedCreature::new();
        creature.classes = vec![SavedClass {
            class_id: 1,
            class_level: 2,
            ..SavedClass::default()
        }];

        let parsed = SavedCreature::from_struct(&creature.to_struct(0));

        assert_eq!(parsed.classes[0].class_id, 1);
        assert!(parsed.classes[0].powers.is_empty());
        assert!(parsed.classes[0].spells_per_day.is_empty());
    }

    #[test]
    fn a_default_snapshot_writes_every_script_hook() {
        // The positional Vec this replaced wrote nothing by default and
        // truncated silently if it were short.
        let written = SavedCreature::default().to_struct(0);

        for label in [
            "ScriptAttacked",
            "ScriptDamaged",
            "ScriptDeath",
            "ScriptDialogue",
            "ScriptDisturbed",
            "ScriptEndDialogu",
            "ScriptEndRound",
            "ScriptHeartbeat",
            "ScriptOnBlocked",
            "ScriptOnNotice",
            "ScriptRested",
            "ScriptSpawn",
            "ScriptSpellAt",
            "ScriptUserDefine",
            "Conversation",
        ] {
            assert!(written.field(label).is_some(), "{label} was not written");
        }
    }

    #[test]
    fn negative_save_bonuses_survive() {
        // refbonus / willbonus / fortbonus are signed inputs the engine reads
        // back, unlike the computed totals beside them.
        let mut creature = SavedCreature::new();
        creature.ref_bonus = -5;
        creature.will_bonus = -1;
        creature.fort_save_throw = -2;

        let parsed = SavedCreature::from_struct(&creature.to_struct(0));

        assert_eq!(parsed.ref_bonus, -5);
        assert_eq!(parsed.will_bonus, -1);
        assert_eq!(parsed.fort_save_throw, -2);
    }
}