Skip to main content

runec/
trigger_table.rs

1//! Single source of truth for RuneScript trigger metadata.
2//!
3//! Every trigger keyword (`[opnpc1,…]`, `[if_button,…]`, `[login,_]`, …)
4//! has the same shape of metadata: a byte discriminant for lookup-key
5//! dispatch, an optional preferred subject type for entity resolution,
6//! whether its subject should be validated to resolve, and whether it's a
7//! button trigger that participates in pointer-grant logic.
8//!
9//! Before this module existed, that metadata was scattered across three
10//! separate matches in `compiler.rs` (the byte table, the
11//! `is_byte_keyed_trigger` whitelist, and the `preferred_type` selector)
12//! plus a 13-arm match in `pointer_checker.rs`. Adding a trigger meant
13//! editing four places, and one of them was the bug shape that silently
14//! produced unreachable scripts.
15
16use crate::types::Type;
17use std::collections::HashMap;
18use std::sync::OnceLock;
19
20#[derive(Debug, Clone, Copy)]
21pub struct TriggerInfo {
22    pub name: &'static str,
23    pub byte: u8,
24    /// Preferred entity type for `lookup_entity_id_typed`. `None` falls
25    /// through to the flat entity-id lookup.
26    pub subject_type: Option<Type>,
27    /// True if a `[trigger,name]` script with a non-`_`, non-`_category`,
28    /// non-coord subject should resolve to a real entity. Drives the
29    /// "subject did not resolve" warning. False for triggers that:
30    ///   - have no entity subject (login, logout)
31    ///   - take coord-shaped subjects (zone, zoneexit, mapzone, mapzoneexit)
32    ///   - intentionally don't validate (ai_queue, ai_timer — preserved
33    ///     from the original `is_byte_keyed_trigger` whitelist; widening
34    ///     this would change emitted warnings)
35    pub validates_subject: bool,
36    /// True for if_button/if_button1-5/if_buttond and inv_button1-5/inv_buttond.
37    /// Used by pointer_checker to grant p_active_player on non-overlay
38    /// interfaces, mirroring ServerPointerChecker.setsPointerTrigger().
39    pub is_button: bool,
40}
41
42const TRIGGERS: &[TriggerInfo] = &[
43    // ── NPC triggers ─────────────────────────────────────────────────
44    npc("apnpc1", 3),
45    npc("apnpc2", 4),
46    npc("apnpc3", 5),
47    npc("apnpc4", 6),
48    npc("apnpc5", 7),
49    npc("apnpcu", 8),
50    npc("apnpct", 9),
51    npc("opnpc1", 10),
52    npc("opnpc2", 11),
53    npc("opnpc3", 12),
54    npc("opnpc4", 13),
55    npc("opnpc5", 14),
56    npc("opnpcu", 15),
57    npc("opnpct", 16),
58    npc("ai_apnpc1", 17),
59    npc("ai_apnpc2", 18),
60    npc("ai_apnpc3", 19),
61    npc("ai_apnpc4", 20),
62    npc("ai_apnpc5", 21),
63    npc("ai_opnpc1", 24),
64    npc("ai_opnpc2", 25),
65    npc("ai_opnpc3", 26),
66    npc("ai_opnpc4", 27),
67    npc("ai_opnpc5", 28),
68    // ── Ground obj triggers ──────────────────────────────────────────
69    obj("apobj1", 31),
70    obj("apobj2", 32),
71    obj("apobj3", 33),
72    obj("apobj4", 34),
73    obj("apobj5", 35),
74    obj("apobju", 36),
75    obj("apobjt", 37),
76    obj("opobj1", 38),
77    obj("opobj2", 39),
78    obj("opobj3", 40),
79    obj("opobj4", 41),
80    obj("opobj5", 42),
81    obj("opobju", 43),
82    obj("opobjt", 44),
83    obj("ai_apobj1", 45),
84    obj("ai_apobj2", 46),
85    obj("ai_apobj3", 47),
86    obj("ai_apobj4", 48),
87    obj("ai_apobj5", 49),
88    obj("ai_opobj1", 52),
89    obj("ai_opobj2", 53),
90    obj("ai_opobj3", 54),
91    obj("ai_opobj4", 55),
92    obj("ai_opobj5", 56),
93    // ── Loc triggers ─────────────────────────────────────────────────
94    loc("aploc1", 59),
95    loc("aploc2", 60),
96    loc("aploc3", 61),
97    loc("aploc4", 62),
98    loc("aploc5", 63),
99    loc("aplocu", 64),
100    loc("aploct", 65),
101    loc("oploc1", 66),
102    loc("oploc2", 67),
103    loc("oploc3", 68),
104    loc("oploc4", 69),
105    loc("oploc5", 70),
106    loc("oplocu", 71),
107    loc("oploct", 72),
108    loc("ai_aploc1", 73),
109    loc("ai_aploc2", 74),
110    loc("ai_aploc3", 75),
111    loc("ai_aploc4", 76),
112    loc("ai_aploc5", 77),
113    loc("ai_oploc1", 80),
114    loc("ai_oploc2", 81),
115    loc("ai_oploc3", 82),
116    loc("ai_oploc4", 83),
117    loc("ai_oploc5", 84),
118    // ── Player triggers (no preferred type — fall through to flat lookup) ──
119    flat("applayer1", 87),
120    flat("applayer2", 88),
121    flat("applayer3", 89),
122    flat("applayer4", 90),
123    flat("applayer5", 91),
124    flat("applayeru", 92),
125    flat("applayert", 93),
126    flat("opplayer1", 94),
127    flat("opplayer2", 95),
128    flat("opplayer3", 96),
129    flat("opplayer4", 97),
130    flat("opplayer5", 98),
131    flat("opplayeru", 99),
132    flat("opplayert", 100),
133    flat("ai_applayer1", 101),
134    flat("ai_applayer2", 102),
135    flat("ai_applayer3", 103),
136    flat("ai_applayer4", 104),
137    flat("ai_applayer5", 105),
138    flat("ai_opplayer1", 108),
139    flat("ai_opplayer2", 109),
140    flat("ai_opplayer3", 110),
141    flat("ai_opplayer4", 111),
142    flat("ai_opplayer5", 112),
143    // ── AI queue / timer (NPC-keyed, but historically not validated) ──
144    npc_no_validate("ai_queue1", 117),
145    npc_no_validate("ai_queue2", 118),
146    npc_no_validate("ai_queue3", 119),
147    npc_no_validate("ai_queue4", 120),
148    npc_no_validate("ai_queue5", 121),
149    npc_no_validate("ai_queue6", 122),
150    npc_no_validate("ai_queue7", 123),
151    npc_no_validate("ai_queue8", 124),
152    npc_no_validate("ai_queue9", 125),
153    npc_no_validate("ai_queue10", 126),
154    npc_no_validate("ai_queue11", 127),
155    npc_no_validate("ai_queue12", 128),
156    npc_no_validate("ai_queue13", 129),
157    npc_no_validate("ai_queue14", 130),
158    npc_no_validate("ai_queue15", 131),
159    npc_no_validate("ai_queue16", 132),
160    npc_no_validate("ai_queue17", 133),
161    npc_no_validate("ai_queue18", 134),
162    npc_no_validate("ai_queue19", 135),
163    npc_no_validate("ai_queue20", 136),
164    flat_no_validate("ai_timer", 139),
165    // ── Held / inventory item triggers ───────────────────────────────
166    obj("opheld1", 140),
167    obj("opheld2", 141),
168    obj("opheld3", 142),
169    obj("opheld4", 143),
170    obj("opheld5", 144),
171    obj("opheldu", 145),
172    obj("opheldt", 146),
173    // ── Interface / button triggers ──────────────────────────────────
174    iface("if_button", 147, true),
175    iface("if_close", 148, false),
176    iface("if_button1", 149, true),
177    iface("if_button2", 150, true),
178    iface("if_button3", 151, true),
179    iface("if_button4", 152, true),
180    iface("if_button5", 153, true),
181    iface("if_buttond", 154, true),
182    component("inv_button1", 149),
183    component("inv_button2", 150),
184    component("inv_button3", 151),
185    component("inv_button4", 152),
186    component("inv_button5", 153),
187    component("inv_buttond", 154),
188    // ── Player lifecycle / coord / stat triggers ─────────────────────
189    flat_no_validate("login", 157),
190    flat_no_validate("logout", 158),
191    flat("tutorial", 159),
192    flat("advancestat", 160),
193    flat_no_validate("mapzone", 161),
194    flat_no_validate("mapzoneexit", 162),
195    flat_no_validate("zone", 163),
196    flat_no_validate("zoneexit", 164),
197    flat("changestat", 165),
198    flat("ai_spawn", 166),
199    flat("ai_despawn", 167),
200];
201
202// ── Constructor helpers ──────────────────────────────────────────────
203//
204// `const fn` so the static slice above stays trivially constructible.
205
206const fn npc(name: &'static str, byte: u8) -> TriggerInfo {
207    TriggerInfo {
208        name,
209        byte,
210        subject_type: Some(Type::Npc),
211        validates_subject: true,
212        is_button: false,
213    }
214}
215
216const fn npc_no_validate(name: &'static str, byte: u8) -> TriggerInfo {
217    TriggerInfo {
218        name,
219        byte,
220        subject_type: Some(Type::Npc),
221        validates_subject: false,
222        is_button: false,
223    }
224}
225
226const fn obj(name: &'static str, byte: u8) -> TriggerInfo {
227    TriggerInfo {
228        name,
229        byte,
230        subject_type: Some(Type::Obj),
231        validates_subject: true,
232        is_button: false,
233    }
234}
235
236const fn loc(name: &'static str, byte: u8) -> TriggerInfo {
237    TriggerInfo {
238        name,
239        byte,
240        subject_type: Some(Type::Loc),
241        validates_subject: true,
242        is_button: false,
243    }
244}
245
246const fn iface(name: &'static str, byte: u8, is_button: bool) -> TriggerInfo {
247    TriggerInfo {
248        name,
249        byte,
250        subject_type: Some(Type::Interface),
251        validates_subject: true,
252        is_button,
253    }
254}
255
256const fn component(name: &'static str, byte: u8) -> TriggerInfo {
257    TriggerInfo {
258        name,
259        byte,
260        subject_type: Some(Type::Component),
261        validates_subject: true,
262        is_button: true,
263    }
264}
265
266const fn flat(name: &'static str, byte: u8) -> TriggerInfo {
267    TriggerInfo {
268        name,
269        byte,
270        subject_type: None,
271        validates_subject: true,
272        is_button: false,
273    }
274}
275
276const fn flat_no_validate(name: &'static str, byte: u8) -> TriggerInfo {
277    TriggerInfo {
278        name,
279        byte,
280        subject_type: None,
281        validates_subject: false,
282        is_button: false,
283    }
284}
285
286// ── Name-keyed triggers ─────────────────────────────────────────────
287//
288// Triggers dispatched by script name (no byte discriminant). These are
289// valid trigger keywords but don't participate in lookup-key hashing.
290
291const NAME_KEYED_TRIGGERS: &[&str] = &[
292    "proc",
293    "label",
294    "debugproc",
295    "command",
296    "clientscript",
297    "walktrigger",
298    "queue",
299    "timer",
300    "softtimer",
301];
302
303// Rev-647 extensions: valid triggers whose byte discriminants are not
304// yet standardized in the reference implementation.
305const EXTENDED_TRIGGERS: &[&str] = &["opheld6", "opheld7", "opheld8", "switch_window_mode"];
306
307// ── Public lookup API ────────────────────────────────────────────────
308
309fn table() -> &'static HashMap<&'static str, TriggerInfo> {
310    static TABLE: OnceLock<HashMap<&'static str, TriggerInfo>> = OnceLock::new();
311    TABLE.get_or_init(|| TRIGGERS.iter().map(|t| (t.name, *t)).collect())
312}
313
314pub fn lookup(name: &str) -> Option<TriggerInfo> {
315    table().get(name).copied()
316}
317
318pub fn byte(name: &str) -> Option<u8> {
319    lookup(name).map(|t| t.byte)
320}
321
322pub fn subject_type(name: &str) -> Option<Type> {
323    lookup(name).and_then(|t| t.subject_type)
324}
325
326pub fn validates_subject(name: &str) -> bool {
327    lookup(name).map(|t| t.validates_subject).unwrap_or(false)
328}
329
330pub fn is_button(name: &str) -> bool {
331    lookup(name).map(|t| t.is_button).unwrap_or(false)
332}
333
334pub fn is_valid_trigger(name: &str) -> bool {
335    lookup(name).is_some()
336        || NAME_KEYED_TRIGGERS.contains(&name)
337        || EXTENDED_TRIGGERS.contains(&name)
338}
339
340pub fn allows_returns(name: &str) -> bool {
341    matches!(name, "proc" | "clientscript" | "command" | "logout")
342}
343
344#[cfg(test)]
345mod tests {
346    use super::*;
347
348    #[test]
349    fn no_duplicate_trigger_names() {
350        let mut seen = std::collections::HashSet::new();
351        for t in TRIGGERS {
352            assert!(seen.insert(t.name), "duplicate trigger name: {}", t.name);
353        }
354    }
355
356    #[test]
357    fn button_triggers_match_legacy_set() {
358        // Locks in pointer_checker's old hand-maintained list.
359        let expected = [
360            "if_button",
361            "if_button1",
362            "if_button2",
363            "if_button3",
364            "if_button4",
365            "if_button5",
366            "if_buttond",
367            "inv_button1",
368            "inv_button2",
369            "inv_button3",
370            "inv_button4",
371            "inv_button5",
372            "inv_buttond",
373        ];
374        for name in expected {
375            assert!(is_button(name), "{} should be a button trigger", name);
376        }
377        // Spot-check that non-buttons aren't flagged.
378        assert!(!is_button("if_close"));
379        assert!(!is_button("opnpc1"));
380        assert!(!is_button("login"));
381    }
382
383    #[test]
384    fn known_byte_values() {
385        // Anchors against the RuneScriptTS ServerTriggerType.ts byte
386        // discriminants. If any of these change, the engine's dispatch
387        // will silently desync.
388        assert_eq!(byte("opnpc1"), Some(10));
389        assert_eq!(byte("opheld1"), Some(140));
390        assert_eq!(byte("if_button"), Some(147));
391        assert_eq!(byte("if_button1"), Some(149));
392        assert_eq!(byte("inv_button1"), Some(149));
393        assert_eq!(byte("login"), Some(157));
394        assert_eq!(byte("ai_despawn"), Some(167));
395        assert_eq!(byte("totally_unknown_trigger"), None);
396    }
397
398    #[test]
399    fn subject_type_routing() {
400        assert_eq!(subject_type("opnpc1"), Some(Type::Npc));
401        assert_eq!(subject_type("opobj1"), Some(Type::Obj));
402        assert_eq!(subject_type("oploc1"), Some(Type::Loc));
403        assert_eq!(subject_type("opheld1"), Some(Type::Obj));
404        assert_eq!(subject_type("if_button"), Some(Type::Interface));
405        assert_eq!(subject_type("inv_button1"), Some(Type::Component));
406        assert_eq!(subject_type("login"), None);
407        assert_eq!(subject_type("opplayer1"), None); // flat lookup
408    }
409
410    #[test]
411    fn validation_skip_list() {
412        // Triggers historically excluded from subject validation.
413        assert!(!validates_subject("login"));
414        assert!(!validates_subject("logout"));
415        assert!(!validates_subject("zone"));
416        assert!(!validates_subject("zoneexit"));
417        assert!(!validates_subject("mapzone"));
418        assert!(!validates_subject("mapzoneexit"));
419        assert!(!validates_subject("ai_queue1"));
420        assert!(!validates_subject("ai_timer"));
421        // …but the rest of the byte-keyed triggers do validate.
422        assert!(validates_subject("if_button"));
423        assert!(validates_subject("opnpc1"));
424        assert!(validates_subject("opheld1"));
425        assert!(validates_subject("tutorial"));
426    }
427
428    #[test]
429    fn is_valid_trigger_byte_keyed() {
430        assert!(is_valid_trigger("opnpc1"));
431        assert!(is_valid_trigger("opheld1"));
432        assert!(is_valid_trigger("if_button"));
433        assert!(is_valid_trigger("login"));
434        assert!(is_valid_trigger("ai_queue1"));
435        assert!(is_valid_trigger("ai_despawn"));
436    }
437
438    #[test]
439    fn is_valid_trigger_name_keyed() {
440        assert!(is_valid_trigger("proc"));
441        assert!(is_valid_trigger("label"));
442        assert!(is_valid_trigger("debugproc"));
443        assert!(is_valid_trigger("command"));
444        assert!(is_valid_trigger("clientscript"));
445        assert!(is_valid_trigger("walktrigger"));
446        assert!(is_valid_trigger("queue"));
447        assert!(is_valid_trigger("timer"));
448        assert!(is_valid_trigger("softtimer"));
449    }
450
451    #[test]
452    fn is_valid_trigger_extended() {
453        assert!(is_valid_trigger("opheld6"));
454        assert!(is_valid_trigger("opheld7"));
455        assert!(is_valid_trigger("opheld8"));
456        assert!(is_valid_trigger("switch_window_mode"));
457    }
458
459    #[test]
460    fn is_valid_trigger_unknown_rejected() {
461        assert!(!is_valid_trigger("not_a_real_trigger"));
462        assert!(!is_valid_trigger(""));
463        assert!(!is_valid_trigger("procc"));
464    }
465
466    #[test]
467    fn allows_returns_matches_lib_set() {
468        assert!(allows_returns("proc"));
469        assert!(allows_returns("clientscript"));
470        assert!(allows_returns("command"));
471        assert!(allows_returns("logout"));
472        assert!(!allows_returns("label"));
473        assert!(!allows_returns("debugproc"));
474        assert!(!allows_returns("queue"));
475        assert!(!allows_returns("timer"));
476        assert!(!allows_returns("softtimer"));
477        assert!(!allows_returns("walktrigger"));
478        assert!(!allows_returns("login"));
479        assert!(!allows_returns("opnpc1"));
480    }
481
482    #[test]
483    fn name_keyed_triggers_have_no_byte() {
484        assert_eq!(byte("proc"), None);
485        assert_eq!(byte("label"), None);
486        assert_eq!(byte("command"), None);
487        assert_eq!(byte("walktrigger"), None);
488    }
489}