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-10/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    // Rev-647: client merged OpHeld/InvButton into IfButton1-10. Inventory
183    // item ops 6-10 (e.g. Drop=op8) are handled in content via
184    // `[if_button6..10,inv:component]` + `p_opheld(op, inv, slot)`.
185    // Bytes 173-177 must match the engine's ServerTriggerType InvButton6-10.
186    iface("if_button6", 173, true),
187    iface("if_button7", 174, true),
188    iface("if_button8", 175, true),
189    iface("if_button9", 176, true),
190    iface("if_button10", 177, true),
191    component("inv_button1", 149),
192    component("inv_button2", 150),
193    component("inv_button3", 151),
194    component("inv_button4", 152),
195    component("inv_button5", 153),
196    component("inv_buttond", 154),
197    // ── Player lifecycle / coord / stat triggers ─────────────────────
198    flat_no_validate("login", 157),
199    flat_no_validate("logout", 158),
200    flat("tutorial", 159),
201    flat("advancestat", 160),
202    flat_no_validate("mapzone", 161),
203    flat_no_validate("mapzoneexit", 162),
204    flat_no_validate("zone", 163),
205    flat_no_validate("zoneexit", 164),
206    flat("changestat", 165),
207    flat("ai_spawn", 166),
208    flat("ai_despawn", 167),
209];
210
211// ── Constructor helpers ──────────────────────────────────────────────
212//
213// `const fn` so the static slice above stays trivially constructible.
214
215const fn npc(name: &'static str, byte: u8) -> TriggerInfo {
216    TriggerInfo {
217        name,
218        byte,
219        subject_type: Some(Type::Npc),
220        validates_subject: true,
221        is_button: false,
222    }
223}
224
225const fn npc_no_validate(name: &'static str, byte: u8) -> TriggerInfo {
226    TriggerInfo {
227        name,
228        byte,
229        subject_type: Some(Type::Npc),
230        validates_subject: false,
231        is_button: false,
232    }
233}
234
235const fn obj(name: &'static str, byte: u8) -> TriggerInfo {
236    TriggerInfo {
237        name,
238        byte,
239        subject_type: Some(Type::Obj),
240        validates_subject: true,
241        is_button: false,
242    }
243}
244
245const fn loc(name: &'static str, byte: u8) -> TriggerInfo {
246    TriggerInfo {
247        name,
248        byte,
249        subject_type: Some(Type::Loc),
250        validates_subject: true,
251        is_button: false,
252    }
253}
254
255const fn iface(name: &'static str, byte: u8, is_button: bool) -> TriggerInfo {
256    TriggerInfo {
257        name,
258        byte,
259        subject_type: Some(Type::Interface),
260        validates_subject: true,
261        is_button,
262    }
263}
264
265const fn component(name: &'static str, byte: u8) -> TriggerInfo {
266    TriggerInfo {
267        name,
268        byte,
269        subject_type: Some(Type::Component),
270        validates_subject: true,
271        is_button: true,
272    }
273}
274
275const fn flat(name: &'static str, byte: u8) -> TriggerInfo {
276    TriggerInfo {
277        name,
278        byte,
279        subject_type: None,
280        validates_subject: true,
281        is_button: false,
282    }
283}
284
285const fn flat_no_validate(name: &'static str, byte: u8) -> TriggerInfo {
286    TriggerInfo {
287        name,
288        byte,
289        subject_type: None,
290        validates_subject: false,
291        is_button: false,
292    }
293}
294
295// ── Name-keyed triggers ─────────────────────────────────────────────
296//
297// Triggers dispatched by script name (no byte discriminant). These are
298// valid trigger keywords but don't participate in lookup-key hashing.
299
300const NAME_KEYED_TRIGGERS: &[&str] = &[
301    "proc",
302    "label",
303    "debugproc",
304    "command",
305    "clientscript",
306    "walktrigger",
307    "queue",
308    "timer",
309    "softtimer",
310];
311
312// Rev-647 extensions: valid triggers whose byte discriminants are not
313// yet standardized in the reference implementation.
314const EXTENDED_TRIGGERS: &[&str] = &["switch_window_mode"];
315
316// ── Public lookup API ────────────────────────────────────────────────
317
318fn table() -> &'static HashMap<&'static str, TriggerInfo> {
319    static TABLE: OnceLock<HashMap<&'static str, TriggerInfo>> = OnceLock::new();
320    TABLE.get_or_init(|| TRIGGERS.iter().map(|t| (t.name, *t)).collect())
321}
322
323pub fn lookup(name: &str) -> Option<TriggerInfo> {
324    table().get(name).copied()
325}
326
327pub fn byte(name: &str) -> Option<u8> {
328    lookup(name).map(|t| t.byte)
329}
330
331pub fn subject_type(name: &str) -> Option<Type> {
332    lookup(name).and_then(|t| t.subject_type)
333}
334
335pub fn validates_subject(name: &str) -> bool {
336    lookup(name).map(|t| t.validates_subject).unwrap_or(false)
337}
338
339pub fn is_button(name: &str) -> bool {
340    lookup(name).map(|t| t.is_button).unwrap_or(false)
341}
342
343pub fn is_valid_trigger(name: &str) -> bool {
344    lookup(name).is_some()
345        || NAME_KEYED_TRIGGERS.contains(&name)
346        || EXTENDED_TRIGGERS.contains(&name)
347}
348
349pub fn allows_returns(name: &str) -> bool {
350    matches!(name, "proc" | "clientscript" | "command" | "logout")
351}
352
353#[cfg(test)]
354mod tests {
355    use super::*;
356
357    #[test]
358    fn no_duplicate_trigger_names() {
359        let mut seen = std::collections::HashSet::new();
360        for t in TRIGGERS {
361            assert!(seen.insert(t.name), "duplicate trigger name: {}", t.name);
362        }
363    }
364
365    #[test]
366    fn button_triggers_match_legacy_set() {
367        // Locks in pointer_checker's old hand-maintained list.
368        let expected = [
369            "if_button",
370            "if_button1",
371            "if_button2",
372            "if_button3",
373            "if_button4",
374            "if_button5",
375            "if_button6",
376            "if_button7",
377            "if_button8",
378            "if_button9",
379            "if_button10",
380            "if_buttond",
381            "inv_button1",
382            "inv_button2",
383            "inv_button3",
384            "inv_button4",
385            "inv_button5",
386            "inv_buttond",
387        ];
388        for name in expected {
389            assert!(is_button(name), "{} should be a button trigger", name);
390        }
391        // Spot-check that non-buttons aren't flagged.
392        assert!(!is_button("if_close"));
393        assert!(!is_button("opnpc1"));
394        assert!(!is_button("login"));
395    }
396
397    #[test]
398    fn known_byte_values() {
399        // Anchors against the RuneScriptTS ServerTriggerType.ts byte
400        // discriminants. If any of these change, the engine's dispatch
401        // will silently desync.
402        assert_eq!(byte("opnpc1"), Some(10));
403        assert_eq!(byte("opheld1"), Some(140));
404        assert_eq!(byte("if_button"), Some(147));
405        assert_eq!(byte("if_button1"), Some(149));
406        assert_eq!(byte("inv_button1"), Some(149));
407        assert_eq!(byte("login"), Some(157));
408        assert_eq!(byte("ai_despawn"), Some(167));
409        assert_eq!(byte("totally_unknown_trigger"), None);
410    }
411
412    #[test]
413    fn subject_type_routing() {
414        assert_eq!(subject_type("opnpc1"), Some(Type::Npc));
415        assert_eq!(subject_type("opobj1"), Some(Type::Obj));
416        assert_eq!(subject_type("oploc1"), Some(Type::Loc));
417        assert_eq!(subject_type("opheld1"), Some(Type::Obj));
418        assert_eq!(subject_type("if_button"), Some(Type::Interface));
419        assert_eq!(subject_type("inv_button1"), Some(Type::Component));
420        assert_eq!(subject_type("login"), None);
421        assert_eq!(subject_type("opplayer1"), None); // flat lookup
422    }
423
424    #[test]
425    fn validation_skip_list() {
426        // Triggers historically excluded from subject validation.
427        assert!(!validates_subject("login"));
428        assert!(!validates_subject("logout"));
429        assert!(!validates_subject("zone"));
430        assert!(!validates_subject("zoneexit"));
431        assert!(!validates_subject("mapzone"));
432        assert!(!validates_subject("mapzoneexit"));
433        assert!(!validates_subject("ai_queue1"));
434        assert!(!validates_subject("ai_timer"));
435        // …but the rest of the byte-keyed triggers do validate.
436        assert!(validates_subject("if_button"));
437        assert!(validates_subject("opnpc1"));
438        assert!(validates_subject("opheld1"));
439        assert!(validates_subject("tutorial"));
440    }
441
442    #[test]
443    fn is_valid_trigger_byte_keyed() {
444        assert!(is_valid_trigger("opnpc1"));
445        assert!(is_valid_trigger("opheld1"));
446        assert!(is_valid_trigger("if_button"));
447        assert!(is_valid_trigger("login"));
448        assert!(is_valid_trigger("ai_queue1"));
449        assert!(is_valid_trigger("ai_despawn"));
450    }
451
452    #[test]
453    fn is_valid_trigger_name_keyed() {
454        assert!(is_valid_trigger("proc"));
455        assert!(is_valid_trigger("label"));
456        assert!(is_valid_trigger("debugproc"));
457        assert!(is_valid_trigger("command"));
458        assert!(is_valid_trigger("clientscript"));
459        assert!(is_valid_trigger("walktrigger"));
460        assert!(is_valid_trigger("queue"));
461        assert!(is_valid_trigger("timer"));
462        assert!(is_valid_trigger("softtimer"));
463    }
464
465    #[test]
466    fn is_valid_trigger_extended() {
467        assert!(is_valid_trigger("switch_window_mode"));
468    }
469
470    #[test]
471    fn opheld_only_goes_to_five() {
472        // Rev-647 (and OSRS) have no opheld beyond 5. Inventory item ops 6-10
473        // route through if_button6-10 + the p_opheld content command instead.
474        assert!(is_valid_trigger("opheld5"));
475        assert!(!is_valid_trigger("opheld6"));
476        assert!(!is_valid_trigger("opheld7"));
477        assert!(!is_valid_trigger("opheld10"));
478    }
479
480    #[test]
481    fn if_button_extended_to_ten() {
482        // Bytes 173-177 must stay in sync with the engine's ServerTriggerType
483        // InvButton6-10.
484        assert!(is_valid_trigger("if_button6"));
485        assert!(is_valid_trigger("if_button10"));
486        assert_eq!(byte("if_button6"), Some(173));
487        assert_eq!(byte("if_button10"), Some(177));
488    }
489
490    #[test]
491    fn inv_button_caps_at_five() {
492        // inv_button is the 225-era spelling with ops 1-5 (+ d). 647 content
493        // uses if_button, which extends to 6-10. Both 225 and 647 content
494        // compile here, so inv_button1-5/inv_buttond stay valid while
495        // inv_button6-10 must not exist.
496        for n in ["inv_button1", "inv_button5", "inv_buttond"] {
497            assert!(is_valid_trigger(n), "{n} should still be a trigger");
498        }
499        for n in ["inv_button6", "inv_button7", "inv_button10"] {
500            assert!(
501                !is_valid_trigger(n),
502                "{n} must not exist (inv_button caps at 5)"
503            );
504            assert_eq!(byte(n), None);
505        }
506    }
507
508    #[test]
509    fn is_valid_trigger_unknown_rejected() {
510        assert!(!is_valid_trigger("not_a_real_trigger"));
511        assert!(!is_valid_trigger(""));
512        assert!(!is_valid_trigger("procc"));
513    }
514
515    #[test]
516    fn allows_returns_matches_lib_set() {
517        assert!(allows_returns("proc"));
518        assert!(allows_returns("clientscript"));
519        assert!(allows_returns("command"));
520        assert!(allows_returns("logout"));
521        assert!(!allows_returns("label"));
522        assert!(!allows_returns("debugproc"));
523        assert!(!allows_returns("queue"));
524        assert!(!allows_returns("timer"));
525        assert!(!allows_returns("softtimer"));
526        assert!(!allows_returns("walktrigger"));
527        assert!(!allows_returns("login"));
528        assert!(!allows_returns("opnpc1"));
529    }
530
531    #[test]
532    fn name_keyed_triggers_have_no_byte() {
533        assert_eq!(byte("proc"), None);
534        assert_eq!(byte("label"), None);
535        assert_eq!(byte("command"), None);
536        assert_eq!(byte("walktrigger"), None);
537    }
538}