rakata_generics/

shared.rs

//! Shared typed building blocks used across multiple GFF generic wrappers.
//!
//! These types reduce drift between format modules by centralizing repeated
//! field groups (for example trap settings and common trap-related scripts).

use rakata_core::ResRef;
use rakata_formats::GffValue;

/// A runtime object handle, as the engine hands them out.
///
/// A newtype rather than a bare `u32` because the two are not
/// interchangeable: zero is a perfectly ordinary object id, so a plain
/// integer field cannot tell "object number zero" from "no object". Every
/// type carrying one of these had that bug, defaulting to zero and thereby
/// claiming an unplaced object referred to whichever object the engine
/// numbered first.
///
/// [`Default`] is [`Self::INVALID`], which is what makes the fix structural.
/// A type holding this can keep `#[derive(Default)]` and get the right value,
/// where a bare `u32` needs every author to remember.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ObjectId(u32);

impl ObjectId {
    /// The engine-wide `OBJECT_INVALID` placeholder, carried by anything that
    /// has not been assigned a runtime id.
    pub const INVALID: Self = Self(0x7F00_0000);

    /// Wraps a raw handle.
    pub const fn new(raw: u32) -> Self {
        Self(raw)
    }

    /// The raw handle, for writing back into a GFF field.
    pub const fn get(self) -> u32 {
        self.0
    }

    /// Whether this names an actual object rather than the placeholder.
    pub const fn is_valid(self) -> bool {
        self.0 != Self::INVALID.0
    }
}

impl Default for ObjectId {
    fn default() -> Self {
        Self::INVALID
    }
}

impl From<u32> for ObjectId {
    fn from(raw: u32) -> Self {
        Self(raw)
    }
}

impl From<ObjectId> for u32 {
    fn from(id: ObjectId) -> Self {
        id.0
    }
}

/// Shared trap configuration block used by door/placeable/trap-like templates.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct TrapSettings {
    /// Trap-detectable flag (`TrapDetectable`).
    pub detectable: bool,
    /// Trap detect DC (`TrapDetectDC`).
    pub detect_dc: u8,
    /// Trap-disarmable flag (`TrapDisarmable`).
    pub disarmable: bool,
    /// Trap disarm DC (`DisarmDC`).
    pub disarm_dc: u8,
    /// Trap flag (`TrapFlag`).
    pub flag: u8,
    /// Trap one-shot flag (`TrapOneShot`).
    pub one_shot: bool,
    /// Trap type (`TrapType`).
    pub trap_type: u8,
}

/// The `PortraitId` value that hands control back to the `Portrait` resref.
///
/// A trigger's read stamps this when the file carries no `PortraitId`, which
/// lands inside the documented `>= 0xFFFE` range where the engine consults
/// the string field instead of the id. Defaulting to `0` would name portrait
/// row zero and shadow the resref, which is the opposite behaviour.
pub const PORTRAIT_ID_USE_RESREF: u16 = 0xFFFF;

/// `TrapType`'s value when a file does not carry one.
///
/// Not a `traps.2da` row. Row `255` does not exist in vanilla data, so a file
/// missing both this and `OnTrapTriggered` sends the engine to an
/// out-of-range lookup rather than to a clean "no trap" state. Reading an
/// absent `TrapType` as `0` instead would name a row that does exist, turning
/// "no trap configured" into "trap type 0".
pub const TRAP_TYPE_ABSENT: u8 = 0xFF;

/// What one loader holds for the trap fields a file leaves out.
///
/// Three consumers share `TrapSettings` and none of them agree. A door
/// carries its constructor's armed flags over, a placeable's read stamps `0`
/// across all three, and a trigger stamps `0` over two of them while
/// `TrapOneShot` carries `1` over like a door's. So the defaults cannot live
/// in the shared reader; they belong to whoever is calling it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct TrapDefaults {
    detectable: bool,
    disarmable: bool,
    one_shot: bool,
}

impl TrapDefaults {
    /// `CSWSDoor`: the constructor arms all three and every read carries over.
    pub(crate) const DOOR: Self = Self {
        detectable: true,
        disarmable: true,
        one_shot: true,
    };

    /// `CSWSTrigger`: `TrapDetectable` and `TrapDisarmable` are constructed
    /// armed and then stamped `0` by their own reads, so a trigger that omits
    /// them loads undetectable and undisarmable. `TrapOneShot` is the one that
    /// genuinely carries its constructed `1`.
    pub(crate) const TRIGGER: Self = Self {
        detectable: false,
        disarmable: false,
        one_shot: true,
    };

    /// `CSWSPlaceable`: all three constructed armed and all three stamped `0`,
    /// so an absent trap flag set loads as a non-functional trap.
    pub(crate) const PLACEABLE: Self = Self {
        detectable: false,
        disarmable: false,
        one_shot: false,
    };
}

impl TrapSettings {
    /// Builds trap settings from caller-provided field readers.
    ///
    /// `defaults` is the calling loader's own absent-field behaviour; see
    /// [`TrapDefaults`] for why it cannot be one shared set.
    pub(crate) fn read<FBool, FU8>(
        defaults: TrapDefaults,
        mut get_bool: FBool,
        mut get_u8: FU8,
    ) -> Self
    where
        FBool: FnMut(&str) -> Option<bool>,
        FU8: FnMut(&str) -> Option<u8>,
    {
        Self {
            detectable: get_bool("TrapDetectable").unwrap_or(defaults.detectable),
            detect_dc: get_u8("TrapDetectDC").unwrap_or(0),
            disarmable: get_bool("TrapDisarmable").unwrap_or(defaults.disarmable),
            disarm_dc: get_u8("DisarmDC").unwrap_or(0),
            flag: get_u8("TrapFlag").unwrap_or(0),
            one_shot: get_bool("TrapOneShot").unwrap_or(defaults.one_shot),
            trap_type: get_u8("TrapType").unwrap_or(TRAP_TYPE_ABSENT),
        }
    }

    /// Writes trap settings via caller-provided upsert callback.
    pub(crate) fn write<FUpsert>(&self, mut upsert: FUpsert)
    where
        FUpsert: FnMut(&str, GffValue),
    {
        upsert("TrapDetectable", GffValue::UInt8(u8::from(self.detectable)));
        upsert("TrapDetectDC", GffValue::UInt8(self.detect_dc));
        upsert("TrapDisarmable", GffValue::UInt8(u8::from(self.disarmable)));
        upsert("DisarmDC", GffValue::UInt8(self.disarm_dc));
        upsert("TrapFlag", GffValue::UInt8(self.flag));
        upsert("TrapOneShot", GffValue::UInt8(u8::from(self.one_shot)));
        upsert("TrapType", GffValue::UInt8(self.trap_type));
    }
}

/// Shared script hook bundle common to placeables and doors.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct CommonTrapScripts {
    /// On-closed script (`OnClosed`).
    pub on_closed: ResRef,
    /// On-damaged script (`OnDamaged`).
    pub on_damaged: ResRef,
    /// On-death script (`OnDeath`).
    pub on_death: ResRef,
    /// On-disarm script (`OnDisarm`).
    pub on_disarm: ResRef,
    /// On-heartbeat script (`OnHeartbeat`).
    pub on_heartbeat: ResRef,
    /// On-lock script (`OnLock`).
    pub on_lock: ResRef,
    /// On-melee-attacked script (`OnMeleeAttacked`).
    pub on_melee_attacked: ResRef,
    /// On-open script (`OnOpen`).
    pub on_open: ResRef,
    /// On-spell-cast-at script (`OnSpellCastAt`).
    pub on_spell_cast_at: ResRef,
    /// On-trap-triggered script (`OnTrapTriggered`).
    pub on_trap_triggered: ResRef,
    /// On-unlock script (`OnUnlock`).
    pub on_unlock: ResRef,
    /// On-user-defined script (`OnUserDefined`).
    pub on_user_defined: ResRef,
}

/// The resref a script slot holds when a file does not name one.
///
/// A door's constructor pre-arms all fifteen slots with the literal string
/// `"default"`, and a trigger's does the same for its seven, so an absent hook
/// on either resolves to that name rather than to nothing. This is the
/// mechanism behind the documented `traps.2da` fallback: `OnTrapTriggered`
/// becomes `"default"` on its own, which is one of the three spellings that
/// routes to the table. A placeable's constructor arms nothing, so its hooks
/// really are empty when absent.
pub const SCRIPT_SLOT_SEED: ResRef = match ResRef::const_new("default") {
    Ok(seed) => seed,
    // Unreachable: a seven-character ASCII literal is inside every ResRef
    // limit. `expect` is not const, so the match spells out the same thing.
    Err(_) => panic!("\"default\" is a valid resref"),
};

impl CommonTrapScripts {
    /// Builds the shared script bundle from caller-provided field readers.
    ///
    /// `seed` is what the calling loader's constructor left in each slot:
    /// [`SCRIPT_SLOT_SEED`] for a door, empty for a placeable.
    pub(crate) fn read<FResRef>(seed: ResRef, mut get_resref: FResRef) -> Self
    where
        FResRef: FnMut(&str) -> Option<ResRef>,
    {
        Self {
            on_closed: get_resref("OnClosed").unwrap_or(seed),
            on_damaged: get_resref("OnDamaged").unwrap_or(seed),
            on_death: get_resref("OnDeath").unwrap_or(seed),
            on_disarm: get_resref("OnDisarm").unwrap_or(seed),
            on_heartbeat: get_resref("OnHeartbeat").unwrap_or(seed),
            on_lock: get_resref("OnLock").unwrap_or(seed),
            on_melee_attacked: get_resref("OnMeleeAttacked").unwrap_or(seed),
            on_open: get_resref("OnOpen").unwrap_or(seed),
            on_spell_cast_at: get_resref("OnSpellCastAt").unwrap_or(seed),
            on_trap_triggered: get_resref("OnTrapTriggered").unwrap_or(seed),
            on_unlock: get_resref("OnUnlock").unwrap_or(seed),
            on_user_defined: get_resref("OnUserDefined").unwrap_or(seed),
        }
    }

    /// Writes the shared script bundle via caller-provided upsert callback.
    pub(crate) fn write<FUpsert>(&self, mut upsert: FUpsert)
    where
        FUpsert: FnMut(&str, GffValue),
    {
        upsert("OnClosed", GffValue::ResRef(self.on_closed));
        upsert("OnDamaged", GffValue::ResRef(self.on_damaged));
        upsert("OnDeath", GffValue::ResRef(self.on_death));
        upsert("OnDisarm", GffValue::ResRef(self.on_disarm));
        upsert("OnHeartbeat", GffValue::ResRef(self.on_heartbeat));
        upsert("OnLock", GffValue::ResRef(self.on_lock));
        upsert("OnMeleeAttacked", GffValue::ResRef(self.on_melee_attacked));
        upsert("OnOpen", GffValue::ResRef(self.on_open));
        upsert("OnSpellCastAt", GffValue::ResRef(self.on_spell_cast_at));
        upsert("OnTrapTriggered", GffValue::ResRef(self.on_trap_triggered));
        upsert("OnUnlock", GffValue::ResRef(self.on_unlock));
        upsert("OnUserDefined", GffValue::ResRef(self.on_user_defined));
    }
}

/// How a saved object names its portrait.
///
/// A saved object carries either `Portrait`, a resref naming the image
/// directly, or `PortraitId`, a row index into `portraits.2da`. Across every
/// placeable and trigger in the fixture saves the two are exactly
/// complementary: never both on one object, and never neither. Modelling them
/// as one value rather than two [`Option`]s means the state where an object
/// claims both, or claims neither, cannot be built.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SavedPortrait {
    /// `Portrait`: a resref naming the portrait image.
    ResRef(ResRef),
    /// `PortraitId`: a row index into `portraits.2da`.
    Id(u16),
}

impl Default for SavedPortrait {
    /// Row 0 of `portraits.2da`, which is what an object with no portrait
    /// field at all resolves to.
    fn default() -> Self {
        Self::Id(0)
    }
}

impl SavedPortrait {
    /// Reads whichever of the two fields the object carries.
    ///
    /// Prefers `Portrait` when both somehow appear, since a resref names an
    /// image outright and a row index still has to be looked up.
    pub(crate) fn read<FRes, FU16>(mut get_resref: FRes, mut get_u16: FU16) -> Self
    where
        FRes: FnMut(&str) -> Option<ResRef>,
        FU16: FnMut(&str) -> Option<u16>,
    {
        match (get_resref("Portrait"), get_u16("PortraitId")) {
            (Some(resref), _) => Self::ResRef(resref),
            (None, Some(id)) => Self::Id(id),
            (None, None) => Self::default(),
        }
    }

    /// Writes back the one field this portrait uses, and only that one.
    pub(crate) fn write<F>(&self, mut upsert: F)
    where
        F: FnMut(&str, GffValue),
    {
        match self {
            Self::ResRef(resref) => upsert("Portrait", GffValue::ResRef(*resref)),
            Self::Id(id) => upsert("PortraitId", GffValue::UInt16(*id)),
        }
    }
}

/// Shared grid/repository position used by inventory list entries.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct InventoryGridPosition {
    /// Repository/grid X coordinate.
    pub x: u16,
    /// Repository/grid Y coordinate.
    pub y: u16,
}

/// A vertex in a trigger geometry polygon (`PointX`/`PointY`/`PointZ`).
#[derive(Debug, Clone, PartialEq, Default)]
pub struct GitTriggerPoint {
    /// X coordinate (`PointX`).
    pub point_x: f32,
    /// Y coordinate (`PointY`).
    pub point_y: f32,
    /// Z coordinate (`PointZ`).
    pub point_z: f32,
}

impl GitTriggerPoint {
    /// Builds a trigger point from a raw GFF struct.
    pub fn from_gff_struct(s: &rakata_formats::GffStruct) -> Self {
        use crate::gff_helpers::get_f32;
        Self {
            point_x: get_f32(s, "PointX").unwrap_or(0.0),
            point_y: get_f32(s, "PointY").unwrap_or(0.0),
            point_z: get_f32(s, "PointZ").unwrap_or(0.0),
        }
    }

    /// Converts this trigger point to a raw GFF struct.
    pub fn to_gff_struct(&self) -> rakata_formats::GffStruct {
        use crate::gff_helpers::upsert_field;
        let mut s = rakata_formats::GffStruct::new(0);
        upsert_field(&mut s, "PointX", GffValue::Single(self.point_x));
        upsert_field(&mut s, "PointY", GffValue::Single(self.point_y));
        upsert_field(&mut s, "PointZ", GffValue::Single(self.point_z));
        s
    }
}