@hmcs/sdk 1.0.0

package/dist/vrm.js

@@ -0,0 +1,466 @@
+import { host } from './host.js';
+import { EventSource } from 'eventsource';
+import { entities } from './entities.js';
+
+/**
+ * Helper functions for building {@link VrmaRepeat} values.
+ *
+ * @example
+ * ```typescript
+ * await vrm.playVrma({
+ *   asset: "vrma:idle-maid",
+ *   repeat: repeat.forever(),
+ * });
+ *
+ * await vrm.playVrma({
+ *   asset: "vrma:grabbed",
+ *   repeat: repeat.count(3),
+ * });
+ * ```
+ */
+var repeat;
+(function (repeat) {
+    /**
+     * Repeat the animation forever.
+     */
+    function forever() {
+        return { type: "forever" };
+    }
+    repeat.forever = forever;
+    /**
+     * Play the animation once (no repeat).
+     */
+    function never() {
+        return { type: "never" };
+    }
+    repeat.never = never;
+    /**
+     * Repeat the animation a fixed number of times.
+     *
+     * @param n Positive integer repeat count.
+     * @throws {RangeError} If `n` is not a positive integer.
+     */
+    function count(n) {
+        if (!Number.isInteger(n) || !Number.isFinite(n) || n <= 0) {
+            throw new RangeError("repeat.count(n) requires a positive integer");
+        }
+        return { type: "count", count: n };
+    }
+    repeat.count = count;
+})(repeat || (repeat = {}));
+class VrmEventSource {
+    eventSource;
+    constructor(eventSource) {
+        this.eventSource = eventSource;
+    }
+    /**
+     * Registers an event listener for the specified event type.
+     */
+    on(event, callback) {
+        this.eventSource.addEventListener(event, e => {
+            callback(JSON.parse(e.data));
+        });
+    }
+    /**
+     * Closes the EventSource connection.
+     */
+    close() {
+        this.eventSource.close();
+    }
+    [Symbol.dispose]() {
+        this.eventSource.close();
+    }
+}
+class Vrm {
+    entity;
+    constructor(entity) {
+        this.entity = entity;
+    }
+    /**
+     * Returns an EventSource for receiving events related to this VRM entity.
+     */
+    events() {
+        const url = host.createUrl(`vrm/${this.entity}/events`);
+        return new VrmEventSource(new EventSource(url));
+    }
+    /**
+     * Returns the current state of the VRM.
+     */
+    async state() {
+        const response = await this.fetch("state");
+        const json = await response.json();
+        return json.state;
+    }
+    /**
+     * Sets the state of the VRM.
+     *
+     * @param state The new state to set.
+     */
+    async setState(state) {
+        await this.put("state", { state });
+    }
+    /**
+     * Returns the persona of the VRM.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const persona = await vrm.persona();
+     * console.log(persona.profile);
+     * ```
+     */
+    async persona() {
+        const response = await this.fetch("persona");
+        return await response.json();
+    }
+    /**
+     * Sets the persona of the VRM.
+     *
+     * @param persona The persona data to set.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.setPersona({
+     *   profile: "A cheerful assistant",
+     *   ocean: { openness: 0.8, extraversion: 0.7 },
+     *   metadata: {},
+     * });
+     * ```
+     */
+    async setPersona(persona) {
+        await this.put("persona", persona);
+    }
+    /**
+     * Returns the name of the VRM avatar.
+     */
+    async name() {
+        return await entities.name(this.entity);
+    }
+    /**
+     * Finds the entity ID of a bone by its name.
+     */
+    async findBoneEntity(bone) {
+        const response = await host.get(host.createUrl(`vrm/${this.entity}/bone/${bone}`));
+        return Number(await response.json());
+    }
+    /**
+     * Despawns this VRM entity.
+     */
+    async despawn() {
+        await host.deleteMethod(host.createUrl(`vrm/${this.entity}`));
+    }
+    /**
+     * Gets the current position of this VRM in both screen and world coordinates.
+     *
+     * @example
+     * ```ts
+     * const vrm = await Vrm.findByName("MyCharacter");
+     * const pos = await vrm.position();
+     * console.log(`Screen: (${pos.globalViewport?.[0]}, ${pos.globalViewport?.[1]})`);
+     * console.log(`World: (${pos.world[0]}, ${pos.world[1]}, ${pos.world[2]})`);
+     * ```
+     */
+    async position() {
+        const response = await this.fetch("position");
+        return await response.json();
+    }
+    /**
+     * Gets all expressions and their current weights, including metadata
+     * such as binary status and override settings.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const { expressions } = await vrm.expressions();
+     * for (const expr of expressions) {
+     *   console.log(`${expr.name}: ${expr.weight}`);
+     * }
+     * ```
+     */
+    async expressions() {
+        const response = await this.fetch("expressions");
+        return await response.json();
+    }
+    /**
+     * Sets expression weights, replacing all previous overrides.
+     * Expressions not included will return to VRMA animation control.
+     *
+     * @param weights A record of expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.setExpressions({ happy: 1.0, blink: 0.5 });
+     * ```
+     */
+    async setExpressions(weights) {
+        await this.put("expressions", { weights });
+    }
+    /**
+     * Modifies specific expression weights without affecting others (partial update).
+     * Existing overrides not mentioned remain unchanged.
+     *
+     * @param weights A record of expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * // Only modifies "happy", leaves other overrides intact
+     * await vrm.modifyExpressions({ happy: 1.0 });
+     * ```
+     */
+    async modifyExpressions(weights) {
+        await this.patch("expressions", { weights });
+    }
+    /**
+     * Clears all expression overrides, returning control to VRMA animation.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.clearExpressions();
+     * ```
+     */
+    async clearExpressions() {
+        await this.delete("expressions");
+    }
+    /**
+     * Modifies mouth expression weights for lip-sync.
+     * Unspecified mouth expressions are reset to 0.0.
+     * Non-mouth expression overrides are preserved.
+     *
+     * @param weights A record of mouth expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.modifyMouth({ aa: 0.8, oh: 0.2 });
+     * ```
+     */
+    async modifyMouth(weights) {
+        await this.patch("expressions/mouth", { weights });
+    }
+    /**
+     * Gets all spring bone chains.
+     */
+    async springBones() {
+        const response = await this.fetch("spring-bones");
+        return await response.json();
+    }
+    /**
+     * Gets a single spring bone chain by entity ID.
+     *
+     * @param chainId The chain entity ID.
+     */
+    async springBone(chainId) {
+        const response = await host.get(host.createUrl(`vrm/${this.entity}/spring-bones/${chainId}`));
+        return await response.json();
+    }
+    /**
+     * Updates spring bone properties for a chain.
+     *
+     * @param chainId The chain entity ID.
+     * @param props Partial properties to update.
+     */
+    async setSpringBone(chainId, props) {
+        await host.put(host.createUrl(`vrm/${this.entity}/spring-bones/${chainId}`), props);
+    }
+    /**
+     * Gets all VRMA animations for this VRM.
+     */
+    async listVrma() {
+        const response = await host.get(host.createUrl(`vrm/${this.entity}/vrma`));
+        return await response.json();
+    }
+    /**
+     * Plays a VRMA animation.
+     *
+     * @param options Play request options including asset, repeat, transition.
+     */
+    async playVrma(options) {
+        await this.post("vrma/play", options);
+    }
+    /**
+     * Stops a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation to stop.
+     */
+    async stopVrma(asset) {
+        await this.post("vrma/stop", { asset });
+    }
+    /**
+     * Gets the state of a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation to query.
+     */
+    async vrmaState(asset) {
+        const response = await host.get(host.createUrl(`vrm/${this.entity}/vrma/state`, { asset }));
+        return await response.json();
+    }
+    /**
+     * Sets the playback speed of a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation.
+     * @param speed The playback speed.
+     */
+    async setVrmaSpeed(asset, speed) {
+        await host.put(host.createUrl(`vrm/${this.entity}/vrma/speed`), { asset, speed });
+    }
+    /**
+     * Speaks using pre-generated audio with a timeline of expression keyframes.
+     * This allows any TTS engine to be used — the engine receives WAV audio and
+     * frame-synchronized lip-sync data.
+     *
+     * @param audio - WAV audio data as ArrayBuffer or Uint8Array.
+     * @param keyframes - Timeline keyframes specifying expression targets and durations.
+     * @param options - Optional settings (e.g. waitForCompletion).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const wavData = await fetchWavFromTTS("Hello world");
+     * await vrm.speakWithTimeline(wavData, [
+     *   { duration: 0.1, targets: { aa: 1.0 } },
+     *   { duration: 0.05 },
+     *   { duration: 0.12, targets: { oh: 1.0, happy: 0.5 } },
+     * ]);
+     * ```
+     */
+    async speakWithTimeline(audio, keyframes, options) {
+        const bytes = audio instanceof Uint8Array ? audio : new Uint8Array(audio);
+        let binary = '';
+        for (let i = 0; i < bytes.length; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        const base64Audio = btoa(binary);
+        await this.post("speech/timeline", {
+            audio: base64Audio,
+            keyframes,
+            ...options,
+        });
+    }
+    /**
+     * Looks at the mouse cursor.
+     */
+    async lookAtCursor() {
+        await this.put("look/cursor");
+    }
+    /**
+     * Sets the VRM's look-at target to a specific entity.
+     *
+     * @param target The entity ID to look at.
+     */
+    async lookAtTarget(target) {
+        await this.put(`look/target/${target}`);
+    }
+    /**
+     * Disables the VRM's look-at functionality.
+     */
+    async unlook() {
+        await this.delete("look");
+    }
+    /**
+     * Spawns a new VRM instance from the given mod asset ID.
+     */
+    static async spawn(asset, options) {
+        const response = await host.post(host.createUrl("vrm"), {
+            asset,
+            transform: options?.transform,
+            persona: options?.persona,
+        });
+        return new Vrm(Number(await response.text()));
+    }
+    /**
+     * Finds a VRM instance by its name.
+     *
+     * @param vrmName VRM avatar name
+     */
+    static async findByName(vrmName) {
+        const response = await host.get(host.createUrl("vrm", { name: vrmName }));
+        const entities = await response.json();
+        if (entities.length === 0) {
+            throw new Error(`VRM not found: ${vrmName}`);
+        }
+        return new Vrm(entities[0]);
+    }
+    /**
+     * Waits for a VRM instance to be spawned and initialized by its name.
+     *
+     * @param vrmName VRM avatar name
+     */
+    static async waitLoadByName(vrmName) {
+        const response = await host.get(host.createUrl("vrm/wait-load", {
+            name: vrmName,
+        }));
+        return new Vrm(Number(await response.json()));
+    }
+    /**
+     * Returns entity IDs of all currently loaded VRM instances.
+     *
+     * @example
+     * ```typescript
+     * const entities = await Vrm.findAllEntities();
+     * console.log(`Found ${entities.length} VRM entities`);
+     * ```
+     */
+    static async findAllEntities() {
+        const response = await host.get(host.createUrl("vrm"));
+        return await response.json();
+    }
+    /**
+     * Returns detailed snapshot of all VRM instances.
+     *
+     * @example
+     * ```typescript
+     * const snapshots = await Vrm.findAllDetailed();
+     * for (const s of snapshots) {
+     *   console.log(`${s.name}: ${s.state} at (${s.globalViewport?.[0]}, ${s.globalViewport?.[1]})`);
+     * }
+     * ```
+     */
+    static async findAllDetailed() {
+        const response = await host.get(host.createUrl("vrm/snapshot"));
+        return await response.json();
+    }
+    static streamMetadata(f) {
+        const es = new EventSource(host.createUrl("vrm/stream"));
+        es.addEventListener("message", (e) => {
+            f(JSON.parse(e.data));
+        });
+        return es;
+    }
+    /**
+     * Streams all currently existing VRM instances and any VRM instances that will be created in the future.
+     * @param f
+     */
+    static stream(f) {
+        return Vrm.streamMetadata(metadata => {
+            f(new Vrm(metadata.entity));
+        });
+    }
+    /**
+     * Returns all VRM instances that are currently loaded.
+     */
+    static async findAll() {
+        const entities = await Vrm.findAllEntities();
+        return entities.map(entity => new Vrm(entity));
+    }
+    async fetch(path) {
+        return await host.get(host.createUrl(`vrm/${this.entity}/${path}`));
+    }
+    async post(path, body) {
+        return await host.post(host.createUrl(`vrm/${this.entity}/${path}`), body);
+    }
+    async put(path, body) {
+        await host.put(host.createUrl(`vrm/${this.entity}/${path}`), body);
+    }
+    async patch(path, body) {
+        await host.patch(host.createUrl(`vrm/${this.entity}/${path}`), body);
+    }
+    async delete(path) {
+        await host.deleteMethod(host.createUrl(`vrm/${this.entity}/${path}`));
+    }
+}
+
+export { Vrm, VrmEventSource, repeat };