@laplace.live/persona-sdk 1.19.0 → 1.20.0

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from './values/limits.ts';
 export * from './values/lipsync.ts';
 export * from './values/locale.ts';
 export * from './values/model-info.ts';
+export * from './values/model-movement.ts';
 export * from './values/mouse.ts';
 export * from './values/scene-transition.ts';
 export * from './values/stage-info.ts';

package/dist/index.js

@@ -19,6 +19,7 @@ export * from "./values/limits.js";
 export * from "./values/lipsync.js";
 export * from "./values/locale.js";
 export * from "./values/model-info.js";
+export * from "./values/model-movement.js";
 export * from "./values/mouse.js";
 export * from "./values/scene-transition.js";
 export * from "./values/stage-info.js";

package/dist/values/model-movement.d.ts

@@ -0,0 +1,29 @@
+/**
+ * VTube Studio's Movement Config: how far tracked face position slides (`x`, `y`) and scales (`z`)
+ * a whole Live2D model. It moves the model itself and never writes a parameter, so it stacks with
+ * a rig that binds `FacePositionZ` to a parameter of its own. Amounts are signed — a negative one
+ * inverts its axis, 0 switches it off.
+ */
+export interface ModelMovementConfig {
+    enabled: boolean;
+    x: number;
+    y: number;
+    z: number;
+    /** Smoothing levels 0–100, read once when the model loads; file-only, as in VTS. */
+    smoothingX: number;
+    smoothingY: number;
+    smoothingZ: number;
+}
+/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
+export declare const MODEL_MOVEMENT_MAX = 20;
+/** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
+export declare const DEFAULT_MODEL_MOVEMENT: Readonly<ModelMovementConfig>;
+/**
+ * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
+ * written: VTS clamps its sliders to ±20, never what a file holds.
+ */
+export declare function healModelMovement(raw: unknown): ModelMovementConfig;
+/** What the Movement Config editor changes; a file's smoothing levels are left as they are. */
+export type ModelMovementEdit = Partial<Pick<ModelMovementConfig, 'enabled' | 'x' | 'y' | 'z'>>;
+/** An edit healed to the editor's limits; an absent or unusable field is dropped, not defaulted. */
+export declare function healModelMovementEdit(raw: unknown): ModelMovementEdit;

package/dist/values/model-movement.js

@@ -0,0 +1,44 @@
+import { finiteOr, isFiniteNumber, isRecord } from "./guards.js";
+import { clamp } from "./limits.js";
+/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
+export const MODEL_MOVEMENT_MAX = 20;
+/** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
+export const DEFAULT_MODEL_MOVEMENT = {
+    enabled: true,
+    x: 6,
+    y: 8,
+    z: 11,
+    smoothingX: 10,
+    smoothingY: 10,
+    smoothingZ: 10,
+};
+/**
+ * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
+ * written: VTS clamps its sliders to ±20, never what a file holds.
+ */
+export function healModelMovement(raw) {
+    const r = isRecord(raw) ? raw : {};
+    const d = DEFAULT_MODEL_MOVEMENT;
+    return {
+        enabled: typeof r.enabled === 'boolean' ? r.enabled : d.enabled,
+        x: finiteOr(r.x, d.x),
+        y: finiteOr(r.y, d.y),
+        z: finiteOr(r.z, d.z),
+        smoothingX: finiteOr(r.smoothingX, d.smoothingX),
+        smoothingY: finiteOr(r.smoothingY, d.smoothingY),
+        smoothingZ: finiteOr(r.smoothingZ, d.smoothingZ),
+    };
+}
+/** An edit healed to the editor's limits; an absent or unusable field is dropped, not defaulted. */
+export function healModelMovementEdit(raw) {
+    const r = isRecord(raw) ? raw : {};
+    const edit = {};
+    if (typeof r.enabled === 'boolean')
+        edit.enabled = r.enabled;
+    for (const axis of ['x', 'y', 'z']) {
+        const v = r[axis];
+        if (isFiniteNumber(v))
+            edit[axis] = clamp(Math.round(v), -MODEL_MOVEMENT_MAX, MODEL_MOVEMENT_MAX);
+    }
+    return edit;
+}

package/dist/wire/events.d.ts

@@ -1,3 +1,4 @@
+import type { ModelMovementConfig } from '../values/model-movement.ts';
 import type { AutomationInfo, ExpressionPersistence, HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, TrackingStatus } from './types.ts';
 /** Every push event a session can subscribe to, with its payload. */
 export interface EventMap {
@@ -70,6 +71,11 @@ export interface EventMap {
         modelId: string;
         persistence: ExpressionPersistence;
     };
+    /** A model's Movement Config changed, from any editor; every instance of the model follows it. */
+    'model.movement': {
+        modelId: string;
+        movement: ModelMovementConfig;
+    };
 }
 export type EventName = keyof EventMap;
 export type EventData<E extends EventName = EventName> = EventMap[E];

package/dist/wire/events.js

@@ -17,6 +17,7 @@ export const EVENT_NAMES = Object.keys({
     'selection.changed': true,
     'registry.changed': true,
     'expression.persistence': true,
+    'model.movement': true,
 });
 export function isEventName(v) {
     return isOneOf(v, EVENT_NAMES);

package/dist/wire/methods.d.ts

@@ -2,6 +2,7 @@ import type { Binding, BindingEditorData, BindingLiveValues } from '../values/bi
 import type { ControllerMovementConfig, ControllerState } from '../values/controller.ts';
 import type { SpawnTransition } from '../values/item-transition.ts';
 import type { LipSyncCalibrationCommand, LipSyncConfig, LipSyncMode, LipSyncState } from '../values/lipsync.ts';
+import type { ModelMovementConfig, ModelMovementEdit } from '../values/model-movement.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, TrackingLostBehavior, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
@@ -633,6 +634,23 @@ export interface BindingOverrideRequest extends BindingTarget {
     value: number | null;
 }
 export type BindingOverrideResponse = EmptyResponse;
+/** `modelId` defaults to the primary model's; movement is Live2D-only. */
+export interface ModelGetMovementRequest {
+    modelId?: string;
+}
+export interface ModelGetMovementResponse {
+    movement: ModelMovementConfig;
+}
+export interface ModelSetMovementRequest {
+    modelId?: string;
+    movement: ModelMovementEdit;
+}
+export interface ModelSetMovementResponse {
+    /** The configuration now moving the model, whether or not it reached the file. */
+    movement: ModelMovementConfig;
+    /** False when nothing reached the file: a refused write (read-only, unreadable), or no usable field. */
+    saved: boolean;
+}
 export interface InstanceSetBreathRequest {
     instanceId: string;
     breath?: boolean;
@@ -974,6 +992,14 @@ export interface MethodMap {
         request: ModelRegisterRequest;
         response: ModelRegisterResponse;
     };
+    'model.getMovement': {
+        request: ModelGetMovementRequest;
+        response: ModelGetMovementResponse;
+    };
+    'model.setMovement': {
+        request: ModelSetMovementRequest;
+        response: ModelSetMovementResponse;
+    };
     'asset.register': {
         request: AssetRegisterRequest;
         response: AssetRegisterResponse;

package/dist/wire/methods.js

@@ -60,6 +60,8 @@ export const METHOD_NAMES = Object.keys({
     'automation.run': true,
     'model.list': true,
     'model.register': true,
+    'model.getMovement': true,
+    'model.setMovement': true,
     'asset.list': true,
     'asset.register': true,
     'registry.thumbnail': true,

package/dist/wire/schemas/requests.d.ts

@@ -216,6 +216,13 @@ export declare const requestSchemas: {
     'model.register': z.ZodObject<{
         path: z.ZodString;
     }, z.core.$strip>;
+    'model.getMovement': z.ZodObject<{
+        modelId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    'model.setMovement': z.ZodObject<{
+        modelId: z.ZodOptional<z.ZodString>;
+        movement: z.ZodCustom<Partial<Pick<import("../../index.ts").ModelMovementConfig, "enabled" | "x" | "y" | "z">>, Partial<Pick<import("../../index.ts").ModelMovementConfig, "enabled" | "x" | "y" | "z">>>;
+    }, z.core.$strip>;
     'asset.register': z.ZodObject<{
         path: z.ZodString;
         want: z.ZodOptional<z.ZodEnum<{

package/dist/wire/schemas/requests.js

@@ -128,6 +128,12 @@ export const requestSchemas = {
     }),
     'tracking.removeSource': z.object({ id: nonEmpty }),
     'model.register': z.object({ path: nonEmpty }),
+    'model.getMovement': z.object({ modelId: nonEmpty.optional() }),
+    // Healed by the host like the desktop editor's own edits, so only the shape is checked here.
+    'model.setMovement': z.object({
+        modelId: nonEmpty.optional(),
+        movement: z.custom(isRecord, 'movement must be an object'),
+    }),
     // Straight off ASSET_KINDS: a kind added there has to reach the wire gate too, or
     // `want` answers invalid-params for a kind the registry already knows how to take.
     'asset.register': z.object({ path: nonEmpty, want: z.enum(ASSET_KINDS).optional() }),

package/dist/wire/types.d.ts

@@ -1041,7 +1041,7 @@ 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", "tracking-lost", "motion-stop", "stage-capture"];
+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", "stage-capture", "model-movement"];
 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`. */

package/dist/wire/types.js

@@ -53,6 +53,8 @@ export const APP_CAPABILITIES = [
     'motion-stop',
     /** `stage.capture`. */
     'stage-capture',
+    /** `model.getMovement` / `model.setMovement` and the `model.movement` event. */
+    'model-movement',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);

package/package.json

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