smudgy:core — Automations

Generated from smudgy v0.4.0 (smudgy-core.d.ts @ 3c804cdb8fa3). Index: scriptref.

Aliases, triggers, timers, and hotkeys created from scripts: the create* functions, the handles they return, and the registries. These are cleared and recreated on every script reload. For the saved automations shown in the automations window, see saved-automations.

export function createAlias(
  patterns: Pattern | Pattern[],
  script: AutomationScript,
  options?: AliasOptions,
): Alias;

Create an alias: a shortcut that watches what you type and runs a script instead of sending it. patterns is one regex or several; when your input matches, script runs: a command template string, or a function that receives the Matches.

import { createAlias } from "smudgy:core";
// Typing "gt any message here" sends "guildtell any message here".
createAlias("^gt (.+)$", "guildtell $1");

The typed command is consumed by default (see capture). Aliases created this way last until the next script reload, and show up in the automations window named after their pattern (pass options.name to label one yourself). Returns an Alias handle.

export function createTrigger(
  patterns: Pattern | TriggerPatterns,
  script: AutomationScript,
  options?: TriggerOptions,
): Trigger;

Create a trigger: it watches every line arriving from the MUD and runs a script on a match. patterns is one regex, or a TriggerPatterns object for raw/anti patterns; script is a command template string, or a function that receives the Matches.

import { createTrigger, send } from "smudgy:core";
// Congratulate, reusing the captured name.
createTrigger("^(\\w+) has advanced a level", "say Grats, $1!");
// A function body can decide what to do; named groups arrive by name.
createTrigger(/^(?<hp>\d+)H /, ({ hp }) => {
  if (parseInt(hp) < 100) send("flee");
});

Triggers created this way last until the next script reload, and show up in the automations window named after their patterns (pass options.name to label one yourself); see TriggerOptions for prompt matching, fire limits, and more. Returns a Trigger handle.

export function createTriggers(triggers: Record<string, TriggerDef>): Record<string, Trigger>;

Create several triggers in one call: pass an object mapping each name to its TriggerDef; get back the same names mapped to their Trigger handles. The keys make this the natural form for a staged chain (chain.row.enabled = true) and give multi-pattern triggers a readable name in the automations window.

export function createTimer(options: TimerOptions, callback: () => void): Timer;

Create a timer that runs callback after intervalMs milliseconds: once by default, or repeatedly with repeat: true.

import { createTimer, send } from "smudgy:core";
// Keep sipping, every 30 seconds until deleted:
const sip = createTimer({ intervalMs: 30000, repeat: true },
  () => send("drink potion"));
// later: sip.delete();

Timers are cleared on script reload. Returns a Timer handle; set enabled = false to pause it, or delete() to stop it.

export function createHotkey(keySpec: KeySpec, handler: () => void, options?: HotkeyOptions): Hotkey;

Bind a keyboard shortcut: handler runs whenever the KeySpec combination is pressed in this session.

import { createHotkey, send } from "smudgy:core";
createHotkey({ key: "F1" }, () => send("flee"));
createHotkey({ key: "h", modifiers: ["ctrl"] }, () => send("cast 'heal' self"));

Hotkeys are cleared on script reload. Returns a Hotkey handle.

export interface Alias {
  readonly name: string;
  readonly created?: boolean;
  enabled: boolean;
  readonly pattern: string;
  delete(): void;
}

A handle to a script-created alias: enable/disable it with enabled, remove it with delete(). Returned by createAlias.

name — Its name: the name option if one was given, otherwise the pattern.
created — false when a singleton request found an existing automation and returned that one instead of creating a new one.
enabled — Whether the alias is active: set false to disable, true to re-enable.
pattern — The first pattern's regex source ("" if the alias no longer exists).
delete — Remove the alias. Safe to call more than once.

export interface Trigger {
  readonly name: string;
  readonly created?: boolean;
  enabled: boolean;
  readonly pattern: string;
  delete(): void;
}

A handle to a script-created trigger; the same shape as Alias. Returned by createTrigger.

export interface Timer {
  readonly name: string;
  enabled: boolean;
  delete(): void;
}

A handle to a script-created timer. Returned by createTimer; timers are cleared on script reload.

enabled — Whether the timer is running: set false to pause, true to resume.
delete — Stop and remove the timer. Safe to call more than once.

export interface Hotkey {
  readonly name: string;
  enabled: boolean;
  delete(): void;
}

A handle to a script-created hotkey. Returned by createHotkey; hotkeys are cleared on script reload.

enabled — Whether the key is bound: set false to unbind, true to rebind.
delete — Unbind and remove the hotkey. Safe to call more than once.

export const aliases: AutomationRegistry<Alias>;

The registry of aliases your scripts created.

export const triggers: AutomationRegistry<Trigger>;

The registry of triggers your scripts created.

export const timers: AutomationRegistry<Timer>;

The registry of timers your scripts created.

export const hotkeys: AutomationRegistry<Hotkey>;

The registry of hotkeys your scripts created.

export interface AutomationRegistry<H> {
  get(name: string): H | undefined;
  list(): string[];
  exists(name: string): boolean;
}

Look up the automations of one kind that your own scripts created. Each script sees only its own; two scripts can both own a "heal" trigger without colliding.

get — The handle for name, or undefined if you have no such automation.
list — The names of your automations of this kind.
exists — Whether you have an automation named name.

export type Matches = {
  readonly [group: number]: string;
  readonly [name: string]: string;
};

The captures handed to a trigger or alias handler. matches[0] is the whole matched text; matches[1], matches[2], and so on are the capture groups in order. A named group like (?<who>...) can also be read by name, as matches.who, and handlers often destructure it: ({ who }) => .... Every group of the pattern that fired is present: one that matched nothing (an optional group, say) is the empty string, not undefined as in standard JavaScript regex matches.

When a trigger has several patterns, only the fired pattern's groups are present; the other patterns' groups are absent and read as undefined. "who" in matches tells you which pattern fired.

export type InlineTemplate = string;

A trigger/alias body written as a plain string instead of a function: a command template sent to the MUD after substitution.

$1 … $9 insert capture groups (single digit; write ${10} for group ten)
$name / ${name} insert a named group
$$ is a literal dollar sign

Unknown or non-matching groups become the empty string.

export type TriggerPatterns = {
  patterns?: Pattern[];
  rawPatterns?: Pattern[];
  antiPatterns?: Pattern[];
};

The three pattern lists a trigger can match with. Most triggers set only patterns.

patterns — Regexes tested against each incoming line's displayed text.
rawPatterns — Regexes tested against the raw incoming line, before ANSI color codes are stripped. Use these to match on colors.
antiPatterns — Vetoes: if any of these match the line, the trigger does not fire.

export type TriggerDef = TriggerPatterns & {
  script: InlineTemplate | ((matches: Matches) => string | void);
  prompt?: boolean;
  enabled?: boolean;
  singleton?: boolean;
  fireLimit?: number;
  lineLimit?: number;
};

One trigger in a createTriggers batch: its patterns, its body, and the same options as TriggerOptions (except name — the batch's key is the name).

script — The trigger body: a command template string or a function (see AutomationScript).

export type AliasOptions = {
  name?: string;
  singleton?: boolean;
  fireLimit?: number;
};

Options for createAlias.

name — A name of your choosing. Without one, the alias is named after its pattern, which is usually all the automations window needs; name it yourself to tell apart two aliases that share a pattern, or to keep a stable label your code looks up later.
singleton — Keep the first registration: if a singleton automation with this name already exists in the session, create* returns the existing one (its handle reports created: false) instead of replacing it.
fireLimit — The alias removes itself after firing this many times (1 = one-shot).

export type TriggerOptions = {
  name?: string;
  prompt?: boolean;
  enabled?: boolean;
  singleton?: boolean;
  fireLimit?: number;
  lineLimit?: number;
};

Options for createTrigger.

name — A name of your choosing. Without one, the trigger is named after its pattern, which is usually all the automations window needs; name it yourself to tell apart two triggers that share a pattern, or to keep a stable label your code looks up later.
prompt — Also test prompts (the partial line the MUD leaves waiting for input), not just complete lines. Default false.
enabled — Start enabled? Default true; pass false to create it switched off (e.g. a follow-on trigger that an earlier trigger enables).
singleton — Keep the first registration: if a singleton automation with this name already exists in the session, create* returns the existing one (its handle reports created: false) instead of replacing it.
fireLimit — The trigger removes itself after firing this many times (1 = one-shot).
lineLimit — The trigger removes itself after testing this many incoming lines, whether or not they fired it.

export type TimerOptions = {
  name?: string;
  intervalMs: number;
  repeat?: boolean;
  fireLimit?: number;
};

Options for createTimer.

name — A name of your choosing; without one, the timer is named after its interval and callback. Re-creating a timer with the same name replaces the old one.
intervalMs — Time between fires, in milliseconds (1000 = one second). Required.
repeat — Keep firing until stopped. Default false: fire once, then the timer removes itself.
fireLimit — With repeat, the timer removes itself after this many fires.

export type HotkeyOptions = {
  name?: string;
};

Options for createHotkey.

name — A name of your choosing; without one, the hotkey is named after its key combination (e.g. "ctrl+h"). Re-creating a hotkey with the same name replaces the old binding.

export type KeySpec = {
  key: string;
  modifiers?: string[];
};

The key combination for createHotkey.

key — The main key (e.g. "F1", "a").
modifiers — Modifier keys that must be held with it (e.g. ["ctrl", "shift"]).

This describes a type returned from a function on this page. Typically you'll never construct it directly.

type Pattern = string | RegExp;

A match pattern: a regular expression, written either as a RegExp (/^You follow/) or as a string of regex source ("^You follow"). Strings are compiled as regexes, not matched literally.

This describes a type returned from a function on this page. Typically you'll never construct it directly.

type AutomationScript = InlineTemplate | ((matches: Matches) => string | void);

Either body form an automation accepts: a command template string (see InlineTemplate), or a function called with the Matches. If the function returns a string, that string is sent to the MUD as a command (aliases apply to it).

Script API reference · smudgy:core — Sessions & output · smudgy:core — Lines & buffer · smudgy:core — Shared state & events · GMCP · smudgy:core — Saved automations · smudgy:core — Panes · smudgy:widgets · Mapper · smudgy:params