API Reference

Quick-reference index for all public UrsaMU APIs. For full documentation of
each section, see Core API Reference.

Imports

// All public APIs
import {
  addCmd, registerPluginRoute, mu, createObj, DBO, dbojs, gameHooks
} from "jsr:@ursamu/ursamu";

// Types (zero runtime cost)
import type {
  ICmd, IPlugin, IDBObj, IUrsamuSDK,
  SayEvent, PoseEvent, PageEvent, MoveEvent, SessionEvent,
  ChannelMessageEvent, SceneCreatedEvent, ScenePoseEvent,
  SceneSetEvent, SceneTitleEvent, SceneClearEvent,
} from "jsr:@ursamu/ursamu";

Internal plugins may use direct paths:

import { addCmd } from "../../services/commands/cmdParser.ts";
import type { IUrsamuSDK } from "../../@types/UrsamuSDK.ts";

Types

See Core API Reference for full type definitions.

addCmd

Registers one or more in-game commands at module-load time.

import { addCmd } from "jsr:@ursamu/ursamu";
import type { IUrsamuSDK } from "jsr:@ursamu/ursamu";

addCmd({
  name:    "+greet",
  pattern: /^\+greet\s+(.*)/i,   // capture groups → u.cmd.args[0], args[1], …
  lock:    "connected",
  exec: async (u: IUrsamuSDK) => {
    const target = await u.util.target(u.me, u.cmd.args[0]);
    if (!target) { u.send("Who?"); return; }
    u.send(`You wave to ${u.util.displayName(target, u.me)}.`);
  },
  help:     "+greet <name>\nWave at someone.",
  category: "Social",
});

Lock expression quick reference

u.db

Database operations. All methods are async. Available in both addCmd handlers
and sandbox scripts.

modify ops: "$set" (merge), "$unset" (remove field), "$inc" (increment number).
Do not pass any other string — it is rejected.

// Merge a field
await u.db.modify(u.me.id, "$set", { "data.gold": 100 });

// Full state replace (always spread to preserve other fields)
await u.db.modify(u.me.id, "$set", { data: { ...u.me.state, gold: 100 } });

// Increment
await u.db.modify(u.me.id, "$inc", { "data.deaths": 1 });

// Remove a field
await u.db.modify(u.me.id, "$unset", { "data.tempAttr": "" });

Search examples:

const online  = await u.db.search({ flags: /connected/i });
const rooms   = await u.db.search({ flags: /room/i });
const here    = await u.db.search({ location: u.here.id });
const byName  = await u.db.search({ "data.name": /alice/i });
const found   = await u.db.search({ $or: [
  { "data.name": /alice/i }, { "data.alias": /alice/i }
]});

u.* Quick Reference

All namespaces on the u SDK object. Every method is async (returns a Promise).

Top-level methods

u.util

u.auth

u.sys

u.chan

u.bb

u.text

u.attr

u.mail (sandbox scripts only)

u.events

dbojs

Direct game-object database access (for plugins and startup code, not scripts).

import { dbojs } from "jsr:@ursamu/ursamu";

const players = await dbojs.queryAll((o) => o.flags.has("player"));
const room    = await dbojs.queryOne((o) => o.id === "1");
// queryOne returns IDBOBJ | undefined | false

DBO<T>

Typed plugin-specific database collections backed by Deno KV.

import { DBO } from "jsr:@ursamu/ursamu";

interface INote { id: string; playerId: string; text: string; date: number; }
const notes = new DBO<INote>("myplugin.notes");

await notes.create({ id: crypto.randomUUID(), playerId: u.me.id, text: "hi", date: Date.now() });
const all  = await notes.find({ playerId: u.me.id });
const one  = await notes.findOne({ id: noteId });
await notes.update({ id: noteId }, { text: "updated" });
await notes.delete({ id: noteId });

GameHooks

Typed event bus for the 12 built-in engine events.

import { gameHooks } from "jsr:@ursamu/ursamu";

const handler = ({ actorId, actorName }: SessionEvent) => { /* ... */ };
gameHooks.on("player:login", handler);
gameHooks.off("player:login", handler);    // call in plugin remove()

Event catalog

Other hook buses (from specific plugins):

• wikiHooks — wiki:created, wiki:edited, wiki:deleted
• eventHooks — event:created, event:updated, event:deleted, event:started, event:ended, event:rsvp, event:cancelled

REST API

Authentication: Authorization: Bearer <jwt> header on all protected routes.

For AI Tools

For a single dense reference optimized for AI code generation, see:

/docs/llms.md — complete type signatures, all method signatures,
common patterns, and MUSH color codes in one flat document.