smudgy:core — Sessions & output

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

The basic output functions (echo/send/sendRaw), the current session and other connected sessions, and the profile and app settings. Import from smudgy:core.

export function echo(line: string | StyledText): void;
 
export function echo(text: TemplateStringsArray, ...values: unknown[]): void;

Print a line in your session's output window; nothing is sent to the MUD. Also usable directly as a template tag: echohi ${style.redthere} .

export function send(command: string): void;

Send a command to the MUD as if you typed it: aliases run, and the command separator (e.g. ;) splits it into multiple commands.

export function sendRaw(text: string): void;

Send text to the MUD exactly as given: no alias processing, no splitting on the command separator.

export function reload(): void;

Reload the current session's scripts and automations.

export const session: Session;

The session your script is running in.

export const id: number;

Your session's numeric id.

export interface Session {
  readonly id: number;
  readonly profile: Profile;
  echo(line: string | StyledText): void;
  echo(text: TemplateStringsArray, ...values: unknown[]): void;
  send(line: string): void;
  sendRaw(line: string): void;
  reload(): void;
  readonly mainPane: Pane;
  readonly panes: PaneRegistry;
  toString(): string;
}

A MUD session. Every method acts on the session the handle names, which need not be the one your script is running in: session is your own, and getSessions / byName reach any connected one, so byName("scout")?.send("look") drives another character.

On a session other than your own, panes can be split, closed, and written to, but not listed or looked up.

• id — The session's numeric id.
• profile — The session's profile (name + subtext).
• echo — Echo a line into this session's output (local; not sent to the MUD). Takes styled text too, and works directly as a template tag.
• send — Send a command to this session's MUD (alias processing + command splitting).
• sendRaw — Send text to this session's MUD verbatim.
• reload — Reload this session's scripts and automations.
• mainPane — This session's main (output + input) pane.
• panes — This session's pane registry (see PaneRegistry).

export function getSessions(): Session[];

All connected sessions.

import { getSessions, createAlias } from "smudgy:core";
// Typing "*<anything>" sends that command to every connected session.
createAlias(/^\*(?<command>.*)$/, ({ command }) => {
  for (const s of getSessions()) s.send(command);
});

export function byName(name: string): Session | undefined;

The first connected session whose profile name is name. Returns undefined if no match is found.

export function getProfile(): Profile;

Your session's profile.

export interface Profile {
  name?: string;
  subtext?: string;
}

The name and subtext (caption) associated with a session.

export function getSettings(): Settings;

The current app settings as set in the preferences window. Read-only.

export interface Settings {
  commandSeparator: string;
  rawLinePrefix: string;
  scrollbackLength: number;
  terminalFontFamily: string;
  terminalFontSize: number;
  terminalLineLength?: number;
  theme: string;
  commandInputBehavior: "selectAllClearOnBlur" | "selectAll" | "clear";
  palette?: Palette;
}

The read-only app settings returned by getSettings. Only display and behavior settings are exposed. palette can be briefly absent right after a session starts.

• commandSeparator — Separates multiple commands typed on one input line (e.g. ;); empty disables splitting.
• rawLinePrefix — Lines starting with this prefix are sent verbatim; empty disables it.
• scrollbackLength — The scrollback buffer's maximum line count.
• terminalFontSize — Terminal font size in pixels (line height is size * 1.25).
• terminalLineLength — Maximum terminal line length in columns; absent means wrap to pane width.
• theme — The active color-scheme name.
• commandInputBehavior — What the command input does with the text after a send.
• palette — The resolved terminal palette; can be briefly absent at session start.

export interface Palette {
  ansi: string[];
  foreground: string;
  background: string;
  echo: string;
  warn: string;
  output: string;
  selection: string;
  inputBackground: string;
  accent?: string;
}

The terminal's color scheme, as #rrggbb hex strings.

• ansi — The 16 ANSI colors as #rrggbb strings: the 8 normal shades first, then the 8 bright ones (black, red, green, yellow, blue, magenta, cyan, white).
• accent — The app accent color, if the color scheme defines one.

export function getDataDir(): string;

Your script's (or package's) data directory ($DATA), as an absolute path.

export const vars: Record<string, any>;

Variables shared by every script on this server, persisted across reloads and characters. Read and write plain properties:

import { vars, send } from "smudgy:core";
vars.target = "goblin";        // set it in one script...
send(`kill ${vars.target}`);   // ...use it in another

These are internally stored as JSON, so only valid JSON types will persist.

export const mapper: Mapper;

The current session's map API (see Mapper).

export interface SmudgyApi {
  echo(line: string | StyledText): void;
  echo(text: TemplateStringsArray, ...values: unknown[]): void;
  readonly style: StyleBuilder;
  readonly link: typeof link;
  send(command: string): void;
  sendRaw(text: string): void;
  reload(): void;
  capture(value: boolean): void;
  byName(name: string): Session | undefined;
  getSessions(): Session[];
  getProfile(): Profile;
  getSettings(): Settings;
  getDataDir(): string;
  readonly userAutomations: UserAutomations;
  createState: typeof createState;
  createEvent: typeof createEvent;
  createProcedure: typeof createProcedure;
  createDerived: typeof createDerived;
  readonly events: typeof events;
  readonly gmcp: typeof gmcp;
  createAlias: typeof createAlias;
  createTrigger: typeof createTrigger;
  createTriggers: typeof createTriggers;
  createTimer: typeof createTimer;
  createHotkey: typeof createHotkey;
  readonly aliases: AutomationRegistry<Alias>;
  readonly triggers: AutomationRegistry<Trigger>;
  readonly timers: AutomationRegistry<Timer>;
  readonly hotkeys: AutomationRegistry<Hotkey>;
  readonly vars: Record<string, any>;
  readonly line: Line;
  readonly buffer: Buffer;
  readonly mapper: Mapper;
  readonly session: Session;
  readonly id: number;
}

The whole current-session API on one object. Every member mirrors the named export of the same name.

• mapper — The map API.
• session — The current session.
• id — The current session id.

The module's default export (api).

const api: SmudgyApi;

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