@laplace.live/persona-sdk 1.15.0 → 1.17.0

package/dist/values/limits.d.ts

@@ -1,4 +1,4 @@
-import type { AssetRef, Attach, EnvironmentLook, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneEnvironment, SceneLight, SceneLightCameraFollowOptions, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
+import type { AssetRef, Attach, AttachDepth, EnvironmentLook, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneEnvironment, SceneLight, SceneLightCameraFollowOptions, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
 export declare function clamp(v: number, min: number, max: number): number;
 /** Clamp to the unit interval. */
 export declare function clamp01(v: number): number;
@@ -173,11 +173,51 @@ export declare function objectSupportsSpace(kind: ObjectContent['kind'], space:
 /** The asset an object streams from, or null for kinds that carry their source inline (web, capture). */
 export declare function contentAssetId(content: ObjectContent): string | null;
 /**
- * The one model format a space's objects can ride: the renderers never mix, and
- * the three canvas always composites over the Pixi one, so a cross-space pin
- * would z-fight by construction.
+ * The one model format a space's objects can ride: the screen layer always composites
+ * over the world scene, so a cross-space pin would z-fight by construction.
  */
 export declare function attachableParentFormat(space: ObjectSpace): ModelFormat;
+/**
+ * Every instance that rides `instanceId`, directly or through a chain of pins — the set it can
+ * never pin to itself, or the two would ride each other in a circle. Includes `instanceId`.
+ */
+export declare function pinRiders(items: readonly {
+    instanceId: string;
+    attach?: {
+        parentInstanceId: string;
+    } | null;
+}[], instanceId: string): Set<string>;
+/**
+ * Rows for the pin picker: every other Live2D model, each flagged when it already rides
+ * `instanceId` — picking one would put the two in a circle, so both apps offer it disabled
+ * rather than hidden. One rule, or the console offers a pin the desktop refuses.
+ */
+export declare function pinnableParents(models: readonly {
+    instanceId: string;
+    ref: {
+        kind: string;
+        name: string;
+    };
+}[], items: readonly {
+    instanceId: string;
+    attach?: {
+        parentInstanceId: string;
+    } | null;
+}[], instanceId: string): {
+    instanceId: string;
+    name: string;
+    ridesThis: boolean;
+}[];
+/**
+ * The depth control's stops, back to front: behind the model, above each of its ArtMeshes in
+ * paint order, then in front of it all. One continuous run, so depth is a slider over the host's
+ * stack rather than a list of ArtMesh ids nobody can read.
+ */
+export declare function depthStops(meshes: readonly string[]): AttachDepth[];
+/** Which stop a depth sits at; an ArtMesh the host no longer has reads as the frontmost. */
+export declare function depthStopIndex(meshes: readonly string[], depth: AttachDepth): number;
+/** A fresh pin onto `parentInstanceId`: root anchor, in front of the model, no response tuning. */
+export declare function defaultAttach(parentInstanceId: string): Attach;
 export declare const DEFAULT_HEAD_ANGLE: NonNullable<Attach['headAngle']>;
 export declare const ATTACH_MULTIPLIER_MIN = -2;
 export declare const ATTACH_MULTIPLIER_MAX = 2;

package/dist/values/limits.js

@@ -297,13 +297,77 @@ export function contentAssetId(content) {
     return content.kind === 'image' || content.kind === 'video' || content.kind === 'prop' ? content.assetId : null;
 }
 /**
- * The one model format a space's objects can ride: the renderers never mix, and
- * the three canvas always composites over the Pixi one, so a cross-space pin
- * would z-fight by construction.
+ * The one model format a space's objects can ride: the screen layer always composites
+ * over the world scene, so a cross-space pin would z-fight by construction.
  */
 export function attachableParentFormat(space) {
     return space === '2d' ? 'live2d' : 'vrm';
 }
+/**
+ * Every instance that rides `instanceId`, directly or through a chain of pins — the set it can
+ * never pin to itself, or the two would ride each other in a circle. Includes `instanceId`.
+ */
+export function pinRiders(items, instanceId) {
+    const riders = new Set([instanceId]);
+    // One pass per item is enough for a chain of any depth: each pass adopts the next level down.
+    for (let i = 0; i < items.length; i++) {
+        let grew = false;
+        for (const item of items) {
+            const parent = item.attach?.parentInstanceId;
+            if (parent !== undefined && riders.has(parent) && !riders.has(item.instanceId)) {
+                riders.add(item.instanceId);
+                grew = true;
+            }
+        }
+        if (!grew)
+            break;
+    }
+    return riders;
+}
+/**
+ * Rows for the pin picker: every other Live2D model, each flagged when it already rides
+ * `instanceId` — picking one would put the two in a circle, so both apps offer it disabled
+ * rather than hidden. One rule, or the console offers a pin the desktop refuses.
+ */
+export function pinnableParents(models, items, instanceId) {
+    const riders = pinRiders(items, instanceId);
+    const out = [];
+    for (const m of models) {
+        if (m.ref.kind !== 'live2d' || m.instanceId === instanceId)
+            continue;
+        out.push({ instanceId: m.instanceId, name: m.ref.name, ridesThis: riders.has(m.instanceId) });
+    }
+    return out;
+}
+/**
+ * The depth control's stops, back to front: behind the model, above each of its ArtMeshes in
+ * paint order, then in front of it all. One continuous run, so depth is a slider over the host's
+ * stack rather than a list of ArtMesh ids nobody can read.
+ */
+export function depthStops(meshes) {
+    return [{ kind: 'behind' }, ...meshes.map((id) => ({ kind: 'artMesh', id })), { kind: 'front' }];
+}
+/** Which stop a depth sits at; an ArtMesh the host no longer has reads as the frontmost. */
+export function depthStopIndex(meshes, depth) {
+    if (depth.kind === 'behind')
+        return 0;
+    if (depth.kind === 'front')
+        return meshes.length + 1;
+    const at = meshes.indexOf(depth.id);
+    return at < 0 ? meshes.length + 1 : at + 1;
+}
+/** A fresh pin onto `parentInstanceId`: root anchor, in front of the model, no response tuning. */
+export function defaultAttach(parentInstanceId) {
+    return {
+        parentInstanceId,
+        anchor: { kind: 'root' },
+        followRotation: true,
+        depth: { kind: 'front' },
+        split: null,
+        headAngle: null,
+        elasticity: null,
+    };
+}
 export const DEFAULT_HEAD_ANGLE = {
     multiplier: 1,
     parallaxX: 0,

package/dist/wire/methods.d.ts

@@ -149,6 +149,16 @@ export interface InstanceSetPlacementRequest {
     vrm?: Partial<VrmPlacement>;
 }
 export type InstanceSetPlacementResponse = EmptyResponse;
+/**
+ * Pin a Live2D instance to another one as an item (VTS's Live2D Items): its placement becomes an
+ * offset from the anchor, and `attach.depth` says where it paints in the host's ArtMesh stack.
+ */
+export interface InstanceAttachRequest {
+    instanceId?: string;
+    /** Null detaches, leaving the instance where it stands. */
+    attach: AttachInput | null;
+}
+export type InstanceAttachResponse = EmptyResponse;
 export interface InstanceSetMToonRequest {
     instanceId?: string;
     tuning: Partial<MToonTuning>;
@@ -810,6 +820,10 @@ export interface MethodMap {
         request: InstanceSetPlacementRequest;
         response: InstanceSetPlacementResponse;
     };
+    'instance.attach': {
+        request: InstanceAttachRequest;
+        response: InstanceAttachResponse;
+    };
     'instance.setMToon': {
         request: InstanceSetMToonRequest;
         response: InstanceSetMToonResponse;

package/dist/wire/protocol.d.ts

@@ -18,9 +18,10 @@ export declare const INJECT_LEASE_TTL_MS = 1000;
 /** How often {@link PersonaClient.driveParameter} re-sends held leases to keep them alive. */
 export declare const INJECT_HEARTBEAT_MS = 100;
 /**
- * How often the binding editor's live indicators sample the tracking inputs (~20/s) — both the
- * stage's push and the editor's poll of it, which must agree. Fast enough to read as live on a
- * level bar, slow enough that neither the worker port nor the panel relay carries per-frame traffic.
+ * Least gap between the stage's refreshes of the tracking inputs behind the binding editor's live
+ * indicators (~20/s at most). The refresh rides the stage's frames, so a capped frame rate
+ * stretches it. Fast enough to read as live, slow enough that the worker port carries no
+ * per-frame traffic.
  */
 export declare const TRACKING_INPUTS_MS = 50;
 /**

package/dist/wire/protocol.js

@@ -17,9 +17,10 @@ export const INJECT_LEASE_TTL_MS = 1000;
 /** How often {@link PersonaClient.driveParameter} re-sends held leases to keep them alive. */
 export const INJECT_HEARTBEAT_MS = 100;
 /**
- * How often the binding editor's live indicators sample the tracking inputs (~20/s) — both the
- * stage's push and the editor's poll of it, which must agree. Fast enough to read as live on a
- * level bar, slow enough that neither the worker port nor the panel relay carries per-frame traffic.
+ * Least gap between the stage's refreshes of the tracking inputs behind the binding editor's live
+ * indicators (~20/s at most). The refresh rides the stage's frames, so a capped frame rate
+ * stretches it. Fast enough to read as live, slow enough that the worker port carries no
+ * per-frame traffic.
  */
 export const TRACKING_INPUTS_MS = 50;
 /**

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

@@ -255,10 +255,6 @@ export declare const requestSchemas: {
                     medium: "medium";
                 }>>;
                 renderScale: z.ZodOptional<z.ZodNumber>;
-                live2dEngine: z.ZodOptional<z.ZodEnum<{
-                    pixi: "pixi";
-                    three: "three";
-                }>>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
     }, z.core.$strip>;

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

@@ -1,10 +1,6 @@
 import * as z from 'zod';
 /** Shared field definitions; parsing validates values without adding defaults or healing them. */
 export declare const PortSchema: z.ZodNumber;
-export declare const Live2DEngineSchema: z.ZodEnum<{
-    pixi: "pixi";
-    three: "three";
-}>;
 export declare const EffectsQualitySchema: z.ZodEnum<{
     high: "high";
     low: "low";
@@ -110,10 +106,6 @@ export declare const PerformanceSettingsSchema: z.ZodObject<{
         medium: "medium";
     }>;
     renderScale: z.ZodNumber;
-    live2dEngine: z.ZodEnum<{
-        pixi: "pixi";
-        three: "three";
-    }>;
 }, z.core.$strip>;
 /** Stage content dimensions in device-independent pixels. */
 export declare const StageSizeSchema: z.ZodObject<{
@@ -201,10 +193,6 @@ export declare const SettingsSchema: z.ZodObject<{
             medium: "medium";
         }>;
         renderScale: z.ZodOptional<z.ZodNumber>;
-        live2dEngine: z.ZodOptional<z.ZodEnum<{
-            pixi: "pixi";
-            three: "three";
-        }>>;
     }, z.core.$strip>;
     tracking: z.ZodObject<{
         enabled: z.ZodBoolean;
@@ -276,9 +264,5 @@ export declare const SettingsPatchSchema: z.ZodObject<{
             medium: "medium";
         }>>;
         renderScale: z.ZodOptional<z.ZodNumber>;
-        live2dEngine: z.ZodOptional<z.ZodEnum<{
-            pixi: "pixi";
-            three: "three";
-        }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/wire/schemas/settings.js

@@ -2,10 +2,9 @@ import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../../values/controller.js";
 import { LIP_SYNC_GAIN_MAX, LIP_SYNC_MAX_SAMPLES, LIP_SYNC_MFCC_COEFFICIENTS, LIP_SYNC_MIN_SAMPLES, LIP_SYNC_NOISE_GATE_MIN, LIP_SYNC_PHONEMES, LIP_SYNC_SMOOTHING_MAX, } from "../../values/lipsync.js";
 import { LOCALES } from "../../values/locale.js";
-import { EFFECTS_QUALITY_LEVELS, LIVE2D_ENGINES, MEDIAPIPE_DELEGATES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "../types.js";
+import { EFFECTS_QUALITY_LEVELS, MEDIAPIPE_DELEGATES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "../types.js";
 /** Shared field definitions; parsing validates values without adding defaults or healing them. */
 export const PortSchema = z.number().int().min(1).max(65535).describe('Network port, from 1 through 65535.');
-export const Live2DEngineSchema = z.enum(LIVE2D_ENGINES).describe('Engine used to render Live2D models.');
 export const EffectsQualitySchema = z.enum(EFFECTS_QUALITY_LEVELS).describe('Scene and layer effects quality tier.');
 export const LanguageSettingSchema = z
     .enum(['system', ...LOCALES])
@@ -75,7 +74,6 @@ export const PerformanceSettingsSchema = z.object({
     fpsLimit: z.number().describe('Frame-rate cap; zero is unlimited. The desktop snaps changes to supported presets.'),
     effectsQuality: EffectsQualitySchema,
     renderScale: z.number().describe('Render resolution multiplier. The desktop snaps changes to supported presets.'),
-    live2dEngine: Live2DEngineSchema,
 });
 /** Stage content dimensions in device-independent pixels. */
 export const StageSizeSchema = z.object({
@@ -107,7 +105,7 @@ export const SettingsSchema = z.object({
     ui: z
         .object({ trayVisible: z.boolean().describe('Show the tray or menu bar icon.') })
         .describe('Public interface preferences.'),
-    performance: PerformanceSettingsSchema.partial({ renderScale: true, live2dEngine: true }).describe('Renderer settings; renderScale and live2dEngine are absent on older hosts.'),
+    performance: PerformanceSettingsSchema.partial({ renderScale: true }).describe('Renderer settings; renderScale is absent on older hosts.'),
     tracking: TrackingSettingsSchema.describe('Network face master switch and all configured tracking sources.'),
     pose: PoseSettingsSchema.describe('Network body master switch and legacy source mirrors.'),
 });

package/dist/wire/types.d.ts

@@ -198,6 +198,12 @@ export interface SceneModelItem {
     breathDepth: number;
     /** MToon material fine-tuning, VRM only. */
     mtoon: MToonTuning;
+    /**
+     * Live2D only: this model rides another one as an item (VTS's Live2D Items) — its placement
+     * reads as an offset from the anchor, and `depth` says where it paints in the parent's stack.
+     * Null stands alone; a VRM instance ignores it, keeping it across a format switch.
+     */
+    attach: Attach | null;
 }
 export declare const OBJECT_SPACES: readonly ["2d", "3d"];
 export type ObjectSpace = (typeof OBJECT_SPACES)[number];
@@ -275,11 +281,41 @@ export interface AttachElasticity {
     damping: number;
     maxSpeed: number;
 }
+/**
+ * How deep a pinned item paints in its parent — VTube Studio's Between-Layer Item Pinning, as one
+ * value: the two ends clear the parent's whole stack, and `artMesh` slots the item in directly
+ * above that ArtMesh, so every parent mesh over it paints on top. Ids rather than positions,
+ * because Cubism re-sorts the stack as motions play, and an id carries to any rig that has it.
+ * Live2D parents only: on a VRM an item always paints in front.
+ */
+export type AttachDepth = {
+    kind: 'front';
+} | {
+    kind: 'behind';
+} | {
+    kind: 'artMesh';
+    id: string;
+};
+/**
+ * VTube Studio's front/back splitting: the item is cut at one of its **own** ArtMeshes, and
+ * everything it paints below that goes to a second depth in the parent — so the parent's meshes
+ * in between wrap over it (a scarf in front of the chest and behind the hair). Live2D items only.
+ */
+export interface AttachSplit {
+    /** ArtMesh of the item it is cut at; the item paints everything under this as its back half. */
+    itemArtMesh: string;
+    /** How deep the back half paints — the same control as the item's own depth. */
+    depth: AttachDepth;
+}
 export interface Attach {
     /** Always a model instance in the same space; anything else is cleared on load. */
     parentInstanceId: string;
     anchor: AttachAnchor;
     followRotation: boolean;
+    /** Where it paints in the parent's ArtMesh stack; `front` is the plain "on top of the model". */
+    depth: AttachDepth;
+    /** Front/back splitting, independent of `depth`; null keeps the item in one piece. */
+    split: AttachSplit | null;
     headAngle: AttachHeadAngle | null;
     elasticity: AttachElasticity | null;
 }
@@ -1016,12 +1052,15 @@ export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'p
  | 'breath'
 /** `expression.setWeight`; Cubism expressions carry no user-settable weight, so Live2D lacks it. */
  | 'expression-weights'
-/** `speech.play` lip-sync; engine-dependent, so gate on the runtime, not the format. */
+/**
+ * `speech.play` lip-sync. Loaded Live2D models only; 0.53 and earlier hosts also omit it under
+ * the Pixi engine, so gate on the runtime, not the format.
+ */
  | 'speech'
 /**
  * Draws through the 3D post chain, so the scene's look rows (tone mapping, exposure, LUT)
- * reach it. Always on VRM; on Live2D only under the `three` renderer, so read it off the
- * runtime rather than the format.
+ * reach it. Every model; 0.53 and earlier hosts omit it on Pixi-engine Live2D, so read it off
+ * the runtime rather than the format.
  */
  | 'post-fx';
 export interface InstanceRuntime {
@@ -1059,6 +1098,11 @@ export interface PlayingMotion {
 export interface AnchorOption {
     anchor: AttachAnchor;
     label: string;
+    /**
+     * Paint order when the list was taken, ascending from the backmost — what the depth control
+     * orders its stops by. Live2D only, and absent from hosts older than depth pinning.
+     */
+    order?: number;
 }
 export type { ModelInfo } from '../values/model-info.ts';
 export interface Hotkey {
@@ -1116,8 +1160,6 @@ export interface ExpressionPersistence {
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export declare const LIVE2D_ENGINES: readonly ["pixi", "three"];
-export type Live2DEngine = (typeof LIVE2D_ENGINES)[number];
 export declare const TRACKING_SOURCE_IDS: readonly ["persona-ios", "ifacialmocap", "vts-ios"];
 export type TrackingSourceId = (typeof TRACKING_SOURCE_IDS)[number];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */

package/dist/wire/types.js

@@ -82,7 +82,6 @@ export const AUTOMATION_BOUNDARY_KINDS = [
     'load-model',
 ];
 // ---- Settings ------------------------------------------------------------------
-export const LIVE2D_ENGINES = ['pixi', 'three'];
 export const TRACKING_SOURCE_IDS = ['persona-ios', 'ifacialmocap', 'vts-ios'];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
 export const POSE_SOURCE_IDS = ['vmc', 'mocopi'];

package/package.json

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