rakata_generics/

ifo.rs

//! IFO (`.ifo`) typed generic wrapper.
//!
//! IFO resources are GFF-backed module info files that define a module's
//! identity, entry point, time settings, scripts, and area list.
//!
//! ## Scope
//! - Typed access for all root fields from the Ghidra audit.
//! - Save-game-only fields (calendar state, ID counters, player list, tokens).
//! - Typed area list (`Mod_Area_list`) with per-entry area name and object ID.
//! - Typed script hooks (15 module-level event scripts).
//! - Typed expansion, cutscene, player, and token lists.
//!
//! ## Field Layout (simplified)
//! ```text
//! IFO root struct
//! +-- Mod_IsSaveGame / Mod_IsNWMFile / Mod_NWMResName
//! +-- Mod_ID / Mod_Creator_ID / Mod_Version
//! +-- Mod_Tag / Mod_Name / Mod_Description
//! +-- Mod_Entry_Area / Mod_Entry_X / Mod_Entry_Y / Mod_Entry_Z
//! +-- Mod_Entry_Dir_X / Mod_Entry_Dir_Y / Mod_StartMovie
//! +-- Mod_MinPerHour / Mod_DawnHour / Mod_DuskHour / Mod_XPScale
//! +-- Mod_On* (15 script hooks)
//! +-- Mod_Area_list[]
//! |   +-- Area_Name / ObjectId (save-only)
//! +-- Mod_Expan_List[] / Mod_CutSceneList[]
//! +-- Mod_PlayerList[] (save-only) / Mod_Tokens[] (save-only)
//! +-- Save-game calendar state / ID counters / Mod_Hak
//! ```

use std::io::{Cursor, Read, Write};

use crate::gff_helpers::{
    get_bool, get_f32, get_i32, get_locstring, get_resref, get_string, get_u16, get_u32, get_u64,
    get_u8, upsert_field,
};
use crate::shared::ObjectId;
use rakata_core::{ResRef, StrRef};
use rakata_formats::{
    gff_schema::{AbsentDefault, FieldLife, FieldSchema, GffSchema, GffType},
    read_gff, read_gff_from_bytes, write_gff, Gff, GffBinaryError, GffLocalizedString, GffStruct,
    GffValue,
};
use thiserror::Error;

/// Typed IFO area list entry (`Mod_Area_list`).
#[derive(Debug, Clone, PartialEq)]
pub struct IfoArea {
    /// Area resref (`Area_Name`).
    pub area_name: ResRef,
    /// Object ID assigned at runtime in save games (`ObjectId`).
    pub object_id: ObjectId,
}

/// Typed IFO expansion list entry (`Mod_Expan_List`).
#[derive(Debug, Clone, PartialEq)]
pub struct IfoExpansion {
    /// Localized expansion name (`Expansion_Name`).
    pub expansion_name: GffLocalizedString,
    /// Expansion ID (`Expansion_ID`).
    pub expansion_id: i32,
}

/// Typed IFO cutscene list entry (`Mod_CutSceneList`).
#[derive(Debug, Clone, PartialEq)]
pub struct IfoCutScene {
    /// Cutscene resref (`CutScene_Name`).
    pub cutscene_name: ResRef,
    /// Cutscene ID (`CutScene_ID`).
    pub cutscene_id: u32,
}

/// Typed IFO player list entry (`Mod_PlayerList`, save-only).
#[derive(Debug, Clone, PartialEq)]
pub struct IfoPlayer {
    /// Community name (`Mod_CommntyName`).
    pub community_name: String,
    /// Localized first name (`Mod_FirstName`).
    pub first_name: GffLocalizedString,
    /// Localized last name (`Mod_LastName`).
    pub last_name: GffLocalizedString,
    /// Whether this is the primary player (`Mod_IsPrimaryPlr`).
    pub is_primary_player: bool,
}

/// Typed IFO token entry (`Mod_Tokens`).
#[derive(Debug, Clone, PartialEq)]
pub struct IfoToken {
    /// Token number (`Mod_TokensNumber`).
    pub token_number: u32,
    /// Token value (`Mod_TokensValue`).
    pub token_value: String,
}

/// Typed IFO model built from/to [`Gff`] data.
#[derive(Debug, Clone, PartialEq)]
pub struct Ifo {
    // --- Root flags ---
    /// Whether this is a save game (`Mod_IsSaveGame`).
    pub is_save_game: bool,
    /// Whether this is an NWM file (`Mod_IsNWMFile`).
    pub is_nwm_file: bool,
    /// NWM resource name, only meaningful when `is_nwm_file` is true (`Mod_NWMResName`). If empty when flagged as NWM, execution becomes unstable.
    pub nwm_res_name: String,

    // --- Module identity ---
    /// Module ID blob (`Mod_ID`), kept at whatever length the file carries.
    ///
    /// Vanilla `module.ifo` carries 16 bytes; every savegame `module.ifo`
    /// carries 32. The difference is an engine artefact rather than a format
    /// rule: the loader reads this into a fixed 32-byte buffer it never
    /// zeroes, and the writer always emits all 32 back, so a vanilla module
    /// widens to 32 the first time the game saves it and the upper half is
    /// whatever was in that memory.
    ///
    /// **Do not pad short values to 32 bytes to match.** That reproduces the
    /// engine's own bug, and it is the tempting move for anyone who checks
    /// only savegames, where 32 looks canonical. Reading 16 and writing 16
    /// leaves the file exactly as its author wrote it. The engine never
    /// consumes or compares this value, so neither behaviour affects play.
    pub module_id: Vec<u8>,
    /// Creator ID (`Mod_Creator_ID`).
    pub creator_id: i32,
    /// Module version (`Mod_Version`).
    pub version: u32,
    /// Module tag (`Mod_Tag`).
    pub tag: String,
    /// Localized module name (`Mod_Name`).
    pub name: GffLocalizedString,
    /// Localized module description (`Mod_Description`).
    pub description: GffLocalizedString,

    // --- Entry point ---
    /// Introductory movie (`Mod_StartMovie`).
    pub start_movie: ResRef,
    /// Entry area resref (`Mod_Entry_Area`).
    pub entry_area: ResRef,
    /// Entry X coordinate (`Mod_Entry_X`).
    pub entry_x: f32,
    /// Entry Y coordinate (`Mod_Entry_Y`).
    pub entry_y: f32,
    /// Entry Z coordinate (`Mod_Entry_Z`).
    pub entry_z: f32,
    /// Entry facing direction X (`Mod_Entry_Dir_X`). If X and Y are both 0.0, engine locks spawn facing east (1.0, 0.0).
    pub entry_dir_x: f32,
    /// Entry facing direction Y (`Mod_Entry_Dir_Y`). If X and Y are both 0.0, engine locks spawn facing east (1.0, 0.0).
    pub entry_dir_y: f32,

    // --- Time / day-night ---
    /// Minutes per game hour (`Mod_MinPerHour`). If missing, defaults to 2.
    pub min_per_hour: u8,
    /// Dawn hour (`Mod_DawnHour`). If equal to dusk hour, module is locked into perpetual daylight. If missing, defaults to 6.
    pub dawn_hour: u8,
    /// Dusk hour (`Mod_DuskHour`). If equal to dawn hour, module is locked into perpetual daylight. If missing, defaults to 18. Engine derives a continuous day/night state flag from `dawn_hour`, `dusk_hour`, and the current hour: `1` = Day, `2` = Night, `3` = Dawn, `4` = Dusk.
    pub dusk_hour: u8,
    /// XP scale multiplier (`Mod_XPScale`). Setting to 0 completely halts localized XP acquisition. If missing, defaults to 10.
    pub xp_scale: u8,

    // --- Save-game-only: calendar state ---
    /// Game calendar year (`Mod_StartYear`, save-only, default 1340).
    pub start_year: u32,
    /// Calendar month (`Mod_StartMonth`, save-only, default 6).
    pub start_month: u8,
    /// Calendar day (`Mod_StartDay`, save-only, default 1).
    pub start_day: u8,
    /// Calendar hour (`Mod_StartHour`, save-only, default 23).
    pub start_hour: u8,
    /// Calendar minute (`Mod_StartMinute`, save-only, default 0).
    pub start_minute: u16,
    /// Calendar second (`Mod_StartSecond`, save-only, default 0).
    pub start_second: u16,
    /// Calendar millisecond (`Mod_StartMiliSec`, save-only, default 0).
    pub start_millisecond: u16,
    /// Transition state (`Mod_Transition`, save-only, default 0).
    pub transition: u32,
    /// Paused time-of-day in milliseconds (`Mod_PauseTime`, save-only, default 0).
    pub pause_time: u32,
    /// Paused calendar day (`Mod_PauseDay`, save-only, default 0).
    pub pause_day: u32,

    // --- Save-game-only: ID counters ---
    /// Next effect ID counter (`Mod_Effect_NxtId`, save-only).
    pub effect_next_id: u64,
    /// Next character ID low word (`Mod_NextCharId0`, save-only).
    pub next_char_id_0: u32,
    /// Next character ID high word (`Mod_NextCharId1`, save-only).
    pub next_char_id_1: u32,
    /// Next object ID low word (`Mod_NextObjId0`, save-only).
    pub next_obj_id_0: u32,
    /// Next object ID high word (`Mod_NextObjId1`, save-only).
    pub next_obj_id_1: u32,

    // --- Save-game-only: Mod_Hak (written but not read by engine) ---
    /// Hak pack name (`Mod_Hak`, save-only). The save routine writes this string into save-games as a leftover NWN legacy artifact, but `LoadModuleStart` completely ignores it - cannot be used to hook custom override archives.
    pub hak: String,

    // --- Scripts (15) ---
    /// On-heartbeat script (`Mod_OnHeartbeat`).
    pub on_heartbeat: ResRef,
    /// On-user-defined script (`Mod_OnUsrDefined`).
    pub on_user_defined: ResRef,
    /// On-module-load script (`Mod_OnModLoad`).
    pub on_mod_load: ResRef,
    /// On-module-start script (`Mod_OnModStart`).
    pub on_mod_start: ResRef,
    /// On-client-enter script (`Mod_OnClientEntr`).
    pub on_client_enter: ResRef,
    /// On-client-leave script (`Mod_OnClientLeav`).
    pub on_client_leave: ResRef,
    /// On-activate-item script (`Mod_OnActvtItem`).
    pub on_activate_item: ResRef,
    /// On-acquire-item script (`Mod_OnAcquirItem`).
    pub on_acquire_item: ResRef,
    /// On-unacquire-item script (`Mod_OnUnAqreItem`).
    pub on_unacquire_item: ResRef,
    /// On-player-death script (`Mod_OnPlrDeath`).
    pub on_player_death: ResRef,
    /// On-player-dying script (`Mod_OnPlrDying`).
    pub on_player_dying: ResRef,
    /// On-spawn-button-down script (`Mod_OnSpawnBtnDn`).
    pub on_spawn_btn_down: ResRef,
    /// On-player-rest script (`Mod_OnPlrRest`).
    pub on_player_rest: ResRef,
    /// On-player-level-up script (`Mod_OnPlrLvlUp`).
    pub on_player_level_up: ResRef,
    /// On-equip-item script (`Mod_OnEquipItem`). Asymmetric I/O: the engine loads this during `LoadModuleStart` but entirely omits it from `SaveModuleIFOStart` save-game serialization.
    pub on_equip_item: ResRef,

    // --- Lists ---
    /// Module areas (`Mod_Area_list`). An empty list will fault the engine load cycle. The format technically supports multiple entries (NWN legacy), but the KOTOR engine strictly enforces a single active area boundary per module.
    pub areas: Vec<IfoArea>,
    /// Expansion list (`Mod_Expan_List`).
    pub expansion_list: Vec<IfoExpansion>,
    /// Cutscene list (`Mod_CutSceneList`).
    pub cutscene_list: Vec<IfoCutScene>,
    /// Player list (`Mod_PlayerList`, save-only).
    pub player_list: Vec<IfoPlayer>,
    /// Token list (`Mod_Tokens`).
    pub tokens: Vec<IfoToken>,
}

impl Default for Ifo {
    fn default() -> Self {
        Self {
            is_save_game: false,
            is_nwm_file: false,
            nwm_res_name: String::new(),
            module_id: Vec::new(),
            creator_id: 0,
            version: 0,
            tag: String::new(),
            name: GffLocalizedString::new(StrRef::invalid()),
            description: GffLocalizedString::new(StrRef::invalid()),
            start_movie: ResRef::blank(),
            entry_area: ResRef::blank(),
            entry_x: 0.0,
            entry_y: 0.0,
            entry_z: 0.0,
            entry_dir_x: 0.0,
            entry_dir_y: 0.0,
            min_per_hour: 0,
            dawn_hour: 0,
            dusk_hour: 0,
            xp_scale: 10,
            start_year: 1340,
            start_month: 6,
            start_day: 1,
            start_hour: 23,
            start_minute: 0,
            start_second: 0,
            start_millisecond: 0,
            transition: 0,
            pause_time: 0,
            pause_day: 0,
            effect_next_id: 0,
            next_char_id_0: 0,
            next_char_id_1: 0,
            next_obj_id_0: 0,
            next_obj_id_1: 0,
            hak: String::new(),
            on_heartbeat: ResRef::blank(),
            on_user_defined: ResRef::blank(),
            on_mod_load: ResRef::blank(),
            on_mod_start: ResRef::blank(),
            on_client_enter: ResRef::blank(),
            on_client_leave: ResRef::blank(),
            on_activate_item: ResRef::blank(),
            on_acquire_item: ResRef::blank(),
            on_unacquire_item: ResRef::blank(),
            on_player_death: ResRef::blank(),
            on_player_dying: ResRef::blank(),
            on_spawn_btn_down: ResRef::blank(),
            on_player_rest: ResRef::blank(),
            on_player_level_up: ResRef::blank(),
            on_equip_item: ResRef::blank(),
            areas: Vec::new(),
            expansion_list: Vec::new(),
            cutscene_list: Vec::new(),
            player_list: Vec::new(),
            tokens: Vec::new(),
        }
    }
}

impl Ifo {
    /// Creates an empty IFO value.
    pub fn new() -> Self {
        Self::default()
    }

    /// Builds typed IFO data from a parsed GFF container.
    pub fn from_gff(gff: &Gff) -> Result<Self, IfoError> {
        if gff.file_type != *b"IFO " && gff.file_type != *b"GFF " {
            return Err(IfoError::UnsupportedFileType(gff.file_type));
        }

        let root = &gff.root;

        let is_save_game = get_bool(root, "Mod_IsSaveGame").unwrap_or(false);
        let is_nwm_file = get_bool(root, "Mod_IsNWMFile").unwrap_or(false);
        let nwm_res_name = if is_nwm_file {
            get_string(root, "Mod_NWMResName").unwrap_or_default()
        } else {
            String::new()
        };

        let module_id = match root.field("Mod_ID") {
            Some(GffValue::Binary(data)) => data.clone(),
            _ => Vec::new(),
        };

        let areas = match root.field("Mod_Area_list") {
            Some(GffValue::List(elements)) => elements
                .iter()
                .map(|s| IfoArea {
                    area_name: get_resref(s, "Area_Name").unwrap_or_default(),
                    object_id: get_u32(s, "ObjectId").map_or(ObjectId::INVALID, ObjectId::new),
                })
                .collect(),
            _ => Vec::new(),
        };

        let expansion_list = match root.field("Mod_Expan_List") {
            Some(GffValue::List(elements)) => elements
                .iter()
                .map(|s| IfoExpansion {
                    expansion_name: get_locstring(s, "Expansion_Name")
                        .cloned()
                        .unwrap_or_else(|| GffLocalizedString::new(StrRef::invalid())),
                    expansion_id: get_i32(s, "Expansion_ID").unwrap_or(0),
                })
                .collect(),
            _ => Vec::new(),
        };

        let cutscene_list = match root.field("Mod_CutSceneList") {
            Some(GffValue::List(elements)) => elements
                .iter()
                .map(|s| IfoCutScene {
                    cutscene_name: get_resref(s, "CutScene_Name").unwrap_or_default(),
                    cutscene_id: get_u32(s, "CutScene_ID").unwrap_or(0),
                })
                .collect(),
            _ => Vec::new(),
        };

        let player_list = match root.field("Mod_PlayerList") {
            Some(GffValue::List(elements)) => elements
                .iter()
                .map(|s| IfoPlayer {
                    community_name: get_string(s, "Mod_CommntyName").unwrap_or_default(),
                    first_name: get_locstring(s, "Mod_FirstName")
                        .cloned()
                        .unwrap_or_else(|| GffLocalizedString::new(StrRef::invalid())),
                    last_name: get_locstring(s, "Mod_LastName")
                        .cloned()
                        .unwrap_or_else(|| GffLocalizedString::new(StrRef::invalid())),
                    is_primary_player: get_bool(s, "Mod_IsPrimaryPlr").unwrap_or(false),
                })
                .collect(),
            _ => Vec::new(),
        };

        let tokens_list = match root.field("Mod_Tokens") {
            Some(GffValue::List(elements)) => elements
                .iter()
                .map(|s| IfoToken {
                    token_number: get_u32(s, "Mod_TokensNumber").unwrap_or(0),
                    token_value: get_string(s, "Mod_TokensValue").unwrap_or_default(),
                })
                .collect(),
            _ => Vec::new(),
        };

        Ok(Self {
            is_save_game,
            is_nwm_file,
            nwm_res_name,
            module_id,
            creator_id: get_i32(root, "Mod_Creator_ID").unwrap_or(0),
            version: get_u32(root, "Mod_Version").unwrap_or(0),
            tag: get_string(root, "Mod_Tag").unwrap_or_default(),
            name: get_locstring(root, "Mod_Name")
                .cloned()
                .unwrap_or_else(|| GffLocalizedString::new(StrRef::invalid())),
            description: get_locstring(root, "Mod_Description")
                .cloned()
                .unwrap_or_else(|| GffLocalizedString::new(StrRef::invalid())),
            start_movie: get_resref(root, "Mod_StartMovie").unwrap_or_default(),
            entry_area: get_resref(root, "Mod_Entry_Area").unwrap_or_default(),
            entry_x: get_f32(root, "Mod_Entry_X").unwrap_or(0.0),
            entry_y: get_f32(root, "Mod_Entry_Y").unwrap_or(0.0),
            entry_z: get_f32(root, "Mod_Entry_Z").unwrap_or(0.0),
            entry_dir_x: get_f32(root, "Mod_Entry_Dir_X").unwrap_or(0.0),
            entry_dir_y: get_f32(root, "Mod_Entry_Dir_Y").unwrap_or(0.0),
            min_per_hour: get_u8(root, "Mod_MinPerHour").unwrap_or(0),
            dawn_hour: get_u8(root, "Mod_DawnHour").unwrap_or(0),
            dusk_hour: get_u8(root, "Mod_DuskHour").unwrap_or(0),
            xp_scale: get_u8(root, "Mod_XPScale").unwrap_or(10),
            start_year: get_u32(root, "Mod_StartYear").unwrap_or(1340),
            start_month: get_u8(root, "Mod_StartMonth").unwrap_or(6),
            start_day: get_u8(root, "Mod_StartDay").unwrap_or(1),
            start_hour: get_u8(root, "Mod_StartHour").unwrap_or(23),
            start_minute: get_u16(root, "Mod_StartMinute").unwrap_or(0),
            start_second: get_u16(root, "Mod_StartSecond").unwrap_or(0),
            start_millisecond: get_u16(root, "Mod_StartMiliSec").unwrap_or(0),
            transition: get_u32(root, "Mod_Transition").unwrap_or(0),
            pause_time: get_u32(root, "Mod_PauseTime").unwrap_or(0),
            pause_day: get_u32(root, "Mod_PauseDay").unwrap_or(0),
            effect_next_id: get_u64(root, "Mod_Effect_NxtId").unwrap_or(0),
            next_char_id_0: get_u32(root, "Mod_NextCharId0").unwrap_or(0),
            next_char_id_1: get_u32(root, "Mod_NextCharId1").unwrap_or(0),
            next_obj_id_0: get_u32(root, "Mod_NextObjId0").unwrap_or(0),
            next_obj_id_1: get_u32(root, "Mod_NextObjId1").unwrap_or(0),
            hak: get_string(root, "Mod_Hak").unwrap_or_default(),
            on_heartbeat: get_resref(root, "Mod_OnHeartbeat").unwrap_or_default(),
            on_user_defined: get_resref(root, "Mod_OnUsrDefined").unwrap_or_default(),
            on_mod_load: get_resref(root, "Mod_OnModLoad").unwrap_or_default(),
            on_mod_start: get_resref(root, "Mod_OnModStart").unwrap_or_default(),
            on_client_enter: get_resref(root, "Mod_OnClientEntr").unwrap_or_default(),
            on_client_leave: get_resref(root, "Mod_OnClientLeav").unwrap_or_default(),
            on_activate_item: get_resref(root, "Mod_OnActvtItem").unwrap_or_default(),
            on_acquire_item: get_resref(root, "Mod_OnAcquirItem").unwrap_or_default(),
            on_unacquire_item: get_resref(root, "Mod_OnUnAqreItem").unwrap_or_default(),
            on_player_death: get_resref(root, "Mod_OnPlrDeath").unwrap_or_default(),
            on_player_dying: get_resref(root, "Mod_OnPlrDying").unwrap_or_default(),
            on_spawn_btn_down: get_resref(root, "Mod_OnSpawnBtnDn").unwrap_or_default(),
            on_player_rest: get_resref(root, "Mod_OnPlrRest").unwrap_or_default(),
            on_player_level_up: get_resref(root, "Mod_OnPlrLvlUp").unwrap_or_default(),
            on_equip_item: get_resref(root, "Mod_OnEquipItem").unwrap_or_default(),
            areas,
            expansion_list,
            cutscene_list,
            player_list,
            tokens: tokens_list,
        })
    }

    /// Converts this typed IFO value into a GFF container.
    ///
    /// Builds the GFF root from scratch using only modeled fields.
    pub fn to_gff(&self) -> Gff {
        let mut root = GffStruct::new(-1);

        // --- Root flags ---
        upsert_field(
            &mut root,
            "Mod_IsSaveGame",
            GffValue::UInt8(u8::from(self.is_save_game)),
        );
        upsert_field(
            &mut root,
            "Mod_IsNWMFile",
            GffValue::UInt8(u8::from(self.is_nwm_file)),
        );
        if self.is_nwm_file {
            upsert_field(
                &mut root,
                "Mod_NWMResName",
                GffValue::String(self.nwm_res_name.clone()),
            );
        }

        // --- Module identity ---
        upsert_field(
            &mut root,
            "Mod_ID",
            GffValue::Binary(self.module_id.clone()),
        );
        upsert_field(
            &mut root,
            "Mod_Creator_ID",
            GffValue::Int32(self.creator_id),
        );
        upsert_field(&mut root, "Mod_Version", GffValue::UInt32(self.version));
        upsert_field(&mut root, "Mod_Tag", GffValue::String(self.tag.clone()));
        upsert_field(
            &mut root,
            "Mod_Name",
            GffValue::LocalizedString(self.name.clone()),
        );
        upsert_field(
            &mut root,
            "Mod_Description",
            GffValue::LocalizedString(self.description.clone()),
        );

        // --- Entry point ---
        upsert_field(
            &mut root,
            "Mod_StartMovie",
            GffValue::ResRef(self.start_movie),
        );
        upsert_field(
            &mut root,
            "Mod_Entry_Area",
            GffValue::ResRef(self.entry_area),
        );
        upsert_field(&mut root, "Mod_Entry_X", GffValue::Single(self.entry_x));
        upsert_field(&mut root, "Mod_Entry_Y", GffValue::Single(self.entry_y));
        upsert_field(&mut root, "Mod_Entry_Z", GffValue::Single(self.entry_z));
        upsert_field(
            &mut root,
            "Mod_Entry_Dir_X",
            GffValue::Single(self.entry_dir_x),
        );
        upsert_field(
            &mut root,
            "Mod_Entry_Dir_Y",
            GffValue::Single(self.entry_dir_y),
        );

        // --- Time / day-night ---
        upsert_field(
            &mut root,
            "Mod_MinPerHour",
            GffValue::UInt8(self.min_per_hour),
        );
        upsert_field(&mut root, "Mod_DawnHour", GffValue::UInt8(self.dawn_hour));
        upsert_field(&mut root, "Mod_DuskHour", GffValue::UInt8(self.dusk_hour));
        upsert_field(&mut root, "Mod_XPScale", GffValue::UInt8(self.xp_scale));

        // --- Save-game-only: calendar state ---
        upsert_field(
            &mut root,
            "Mod_StartYear",
            GffValue::UInt32(self.start_year),
        );
        upsert_field(
            &mut root,
            "Mod_StartMonth",
            GffValue::UInt8(self.start_month),
        );
        upsert_field(&mut root, "Mod_StartDay", GffValue::UInt8(self.start_day));
        upsert_field(&mut root, "Mod_StartHour", GffValue::UInt8(self.start_hour));
        upsert_field(
            &mut root,
            "Mod_StartMinute",
            GffValue::UInt16(self.start_minute),
        );
        upsert_field(
            &mut root,
            "Mod_StartSecond",
            GffValue::UInt16(self.start_second),
        );
        upsert_field(
            &mut root,
            "Mod_StartMiliSec",
            GffValue::UInt16(self.start_millisecond),
        );
        upsert_field(
            &mut root,
            "Mod_Transition",
            GffValue::UInt32(self.transition),
        );
        upsert_field(
            &mut root,
            "Mod_PauseTime",
            GffValue::UInt32(self.pause_time),
        );
        upsert_field(&mut root, "Mod_PauseDay", GffValue::UInt32(self.pause_day));

        // --- Save-game-only: ID counters ---
        upsert_field(
            &mut root,
            "Mod_Effect_NxtId",
            GffValue::UInt64(self.effect_next_id),
        );
        upsert_field(
            &mut root,
            "Mod_NextCharId0",
            GffValue::UInt32(self.next_char_id_0),
        );
        upsert_field(
            &mut root,
            "Mod_NextCharId1",
            GffValue::UInt32(self.next_char_id_1),
        );
        upsert_field(
            &mut root,
            "Mod_NextObjId0",
            GffValue::UInt32(self.next_obj_id_0),
        );
        upsert_field(
            &mut root,
            "Mod_NextObjId1",
            GffValue::UInt32(self.next_obj_id_1),
        );

        // --- Save-game-only: Mod_Hak ---
        if !self.hak.is_empty() {
            upsert_field(&mut root, "Mod_Hak", GffValue::String(self.hak.clone()));
        }

        // --- Scripts ---
        upsert_field(
            &mut root,
            "Mod_OnHeartbeat",
            GffValue::ResRef(self.on_heartbeat),
        );
        upsert_field(
            &mut root,
            "Mod_OnUsrDefined",
            GffValue::ResRef(self.on_user_defined),
        );
        upsert_field(
            &mut root,
            "Mod_OnModLoad",
            GffValue::ResRef(self.on_mod_load),
        );
        upsert_field(
            &mut root,
            "Mod_OnModStart",
            GffValue::ResRef(self.on_mod_start),
        );
        upsert_field(
            &mut root,
            "Mod_OnClientEntr",
            GffValue::ResRef(self.on_client_enter),
        );
        upsert_field(
            &mut root,
            "Mod_OnClientLeav",
            GffValue::ResRef(self.on_client_leave),
        );
        upsert_field(
            &mut root,
            "Mod_OnActvtItem",
            GffValue::ResRef(self.on_activate_item),
        );
        upsert_field(
            &mut root,
            "Mod_OnAcquirItem",
            GffValue::ResRef(self.on_acquire_item),
        );
        upsert_field(
            &mut root,
            "Mod_OnUnAqreItem",
            GffValue::ResRef(self.on_unacquire_item),
        );
        upsert_field(
            &mut root,
            "Mod_OnPlrDeath",
            GffValue::ResRef(self.on_player_death),
        );
        upsert_field(
            &mut root,
            "Mod_OnPlrDying",
            GffValue::ResRef(self.on_player_dying),
        );
        upsert_field(
            &mut root,
            "Mod_OnSpawnBtnDn",
            GffValue::ResRef(self.on_spawn_btn_down),
        );
        upsert_field(
            &mut root,
            "Mod_OnPlrRest",
            GffValue::ResRef(self.on_player_rest),
        );
        upsert_field(
            &mut root,
            "Mod_OnPlrLvlUp",
            GffValue::ResRef(self.on_player_level_up),
        );
        upsert_field(
            &mut root,
            "Mod_OnEquipItem",
            GffValue::ResRef(self.on_equip_item),
        );

        // --- Area list ---
        let area_structs: Vec<GffStruct> = self
            .areas
            .iter()
            .map(|area| {
                let mut s = GffStruct::new(6);
                s.push_field("Area_Name", GffValue::ResRef(area.area_name));
                // Omit at the placeholder, not at zero. The read defaults an
                // absent `ObjectId` to `OBJECT_INVALID`, so comparing against
                // zero here would write the placeholder back onto every module
                // IFO that never carried the label.
                if area.object_id.is_valid() {
                    s.push_field("ObjectId", GffValue::UInt32(area.object_id.get()));
                }
                s
            })
            .collect();
        upsert_field(&mut root, "Mod_Area_list", GffValue::List(area_structs));

        // --- Expansion list ---
        let expansion_structs: Vec<GffStruct> = self
            .expansion_list
            .iter()
            .map(|exp| {
                let mut s = GffStruct::new(0);
                s.push_field(
                    "Expansion_Name",
                    GffValue::LocalizedString(exp.expansion_name.clone()),
                );
                s.push_field("Expansion_ID", GffValue::Int32(exp.expansion_id));
                s
            })
            .collect();
        upsert_field(
            &mut root,
            "Mod_Expan_List",
            GffValue::List(expansion_structs),
        );

        // --- Cutscene list ---
        let cutscene_structs: Vec<GffStruct> = self
            .cutscene_list
            .iter()
            .map(|cs| {
                let mut s = GffStruct::new(1);
                s.push_field("CutScene_Name", GffValue::ResRef(cs.cutscene_name));
                s.push_field("CutScene_ID", GffValue::UInt32(cs.cutscene_id));
                s
            })
            .collect();
        upsert_field(
            &mut root,
            "Mod_CutSceneList",
            GffValue::List(cutscene_structs),
        );

        // --- Player list ---
        if !self.player_list.is_empty() {
            let player_structs: Vec<GffStruct> = self
                .player_list
                .iter()
                .map(|p| {
                    let mut s = GffStruct::new(0);
                    s.push_field(
                        "Mod_CommntyName",
                        GffValue::String(p.community_name.clone()),
                    );
                    s.push_field(
                        "Mod_FirstName",
                        GffValue::LocalizedString(p.first_name.clone()),
                    );
                    s.push_field(
                        "Mod_LastName",
                        GffValue::LocalizedString(p.last_name.clone()),
                    );
                    s.push_field(
                        "Mod_IsPrimaryPlr",
                        GffValue::UInt8(u8::from(p.is_primary_player)),
                    );
                    s
                })
                .collect();
            upsert_field(&mut root, "Mod_PlayerList", GffValue::List(player_structs));
        }

        // --- Tokens ---
        if !self.tokens.is_empty() {
            let token_structs: Vec<GffStruct> = self
                .tokens
                .iter()
                .map(|t| {
                    let mut s = GffStruct::new(7);
                    s.push_field("Mod_TokensNumber", GffValue::UInt32(t.token_number));
                    s.push_field("Mod_TokensValue", GffValue::String(t.token_value.clone()));
                    s
                })
                .collect();
            upsert_field(&mut root, "Mod_Tokens", GffValue::List(token_structs));
        }

        Gff::new(*b"IFO ", root)
    }
}

/// Errors produced while reading or writing typed IFO data.
#[derive(Debug, Error)]
pub enum IfoError {
    /// Source file type is not supported by this parser.
    #[error("unsupported IFO file type: {0:?}")]
    UnsupportedFileType([u8; 4]),
    /// Underlying GFF parser/writer error.
    #[error(transparent)]
    Gff(#[from] GffBinaryError),
}

/// Reads typed IFO data from a reader at the current stream position.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader))
)]
pub fn read_ifo<R: Read>(reader: &mut R) -> Result<Ifo, IfoError> {
    let gff = read_gff(reader)?;
    Ifo::from_gff(&gff)
}

/// Reads typed IFO data directly from bytes.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(bytes), fields(bytes_len = bytes.len()))
)]
pub fn read_ifo_from_bytes(bytes: &[u8]) -> Result<Ifo, IfoError> {
    let gff = read_gff_from_bytes(bytes)?;
    Ifo::from_gff(&gff)
}

/// Writes typed IFO data to an output writer.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(writer, ifo))
)]
pub fn write_ifo<W: Write>(writer: &mut W, ifo: &Ifo) -> Result<(), IfoError> {
    let gff = ifo.to_gff();
    write_gff(writer, &gff)?;
    Ok(())
}

/// Serializes typed IFO data into a byte vector.
#[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip(ifo)))]
pub fn write_ifo_to_vec(ifo: &Ifo) -> Result<Vec<u8>, IfoError> {
    let mut cursor = Cursor::new(Vec::new());
    write_ifo(&mut cursor, ifo)?;
    Ok(cursor.into_inner())
}

/// IFO `Mod_Expan_List` list entry child schema.
static EXPANSION_LIST_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Expansion_Name",
        expected_type: GffType::LocalizedString,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Expansion_ID",
        expected_type: GffType::Int32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// IFO `Mod_CutSceneList` list entry child schema.
static CUTSCENE_LIST_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "CutScene_Name",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "CutScene_ID",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// IFO `Mod_Area_list` list entry child schema.
static AREA_LIST_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Area_Name",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "ObjectId",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// IFO `Mod_PlayerList` list entry child schema.
static PLAYER_LIST_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Mod_CommntyName",
        expected_type: GffType::String,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Mod_FirstName",
        expected_type: GffType::LocalizedString,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Mod_LastName",
        expected_type: GffType::LocalizedString,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Mod_IsPrimaryPlr",
        expected_type: GffType::UInt8,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// IFO `Mod_Tokens` list entry child schema.
static TOKENS_LIST_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Mod_TokensNumber",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Mod_TokensValue",
        expected_type: GffType::String,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

impl GffSchema for Ifo {
    fn schema() -> &'static [FieldSchema] {
        static SCHEMA: &[FieldSchema] = &[
            // --- Module identity ---
            FieldSchema {
                label: "Mod_ID",
                expected_type: GffType::Binary,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Creator_ID",
                expected_type: GffType::Int32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Version",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Name",
                expected_type: GffType::LocalizedString,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Description",
                expected_type: GffType::LocalizedString,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Tag",
                expected_type: GffType::String,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_IsSaveGame",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_IsNWMFile",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_NWMResName",
                expected_type: GffType::String,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            // --- Entry point ---
            FieldSchema {
                label: "Mod_StartMovie",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Entry_Area",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Entry_X",
                expected_type: GffType::Single,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Entry_Y",
                expected_type: GffType::Single,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Entry_Z",
                expected_type: GffType::Single,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Entry_Dir_X",
                expected_type: GffType::Single,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Entry_Dir_Y",
                expected_type: GffType::Single,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            // --- Time / day-night ---
            FieldSchema {
                label: "Mod_MinPerHour",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_DawnHour",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_DuskHour",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_XPScale",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            // --- Save-game-only: calendar state ---
            FieldSchema {
                label: "Mod_StartYear",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_StartMonth",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_StartDay",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_StartHour",
                expected_type: GffType::UInt8,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Transition",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_StartMinute",
                expected_type: GffType::UInt16,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_StartSecond",
                expected_type: GffType::UInt16,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_StartMiliSec",
                expected_type: GffType::UInt16,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_PauseTime",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_PauseDay",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            // --- Save-game-only: ID counters ---
            FieldSchema {
                label: "Mod_Effect_NxtId",
                expected_type: GffType::UInt64,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_NextCharId0",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_NextCharId1",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_NextObjId0",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_NextObjId1",
                expected_type: GffType::UInt32,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            // --- Save-game-only: Mod_Hak ---
            FieldSchema {
                label: "Mod_Hak",
                expected_type: GffType::String,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            // --- Scripts (15 total, all ResRef) ---
            FieldSchema {
                label: "Mod_OnHeartbeat",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnUsrDefined",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnModLoad",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnModStart",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnClientEntr",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnClientLeav",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnActvtItem",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnAcquirItem",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnUnAqreItem",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnPlrDeath",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnPlrDying",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnSpawnBtnDn",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnPlrRest",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnPlrLvlUp",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "Mod_OnEquipItem",
                expected_type: GffType::ResRef,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            // --- Lists ---
            FieldSchema {
                label: "Mod_Expan_List",
                expected_type: GffType::List,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: Some(EXPANSION_LIST_CHILDREN),
                constraint: None,
            },
            FieldSchema {
                label: "Mod_CutSceneList",
                expected_type: GffType::List,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: Some(CUTSCENE_LIST_CHILDREN),
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Area_list",
                expected_type: GffType::List,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: Some(AREA_LIST_CHILDREN),
                constraint: None,
            },
            FieldSchema {
                label: "Mod_PlayerList",
                expected_type: GffType::List,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: Some(PLAYER_LIST_CHILDREN),
                constraint: None,
            },
            FieldSchema {
                label: "Mod_Tokens",
                expected_type: GffType::List,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: Some(TOKENS_LIST_CHILDREN),
                constraint: None,
            },
            // --- Variable tables (save-game-only, standard pattern) ---
            FieldSchema {
                label: "SWVarTable",
                expected_type: GffType::Struct,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
            FieldSchema {
                label: "VarTable",
                expected_type: GffType::List,
                life: FieldLife::Live,
                required: false,
                absent: AbsentDefault::Unverified,
                children: None,
                constraint: None,
            },
        ];
        SCHEMA
    }
}

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

    /// Build a minimal IFO GFF for testing.
    fn make_test_ifo_gff() -> Gff {
        let mut root = GffStruct::new(-1);
        root.push_field("Mod_IsSaveGame", GffValue::UInt8(0));
        root.push_field("Mod_IsNWMFile", GffValue::UInt8(0));
        root.push_field("Mod_ID", GffValue::Binary(vec![0xAB; 32]));
        root.push_field("Mod_Creator_ID", GffValue::Int32(42));
        root.push_field("Mod_Version", GffValue::UInt32(3));
        root.push_field("Mod_Tag", GffValue::String("end_m01aa".into()));
        root.push_field(
            "Mod_Name",
            GffValue::LocalizedString(GffLocalizedString::new(StrRef::from_raw(42000))),
        );
        root.push_field(
            "Mod_Description",
            GffValue::LocalizedString(GffLocalizedString::new(StrRef::from_raw(42001))),
        );
        root.push_field("Mod_StartMovie", GffValue::resref_lit("leclogo"));
        root.push_field("Mod_Entry_Area", GffValue::resref_lit("m01aa"));
        root.push_field("Mod_Entry_X", GffValue::Single(10.5));
        root.push_field("Mod_Entry_Y", GffValue::Single(20.3));
        root.push_field("Mod_Entry_Z", GffValue::Single(0.0));
        root.push_field("Mod_Entry_Dir_X", GffValue::Single(0.0));
        root.push_field("Mod_Entry_Dir_Y", GffValue::Single(1.0));
        root.push_field("Mod_MinPerHour", GffValue::UInt8(2));
        root.push_field("Mod_DawnHour", GffValue::UInt8(6));
        root.push_field("Mod_DuskHour", GffValue::UInt8(18));
        root.push_field("Mod_XPScale", GffValue::UInt8(10));

        root.push_field("Mod_OnHeartbeat", GffValue::resref_lit("k_mod_hb"));
        root.push_field("Mod_OnUsrDefined", GffValue::resref_lit(""));
        root.push_field("Mod_OnModLoad", GffValue::resref_lit("k_mod_load"));
        root.push_field("Mod_OnModStart", GffValue::resref_lit("k_mod_start"));
        root.push_field("Mod_OnClientEntr", GffValue::resref_lit("k_mod_enter"));
        root.push_field("Mod_OnClientLeav", GffValue::resref_lit(""));
        root.push_field("Mod_OnActvtItem", GffValue::resref_lit("k_act_item"));
        root.push_field("Mod_OnAcquirItem", GffValue::resref_lit("k_acq_item"));
        root.push_field("Mod_OnUnAqreItem", GffValue::resref_lit(""));
        root.push_field("Mod_OnPlrDeath", GffValue::resref_lit("k_plr_death"));
        root.push_field("Mod_OnPlrDying", GffValue::resref_lit("k_plr_dying"));
        root.push_field("Mod_OnSpawnBtnDn", GffValue::resref_lit(""));
        root.push_field("Mod_OnPlrRest", GffValue::resref_lit("k_plr_rest"));
        root.push_field("Mod_OnPlrLvlUp", GffValue::resref_lit(""));
        root.push_field("Mod_OnEquipItem", GffValue::resref_lit(""));

        // Area list with two areas.
        let mut a1 = GffStruct::new(6);
        a1.push_field("Area_Name", GffValue::resref_lit("m01aa"));
        let mut a2 = GffStruct::new(6);
        a2.push_field("Area_Name", GffValue::resref_lit("m01ab"));
        root.push_field("Mod_Area_list", GffValue::List(vec![a1, a2]));

        // Empty expansion and cutscene lists.
        root.push_field("Mod_Expan_List", GffValue::List(Vec::new()));
        root.push_field("Mod_CutSceneList", GffValue::List(Vec::new()));

        Gff::new(*b"IFO ", root)
    }

    /// Build a save-game IFO GFF with all fields populated.
    fn make_save_game_ifo_gff() -> Gff {
        let mut gff = make_test_ifo_gff();
        // Flip save-game flag.
        for field in &mut gff.root.fields {
            if field.label == "Mod_IsSaveGame" {
                field.value = GffValue::UInt8(1);
            }
        }

        // Save-game calendar state.
        gff.root.push_field("Mod_StartYear", GffValue::UInt32(1340));
        gff.root.push_field("Mod_StartMonth", GffValue::UInt8(6));
        gff.root.push_field("Mod_StartDay", GffValue::UInt8(1));
        gff.root.push_field("Mod_StartHour", GffValue::UInt8(23));
        gff.root.push_field("Mod_StartMinute", GffValue::UInt16(30));
        gff.root.push_field("Mod_StartSecond", GffValue::UInt16(15));
        gff.root
            .push_field("Mod_StartMiliSec", GffValue::UInt16(500));
        gff.root.push_field("Mod_Transition", GffValue::UInt32(1));
        gff.root.push_field("Mod_PauseTime", GffValue::UInt32(1000));
        gff.root.push_field("Mod_PauseDay", GffValue::UInt32(5));

        // ID counters.
        gff.root
            .push_field("Mod_Effect_NxtId", GffValue::UInt64(999));
        gff.root.push_field("Mod_NextCharId0", GffValue::UInt32(10));
        gff.root.push_field("Mod_NextCharId1", GffValue::UInt32(20));
        gff.root.push_field("Mod_NextObjId0", GffValue::UInt32(100));
        gff.root.push_field("Mod_NextObjId1", GffValue::UInt32(200));

        // Hak.
        gff.root
            .push_field("Mod_Hak", GffValue::String("my_hak".into()));

        // Area with ObjectId.
        gff.root.fields.retain(|f| f.label != "Mod_Area_list");
        let mut a1 = GffStruct::new(6);
        a1.push_field("Area_Name", GffValue::resref_lit("m01aa"));
        a1.push_field("ObjectId", GffValue::UInt32(0x7F00_0001));
        gff.root
            .push_field("Mod_Area_list", GffValue::List(vec![a1]));

        // Player list.
        let mut player = GffStruct::new(0);
        player.push_field("Mod_CommntyName", GffValue::String("TestPlayer".into()));
        use rakata_formats::GffLocalizedSubstring;
        let first = GffLocalizedString {
            string_ref: StrRef::invalid(),
            substrings: vec![GffLocalizedSubstring {
                string_id: 0,
                text: "Revan".into(),
            }],
        };
        player.push_field("Mod_FirstName", GffValue::LocalizedString(first));
        player.push_field(
            "Mod_LastName",
            GffValue::LocalizedString(GffLocalizedString::new(StrRef::invalid())),
        );
        player.push_field("Mod_IsPrimaryPlr", GffValue::UInt8(1));
        gff.root
            .push_field("Mod_PlayerList", GffValue::List(vec![player]));

        // Tokens.
        let mut token = GffStruct::new(7);
        token.push_field("Mod_TokensNumber", GffValue::UInt32(0));
        token.push_field("Mod_TokensValue", GffValue::String("Revan".into()));
        gff.root
            .push_field("Mod_Tokens", GffValue::List(vec![token]));

        // Expansion list.
        gff.root.fields.retain(|f| f.label != "Mod_Expan_List");
        let mut exp = GffStruct::new(0);
        exp.push_field(
            "Expansion_Name",
            GffValue::LocalizedString(GffLocalizedString::new(StrRef::from_raw(100))),
        );
        exp.push_field("Expansion_ID", GffValue::Int32(1));
        gff.root
            .push_field("Mod_Expan_List", GffValue::List(vec![exp]));

        // Cutscene list.
        gff.root.fields.retain(|f| f.label != "Mod_CutSceneList");
        let mut cs = GffStruct::new(1);
        cs.push_field("CutScene_Name", GffValue::resref_lit("cs_intro"));
        cs.push_field("CutScene_ID", GffValue::UInt32(0));
        gff.root
            .push_field("Mod_CutSceneList", GffValue::List(vec![cs]));

        gff
    }

    #[test]
    fn reads_core_ifo_fields() {
        let gff = make_test_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert_eq!(ifo.tag, "end_m01aa");
        assert_eq!(ifo.name.string_ref.raw(), 42000);
        assert_eq!(ifo.description.string_ref.raw(), 42001);
        assert_eq!(ifo.start_movie, "leclogo");
        assert_eq!(ifo.entry_area, "m01aa");
        assert_eq!(ifo.entry_x, 10.5);
        assert_eq!(ifo.entry_y, 20.3);
        assert_eq!(ifo.entry_z, 0.0);
        assert_eq!(ifo.entry_dir_x, 0.0);
        assert_eq!(ifo.entry_dir_y, 1.0);
        assert_eq!(ifo.min_per_hour, 2);
        assert_eq!(ifo.dawn_hour, 6);
        assert_eq!(ifo.dusk_hour, 18);
        assert_eq!(ifo.xp_scale, 10);
    }

    #[test]
    fn reads_root_identity_fields() {
        let gff = make_test_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert!(!ifo.is_save_game);
        assert!(!ifo.is_nwm_file);
        assert!(ifo.nwm_res_name.is_empty());
        assert_eq!(ifo.module_id, vec![0xAB; 32]);
        assert_eq!(ifo.creator_id, 42);
        assert_eq!(ifo.version, 3);
    }

    #[test]
    fn a_module_id_of_any_length_survives_a_round_trip() {
        // Vanilla `module.ifo` carries 16 bytes here and a savegame carries
        // 32. Requiring one length replaced the other with zeros, silently,
        // on every vanilla module in the game.
        for length in [0, 1, 15, 16, 17, 31, 32, 33, 64] {
            let mut root = GffStruct::new(-1);
            root.push_field("Mod_ID", GffValue::Binary(vec![0xCD; length]));
            let ifo = Ifo::from_gff(&Gff::new(*b"IFO ", root)).expect("must parse");

            assert_eq!(
                ifo.module_id,
                vec![0xCD; length],
                "a {length}-byte Mod_ID must survive the read"
            );
            assert_eq!(
                Ifo::from_gff(&ifo.to_gff()).expect("must parse").module_id,
                vec![0xCD; length],
                "a {length}-byte Mod_ID must survive the write"
            );
        }
    }

    #[test]
    fn reads_scripts() {
        let gff = make_test_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert_eq!(ifo.on_heartbeat, "k_mod_hb");
        assert_eq!(ifo.on_user_defined, "");
        assert_eq!(ifo.on_mod_load, "k_mod_load");
        assert_eq!(ifo.on_mod_start, "k_mod_start");
        assert_eq!(ifo.on_client_enter, "k_mod_enter");
        assert_eq!(ifo.on_client_leave, "");
        assert_eq!(ifo.on_activate_item, "k_act_item");
        assert_eq!(ifo.on_acquire_item, "k_acq_item");
        assert_eq!(ifo.on_unacquire_item, "");
        assert_eq!(ifo.on_player_death, "k_plr_death");
        assert_eq!(ifo.on_player_dying, "k_plr_dying");
        assert_eq!(ifo.on_spawn_btn_down, "");
        assert_eq!(ifo.on_player_rest, "k_plr_rest");
        assert_eq!(ifo.on_player_level_up, "");
        assert_eq!(ifo.on_equip_item, "");
    }

    #[test]
    fn reads_area_list() {
        let gff = make_test_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert_eq!(ifo.areas.len(), 2);
        assert_eq!(ifo.areas[0].area_name, "m01aa");
        // Absent, so the placeholder rather than object zero. This test
        // asserted `0` while the reader defaulted there, which is a test and
        // an implementation sharing one mistake rather than confirming each
        // other.
        assert_eq!(ifo.areas[0].object_id, ObjectId::INVALID);
        assert_eq!(ifo.areas[1].area_name, "m01ab");
        assert_eq!(ifo.areas[1].object_id, ObjectId::INVALID);
    }

    #[test]
    fn reads_save_game_fields() {
        let gff = make_save_game_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert!(ifo.is_save_game);
        assert_eq!(ifo.start_year, 1340);
        assert_eq!(ifo.start_month, 6);
        assert_eq!(ifo.start_day, 1);
        assert_eq!(ifo.start_hour, 23);
        assert_eq!(ifo.start_minute, 30);
        assert_eq!(ifo.start_second, 15);
        assert_eq!(ifo.start_millisecond, 500);
        assert_eq!(ifo.transition, 1);
        assert_eq!(ifo.pause_time, 1000);
        assert_eq!(ifo.pause_day, 5);
        assert_eq!(ifo.effect_next_id, 999);
        assert_eq!(ifo.next_char_id_0, 10);
        assert_eq!(ifo.next_char_id_1, 20);
        assert_eq!(ifo.next_obj_id_0, 100);
        assert_eq!(ifo.next_obj_id_1, 200);
        assert_eq!(ifo.hak, "my_hak");
    }

    #[test]
    fn reads_area_object_id() {
        let gff = make_save_game_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert_eq!(ifo.areas.len(), 1);
        assert_eq!(ifo.areas[0].area_name, "m01aa");
        assert_eq!(ifo.areas[0].object_id, ObjectId::new(0x7F00_0001));
    }

    #[test]
    fn reads_player_list() {
        let gff = make_save_game_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert_eq!(ifo.player_list.len(), 1);
        assert_eq!(ifo.player_list[0].community_name, "TestPlayer");
        assert!(ifo.player_list[0].is_primary_player);
        assert_eq!(ifo.player_list[0].first_name.substrings[0].text, "Revan");
    }

    #[test]
    fn reads_tokens() {
        let gff = make_save_game_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert_eq!(ifo.tokens.len(), 1);
        assert_eq!(ifo.tokens[0].token_number, 0);
        assert_eq!(ifo.tokens[0].token_value, "Revan");
    }

    #[test]
    fn reads_expansion_list() {
        let gff = make_save_game_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert_eq!(ifo.expansion_list.len(), 1);
        assert_eq!(ifo.expansion_list[0].expansion_name.string_ref.raw(), 100);
        assert_eq!(ifo.expansion_list[0].expansion_id, 1);
    }

    #[test]
    fn reads_cutscene_list() {
        let gff = make_save_game_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        assert_eq!(ifo.cutscene_list.len(), 1);
        assert_eq!(ifo.cutscene_list[0].cutscene_name, "cs_intro");
        assert_eq!(ifo.cutscene_list[0].cutscene_id, 0);
    }

    #[test]
    fn all_fields_survive_typed_roundtrip() {
        let gff = make_save_game_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("typed parse");
        let bytes = write_ifo_to_vec(&ifo).expect("write succeeds");
        let reparsed = read_ifo_from_bytes(&bytes).expect("reparse succeeds");

        assert_eq!(ifo, reparsed);
    }

    #[test]
    fn typed_edits_roundtrip_through_gff_writer() {
        let gff = make_test_ifo_gff();
        let mut ifo = Ifo::from_gff(&gff).expect("must parse");
        ifo.tag = "end_m01ab".into();
        ifo.entry_area = ResRef::new("m01ab").expect("valid test resref");
        ifo.entry_x = 50.0;
        ifo.areas.push(IfoArea {
            area_name: ResRef::new("m01ac").expect("valid test resref"),
            object_id: ObjectId::new(0),
        });

        let bytes = write_ifo_to_vec(&ifo).expect("write succeeds");
        let reparsed = read_ifo_from_bytes(&bytes).expect("reparse succeeds");

        assert_eq!(reparsed.tag, "end_m01ab");
        assert_eq!(reparsed.entry_area, "m01ab");
        assert_eq!(reparsed.entry_x, 50.0);
        assert_eq!(reparsed.areas.len(), 3);
        assert_eq!(reparsed.areas[2].area_name, "m01ac");
    }

    #[test]
    fn read_ifo_from_reader_matches_bytes_path() {
        let gff = make_test_ifo_gff();
        let bytes = {
            let mut c = Cursor::new(Vec::new());
            write_gff(&mut c, &gff).expect("test fixture must be valid");
            c.into_inner()
        };

        let mut cursor = Cursor::new(&bytes);
        let via_reader = read_ifo(&mut cursor).expect("reader parse succeeds");
        let via_bytes = read_ifo_from_bytes(&bytes).expect("bytes parse succeeds");

        assert_eq!(via_reader, via_bytes);
    }

    #[test]
    fn rejects_non_ifo_file_type() {
        let mut gff = make_test_ifo_gff();
        gff.file_type = *b"UTT ";

        let err = Ifo::from_gff(&gff).expect_err("UTT must be rejected as IFO input");
        assert!(matches!(
            err,
            IfoError::UnsupportedFileType(file_type) if file_type == *b"UTT "
        ));
    }

    #[test]
    fn write_ifo_matches_direct_gff_writer() {
        let gff = make_test_ifo_gff();
        let ifo = Ifo::from_gff(&gff).expect("must parse");

        let via_typed = write_ifo_to_vec(&ifo).expect("typed write succeeds");

        let mut direct = Cursor::new(Vec::new());
        write_gff(&mut direct, &ifo.to_gff()).expect("direct write succeeds");

        assert_eq!(via_typed, direct.into_inner());
    }

    #[test]
    fn empty_area_list_ok() {
        let mut gff = make_test_ifo_gff();
        gff.root.fields.retain(|f| f.label != "Mod_Area_list");

        let ifo = Ifo::from_gff(&gff).expect("must parse");
        assert!(ifo.areas.is_empty());
    }

    #[test]
    fn schema_field_count() {
        assert_eq!(Ifo::schema().len(), 58);
    }

    #[test]
    fn schema_no_duplicate_labels() {
        let schema = Ifo::schema();
        let mut labels: Vec<&str> = schema.iter().map(|f| f.label).collect();
        labels.sort();
        let before = labels.len();
        labels.dedup();
        assert_eq!(before, labels.len(), "duplicate labels in IFO schema");
    }

    #[test]
    fn schema_lists_have_children() {
        let schema = Ifo::schema();
        let expan = schema
            .iter()
            .find(|f| f.label == "Mod_Expan_List")
            .expect("test fixture must be valid");
        assert_eq!(expan.children.expect("test fixture must be valid").len(), 2);
        let cutscene = schema
            .iter()
            .find(|f| f.label == "Mod_CutSceneList")
            .expect("test fixture must be valid");
        assert_eq!(
            cutscene.children.expect("test fixture must be valid").len(),
            2
        );
        let area = schema
            .iter()
            .find(|f| f.label == "Mod_Area_list")
            .expect("test fixture must be valid");
        assert_eq!(area.children.expect("test fixture must be valid").len(), 2);
        let player = schema
            .iter()
            .find(|f| f.label == "Mod_PlayerList")
            .expect("test fixture must be valid");
        assert_eq!(
            player.children.expect("test fixture must be valid").len(),
            4
        );
        let tokens = schema
            .iter()
            .find(|f| f.label == "Mod_Tokens")
            .expect("test fixture must be valid");
        assert_eq!(
            tokens.children.expect("test fixture must be valid").len(),
            2
        );
    }

    #[test]
    fn nwm_res_name_only_read_when_nwm_file() {
        let mut gff = make_test_ifo_gff();
        gff.root
            .push_field("Mod_NWMResName", GffValue::String("some_nwm".into()));

        // With IsNWMFile=0, nwm_res_name should be empty.
        let ifo = Ifo::from_gff(&gff).expect("must parse");
        assert!(ifo.nwm_res_name.is_empty());

        // Set IsNWMFile=1.
        for field in &mut gff.root.fields {
            if field.label == "Mod_IsNWMFile" {
                field.value = GffValue::UInt8(1);
            }
        }
        let ifo = Ifo::from_gff(&gff).expect("must parse");
        assert_eq!(ifo.nwm_res_name, "some_nwm");
    }
}