@sculptr/sdk 0.0.0-stage → 2.17.1

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @sculptr/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+WIP
+
+Write sculptr mods for GameMaker 8 and GameMaker Studio games.
+
+```sh
+npm install @sculptr/sdk
+```
+
+```ts
+import { createMod } from "@sculptr/sdk";
+
+export default createMod((mod) => {
+  mod.resource.object.create({
+    name: "greeter",
+    persistent: true,
+    events: {
+      create: ({ send }) => send("hello", "string(room)"),
+    },
+  });
+  mod.on("hello", (room) => console.log(`hello from ${room}`));
+});
+```

package/dist/content/index.d.ts

@@ -0,0 +1,54 @@
+import type { Block } from "../decompiled-gml";
+import type { EventName } from "../host";
+export interface ScriptContent {
+    readonly name: string;
+    readonly body: Block;
+}
+export interface ObjectContent {
+    readonly name: string;
+    /** The events the object declares itself, among the six a mod object can have. The same code is
+     *  in `GameContent.events` under the engine's own name for the event. */
+    readonly events: Partial<Record<EventName, Block>>;
+}
+/** One piece of the game's code, named so a mod can say which one it means. */
+export interface CodeContent {
+    /**
+     * How the engine names this piece of code -- `world.KeyPress_82`, `player.Collision_17`,
+     * `boss.Alarm_0` on GameMaker 8. Engine-specific on purpose: a name the engine itself uses is
+     * one you can find again in the IDE.
+     *
+     * For room code (`RoomCodeContent`) it is `<room>.room` or `<room>.instance_<id>`.
+     */
+    readonly name: string;
+    readonly body: Block;
+}
+/** one piece of code a room runs when it loads */
+export interface RoomCodeContent extends CodeContent {
+    /** the room whose load runs this */
+    readonly room: string;
+    /** the object of the instance this is the creation code of */
+    readonly object: string | null;
+}
+/** Game sound asset */
+export interface SoundContent {
+    readonly name: string;
+    /** Whether playing this sound stops whatever else was playing. */
+    readonly exclusive: boolean;
+}
+/**
+ * Game resources. Lossy. Useful for detecting patterns.
+ */
+export interface GameContent {
+    readonly scripts: readonly ScriptContent[];
+    readonly objects: readonly ObjectContent[];
+    /** every event every object declares, flat, as addressable code */
+    readonly events: readonly CodeContent[];
+    /** the game's sound assets */
+    readonly sounds: readonly SoundContent[];
+    /** a room's own creation code, and the creation code of each instance placed in it */
+    readonly rooms: readonly RoomCodeContent[];
+}
+/**
+ * The highest constant argument index a piece of the game's code reads, or -1 for none.
+ */
+export declare const highestArgument: (block: Block) => number;

package/dist/decompiled-gml.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Types for representing decompiled GML code.
+ * Useful for detecting patterns in a game (e.g. identify the "killPlayer" script, etc.)
+ */
+/**
+ * A GML block (list of statements), lossy.
+ */
+export type Block = Stmt[];
+/**
+ * Where a statement is, opaquely. Only good for `mod.resource.script.insert`, and only for the game
+ * and launch it came from, so never persist one.
+ */
+export type At = string & {
+    readonly __at: unique symbol;
+};
+/**
+ * A GML statement, lossy.
+ *
+ * `at` is absent when the engine could not place the statement (a `for` header's parts, a
+ * decompiler's temporary); inserting at one is refused.
+ */
+export type Stmt = {
+    k: "assign";
+    at?: At;
+    target: Expr;
+    op: "=" | "+=" | "-=" | "*=" | "/=" | "other";
+    value: Expr;
+} | {
+    k: "call";
+    at?: At;
+    call: CallExpr;
+} | {
+    k: "if";
+    at?: At;
+    cond: Expr;
+    then: Block;
+    else: Block;
+} | {
+    k: "with";
+    at?: At;
+    target: Expr;
+    body: Block;
+}
+/**
+ * Any loop
+ */
+ | {
+    k: "loop";
+    at?: At;
+    body: Block;
+} | {
+    k: "switch";
+    at?: At;
+    value: Expr;
+    bodies: Block[];
+} | {
+    k: "exit";
+    at?: At;
+    value: Expr | null;
+}
+/**
+ * Anything not modelled here: `break`, `continue`, a `case` label.
+ */
+ | {
+    k: "unknown";
+    at?: At;
+};
+/**
+ * Every statement in a block, in source order, descending into branches, bodies and cases:
+ * ```ts
+ * for (const stmt of walk(script.body)) {
+ *   if (stmt.k === "call" && stmt.call.name === "instance_destroy") ...
+ * }
+ * ```
+ */
+export declare function walk(block: Block): Generator<Stmt>;
+export type Expr = {
+    k: "number";
+    value: number;
+} | {
+    k: "string";
+    value: string;
+} | {
+    k: "constant";
+    name: string;
+} | {
+    k: "asset";
+    kind: "object" | "script" | "sprite" | "room" | "sound" | "other";
+    name: string;
+} | {
+    k: "var";
+    scope: "local" | "self" | "global" | "builtin";
+    name: string;
+} | {
+    k: "field";
+    of: Expr;
+    name: string;
+} | {
+    k: "index";
+    of: Expr;
+    at: Expr[];
+} | {
+    k: "arg";
+    index: number | null;
+} | CallExpr | {
+    k: "op";
+    op: string;
+    args: Expr[];
+} | {
+    k: "unknown";
+};
+export interface CallExpr {
+    k: "call";
+    kind: "script" | "builtin";
+    name: string;
+    args: Expr[];
+}

package/dist/host/index.d.ts

@@ -0,0 +1,160 @@
+import type { Block } from "../decompiled-gml";
+import type { ModUi } from "../ui";
+/**
+ * GameMaker version
+ *
+ * 8.1 and 8.2 are treated as gm8.
+ * Studio 1.4 and 2.x are treated as gms.
+ */
+export type Engine = "gm8" | "gms";
+/**
+ * The host's language
+ */
+export type Language = "en" | "zh-CN" | "ja" | "ko" | "es" | "pt-BR" | "de" | "fr" | "it" | "ru" | "pl";
+/**
+ * The object events accessible to a mod.
+ */
+export type EventName = "create" | "destroy" | "beginStep" | "step" | "endStep" | "draw";
+export interface Identity {
+    /**
+     * Unique across all mods. All mangled names are derived from it.
+     */
+    id: string;
+    version: string;
+}
+interface HostObject {
+    kind: "object";
+    name: string;
+    events: Partial<Record<EventName, string>>;
+    depth?: number;
+    persistent?: boolean;
+    visible?: boolean;
+}
+interface HostScript {
+    kind: "script";
+    name: string;
+    source: string;
+}
+interface HostHook {
+    kind: "hook";
+    script: string;
+    original: string;
+    source: string;
+}
+interface HostInsert {
+    kind: "insert";
+    /** The statement's opaque token, from `mod.content`. */
+    at: string;
+    place: "before" | "after" | "instead";
+    /** The asset name of a script declared alongside this. */
+    call: string;
+}
+interface HostGameCode {
+    scripts: {
+        name: string;
+        body: Block;
+    }[];
+    objects: {
+        name: string;
+        events: Partial<Record<EventName, Block>>;
+    }[];
+    events: {
+        name: string;
+        body: Block;
+    }[];
+    sounds: {
+        name: string;
+        exclusive: boolean;
+    }[];
+    rooms: {
+        name: string;
+        body: Block;
+        room: string;
+        object: string | null;
+    }[];
+}
+interface HostGml {
+    send(expression: string): string;
+    receive(variable: string): string;
+}
+/**
+ * The raw API exposed to a mod. You shouldn't need to use this directly.
+ */
+/**
+ * A chosen character. `sheet` is a 128x128 PNG: four 32x32 frames across, four rows down --
+ * idle, run, jump, fall, each row repeating its last frame if its animation is shorter.
+ *
+ * The bytes rather than a URL, so a mod needs no network -- and so it works in the main process,
+ * which cannot fetch the app's own scheme.
+ */
+export interface HostSkin {
+    readonly id: string;
+    readonly sheet: Uint8Array;
+}
+export type ControlAction = "up" | "down" | "left" | "right" | "confirm" | "cancel" | "retry";
+export declare const CANONICAL_CONTROL_KEYS: Readonly<Record<ControlAction, string>>;
+/** Every action, in the order the host shows them. */
+export declare const CONTROL_ACTIONS: readonly ControlAction[];
+/**
+ * What the player bound each action to
+ */
+export type HostControls = Readonly<Record<ControlAction, readonly string[]>>;
+/**
+ * Whether a binding is a controller input rather than a key.
+ *
+ * Controller bindings live in the same list as keys (`PadButton0`, `PadAxis1Plus`, ... -- the
+ * Gamepad API's standard-mapping indices). `gameMakerKey` answers `0` for them, so a mod that only
+ * deals in keys ignores them for free.
+ */
+export declare function isPadBinding(code: string): boolean;
+/** Who is playing. */
+export interface HostPlayer {
+    readonly account: {
+        readonly id: string;
+        readonly name: string;
+    } | null;
+    readonly skin: HostSkin | null;
+    readonly room: HostRoom | null;
+    readonly language: Language;
+    readonly controls: HostControls;
+}
+export interface HostRoom {
+    readonly id: string;
+}
+/**
+ * Handing bytes to the game as a file.
+ *
+ * The host always owns the filesystem the game reads: in the browser both engines share one
+ * virtual filesystem that lives in the app, and a native install is a real game reading real files
+ * the app put there. So a picture is written, not transmitted.
+ */
+export interface HostFiles {
+    /**
+     * Writes the bytes and answers with the path the *game* should open.
+     *
+     * `at` is the directory the game reported: the string it puts in front of a filename. A host
+     * whose filesystem is the game's own composes the path from it, so both sides mean the same file
+     * without anyone guessing how that engine resolves a relative name. A host writing a real file
+     * somewhere of its own choosing ignores it.
+     */
+    write(name: string, bytes: Uint8Array, at: string): Promise<string>;
+}
+export interface HostApi {
+    readonly identity: Identity;
+    readonly target: {
+        engine: Engine;
+    };
+    readonly game: HostGameCode;
+    getPlayer(): HostPlayer;
+    resource: {
+        create(resource: HostObject | HostScript | HostHook | HostInsert): void;
+    };
+    readonly gml: HostGml;
+    readonly files: HostFiles;
+    send(message: string): void;
+    readonly ui: ModUi;
+    on(event: "message", handler: (message: string) => void): void;
+    on(event: "start", handler: () => void): void;
+    on(event: "player", handler: (player: HostPlayer) => void): void;
+}
+export {};

package/dist/image/index.d.ts

@@ -0,0 +1,16 @@
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+export interface ImageRect extends ImageSize {
+    x: number;
+    y: number;
+}
+/**
+ * A PNG's dimensions, read from its header -- so no decoder, in either host.
+ */
+export declare const pngSize: (png: Uint8Array) => ImageSize;
+/**
+ * One rectangle of a picture, as its own PNG.
+ */
+export declare const sliceImage: (png: Uint8Array, rect: ImageRect) => Promise<Uint8Array>;

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import type { GameContent } from "./content";
+import type { Engine, HostApi, HostPlayer } from "./host";
+import { type ObjectActions } from "./resources/object";
+import { type ScriptActions } from "./resources/script";
+import { type SpriteActions } from "./resources/sprite";
+import type { ModUi } from "./ui";
+import { type EventHandler } from "./utils";
+export type { ControlAction, Engine, EventName, HostApi, HostControls, HostPlayer, HostRoom, HostSkin, Identity, Language, } from "./host";
+export { CANONICAL_CONTROL_KEYS, CONTROL_ACTIONS, isPadBinding } from "./host";
+export type { ImageRect, ImageSize } from "./image";
+export { pngSize, sliceImage } from "./image";
+export type { CodeContent, GameContent, ObjectContent, RoomCodeContent, ScriptContent, SoundContent, } from "./content";
+export { highestArgument } from "./content";
+export type { At, Block, CallExpr, Expr, Stmt } from "./decompiled-gml";
+export { walk } from "./decompiled-gml";
+export type { ObjectContext, ObjectGml, ObjectReceiveContext, ObjectReceiveGml, ObjectSpec, ObjectVars, } from "./resources/object";
+export type { HookContext, HookWrap, InsertContext, InsertSpec, OriginalScript, ScriptContext, ScriptSpec, } from "./resources/script";
+export type { Sprite, SpriteOptions, SpriteSize, SpriteSource } from "./resources/sprite";
+export type { EventHandler } from "./utils";
+export { gameMakerKey } from "./keyboard";
+export type { Bindable, ModUi, ReadonlyRef, Ref, UiAlign, UiBuilder, UiButtonOptions, UiColOptions, UiEachOptions, UiGap, UiInputOptions, UiKeybindOptions, UiNodeSpec, UiRowOptions, UiScrollOptions, UiSectionOptions, UiSelectOption, UiSelectOptions, UiSpec, UiStateOptions, UiTextOptions, UiToggleOptions, UiTone, UiVariant, } from "./ui";
+export interface Mod {
+    engine: Engine;
+    /**
+     * Who is playing, the character they chose, and the language the host is in. The first two are
+     * null when signed out; `skin` is also null when they never picked one, and `language` is always
+     * set.
+     *
+     * A function because it can change while the game runs, so read it again rather than keeping the
+     * result. During the mod's setup it is pinned -- on a native install that setup runs twice, once
+     * to bake the GML and once to run this JavaScript, and a mod whose resources depended on a live
+     * value could declare two different things.
+     */
+    getPlayer: () => HostPlayer;
+    /**
+     * The player signed in or out, picked a different character, or changed the host's language.
+     * Never during setup, so what a mod declares cannot depend on it -- only what it does with what
+     * it declared.
+     */
+    onPlayerChange(handler: (player: HostPlayer) => void): void;
+    /**
+     * Existing game content. Useful for detecting patterns.
+     */
+    content: GameContent;
+    /**
+     * Manipulate the game resources.
+     */
+    resource: {
+        object: ObjectActions;
+        script: ScriptActions;
+        sprite: SpriteActions;
+    };
+    /**
+     * A path for a scratch file as a GML expression.
+     * Not deleted automatically, so delete it once you're done.
+     */
+    scratchPath(name: string): string;
+    /**
+     * A call to one of this mod's own scripts, as GML.
+     *
+     * The same thing an event's context hands you, available without one -- which is what lets a
+     * library built on top of this declare scripts and then write calls to them without every one of
+     * its functions taking a context it does not otherwise need.
+     */
+    call(script: string, ...args: string[]): string;
+    /**
+     * Called once the game is running and can hear this mod.
+     */
+    onStart(handler: () => void): void;
+    /**
+     * Receive an event from GML to JS.
+     */
+    on(event: string, handler: EventHandler): void;
+    /**
+     * Send an event from JS to GML.
+     */
+    send(event: string, payload?: string): void;
+    /**
+     * This mod's own panel, shown beside the game while it runs.
+     *
+     * Where a mod's settings live. Rather than the host growing a checkbox for every mod that needs
+     * one -- which it cannot do at all for a mod it does not ship -- the mod brings its own UI and the
+     * app renders it without knowing what any of it means. See `ModUi`.
+     */
+    ui: ModUi;
+}
+export interface ModDefinition {
+    activate: (api: HostApi) => void;
+}
+/**
+ * Entry point for creating a mod
+ */
+export declare const createMod: (init: (mod: Mod) => void) => ModDefinition;