@laplace.live/persona-sdk 1.13.0 → 1.15.0

package/dist/values/labels.d.ts

@@ -7,6 +7,11 @@ export declare function fileBasename(path: string): string;
  * so the basename is the only identifier there is.
  */
 export declare function motionLabel(file: string): string;
+/**
+ * Label for one motion of a group: the group alone when the file just repeats it (a VRM clip
+ * group named for its file, or a loose VTS file whose group is its basename), else both.
+ */
+export declare function motionSlotLabel(group: string, file: string): string;
 /** Playable entries of a `MotionGroup` with their authored indices; an empty string is a missing file and keeps its slot. */
 export declare function motionSlots(files: readonly string[]): {
     file: string;

package/dist/values/labels.js

@@ -13,6 +13,14 @@ export function motionLabel(file) {
     const base = fileBasename(file);
     return base.replace(/\.motion3\.json$|\.exp3\.json$|\.vrma$|\.json$/i, '') || base;
 }
+/**
+ * Label for one motion of a group: the group alone when the file just repeats it (a VRM clip
+ * group named for its file, or a loose VTS file whose group is its basename), else both.
+ */
+export function motionSlotLabel(group, file) {
+    const name = motionLabel(file);
+    return group === file || name === group ? group : `${group} · ${name}`;
+}
 /** Playable entries of a `MotionGroup` with their authored indices; an empty string is a missing file and keeps its slot. */
 export function motionSlots(files) {
     return files.flatMap((file, index) => (file === '' ? [] : [{ file, index }]));

package/dist/values/limits.d.ts

@@ -81,6 +81,8 @@ export interface CameraDistanceLimits {
 export declare function cameraDistanceLimits(env: Pick<SceneEnvironment, 'modelAssetId' | 'modelPlace'>, setRadius: number | null): CameraDistanceLimits;
 /** ×2 doubles Cubism's own breath amplitude — past that the head sway reads as a nod, not a breath. */
 export declare const BREATH_DEPTH_MAX = 2;
+/** Seconds; a minute without a face is well past any dropout worth waiting out. */
+export declare const TRACKING_LOST_DELAY_MAX = 60;
 export declare const MTOON_NORMAL_SCALE_MAX = 2;
 export declare const MTOON_RIM_MAX = 2;
 /** ×0 flattens the Fresnel to a flood fill, ×4 tightens a default power-5 rim to a hairline. */

package/dist/values/limits.js

@@ -112,6 +112,8 @@ export function cameraDistanceLimits(env, setRadius) {
 }
 /** ×2 doubles Cubism's own breath amplitude — past that the head sway reads as a nod, not a breath. */
 export const BREATH_DEPTH_MAX = 2;
+/** Seconds; a minute without a face is well past any dropout worth waiting out. */
+export const TRACKING_LOST_DELAY_MAX = 60;
 export const MTOON_NORMAL_SCALE_MAX = 2;
 export const MTOON_RIM_MAX = 2;
 /** ×0 flattens the Fresnel to a flood fill, ×4 tightens a default power-5 rim to a hairline. */

package/dist/wire/events.d.ts

@@ -31,10 +31,12 @@ export interface EventMap {
         active: string[];
         weights?: Record<string, number>;
     };
+    /** `oneShot`: the motion outranks the idle, so `motion.stop` would end it; hosts with `motion-stop` send it. */
     'motion.started': {
         instanceId: string;
         group: string;
         index: number;
+        oneShot?: boolean;
     };
     'motion.ended': {
         instanceId: string;

package/dist/wire/methods.d.ts

@@ -4,7 +4,7 @@ import type { SpawnTransition } from '../values/item-transition.ts';
 import type { LipSyncCalibrationCommand, LipSyncConfig, LipSyncMode, LipSyncState } from '../values/lipsync.ts';
 import type { SceneInspection } from '../values/stage-info.ts';
 import type { EventName } from './events.ts';
-import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, Expression, ExpressionPersistence, HandTrackingMode, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, LayerEffectKey, LayerEffects, LayerEffectsPatch, MediaPipeConfig, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, SceneLight, SceneLightCameraFollowOptions, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
+import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, Expression, ExpressionPersistence, HandTrackingMode, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, LayerEffectKey, LayerEffects, LayerEffectsPatch, MediaPipeConfig, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, SceneLight, SceneLightCameraFollowOptions, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingLostBehavior, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
 /** Marker for methods that take no parameters; the client lets you omit the argument. */
 export type EmptyRequest = Record<never, never>;
 /** Marker for methods whose success response carries no data. */
@@ -157,7 +157,16 @@ export type InstanceSetMToonResponse = EmptyResponse;
 export interface InstanceSetIdleRequest {
     instanceId?: string;
     idleAnimation?: boolean;
+    /** VRM only. */
     idleClip?: string;
+    /** Live2D only: a motion file from `motion.list`, or null for the model's `Idle` group. */
+    idleMotion?: string | null;
+    /** The `tracking-lost` app capability carries these three. */
+    trackingLostBehavior?: TrackingLostBehavior;
+    /** Live2D only: a motion file from `motion.list`, or null for none. */
+    trackingLostMotion?: string | null;
+    /** Seconds, 0 to `TRACKING_LOST_DELAY_MAX`. */
+    trackingLostDelay?: number;
 }
 export type InstanceSetIdleResponse = EmptyResponse;
 export interface InstanceInfoRequest {
@@ -283,6 +292,16 @@ export interface MotionPlayingRequest {
 }
 export interface MotionPlayingResponse {
     playing: PlayingMotion | null;
+    /** `playing` outranks the idle — what `motion.stop` ends. Absent on hosts without `motion-stop`. */
+    oneShot?: boolean;
+}
+/** Fade the running motion out and let the idle resume; the idle itself is left alone. */
+export interface MotionStopRequest {
+    instanceId?: string;
+}
+export interface MotionStopResponse {
+    /** A motion above the idle was playing and is now fading out. */
+    stopped: boolean;
 }
 /** Play a clip with lip-sync. One utterance per model: a new play supersedes the current one. */
 export interface SpeechPlayRequest {
@@ -875,6 +894,11 @@ export interface MethodMap {
         request: MotionPlayingRequest;
         response: MotionPlayingResponse;
     };
+    /** Needs the `motion-stop` app capability. */
+    'motion.stop': {
+        request: MotionStopRequest;
+        response: MotionStopResponse;
+    };
     /**
      * Lip-synced audio on models advertising the `speech` capability. The response means
      * playback started (else `invalid-state`); `speech.started`/`speech.ended` bracket it.

package/dist/wire/types.d.ts

@@ -167,8 +167,28 @@ export interface SceneModelItem {
     controllerMovement: ControllerMovementConfig;
     live2d: ScreenPlacement;
     vrm: VrmPlacement;
+    /** Whether the idle base animation plays: VRM loops `idleClip`, Live2D `idleMotion`. */
     idleAnimation: boolean;
+    /** VRM: a bundled `.vrma` filename or `asset:<id>`. Kept while the instance shows a Live2D model. */
     idleClip: string;
+    /**
+     * Live2D: a motion file the model lists (as `motion.list` names it), looped beneath every
+     * other motion, or null for the model's own `Idle` group at random. A file the model no
+     * longer lists degrades to that group. Kept while the instance shows a VRM.
+     */
+    idleMotion: string | null;
+    /**
+     * What the tracked parameters do while the face is lost: keep the last pose until it is
+     * found again (`hold`), or ease back to the idle over ~0.3 s and return the same way (`idle`).
+     */
+    trackingLostBehavior: TrackingLostBehavior;
+    /**
+     * Live2D: a listed motion that replaces the idle once the face has been lost for
+     * `trackingLostDelay` seconds, until it is found again; null keeps the idle playing.
+     */
+    trackingLostMotion: string | null;
+    /** Seconds without a face before `trackingLostMotion` takes over. */
+    trackingLostDelay: number;
     /**
      * Live2D only: the engine's built-in idle breath. Beyond `ParamBreath` it also sways
      * `ParamAngle*`/`ParamBodyAngleX`, so a rig whose head ranges are tuned tightly may want it off.
@@ -985,11 +1005,13 @@ export interface ScenePatch {
  * App-level features a client gates on (never version-sniff): `hello` and
  * `app.info` report them — the per-app mirror of {@link InstanceRuntime.capabilities}.
  */
-export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost", "motion-stop"];
 export type AppCapability = (typeof APP_CAPABILITIES)[number];
 export declare function isAppCapability(v: unknown): v is AppCapability;
 /** What a loaded model instance can do; absent capabilities answer `unsupported-for-format`. */
-export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'placement-3d' | 'mtoon' | 'idle-clips' | 'pose' | 'live2d-params'
+export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'placement-3d' | 'mtoon' | 'idle-clips'
+/** `instance.setIdle` with `idleMotion`: one of the model's motions loops as its idle. Live2D only. */
+ | 'idle-motions' | 'pose' | 'live2d-params'
 /** `instance.setBreath`; the idle breathing loop is Cubism's, so VRM lacks it. */
  | 'breath'
 /** `expression.setWeight`; Cubism expressions carry no user-settable weight, so Live2D lacks it. */
@@ -1115,6 +1137,9 @@ export declare const TRACKING_CHANNEL_FIELDS: {
 };
 export declare const TRACKING_CHANNELS: readonly TrackingChannel[];
 export declare const HAND_TRACKING_MODES: readonly ["arms", "fingers"];
+/** How the face drivers react to a dropout; see `SceneModelInstance.trackingLostBehavior`. */
+export declare const TRACKING_LOST_BEHAVIORS: readonly ["hold", "idle"];
+export type TrackingLostBehavior = (typeof TRACKING_LOST_BEHAVIORS)[number];
 export type HandTrackingMode = (typeof HAND_TRACKING_MODES)[number];
 export declare function isHandTrackingMode(v: unknown): v is HandTrackingMode;
 export declare const MEDIAPIPE_DELEGATES: readonly ["CPU", "GPU"];

package/dist/wire/types.js

@@ -47,6 +47,10 @@ export const APP_CAPABILITIES = [
     'shadow-filters',
     'environment-map-model',
     'spawn',
+    /** `instance.setIdle` takes `trackingLostBehavior`, `trackingLostMotion` and `trackingLostDelay`. */
+    'tracking-lost',
+    /** `motion.stop`; `motion.playing` and `motion.started` carry `oneShot`. */
+    'motion-stop',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);
@@ -92,6 +96,8 @@ export const TRACKING_CHANNEL_FIELDS = {
 };
 export const TRACKING_CHANNELS = keysOf(TRACKING_CHANNEL_FIELDS);
 export const HAND_TRACKING_MODES = ['arms', 'fingers'];
+/** How the face drivers react to a dropout; see `SceneModelInstance.trackingLostBehavior`. */
+export const TRACKING_LOST_BEHAVIORS = ['hold', 'idle'];
 export function isHandTrackingMode(v) {
     return isOneOf(v, HAND_TRACKING_MODES);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",