rakata_generics/

git.rs

//! GIT (`.git`) typed generic wrapper.
//!
//! GIT (Game Instance Template) resources are GFF-backed area instance data.
//! Each area has one GIT that holds positioned object instances (creatures,
//! items, doors, placeables, waypoints, sounds, triggers, stores, encounters,
//! area effects), area-level properties (music, ambient sounds, stealth XP),
//! and a camera list.
//!
//! ## Scope
//! - Typed access for all 10 instance list types with position/orientation.
//! - Typed `AreaProperties` with music, ambient sound, and stealth XP fields.
//! - Typed camera list with Position (Vector3) and Orientation (Quaternion).
//! - Full typed roundtrip for all engine-read fields.

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

use rakata_formats::gff::{upsert_field, GffLabel};
use rakata_formats::gff_label;
use rakata_formats::schema::FromGff;
use rakata_formats::schema::GffScalar;
use rakata_formats::GENERIC_FILE_TYPE;
use rakata_formats::{
    read_gff, read_gff_from_bytes, write_gff, Gff, GffBinaryError, GffModel, GffStruct, GffValue,
};
use thiserror::Error;

use crate::shared::ObjectId;

use crate::git::creature::SavedCreature;
use crate::git::door::SavedDoor;
use crate::git::item::SavedItem;
use crate::git::placeable::SavedPlaceable;
use crate::git::sound::SavedSound;
use crate::git::store::SavedStore;
use crate::git::trigger::SavedTrigger;
pub mod area_effect;
pub mod area_properties;
pub mod blocks;
pub mod camera;
pub mod creature;
pub mod door;
pub mod encounter;
pub mod item;
pub mod placeable;
pub mod sound;
pub mod store;
pub mod trigger;
pub mod waypoint;

pub use area_effect::{GitAreaEffect, GitAreaEffectShape};
pub use area_properties::GitAreaProperties;
pub use camera::GitCamera;
pub use creature::GitCreature;
pub use creature::GitCreatureCommon;
pub use door::GitDoor;
pub use door::GitDoorCommon;
pub use encounter::{GitEncounter, GitEncounterPoint, GitSpawnPoint};
pub use item::GitItem;
pub use placeable::GitPlaceable;
pub use placeable::GitPlaceableCommon;
pub use sound::GitSound;
pub use sound::GitSoundCommon;
pub use store::GitStore;
pub use trigger::GitTrigger;
pub use trigger::GitTriggerCommon;
pub use waypoint::{GitMapNote, GitWaypoint};

// =========================================================================
// Instance sub-types
// =========================================================================

/// The two forms an object list in a `GIT` can take.
///
/// `UseTemplates` decides which, for every object list at once: `1` in a
/// module's static `.git`, `0` inside a save. What each setting changes about
/// how an element is read, and what a missing field falls back to, is in
/// `docs/src/formats/save/index.md`.
///
/// The flag is not kept as a separate field on [`Git`], because it describes
/// exactly this choice and storing both would let them disagree.
///
/// # Three lists are not one of these
///
/// Waypoints, because `LoadWaypoints` ignores `UseTemplates` and always
/// reads inline data, so there is nothing to select between. Area effects,
/// because no loader in the binary opens a template for one, so that list is
/// only ever the saved form. Encounters, because their saved field set is
/// not modelled yet; see [`Git::encounters`] for why.
#[derive(Debug, Clone, PartialEq)]
pub enum GitObjects<S, T> {
    /// `UseTemplates = 1`: sparse placements referencing blueprints.
    Static(Vec<S>),
    /// `UseTemplates = 0`: full snapshots, as a savegame stores them.
    Saved(Vec<T>),
}

impl<S, T> Default for GitObjects<S, T> {
    /// Matches the engine's loader default of `0` for an absent
    /// `UseTemplates`.
    fn default() -> Self {
        Self::Saved(Vec::new())
    }
}

impl<S, T> GitObjects<S, T> {
    /// Returns whether this list references blueprints rather than carrying
    /// snapshots, which is what `UseTemplates` records.
    pub fn uses_templates(&self) -> bool {
        matches!(self, Self::Static(_))
    }

    /// Returns the number of entries, whichever form they take.
    pub fn len(&self) -> usize {
        match self {
            Self::Static(entries) => entries.len(),
            Self::Saved(entries) => entries.len(),
        }
    }

    /// Returns whether the list holds no entries.
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Returns the static placements, or `None` when the list is saved content.
    pub fn as_static(&self) -> Option<&[S]> {
        match self {
            Self::Static(entries) => Some(entries),
            Self::Saved(_) => None,
        }
    }

    /// Returns the saved snapshots, or `None` when the list is static content.
    pub fn as_saved(&self) -> Option<&[T]> {
        match self {
            Self::Saved(entries) => Some(entries),
            Self::Static(_) => None,
        }
    }

    /// Mutable view of the static placements, or `None` for saved content.
    pub fn as_static_mut(&mut self) -> Option<&mut Vec<S>> {
        match self {
            Self::Static(entries) => Some(entries),
            Self::Saved(_) => None,
        }
    }

    /// Mutable view of the saved snapshots, or `None` for static content.
    pub fn as_saved_mut(&mut self) -> Option<&mut Vec<T>> {
        match self {
            Self::Saved(entries) => Some(entries),
            Self::Static(_) => None,
        }
    }
}

/// A `Creature List` in either of its two forms.
pub type GitCreatures = GitObjects<GitCreature, SavedCreature>;

/// A `Door List` in either of its two forms.
pub type GitDoors = GitObjects<GitDoor, SavedDoor>;

/// A `Placeable List` in either of its two forms.
pub type GitPlaceables = GitObjects<GitPlaceable, SavedPlaceable>;

/// A `List` of loose area items in either of its two forms.
pub type GitItems = GitObjects<GitItem, SavedItem>;

/// A `SoundList` in either of its two forms.
pub type GitSounds = GitObjects<GitSound, SavedSound>;

/// A `StoreList` in either of its two forms.
pub type GitStores = GitObjects<GitStore, SavedStore>;

/// A `TriggerList` in either of its two forms.
pub type GitTriggers = GitObjects<GitTrigger, SavedTrigger>;

// =========================================================================
// Non-instance sub-types
// =========================================================================

// =========================================================================
// Root GIT struct
// =========================================================================

/// The bitmap payload, named so the entry can reach its GFF mapping.
type AreaMapBytes = Vec<u8>;

/// The area's explored-map bitmap, which the view declares and does not model.
///
/// Four labels with no member: the bitmap is save state a projection has
/// nothing to say about, and leaving them out would make an unrecognised
/// field check fire on a correct save.
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_entry(AreaMapResX, wire = i32, unexamined)]
#[gff_entry(AreaMapResY, wire = i32, unexamined)]
#[gff_entry(AreaMapDataSize, wire = u32, unexamined)]
#[gff_entry(AreaMapData, wire = AreaMapBytes, unexamined)]
pub struct GitAreaMap {}

/// Typed GIT model built from/to [`Gff`] data.
///
/// GIT is the area instance container. It places object instances by
/// referencing templates and providing position/orientation data. All
/// engine-read fields are typed; roundtrip is fully lossless for typed
/// fields.
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_entry(UseTemplates, wire = u8, stamped)]
#[gff_entry(VarTable, container = list, unexamined)]
pub struct Git {
    /// The explored-map bitmap (`AreaMap`), declared and not modelled.
    ///
    /// Save-only. `AreaMapData` appears in every save fixture and in no
    /// module GIT the install ships, so writing the block unconditionally
    /// would put an explored map on an area nobody has walked.
    #[gff(AreaMap, unexamined, nested = GitAreaMap, optional)]
    pub area_map: Option<GitAreaMap>,
    /// Current weather (`CurrentWeather`). If area is an interior, engine forcibly overrides to 0xFF.
    #[gff(CurrentWeather, unexamined)]
    pub current_weather: u8,
    /// Weather started flag (`WeatherStarted`). If area is an interior, engine forcibly overrides to 0 (false).
    #[gff(WeatherStarted, unexamined)]
    pub weather_started: bool,
    /// Waypoint instances (`WaypointList`).
    #[gff(WaypointList, not_a_constant, list = GitWaypoint, element_id = 5)]
    pub waypoints: Vec<GitWaypoint>,
    /// Encounter instances (`Encounter List`).
    ///
    /// Read as static placements whatever `UseTemplates` says, which is
    /// wrong for a savegame `GIT`: a saved encounter comes back with an
    /// empty `TemplateResRef` rather than its spawned state. Encounters are
    /// the one object list still in that position. They are held back
    /// because there is nothing to model them against: every save in
    /// `fixtures/saves/` has an empty `Encounter List`, and unlike area
    /// effects the engine's saved encounter field set is not written down in
    /// `docs/src/formats/gff/git.md` either. Modelling it from `LoadEncounters`
    /// alone would ship a field set with no way to check it.
    #[gff("Encounter List", not_a_constant, list = GitEncounter, element_id = 7)]
    pub encounters: Vec<GitEncounter>,
    /// Area-of-effect instances (`AreaEffectList`).
    #[gff(AreaEffectList, not_a_constant, list = GitAreaEffect, element_id = 13)]
    pub area_effects: Vec<GitAreaEffect>,
    /// Area-level properties (`AreaProperties`).
    #[gff(AreaProperties, unexamined, nested = GitAreaProperties, optional)]
    pub area_properties: Option<GitAreaProperties>,
    /// Static cameras (`CameraList`). Engine load failure occurs if array contains 51 or more entries.
    #[gff(
        CameraList,
        not_a_constant,
        list = GitCamera,
        element_id = unenforced(
            14,
            "LoadPlaceableCameras walks the list by position and takes each field \
             by label, so nothing tests an element's id. Every vanilla file writes \
             14 and there is no reason to write anything else; what that loader \
             does check is the list's total length"
        )
    )]
    pub cameras: Vec<GitCamera>,
    /// Creature List instances, in whichever form the file uses.
    #[gff(
        "Creature List",
        live,
        not_a_constant,
        list = GitCreatureCommon,
        split = UseTemplates(GitCreature, SavedCreature),
        element_id = 4,
        manual_read,
        manual_write
    )]
    pub creatures: GitCreatures,
    /// List instances, in whichever form the file uses.
    #[gff(
        List,
        not_a_constant,
        list = GitObjectPlacement,
        split = UseTemplates(GitItem, SavedItem),
        element_id = 0,
        manual_read,
        manual_write
    )]
    pub items: GitItems,
    /// Door List instances, in whichever form the file uses.
    #[gff(
        "Door List",
        not_a_constant,
        list = GitDoorCommon,
        split = UseTemplates(GitDoor, SavedDoor),
        element_id = 8,
        manual_read,
        manual_write
    )]
    pub doors: GitDoors,
    /// Placeable List instances, in whichever form the file uses.
    #[gff(
        "Placeable List",
        not_a_constant,
        list = GitPlaceableCommon,
        split = UseTemplates(GitPlaceable, SavedPlaceable),
        element_id = 9,
        manual_read,
        manual_write
    )]
    pub placeables: GitPlaceables,
    /// SoundList instances, in whichever form the file uses.
    #[gff(
        SoundList,
        not_a_constant,
        list = GitSoundCommon,
        split = UseTemplates(GitSound, SavedSound),
        element_id = 6,
        manual_read,
        manual_write
    )]
    pub sounds: GitSounds,
    /// TriggerList instances, in whichever form the file uses.
    #[gff(
        TriggerList,
        not_a_constant,
        list = GitTriggerCommon,
        split = UseTemplates(GitTrigger, SavedTrigger),
        element_id = 1,
        manual_read,
        manual_write
    )]
    pub triggers: GitTriggers,
    /// StoreList instances, in whichever form the file uses.
    #[gff(
        StoreList,
        not_a_constant,
        list = GitObjectPlacement,
        split = UseTemplates(GitStore, SavedStore),
        element_id = 11,
        manual_read,
        manual_write
    )]
    pub stores: GitStores,
}

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

    /// Builds typed GIT data from a parsed GFF container.
    ///
    /// # Errors
    ///
    /// Returns [`GitError::UnsupportedFileType`] when the container is not a
    /// `GIT ` or a bare `GFF `.
    pub fn from_gff(gff: &Gff) -> Result<Self, GitError> {
        if gff.file_type != <Git as FromGff>::MAGIC && gff.file_type != GENERIC_FILE_TYPE {
            return Err(GitError::UnsupportedFileType(gff.file_type));
        }
        let root = &gff.root;

        // One resolution for every object list, from the struct they all sit
        // on. The selector is a sibling of the lists rather than a field of an
        // element, which is why no element reader takes a form parameter.
        let templated = root
            .field("UseTemplates")
            .and_then(<bool as GffScalar>::from_gff_value)
            .unwrap_or(false);

        Ok(Self {
            creatures: read_objects(root, "Creature List", templated),
            items: read_objects(root, "List", templated),
            doors: read_objects(root, "Door List", templated),
            placeables: read_objects(root, "Placeable List", templated),
            sounds: read_objects(root, "SoundList", templated),
            triggers: read_objects(root, "TriggerList", templated),
            stores: read_objects(root, "StoreList", templated),
            ..Self::read_declared(root)
        })
    }

    /// Converts this typed GIT value into a GFF container.
    pub fn to_gff(&self) -> Gff {
        let mut root = GffStruct::new(-1);
        self.write_declared(&mut root);

        // Derived from the lists rather than held beside them, so the flag
        // and the contents cannot disagree. A static module `.git` sets it; a
        // savegame omits it, because the engine's own writer never emits one
        // and its loader defaults to clear.
        if self.creatures.uses_templates() {
            upsert_field(&mut root, gff_label!("UseTemplates"), GffValue::UInt8(1));
        }

        write_objects(&mut root, gff_label!("Creature List"), &self.creatures, 4);
        write_objects(&mut root, gff_label!("List"), &self.items, 0);
        write_objects(&mut root, gff_label!("Door List"), &self.doors, 8);
        write_objects(&mut root, gff_label!("Placeable List"), &self.placeables, 9);
        write_objects(&mut root, gff_label!("SoundList"), &self.sounds, 6);
        write_objects(&mut root, gff_label!("TriggerList"), &self.triggers, 1);
        write_objects(&mut root, gff_label!("StoreList"), &self.stores, 11);

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

/// Reads one object list in whichever form the selector chose.
///
/// The arms are separate types, so the read is one branch and then the
/// ordinary element read on whichever side it landed.
fn read_objects<S, T>(root: &GffStruct, label: &str, templated: bool) -> GitObjects<S, T>
where
    S: GitElement,
    T: GitElement,
{
    let Some(GffValue::List(elements)) = root.field(label) else {
        return if templated {
            GitObjects::Static(Vec::new())
        } else {
            GitObjects::Saved(Vec::new())
        };
    };
    if templated {
        GitObjects::Static(elements.iter().map(S::read).collect())
    } else {
        GitObjects::Saved(elements.iter().map(T::read).collect())
    }
}

/// Writes one object list, stamping the id its loader tests against.
fn write_objects<S, T>(root: &mut GffStruct, label: GffLabel, objects: &GitObjects<S, T>, id: i32)
where
    S: GitElement,
    T: GitElement,
{
    let elements: Vec<GffStruct> = match objects {
        GitObjects::Static(entries) => entries.iter().map(|e| e.write(id)).collect(),
        GitObjects::Saved(entries) => entries.iter().map(|e| e.write(id)).collect(),
    };
    upsert_field(root, label, GffValue::List(elements));
}

/// One arm's element codec, so a list can read or write either side without
/// naming which.
///
/// Both halves are what the derive already generates for a list element; this
/// only gives the two arms one name so the list can be generic over them.
pub trait GitElement: Sized {
    /// Reads one element.
    fn read(structure: &GffStruct) -> Self;
    /// Writes one element into a struct carrying the list's own id.
    fn write(&self, id: i32) -> GffStruct;
}

/// Where an item entry or a store entry sits, whichever form the entry takes.
///
/// One type for two lists rather than one each: the sets are the same, they
/// agree on every audited axis, and the declarations the extraction produced
/// for them are identical. A later measurement that parts them breaks the
/// share rather than quietly answering for the wrong list.
///
/// `ObjectId` is deliberately not here, because it is not shared: every
/// saved form carries it, no static form does, and the party stash carries it
/// on none of its items. It is declared by the saved arms instead, so a list
/// that has no runtime id does not gain one on the way back out.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct GitObjectPlacement {
    /// Runtime object id (`ObjectId`), which not every list carries.
    ///
    /// `None` where the file has no label, which is the state the six fields
    /// below never reach: they are on every element of every list measured and
    /// this one is not. Static forms carry it nowhere, and among saved forms
    /// the party's shared stash carries it on none of its items while every
    /// other item list carries it on all of theirs.
    ///
    /// Held as the absence rather than resolved to a value because writing it
    /// back is what the resolution would cost. The engine's own answer for an
    /// absent label is on the schema entry beside this one, and it is
    /// `INVALID` rather than zero.
    #[gff(ObjectId, stamped = ObjectId::INVALID, optional = ObjectId)]
    pub object_id: Option<ObjectId>,
    /// X position (`XPosition`).
    #[gff(XPosition, unexamined)]
    pub x_position: f32,
    /// Y position (`YPosition`).
    #[gff(YPosition, unexamined)]
    pub y_position: f32,
    /// Z position (`ZPosition`).
    #[gff(ZPosition, unexamined)]
    pub z_position: f32,
    /// X orientation (`XOrientation`).
    #[gff(XOrientation, unexamined)]
    pub x_orientation: f32,
    /// Y orientation (`YOrientation`).
    #[gff(YOrientation, unexamined)]
    pub y_orientation: f32,
    /// Z orientation (`ZOrientation`).
    /// Z orientation (`ZOrientation`), which only a saved form carries.
    ///
    /// The same two-versus-three split the creature block has: a static item or
    /// store placement carries `XOrientation` and `YOrientation` and no third,
    /// and every saved one carries all three.
    #[gff(ZOrientation, unexamined, optional = f32)]
    pub z_orientation: Option<f32>,
}

/// Every arm type, each reaching the pair its own derive supplied.
macro_rules! git_element {
    ($($ty:ty),* $(,)?) => {$(
        impl GitElement for $ty {
            fn read(structure: &GffStruct) -> Self {
                <$ty>::read_element(structure)
            }

            fn write(&self, id: i32) -> GffStruct {
                let mut element = GffStruct::new(id);
                <$ty>::write_element(self, &mut element);
                element
            }
        }
    )*};
}

git_element!(
    GitCreature,
    SavedCreature,
    GitItem,
    SavedItem,
    GitDoor,
    SavedDoor,
    GitPlaceable,
    SavedPlaceable,
    GitSound,
    SavedSound,
    GitTrigger,
    SavedTrigger,
    GitStore,
    SavedStore,
);

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

/// Reads typed GIT data from a reader at the current stream position.
///
/// # Errors
///
/// [`GitError::Gff`] when the stream is not a readable GFF, and
/// [`GitError::UnsupportedFileType`] when it is a GFF of some other format,
/// carrying the fourcc that was found.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader))
)]
pub fn read_git<R: Read>(reader: &mut R) -> Result<Git, GitError> {
    let gff = read_gff(reader)?;
    Git::from_gff(&gff)
}

/// Reads typed GIT data directly from bytes.
///
/// # Errors
///
/// [`GitError::Gff`] when `bytes` are not a readable GFF, and
/// [`GitError::UnsupportedFileType`] when they are a GFF of some other format,
/// carrying the fourcc that was found.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(bytes), fields(bytes_len = bytes.len()))
)]
pub fn read_git_from_bytes(bytes: &[u8]) -> Result<Git, GitError> {
    let gff = read_gff_from_bytes(bytes)?;
    Git::from_gff(&gff)
}

/// Authors the GIT file the typed view describes, into a writer.
///
/// # Errors
///
/// [`GitError::Gff`] when the writer fails or a value will not encode. The
/// typed view fixes the file type, so `UnsupportedFileType` cannot arise on
/// this side.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(writer, git))
)]
pub fn author_git<W: Write>(writer: &mut W, git: &Git) -> Result<(), GitError> {
    let gff = git.to_gff();
    write_gff(writer, &gff)?;
    Ok(())
}

/// Authors the GIT file the typed view describes, as bytes.
///
/// # Errors
///
/// [`GitError::Gff`] when a value will not encode. Writing into a `Vec` has no
/// I/O to fail at.
#[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip(git)))]
pub fn author_git_to_vec(git: &Git) -> Result<Vec<u8>, GitError> {
    let mut cursor = Cursor::new(Vec::new());
    author_git(&mut cursor, git)?;
    Ok(cursor.into_inner())
}

// =========================================================================
// Leaf sub-schemas (no nested children)
// =========================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use rakata_formats::schema::{Absent, Field, GffScalar, HasSchema, Resolution, Shape};

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

    use rakata_core::{ResRef, StrRef};
    use rakata_formats::GffLocalizedString;

    /// Build a minimal GIT GFF for testing.
    fn make_test_git_gff() -> Gff {
        let mut root = GffStruct::new(-1);
        root.push_field(gff_label!("CurrentWeather"), GffValue::UInt8(0));
        root.push_field(gff_label!("WeatherStarted"), GffValue::UInt8(0));
        root.push_field(gff_label!("UseTemplates"), GffValue::UInt8(1));

        // One creature.
        let mut creature = GffStruct::new(4);
        creature.push_field(
            gff_label!("TemplateResRef"),
            GffValue::resref_lit("n_darthbandon"),
        );
        creature.push_field(gff_label!("XPosition"), GffValue::Single(10.0));
        creature.push_field(gff_label!("YPosition"), GffValue::Single(20.0));
        creature.push_field(gff_label!("ZPosition"), GffValue::Single(0.5));
        creature.push_field(gff_label!("XOrientation"), GffValue::Single(0.0));
        creature.push_field(gff_label!("YOrientation"), GffValue::Single(1.0));
        creature.push_field(gff_label!("ZOrientation"), GffValue::Single(0.0));
        creature.push_field(gff_label!("ObjectId"), GffValue::UInt32(0));
        root.push_field(gff_label!("Creature List"), GffValue::List(vec![creature]));

        // One placeable.
        let mut placeable = GffStruct::new(9);
        placeable.push_field(
            gff_label!("TemplateResRef"),
            GffValue::resref_lit("plc_footlkr"),
        );
        placeable.push_field(gff_label!("Bearing"), GffValue::Single(1.57));
        placeable.push_field(gff_label!("X"), GffValue::Single(15.0));
        placeable.push_field(gff_label!("Y"), GffValue::Single(25.0));
        placeable.push_field(gff_label!("Z"), GffValue::Single(0.0));
        placeable.push_field(gff_label!("ObjectId"), GffValue::UInt32(0));
        root.push_field(
            gff_label!("Placeable List"),
            GffValue::List(vec![placeable]),
        );

        // One trigger with geometry.
        let mut trigger = GffStruct::new(1);
        trigger.push_field(
            gff_label!("TemplateResRef"),
            GffValue::resref_lit("newtransition9"),
        );
        trigger.push_field(
            gff_label!("LinkedToModule"),
            GffValue::resref_lit("tar_m02aa"),
        );
        trigger.push_field(
            gff_label!("TransitionDestin"),
            GffValue::LocalizedString(GffLocalizedString::new(StrRef::from_raw(12345))),
        );
        trigger.push_field(gff_label!("LinkedTo"), GffValue::String("wp_target".into()));
        trigger.push_field(gff_label!("LinkedToFlags"), GffValue::UInt8(2));
        trigger.push_field(gff_label!("XPosition"), GffValue::Single(5.0));
        trigger.push_field(gff_label!("YPosition"), GffValue::Single(5.0));
        trigger.push_field(gff_label!("ZPosition"), GffValue::Single(0.0));
        let mut pt0 = GffStruct::new(0);
        pt0.push_field(gff_label!("PointX"), GffValue::Single(0.0));
        pt0.push_field(gff_label!("PointY"), GffValue::Single(0.0));
        pt0.push_field(gff_label!("PointZ"), GffValue::Single(0.0));
        let mut pt1 = GffStruct::new(0);
        pt1.push_field(gff_label!("PointX"), GffValue::Single(5.0));
        pt1.push_field(gff_label!("PointY"), GffValue::Single(0.0));
        pt1.push_field(gff_label!("PointZ"), GffValue::Single(0.0));
        let mut pt2 = GffStruct::new(0);
        pt2.push_field(gff_label!("PointX"), GffValue::Single(5.0));
        pt2.push_field(gff_label!("PointY"), GffValue::Single(5.0));
        pt2.push_field(gff_label!("PointZ"), GffValue::Single(0.0));
        trigger.push_field(gff_label!("Geometry"), GffValue::List(vec![pt0, pt1, pt2]));
        trigger.push_field(gff_label!("ObjectId"), GffValue::UInt32(0));
        root.push_field(gff_label!("TriggerList"), GffValue::List(vec![trigger]));

        // AreaProperties.
        let mut props = GffStruct::new(0);
        props.push_field(gff_label!("Unescapable"), GffValue::UInt8(0));
        props.push_field(gff_label!("StealthXPMax"), GffValue::UInt32(100));
        props.push_field(gff_label!("StealthXPCurrent"), GffValue::UInt32(0));
        props.push_field(gff_label!("StealthXPLoss"), GffValue::UInt32(10));
        props.push_field(gff_label!("StealthXPEnabled"), GffValue::UInt8(1));
        props.push_field(gff_label!("TransPending"), GffValue::UInt8(0));
        props.push_field(gff_label!("TransPendNextID"), GffValue::UInt8(0));
        props.push_field(gff_label!("TransPendCurrID"), GffValue::UInt8(0));
        props.push_field(gff_label!("SunFogColor"), GffValue::UInt32(0x00ABCDEF));
        props.push_field(gff_label!("MusicDelay"), GffValue::Int32(6000));
        props.push_field(gff_label!("MusicDay"), GffValue::Int32(48));
        props.push_field(gff_label!("MusicNight"), GffValue::Int32(49));
        props.push_field(gff_label!("MusicBattle"), GffValue::Int32(25));
        props.push_field(gff_label!("AmbientSndDay"), GffValue::Int32(12));
        props.push_field(gff_label!("AmbientSndNight"), GffValue::Int32(13));
        props.push_field(gff_label!("AmbientSndDayVol"), GffValue::Int32(50));
        props.push_field(gff_label!("AmbientSndNitVol"), GffValue::Int32(40));
        root.push_field(
            gff_label!("AreaProperties"),
            GffValue::Struct(Box::new(props)),
        );

        // Empty lists for remaining types.
        root.push_field(gff_label!("List"), GffValue::List(vec![]));
        root.push_field(gff_label!("Door List"), GffValue::List(vec![]));
        root.push_field(gff_label!("WaypointList"), GffValue::List(vec![]));
        root.push_field(gff_label!("SoundList"), GffValue::List(vec![]));
        root.push_field(gff_label!("StoreList"), GffValue::List(vec![]));
        root.push_field(gff_label!("Encounter List"), GffValue::List(vec![]));
        root.push_field(gff_label!("AreaEffectList"), GffValue::List(vec![]));
        root.push_field(gff_label!("CameraList"), GffValue::List(vec![]));

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

    #[test]
    fn reads_root_scalars() {
        let gff = make_test_git_gff();
        let git = Git::from_gff(&gff).expect("valid GIT GFF must parse");

        assert_eq!(git.current_weather, 0);
        assert!(!git.weather_started);
        assert!(git.creatures.uses_templates());
    }

    #[test]
    fn reads_creature_list() {
        let gff = make_test_git_gff();
        let git = Git::from_gff(&gff).expect("valid GIT GFF must parse");

        assert_eq!(git.creatures.len(), 1);
        let statics = git
            .creatures
            .as_static()
            .expect("the fixture sets UseTemplates = 1");
        let c = &statics[0];
        assert_eq!(c.template_resref, "n_darthbandon");
        assert!((c.common.x_position - 10.0).abs() < f32::EPSILON);
        assert!((c.common.y_position - 20.0).abs() < f32::EPSILON);
        assert!((c.common.y_orientation - 1.0).abs() < f32::EPSILON);
    }

    fn sample_area_effect() -> GitAreaEffect {
        GitAreaEffect {
            tag: "aoe_stasis".to_string(),
            object_id: ObjectId::INVALID,
            area_effect_id: 12,
            spell_id: 44,
            spell_save_dc: 18,
            spell_level: 3,
            shape: GitAreaEffectShape::Circle { radius: 5.0 },
            duration: 30_000,
            duration_type: 2,
            position_x: 1.5,
            orientation_y: 1.0,
            ..GitAreaEffect::default()
        }
    }

    #[test]
    fn area_effect_round_trips_through_a_list_element() {
        let effect = sample_area_effect();

        let parsed = GitAreaEffect::read_element(&written!(effect, 0));

        assert_eq!(parsed, effect);
    }

    #[test]
    fn an_area_effect_writes_only_the_dimensions_its_shape_uses() {
        // The loader reads Radius only for shape 0 and Length/Width only for
        // shape 1, so writing the other pair puts fields on the object the
        // engine would never read back.
        let circle = written!(sample_area_effect(), 0);
        assert!(circle.field("Radius").is_some());
        assert!(circle.field("Length").is_none());
        assert!(circle.field("Width").is_none());

        let rectangle = GitAreaEffect {
            shape: GitAreaEffectShape::Rectangle {
                length: 4.0,
                width: 2.0,
            },
            ..sample_area_effect()
        };
        let rectangle = written!(rectangle, 13);
        assert!(rectangle.field("Radius").is_none());
        assert!(rectangle.field("Length").is_some());
        assert!(rectangle.field("Width").is_some());

        let shapeless = GitAreaEffect {
            shape: GitAreaEffectShape::None(7),
            ..sample_area_effect()
        };
        let shapeless = written!(shapeless, 13);
        assert!(shapeless.field("Radius").is_none());
        assert!(shapeless.field("Length").is_none());
        assert_eq!(shapeless.field("Shape"), Some(&GffValue::UInt8(7)));
    }

    #[test]
    fn a_door_placement_keeps_its_blueprint_and_transition() {
        // The view modelled position and bearing only, so a vanilla door
        // round-tripped into a placement with nothing to instantiate from
        // and no transition. Both are set in vanilla modules.
        let mut door = GffStruct::new(8);
        door.push_field(
            gff_label!("TemplateResRef"),
            GffValue::ResRef(ResRef::new("m13aa_door01").expect("valid test resref")),
        );
        door.push_field(gff_label!("Tag"), GffValue::String("EnclaveDoor".into()));
        door.push_field(gff_label!("Bearing"), GffValue::Single(1.57));
        door.push_field(
            gff_label!("LinkedToModule"),
            GffValue::ResRef(ResRef::new("danm14aa").expect("valid test resref")),
        );
        door.push_field(
            gff_label!("LinkedTo"),
            GffValue::String("from_courtyard".into()),
        );
        door.push_field(gff_label!("LinkedToFlags"), GffValue::UInt8(2));
        door.push_field(
            gff_label!("TransitionDestin"),
            GffValue::LocalizedString(GffLocalizedString::new(
                StrRef::from_index(31982).expect("valid test strref"),
            )),
        );

        let parsed = GitDoor::read_element(&door);
        assert_eq!(parsed.template_resref, "m13aa_door01");
        assert_eq!(parsed.common.linked_to_module, "danm14aa");
        assert_eq!(parsed.common.linked_to, "from_courtyard");
        assert_eq!(parsed.common.linked_to_flags, 2);
        assert_eq!(
            parsed.common.transition_destination.string_ref,
            StrRef::from_index(31982).expect("valid test strref")
        );

        let written = written!(parsed, 0);
        for label in [
            "TemplateResRef",
            "LinkedToModule",
            "LinkedTo",
            "LinkedToFlags",
            "TransitionDestin",
        ] {
            assert_eq!(
                written.field(label),
                door.field(label),
                "{label} must survive the round-trip unchanged"
            );
        }

        // `Tag` is the one label here the engine does not read at this path:
        // a templated door takes its tag from the blueprint with no overlay.
        // Modelling it would hand callers a field that looks settable and
        // does nothing, so the view drops it and a raw-tree rule reports it.
        assert!(
            written.field("Tag").is_none(),
            "the placement's Tag is dead and must not be written back"
        );
    }

    #[test]
    fn an_absent_object_id_is_the_invalid_placeholder_on_every_type() {
        // Zero is a valid object id, so defaulting there claims an unplaced
        // object refers to whichever object the engine numbered first. Only
        // the area effect got this right; every other type read zero. No
        // vanilla static GIT carries ObjectId at all, so every one of them
        // was affected.
        //
        // The types reaching the label through `GitObjectPlacement` hold the
        // absence instead of resolving it, so that a list carrying no id does
        // not gain one on write. The audited answer did not move off them: it
        // is on their schema entry, which the assertion at the end of this
        // test reads back.
        let empty = GffStruct::new(0);

        // No `GitCreature` here: the static creature path never reads the
        // label, so the type does not model it. See `git/creature.rs`.
        assert_eq!(GitItem::read_element(&empty).common.object_id, None);
        assert_eq!(GitDoor::read_element(&empty).common.object_id, None);
        assert_eq!(GitPlaceable::read_element(&empty).common.object_id, None);
        assert_eq!(GitWaypoint::read_element(&empty).object_id, None);
        assert_eq!(GitSound::read_element(&empty).common.object_id, None);
        assert_eq!(GitTrigger::read_element(&empty).common.object_id, None);
        assert_eq!(GitStore::read_element(&empty).common.object_id, None);
        assert_eq!(GitEncounter::read_element(&empty).object_id, None);
        assert_eq!(
            GitAreaEffect::read_element(&GffStruct::new(13)).object_id,
            ObjectId::INVALID
        );

        // The saved forms read the same label through the same instruction,
        // which runs before the static-versus-save branch, so they cannot
        // legitimately differ from the placements above. They defaulted to
        // zero until this was checked rather than assumed.
        assert_eq!(
            crate::git::creature::SavedCreature::read_element(&empty).object_id,
            ObjectId::INVALID
        );
        assert_eq!(
            crate::git::door::SavedDoor::read_element(&empty)
                .common
                .object_id,
            None
        );
        assert_eq!(
            crate::git::item::SavedItem::read_element(&empty)
                .common
                .object_id,
            None
        );
        assert_eq!(
            crate::git::placeable::SavedPlaceable::read_element(&empty)
                .common
                .object_id,
            None
        );
        assert_eq!(
            crate::git::sound::SavedSound::read_element(&empty)
                .common
                .object_id,
            None
        );
        assert_eq!(
            crate::git::store::SavedStore::read_element(&empty)
                .common
                .object_id,
            None
        );
        assert_eq!(
            crate::git::trigger::SavedTrigger::read_element(&empty)
                .common
                .object_id,
            None
        );
        // The four types reaching the label through `GitObjectPlacement` hold
        // the absence, so the audited answer is only on the schema now. If it
        // is ever dropped there it is gone from the workspace entirely.
        let entry = GitObjectPlacement::SCHEMA
            .iter()
            .find(|field| field.label.as_str() == "ObjectId")
            .expect("the block declares it");
        let Absent::Resolves(Resolution::Stamped, value, _) = entry.absent else {
            panic!("the engine stamps a literal here, and the entry has to say so");
        };
        assert_eq!(value.get(), ObjectId::INVALID.to_gff_value());
    }

    #[test]
    fn reads_placeable_list() {
        let gff = make_test_git_gff();
        let git = Git::from_gff(&gff).expect("valid GIT GFF must parse");

        assert_eq!(git.placeables.len(), 1);
        let statics = git
            .placeables
            .as_static()
            .expect("the fixture sets UseTemplates = 1");
        let p = &statics[0];
        assert_eq!(p.template_resref, "plc_footlkr");
        assert!((p.placement.bearing - 1.57).abs() < 0.01);
        assert!((p.placement.x - 15.0).abs() < f32::EPSILON);
    }

    #[test]
    fn reads_trigger_with_geometry() {
        let gff = make_test_git_gff();
        let git = Git::from_gff(&gff).expect("valid GIT GFF must parse");

        assert_eq!(git.triggers.len(), 1);
        let statics = git
            .triggers
            .as_static()
            .expect("the fixture sets UseTemplates = 1");
        let t = &statics[0];
        assert_eq!(t.template_resref, "newtransition9");
        assert_eq!(t.common.linked_to_module, "tar_m02aa");
        assert_eq!(t.common.linked_to, "wp_target");
        assert_eq!(t.common.linked_to_flags, 2);
        assert_eq!(t.geometry.len(), 3);
        assert!((t.geometry[1].point_x - 5.0).abs() < f32::EPSILON);
    }

    #[test]
    fn reads_area_properties() {
        let gff = make_test_git_gff();
        let git = Git::from_gff(&gff).expect("valid GIT GFF must parse");

        let ap = git
            .area_properties
            .as_ref()
            .expect("test GFF includes AreaProperties");
        assert!(!ap.unescapable);
        assert_eq!(ap.stealth_xp_max, 100);
        assert!(ap.stealth_xp_enabled);
        assert_eq!(ap.music_day, 48);
        assert_eq!(ap.music_night, 49);
        assert_eq!(ap.music_battle, 25);
        assert_eq!(ap.ambient_snd_day_vol, 50);
        assert_eq!(ap.ambient_snd_nit_vol, 40);
    }

    #[test]
    fn all_fields_survive_synthetic_roundtrip() {
        let gff = make_test_git_gff();
        let git = Git::from_gff(&gff).expect("valid GIT GFF must parse");
        let bytes = author_git_to_vec(&git).expect("write succeeds");
        let reparsed = read_git_from_bytes(&bytes).expect("reparse succeeds");

        assert_eq!(reparsed, git);
    }

    #[test]
    fn typed_edits_roundtrip_through_gff_writer() {
        let gff = make_test_git_gff();
        let mut git = Git::from_gff(&gff).expect("valid GIT GFF must parse");
        let statics = git
            .creatures
            .as_static_mut()
            .expect("the fixture sets UseTemplates = 1");
        statics[0].template_resref = ResRef::new("n_sithsoldier").expect("valid test resref");
        statics[0].common.x_position = 100.0;
        git.area_properties
            .as_mut()
            .expect("test GFF includes AreaProperties")
            .music_day = 99;

        let bytes = author_git_to_vec(&git).expect("write succeeds");
        let reparsed = read_git_from_bytes(&bytes).expect("reparse succeeds");

        let reparsed_statics = reparsed
            .creatures
            .as_static()
            .expect("round-trip keeps UseTemplates = 1");
        assert_eq!(reparsed_statics[0].template_resref, "n_sithsoldier");
        assert!((reparsed_statics[0].common.x_position - 100.0).abs() < f32::EPSILON);
        assert_eq!(
            reparsed
                .area_properties
                .as_ref()
                .expect("roundtripped GIT must have AreaProperties")
                .music_day,
            99
        );
    }

    #[test]
    fn read_git_from_reader_matches_bytes_path() {
        let gff = make_test_git_gff();
        let bytes = {
            let mut c = Cursor::new(Vec::new());
            write_gff(&mut c, &gff).expect("GFF write to cursor always succeeds");
            c.into_inner()
        };

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

        assert_eq!(via_reader, via_bytes);
    }

    #[test]
    fn rejects_non_git_file_type() {
        let mut gff = make_test_git_gff();
        gff.file_type = *b"UTW ";

        let err = Git::from_gff(&gff).expect_err("UTW must be rejected as GIT input");
        assert!(matches!(
            err,
            GitError::UnsupportedFileType(ft) if ft == *b"UTW "
        ));
    }

    #[test]
    fn write_git_matches_direct_gff_writer() {
        let gff = make_test_git_gff();
        let git = Git::from_gff(&gff).expect("valid GIT GFF must parse");

        let via_typed = author_git_to_vec(&git).expect("typed write succeeds");

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

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

    // --- Fixture tests ---

    const TEST_GIT: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/test.git"
    ));
    const K1_GIT: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/k1_same_git_test.git"
    ));

    #[test]
    fn parses_test_git_fixture() {
        let git = read_git_from_bytes(TEST_GIT).expect("test.git must parse");
        // Should have at least some instance data.
        let total = git.creatures.len()
            + git.items.len()
            + git.doors.len()
            + git.placeables.len()
            + git.waypoints.len()
            + git.sounds.len()
            + git.triggers.len()
            + git.stores.len()
            + git.encounters.len()
            + git.area_effects.len();
        assert!(total > 0, "fixture should have some instance data");
    }

    #[test]
    fn parses_k1_git_fixture() {
        let git = read_git_from_bytes(K1_GIT).expect("k1 GIT must parse");
        let total = git.creatures.len()
            + git.items.len()
            + git.doors.len()
            + git.placeables.len()
            + git.waypoints.len()
            + git.sounds.len()
            + git.triggers.len()
            + git.stores.len()
            + git.encounters.len()
            + git.area_effects.len();
        assert!(total > 0, "K1 fixture should have some instance data");
    }

    #[test]
    fn all_fields_survive_typed_roundtrip() {
        let git = read_git_from_bytes(TEST_GIT).expect("test.git must parse");
        let bytes = author_git_to_vec(&git).expect("write succeeds");
        let reparsed = read_git_from_bytes(&bytes).expect("reparse succeeds");

        assert_eq!(reparsed, git);
    }

    #[test]
    fn all_fields_survive_typed_roundtrip_k1() {
        let git = read_git_from_bytes(K1_GIT).expect("k1 GIT must parse");
        let bytes = author_git_to_vec(&git).expect("write succeeds");
        let reparsed = read_git_from_bytes(&bytes).expect("reparse succeeds");

        assert_eq!(reparsed, git);
    }

    // --- Schema tests ---

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

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

    /// Each GIT list declares at least the children it declared before.
    ///
    /// A floor rather than an exact count. The exact form asserted numbers
    /// that were only ever a snapshot, so declaring the saved forms' labels
    /// broke it without anything being wrong; a floor still catches the case
    /// that matters, which is a child table losing entries and taking the
    /// coverage check's reach down with it.
    ///
    /// Summed across the element's parts and both arms of a split, since that
    /// is where a list's children live now.
    #[test]
    fn every_list_declares_at_least_the_children_it_had() {
        const FLOOR: &[(&str, usize)] = &[
            ("Creature List", 104),
            ("List", 29),
            ("Door List", 60),
            ("Placeable List", 65),
            ("WaypointList", 17),
            ("SoundList", 27),
            ("TriggerList", 37),
            ("StoreList", 16),
            ("Encounter List", 7),
        ];
        let count =
            |parts: &[&'static [Field]]| -> usize { parts.iter().map(|part| part.len()).sum() };
        for (label, floor) in FLOOR {
            let entry = Git::schema()
                .iter()
                .find(|f| f.label.as_str() == *label)
                .unwrap_or_else(|| panic!("schema must contain {label}"));
            let Shape::List { element, split, .. } = entry.shape else {
                panic!("{label} is a list");
            };
            let children =
                count(element) + split.map_or(0, |s| count(s.when_set) + count(s.when_clear));
            assert!(
                children >= *floor,
                "{label} declares {children} children, fewer than the {floor} it had"
            );
        }
    }
}