@sculptr/sdk 0.0.0-stage → 2.17.1

package/dist/resources/object.d.ts

@@ -0,0 +1,109 @@
+import type { Engine, EventName, HostApi, Identity } from "../host";
+/**
+ * The added GML variables.
+ */
+export type ObjectVars<Name extends string> = Record<Name, string>;
+/**
+ * What is given to help create a GML block.
+ */
+export interface ObjectContext<Name extends string> {
+    /**
+     * Useful if your code needs to differ by GM version
+     */
+    engine: Engine;
+    /**
+     * List of modded vars for this GML
+     */
+    v: ObjectVars<Name>;
+    /**
+     * Sends an event to JavaScript:
+     * ```ts
+     * mod.resource.object.create({
+     *   name: "myObject",
+     *   events: {
+     *     create: ({ send }) => send("ping", `"Hello from GML"`),
+     *   },
+     * });
+     * ```
+     */
+    send(event: string, expression?: string): string;
+    /**
+     * Calls a script you previously defined:
+     * ```ts
+     * mod.resource.script.create({
+     *   name: "myScript",
+     *   // ...
+     * });
+     * mod.resource.object.create({
+     *   name: "myObject",
+     *   events: {
+     *     create: ({ call }) => `${call("myScript", "1")};`,
+     *   },
+     * });
+     * ```
+     */
+    call(script: string, ...args: string[]): string;
+}
+/**
+ * Same as @see ObjectContext but with the extra receive payload
+ */
+export interface ObjectReceiveContext<Name extends string> extends ObjectContext<Name> {
+    /**
+     * The GML variable holding this message's payload.
+     */
+    payload: string;
+}
+/**
+ * GML factory
+ */
+export type ObjectGml<Name extends string> = (context: ObjectContext<Name>) => string;
+/**
+ * GML factory for a receive event
+ */
+export type ObjectReceiveGml<Name extends string> = (context: ObjectReceiveContext<Name>) => string;
+export interface ObjectSpec<Name extends string> {
+    /**
+     * The object name can be simple as it will be mangled.
+     */
+    name: string;
+    vars?: readonly Name[];
+    events?: Partial<Record<EventName, ObjectGml<Name>>>;
+    /**
+     * GML to run when a given event is received:
+     * ```ts
+     * mod.resource.object.create({
+     *   name: "myObject",
+     *   receive: {
+     *     pong: ({ payload }) => `show_message(${payload});`,
+     *   },
+     * });
+     * ```
+     */
+    receive?: Record<string, ObjectReceiveGml<Name>>;
+    depth?: number;
+    persistent?: boolean;
+    visible?: boolean;
+}
+export interface ObjectActions {
+    /**
+     * Creates a new object.
+     */
+    create<const Name extends string = never>(spec: ObjectSpec<Name>): void;
+}
+/**
+ * Installs the mod's objects, plus the inbox object that sorts incoming events into queues.
+ */
+export declare const registerObjects: (data: {
+    identity: Identity;
+    hostApi: HostApi;
+    prefix: string;
+    objects: ObjectSpec<string>[];
+    /** GML the inbox runs for each of the library's own events. */
+    internalReceive: Record<string, string>;
+    /** GML appended to the inbox's Create. */
+    internalCreate: string;
+    normalizeEventName: (event: string) => string;
+    context: (spec: ObjectSpec<string>) => ObjectContext<string>;
+    queue: (event: string) => string;
+    scratch: (name: string) => string;
+}) => void;

package/dist/resources/script.d.ts

@@ -0,0 +1,184 @@
+import { type GameContent } from "../content";
+import type { At, Stmt } from "../decompiled-gml";
+import type { Engine, HostApi, Identity } from "../host";
+/**
+ * What is given to help create the GML block.
+ */
+export interface ScriptContext<Arg extends string> {
+    engine: Engine;
+    /** This script's arguments, by the names it declared: `a.value` is `argument0`. */
+    a: Record<Arg, string>;
+    /**
+     * Sends an event to JavaScript:
+     * ```ts
+     * mod.resource.script.create({
+     *   name: "myScript",
+     *   body: ({ send }) => send("ping", `"Hello from GML"`),
+     * });
+     * ```
+     */
+    send(event: string, expression?: string): string;
+    /**
+     * Calls a script you previously defined:
+     * ```ts
+     * mod.resource.script.create({
+     *   name: "myScript",
+     *   body: ({ call }) => `return ${call("myOtherScript", "1")};`,
+     * });
+     * ```
+     */
+    call(script: string, ...args: string[]): string;
+}
+export interface ScriptSpec<Arg extends string> {
+    /**
+     * The script name can be simple as it will be mangled.
+     */
+    name: string;
+    /**
+     * Script argument names:
+     * ```ts
+     * mod.resource.script.create({
+     *   name: "sum",
+     *   args: ["x", "y"],
+     *   body: ({ a }) => `return ${a.x} + ${a.y};`,
+     * });
+     * ```
+     */
+    args?: readonly Arg[];
+    body: (context: ScriptContext<Arg>) => string;
+}
+/**
+ * The script a hook replaced.
+ */
+export interface OriginalScript {
+    /**
+     * Calls the original. With no arguments it forwards the ones this call received.
+     */
+    call(...args: string[]): string;
+    /**
+     * Argument `index` of this call, as GML.
+     */
+    arg(index: number): string;
+    /**
+     * How many arguments this call received, as GML.
+     */
+    readonly argumentCount: string;
+}
+/**
+ * Same as @see ScriptContext but with the original instead of the arguments.
+ */
+export interface HookContext {
+    engine: Engine;
+    original: OriginalScript;
+    send(event: string, expression?: string): string;
+    call(script: string, ...args: string[]): string;
+}
+/**
+ * GML factory for a hook
+ */
+export type HookWrap = (context: HookContext) => string;
+/**
+ * Same as @see HookContext but with no original: an insertion runs beside the game's code, not
+ * instead of it.
+ */
+export interface InsertContext {
+    engine: Engine;
+    send(event: string, expression?: string): string;
+    call(script: string, ...args: string[]): string;
+}
+export interface InsertSpec {
+    /**
+     * The statement to run around, from `mod.content`. One the engine could not place is refused.
+     */
+    at: Stmt;
+    /**
+     * `"before"` it starts, or `"after"` it finishes -- once, on every way out of it. For a loop that
+     * is once when the loop ends; point at the last statement of its body to run per iteration.
+     *
+     * `"instead"` replaces it: the body runs and the statement does not.
+     */
+    place: "before" | "after" | "instead";
+    /**
+     * The GML to run there.
+     */
+    body: (context: InsertContext) => string;
+}
+export interface Hook {
+    script: string;
+    wrap: HookWrap;
+}
+export declare const registerHooks: (data: {
+    identity: Identity;
+    hooks: Hook[];
+    content: GameContent;
+    prefix: string;
+    hostApi: HostApi;
+    send(event: string, expression?: string | undefined): string;
+    call(script: string, ...args: string[]): string;
+}) => void;
+export interface Insert {
+    at: At;
+    place: "before" | "after" | "instead";
+    body: (context: InsertContext) => string;
+}
+/**
+ * The statement's token, refusing what only this side can see. The host checks the token, and the
+ * engine checks the address.
+ */
+export declare function insertToken(modId: string, spec: InsertSpec): At;
+/**
+ * Declares each body as a script, then the insertion calling it. Scripts first, so the call resolves.
+ */
+export declare const registerInserts: (data: {
+    identity: Identity;
+    inserts: Insert[];
+    prefix: string;
+    hostApi: HostApi;
+    send(event: string, expression?: string): string;
+    call(script: string, ...args: string[]): string;
+}) => void;
+export interface ScriptActions {
+    /**
+     * Creates a new script.
+     */
+    create<const Arg extends string = never>(spec: ScriptSpec<Arg>): void;
+    /**
+     * Replaces one of the game's scripts, keeping the original callable:
+     * ```ts
+     * mod.resource.script.hook("saveExe", ({ original, call }) => `
+     *   var result = ${original.call()};
+     *   ${call("afterLoad")};
+     *   return result;
+     * `);
+     * ```
+     *
+     * Only the game's own scripts: an object event has no caller to wrap.
+     */
+    hook(name: string, wrap: HookWrap): void;
+    /**
+     * Runs GML at one statement inside the game's code -- or in place of it -- leaving the rest
+     * alone:
+     * ```ts
+     * mod.resource.script.insert({
+     *   at: statement,
+     *   place: "after",
+     *   body: ({ send }) => send("saved", "string(room)"),
+     * });
+     * ```
+     *
+     * The body sees `self`, `other`, globals and builtins, but not the host script's `var` locals or
+     * its `argument0...`. Several insertions at one statement run in declaration order.
+     *
+     * Statements of the game's scripts and of its object events (`mod.content.events`). A statement
+     * the engine could not place carries no `at` and is refused here, by name.
+     */
+    insert(spec: InsertSpec): void;
+}
+export declare const registerScripts: (data: {
+    identity: Identity;
+    scripts: ScriptSpec<string>[];
+    prefix: string;
+    hostApi: HostApi;
+    send(event: string, expression?: string | undefined): string;
+    call(script: string, ...args: string[]): string;
+}) => void;

package/dist/resources/sprite.d.ts

@@ -0,0 +1,142 @@
+import type { Engine, HostApi, Identity } from "../host";
+import type { EventHandler } from "../utils";
+/** How long to wait for the game to confirm a picture before giving up on it. */
+export declare const SPRITE_TIMEOUT_MS = 15000;
+/** How long to give the game to say where its files live, before writing anyway. */
+export declare const WHERE_WAIT_MS = 2000;
+export interface SpriteOptions {
+    frames?: number;
+    origin?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Shrink any frame longer than this on its longest side before sending it.
+     */
+    maxSize?: number;
+}
+export interface SpriteSize {
+    width: number;
+    height: number;
+}
+/**
+ * The picture itself.
+ * Either a URL to fetch, a `data:` URI, or bytes.
+ */
+export type SpriteSource = string | Uint8Array | ArrayBuffer;
+/**
+ * A sprite this mod can fill with a picture while the game runs.
+ *
+ * Must be declared immediately but can be loaded anytime.
+ */
+export interface Sprite {
+    /**
+     * The sprite index, or `-1` if unloaded.
+     * ```
+     * draw: () => `if (${mySprite.id} >= 0) draw_sprite(${mySprite.id}, 0, x, y);`
+     * ```
+     */
+    readonly id: string;
+    /**
+     * Every frame must be the same size.
+     *
+     * @returns the sprite size
+     */
+    load(frames: SpriteSource[]): Promise<SpriteSize>;
+}
+export interface SpriteActions {
+    /**
+     * Creates a new sprite.
+     */
+    create(name: string, options?: SpriteOptions): Sprite;
+}
+export interface ImageKind {
+    extension: string;
+    type: string;
+}
+export declare const getImageKind: (bytes: Uint8Array) => ImageKind | null;
+/**
+ * The game restarted, and a newer load of the same pictures is on its way.
+ */
+export declare class SupersededTransfer extends Error {
+    constructor();
+}
+export declare const readBytes: (source: SpriteSource) => Promise<Uint8Array>;
+/**
+ * Lays several pictures out left to right as one PNG.
+ *
+ * Every frame has to be the same size.
+ */
+export declare const composeStrip: (images: Uint8Array[], maxSize?: number) => Promise<Uint8Array>;
+export declare const toPng: (bytes: Uint8Array, type: string, maxSize?: number) => Promise<Uint8Array>;
+/**
+ * The directory the game reads its mod files from, as a GML *value* it can report.
+ *
+ * The host writes the picture; what it needs back is the string the game puts in front of a
+ * filename, and only the game can say. `game_save_id` rather than `working_directory` for
+ * GameMaker Studio, and the difference is the whole point: a Studio runner re-roots every path a
+ * game opens into its save area, so a file written next to the game is looked for somewhere else
+ * entirely and reads as missing.
+ */
+export declare const scratchHere: (engine: Engine) => string;
+/** Everything the two sides say to each other about pictures. */
+export declare const SPR: {
+    /** host -> game: the picture is on the filesystem; add it. */
+    readonly put: "__spr_put";
+    /** game -> host: added, with its size. */
+    readonly ok: "__spr_ok";
+    /** game -> host: could not. */
+    readonly failed: "__spr_failed";
+    /** game -> host: I have (re)started, and hold no pictures. */
+    readonly hello: "__spr_hello";
+    /** game -> host: this is where I read files from. */
+    readonly where: "__spr_where";
+};
+export declare const getSpriteLoader: (data: {
+    identity: Identity;
+    hostApi: HostApi;
+    sendInternal: (event: string, payload?: string) => void;
+}) => {
+    loadSprite: (slot: string, options: SpriteOptions, source: SpriteSource | SpriteSource[], stillWanted?: () => boolean) => Promise<SpriteSize>;
+    where: (dir: string) => void;
+    done: (slot: string, size: SpriteSize) => void;
+    failed: (slot: string, reason: string) => void;
+    abandon: () => void | undefined;
+};
+export type SpriteLoader = ReturnType<typeof getSpriteLoader>;
+export interface DeclaredSprite {
+    name: string;
+    options: SpriteOptions;
+}
+/**
+ * Installs the GML half of the sprite transfer.
+ *
+ * @returns the GML handling each internal event, keyed by event name
+ */
+export declare const registerSprites: (data: {
+    hostApi: HostApi;
+    prefix: string;
+    sprites: DeclaredSprite[];
+    payload: string;
+    sendInternalGml: (event: string, expression?: string) => string;
+}) => Record<string, string>;
+/**
+ * The inbox object's Create: no sprites yet, and a word to the host.
+ *
+ * Runs again after a `game_restart()`, which frees every added sprite and wipes every global --
+ * hence the hello, which means "I hold nothing; send it all again". That costs a write and a
+ * message per picture, which is why nothing here tries to be clever about putting them back.
+ */
+export declare const spriteInboxCreate: (data: {
+    engine: Engine;
+    prefix: string;
+    sprites: DeclaredSprite[];
+    sendInternalGml: (event: string, expression?: string) => string;
+}) => string;
+export declare const registerSpriteHandlers: (data: {
+    identity: Identity;
+    sprites: DeclaredSprite[];
+    shown: Map<string, SpriteSource[]>;
+    spriteLoader: SpriteLoader;
+    handlers: Map<string, EventHandler[]>;
+}) => void;

package/dist/ui/index.d.ts

@@ -0,0 +1,232 @@
+/**
+ * A mod's own panel.
+ *
+ * The host shows it beside the running game, and in its own window for an installed one. The mod
+ * describes it once; after that it never renders again, it just writes to the values it declared and
+ * whatever showed them updates.
+ *
+ * ```ts
+ * const channel = mod.ui.state("", { persist: "channel" });
+ * const lines = mod.ui.state<string[]>([]);
+ *
+ * mod.ui.panel({ title: "Chat" }, (ui) => [
+ *   ui.input({ label: "Channel", value: channel }),
+ *   ui.scroll([ui.each(lines, (line) => ui.text(line), { key: (line) => line })], {
+ *     grow: true,
+ *     stickToBottom: true,
+ *   }),
+ * ]);
+ * ```
+ *
+ * These types mirror the loader's own, structurally. The SDK is a published package that must build
+ * on its own, so it states the shape it is written against rather than importing it -- the same way
+ * `HostApi` is declared here rather than depended on.
+ */
+/** A value the panel can show and the player can change. Read and write `.value`. */
+export interface Ref<T> {
+    value: T;
+}
+/** A value derived from other values. Rendered, never written to. */
+export interface ReadonlyRef<T> {
+    readonly value: T;
+}
+/**
+ * Anything a node property accepts.
+ *
+ * A plain value never changes. A `Ref` changes when you write to it. A function is read like a
+ * `computed` -- handy for a label built out of other values, without naming it first.
+ */
+export type Bindable<T> = T | Ref<T> | ReadonlyRef<T> | (() => T);
+/** What a render function returns, at any depth: one node, or several. */
+export type UiSpec = UiNodeSpec | readonly UiNodeSpec[];
+/** One node. Opaque -- build them with the `ui` builder, never by hand. */
+export interface UiNodeSpec {
+    readonly t: "element" | "dynamic" | "each";
+}
+/** How much a piece of text is trying to say. Never a colour: the app decides what these look like,
+ *  and looks different in the dark panel beside a game than it would on a page. */
+export type UiTone = "normal" | "muted" | "ok" | "warning" | "danger";
+/** A button's weight. */
+export type UiVariant = "normal" | "primary" | "danger" | "ghost";
+export type UiGap = "none" | "small" | "normal" | "large";
+export type UiAlign = "start" | "center" | "end" | "between";
+export interface UiSelectOption {
+    readonly value: string;
+    readonly label: string;
+}
+export interface UiSectionOptions {
+    title?: Bindable<string>;
+    /** Lets the player fold it away. The fold state belongs to the app, not to the mod. */
+    collapsible?: boolean;
+    grow?: boolean;
+}
+export interface UiRowOptions {
+    align?: UiAlign;
+    /** Defaults to true. The panel is narrow, and how narrow is not something a mod can know. */
+    wrap?: boolean;
+    grow?: boolean;
+}
+export interface UiColOptions {
+    gap?: UiGap;
+    grow?: boolean;
+}
+export interface UiScrollOptions {
+    grow?: boolean;
+    /** Keep the newest line in view as they arrive -- unless the player has scrolled up to read. */
+    stickToBottom?: boolean;
+    /**
+     * A fixed height in pixels, rather than however tall its contents happen to be.
+     *
+     * For a box whose whole job is to hold a growing list -- a chat log, a run of events -- where the
+     * panel jumping about as lines arrive is worse than the space an empty box costs. The box is the
+     * same height holding nothing as holding a hundred lines.
+     */
+    height?: number;
+}
+export interface UiTextOptions {
+    tone?: UiTone;
+    strong?: boolean;
+}
+export interface UiButtonOptions {
+    label: Bindable<string>;
+    onClick?: () => void;
+    variant?: UiVariant;
+    disabled?: Bindable<boolean>;
+    grow?: boolean;
+}
+export interface UiToggleOptions {
+    label: Bindable<string>;
+    /** A `Ref` here is two-way: the player flipping the switch writes it, like `v-model`. */
+    value: Bindable<boolean>;
+    onChange?: (value: boolean) => void;
+    disabled?: Bindable<boolean>;
+}
+export interface UiInputOptions {
+    /** A `Ref` here is two-way: what the player types is written straight into it. */
+    value: Bindable<string>;
+    label?: Bindable<string>;
+    placeholder?: Bindable<string>;
+    multiline?: boolean;
+    onChange?: (value: string) => void;
+    /** Enter in a single-line field. */
+    onSubmit?: () => void;
+    disabled?: Bindable<boolean>;
+    grow?: boolean;
+}
+export interface UiSelectOptions {
+    value: Bindable<string>;
+    options: Bindable<readonly UiSelectOption[]>;
+    label?: Bindable<string>;
+    onChange?: (value: string) => void;
+    disabled?: Bindable<boolean>;
+}
+export interface UiKeybindOptions {
+    /**
+     * A `KeyboardEvent.code` -- `"KeyH"`, `"ArrowLeft"`, `"Space"` -- or `""` for unbound. Two-way
+     * when it is a `Ref`, like every other control's value.
+     *
+     * The *physical* key, not the letter printed on it, so a binding made on AZERTY stays under the
+     * same finger. `gameMakerKey` turns one into the number GML checks.
+     */
+    value: Bindable<string>;
+    label?: Bindable<string>;
+    onChange?: (code: string) => void;
+    disabled?: Bindable<boolean>;
+}
+export interface UiEachOptions<T> {
+    /**
+     * Stable identity for one item.
+     *
+     * Required rather than defaulted to the position, because the position is wrong in exactly the
+     * case this exists for: add a line at the top and every position shifts, so a position-keyed list
+     * redraws itself entirely instead of inserting one row.
+     */
+    key: (item: T, index: number) => string | number;
+}
+/**
+ * Everything a panel is made of.
+ *
+ * Layout is expressed as intent, never as measurement: say which child should absorb the leftover
+ * room with `grow`, and let the app decide what that means at the width it happens to have. There
+ * are no pixels, no percentages and no styles here, which is what lets one panel work in a narrow
+ * sidebar, on a phone, and in a desktop window without its author having thought about any of them.
+ */
+export interface UiBuilder {
+    /** The primary grouping: a titled card. Vertical inside. */
+    section(options: UiSectionOptions, children: UiSpec): UiNodeSpec;
+    /** Horizontal, wrapping by default. */
+    row(children: UiSpec, options?: UiRowOptions): UiNodeSpec;
+    col(children: UiSpec, options?: UiColOptions): UiNodeSpec;
+    grid(children: UiSpec, options: {
+        columns: number;
+        grow?: boolean;
+    }): UiNodeSpec;
+    /** The one container that absorbs leftover height and scrolls. */
+    scroll(children: UiSpec, options?: UiScrollOptions): UiNodeSpec;
+    text(text: Bindable<string>, options?: UiTextOptions): UiNodeSpec;
+    badge(label: Bindable<string>, options?: {
+        tone?: UiTone;
+    }): UiNodeSpec;
+    separator(): UiNodeSpec;
+    spacer(): UiNodeSpec;
+    /** 0..1. */
+    progress(value: Bindable<number>, options?: {
+        label?: Bindable<string>;
+    }): UiNodeSpec;
+    button(options: UiButtonOptions): UiNodeSpec;
+    toggle(options: UiToggleOptions): UiNodeSpec;
+    input(options: UiInputOptions): UiNodeSpec;
+    select(options: UiSelectOptions): UiNodeSpec;
+    /**
+     * A key the player can rebind.
+     *
+     * **The one control whose value you cannot bake into your GML.** A mod's code is written before
+     * the player has said anything, so `keyboard_check_pressed(ord("H"))` fixes that key forever.
+     * Keep the key in an instance variable, send the new one down when it changes, and the binding
+     * follows. See `gameMakerKey` for the translation and a worked example.
+     */
+    keybind(options: UiKeybindOptions): UiNodeSpec;
+    /**
+     * A region that re-runs when any value it reads changes. For anything whose *shape* depends on
+     * state -- a conditional, a different set of controls once connected.
+     *
+     * Keep it synchronous: a value read after an `await` is read outside the region, so it is not
+     * noticed and the region will not re-run for it.
+     */
+    dynamic(fn: () => UiSpec): UiNodeSpec;
+    /**
+     * A keyed list.
+     *
+     * The item function runs per item and does not subscribe the list to what it reads, so one item's
+     * value moving updates that item alone rather than redrawing everything.
+     */
+    each<T>(source: Bindable<readonly T[]>, render: (item: T, index: number) => UiSpec, options: UiEachOptions<T>): UiNodeSpec;
+}
+export interface UiStateOptions {
+    /**
+     * Keep this value between sessions, under this name.
+     *
+     * Stored by the host against the player's account when they are signed in, and in the browser
+     * when they are not. It is an opaque bag as far as the app is concerned -- it stores what the mod
+     * puts there and never reads into it -- which is what lets a mod have settings without the host
+     * having to know what they are.
+     */
+    persist?: string;
+}
+/** `mod.ui`. */
+export interface ModUi {
+    /** A value the panel can show and the player can change. */
+    state<T>(initial: T, options?: UiStateOptions): Ref<T>;
+    /** A value derived from other values. */
+    computed<T>(fn: () => T): ReadonlyRef<T>;
+    /**
+     * Declares a panel. Only while the mod is being built, like every other thing it declares.
+     *
+     * The render function runs once. What keeps the panel live afterwards are the values it read, so
+     * there is nothing to call again and nothing for a mod to know about when its panel is on screen.
+     */
+    panel(options: {
+        id?: string;
+        title: string;
+    }, render: (ui: UiBuilder) => UiSpec): void;
+}

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+export declare const EVENT_NAME: RegExp;
+export declare const VAR_NAME: RegExp;
+export declare const SCRATCH_NAME: RegExp;
+export type EventHandler = (payload: string) => void | Promise<void>;