smudgy
dev:manual:scripting:packages

Table of Contents

Package manifests and publishing

The manifest is both a build contract and the installer's first explanation of the package. Keep the name and description literal, request only the access the released code uses, and describe setup in the README before publishing.

The structured package manifest editor with identity, version, dependencies, parameters, and capabilities sections

The packages window creates a package folder with smudgy.package.json and an entry module. Edit a copy locally, test it in a session, and publish from the same window when it is ready.

Manifest responsibilities

The manifest describes the parts of a package that must be known before its code runs:

  • version — the package version.
  • description — a short explanation shown to people browsing or installing it.
  • entry — the module loaded when the package starts; defaults to index.ts.
  • dependencies — packages whose code this package imports.
  • requires — packages that must be installed for shared state, events, or procedures, without importing their code.
  • params — options collected at install time and read through smudgy:params.
  • permissions — access requested from the package sandbox.
  • hosts — optional MUD hostnames used to improve discovery results.

The packages window remains the safest place to create and edit the manifest because it validates these fields and presents the same information used during installation.

The System permission tab separates environment variables, system-information categories, runnable programs, and native libraries. run and ffi are declarable for sandboxed packages, but the program or native code executes outside the script sandbox. The editor and installation review flag that distinction rather than presenting these as ordinary contained grants.

The package manifest System tab with scoped run and FFI entries and their full-access warnings

See Permissions, sandboxing, and trust before adding filesystem, process, or native-code access.

Dependencies and requirements

An entry can include a semantic version range: 

"smudgy://kapusniak/arctic-prompt@^1.0"

Use dependencies when the package executes an import such as: 

import "smudgy://kapusniak/arctic-prompt";

Use requires when the producer only needs to be installed and running: 

import { prompt } from "smudgy:events/kapusniak/arctic-prompt";

Installing a package also installs its dependencies and requirements. Published versions are immutable, so changing code or metadata requires a new version.

Install-time options

Each params entry has a stable key. Read the configured value from inside the package: 

import { get } from "smudgy:params";
 
const channel = get("channel");
if (typeof channel === "string") {
  console.log(`Configured channel: ${channel}`);
}

See smudgy:params for scalar, list, and table values.

Visibility and publishing

A published package is one of:

  • Private — available only to you and people you share it with.
  • Public — listed in Discover and installable by anyone.

Local packages exist only on your device. Public discovery uses hosts to show packages written for the current MUD without hiding universal packages.

smudgy