Script API reference
Generated from smudgy v0.3.5 (smudgy-core.d.ts @ cfcea3b156f6, smudgy-mapper.d.ts @ bd98f888f8b0, smudgy-params.d.ts @ 36bdd47232ed, smudgy-widgets.d.ts @ 9f2a8e811d12)
Every function and type available to smudgy scripts.
Writing scripts
Smudgy's built-in script editor is only suited to simple scripts. Anything more complex is usually built in an IDE, as modules (script files in your Documents/smudgy/<server>/modules/ folder) or as installable packages.
Smudgy maintains a TypeScript project next to your scripts, so an editor with TypeScript support provides autocomplete and type checking:
- VS Code: (recommended) TypeScript support is built in.
- Other editors: use a TypeScript language server such as typescript-language-server.
- AI coding tools (Claude Code, Codex, and similar) generally recognize TypeScript projects. Because this documentation sits on disk next to your scripts, they implicitly know the full scripting API.
Everything in this reference is also in your editor. The IntelliSense documentation shown when hovering a function or symbol matches these pages.
Reading this reference
The reference is organized by module:
| Module | Covers |
|---|---|
smudgy:core | Sessions & output · Lines & buffer · Events · Automations · Saved automations · Panes |
mapper (from smudgy:core) | The map: areas, rooms, exits, pathfinding |
smudgy:widgets | On-screen UI built from widget components |
smudgy:params | Install-time options for installed packages |
Importing the API from a module or package:
import { on, send, createTrigger, mapper } from "smudgy:core";
import { createWidget, Column, Text } from "smudgy:widgets";
import { get } from "smudgy:params";
Within each page, lowercase entries (send, createTrigger) are the functions you call; capitalized entries (TriggerOptions, Session) describe the values they accept and return. Every entry shows its TypeScript declaration in a grey box.
The runtime (Deno)
Scripts run on Deno. Besides the smudgy modules above, the standard web APIs are available (fetch, WebSocket, localStorage, timers, crypto), along with:
Web workers (Worker) are not supported.
SQLite is built in: the node:sqlite module provides an embedded SQL database: import { DatabaseSync } from "node:sqlite". new DatabaseSync(getDataDir() + "/my.db") opens (or creates) a database file in the script's data directory.
In a sandboxed package, all of this obeys the manifest: network APIs need a network permission, and file-backed APIs need file permissions.
Modules vs packages
Modules are loose script files in Documents/smudgy/<server>/modules/. Every file at the top level of that folder loads automatically in each session for that server; there is nothing to register or enable.
Packages are folders with a manifest (smudgy.package.json) and an entry module (index.ts by default), created and managed in the packages window; the files live in Documents/smudgy/<server>/packages/<name>/. A package loads through its entry module when enabled. Packages are versioned, can depend on other packages, ask for options at install time, and can be published for others to install. An installed package runs limited to the permissions its manifest declares, so what it can do (send commands, touch files, use the network) is visible before others install it.
Sharing packages
A published package has an address: smudgy://<owner>/<name>, where the owner is the publisher's smudgy.org nickname. Publish from the packages window; each publish creates a new version, and published versions never change.
A package can be private (only you and those you've shared it with can see and install it) or public (listed in Discover for anyone to find and install).
A package can also tag the MUD hostnames it is written for (hosts in the manifest). Searching Discover from a session then shows universal packages and packages tagged for that MUD; packages tagged only for other MUDs are left out. Tagged packages get a ranking boost, so a niche MUD's packages are not buried under globally popular ones.
Install packages from the packages window: public packages are searchable in Discover, and private packages (your own, and those shared with you) appear under Private & Shared.
A module imports an installed package by its address. The bare address is the package's entry module; a subpath names a file inside it.
// After installing kapusniak's arctic-prompt package:
import { on, send } from "smudgy:core";
import { promptEvent } from "smudgy://kapusniak/arctic-prompt";
on(promptEvent, ({ hp }) => {
if (hp && hp < 100) send("quaff healing");
});
A package that imports another package must also list it in its manifest's dependencies, optionally with a version range (smudgy://kapusniak/arctic-prompt@^1.0). Installing a package installs its dependencies with it.
Sandboxing
Modules run with full access: they are your own files, and nothing they do is restricted.
Every package, installed or locally authored, runs in its own sandbox, limited to the permissions its manifest declares. A call outside those permissions fails. The permissions are part of the manifest, so they are shown before anything runs; a package can never quietly do more than what you accepted.
What a sandbox is: each sandboxed package runs in its own V8 isolate, a separate instance of the JavaScript engine with its own memory and globals. Isolates share nothing, so a package cannot reach the variables of your modules or of any other package. Chrome uses the same mechanism: the JavaScript of each browser tab and each web worker runs in its own isolate, which is why one page's scripts can never touch another's.
With “Enable advanced scripting features” turned on in the preferences window, a package can be trusted from the packages window. A trusted package's sandbox is lifted entirely: it runs with the same full access as your modules. Trust is per package and off by default.
smudgy:core — Sessions & output
The basic output functions (echo/send/sendRaw), the current session and other connected sessions, and the profile and app settings. Import from smudgy:core.
echo · send · sendRaw · reload · session · id · Session · getSessions · byName · getProfile · Profile · getSettings · Settings · Palette · getDataDir · vars · mapper · SmudgyApi
smudgy:core — Lines & buffer
Read and edit the text on screen: the line a trigger is processing right now (line), recently printed lines (buffer), colors and styling, and alias capture control.
line · buffer · Line · Buffer · capture · Color · StyleSpan · LineColorOptions
smudgy:core — Events
Events fire when something happens (the session connects or disconnects, a command goes out, the map location changes) or when a package broadcasts one. Subscribe with on, broadcast with emit. Import from smudgy:core.
on · once · emit · SmudgyEventMap · SmudgyEvent · EventSubscription
smudgy:core — Automations
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.
createAlias · createTrigger · createTriggers · createTimer · createHotkey · Alias · Trigger · Timer · Hotkey · aliases · triggers · timers · hotkeys · AutomationRegistry · Matches · InlineTemplate · TriggerPatterns · TriggerDef · AliasOptions · TriggerOptions · TimerOptions · KeySpec
smudgy:core — Saved automations
Create, edit, and delete the saved aliases/triggers/hotkeys (the ones shown in the automations window) from a script, via userAutomations. Saved automations run outside any sandbox, so a sandboxed package can never access them: writing one would let the package run code outside its sandbox. For the automations scripts create with the create* functions, see automations.
userAutomations · UserAutomations · SavedAutomationRegistry · SavedAutomationHandle · SavedAlias · SavedTrigger · SavedHotkey · SavedAliasHandle · SavedTriggerHandle · SavedHotkeyHandle · ScriptLang
smudgy:core — Panes
Session panes: split named panes off the main pane (or off each other) and write lines into them. Panes host widgets (see widgets) and, unless created widgets-only, a terminal.
Pane · PaneRegistry · PaneRegistryMethods · PaneSpec · PaneSpecBase · SplitDirection · TitleBarSpec
smudgy:widgets
Script-driven UI: build widget trees from the components below (directly or with JSX in a .tsx module) and put them on screen with createWidget. Import from smudgy:widgets.
createWidget · removeWidget · CreateWidgetOptions · Column · ColumnProps · Row · RowProps · Stack · StackProps · Container · ContainerProps · Text · TextProps · ProgressBar · ProgressBarProps · Button · ButtonProps · ButtonVariant · Scrollable · ScrollableProps · ScrollDirection · Markdown · MarkdownProps · Modal · ModalProps · TextEditor · TextEditorProps · MapView · MapViewProps · Element · Length · Children · HorizontalAlign · VerticalAlign · SmudgyElement · WidgetLength · WidgetChild · WidgetChildren · jsx · jsxs · Fragment · JSX
Mapper
The map API: import { mapper } from "smudgy:core". The map types (Area, Room, …) need no import.
mapper · Mapper · Area · Room · Exit · CreateRoomParams · UpdateRoomParams · ExitArgs · ExitUpdates · AreaJson · Label · LabelArgs · LabelUpdates · Shape · ShapeArgs · ShapeUpdates · AreaId · RoomNumber · ExitId · LabelId · ShapeId · ExitDirection · ExitStyle · LabelHorizontalAlign · LabelVerticalAlign · ShapeKind
smudgy:params
Per-package configuration: read the option values chosen when a package was installed (the options block of its smudgy.package.json). Import from smudgy:params.