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.
//! `Enemies` and `Obstacles` are engine-attested; `Mouse` sits alongside them
//! in the one vanilla file carrying it, but its loader path is untraced, so
//! that level rests on the data alone.
//!
//! The nesting was wrong here for a while, which read every enemy and obstacle
//! in the game as absent. `docs/src/internals/minigame_deep_dive.md` has the
//! structure and what the engine does with each, and
//! `docs/src/testing.md` uses the mistake as its worked example of a test that
//! repeats the code's own misreading.

use rakata_core::ResRef;
use rakata_formats::{GffModel, GffStruct};

/// Typed view over the ARE `MiniGame` nested struct.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct AreMiniGame {
    /// Mini-game type (`Type`): 1 = swoop, 2 = turret.
    #[gff(Type, unexamined)]
    pub mini_game_type: u32,
    /// Movement speed (`MovementPerSec`).
    #[gff(MovementPerSec, unexamined)]
    pub movement_per_sec: f32,
    /// Lateral acceleration (`LateralAccel`).
    #[gff(LateralAccel, unexamined = 60.0)]
    pub lateral_accel: f32,
    /// Bump plane index (`Bump_Plane`).
    #[gff(Bump_Plane, unexamined)]
    pub bump_plane: u32,
    /// Bumping enabled (`DoBumping`).
    #[gff(DoBumping, unexamined)]
    pub do_bumping: bool,
    /// Inertia enabled (`UseInertia`).
    #[gff(UseInertia, unexamined)]
    pub use_inertia: bool,
    /// Degrees of freedom (`DOF`).
    #[gff(DOF, unexamined)]
    pub dof: u32,
    /// Music resref (`Music`).
    #[gff(Music, unexamined)]
    pub music: ResRef,
    /// Far clip distance (`Far_Clip`).
    #[gff(Far_Clip, unexamined = 100.0)]
    pub far_clip: f32,
    /// Near clip distance (`Near_Clip`).
    #[gff(Near_Clip, unexamined = 0.1)]
    pub near_clip: f32,
    /// Camera view angle (`CameraViewAngle`).
    #[gff(CameraViewAngle, unexamined = 65.0)]
    pub camera_view_angle: f32,
    /// Player sub-struct (`Player`).
    #[gff(Player, unexamined, nested = AreMiniGamePlayer, optional)]
    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.
    #[gff(Mouse, not_a_constant, nested = AreMiniGameMouse, optional)]
    pub mouse: Option<AreMiniGameMouse>,
    /// Enemy list (`Enemies`), a sibling of `Player`.
    #[gff(Enemies, unexamined, list = AreMiniGameEnemy, element_id = 0)]
    pub enemies: Vec<AreMiniGameEnemy>,
    /// Obstacle list (`Obstacles`), a sibling of `Player`.
    #[gff(Obstacles, unexamined, list = AreMiniGameObstacle, element_id = 0)]
    pub obstacles: Vec<AreMiniGameObstacle>,
}

/// 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, GffModel)]
pub struct AreMiniGameObjectScripts {
    /// Fired when the object is created (`OnCreate`).
    #[gff(OnCreate, stamped)]
    pub on_create: ResRef,
    /// Fired on the object's heartbeat (`OnHeartbeat`).
    #[gff(OnHeartbeat, stamped)]
    pub on_heartbeat: ResRef,
    /// Fired on a model animation event (`OnAnimEvent`).
    #[gff(OnAnimEvent, stamped)]
    pub on_anim_event: ResRef,
    /// Fired when a bullet hits the object (`OnHitBullet`).
    #[gff(OnHitBullet, stamped)]
    pub on_hit_bullet: ResRef,
    /// Fired when a track follower hits the object (`OnHitFollower`).
    #[gff(OnHitFollower, stamped)]
    pub on_hit_follower: ResRef,
}

/// 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, GffModel)]
pub struct AreMiniGameVehicleScripts {
    /// The slots shared with obstacles.
    #[gff(flatten = AreMiniGameObjectScripts)]
    pub object: AreMiniGameObjectScripts,
    /// Fired when the vehicle takes damage (`OnDamage`).
    #[gff(OnDamage, stamped)]
    pub on_damage: ResRef,
    /// Fired when the vehicle is destroyed (`OnDeath`).
    #[gff(OnDeath, stamped)]
    pub on_death: ResRef,
    /// Fired when the vehicle fires a gun bank (`OnFire`).
    #[gff(OnFire, stamped)]
    pub on_fire: ResRef,
    /// Fired when the vehicle hits an obstacle (`OnHitObstacle`).
    #[gff(OnHitObstacle, stamped)]
    pub on_hit_obstacle: ResRef,
    /// Fired each time the vehicle completes a track loop (`OnTrackLoop`).
    #[gff(OnTrackLoop, stamped)]
    pub on_track_loop: ResRef,
}

/// 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, GffModel)]
pub struct AreMiniGameSounds {
    /// Looping engine sound (`Engine`).
    #[gff(Engine, stamped)]
    pub engine: ResRef,
    /// One-shot destruction sound (`Death`).
    #[gff(Death, stamped)]
    pub death: ResRef,
}

/// 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, GffModel)]
pub struct AreMiniGameBullet {
    /// Damage per hit (`Damage`).
    #[gff(Damage, required, not_a_constant)]
    pub damage: u32,
    /// Seconds before the bullet expires (`Lifespan`).
    #[gff(Lifespan, required, not_a_constant)]
    pub lifespan: f32,
    /// Seconds between shots (`Rate_Of_Fire`).
    #[gff(Rate_Of_Fire, required, not_a_constant)]
    pub rate_of_fire: f32,
    /// Travel speed (`Speed`).
    #[gff(Speed, required, not_a_constant)]
    pub speed: f32,
    /// What the bank is allowed to shoot at (`Target_Type`).
    #[gff(Target_Type, required, not_a_constant)]
    pub target_type: u32,
    /// Bullet model resref (`Bullet_Model`).
    #[gff(Bullet_Model, stamped)]
    pub bullet_model: ResRef,
    /// Sound played on impact (`Collision_Sound`).
    #[gff(Collision_Sound, stamped)]
    pub collision_sound: ResRef,
}

/// 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, GffModel)]
pub struct AreMiniGameTargeting {
    /// How far the bank looks for a target (`Sensing_Radius`).
    #[gff(Sensing_Radius, not_a_constant)]
    pub sensing_radius: f32,
    /// Horizontal firing arc (`Horiz_Spread`).
    #[gff(Horiz_Spread, not_a_constant)]
    pub horiz_spread: f32,
    /// Vertical firing arc (`Vert_Spread`).
    #[gff(Vert_Spread, not_a_constant)]
    pub vert_spread: f32,
    /// How far shots stray from the target (`Inaccuracy`).
    #[gff(Inaccuracy, not_a_constant)]
    pub inaccuracy: f32,
}

impl AreMiniGameTargeting {
    /// The four labels, 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 read_group(structure: &GffStruct) -> Option<Self> {
        Self::LABELS
            .iter()
            .all(|label| structure.field(label).is_some())
            .then(|| Self::read_declared(structure))
    }
}

/// One entry in a vehicle's `Gun_Banks` list.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct AreMiniGameGunBank {
    /// Which hardpoint this bank occupies (`BankID`).
    ///
    /// [`BANK_ID_NONE`] means the engine skips the bank entirely.
    #[gff(BankID, required, stamped = 4294967295)]
    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.
    #[gff(Gun_Model, required, not_a_constant)]
    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.
    #[gff(Bullet, unexamined, nested = AreMiniGameBullet, optional)]
    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.
    #[gff(Fire_Sound, stamped)]
    pub fire_sound: ResRef,
    /// AI aiming parameters, absent on a player's own banks.
    ///
    /// Flat on the bank entry rather than under a label of its own, so the
    /// four sit beside `Bullet` in the file. Whether the bank carries them at
    /// all is a rule no attribute states, which is why both codec halves are
    /// this type's: the engine reads the four as a presence-gated chain and
    /// drops the whole bank if one is missing, so a partial set is not a
    /// group to fill in with defaults.
    #[gff(flatten = AreMiniGameTargeting, manual_read, manual_write)]
    pub targeting: Option<AreMiniGameTargeting>,
}

impl AreMiniGameGunBank {
    /// Reads one `Gun_Banks` element.
    ///
    /// The derive supplies neither element half for a type with a
    /// hand-written codec, so the targeting group's presence rule lives here.
    fn read_element(structure: &GffStruct) -> Self {
        Self {
            targeting: AreMiniGameTargeting::read_group(structure),
            ..Self::read_declared(structure)
        }
    }

    /// Writes one `Gun_Banks` element.
    fn write_element(&self, structure: &mut GffStruct) {
        self.write_declared(structure);
        if let Some(targeting) = &self.targeting {
            targeting.write_element(structure);
        }
    }
}

/// 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, GffModel)]
pub struct AreMiniGameVehicle {
    /// Model list (`Models`).
    #[gff(Models, unexamined, list = AreMiniGameModel, element_id = 0)]
    pub models: Vec<AreMiniGameModel>,
    /// Track resref (`Track`) the vehicle follows.
    #[gff(Track, unexamined)]
    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".
    #[gff(Hit_Points, unanswered)]
    pub hit_points: u32,
    /// Maximum hit points (`Max_HPs`), gated the same way as [`Self::hit_points`].
    #[gff(Max_HPs, unanswered)]
    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.
    #[gff(Sphere_Radius, unanswered = -1.0)]
    pub sphere_radius: f32,
    /// Invulnerability window in seconds after a hit (`Invince_Period`).
    #[gff(Invince_Period, stamped)]
    pub invince_period: f32,
    /// Damage dealt to whatever this vehicle bumps into (`Bump_Damage`).
    #[gff(Bump_Damage, stamped)]
    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.
    #[gff(Num_Loops, unanswered = -10)]
    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.
    #[gff(Scripts, unexamined, nested = AreMiniGameVehicleScripts)]
    pub scripts: AreMiniGameVehicleScripts,
    /// Engine and destruction sounds (`Sounds`), on the same footing as
    /// [`Self::scripts`].
    #[gff(Sounds, unexamined, nested = AreMiniGameSounds)]
    pub sounds: AreMiniGameSounds,
    /// Weapon hardpoints (`Gun_Banks`).
    #[gff(Gun_Banks, unexamined, list = AreMiniGameGunBank, element_id = 0)]
    pub gun_banks: Vec<AreMiniGameGunBank>,
}

/// Typed view over the `MiniGame.Player` sub-struct.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct AreMiniGamePlayer {
    /// The vehicle fields shared with every enemy.
    #[gff(flatten = AreMiniGameVehicle)]
    pub vehicle: AreMiniGameVehicle,
    /// Camera resref (`Camera`) - only used for turret type (type 2).
    #[gff(Camera, unexamined)]
    pub camera: ResRef,
    /// Camera rotation flag (`CameraRotate`).
    #[gff(CameraRotate, unexamined)]
    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.
    #[gff(Minimum_Speed, unanswered = -1.0)]
    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.
    #[gff(Maximum_Speed, stamped = 100.0)]
    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.
    #[gff(Accel_Secs, not_a_constant = -1.0)]
    pub accel_secs: f32,
    /// Positive-X track boundary (`TunnelXPos`).
    #[gff(TunnelXPos, stamped)]
    pub tunnel_x_pos: f32,
    /// Negative-X track boundary (`TunnelXNeg`).
    #[gff(TunnelXNeg, stamped)]
    pub tunnel_x_neg: f32,
    /// Positive-Y track boundary (`TunnelYPos`).
    #[gff(TunnelYPos, unexamined)]
    pub tunnel_y_pos: f32,
    /// Negative-Y track boundary (`TunnelYNeg`).
    #[gff(TunnelYNeg, unexamined)]
    pub tunnel_y_neg: f32,
    /// Positive-Z track boundary (`TunnelZPos`).
    #[gff(TunnelZPos, stamped)]
    pub tunnel_z_pos: f32,
    /// Negative-Z track boundary (`TunnelZNeg`).
    #[gff(TunnelZNeg, stamped)]
    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.
    #[gff(TunnelInfinite, unexamined)]
    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.
    #[gff(Start_Offset_X, stamped)]
    pub start_offset_x: f32,
    /// Start position Y offset (`Start_Offset_Y`).
    #[gff(Start_Offset_Y, stamped)]
    pub start_offset_y: f32,
    /// Start position Z offset (`Start_Offset_Z`).
    #[gff(Start_Offset_Z, stamped)]
    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.
    #[gff(Target_Offset_X, stamped)]
    pub target_offset_x: f32,
    /// Camera target Y offset (`Target_Offset_Y`).
    #[gff(Target_Offset_Y, stamped)]
    pub target_offset_y: f32,
    /// Camera target Z offset (`Target_Offset_Z`).
    #[gff(Target_Offset_Z, stamped)]
    pub target_offset_z: f32,
}

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

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

/// Typed view over one enemy entry in `MiniGame.Enemies`.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct AreMiniGameEnemy {
    /// The vehicle fields shared with the player.
    #[gff(flatten = AreMiniGameVehicle)]
    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.
    #[gff(Trigger, stamped)]
    pub trigger: u8,
}

/// 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, GffModel)]
pub struct AreMiniGameObstacle {
    /// Obstacle name resref (`Name`), matched against a placed object.
    #[gff(Name, unexamined)]
    pub name: ResRef,
    /// Script slots (`Scripts`), the base set with none of the vehicle
    /// additions.
    #[gff(Scripts, unexamined, nested = AreMiniGameObjectScripts)]
    pub scripts: AreMiniGameObjectScripts,
}

#[cfg(test)]
mod tests {
    use rakata_formats::schema::{Field, Shape};
    use rakata_formats::{gff_label, GffValue};

    /// One value written into a struct of its own, which is what the old
    /// `to_struct` pair returned.
    macro_rules! written_struct {
        ($value:expr) => {{
            let mut structure = GffStruct::new(0);
            $value.write_element(&mut structure);
            structure
        }};
    }

    use super::*;

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

    /// Asserts every label the writer emits is declared at the level it lands
    /// on.
    ///
    /// A container references its child's parts, so a flattened grandchild's
    /// fields are in the walk. Recursion stops where a container declares no
    /// child schema, which is the view modelling nothing behind it rather
    /// than a level going unchecked.
    fn assert_declared(structure: &GffStruct, parts: &[&[Field]], path: &str) {
        for field in &structure.fields {
            let entry = parts
                .iter()
                .flat_map(|part| part.iter())
                .find(|f| f.label.as_str() == 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.shape) {
                (GffValue::Struct(inner), Shape::Struct { fields }) if !fields.is_empty() => {
                    assert_declared(inner, fields, &child_path);
                }
                (GffValue::List(items), Shape::List { element, .. }) if !element.is_empty() => {
                    for item in items {
                        assert_declared(item, element, &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 mut written = GffStruct::new(0);
        mini_game.write_element(&mut written);
        // 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, AreMiniGame::PARTS, "MiniGame");
    }

    #[test]
    fn a_mistyped_mini_game_field_reads_as_absent() {
        let mut root = GffStruct::new(-1);
        root.push_field(gff_label!("MiniGame"), GffValue::UInt32(7));
        let gff = Gff::new(*b"ARE ", root);

        let are = Are::from_gff(&gff).expect("a mistyped field is not a read failure");

        assert!(are.mini_game.is_none());
    }

    #[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 = author_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::read_element(&GffStruct::new(0));
        assert!(bank.bullet.is_none());
        assert_eq!(bank.bank_id, BANK_ID_NONE);

        let written = written_struct!(bank);
        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(gff_label!("Sensing_Radius"), GffValue::Single(200.0));
        partial.push_field(gff_label!("Horiz_Spread"), GffValue::Single(70.0));
        partial.push_field(gff_label!("Vert_Spread"), GffValue::Single(70.0));
        let bank = AreMiniGameGunBank::read_element(&partial);
        assert!(bank.targeting.is_none(), "three of four is not a set");

        let mut full = partial.clone();
        full.push_field(gff_label!("Inaccuracy"), GffValue::Single(0.01));
        let bank = AreMiniGameGunBank::read_element(&full);
        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::read_element(&GffStruct::new(0));
        let written = written_struct!(player_bank);
        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::read_element(&GffStruct::new(0));
        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::read_element(&written_struct!(player));
        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 = written_struct!(player);
        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());
    }
}