rakata_generics/git/

trigger.rs

//! Trigger placements in a GIT.

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

use crate::git::blocks::{SavedPortrait, SavedPortraitLabels};
use crate::shared::ObjectId;
use crate::utt::UttGeometryPoint;

/// The part of a `trigger` entry that is what every trigger entry carries, whichever form it takes.
///
/// Both arms flatten it and the list's element is it, so the labels here
/// are one declaration reached from both forms rather than two copies.
#[derive(Debug, Clone, PartialEq, GffModel)]
pub struct GitTriggerCommon {
    /// Linked-to tag (`LinkedTo`). Waypoint tag in the target module.
    #[gff(LinkedTo, not_a_constant)]
    pub linked_to: String,
    /// Linked-to flags (`LinkedToFlags`).
    #[gff(LinkedToFlags, not_a_constant)]
    pub linked_to_flags: u8,
    /// Linked module resref (`LinkedToModule`). Area transition target.
    #[gff(LinkedToModule, not_a_constant)]
    pub linked_to_module: ResRef,
    /// Runtime object ID (`ObjectId`). Save-game only.
    /// Runtime object id (`ObjectId`), which only a saved form carries.
    ///
    /// The area-level dispatcher reads it once per element ahead of the
    /// static-versus-saved branch, so the engine reads it on both forms and
    /// the liveness below is right. What it does not do is author it: every
    /// element the engine saves carries one and no element the toolset shipped
    /// does. Held as the absence so writing a static placement back does not
    /// invent a runtime id for it.
    #[gff(ObjectId, stamped = ObjectId::INVALID, optional = ObjectId)]
    pub object_id: Option<ObjectId>,
    /// Transition destination text (`TransitionDestin`, truncated from
    /// `TransitionDestination` by the 16-byte GFF label limit).
    #[gff(TransitionDestin, constructed)]
    pub transition_destination: GffLocalizedString,
    /// X position (`XPosition`).
    #[gff(XPosition, unexamined)]
    pub x_position: f32,
    /// Y position (`YPosition`).
    #[gff(YPosition, unexamined)]
    pub y_position: f32,
    /// Z position (`ZPosition`).
    #[gff(ZPosition, unexamined)]
    pub z_position: f32,
    /// X orientation (`XOrientation`).
    ///
    /// Every trigger in a retail install leaves the three orientation fields
    /// at zero, which is why they went unnoticed while the other object types
    /// got theirs. A trigger's shape comes from its `Geometry` polygon, so
    /// rotating one is not something vanilla content ever needed. That says
    /// nothing about a mod that does.
    #[gff(XOrientation, unexamined)]
    pub x_orientation: f32,
    /// Y orientation (`YOrientation`).
    #[gff(YOrientation, unexamined)]
    pub y_orientation: f32,
    /// Z orientation (`ZOrientation`).
    #[gff(ZOrientation, unexamined)]
    pub z_orientation: f32,
}

/// A trigger instance placed in the area (struct type 1).
///
/// Triggers carry geometry (vertex polygon) and optional area-transition
/// fields (`LinkedToModule`, `LinkedTo`, `LinkedToFlags`,
/// `TransitionDestination`).
///
/// ## `Tag` is dead here, and deliberately unmodelled
///
/// Every trigger placement that carries a `Tag` carries a real value, and the
/// engine does not read it at this path: a templated trigger takes its tag
/// from the `.utt` blueprint, with no overlay from the placement. Same
/// situation as [`GitDoor`](super::GitDoor), and the same trap. Setting it on
/// a placement looks like renaming that trigger and changes nothing.
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_manual_element]
pub struct GitTrigger {
    /// The trigger's boundary (`Geometry`).
    #[gff(Geometry, not_a_constant, list = UttGeometryPoint, element_id = 3)]
    pub geometry: Vec<UttGeometryPoint>,
    /// The block both forms carry, which the list declares as its element.
    ///
    /// No `#[gff]`: the arm contributes its parts to the split, and the
    /// element is this block, so declaring it here too would make one label
    /// two declarations. The arm's own codec reads and writes it.
    pub common: GitTriggerCommon,
    /// Template resref (`TemplateResRef`).
    #[gff(TemplateResRef, unexamined)]
    pub template_resref: ResRef,
}

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

// Triggers as stored inside a save game.
//
// A savegame trigger carries the whole object inline rather than referencing a
// `.utt`, including the polygon that defines where it fires. See
// `docs/src/formats/save/index.md` for the template-versus-snapshot rule.
//
// ## Trap fields are a subset of a door's
//
// A saved trigger writes `TrapDetectable`, `TrapDisarmable`, `TrapOneShot`
// and `TrapType`, and none of `TrapDetectDC`, `DisarmDC` or `TrapFlag`. A
// saved door writes all seven. Declaring the four here rather than reaching
// for a door's block keeps a trigger from writing back three fields the
// engine never puts on one.
//
// ## What is not modelled
//
// `ActionList`, `VarTable` and `SWVarTable` are live runtime state whose
// layouts are only partly audited, and they are skipped for the same reason
// [`SavedCreature`](crate::git::creature::SavedCreature) skips them.

/// A trigger as stored inside a save game's module `GIT`.
#[derive(Debug, Clone, PartialEq, GffModel)]
#[gff_manual_element]
pub struct SavedTrigger {
    /// Portrait, as whichever of the two labels the trigger carries.
    ///
    /// Declared per owner: the audit parts both labels from the door's and
    /// the placeable's on the absent axis.
    #[gff(flatten = SavedPortraitLabels, manual_read, manual_write)]
    pub portrait: SavedPortrait,
    /// Whether the trap can be spotted (`TrapDetectable`).
    #[gff(TrapDetectable, stamped = false)]
    pub trap_detectable: bool,
    /// Whether the trap can be disarmed (`TrapDisarmable`).
    #[gff(TrapDisarmable, stamped = false)]
    pub trap_disarmable: bool,
    /// Whether the trap fires once and clears (`TrapOneShot`).
    #[gff(TrapOneShot, constructed = true)]
    pub trap_one_shot: bool,
    /// Trap row in `traps.2da` (`TrapType`).
    #[gff(TrapType, constructed = 255)]
    pub trap_type: u8,
    /// The block both forms carry, which the list declares as its element.
    ///
    /// No `#[gff]`: the arm contributes its parts to the split, and the
    /// element is this block, so declaring it here too would make one label
    /// two declarations. The arm's own codec reads and writes it.
    pub common: GitTriggerCommon,
    /// Object tag (`Tag`).
    #[gff(
        Tag,
        read_only_dead = "a templated placement takes its tag from the blueprint, which the placement cannot override",
        unexamined
    )]
    pub tag: String,
    /// Polygon defining the trigger area (`Geometry`).
    #[gff(Geometry, not_a_constant, list = UttGeometryPoint, element_id = 3)]
    pub geometry: Vec<UttGeometryPoint>,
    /// Consume the key on use (`AutoRemoveKey`).
    #[gff(AutoRemoveKey, unexamined)]
    pub auto_remove_key: bool,
    /// Accepts scripted commands (`Commandable`).
    #[gff(Commandable, unexamined)]
    pub commandable: bool,
    /// Object that created this trigger at runtime (`CreatorId`).
    #[gff(CreatorId, unexamined)]
    pub creator_id: u32,
    /// Cursor shown over the trigger (`Cursor`).
    #[gff(Cursor, unexamined)]
    pub cursor: u8,
    /// Faction id (`Faction`).
    #[gff(Faction, unexamined)]
    pub faction: u32,
    /// Highlight rendering height (`HighlightHeight`).
    #[gff(HighlightHeight, unexamined)]
    pub highlight_height: f32,
    /// Key tag that disarms this trigger (`KeyName`).
    #[gff(KeyName, unexamined)]
    pub key_name: String,
    /// Load screen shown across the transition (`LoadScreenID`).
    #[gff(LoadScreenID, unexamined)]
    pub load_screen_id: u16,
    /// Displayed name (`LocalizedName`).
    #[gff(LocalizedName, unexamined)]
    pub localized_name: GffLocalizedString,
    /// `OnClick`.
    #[gff(OnClick, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_click: ResRef,
    /// `OnDisarm`.
    #[gff(OnDisarm, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_disarm: ResRef,
    /// `OnTrapTriggered`.
    #[gff(OnTrapTriggered, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub on_trap_triggered: ResRef,
    /// `ScriptHeartbeat`.
    #[gff(ScriptHeartbeat, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub script_heartbeat: ResRef,
    /// `ScriptOnEnter`.
    #[gff(ScriptOnEnter, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub script_on_enter: ResRef,
    /// `ScriptOnExit`.
    #[gff(ScriptOnExit, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub script_on_exit: ResRef,
    /// `ScriptUserDefine`.
    #[gff(ScriptUserDefine, constructed = ResRef::const_new("default").expect("a literal short enough for a resref"))]
    pub script_user_define: ResRef,
    /// Placed by the player party at runtime (`SetByPlayerParty`).
    #[gff(SetByPlayerParty, unexamined)]
    pub set_by_player_party: bool,
    /// Trigger kind (`Type`): generic, area transition, or trap.
    #[gff(Type, unexamined)]
    pub trigger_type: i32,
}

impl SavedTrigger {
    /// Reads one element, resolving the portrait's two labels into one value.
    pub fn read_element(structure: &GffStruct) -> Self {
        Self {
            common: GitTriggerCommon::read_declared(structure),
            portrait: SavedPortrait::read(structure),
            ..Self::read_declared(structure)
        }
    }

    /// Writes one element, emitting whichever portrait label the value uses.
    pub fn write_element(&self, structure: &mut GffStruct) {
        self.write_declared(structure);
        self.common.write_declared(structure);
        self.portrait.write(structure);
    }
}

impl GitTrigger {
    /// Reads one element, with the block the list declares as its element.
    pub fn read_element(structure: &GffStruct) -> Self {
        Self {
            common: GitTriggerCommon::read_declared(structure),
            ..Self::read_declared(structure)
        }
    }

    /// Writes one element, the common block included.
    pub fn write_element(&self, structure: &mut GffStruct) {
        self.write_declared(structure);
        self.common.write_declared(structure);
    }
}

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

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

    fn sample() -> SavedTrigger {
        SavedTrigger {
            tag: "tr_transition".to_string(),
            common: GitTriggerCommon {
                linked_to: "wp_arrive".to_string(),
                object_id: Some(ObjectId::new(0x8000_0012)),
                ..GitTriggerCommon::default()
            },
            trigger_type: 1,
            portrait: SavedPortrait::Id(0),
            geometry: vec![
                UttGeometryPoint {
                    point_x: 0.0,
                    point_y: 0.0,
                    point_z: 0.0,
                },
                UttGeometryPoint {
                    point_x: 5.0,
                    point_y: 0.0,
                    point_z: 0.0,
                },
            ],
            load_screen_id: 3,
            trap_detectable: true,
            script_on_enter: ResRef::new("k_trg_enter").expect("valid resref"),
            ..SavedTrigger::default()
        }
    }

    #[test]
    fn round_trips_through_a_list_element() {
        let trigger = sample();

        let parsed = SavedTrigger::read_element(&written!(trigger, 0));

        assert_eq!(parsed, trigger);
    }

    #[test]
    fn does_not_gain_the_trap_dcs_a_door_carries() {
        // A saved trigger has no TrapDetectDC, DisarmDC or TrapFlag. Reusing
        // the shared trap block would write all three.
        let written = written!(sample(), 0);

        assert!(written.field("TrapDetectDC").is_none());
        assert!(written.field("DisarmDC").is_none());
        assert!(written.field("TrapFlag").is_none());
        assert!(written.field("TrapType").is_some());
    }
}