rakata_generics/are/

minigame.rs

//! Typed views over the ARE `MiniGame` subsystem.
//!
//! One area in four thousand-odd ships a minigame, and the four that do carry
//! a `MiniGame` struct nested in the ARE root. `Type` selects the mode: 1 is
//! swoop racing, 2 is the turret sequence. Naming anything here for swoop
//! alone names half the subsystem, hence the neutral module name.
//!
//! ## Field layout
//! ```text
//! MiniGame              (Struct -> AreMiniGame)
//! +-- Type / MovementPerSec / LateralAccel / Bump_Plane
//! +-- DoBumping / UseInertia / DOF / Music
//! +-- Far_Clip / Near_Clip / CameraViewAngle
//! +-- Player            (Struct -> AreMiniGamePlayer)
//! |   +-- Models        (List<AreMiniGameModel>)
//! |   `-- Track / Camera / CameraRotate
//! +-- Mouse             (Struct -> AreMiniGameMouse)
//! +-- Enemies           (List<AreMiniGameEnemy>)
//! `-- Obstacles         (List<AreMiniGameObstacle>)
//! ```
//!
//! `Mouse`, `Enemies` and `Obstacles` are siblings of `Player`, not children.
//! This diagram and the reader both nested them under `Player` until a corpus
//! extraction showed otherwise, which meant every enemy and obstacle in the
//! game was silently read as absent: 95 enemies and 67 obstacles across the
//! four minigame areas. `CSWMiniGame::Load` reads the `Enemies` and
//! `Obstacles` lists off the `MiniGame` struct, so those two are
//! engine-attested. `Mouse` sits alongside them in the one vanilla file that
//! carries it, but its loader path is untraced, so that level rests on the
//! data alone.

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

use crate::are::AreError;
use crate::gff_helpers::{get_bool, get_f32, get_i32, get_resref, get_u32, get_u8, upsert_field};

/// Typed view over the ARE `MiniGame` nested struct.
#[derive(Debug, Clone, PartialEq)]
pub struct AreMiniGame {
    /// Mini-game type (`Type`): 1 = swoop, 2 = turret.
    pub mini_game_type: u32,
    /// Movement speed (`MovementPerSec`).
    pub movement_per_sec: f32,
    /// Lateral acceleration (`LateralAccel`).
    pub lateral_accel: f32,
    /// Bump plane index (`Bump_Plane`).
    pub bump_plane: u32,
    /// Bumping enabled (`DoBumping`).
    pub do_bumping: bool,
    /// Inertia enabled (`UseInertia`).
    pub use_inertia: bool,
    /// Degrees of freedom (`DOF`).
    pub dof: u32,
    /// Music resref (`Music`).
    pub music: ResRef,
    /// Far clip distance (`Far_Clip`).
    pub far_clip: f32,
    /// Near clip distance (`Near_Clip`).
    pub near_clip: f32,
    /// Camera view angle (`CameraViewAngle`).
    pub camera_view_angle: f32,
    /// Player sub-struct (`Player`).
    pub player: Option<AreMiniGamePlayer>,
    /// Mouse axis settings (`Mouse`), when the area carries the struct.
    ///
    /// A sibling of `Player`, not a child of it. One vanilla minigame area of
    /// four has it.
    ///
    /// [`Option`] rather than a defaulted value, because presence and default
    /// are different questions for a struct. A default answers what the
    /// engine substitutes for an absent scalar; it says nothing about whether
    /// a nested struct exists. Materializing an all-zero `Mouse` for the
    /// three files without one and then writing it back would invent
    /// structure those files never had. `MiniGame` itself is an `Option` on
    /// [`Are`](crate::Are) for the same reason, so this matches the convention already in
    /// place rather than adding a second one.
    ///
    /// What the engine does with an absent `Mouse` is untraced, which is the
    /// argument for `Option` rather than against it: preserving the file's
    /// actual state invents nothing under that ignorance.
    pub mouse: Option<AreMiniGameMouse>,
    /// Enemy list (`Enemies`), a sibling of `Player`.
    pub enemies: Vec<AreMiniGameEnemy>,
    /// Obstacle list (`Obstacles`), a sibling of `Player`.
    pub obstacles: Vec<AreMiniGameObstacle>,
}

impl Default for AreMiniGame {
    fn default() -> Self {
        Self {
            mini_game_type: 0,
            movement_per_sec: 0.0,
            lateral_accel: 60.0,
            bump_plane: 0,
            do_bumping: false,
            use_inertia: false,
            dof: 0,
            music: ResRef::blank(),
            far_clip: 100.0,
            near_clip: 0.1,
            camera_view_angle: 65.0,
            player: None,
            mouse: None,
            enemies: Vec::new(),
            obstacles: Vec::new(),
        }
    }
}

impl AreMiniGame {
    pub(crate) fn from_struct(structure: &GffStruct) -> Result<Self, AreError> {
        let player = match structure.field("Player") {
            Some(GffValue::Struct(s)) => Some(AreMiniGamePlayer::from_struct(s)?),
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: "MiniGame.Player",
                    expected: "Struct",
                });
            }
            None => None,
        };

        // Siblings of `Player`, not children. `CSWMiniGame::Load` reads the
        // `Enemies` and `Obstacles` lists off this struct, and every vanilla
        // minigame area puts them here. `Mouse` sits alongside them in the
        // one file that has it; its loader path is untraced, so the level is
        // data-attested rather than engine-attested.
        let mouse = match structure.field("Mouse") {
            Some(GffValue::Struct(s)) => Some(AreMiniGameMouse::from_struct(s)),
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: "MiniGame.Mouse",
                    expected: "Struct",
                });
            }
            None => None,
        };

        let enemies = match structure.field("Enemies") {
            Some(GffValue::List(items)) => items
                .iter()
                .map(AreMiniGameEnemy::from_struct)
                .collect::<Result<Vec<_>, _>>()?,
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: "MiniGame.Enemies",
                    expected: "List",
                });
            }
            None => Vec::new(),
        };

        let obstacles = match structure.field("Obstacles") {
            Some(GffValue::List(items)) => items
                .iter()
                .map(AreMiniGameObstacle::from_struct)
                .collect::<Result<Vec<_>, _>>()?,
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: "MiniGame.Obstacles",
                    expected: "List",
                });
            }
            None => Vec::new(),
        };

        Ok(Self {
            mini_game_type: get_u32(structure, "Type").unwrap_or(0),
            movement_per_sec: get_f32(structure, "MovementPerSec").unwrap_or(0.0),
            lateral_accel: get_f32(structure, "LateralAccel").unwrap_or(60.0),
            bump_plane: get_u32(structure, "Bump_Plane").unwrap_or(0),
            do_bumping: get_bool(structure, "DoBumping").unwrap_or(false),
            use_inertia: get_bool(structure, "UseInertia").unwrap_or(false),
            dof: get_u32(structure, "DOF").unwrap_or(0),
            music: get_resref(structure, "Music").unwrap_or_default(),
            far_clip: get_f32(structure, "Far_Clip").unwrap_or(100.0),
            near_clip: get_f32(structure, "Near_Clip").unwrap_or(0.1),
            camera_view_angle: get_f32(structure, "CameraViewAngle").unwrap_or(65.0),
            player,
            mouse,
            enemies,
            obstacles,
        })
    }

    pub(crate) fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        upsert_field(&mut s, "Type", GffValue::UInt32(self.mini_game_type));
        upsert_field(
            &mut s,
            "MovementPerSec",
            GffValue::Single(self.movement_per_sec),
        );
        upsert_field(&mut s, "LateralAccel", GffValue::Single(self.lateral_accel));
        upsert_field(&mut s, "Bump_Plane", GffValue::UInt32(self.bump_plane));
        upsert_field(
            &mut s,
            "DoBumping",
            GffValue::UInt8(u8::from(self.do_bumping)),
        );
        upsert_field(
            &mut s,
            "UseInertia",
            GffValue::UInt8(u8::from(self.use_inertia)),
        );
        upsert_field(&mut s, "DOF", GffValue::UInt32(self.dof));
        upsert_field(&mut s, "Music", GffValue::ResRef(self.music));
        upsert_field(&mut s, "Far_Clip", GffValue::Single(self.far_clip));
        upsert_field(&mut s, "Near_Clip", GffValue::Single(self.near_clip));
        upsert_field(
            &mut s,
            "CameraViewAngle",
            GffValue::Single(self.camera_view_angle),
        );
        if let Some(player) = &self.player {
            upsert_field(
                &mut s,
                "Player",
                GffValue::Struct(Box::new(player.to_struct())),
            );
        }
        if let Some(mouse) = &self.mouse {
            upsert_field(
                &mut s,
                "Mouse",
                GffValue::Struct(Box::new(mouse.to_struct())),
            );
        }
        let enemy_structs: Vec<GffStruct> = self
            .enemies
            .iter()
            .map(AreMiniGameEnemy::to_struct)
            .collect();
        upsert_field(&mut s, "Enemies", GffValue::List(enemy_structs));
        let obstacle_structs: Vec<GffStruct> = self
            .obstacles
            .iter()
            .map(AreMiniGameObstacle::to_struct)
            .collect();
        upsert_field(&mut s, "Obstacles", GffValue::List(obstacle_structs));
        s
    }
}

/// The `Scripts` struct every minigame object carries.
///
/// Read by `CSWMiniGameObject::LoadScripts`, which obstacles use directly and
/// vehicles extend (see [`AreMiniGameVehicleScripts`]). Every slot defaults to
/// an empty resref and the engine writes that empty value into the script slot
/// whether or not the file supplied one, so an absent field clears a prior
/// script rather than leaving it in place.
///
/// `OnHeartbeat` is the fifth and last slot the base reads, after
/// `OnAnimEvent`.
///
/// It was missing from the write-up of this subsystem, and from the corpus
/// scan the write-up was checked against, because the ARE root carries a
/// script field under the same label: a scan keyed on bare labels sees the
/// root's and counts the nested one as already modelled.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AreMiniGameObjectScripts {
    /// Fired when the object is created (`OnCreate`).
    pub on_create: ResRef,
    /// Fired on the object's heartbeat (`OnHeartbeat`).
    pub on_heartbeat: ResRef,
    /// Fired on a model animation event (`OnAnimEvent`).
    pub on_anim_event: ResRef,
    /// Fired when a bullet hits the object (`OnHitBullet`).
    pub on_hit_bullet: ResRef,
    /// Fired when a track follower hits the object (`OnHitFollower`).
    pub on_hit_follower: ResRef,
}

impl AreMiniGameObjectScripts {
    fn from_struct(structure: &GffStruct) -> Self {
        Self {
            on_create: get_resref(structure, "OnCreate").unwrap_or_default(),
            on_heartbeat: get_resref(structure, "OnHeartbeat").unwrap_or_default(),
            on_anim_event: get_resref(structure, "OnAnimEvent").unwrap_or_default(),
            on_hit_bullet: get_resref(structure, "OnHitBullet").unwrap_or_default(),
            on_hit_follower: get_resref(structure, "OnHitFollower").unwrap_or_default(),
        }
    }

    fn write_into(&self, s: &mut GffStruct) {
        upsert_field(s, "OnCreate", GffValue::ResRef(self.on_create));
        upsert_field(s, "OnHeartbeat", GffValue::ResRef(self.on_heartbeat));
        upsert_field(s, "OnAnimEvent", GffValue::ResRef(self.on_anim_event));
        upsert_field(s, "OnHitBullet", GffValue::ResRef(self.on_hit_bullet));
        upsert_field(s, "OnHitFollower", GffValue::ResRef(self.on_hit_follower));
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        self.write_into(&mut s);
        s
    }
}

/// The `Scripts` struct on a vehicle, which is the object set plus five more.
///
/// `CSWTrackFollower::LoadScripts` overrides the base and reads the extra five
/// on top of it. Obstacles never carry them, and the corpus agrees: an
/// obstacle's `Scripts` holds exactly the base set.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AreMiniGameVehicleScripts {
    /// The slots shared with obstacles.
    pub object: AreMiniGameObjectScripts,
    /// Fired when the vehicle takes damage (`OnDamage`).
    pub on_damage: ResRef,
    /// Fired when the vehicle is destroyed (`OnDeath`).
    pub on_death: ResRef,
    /// Fired when the vehicle fires a gun bank (`OnFire`).
    pub on_fire: ResRef,
    /// Fired when the vehicle hits an obstacle (`OnHitObstacle`).
    pub on_hit_obstacle: ResRef,
    /// Fired each time the vehicle completes a track loop (`OnTrackLoop`).
    pub on_track_loop: ResRef,
}

impl AreMiniGameVehicleScripts {
    fn from_struct(structure: &GffStruct) -> Self {
        Self {
            object: AreMiniGameObjectScripts::from_struct(structure),
            on_damage: get_resref(structure, "OnDamage").unwrap_or_default(),
            on_death: get_resref(structure, "OnDeath").unwrap_or_default(),
            on_fire: get_resref(structure, "OnFire").unwrap_or_default(),
            on_hit_obstacle: get_resref(structure, "OnHitObstacle").unwrap_or_default(),
            on_track_loop: get_resref(structure, "OnTrackLoop").unwrap_or_default(),
        }
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        self.object.write_into(&mut s);
        upsert_field(&mut s, "OnDamage", GffValue::ResRef(self.on_damage));
        upsert_field(&mut s, "OnDeath", GffValue::ResRef(self.on_death));
        upsert_field(&mut s, "OnFire", GffValue::ResRef(self.on_fire));
        upsert_field(
            &mut s,
            "OnHitObstacle",
            GffValue::ResRef(self.on_hit_obstacle),
        );
        upsert_field(&mut s, "OnTrackLoop", GffValue::ResRef(self.on_track_loop));
        s
    }
}

/// The `Sounds` struct on a vehicle.
///
/// Read by `CSWTrackFollower::LoadSounds`. Both default to empty and are
/// written into their slots whether or not the file supplied them, the same
/// overwrite-on-absence pattern the scripts follow. A non-empty `Engine` sound
/// is additionally forced into looping playback.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AreMiniGameSounds {
    /// Looping engine sound (`Engine`).
    pub engine: ResRef,
    /// One-shot destruction sound (`Death`).
    pub death: ResRef,
}

impl AreMiniGameSounds {
    fn from_struct(structure: &GffStruct) -> Self {
        Self {
            engine: get_resref(structure, "Engine").unwrap_or_default(),
            death: get_resref(structure, "Death").unwrap_or_default(),
        }
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        upsert_field(&mut s, "Engine", GffValue::ResRef(self.engine));
        upsert_field(&mut s, "Death", GffValue::ResRef(self.death));
        s
    }
}

/// The `BankID` value that means "no bank".
///
/// The engine reads `BankID` with this as its default and then gates bank
/// creation by comparing the *resolved* value against the same literal, with
/// no separate check for whether the file supplied one. So an absent `BankID`
/// and one written explicitly as `0xffffffff` are the same case, which is why
/// the view models one `u32` rather than an `Option` that would claim to tell
/// them apart.
pub const BANK_ID_NONE: u32 = 0xFFFF_FFFF;

/// The ballistics of one gun bank (`Bullet`).
///
/// The first five fields are a presence-gated chain: each read reports
/// whether the file supplied the field, and that gates whether the next one
/// is attempted at all. If any is genuinely absent the chain truncates and
/// the bank is never created, so there is no such thing as a partial bank
/// built from defaults. `Bullet_Model` and `Collision_Sound` are read
/// unconditionally once the chain completes.
///
/// The view models all seven as plain fields rather than making the chain
/// visible in the type. A file missing one of the five is malformed, and
/// saying so is a diagnostic's job: the schema marks them required and lint
/// reports the dropped bank. Seven `Option`s would push that judgement onto
/// every caller that only wanted to read a rate of fire.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AreMiniGameBullet {
    /// Damage per hit (`Damage`).
    pub damage: u32,
    /// Seconds before the bullet expires (`Lifespan`).
    pub lifespan: f32,
    /// Seconds between shots (`Rate_Of_Fire`).
    pub rate_of_fire: f32,
    /// Travel speed (`Speed`).
    pub speed: f32,
    /// What the bank is allowed to shoot at (`Target_Type`).
    pub target_type: u32,
    /// Bullet model resref (`Bullet_Model`).
    pub bullet_model: ResRef,
    /// Sound played on impact (`Collision_Sound`).
    pub collision_sound: ResRef,
}

impl AreMiniGameBullet {
    fn from_struct(structure: &GffStruct) -> Self {
        Self {
            damage: get_u32(structure, "Damage").unwrap_or(0),
            lifespan: get_f32(structure, "Lifespan").unwrap_or(0.0),
            rate_of_fire: get_f32(structure, "Rate_Of_Fire").unwrap_or(0.0),
            speed: get_f32(structure, "Speed").unwrap_or(0.0),
            target_type: get_u32(structure, "Target_Type").unwrap_or(0),
            bullet_model: get_resref(structure, "Bullet_Model").unwrap_or_default(),
            collision_sound: get_resref(structure, "Collision_Sound").unwrap_or_default(),
        }
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        upsert_field(&mut s, "Damage", GffValue::UInt32(self.damage));
        upsert_field(&mut s, "Lifespan", GffValue::Single(self.lifespan));
        upsert_field(&mut s, "Rate_Of_Fire", GffValue::Single(self.rate_of_fire));
        upsert_field(&mut s, "Speed", GffValue::Single(self.speed));
        upsert_field(&mut s, "Target_Type", GffValue::UInt32(self.target_type));
        upsert_field(&mut s, "Bullet_Model", GffValue::ResRef(self.bullet_model));
        upsert_field(
            &mut s,
            "Collision_Sound",
            GffValue::ResRef(self.collision_sound),
        );
        s
    }
}

/// The AI aiming parameters an enemy gun bank carries.
///
/// Flat on the bank entry, siblings of `Bullet` rather than fields inside it,
/// and read only for enemies: the player's own guns never carry them. Grouped
/// here because they are one concept and because the grouping is what lets
/// the bank say "this is an enemy's" without a separate flag.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AreMiniGameTargeting {
    /// How far the bank looks for a target (`Sensing_Radius`).
    pub sensing_radius: f32,
    /// Horizontal firing arc (`Horiz_Spread`).
    pub horiz_spread: f32,
    /// Vertical firing arc (`Vert_Spread`).
    pub vert_spread: f32,
    /// How far shots stray from the target (`Inaccuracy`).
    pub inaccuracy: f32,
}

impl AreMiniGameTargeting {
    /// The four labels, which are read and written as a set.
    const LABELS: [&'static str; 4] = [
        "Sensing_Radius",
        "Horiz_Spread",
        "Vert_Spread",
        "Inaccuracy",
    ];

    /// Reads the group, or `None` when the bank is not an enemy's.
    ///
    /// Presence is keyed on all four rather than any, because the engine
    /// reads them as a presence-gated chain and aborts the whole bank if one
    /// is missing. A bank with three of the four is a bank the engine drops,
    /// so treating that as `Some` would report a working set where the file
    /// describes a broken one. No vanilla bank is partial: enemy banks carry
    /// all four and player banks carry none.
    fn from_struct(structure: &GffStruct) -> Option<Self> {
        if !Self::LABELS
            .iter()
            .all(|label| structure.field(label).is_some())
        {
            return None;
        }
        Some(Self {
            sensing_radius: get_f32(structure, "Sensing_Radius").unwrap_or(0.0),
            horiz_spread: get_f32(structure, "Horiz_Spread").unwrap_or(0.0),
            vert_spread: get_f32(structure, "Vert_Spread").unwrap_or(0.0),
            inaccuracy: get_f32(structure, "Inaccuracy").unwrap_or(0.0),
        })
    }

    fn write_into(&self, s: &mut GffStruct) {
        upsert_field(s, "Sensing_Radius", GffValue::Single(self.sensing_radius));
        upsert_field(s, "Horiz_Spread", GffValue::Single(self.horiz_spread));
        upsert_field(s, "Vert_Spread", GffValue::Single(self.vert_spread));
        upsert_field(s, "Inaccuracy", GffValue::Single(self.inaccuracy));
    }
}

/// One entry in a vehicle's `Gun_Banks` list.
#[derive(Debug, Clone, PartialEq)]
pub struct AreMiniGameGunBank {
    /// Which hardpoint this bank occupies (`BankID`).
    ///
    /// [`BANK_ID_NONE`] means the engine skips the bank entirely.
    pub bank_id: u32,
    /// Gun model resref (`Gun_Model`).
    ///
    /// An invalid or absent resref aborts the bank, so an empty value here
    /// describes a bank that will not be created.
    pub gun_model: ResRef,
    /// Ballistics (`Bullet`), absent when the bank carries no such struct.
    ///
    /// [`Option`] because absence is not the same as a zeroed struct. The
    /// engine skips a bank with no `Bullet`; a view that materialised an
    /// all-zero one and wrote it back would turn a bank the engine drops into
    /// one it creates and fires at zero speed. That is a silent change of
    /// meaning on write, which is the failure this type exists to avoid.
    pub bullet: Option<AreMiniGameBullet>,
    /// Sound played when the bank fires (`Fire_Sound`).
    ///
    /// A sibling of `Bullet`, not a field inside it, despite reading like one.
    pub fire_sound: ResRef,
    /// AI aiming parameters, present on enemy banks and absent on the
    /// player's.
    pub targeting: Option<AreMiniGameTargeting>,
}

impl Default for AreMiniGameGunBank {
    fn default() -> Self {
        Self {
            bank_id: BANK_ID_NONE,
            gun_model: ResRef::blank(),
            bullet: None,
            fire_sound: ResRef::blank(),
            targeting: None,
        }
    }
}

impl AreMiniGameGunBank {
    fn from_struct(structure: &GffStruct, bullet_field: &'static str) -> Result<Self, AreError> {
        let bullet = match structure.field("Bullet") {
            Some(GffValue::Struct(s)) => Some(AreMiniGameBullet::from_struct(s)),
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: bullet_field,
                    expected: "Struct",
                });
            }
            None => None,
        };

        Ok(Self {
            bank_id: get_u32(structure, "BankID").unwrap_or(BANK_ID_NONE),
            gun_model: get_resref(structure, "Gun_Model").unwrap_or_default(),
            bullet,
            fire_sound: get_resref(structure, "Fire_Sound").unwrap_or_default(),
            targeting: AreMiniGameTargeting::from_struct(structure),
        })
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        upsert_field(&mut s, "BankID", GffValue::UInt32(self.bank_id));
        upsert_field(&mut s, "Gun_Model", GffValue::ResRef(self.gun_model));
        if let Some(bullet) = &self.bullet {
            upsert_field(
                &mut s,
                "Bullet",
                GffValue::Struct(Box::new(bullet.to_struct())),
            );
        }
        upsert_field(&mut s, "Fire_Sound", GffValue::ResRef(self.fire_sound));
        if let Some(targeting) = &self.targeting {
            targeting.write_into(&mut s);
        }
        s
    }
}

/// Where one vehicle's nested reads sit in the tree, for error reporting.
///
/// A vehicle is read at two different paths, and [`AreError::TypeMismatch`]
/// carries a `&'static str`, so the paths cannot be built at read time. Two
/// constants below cover both cases.
struct VehiclePaths {
    models: &'static str,
    scripts: &'static str,
    sounds: &'static str,
    gun_banks: &'static str,
    bullet: &'static str,
}

const PLAYER_PATHS: VehiclePaths = VehiclePaths {
    models: "MiniGame.Player.Models",
    scripts: "MiniGame.Player.Scripts",
    sounds: "MiniGame.Player.Sounds",
    gun_banks: "MiniGame.Player.Gun_Banks",
    bullet: "MiniGame.Player.Gun_Banks[].Bullet",
};

const ENEMY_PATHS: VehiclePaths = VehiclePaths {
    models: "MiniGame.Enemies[].Models",
    scripts: "MiniGame.Enemies[].Scripts",
    sounds: "MiniGame.Enemies[].Sounds",
    gun_banks: "MiniGame.Enemies[].Gun_Banks",
    bullet: "MiniGame.Enemies[].Gun_Banks[].Bullet",
};

/// The fields the player vehicle and every enemy vehicle both carry.
///
/// The engine backs both with one class, `CSWTrackFollower`, and both
/// `CSWMiniPlayer::Load` and `CSWMiniEnemy::Load` delegate to
/// `CSWTrackFollower::Load` on an embedded sub-object before reading anything
/// of their own. So the sharing here is a fact about the engine's object
/// graph, not a resemblance spotted between two field lists.
///
/// The distinction decides whether a shared base is worth having at all. One
/// derived from the intersection of two field lists is a coincidence given a
/// name, and it breaks the moment either side gains a field the other lacks.
/// This one names a class the engine has, so a new field belongs either to
/// that class or to one of the two subclasses, and the model has somewhere
/// honest to put it either way.
///
/// Obstacles sit outside this entirely. `CSWMGObstacle::Load` reads a name and
/// a scripts struct, with no lifecycle, weapon or track data at all.
#[derive(Debug, Clone, PartialEq)]
pub struct AreMiniGameVehicle {
    /// Model list (`Models`).
    pub models: Vec<AreMiniGameModel>,
    /// Track resref (`Track`) the vehicle follows.
    pub track: ResRef,
    /// Current hit points (`Hit_Points`).
    ///
    /// The engine applies the file's value only when it is greater than zero.
    /// A zero or absent value leaves whatever the object was constructed with,
    /// so zero here means "engine decides", not "starts dead".
    pub hit_points: u32,
    /// Maximum hit points (`Max_HPs`), gated the same way as [`Self::hit_points`].
    pub max_hps: u32,
    /// Collision sphere radius (`Sphere_Radius`).
    ///
    /// Default `-1.0`, which the engine reads as a sentinel: it applies the
    /// value only when it is at or above zero, so a negative radius means the
    /// constructed default stands.
    pub sphere_radius: f32,
    /// Invulnerability window in seconds after a hit (`Invince_Period`).
    pub invince_period: f32,
    /// Damage dealt to whatever this vehicle bumps into (`Bump_Damage`).
    pub bump_damage: i32,
    /// Number of times the vehicle loops its track (`Num_Loops`).
    ///
    /// Default `-10`, a sentinel the engine passes through to a virtual setter
    /// whose own handling of it was not traced. Vanilla writes `-1` for every
    /// enemy, which is a different sentinel again.
    pub num_loops: i32,
    /// Script slots (`Scripts`).
    ///
    /// Not an [`Option`] despite being a nested struct, unlike
    /// [`AreMiniGame::mouse`]. The engine's read here is traced and provably
    /// indifferent: an absent `Scripts` and one holding nothing but empty
    /// resrefs leave the object in the same state, because every slot is
    /// written whether or not the file supplied it. Materializing one invents
    /// a label but no behaviour. Once absent-value auditing can express "omit
    /// when equal to the audited default", an all-empty `Scripts` is a
    /// candidate to stop being written at all.
    pub scripts: AreMiniGameVehicleScripts,
    /// Engine and destruction sounds (`Sounds`), on the same footing as
    /// [`Self::scripts`].
    pub sounds: AreMiniGameSounds,
    /// Weapon hardpoints (`Gun_Banks`).
    pub gun_banks: Vec<AreMiniGameGunBank>,
}

impl Default for AreMiniGameVehicle {
    fn default() -> Self {
        Self {
            models: Vec::new(),
            track: ResRef::blank(),
            hit_points: 0,
            max_hps: 0,
            sphere_radius: -1.0,
            invince_period: 0.0,
            bump_damage: 0,
            num_loops: -10,
            scripts: AreMiniGameVehicleScripts::default(),
            sounds: AreMiniGameSounds::default(),
            gun_banks: Vec::new(),
        }
    }
}

impl AreMiniGameVehicle {
    /// Reads the shared fields off a `Player` struct or an `Enemies` entry.
    fn from_struct(structure: &GffStruct, paths: &VehiclePaths) -> Result<Self, AreError> {
        let models = match structure.field("Models") {
            Some(GffValue::List(items)) => items
                .iter()
                .map(AreMiniGameModel::from_struct)
                .collect::<Vec<_>>(),
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: paths.models,
                    expected: "List",
                });
            }
            None => Vec::new(),
        };

        let scripts = match structure.field("Scripts") {
            Some(GffValue::Struct(s)) => AreMiniGameVehicleScripts::from_struct(s),
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: paths.scripts,
                    expected: "Struct",
                });
            }
            None => AreMiniGameVehicleScripts::default(),
        };

        let sounds = match structure.field("Sounds") {
            Some(GffValue::Struct(s)) => AreMiniGameSounds::from_struct(s),
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: paths.sounds,
                    expected: "Struct",
                });
            }
            None => AreMiniGameSounds::default(),
        };

        let gun_banks = match structure.field("Gun_Banks") {
            Some(GffValue::List(items)) => items
                .iter()
                .map(|item| AreMiniGameGunBank::from_struct(item, paths.bullet))
                .collect::<Result<Vec<_>, _>>()?,
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: paths.gun_banks,
                    expected: "List",
                });
            }
            None => Vec::new(),
        };

        Ok(Self {
            models,
            track: get_resref(structure, "Track").unwrap_or_default(),
            hit_points: get_u32(structure, "Hit_Points").unwrap_or(0),
            max_hps: get_u32(structure, "Max_HPs").unwrap_or(0),
            sphere_radius: get_f32(structure, "Sphere_Radius").unwrap_or(-1.0),
            invince_period: get_f32(structure, "Invince_Period").unwrap_or(0.0),
            bump_damage: get_i32(structure, "Bump_Damage").unwrap_or(0),
            num_loops: get_i32(structure, "Num_Loops").unwrap_or(-10),
            scripts,
            sounds,
            gun_banks,
        })
    }

    /// Writes the shared fields into an already-created struct, so the caller
    /// can add its own on top.
    fn write_into(&self, s: &mut GffStruct) {
        let model_structs: Vec<GffStruct> = self
            .models
            .iter()
            .map(AreMiniGameModel::to_struct)
            .collect();
        upsert_field(s, "Models", GffValue::List(model_structs));
        upsert_field(s, "Track", GffValue::ResRef(self.track));
        upsert_field(s, "Hit_Points", GffValue::UInt32(self.hit_points));
        upsert_field(s, "Max_HPs", GffValue::UInt32(self.max_hps));
        upsert_field(s, "Sphere_Radius", GffValue::Single(self.sphere_radius));
        upsert_field(s, "Invince_Period", GffValue::Single(self.invince_period));
        upsert_field(s, "Bump_Damage", GffValue::Int32(self.bump_damage));
        upsert_field(s, "Num_Loops", GffValue::Int32(self.num_loops));
        upsert_field(
            s,
            "Scripts",
            GffValue::Struct(Box::new(self.scripts.to_struct())),
        );
        upsert_field(
            s,
            "Sounds",
            GffValue::Struct(Box::new(self.sounds.to_struct())),
        );
        let bank_structs: Vec<GffStruct> = self
            .gun_banks
            .iter()
            .map(AreMiniGameGunBank::to_struct)
            .collect();
        upsert_field(s, "Gun_Banks", GffValue::List(bank_structs));
    }
}

/// Typed view over the `MiniGame.Player` sub-struct.
#[derive(Debug, Clone, PartialEq)]
pub struct AreMiniGamePlayer {
    /// The vehicle fields shared with every enemy.
    pub vehicle: AreMiniGameVehicle,
    /// Camera resref (`Camera`) - only used for turret type (type 2).
    pub camera: ResRef,
    /// Camera rotation flag (`CameraRotate`).
    pub camera_rotate: bool,
    /// Lower speed bound (`Minimum_Speed`).
    ///
    /// Default `-1.0`, a sentinel: the engine applies the value only when it
    /// is at or above zero, so a negative bound leaves the constructed one.
    pub minimum_speed: f32,
    /// Upper speed bound (`Maximum_Speed`), default `100.0`.
    ///
    /// Gated the same way as [`Self::minimum_speed`], which for a default of
    /// `100.0` means the gate never rejects it.
    pub maximum_speed: f32,
    /// Seconds to accelerate across the speed range (`Accel_Secs`).
    ///
    /// The engine keeps only the acceleration it derives from this and the
    /// two speed bounds, never the field itself, and the derivation has three
    /// branches: exactly `0.0` gives the full speed range as the rate, a
    /// negative value skips the derivation, and anything else divides the
    /// range by it. The view models the file's value, since that is what the
    /// file holds and what a caller edits.
    pub accel_secs: f32,
    /// Positive-X track boundary (`TunnelXPos`).
    pub tunnel_x_pos: f32,
    /// Negative-X track boundary (`TunnelXNeg`).
    pub tunnel_x_neg: f32,
    /// Positive-Y track boundary (`TunnelYPos`).
    pub tunnel_y_pos: f32,
    /// Negative-Y track boundary (`TunnelYNeg`).
    pub tunnel_y_neg: f32,
    /// Positive-Z track boundary (`TunnelZPos`).
    pub tunnel_z_pos: f32,
    /// Negative-Z track boundary (`TunnelZNeg`).
    pub tunnel_z_neg: f32,
    /// Per-axis flags for an unbounded tunnel (`TunnelInfinite`).
    ///
    /// A GFF vector rather than three floats, unlike the bounds it modifies.
    pub tunnel_infinite: [f32; 3],
    /// Start position X offset (`Start_Offset_X`).
    ///
    /// The engine assembles the three into one vector and feeds it to the
    /// vehicle's origin. They stay three fields here because that is how the
    /// file stores them.
    pub start_offset_x: f32,
    /// Start position Y offset (`Start_Offset_Y`).
    pub start_offset_y: f32,
    /// Start position Z offset (`Start_Offset_Z`).
    pub start_offset_z: f32,
    /// Camera target X offset (`Target_Offset_X`).
    ///
    /// Three independent floats, and not assembled into a vector the way the
    /// start offsets are.
    pub target_offset_x: f32,
    /// Camera target Y offset (`Target_Offset_Y`).
    pub target_offset_y: f32,
    /// Camera target Z offset (`Target_Offset_Z`).
    pub target_offset_z: f32,
}

impl Default for AreMiniGamePlayer {
    fn default() -> Self {
        Self {
            vehicle: AreMiniGameVehicle::default(),
            camera: ResRef::blank(),
            camera_rotate: false,
            minimum_speed: -1.0,
            maximum_speed: 100.0,
            accel_secs: -1.0,
            tunnel_x_pos: 0.0,
            tunnel_x_neg: 0.0,
            tunnel_y_pos: 0.0,
            tunnel_y_neg: 0.0,
            tunnel_z_pos: 0.0,
            tunnel_z_neg: 0.0,
            tunnel_infinite: [0.0; 3],
            start_offset_x: 0.0,
            start_offset_y: 0.0,
            start_offset_z: 0.0,
            target_offset_x: 0.0,
            target_offset_y: 0.0,
            target_offset_z: 0.0,
        }
    }
}

impl AreMiniGamePlayer {
    fn from_struct(structure: &GffStruct) -> Result<Self, AreError> {
        Ok(Self {
            vehicle: AreMiniGameVehicle::from_struct(structure, &PLAYER_PATHS)?,
            camera: get_resref(structure, "Camera").unwrap_or_default(),
            camera_rotate: get_bool(structure, "CameraRotate").unwrap_or(false),
            minimum_speed: get_f32(structure, "Minimum_Speed").unwrap_or(-1.0),
            maximum_speed: get_f32(structure, "Maximum_Speed").unwrap_or(100.0),
            accel_secs: get_f32(structure, "Accel_Secs").unwrap_or(-1.0),
            tunnel_x_pos: get_f32(structure, "TunnelXPos").unwrap_or(0.0),
            tunnel_x_neg: get_f32(structure, "TunnelXNeg").unwrap_or(0.0),
            tunnel_y_pos: get_f32(structure, "TunnelYPos").unwrap_or(0.0),
            tunnel_y_neg: get_f32(structure, "TunnelYNeg").unwrap_or(0.0),
            tunnel_z_pos: get_f32(structure, "TunnelZPos").unwrap_or(0.0),
            tunnel_z_neg: get_f32(structure, "TunnelZNeg").unwrap_or(0.0),
            tunnel_infinite: match structure.field("TunnelInfinite") {
                Some(GffValue::Vector3(v)) => *v,
                _ => [0.0; 3],
            },
            start_offset_x: get_f32(structure, "Start_Offset_X").unwrap_or(0.0),
            start_offset_y: get_f32(structure, "Start_Offset_Y").unwrap_or(0.0),
            start_offset_z: get_f32(structure, "Start_Offset_Z").unwrap_or(0.0),
            target_offset_x: get_f32(structure, "Target_Offset_X").unwrap_or(0.0),
            target_offset_y: get_f32(structure, "Target_Offset_Y").unwrap_or(0.0),
            target_offset_z: get_f32(structure, "Target_Offset_Z").unwrap_or(0.0),
        })
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        self.vehicle.write_into(&mut s);
        upsert_field(&mut s, "Camera", GffValue::ResRef(self.camera));
        upsert_field(
            &mut s,
            "CameraRotate",
            GffValue::UInt8(u8::from(self.camera_rotate)),
        );
        upsert_field(
            &mut s,
            "Minimum_Speed",
            GffValue::Single(self.minimum_speed),
        );
        upsert_field(
            &mut s,
            "Maximum_Speed",
            GffValue::Single(self.maximum_speed),
        );
        upsert_field(&mut s, "Accel_Secs", GffValue::Single(self.accel_secs));
        upsert_field(&mut s, "TunnelXPos", GffValue::Single(self.tunnel_x_pos));
        upsert_field(&mut s, "TunnelXNeg", GffValue::Single(self.tunnel_x_neg));
        upsert_field(&mut s, "TunnelYPos", GffValue::Single(self.tunnel_y_pos));
        upsert_field(&mut s, "TunnelYNeg", GffValue::Single(self.tunnel_y_neg));
        upsert_field(&mut s, "TunnelZPos", GffValue::Single(self.tunnel_z_pos));
        upsert_field(&mut s, "TunnelZNeg", GffValue::Single(self.tunnel_z_neg));
        upsert_field(
            &mut s,
            "TunnelInfinite",
            GffValue::Vector3(self.tunnel_infinite),
        );
        upsert_field(
            &mut s,
            "Start_Offset_X",
            GffValue::Single(self.start_offset_x),
        );
        upsert_field(
            &mut s,
            "Start_Offset_Y",
            GffValue::Single(self.start_offset_y),
        );
        upsert_field(
            &mut s,
            "Start_Offset_Z",
            GffValue::Single(self.start_offset_z),
        );
        upsert_field(
            &mut s,
            "Target_Offset_X",
            GffValue::Single(self.target_offset_x),
        );
        upsert_field(
            &mut s,
            "Target_Offset_Y",
            GffValue::Single(self.target_offset_y),
        );
        upsert_field(
            &mut s,
            "Target_Offset_Z",
            GffValue::Single(self.target_offset_z),
        );
        s
    }
}

/// Typed view over one model entry in a mini-game model list.
#[derive(Debug, Clone, PartialEq)]
pub struct AreMiniGameModel {
    /// Model resref (`Model`).
    pub model: ResRef,
    /// Whether the model rotates (`RotatingModel`).
    pub rotating_model: bool,
}

impl Default for AreMiniGameModel {
    fn default() -> Self {
        Self {
            model: ResRef::blank(),
            rotating_model: true,
        }
    }
}

impl AreMiniGameModel {
    fn from_struct(structure: &GffStruct) -> Self {
        Self {
            model: get_resref(structure, "Model").unwrap_or_default(),
            rotating_model: get_bool(structure, "RotatingModel").unwrap_or(true),
        }
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        upsert_field(&mut s, "Model", GffValue::ResRef(self.model));
        upsert_field(
            &mut s,
            "RotatingModel",
            GffValue::UInt8(u8::from(self.rotating_model)),
        );
        s
    }
}

/// Typed view over the `MiniGame.Player.Mouse` sub-struct.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AreMiniGameMouse {
    /// X axis index (`AxisX`).
    pub axis_x: u32,
    /// Y axis index (`AxisY`).
    pub axis_y: u32,
    /// Flip X axis (`FlipAxisX`).
    pub flip_axis_x: bool,
    /// Flip Y axis (`FlipAxisY`).
    pub flip_axis_y: bool,
}

impl AreMiniGameMouse {
    fn from_struct(structure: &GffStruct) -> Self {
        Self {
            axis_x: get_u32(structure, "AxisX").unwrap_or(0),
            axis_y: get_u32(structure, "AxisY").unwrap_or(0),
            flip_axis_x: get_bool(structure, "FlipAxisX").unwrap_or(false),
            flip_axis_y: get_bool(structure, "FlipAxisY").unwrap_or(false),
        }
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        upsert_field(&mut s, "AxisX", GffValue::UInt32(self.axis_x));
        upsert_field(&mut s, "AxisY", GffValue::UInt32(self.axis_y));
        upsert_field(
            &mut s,
            "FlipAxisX",
            GffValue::UInt8(u8::from(self.flip_axis_x)),
        );
        upsert_field(
            &mut s,
            "FlipAxisY",
            GffValue::UInt8(u8::from(self.flip_axis_y)),
        );
        s
    }
}

/// Typed view over one enemy entry in `MiniGame.Enemies`.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AreMiniGameEnemy {
    /// The vehicle fields shared with the player.
    pub vehicle: AreMiniGameVehicle,
    /// Enemy-only flag (`Trigger`), default `0`.
    ///
    /// The one field an enemy reads beyond the shared base. Unlike the
    /// carry-over fields there, the default is applied unconditionally: the
    /// read's presence flag is never inspected, so an absent `Trigger` lands
    /// as `0` exactly as if the file had written one.
    ///
    /// Kept as the byte the file holds rather than narrowed to a `bool`, even
    /// though vanilla only ever writes `0` or `1` and the module models its
    /// other byte flags as `bool`. The spec records the type and the default
    /// and says nothing about the value being interpreted as a flag, so
    /// narrowing would turn a `2` into a `1` on write on the strength of a
    /// guess about the name. The range vanilla happens to use is evidence
    /// about vanilla's content, not about the field's domain.
    ///
    /// The inconsistency with this module's six `bool` fields runs the other
    /// way from how it looks, and it is deliberate. `DoBumping`,
    /// `UseInertia`, `CameraRotate`, `RotatingModel`, `FlipAxisX` and
    /// `FlipAxisY` appear nowhere in the minigame or ARE specs: they predate
    /// the audit that covered this subsystem, so each is a `bool` on the
    /// strength of its name alone. `Trigger` is the one with a traced read.
    /// Do not "fix" it to match them.
    ///
    /// Left as is rather than widened, because a corpus round-trip reports no
    /// changed values across ARE, which means no vanilla file carries a value
    /// outside `0`/`1` in any of the six. The narrowing is lossless against
    /// real content and latent rather than live, so this is a note and a
    /// cheap future audit question, not a defect.
    pub trigger: u8,
}

impl AreMiniGameEnemy {
    fn from_struct(structure: &GffStruct) -> Result<Self, AreError> {
        Ok(Self {
            vehicle: AreMiniGameVehicle::from_struct(structure, &ENEMY_PATHS)?,
            trigger: get_u8(structure, "Trigger").unwrap_or(0),
        })
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        self.vehicle.write_into(&mut s);
        upsert_field(&mut s, "Trigger", GffValue::UInt8(self.trigger));
        s
    }
}

/// Typed view over one obstacle entry in `MiniGame.Obstacles`.
///
/// The lightest of the three object shapes. `CSWMGObstacle::Load` matches the
/// entry to an already-placed object by `Name` and reads its `Scripts` struct,
/// and nothing else: no lifecycle, no weapons, no track geometry.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AreMiniGameObstacle {
    /// Obstacle name resref (`Name`), matched against a placed object.
    pub name: ResRef,
    /// Script slots (`Scripts`), the base set with none of the vehicle
    /// additions.
    pub scripts: AreMiniGameObjectScripts,
}

impl AreMiniGameObstacle {
    fn from_struct(structure: &GffStruct) -> Result<Self, AreError> {
        let scripts = match structure.field("Scripts") {
            Some(GffValue::Struct(s)) => AreMiniGameObjectScripts::from_struct(s),
            Some(_) => {
                return Err(AreError::TypeMismatch {
                    field: "MiniGame.Obstacles[].Scripts",
                    expected: "Struct",
                });
            }
            None => AreMiniGameObjectScripts::default(),
        };

        Ok(Self {
            name: get_resref(structure, "Name").unwrap_or_default(),
            scripts,
        })
    }

    fn to_struct(&self) -> GffStruct {
        let mut s = GffStruct::new(0);
        upsert_field(&mut s, "Name", GffValue::ResRef(self.name));
        upsert_field(
            &mut s,
            "Scripts",
            GffValue::Struct(Box::new(self.scripts.to_struct())),
        );
        s
    }
}

/// One entry in a `Models` list.
static MODEL_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Model",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "RotatingModel",
        expected_type: GffType::UInt8,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// The `Scripts` struct on an obstacle: the base set and nothing else.
static OBJECT_SCRIPTS_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "OnCreate",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnHeartbeat",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnAnimEvent",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnHitBullet",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnHitFollower",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// The `Scripts` struct on a vehicle: the base set plus five.
static VEHICLE_SCRIPTS_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "OnCreate",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnHeartbeat",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnAnimEvent",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnHitBullet",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnHitFollower",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnDamage",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnDeath",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnFire",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnHitObstacle",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "OnTrackLoop",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// The `Sounds` struct on a vehicle.
static SOUNDS_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Engine",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Death",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// The `Bullet` struct inside one gun bank.
///
/// The first five are `required` because absence does something worse than
/// default: each read reports a presence flag gating the next, so one missing
/// field truncates the chain and the bank is never created. A file missing
/// `Speed` does not get a zero-speed bank, it gets no bank.
static BULLET_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Damage",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: true,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Lifespan",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: true,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Rate_Of_Fire",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: true,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Speed",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: true,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Target_Type",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: true,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Bullet_Model",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Collision_Sound",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// One entry in a `Gun_Banks` list.
///
/// `BankID` and `Gun_Model` are `required` for the same reason as the
/// `Bullet` five: an absent `BankID` resolves to the skip sentinel and an
/// invalid `Gun_Model` aborts the bank, so in both cases the bank does not
/// exist rather than existing with a default.
///
/// The four targeting fields are read only for enemies. A player's bank
/// carries none of them, which is legitimate rather than missing, so they
/// are not `required`.
static GUN_BANK_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "BankID",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: true,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Gun_Model",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: true,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Bullet",
        expected_type: GffType::Struct,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(BULLET_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Fire_Sound",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Sensing_Radius",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Horiz_Spread",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Vert_Spread",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Inaccuracy",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// The `MiniGame.Player` struct: the shared vehicle set plus the camera
/// and the movement block only the player reads.
static PLAYER_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Models",
        expected_type: GffType::List,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(MODEL_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Track",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Hit_Points",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Max_HPs",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Sphere_Radius",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Invince_Period",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Bump_Damage",
        expected_type: GffType::Int32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Num_Loops",
        expected_type: GffType::Int32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Scripts",
        expected_type: GffType::Struct,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(VEHICLE_SCRIPTS_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Sounds",
        expected_type: GffType::Struct,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(SOUNDS_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Gun_Banks",
        expected_type: GffType::List,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(GUN_BANK_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Camera",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "CameraRotate",
        expected_type: GffType::UInt8,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Minimum_Speed",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Maximum_Speed",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Accel_Secs",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "TunnelXPos",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "TunnelXNeg",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "TunnelYPos",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "TunnelYNeg",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "TunnelZPos",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "TunnelZNeg",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "TunnelInfinite",
        expected_type: GffType::Vector3,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Start_Offset_X",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Start_Offset_Y",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Start_Offset_Z",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Target_Offset_X",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Target_Offset_Y",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Target_Offset_Z",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// One `MiniGame.Enemies` entry: the shared vehicle set plus `Trigger`.
static ENEMY_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Models",
        expected_type: GffType::List,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(MODEL_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Track",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Hit_Points",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Max_HPs",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Sphere_Radius",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Invince_Period",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Bump_Damage",
        expected_type: GffType::Int32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Num_Loops",
        expected_type: GffType::Int32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Scripts",
        expected_type: GffType::Struct,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(VEHICLE_SCRIPTS_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Sounds",
        expected_type: GffType::Struct,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(SOUNDS_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Gun_Banks",
        expected_type: GffType::List,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(GUN_BANK_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Trigger",
        expected_type: GffType::UInt8,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// One `MiniGame.Obstacles` entry.
static OBSTACLE_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Name",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Scripts",
        expected_type: GffType::Struct,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(OBJECT_SCRIPTS_CHILDREN),
        constraint: None,
    },
];

/// The `MiniGame.Mouse` struct.
static MOUSE_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "AxisX",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "AxisY",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "FlipAxisX",
        expected_type: GffType::UInt8,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "FlipAxisY",
        expected_type: GffType::UInt8,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
];

/// ARE `MiniGame` struct child schema.
pub(crate) static MINI_GAME_CHILDREN: &[FieldSchema] = &[
    FieldSchema {
        label: "Type",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "MovementPerSec",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "LateralAccel",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Bump_Plane",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "DoBumping",
        expected_type: GffType::UInt8,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "UseInertia",
        expected_type: GffType::UInt8,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "DOF",
        expected_type: GffType::UInt32,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Music",
        expected_type: GffType::ResRef,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Far_Clip",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Near_Clip",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "CameraViewAngle",
        expected_type: GffType::Single,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: None,
        constraint: None,
    },
    FieldSchema {
        label: "Player",
        expected_type: GffType::Struct,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(PLAYER_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Mouse",
        expected_type: GffType::Struct,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(MOUSE_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Enemies",
        expected_type: GffType::List,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(ENEMY_CHILDREN),
        constraint: None,
    },
    FieldSchema {
        label: "Obstacles",
        expected_type: GffType::List,
        life: FieldLife::Live,
        required: false,
        absent: AbsentDefault::Unverified,
        children: Some(OBSTACLE_CHILDREN),
        constraint: None,
    },
];

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

    use crate::are::{read_are_from_bytes, write_are_to_vec, Are};
    use rakata_formats::Gff;

    /// Asserts every label the writer emits is declared in the schema at the
    /// level it lands on.
    ///
    /// Recursion only happens where a schema entry declares `children`, so a
    /// level with `children: None` is skipped rather than failed. That keeps
    /// the guard honest while the subsystem's child schemas are still being
    /// filled in: it covers exactly the levels that claim to be covered.
    fn assert_declared(structure: &GffStruct, schema: &[FieldSchema], path: &str) {
        for field in &structure.fields {
            let entry = schema
                .iter()
                .find(|f| f.label == field.label.as_str())
                .unwrap_or_else(|| {
                    panic!("{path}.{} is written but not in the schema", field.label)
                });
            let child_path = format!("{path}.{}", field.label);
            match (&field.value, entry.children) {
                (GffValue::Struct(inner), Some(children)) => {
                    assert_declared(inner, children, &child_path);
                }
                (GffValue::List(items), Some(children)) => {
                    for item in items {
                        assert_declared(item, children, &child_path);
                    }
                }
                _ => {}
            }
        }
    }

    #[test]
    fn every_written_minigame_label_is_in_the_schema() {
        // Every optional struct present and every list non-empty, because a
        // default value leaves the lists empty and the walk then stops above
        // the levels this is meant to cover. The `Bullet` and targeting
        // levels sit four deep and are only reachable through a populated
        // gun bank.
        let vehicle = || AreMiniGameVehicle {
            models: vec![AreMiniGameModel::default()],
            gun_banks: vec![AreMiniGameGunBank {
                bullet: Some(AreMiniGameBullet::default()),
                targeting: Some(AreMiniGameTargeting::default()),
                ..AreMiniGameGunBank::default()
            }],
            ..AreMiniGameVehicle::default()
        };
        let mini_game = AreMiniGame {
            player: Some(AreMiniGamePlayer {
                vehicle: vehicle(),
                ..AreMiniGamePlayer::default()
            }),
            mouse: Some(AreMiniGameMouse::default()),
            enemies: vec![AreMiniGameEnemy {
                vehicle: vehicle(),
                trigger: 1,
            }],
            obstacles: vec![AreMiniGameObstacle::default()],
            ..AreMiniGame::default()
        };

        let written = mini_game.to_struct();
        // Assert the walk reaches the deepest level before trusting that it
        // found nothing there. A guard that passes by stopping early is the
        // failure this whole batch keeps running into.
        let deepest = written
            .field("Player")
            .and_then(|v| match v {
                GffValue::Struct(p) => p.field("Gun_Banks"),
                _ => None,
            })
            .and_then(|v| match v {
                GffValue::List(banks) => banks.first().and_then(|b| b.field("Bullet")),
                _ => None,
            });
        assert!(
            matches!(deepest, Some(GffValue::Struct(_))),
            "the fixture must reach MiniGame.Player.Gun_Banks[].Bullet"
        );

        assert_declared(&written, MINI_GAME_CHILDREN, "MiniGame");
    }

    #[test]
    fn type_mismatch_on_mini_game_field_is_error() {
        let mut root = GffStruct::new(-1);
        root.push_field("MiniGame", GffValue::UInt32(7));
        let gff = Gff::new(*b"ARE ", root);
        let err = Are::from_gff(&gff).expect_err("must fail");
        assert!(matches!(
            err,
            AreError::TypeMismatch {
                field: "MiniGame",
                expected: "Struct"
            }
        ));
    }

    #[test]
    fn mini_game_struct_roundtrips() {
        let mg = AreMiniGame {
            mini_game_type: 1,
            movement_per_sec: 25.0,
            lateral_accel: 45.0,
            bump_plane: 2,
            do_bumping: true,
            use_inertia: true,
            dof: 3,
            music: ResRef::new("mus_swoop").expect("valid test resref"),
            far_clip: 200.0,
            near_clip: 0.5,
            camera_view_angle: 70.0,
            player: Some(AreMiniGamePlayer {
                vehicle: AreMiniGameVehicle {
                    models: vec![AreMiniGameModel {
                        model: ResRef::new("swoopbike").expect("valid test resref"),
                        rotating_model: false,
                    }],
                    track: ResRef::new("trk_race01").expect("valid test resref"),
                    hit_points: 120,
                    max_hps: 150,
                    sphere_radius: 4.5,
                    invince_period: 0.75,
                    bump_damage: 9,
                    num_loops: 3,
                    scripts: AreMiniGameVehicleScripts {
                        object: AreMiniGameObjectScripts {
                            on_heartbeat: ResRef::new("mg_beat").expect("valid test resref"),
                            ..AreMiniGameObjectScripts::default()
                        },
                        on_fire: ResRef::new("mg_fire").expect("valid test resref"),
                        ..AreMiniGameVehicleScripts::default()
                    },
                    sounds: AreMiniGameSounds {
                        engine: ResRef::new("snd_engine").expect("valid test resref"),
                        death: ResRef::new("snd_boom").expect("valid test resref"),
                    },
                    gun_banks: vec![AreMiniGameGunBank {
                        bank_id: 0,
                        gun_model: ResRef::new("mgg_turret").expect("valid test resref"),
                        bullet: Some(AreMiniGameBullet {
                            damage: 30,
                            speed: 300.0,
                            ..AreMiniGameBullet::default()
                        }),
                        ..AreMiniGameGunBank::default()
                    }],
                },
                camera: ResRef::new("cam_swoop").expect("valid test resref"),
                camera_rotate: true,
                ..AreMiniGamePlayer::default()
            }),
            // Siblings of `Player`, matching where the files put them.
            mouse: Some(AreMiniGameMouse {
                axis_x: 1,
                axis_y: 2,
                flip_axis_x: true,
                flip_axis_y: false,
            }),
            enemies: vec![AreMiniGameEnemy {
                vehicle: AreMiniGameVehicle {
                    track: ResRef::new("trk_enemy01").expect("valid test resref"),
                    hit_points: 40,
                    max_hps: 40,
                    sphere_radius: 2.0,
                    num_loops: -1,
                    ..AreMiniGameVehicle::default()
                },
                trigger: 1,
            }],
            obstacles: vec![AreMiniGameObstacle {
                name: ResRef::new("obs_rock").expect("valid test resref"),
                scripts: AreMiniGameObjectScripts {
                    on_hit_follower: ResRef::new("mg_bump").expect("valid test resref"),
                    ..AreMiniGameObjectScripts::default()
                },
            }],
        };

        let mut are = Are::new();
        are.mini_game = Some(mg);

        let encoded = write_are_to_vec(&are).expect("encode");
        let reparsed = read_are_from_bytes(&encoded).expect("decode");

        let mg_out = reparsed.mini_game.expect("MiniGame must survive roundtrip");
        assert_eq!(mg_out.mini_game_type, 1);
        assert!((mg_out.movement_per_sec - 25.0).abs() < f32::EPSILON);
        assert!((mg_out.lateral_accel - 45.0).abs() < f32::EPSILON);
        assert_eq!(mg_out.bump_plane, 2);
        assert!(mg_out.do_bumping);
        assert!(mg_out.use_inertia);
        assert_eq!(mg_out.dof, 3);
        assert_eq!(mg_out.music, "mus_swoop");
        assert!((mg_out.far_clip - 200.0).abs() < f32::EPSILON);
        assert!((mg_out.near_clip - 0.5).abs() < f32::EPSILON);
        assert!((mg_out.camera_view_angle - 70.0).abs() < f32::EPSILON);

        let player = mg_out.player.expect("Player must survive roundtrip");
        assert_eq!(player.vehicle.models.len(), 1);
        assert_eq!(player.vehicle.models[0].model, "swoopbike");
        assert!(!player.vehicle.models[0].rotating_model);
        assert_eq!(player.vehicle.track, "trk_race01");
        assert_eq!(player.vehicle.hit_points, 120);
        assert_eq!(player.vehicle.max_hps, 150);
        assert!((player.vehicle.sphere_radius - 4.5).abs() < f32::EPSILON);
        assert!((player.vehicle.invince_period - 0.75).abs() < f32::EPSILON);
        assert_eq!(player.vehicle.bump_damage, 9);
        assert_eq!(player.vehicle.num_loops, 3);
        assert_eq!(player.vehicle.scripts.object.on_heartbeat, "mg_beat");
        assert_eq!(player.vehicle.scripts.on_fire, "mg_fire");
        assert_eq!(player.vehicle.sounds.engine, "snd_engine");
        assert_eq!(player.vehicle.sounds.death, "snd_boom");
        assert_eq!(player.camera, "cam_swoop");
        assert!(player.camera_rotate);
        let mouse = mg_out.mouse.as_ref().expect("Mouse must survive roundtrip");
        assert_eq!(mouse.axis_x, 1);
        assert_eq!(mouse.axis_y, 2);
        assert!(mouse.flip_axis_x);
        assert!(!mouse.flip_axis_y);
        assert_eq!(mg_out.enemies.len(), 1);
        assert!(mg_out.enemies[0].vehicle.models.is_empty());
        assert_eq!(mg_out.enemies[0].vehicle.track, "trk_enemy01");
        assert_eq!(mg_out.enemies[0].vehicle.hit_points, 40);
        assert_eq!(mg_out.enemies[0].vehicle.num_loops, -1);
        assert_eq!(mg_out.obstacles.len(), 1);
        assert_eq!(mg_out.obstacles[0].name, "obs_rock");
        assert_eq!(mg_out.obstacles[0].scripts.on_hit_follower, "mg_bump");

        // Pin the level, not just the round-trip. The reader looked these up
        // on `Player` for as long as the type existed, which read every
        // vanilla minigame as having no enemies and no obstacles at all. A
        // round-trip could not catch it: nothing was read, so nothing was
        // written, and the two agreed.
        let encoded_gff = are.to_gff();
        let Some(GffValue::Struct(mini_game)) = encoded_gff.root.field("MiniGame") else {
            panic!("MiniGame must be a struct");
        };
        for label in ["Mouse", "Enemies", "Obstacles"] {
            assert!(
                mini_game.field(label).is_some(),
                "{label} belongs on MiniGame"
            );
        }
        let Some(GffValue::Struct(player_struct)) = mini_game.field("Player") else {
            panic!("Player must be a struct");
        };
        for label in ["Mouse", "Enemies", "Obstacles"] {
            assert!(
                player_struct.field(label).is_none(),
                "{label} must not be written under Player"
            );
        }
    }

    #[test]
    fn a_gun_bank_without_a_bullet_stays_without_one() {
        // The engine skips a bank with no `Bullet`. Materialising an all-zero
        // one on read and writing it back would turn a bank the engine drops
        // into a bank it creates, firing zero-speed bullets. The round-trip
        // would look stable the whole time.
        let bank = AreMiniGameGunBank::from_struct(&GffStruct::new(0), "test.Bullet")
            .expect("a bank with no fields still parses");
        assert!(bank.bullet.is_none());
        assert_eq!(bank.bank_id, BANK_ID_NONE);

        let written = bank.to_struct();
        assert!(
            written.field("Bullet").is_none(),
            "an absent Bullet must not be invented on write"
        );
    }

    #[test]
    fn targeting_needs_all_four_labels_to_count_as_present() {
        // The engine reads the four as a presence-gated chain and aborts the
        // bank if one is missing, so three of four describes a bank that gets
        // dropped. Reporting that as a working targeting group would claim
        // the file says something it does not.
        let mut partial = GffStruct::new(0);
        partial.push_field("Sensing_Radius", GffValue::Single(200.0));
        partial.push_field("Horiz_Spread", GffValue::Single(70.0));
        partial.push_field("Vert_Spread", GffValue::Single(70.0));
        let bank = AreMiniGameGunBank::from_struct(&partial, "test.Bullet").expect("parses");
        assert!(bank.targeting.is_none(), "three of four is not a set");

        let mut full = partial.clone();
        full.push_field("Inaccuracy", GffValue::Single(0.01));
        let bank = AreMiniGameGunBank::from_struct(&full, "test.Bullet").expect("parses");
        let targeting = bank.targeting.expect("all four present");
        assert!((targeting.sensing_radius - 200.0).abs() < f32::EPSILON);
        assert!((targeting.inaccuracy - 0.01).abs() < f32::EPSILON);

        // A player bank carries none of them and must not gain four zeroes.
        let player_bank =
            AreMiniGameGunBank::from_struct(&GffStruct::new(0), "test.Bullet").expect("parses");
        let written = player_bank.to_struct();
        for label in AreMiniGameTargeting::LABELS {
            assert!(
                written.field(label).is_none(),
                "{label} belongs to enemy banks only"
            );
        }
    }

    #[test]
    fn the_player_movement_block_round_trips_and_defaults_to_its_sentinels() {
        // Three of these default to something other than zero, and two of the
        // three are sentinels meaning "leave the constructed value alone". A
        // player struct with none of them set must come back saying that,
        // not saying the vehicle has a zero speed range.
        let bare = AreMiniGamePlayer::from_struct(&GffStruct::new(0)).expect("parses");
        assert!((bare.minimum_speed - -1.0).abs() < f32::EPSILON);
        assert!((bare.maximum_speed - 100.0).abs() < f32::EPSILON);
        assert!((bare.accel_secs - -1.0).abs() < f32::EPSILON);
        assert_eq!(bare.tunnel_infinite, [0.0; 3]);

        let player = AreMiniGamePlayer {
            minimum_speed: 5.0,
            maximum_speed: 42.5,
            accel_secs: 2.5,
            tunnel_x_pos: 45.0,
            tunnel_x_neg: 2.0,
            tunnel_y_pos: 3.0,
            tunnel_y_neg: 4.0,
            tunnel_z_pos: 9999.0,
            tunnel_z_neg: -9999.0,
            tunnel_infinite: [0.0, 0.0, 1.0],
            start_offset_x: 7.0,
            start_offset_y: 8.0,
            start_offset_z: 9.0,
            target_offset_x: 10.0,
            target_offset_y: 11.0,
            target_offset_z: -5.0,
            ..AreMiniGamePlayer::default()
        };

        let back = AreMiniGamePlayer::from_struct(&player.to_struct()).expect("parses");
        assert_eq!(back, player);

        // `TunnelInfinite` is a GFF vector while the bounds it modifies are
        // separate floats, so the writer has to keep them different shapes.
        let written = player.to_struct();
        assert!(matches!(
            written.field("TunnelInfinite"),
            Some(GffValue::Vector3([0.0, 0.0, 1.0]))
        ));
        assert!(matches!(
            written.field("TunnelZPos"),
            Some(GffValue::Single(_))
        ));
    }

    #[test]
    fn an_obstacle_writes_the_base_script_set_and_no_vehicle_slots() {
        // `CSWMGObstacle::Load` goes through the base LoadScripts, so the five
        // slots the track-follower override adds have no reader on an
        // obstacle. Writing them would put labels in the file that the engine
        // never looks for, and the corpus agrees: no vanilla obstacle carries
        // one. A round-trip cannot catch this on its own, since an invented
        // label reads back as whatever was invented.
        let mut are = Are::new();
        are.mini_game = Some(AreMiniGame {
            obstacles: vec![AreMiniGameObstacle::default()],
            ..AreMiniGame::default()
        });

        let encoded = are.to_gff();
        let Some(GffValue::Struct(mini_game)) = encoded.root.field("MiniGame") else {
            panic!("MiniGame must be a struct");
        };
        let Some(GffValue::List(obstacles)) = mini_game.field("Obstacles") else {
            panic!("Obstacles must be a list");
        };
        let Some(GffValue::Struct(scripts)) = obstacles[0].field("Scripts") else {
            panic!("an obstacle must carry a Scripts struct");
        };

        for label in [
            "OnCreate",
            "OnHeartbeat",
            "OnAnimEvent",
            "OnHitBullet",
            "OnHitFollower",
        ] {
            assert!(
                scripts.field(label).is_some(),
                "{label} is in the base script set"
            );
        }
        for label in [
            "OnDamage",
            "OnDeath",
            "OnFire",
            "OnHitObstacle",
            "OnTrackLoop",
        ] {
            assert!(
                scripts.field(label).is_none(),
                "{label} belongs to the vehicle override, not an obstacle"
            );
        }
    }

    #[test]
    fn an_area_without_a_mouse_struct_does_not_gain_one() {
        // Three of the four vanilla minigame areas carry no `Mouse`. Writing
        // an all-zero one back would invent structure they never had, which a
        // defaulted field rather than an `Option` would do silently.
        let mut are = Are::new();
        are.mini_game = Some(AreMiniGame {
            mouse: None,
            ..AreMiniGame::default()
        });

        let encoded = are.to_gff();
        let Some(GffValue::Struct(mini_game)) = encoded.root.field("MiniGame") else {
            panic!("MiniGame must be a struct");
        };
        assert!(mini_game.field("Mouse").is_none());

        let reparsed = Are::from_gff(&encoded).expect("parses");
        assert!(reparsed.mini_game.expect("minigame").mouse.is_none());
    }
}