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    stat("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    stat("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
275/// `[advancestat,stat]` / `[changestat,stat]` — subject is a player stat.
276/// Routes to `Type::Stat` so the subject resolves via the typed map instead
277/// of the flat entity-id map, where a same-named entity of another type
278/// (e.g. a `hunt` called `ranged`) would otherwise shadow the stat.
279const fn stat(name: &'static str, byte: u8) -> TriggerInfo {
280    TriggerInfo {
281        name,
282        byte,
283        subject_type: Some(Type::Stat),
284        validates_subject: true,
285        is_button: false,
286    }
287}
288
289const fn flat(name: &'static str, byte: u8) -> TriggerInfo {
290    TriggerInfo {
291        name,
292        byte,
293        subject_type: None,
294        validates_subject: true,
295        is_button: false,
296    }
297}
298
299const fn flat_no_validate(name: &'static str, byte: u8) -> TriggerInfo {
300    TriggerInfo {
301        name,
302        byte,
303        subject_type: None,
304        validates_subject: false,
305        is_button: false,
306    }
307}
308
309// ── Name-keyed triggers ─────────────────────────────────────────────
310//
311// Triggers dispatched by script name (no byte discriminant). These are
312// valid trigger keywords but don't participate in lookup-key hashing.
313
314const NAME_KEYED_TRIGGERS: &[&str] = &[
315    "proc",
316    "label",
317    "debugproc",
318    "command",
319    "clientscript",
320    "walktrigger",
321    "queue",
322    "timer",
323    "softtimer",
324];
325
326// Rev-647 extensions: valid triggers whose byte discriminants are not
327// yet standardized in the reference implementation.
328const EXTENDED_TRIGGERS: &[&str] = &["switch_window_mode"];
329
330// ── Public lookup API ────────────────────────────────────────────────
331
332fn table() -> &'static HashMap<&'static str, TriggerInfo> {
333    static TABLE: OnceLock<HashMap<&'static str, TriggerInfo>> = OnceLock::new();
334    TABLE.get_or_init(|| TRIGGERS.iter().map(|t| (t.name, *t)).collect())
335}
336
337pub fn lookup(name: &str) -> Option<TriggerInfo> {
338    table().get(name).copied()
339}
340
341pub fn byte(name: &str) -> Option<u8> {
342    lookup(name).map(|t| t.byte)
343}
344
345pub fn subject_type(name: &str) -> Option<Type> {
346    lookup(name).and_then(|t| t.subject_type)
347}
348
349pub fn validates_subject(name: &str) -> bool {
350    lookup(name).map(|t| t.validates_subject).unwrap_or(false)
351}
352
353pub fn is_button(name: &str) -> bool {
354    lookup(name).map(|t| t.is_button).unwrap_or(false)
355}
356
357pub fn is_valid_trigger(name: &str) -> bool {
358    lookup(name).is_some()
359        || NAME_KEYED_TRIGGERS.contains(&name)
360        || EXTENDED_TRIGGERS.contains(&name)
361}
362
363pub fn allows_returns(name: &str) -> bool {
364    matches!(name, "proc" | "clientscript" | "command" | "logout")
365}
366
367#[cfg(test)]
368mod tests {
369    use super::*;
370
371    #[test]
372    fn no_duplicate_trigger_names() {
373        let mut seen = std::collections::HashSet::new();
374        for t in TRIGGERS {
375            assert!(seen.insert(t.name), "duplicate trigger name: {}", t.name);
376        }
377    }
378
379    #[test]
380    fn button_triggers_match_legacy_set() {
381        // Locks in pointer_checker's old hand-maintained list.
382        let expected = [
383            "if_button",
384            "if_button1",
385            "if_button2",
386            "if_button3",
387            "if_button4",
388            "if_button5",
389            "if_button6",
390            "if_button7",
391            "if_button8",
392            "if_button9",
393            "if_button10",
394            "if_buttond",
395            "inv_button1",
396            "inv_button2",
397            "inv_button3",
398            "inv_button4",
399            "inv_button5",
400            "inv_buttond",
401        ];
402        for name in expected {
403            assert!(is_button(name), "{} should be a button trigger", name);
404        }
405        // Spot-check that non-buttons aren't flagged.
406        assert!(!is_button("if_close"));
407        assert!(!is_button("opnpc1"));
408        assert!(!is_button("login"));
409    }
410
411    #[test]
412    fn known_byte_values() {
413        // Anchors against the RuneScriptTS ServerTriggerType.ts byte
414        // discriminants. If any of these change, the engine's dispatch
415        // will silently desync.
416        assert_eq!(byte("opnpc1"), Some(10));
417        assert_eq!(byte("opheld1"), Some(140));
418        assert_eq!(byte("if_button"), Some(147));
419        assert_eq!(byte("if_button1"), Some(149));
420        assert_eq!(byte("inv_button1"), Some(149));
421        assert_eq!(byte("login"), Some(157));
422        assert_eq!(byte("ai_despawn"), Some(167));
423        assert_eq!(byte("totally_unknown_trigger"), None);
424    }
425
426    #[test]
427    fn subject_type_routing() {
428        assert_eq!(subject_type("opnpc1"), Some(Type::Npc));
429        assert_eq!(subject_type("opobj1"), Some(Type::Obj));
430        assert_eq!(subject_type("oploc1"), Some(Type::Loc));
431        assert_eq!(subject_type("opheld1"), Some(Type::Obj));
432        assert_eq!(subject_type("if_button"), Some(Type::Interface));
433        assert_eq!(subject_type("inv_button1"), Some(Type::Component));
434        assert_eq!(subject_type("login"), None);
435        assert_eq!(subject_type("opplayer1"), None); // flat lookup
436        // advancestat/changestat take a stat subject. Without this routing,
437        // `[advancestat,ranged]` flat-resolves `ranged` to whatever type was
438        // registered last under that name (e.g. a hunt) instead of the stat.
439        assert_eq!(subject_type("advancestat"), Some(Type::Stat));
440        assert_eq!(subject_type("changestat"), Some(Type::Stat));
441    }
442
443    #[test]
444    fn validation_skip_list() {
445        // Triggers historically excluded from subject validation.
446        assert!(!validates_subject("login"));
447        assert!(!validates_subject("logout"));
448        assert!(!validates_subject("zone"));
449        assert!(!validates_subject("zoneexit"));
450        assert!(!validates_subject("mapzone"));
451        assert!(!validates_subject("mapzoneexit"));
452        assert!(!validates_subject("ai_queue1"));
453        assert!(!validates_subject("ai_timer"));
454        // …but the rest of the byte-keyed triggers do validate.
455        assert!(validates_subject("if_button"));
456        assert!(validates_subject("opnpc1"));
457        assert!(validates_subject("opheld1"));
458        assert!(validates_subject("tutorial"));
459    }
460
461    #[test]
462    fn is_valid_trigger_byte_keyed() {
463        assert!(is_valid_trigger("opnpc1"));
464        assert!(is_valid_trigger("opheld1"));
465        assert!(is_valid_trigger("if_button"));
466        assert!(is_valid_trigger("login"));
467        assert!(is_valid_trigger("ai_queue1"));
468        assert!(is_valid_trigger("ai_despawn"));
469    }
470
471    #[test]
472    fn is_valid_trigger_name_keyed() {
473        assert!(is_valid_trigger("proc"));
474        assert!(is_valid_trigger("label"));
475        assert!(is_valid_trigger("debugproc"));
476        assert!(is_valid_trigger("command"));
477        assert!(is_valid_trigger("clientscript"));
478        assert!(is_valid_trigger("walktrigger"));
479        assert!(is_valid_trigger("queue"));
480        assert!(is_valid_trigger("timer"));
481        assert!(is_valid_trigger("softtimer"));
482    }
483
484    #[test]
485    fn is_valid_trigger_extended() {
486        assert!(is_valid_trigger("switch_window_mode"));
487    }
488
489    #[test]
490    fn opheld_only_goes_to_five() {
491        // Rev-647 (and OSRS) have no opheld beyond 5. Inventory item ops 6-10
492        // route through if_button6-10 + the p_opheld content command instead.
493        assert!(is_valid_trigger("opheld5"));
494        assert!(!is_valid_trigger("opheld6"));
495        assert!(!is_valid_trigger("opheld7"));
496        assert!(!is_valid_trigger("opheld10"));
497    }
498
499    #[test]
500    fn if_button_extended_to_ten() {
501        // Bytes 173-177 must stay in sync with the engine's ServerTriggerType
502        // InvButton6-10.
503        assert!(is_valid_trigger("if_button6"));
504        assert!(is_valid_trigger("if_button10"));
505        assert_eq!(byte("if_button6"), Some(173));
506        assert_eq!(byte("if_button10"), Some(177));
507    }
508
509    #[test]
510    fn inv_button_caps_at_five() {
511        // inv_button is the 225-era spelling with ops 1-5 (+ d). 647 content
512        // uses if_button, which extends to 6-10. Both 225 and 647 content
513        // compile here, so inv_button1-5/inv_buttond stay valid while
514        // inv_button6-10 must not exist.
515        for n in ["inv_button1", "inv_button5", "inv_buttond"] {
516            assert!(is_valid_trigger(n), "{n} should still be a trigger");
517        }
518        for n in ["inv_button6", "inv_button7", "inv_button10"] {
519            assert!(
520                !is_valid_trigger(n),
521                "{n} must not exist (inv_button caps at 5)"
522            );
523            assert_eq!(byte(n), None);
524        }
525    }
526
527    #[test]
528    fn is_valid_trigger_unknown_rejected() {
529        assert!(!is_valid_trigger("not_a_real_trigger"));
530        assert!(!is_valid_trigger(""));
531        assert!(!is_valid_trigger("procc"));
532    }
533
534    #[test]
535    fn allows_returns_matches_lib_set() {
536        assert!(allows_returns("proc"));
537        assert!(allows_returns("clientscript"));
538        assert!(allows_returns("command"));
539        assert!(allows_returns("logout"));
540        assert!(!allows_returns("label"));
541        assert!(!allows_returns("debugproc"));
542        assert!(!allows_returns("queue"));
543        assert!(!allows_returns("timer"));
544        assert!(!allows_returns("softtimer"));
545        assert!(!allows_returns("walktrigger"));
546        assert!(!allows_returns("login"));
547        assert!(!allows_returns("opnpc1"));
548    }
549
550    #[test]
551    fn name_keyed_triggers_have_no_byte() {
552        assert_eq!(byte("proc"), None);
553        assert_eq!(byte("label"), None);
554        assert_eq!(byte("command"), None);
555        assert_eq!(byte("walktrigger"), None);
556    }
557}