smudgy:core — Automations

Generated from smudgy v0.3.5 (smudgy-core.d.ts @ cfcea3b156f6). 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(
  name: string,
  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", "^gt (.+)$", "guildtell $1");

The typed command is consumed by default (see capture). Aliases created this way last until the next script reload. Returns an Alias handle.

export function createTrigger(
  name: string,
  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("gz", "^(\\w+) has advanced a level", "say Grats, $1!");
// A function body can decide what to do; named groups arrive by name.
createTrigger("lowhp", /^(?<hp>\d+)H /, ({ hp }) => {
  if (parseInt(hp) < 100) send("flee");
});

Triggers created this way last until the next script reload; 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.

export function createTimer(name: string, 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("sip", { 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(name: string, keySpec: KeySpec, handler: () => void): Hotkey;

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

import { createHotkey, send } from "smudgy:core";
createHotkey("panic", { key: "F1" }, () => send("flee"));
createHotkey("heal", { 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 — The name it was created with.
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.

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

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

Options for createAlias.

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 = {
  prompt?: boolean;
  enabled?: boolean;
  singleton?: boolean;
  fireLimit?: number;
  lineLimit?: number;
};

Options for createTrigger.

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 = {
  intervalMs: number;
  repeat?: boolean;
  fireLimit?: number;
};

Options for createTimer.

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 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 — Events · smudgy:core — Saved automations · smudgy:core — Panes · smudgy:widgets · Mapper · smudgy:params