@dreamscript/server

The JavaScript and TypeScript SDK for DreamScript Script Packages.

The package remains platform-neutral. Paper-specific authored APIs come from @dreamscript/paper. Trusted JVM classes come from generated Binding Packages such as @dreamscript/java and @dreamscript/paper-api.

Package files

The package root exposes asynchronous JSON, UTF-8 string, and byte operations. The URI scheme selects read-only authored Package Resources or mutable Package State:

import { readJson, readString, writeJson } from "@dreamscript/server";

const defaults = await readJson("res://defaults.json");
await writeJson("user://saves/world.json", { day: 3 });
const message = await readString("user://message.txt");

res:// reads files beneath the calling package's authored data/ directory; writes to Package Resources reject. user:// URIs are scoped to the calling Package ID. State writes create parent directories, serialize per URI, and atomically replace one destination file. Package State remains after reload, shutdown, or source removal. The SDK does not infer schemas, migrate data, provide multi-file transactions, or delete state implicitly.

Tick scheduling

Use tick scheduling for gameplay work that must run at observable Minecraft tick boundaries:

import { schedule, scheduleRepeating } from "@dreamscript/server";

schedule(1, () => startEncounter());
const heartbeat = scheduleRepeating(0, 20, () => updateEncounter());
heartbeat.cancel();

Zero-delay work runs at the next tick boundary rather than inline. Repeating periods must be positive, and cancellation is idempotent. DreamScript owns each callback and cancels pending and repeating work when its Runtime Generation stops. Promises and standard Node timers remain available; each Active Package receives one non-blocking Node event-loop turn per server tick.

Trusted Java access

Generated Binding Package imports are the supported Java access path. JDK classes come from @dreamscript/java, Paper classes from @dreamscript/paper-api, and plugin classes from the Binding Package generated for that plugin. Each class is imported from its complete deterministic Java package subpath.

import { System } from "@dreamscript/java/java/lang/System";
import { WorldEdit } from "@dreamscript/worldedit-core/com/sk89q/worldedit/WorldEdit";

const now = System.currentTimeMillis();
const worldEdit = WorldEdit.getInstance();

Generated Paper-aware packages encode best-effort or named-plugin class loading in their Binding Recipe, so authored packages do not repeat ownership lookup strings. Raw Java.type and manual Paper.type class strings remain unsupported trusted interop escape hatches. Direct Java side effects are not DreamScript-managed registrations and cannot be rolled back when candidate activation fails.

Release

From the repository root, install locked development dependencies, run the authored SDK tests and strict typechecks, verify both public package shapes, and create the fingerprinted server and Paper artifacts with:

just pack-dreamscript-sdk

The artifacts are written to build/dreamscript-sdk/. Publish those exact verified artifacts to npm in dependency order with:

just publish-dreamscript-sdk

Pass another registry as the recipe argument when validating a release:

just publish-dreamscript-sdk http://127.0.0.1:4873/

Authentication comes from the caller's npm configuration or environment; do not commit npm credentials. Publication explicitly requests public scoped access. An absent version is published, an existing version with identical content is a successful no-op, and different content at an existing version is rejected with instructions to increment the affected package version.