benilla-octo/crates/benilla-ui/src/messages.rs

//! The client's message catalog: `CGGameUI::DisplayError` (`0x496720`) takes only a message id,
//! and the id's 20-byte record in the 465-row table at `0xb4b498` names the `GlobalStrings.lua`
//! key, where it is shown and its sound. The rows are generated by
//! `scripts/gen-message-catalog.py` from `reference/1.12-message-catalog.tsv`, decoded from the
//! table's static initializer `[0x484ca0, 0x488408)`; the text itself is read from the install.

mod catalog;

pub use catalog::CATALOG;

/// Where a message is shown: the record's `+0x04`, as the jump at `0x496888` reads it. Its fourth
/// arm, `3` (the console `0x63cd00`), has no row in this build's table (console lines call
/// `0x63cb50` directly), and the generator refuses a kind it does not know.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MsgKind {
    /// `0`: a chat-window line through the composer `0x49a870`, on the record's `chat_type`.
    Chat,
    /// `1`: `AddErrorMessage(text, 0)`, `UI_INFO_MESSAGE` (`0xe1`), yellow in `UIErrorsFrame`.
    Info,
    /// `2`: `AddErrorMessage(text, 1)`, `UI_ERROR_MESSAGE` (`0xe0`), red in `UIErrorsFrame`.
    Error,
}

/// One row of `0xb4b498`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MessageRecord {
    /// The id `DisplayError` takes, and this row's index.
    pub id: u16,
    /// `+0x00`, the `GlobalStrings.lua` key; an absent or empty string shows nothing
    /// (`0x4967bd`/`0x4967c5`).
    pub key: &'static str,
    /// `+0x04`, where it is shown.
    pub kind: MsgKind,
    /// `+0x08`, the sound cue; `None` on the 435 silent rows.
    pub sound: Option<&'static str>,
    /// `+0x0c`: `0x44` plays [`Self::sound`]; the other 56 rows carry an error-speech id, spoken
    /// in the player's race and gender voice.
    pub type_tag: u8,
    /// `+0x10`, read on [`MsgKind::Chat`] rows only: `10` (`CHAT_MSG_SYSTEM`), except `23`
    /// (`CHAT_MSG_SKILL`) on the skill-up rows `ERR_PROFICIENCY_GAINED_S`, `ERR_SKILL_GAINED_S`
    /// and `ERR_SKILL_UP_SI`.
    pub chat_type: u8,
}

/// The record for a message id; the table ends at the reference's bound, `cmp id,0x1d1` at
/// `0x49672c`.
pub fn by_id(id: u16) -> Option<&'static MessageRecord> {
    CATALOG.get(usize::from(id))
}

/// The record for a `GlobalStrings` key; keys are unique (the generator refuses a duplicate).
pub fn by_key(key: &str) -> Option<&'static MessageRecord> {
    CATALOG.iter().find(|r| r.key == key)
}

/// Where a message goes, by key. A key with no row is a benilla typo, never a reference state
/// (the reference addresses messages by index), and falls back to the red line.
pub fn kind_of(key: &str) -> MsgKind {
    by_key(key).map_or(MsgKind::Error, |r| r.kind)
}

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

    #[test]
    fn ids_are_dense_and_the_table_is_whole() {
        assert_eq!(CATALOG.len(), 465);
        for (i, r) in CATALOG.iter().enumerate() {
            assert_eq!(usize::from(r.id), i, "row {i} carries id {}", r.id);
        }
        assert!(by_id(465).is_none(), "the reference bounds at 0x1d1");
    }

    #[test]
    fn keys_are_unique() {
        let mut keys: Vec<&str> = CATALOG.iter().map(|r| r.key).collect();
        keys.sort_unstable();
        let n = keys.len();
        keys.dedup();
        assert_eq!(keys.len(), n);
    }

    #[test]
    fn the_surface_is_not_guessable_from_the_key() {
        assert_eq!(kind_of("ERR_PETITION_SIGNED_S"), MsgKind::Chat);
        assert_eq!(kind_of("ERR_PETITION_ALREADY_SIGNED"), MsgKind::Error);
        assert_eq!(kind_of("ERR_FISH_ESCAPED"), MsgKind::Info);
        assert_eq!(kind_of("ERR_INV_FULL"), MsgKind::Error);
    }

    #[test]
    fn the_skill_up_rows_speak_on_chat_msg_skill() {
        for key in [
            "ERR_PROFICIENCY_GAINED_S",
            "ERR_SKILL_GAINED_S",
            "ERR_SKILL_UP_SI",
        ] {
            let r = by_key(key).expect(key);
            assert_eq!(r.kind, MsgKind::Chat);
            assert_eq!(r.chat_type, 23, "{key}");
        }
        assert_eq!(by_key("ERR_QUEST_ALREADY_ON").unwrap().chat_type, 10);
    }

    #[test]
    fn an_unknown_key_falls_back_to_the_red_line() {
        assert!(by_key("ERR_NOT_A_REAL_MESSAGE").is_none());
        assert_eq!(kind_of("ERR_NOT_A_REAL_MESSAGE"), MsgKind::Error);
    }
}