@laplace.live/persona-sdk 1.11.0 → 1.12.0

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from './values/gltf-extensions.ts';
 export * from './values/guards.ts';
 export * from './values/hands.ts';
 export * from './values/hotkeys.ts';
+export * from './values/item-transition.ts';
 export * from './values/labels.ts';
 export * from './values/limits.ts';
 export * from './values/lipsync.ts';

package/dist/index.js

@@ -13,6 +13,7 @@ export * from "./values/gltf-extensions.js";
 export * from "./values/guards.js";
 export * from "./values/hands.js";
 export * from "./values/hotkeys.js";
+export * from "./values/item-transition.js";
 export * from "./values/labels.js";
 export * from "./values/limits.js";
 export * from "./values/lipsync.js";

package/dist/values/item-transition.d.ts

@@ -0,0 +1,23 @@
+export declare const ITEM_TRANSITION_STYLES: readonly ["glitch", "dither", "pop", "cut"];
+export type ItemTransitionStyle = (typeof ITEM_TRANSITION_STYLES)[number];
+/** One ramp length for a model switch, an object fade, or a body's entrance and exit. */
+export declare const ITEM_TRANSITION_DEFAULT_MS = 300;
+export declare const ITEM_TRANSITION_MAX_MS = 5000;
+export interface ItemTransition {
+    /**
+     * `glitch` tears and burns through a dithered dissolve, `dither` is the plain screen-door,
+     * `pop` scales in and out, `cut` switches.
+     */
+    style: ItemTransitionStyle;
+    /** Length of the ramp either way, 0–`ITEM_TRANSITION_MAX_MS`; 0 behaves as `cut`. */
+    durationMs: number;
+}
+export declare function defaultItemTransition(): ItemTransition;
+/** A per-call departure from the scene's item transition, for `stage.spawn`. */
+export interface SpawnTransition {
+    style?: ItemTransitionStyle;
+    /** Entrance ramp, 0–`ITEM_TRANSITION_MAX_MS`; defaults to the scene's duration. */
+    inMs?: number;
+    /** Exit ramp — expiry, eviction and clears — 0–`ITEM_TRANSITION_MAX_MS`; defaults to the scene's duration. */
+    outMs?: number;
+}

package/dist/values/item-transition.js

@@ -0,0 +1,9 @@
+// How stage items appear and disappear — models, objects and spawned bodies alike. Per scene,
+// on `SceneEnvironment.itemTransition`; `stage.spawn` may override it per call.
+export const ITEM_TRANSITION_STYLES = ['glitch', 'dither', 'pop', 'cut'];
+/** One ramp length for a model switch, an object fade, or a body's entrance and exit. */
+export const ITEM_TRANSITION_DEFAULT_MS = 300;
+export const ITEM_TRANSITION_MAX_MS = 5000;
+export function defaultItemTransition() {
+    return { style: 'glitch', durationMs: ITEM_TRANSITION_DEFAULT_MS };
+}

package/dist/values/limits.d.ts

@@ -35,6 +35,8 @@ export declare function sceneLightIsAimed(type: SceneLightType): boolean;
 export declare function sceneLightCastsShadows(type: SceneLightType): boolean;
 /** Whether a light of `type` can light volumetric haze; directional and ambient lights never do. */
 export declare function sceneLightCanHaze(type: SceneLightType): boolean;
+/** Whether `light` lights volumetric haze now: switched on, opted in, and of a type that can. */
+export declare function sceneLightHazes(light: Pick<SceneLight, 'type' | 'enabled' | 'volumetric'>): boolean;
 export declare const LIVE2D_SCALE_MIN = 0.1;
 export declare const LIVE2D_SCALE_MAX = 24;
 export declare const VRM_SCALE_MIN = 0.05;
@@ -150,6 +152,14 @@ export declare const PLACE_2D_SCALE_MIN = 0.01;
 export declare const PLACE_2D_SCALE_MAX = 50;
 export declare const PLACE_3D_SCALE_MIN = 0.01;
 export declare const PLACE_3D_SCALE_MAX = 100;
+/** Objects one `object.addMany` call may append. */
+export declare const OBJECT_ADD_MANY_MAX = 100;
+/** `stage.spawn` bounds: bodies per call, bodies alive at once (the oldest make room), scatter and throw ranges, lifetime. */
+export declare const SPAWN_COUNT_MAX = 200;
+export declare const SPAWN_ALIVE_MAX = 500;
+export declare const SPAWN_SPREAD_MAX = 20;
+export declare const SPAWN_SPEED_MAX = 50;
+export declare const SPAWN_TTL_MAX_MS = 600000;
 /** Web object viewport bounds, CSS px per side. */
 export declare const WEB_SIZE_MIN = 16;
 export declare const WEB_SIZE_MAX = 7680;

package/dist/values/limits.js

@@ -59,6 +59,10 @@ export function sceneLightCastsShadows(type) {
 export function sceneLightCanHaze(type) {
     return type === 'point' || type === 'spot' || type === 'area';
 }
+/** Whether `light` lights volumetric haze now: switched on, opted in, and of a type that can. */
+export function sceneLightHazes(light) {
+    return light.enabled !== false && light.volumetric === true && sceneLightCanHaze(light.type);
+}
 // Live2D bounds are the zoom clamp (zoom.ts re-exports these); VRM scales a world-space root.
 export const LIVE2D_SCALE_MIN = 0.1;
 export const LIVE2D_SCALE_MAX = 24;
@@ -268,6 +272,14 @@ export const PLACE_2D_SCALE_MIN = 0.01;
 export const PLACE_2D_SCALE_MAX = 50;
 export const PLACE_3D_SCALE_MIN = 0.01;
 export const PLACE_3D_SCALE_MAX = 100;
+/** Objects one `object.addMany` call may append. */
+export const OBJECT_ADD_MANY_MAX = 100;
+/** `stage.spawn` bounds: bodies per call, bodies alive at once (the oldest make room), scatter and throw ranges, lifetime. */
+export const SPAWN_COUNT_MAX = 200;
+export const SPAWN_ALIVE_MAX = 500;
+export const SPAWN_SPREAD_MAX = 20;
+export const SPAWN_SPEED_MAX = 50;
+export const SPAWN_TTL_MAX_MS = 600_000;
 /** Web object viewport bounds, CSS px per side. */
 export const WEB_SIZE_MIN = 16;
 export const WEB_SIZE_MAX = 7680;

package/dist/wire/methods.d.ts

@@ -1,5 +1,6 @@
 import type { Binding, BindingEditorData } from '../values/bindings.ts';
 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 { SceneInspection } from '../values/stage-info.ts';
 import type { EventName } from './events.ts';
@@ -168,10 +169,21 @@ export interface InstanceInfoResponse {
 export interface ObjectAddRequest {
     content: ObjectContent;
     name?: string;
+    /** Initial placement, so the object never draws a frame at the default one. Omitted axes keep it. */
+    place2d?: Partial<Place2D>;
+    place3d?: Partial<Place3D>;
 }
 export interface ObjectAddResponse {
     instanceId: string;
 }
+/** Up to `OBJECT_ADD_MANY_MAX` objects as one scene edit: one stage apply, one persist, one undo step. */
+export interface ObjectAddManyRequest {
+    objects: ObjectAddRequest[];
+}
+export interface ObjectAddManyResponse {
+    /** In request order. */
+    instanceIds: string[];
+}
 export interface ObjectRenameRequest {
     instanceId: string;
     name: string;
@@ -414,6 +426,44 @@ export interface StageResetTransformRequest {
 export type StageResetTransformResponse = EmptyResponse;
 export type StageResetCameraRequest = EmptyRequest;
 export type StageResetCameraResponse = EmptyResponse;
+/** A world-space vector: metres, or metres per second for a velocity. */
+export interface StageVector {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Drop physics-driven copies of a prop asset onto the stage. They live in the renderer only —
+ * no scene item, no undo, no persistence — and clear with the scene, with Physics, or on
+ * `stage.clearSpawned`. Needs the scene's Physics switch on (`invalid-state` otherwise).
+ */
+export interface StageSpawnRequest {
+    /** A registered `prop` asset. */
+    assetId: string;
+    /** 1–`SPAWN_COUNT_MAX`; default 1. Past `SPAWN_ALIVE_MAX` alive bodies, the oldest make room. */
+    count?: number;
+    /** Centre of the scatter box, metres; default `{ x: 0, y: 3, z: 0 }`, above where an avatar stands. */
+    origin?: StageVector;
+    /** Edge of the scatter box around `origin`, 0–`SPAWN_SPREAD_MAX` metres; default 1. */
+    spread?: number;
+    /** Initial velocity every body shares, each axis within ±`SPAWN_SPEED_MAX`; default at rest. */
+    velocity?: StageVector;
+    /** Placement scale, `PLACE_3D_SCALE_MIN`–`PLACE_3D_SCALE_MAX`; default 1. */
+    scale?: number;
+    /** Lifetime before a body vanishes, 0–`SPAWN_TTL_MAX_MS`; 0 keeps it until cleared. Default 30000. */
+    ttlMs?: number;
+    /** How these bodies appear and disappear; omitted fields take the scene's `itemTransition`. */
+    transition?: SpawnTransition;
+}
+export interface StageSpawnResponse {
+    spawned: number;
+    /** Bodies alive after this call, across every asset. */
+    alive: number;
+}
+export type StageClearSpawnedRequest = EmptyRequest;
+export interface StageClearSpawnedResponse {
+    cleared: number;
+}
 export type AppInfoRequest = EmptyRequest;
 export interface AppInfoResponse {
     name: string;
@@ -759,6 +809,10 @@ export interface MethodMap {
         request: ObjectAddRequest;
         response: ObjectAddResponse;
     };
+    'object.addMany': {
+        request: ObjectAddManyRequest;
+        response: ObjectAddManyResponse;
+    };
     'object.rename': {
         request: ObjectRenameRequest;
         response: ObjectRenameResponse;
@@ -926,6 +980,14 @@ export interface MethodMap {
         request: StageResetCameraRequest;
         response: StageResetCameraResponse;
     };
+    'stage.spawn': {
+        request: StageSpawnRequest;
+        response: StageSpawnResponse;
+    };
+    'stage.clearSpawned': {
+        request: StageClearSpawnedRequest;
+        response: StageClearSpawnedResponse;
+    };
     'app.info': {
         request: AppInfoRequest;
         response: AppInfoResponse;

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

@@ -1,6 +1,6 @@
 import * as z from 'zod';
 import type { MethodName } from '../methods.ts';
-import type { HotkeyConfig, ObjectContent } from '../types.ts';
+import type { HotkeyConfig, ObjectContent, Place2D, Place3D } from '../types.ts';
 /** A complete transition replacement; scene.patch remains stage-owned for its other slices. */
 export declare const SceneTransitionSchema: z.ZodObject<{
     type: z.ZodEnum<{
@@ -132,6 +132,16 @@ export declare const requestSchemas: {
     'object.add': z.ZodObject<{
         content: z.ZodCustom<ObjectContent, ObjectContent>;
         name: z.ZodOptional<z.ZodString>;
+        place2d: z.ZodOptional<z.ZodCustom<Partial<Place2D>, Partial<Place2D>>>;
+        place3d: z.ZodOptional<z.ZodCustom<Partial<Place3D>, Partial<Place3D>>>;
+    }, z.core.$strip>;
+    'object.addMany': z.ZodObject<{
+        objects: z.ZodArray<z.ZodObject<{
+            content: z.ZodCustom<ObjectContent, ObjectContent>;
+            name: z.ZodOptional<z.ZodString>;
+            place2d: z.ZodOptional<z.ZodCustom<Partial<Place2D>, Partial<Place2D>>>;
+            place3d: z.ZodOptional<z.ZodCustom<Partial<Place3D>, Partial<Place3D>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     'object.setContent': z.ZodObject<{
         instanceId: z.ZodString;
@@ -297,6 +307,33 @@ export declare const requestSchemas: {
     'speech.stop': z.ZodObject<{
         instanceId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+    'stage.spawn': z.ZodObject<{
+        assetId: z.ZodString;
+        count: z.ZodOptional<z.ZodNumber>;
+        origin: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strip>>;
+        spread: z.ZodOptional<z.ZodNumber>;
+        velocity: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strip>>;
+        scale: z.ZodOptional<z.ZodNumber>;
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+        transition: z.ZodOptional<z.ZodObject<{
+            style: z.ZodOptional<z.ZodEnum<{
+                glitch: "glitch";
+                dither: "dither";
+                pop: "pop";
+                cut: "cut";
+            }>>;
+            inMs: z.ZodOptional<z.ZodNumber>;
+            outMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
     'events.subscribe': z.ZodObject<{
         events: z.ZodArray<z.ZodCustom<keyof import("../events.ts").EventMap, keyof import("../events.ts").EventMap>>;
     }, z.core.$strip>;

package/dist/wire/schemas/requests.js

@@ -1,7 +1,8 @@
 import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../../values/controller.js";
 import { isRecord } from "../../values/guards.js";
-import { SCENE_COLOR_RE, SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../../values/limits.js";
+import { ITEM_TRANSITION_STYLES } from "../../values/item-transition.js";
+import { OBJECT_ADD_MANY_MAX, SCENE_COLOR_RE, SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../../values/limits.js";
 import { LIP_SYNC_CALIBRATION_ACTIONS, LIP_SYNC_MODES, LIP_SYNC_PHONEMES, } from "../../values/lipsync.js";
 import { SCENE_TRANSITION_DURATION_MAX_MS, SCENE_TRANSITION_DURATION_MIN_MS, SCENE_TRANSITION_FADE_DEFAULT_MS, SCENE_TRANSITION_SWITCH_POINT_MAX, SCENE_TRANSITION_SWITCH_POINT_MIN, SCENE_TRANSITION_TYPES, } from "../../values/scene-transition.js";
 import { ASSET_KINDS, INJECT_TARGET_TYPES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "../types.js";
@@ -59,6 +60,14 @@ const speechUrl = z
         return false;
     }
 }, 'url must be http(s) or data:audio/*');
+// Placements are healed stage-side like `object.setPlacement`'s; only the container is gated here.
+const objectAdd = z.object({
+    content: z.custom(isRecord, 'content must be an object'),
+    name: nonEmpty.optional(),
+    place2d: z.custom(isRecord, 'place2d must be an object').optional(),
+    place3d: z.custom(isRecord, 'place3d must be an object').optional(),
+});
+const stageVector = z.object({ x: z.number(), y: z.number(), z: z.number() });
 export const requestSchemas = {
     'lipSync.state': z.object({}),
     'lipSync.configure': lipSyncPatch,
@@ -85,10 +94,8 @@ export const requestSchemas = {
     }),
     'instance.add': z.object({ modelId: nonEmpty }),
     'instance.setModel': z.object({ instanceId: nonEmpty, modelId: nonEmpty }),
-    'object.add': z.object({
-        content: z.custom(isRecord, 'content must be an object'),
-        name: nonEmpty.optional(),
-    }),
+    'object.add': objectAdd,
+    'object.addMany': z.object({ objects: z.array(objectAdd).min(1).max(OBJECT_ADD_MANY_MAX) }),
     'object.setContent': z.object({
         instanceId: nonEmpty,
         content: z.custom(isRecord, 'content must be an object'),
@@ -144,6 +151,23 @@ export const requestSchemas = {
         volume: z.number().min(0).max(1).optional(),
     }),
     'speech.stop': z.object({ instanceId: nonEmpty.optional() }),
+    // Main needs the asset id to resolve; the stage clamps the rest, so the numbers are gated shallowly.
+    'stage.spawn': z.object({
+        assetId: nonEmpty,
+        count: z.number().optional(),
+        origin: stageVector.optional(),
+        spread: z.number().optional(),
+        velocity: stageVector.optional(),
+        scale: z.number().optional(),
+        ttlMs: z.number().optional(),
+        transition: z
+            .object({
+            style: z.enum(ITEM_TRANSITION_STYLES).optional(),
+            inMs: z.number().optional(),
+            outMs: z.number().optional(),
+        })
+            .optional(),
+    }),
     'events.subscribe': z.object({ events: z.array(lenientEventNameSchema).min(1) }),
     'events.unsubscribe': z.object({ events: z.array(lenientEventNameSchema).optional() }),
     'param.inject': z.object({ entries: z.array(InjectEntrySchema).min(1) }),

package/dist/wire/types.d.ts

@@ -1,5 +1,6 @@
 import type * as z from 'zod';
 import type { EFFECT_BLEND_MODES, EFFECT_SCOPES } from '../values/effect-schema.ts';
+import type { ItemTransition } from '../values/item-transition.ts';
 import type { SCENE_TRANSITION_TYPES } from '../values/scene-transition.ts';
 import type { SettingsPatchSchema, SettingsSchema } from './schemas/settings.ts';
 import { type ArkitInputName } from '../values/arkit.ts';
@@ -922,6 +923,8 @@ export interface SceneEnvironment {
      * The simulated pose is never saved — switching it off restores each object's placement.
      */
     physics?: boolean;
+    /** How models, objects and spawned bodies appear and disappear; omitted by older hosts. */
+    itemTransition?: ItemTransition;
     effects: SceneEffects;
     /**
      * Built-in effects added as layers, in registry order — one keeps its row and tuning while
@@ -981,7 +984,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"];
+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 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

@@ -45,6 +45,7 @@ export const APP_CAPABILITIES = [
     'camera-follow-lights',
     'shadow-filters',
     'environment-map-model',
+    'spawn',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
@@ -28,13 +28,13 @@
   "devDependencies": {
     "rimraf": "^6.1.3",
     "typescript": "~6.0.3",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24"
   },
   "dependencies": {
-    "zod": "^4.6.4"
+    "zod": "^4.6.5"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.build.json",