@hmcs/sdk 1.0.0

package/README.md

@@ -0,0 +1,30 @@
+# @hmcs/sdk
+
+TypeScript SDK for building mods and extensions for [Desktop Homunculus](https://github.com/not-elm/desktop_homunculus).
+
+## Install
+
+```bash
+npm install @hmcs/sdk@https://github.com/desktop-homunculus/typescript-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Vrm } from "@hmcs/sdk";
+// Spawn a VRM character
+const vrm = await Vrm.spawn("my-mod:avatar");
+```
+
+## Function Style
+
+For SDK source code under `src/`, use the following style:
+
+- Use `function` / `async function` declarations for top-level public API functions and reusable top-level helpers.
+- Use arrow functions for inline callbacks (for example, array methods and event listeners).
+
+This keeps API boundaries explicit while preserving readability in callback-heavy code.
+
+## License
+
+MIT

package/dist/app.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * Provides access to the application API.
+ */
+exports.app = void 0;
+(function (app) {
+    /**
+     * Exits the application without any problems.
+     */
+    async function exit() {
+        await host.host.post(host.host.createUrl("app/exit"));
+    }
+    app.exit = exit;
+    /**
+     * Checks if the Desktop Homunculus server is running and healthy.
+     *
+     * Returns `true` if the server responds with a successful health check,
+     * `false` if the server is unreachable or unhealthy.
+     *
+     * @example
+     * ```typescript
+     * const alive = await app.health();
+     * if (!alive) {
+     *   console.error("Homunculus server is not running");
+     * }
+     * ```
+     */
+    async function health() {
+        try {
+            const response = await fetch(host.host.createUrl("app/health"));
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    app.health = health;
+    /**
+     * Returns metadata about the running Desktop Homunculus instance.
+     *
+     * Provides the engine version, platform info, compiled features,
+     * and loaded mods in a single request. Useful for startup checks,
+     * feature detection, and status displays.
+     *
+     * @returns Application info including version, platform, features, and mods
+     *
+     * @example
+     * ```typescript
+     * const info = await app.info();
+     * console.log(`Engine v${info.version} on ${info.platform.os}/${info.platform.arch}`);
+     * console.log(`Features: ${info.features.join(", ")}`);
+     * console.log(`${info.mods.length} mods loaded`);
+     * ```
+     */
+    async function info() {
+        const response = await host.host.get(host.host.createUrl("app/info"));
+        return await response.json();
+    }
+    app.info = info;
+})(exports.app || (exports.app = {}));

package/dist/app.js

@@ -0,0 +1,63 @@
+import { host } from './host.js';
+
+/**
+ * Provides access to the application API.
+ */
+var app;
+(function (app) {
+    /**
+     * Exits the application without any problems.
+     */
+    async function exit() {
+        await host.post(host.createUrl("app/exit"));
+    }
+    app.exit = exit;
+    /**
+     * Checks if the Desktop Homunculus server is running and healthy.
+     *
+     * Returns `true` if the server responds with a successful health check,
+     * `false` if the server is unreachable or unhealthy.
+     *
+     * @example
+     * ```typescript
+     * const alive = await app.health();
+     * if (!alive) {
+     *   console.error("Homunculus server is not running");
+     * }
+     * ```
+     */
+    async function health() {
+        try {
+            const response = await fetch(host.createUrl("app/health"));
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    app.health = health;
+    /**
+     * Returns metadata about the running Desktop Homunculus instance.
+     *
+     * Provides the engine version, platform info, compiled features,
+     * and loaded mods in a single request. Useful for startup checks,
+     * feature detection, and status displays.
+     *
+     * @returns Application info including version, platform, features, and mods
+     *
+     * @example
+     * ```typescript
+     * const info = await app.info();
+     * console.log(`Engine v${info.version} on ${info.platform.os}/${info.platform.arch}`);
+     * console.log(`Features: ${info.features.join(", ")}`);
+     * console.log(`${info.mods.length} mods loaded`);
+     * ```
+     */
+    async function info() {
+        const response = await host.get(host.createUrl("app/info"));
+        return await response.json();
+    }
+    app.info = info;
+})(app || (app = {}));
+
+export { app };

package/dist/assets.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * Assets API namespace for querying available mod assets.
+ *
+ * Provides access to the asset registry, which contains all assets declared
+ * by installed mods. Assets are referenced by their globally unique ID using
+ * the format `"mod-name:asset-name"` (e.g., `"elmer:idle"`, `"my-mod:click"`).
+ *
+ * @example
+ * ```typescript
+ * // List all available assets
+ * const all = await assets.list();
+ *
+ * // Filter by type
+ * const vrms = await assets.list({ type: "vrm" });
+ *
+ * // Filter by mod
+ * const elmerAssets = await assets.list({ mod: "elmer" });
+ * ```
+ */
+exports.assets = void 0;
+(function (assets) {
+    /**
+     * Lists available assets, optionally filtered by type and/or mod.
+     *
+     * @param filter - Optional filter criteria
+     * @returns Array of matching asset info objects
+     *
+     * @example
+     * ```typescript
+     * // Get all assets
+     * const all = await assets.list();
+     *
+     * // Get only VRM models
+     * const vrms = await assets.list({ type: "vrm" });
+     *
+     * // Get assets from a specific mod
+     * const modAssets = await assets.list({ mod: "elmer" });
+     *
+     * // Combine filters
+     * const sounds = await assets.list({ type: "sound", mod: "my-mod" });
+     * ```
+     */
+    async function list(filter) {
+        const response = await host.host.get(host.host.createUrl("assets", filter));
+        return await response.json();
+    }
+    assets.list = list;
+})(exports.assets || (exports.assets = {}));

package/dist/assets.js

@@ -0,0 +1,52 @@
+import { host } from './host.js';
+
+/**
+ * Assets API namespace for querying available mod assets.
+ *
+ * Provides access to the asset registry, which contains all assets declared
+ * by installed mods. Assets are referenced by their globally unique ID using
+ * the format `"mod-name:asset-name"` (e.g., `"elmer:idle"`, `"my-mod:click"`).
+ *
+ * @example
+ * ```typescript
+ * // List all available assets
+ * const all = await assets.list();
+ *
+ * // Filter by type
+ * const vrms = await assets.list({ type: "vrm" });
+ *
+ * // Filter by mod
+ * const elmerAssets = await assets.list({ mod: "elmer" });
+ * ```
+ */
+var assets;
+(function (assets) {
+    /**
+     * Lists available assets, optionally filtered by type and/or mod.
+     *
+     * @param filter - Optional filter criteria
+     * @returns Array of matching asset info objects
+     *
+     * @example
+     * ```typescript
+     * // Get all assets
+     * const all = await assets.list();
+     *
+     * // Get only VRM models
+     * const vrms = await assets.list({ type: "vrm" });
+     *
+     * // Get assets from a specific mod
+     * const modAssets = await assets.list({ mod: "elmer" });
+     *
+     * // Combine filters
+     * const sounds = await assets.list({ type: "sound", mod: "my-mod" });
+     * ```
+     */
+    async function list(filter) {
+        const response = await host.get(host.createUrl("assets", filter));
+        return await response.json();
+    }
+    assets.list = list;
+})(assets || (assets = {}));
+
+export { assets };

package/dist/audio.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * Audio API namespace for playing sound effects and background music.
+ *
+ * Provides functionality for one-shot sound effects ({@link audio.se}) and
+ * looping background music with transport controls ({@link audio.bgm}).
+ *
+ * @example
+ * ```typescript
+ * // Play a sound effect
+ * await audio.se.play("click");
+ *
+ * // Play background music with fade-in
+ * await audio.bgm.play("heme", {
+ *   volume: 0.8,
+ *   fadeIn: { durationSecs: 2.0 }
+ * });
+ *
+ * // Stop BGM with fade-out
+ * await audio.bgm.stop({ fadeOut: { durationSecs: 1.5 } });
+ * ```
+ */
+exports.audio = void 0;
+(function (audio) {
+    (function (se) {
+        /**
+         * Plays a one-shot sound effect.
+         *
+         * @param asset - The asset ID of the sound effect (e.g., `"click"`)
+         * @param options - Optional playback configuration
+         *
+         * @example
+         * ```typescript
+         * await audio.se.play("click");
+         *
+         * await audio.se.play("coin", {
+         *   volume: 0.7,
+         *   speed: 1.5,
+         *   panning: 0.3
+         * });
+         * ```
+         */
+        async function play(asset, options) {
+            await host.host.post(host.host.createUrl("audio/se"), { asset, ...options });
+        }
+        se.play = play;
+    })(audio.se || (audio.se = {}));
+    (function (bgm) {
+        /**
+         * Plays background music, replacing any currently playing BGM.
+         *
+         * @param asset - The asset ID of the music track (e.g., `"theme"`)
+         * @param options - Optional playback configuration
+         *
+         * @example
+         * ```typescript
+         * // Simple playback (loops by default)
+         * await audio.bgm.play("my-mod:battle");
+         *
+         * // With options
+         * await audio.bgm.play("my-mod:intro", {
+         *   loop: false,
+         *   volume: 0.6,
+         *   fadeIn: { durationSecs: 3.0, easing: "easeIn" }
+         * });
+         * ```
+         */
+        async function play(asset, options) {
+            await host.host.post(host.host.createUrl("audio/bgm"), { asset, ...options });
+        }
+        bgm.play = play;
+        /**
+         * Stops the currently playing BGM.
+         *
+         * @param options - Optional stop configuration (e.g., fade-out)
+         *
+         * @example
+         * ```typescript
+         * // Immediate stop
+         * await audio.bgm.stop();
+         *
+         * // Fade out over 2 seconds
+         * await audio.bgm.stop({
+         *   fadeOut: { durationSecs: 2.0, easing: "easeOut" }
+         * });
+         * ```
+         */
+        async function stop(options) {
+            await host.host.post(host.host.createUrl("audio/bgm/stop"), { ...options });
+        }
+        bgm.stop = stop;
+        /**
+         * Pauses the currently playing BGM.
+         *
+         * @example
+         * ```typescript
+         * await audio.bgm.pause();
+         * ```
+         */
+        async function pause() {
+            await host.host.post(host.host.createUrl("audio/bgm/pause"), {});
+        }
+        bgm.pause = pause;
+        /**
+         * Resumes paused BGM playback.
+         *
+         * @example
+         * ```typescript
+         * await audio.bgm.resume();
+         * ```
+         */
+        async function resume() {
+            await host.host.post(host.host.createUrl("audio/bgm/resume"), {});
+        }
+        bgm.resume = resume;
+        /**
+         * Updates playback parameters of the currently playing BGM.
+         *
+         * @param options - The parameters to update
+         *
+         * @example
+         * ```typescript
+         * // Fade volume to 0.3 over 1 second
+         * await audio.bgm.update({
+         *   volume: 0.3,
+         *   tween: { durationSecs: 1.0, easing: "easeInOut" }
+         * });
+         *
+         * // Change speed immediately
+         * await audio.bgm.update({ speed: 0.8 });
+         * ```
+         */
+        async function update(options) {
+            await host.host.patch(host.host.createUrl("audio/bgm"), options);
+        }
+        bgm.update = update;
+        /**
+         * Gets the current BGM playback status.
+         *
+         * @returns The current BGM status including asset, state, volume, and speed
+         *
+         * @example
+         * ```typescript
+         * const status = await audio.bgm.status();
+         * if (status.state === "playing") {
+         *   console.log(`Now playing: ${status.asset} at volume ${status.volume}`);
+         * }
+         * ```
+         */
+        async function status() {
+            const response = await host.host.get(host.host.createUrl("audio/bgm"));
+            return await response.json();
+        }
+        bgm.status = status;
+    })(audio.bgm || (audio.bgm = {}));
+})(exports.audio || (exports.audio = {}));

package/dist/audio.js

@@ -0,0 +1,159 @@
+import { host } from './host.js';
+
+/**
+ * Audio API namespace for playing sound effects and background music.
+ *
+ * Provides functionality for one-shot sound effects ({@link audio.se}) and
+ * looping background music with transport controls ({@link audio.bgm}).
+ *
+ * @example
+ * ```typescript
+ * // Play a sound effect
+ * await audio.se.play("click");
+ *
+ * // Play background music with fade-in
+ * await audio.bgm.play("heme", {
+ *   volume: 0.8,
+ *   fadeIn: { durationSecs: 2.0 }
+ * });
+ *
+ * // Stop BGM with fade-out
+ * await audio.bgm.stop({ fadeOut: { durationSecs: 1.5 } });
+ * ```
+ */
+var audio;
+(function (audio) {
+    (function (se) {
+        /**
+         * Plays a one-shot sound effect.
+         *
+         * @param asset - The asset ID of the sound effect (e.g., `"click"`)
+         * @param options - Optional playback configuration
+         *
+         * @example
+         * ```typescript
+         * await audio.se.play("click");
+         *
+         * await audio.se.play("coin", {
+         *   volume: 0.7,
+         *   speed: 1.5,
+         *   panning: 0.3
+         * });
+         * ```
+         */
+        async function play(asset, options) {
+            await host.post(host.createUrl("audio/se"), { asset, ...options });
+        }
+        se.play = play;
+    })(audio.se || (audio.se = {}));
+    (function (bgm) {
+        /**
+         * Plays background music, replacing any currently playing BGM.
+         *
+         * @param asset - The asset ID of the music track (e.g., `"theme"`)
+         * @param options - Optional playback configuration
+         *
+         * @example
+         * ```typescript
+         * // Simple playback (loops by default)
+         * await audio.bgm.play("my-mod:battle");
+         *
+         * // With options
+         * await audio.bgm.play("my-mod:intro", {
+         *   loop: false,
+         *   volume: 0.6,
+         *   fadeIn: { durationSecs: 3.0, easing: "easeIn" }
+         * });
+         * ```
+         */
+        async function play(asset, options) {
+            await host.post(host.createUrl("audio/bgm"), { asset, ...options });
+        }
+        bgm.play = play;
+        /**
+         * Stops the currently playing BGM.
+         *
+         * @param options - Optional stop configuration (e.g., fade-out)
+         *
+         * @example
+         * ```typescript
+         * // Immediate stop
+         * await audio.bgm.stop();
+         *
+         * // Fade out over 2 seconds
+         * await audio.bgm.stop({
+         *   fadeOut: { durationSecs: 2.0, easing: "easeOut" }
+         * });
+         * ```
+         */
+        async function stop(options) {
+            await host.post(host.createUrl("audio/bgm/stop"), { ...options });
+        }
+        bgm.stop = stop;
+        /**
+         * Pauses the currently playing BGM.
+         *
+         * @example
+         * ```typescript
+         * await audio.bgm.pause();
+         * ```
+         */
+        async function pause() {
+            await host.post(host.createUrl("audio/bgm/pause"), {});
+        }
+        bgm.pause = pause;
+        /**
+         * Resumes paused BGM playback.
+         *
+         * @example
+         * ```typescript
+         * await audio.bgm.resume();
+         * ```
+         */
+        async function resume() {
+            await host.post(host.createUrl("audio/bgm/resume"), {});
+        }
+        bgm.resume = resume;
+        /**
+         * Updates playback parameters of the currently playing BGM.
+         *
+         * @param options - The parameters to update
+         *
+         * @example
+         * ```typescript
+         * // Fade volume to 0.3 over 1 second
+         * await audio.bgm.update({
+         *   volume: 0.3,
+         *   tween: { durationSecs: 1.0, easing: "easeInOut" }
+         * });
+         *
+         * // Change speed immediately
+         * await audio.bgm.update({ speed: 0.8 });
+         * ```
+         */
+        async function update(options) {
+            await host.patch(host.createUrl("audio/bgm"), options);
+        }
+        bgm.update = update;
+        /**
+         * Gets the current BGM playback status.
+         *
+         * @returns The current BGM status including asset, state, volume, and speed
+         *
+         * @example
+         * ```typescript
+         * const status = await audio.bgm.status();
+         * if (status.state === "playing") {
+         *   console.log(`Now playing: ${status.asset} at volume ${status.volume}`);
+         * }
+         * ```
+         */
+        async function status() {
+            const response = await host.get(host.createUrl("audio/bgm"));
+            return await response.json();
+        }
+        bgm.status = status;
+    })(audio.bgm || (audio.bgm = {}));
+})(audio || (audio = {}));
+
+export { audio };