Persona

@laplace.live/persona-sdk 是 Persona 外掛 API 的官方 TypeScript/JavaScript 用戶端，同時提供通訊傳輸 Schema 的型別定義。本頁面為完整的型別與 API 參考；有關伺服端設定、金鑰產生以及可用 RPC 方法的詳細說明，請參閱 外掛 API。

該 SDK 相容 Node.js 22+、Bun、現代 Web 瀏覽器以及 OBS 瀏覽器來源等執行環境。其唯一的執行階段相依套件為 zod，用於定義並驗證傳輸 Schema。

npm install @laplace.live/persona-sdk

你能用它做什麼複製錨點連結

Persona Console 是基於該 SDK 建構的官方參考實作。它提供了一個全功能的 Web 主控台，可在單一瀏覽器分頁內集中管理場景、圖層、素材庫、表情、動作、參數對應、快速鍵、追蹤來源以及全域系統設定，其介面針對直播演播期間的行動裝置與觸控操作進行了專門最佳化。

該主控台完全基於外掛 API 建構，未引用任何桌面端專有程式碼，開發者可使用相同的 SDK 實作同等深度的控制能力。

開發用戶端時建議遵循以下設計原則：

• 基於功能能力判斷，而非格式或版本號：各實例控制項應在讀取 InstanceRuntime.capabilities 後依需求啟用或停用，避免盲目呼叫導致 unsupported-for-format 錯誤；
• 斷線重新連線視為狀態重設：WebSocket 連線中斷期間錯過的廣播事件不會重放，本機快取可能與伺服端最新狀態脫節，重新建立連線後應清除本機快取並重新拉取完整狀態快照；
• 妥善處理終止性連線關閉碼：狀態碼 4001（金鑰失效/撤銷）與 4002（伺服端強制中斷）屬於終止性關閉，應停止自動重新連線重試；其他異常關閉則建議執行指數退避重新連線；
• 事件訂閱由 SDK 託管：透過 persona.on(…) 註冊的事件接聽程式將在重新連線成功後自動重新訂閱，業務程式碼無需手動維護重新連線後的接聽生命週期。

LLM 提示詞複製錨點連結

可將以下 Prompt 提供給 LLM 或加入專案的 CLAUDE.md / AGENTS.md 規則檔案中，作為外掛開發的完整上下文指引：

You are helping me build a plugin for LAPLACE Persona, a desktop VTuber app
(https://laplace.live/persona). Persona exposes a local WebSocket server called the
Plugin API, and `@laplace.live/persona-sdk` is its typed client.

Before writing any code, fetch the reference documents listed at the end — they are
the single source of truth for method names, events, error codes and types. Do not
rely on memory and do not invent names.

## Setup

- Install `@laplace.live/persona-sdk`. Isomorphic: Node 22+, Bun, browsers and OBS
  browser sources. Its only runtime dependency is zod.
- The user enables the server in Persona under Settings → Plugin API and creates an
  API key there. Tokens look like `sk-lp-v1-…`. Default endpoint: `ws://127.0.0.1:25034`.
- Everything — values and types — is exported from the package root; there is no
  other entry point.

## Client

```ts
import { PersonaClient } from "@laplace.live/persona-sdk";

const persona = new PersonaClient({
  token: "sk-lp-v1-…", // required; everything else is optional
  clientInfo: { name: "My Plugin", version: "1.0.0" }, // display-only identity
});
await persona.connect();

const { scenes, activeSceneId } = await persona.call("scene.list");
await persona.call("scene.patch", {
  background: { mode: "color", color: "#00ff00", imageAssetId: null },
});
persona.on("motion.started", (m) => console.log("playing", m.group));

const mouth = persona.driveParameter("MouthOpen", 0.8); // parameter lease
mouth.set(0.3);
mouth.release();
```

`call(method, params?)` is fully typed — the method name determines the request and
response shapes.

Methods cover scenes, model instances, stage objects, expressions, motions, speech,
hotkeys, automations, model and asset registration, settings, tracking and pose
input, per-key storage and parameter injection. Events notify you of scene,
selection, expression, motion, speech, tracking and registry changes.

The exact method and event names, parameter shapes, error codes and limits live in
the reference below — look them up instead of guessing. Gate features on the
capabilities reported by `app.info` and `instance.list`, never on version strings.

## Reference

Fetch these before writing code. The documentation is served as raw Markdown —
append `.mdx` to any page URL (`.en.mdx` for English):

- https://laplace.live/persona/plugin-api.en.mdx — server setup, API keys, and every
  method, event, error code and limit
- https://laplace.live/persona/sdk.en.mdx — the SDK client: options, auth modes and
  every exported type

用戶端複製錨點連結

import { PersonaClient } from "@laplace.live/persona-sdk";

const persona = new PersonaClient({ token: "sk-lp-v1-…" });
await persona.connect();

const { scenes, activeSceneId } = await persona.call("scene.list");
await persona.call("scene.patch", {
  background: { mode: "color", color: "#00ff00", imageAssetId: null },
});
persona.on("motion.started", (m) => console.log("playing", m.group));

PersonaClient 支援透過設定選項建立實例，其中僅 token 為必填項目：

ClientInfo複製錨點連結

clientInfo 用於向 Persona 宣告用戶端的身分識別碼，該識別碼將顯示在用戶端設定介面的已連線的用戶端清單中。此欄位為選用的宣告性中繼資料，僅用於介面呈現，不參與驗證邏輯。SDK 在每次重新連線時均會自動重新回報該資訊。

const persona = new PersonaClient({
  token,
  clientInfo: { name: "My Overlay", version: "1.2.0", developer: "You" },
});

驗證設定複製錨點連結

在瀏覽器環境中，API Token 統一透過 ?token= URL 查詢參數傳遞（受限於瀏覽器 WebSocket API 的實作）。在 Node.js 或 Bun 等伺服端環境中，可透過自訂 createWebSocket 鉤子插入 Authorization: Bearer 請求標頭（配合 ws 等用戶端程式庫）：

import WebSocket from "ws";

const persona = new PersonaClient({
  token,
  auth: "header",
  createWebSocket: (url, headers) => new WebSocket(url, { headers }),
});

WebSocketLike 定義了 createWebSocket 必須回傳的 Socket 抽象介面。全域 WebSocket 實例與 ws 用戶端均在結構上完全滿足該型別條件約束，無需額外的型別斷言。

在 Node.js 22+ 中，全域 WebSocket 可以透過 WebSocketInit 擴充傳送交握請求標頭。SDK 提供的 createNodeClient 輔助函式以此建立用戶端：

• 設定 auth: 'header'
• 使用 Node 的全域 WebSocket
• 將連線逾時設為 5 秒
• 將 SDK 警告與終止性關閉（如 API Key 遭撤銷或被伺服端強制中斷連線）輸出到傳入的 log 函式

import { createNodeClient } from "@laplace.live/persona-sdk";

const persona = createNodeClient({
  token: "sk-lp-v1-…",
  log: console.warn,
});
await persona.connect();

參數租約驅動複製錨點連結

driveParameter 用於持續向模型參數寫入目標值，並回傳一個 InjectionHandle 控制代碼。SDK 在背景自動維護租約心跳，參數租約在最後一次寫入約 1 秒後自動過期並平滑恢復預設值，從而避免用戶端處理程序異常結束時導致參數卡死。

const mouth = persona.driveParameter("MouthOpen", 0.8);
mouth.set(0.3);
mouth.release();

同一模型參數在同一時段內僅允許由單一工作階段獨佔租用；其他工作階段嘗試重複租用將觸發 conflict 錯誤。

該方法亦支援傳入選用的 weight（權重）以及 onError 異常回呼函式。當背景心跳續約失敗時將透過回呼通知，無需在每次更新參數時呼叫 await。

連線關閉處理複製錨點連結

onClose 在伺服端或網路導致連線關閉時觸發。回呼參數包含原始 Socket 關閉碼、關閉原因，以及表示是否已停止重新連線的 terminal 旗標。

• 回呼在用戶端重設內部狀態並清理擱置請求之後才觸發，因此可以在回呼中安全地呼叫 close()。
• 用戶端主動呼叫 close() 不會觸發 onClose。
• 設定 onClose 後，終止性關閉改由它回報，不再經過 onWarning。

PersonaClientState 與用戶端錯誤複製錨點連結

type PersonaClientState = "closed" | "connecting" | "open" | "reconnecting";
type ClientErrorReason =
  | "connect-timeout"
  | "connection-closed"
  | "client-closed"
  | "not-connected"
  | "request-timeout";

當用戶端自身或底層傳輸層無法完成 connect() 或 call() 時，Promise 會以 PersonaClientError 拒絕（帶有 reason: ClientErrorReason，取值見 CLIENT_ERROR_REASONS）；伺服端回傳的錯誤影格則以 PersonaApiError（帶有 code: ApiErrorCode）拒絕 call()。詳見 外掛 API：錯誤代碼。

常數定義複製錨點連結

SDK 還匯出了以下取值清單與輔助函式：

• API_ERROR_CODES、CLIENT_ERROR_REASONS、EVENT_NAMES、INPUT_NAMES、TIME_INPUT_NAMES、RANDOM_PULSE_INPUT_NAMES、MODIFIER_TOKENS、APP_CAPABILITIES、FPS_LIMIT_PRESETS、EFFECTS_QUALITY_LEVELS：as const 陣列，便於在 UI 選擇器中列出全部合法取值
• isApiErrorCode、isEventName、isAppCapability、isTimeInputName、isRandomPulseInputName：對應的 TypeScript 型別防護
• injectTargetKey：產生標準化的注入目標識別碼
• personaWsUrl：根據 { host, port, secure }（PersonaAddress，其中 host 須為純主機名稱或 IP 位址）或使用者輸入的位址字串（支援純主機名稱、host:port、IPv4/IPv6 位址以及完整的 ws:// / wss:// URL）產生 WebSocket URL；API Token 由 PersonaClient 在連線時自動附加
• parseHost、parsePort、isValidPort：驗證純主機名稱/IP 位址（支援帶或不帶方括號的 IPv6，含協定、連接埠、路徑或區域 ID 時回傳 null）與連接埠號碼
• requestTimeoutMs(method, fallbackMs)：依方法名稱計算請求逾時時間（scene.activate 與 asset.import 自動採用各自的長逾時）

模型與素材複製錨點連結

模型與通用素材共用統一的中繼資料定義。kind 用於標識項目的資源型別，origin 用於標識其來源：bundled 代表應用程式內建資源或桌面端從 Persona 目錄按需下載的資源，user 代表使用者本機註冊的檔案，同時包含清單中宣告的創作者署名資訊。

type ModelFormat = "live2d" | "vrm";
type ContentOrigin = "bundled" | "user";
type AssetKind =
  | "image"
  | "video"
  | "audio"
  | "prop"
  | "ibl"
  | "lut"
  | "animation"
  | "cameraMotion"
  | "lyrics";
type InventoryKind = ModelFormat | AssetKind | "effect" | "addon";

effect 屬於特殊的虛擬資產型別，不對應實際磁碟檔案，素材庫透過它列舉系統支援的 內建特效；addon 則代表擴充應用程式本身的選用附加元件（如 攝影機追蹤附加元件），不會作為圖層進入場景。

model.list 回傳 ModelRef 陣列，asset.list 回傳 AssetRef 陣列。兩者都是 ContentRef，kind 分別收窄為 ModelFormat 與 AssetKind。

兩者也帶有布林欄位 exists：AssetRef 的檔案在磁碟上被移動或刪除後，該欄位為 false；ModelRef 在模型入口檔案遺失時同樣為 false。

CatalogItem複製錨點連結

CatalogItem 提供了脫離具體傳輸協定的內容中繼資料抽象模型，本機註冊表項目與遠端資源目錄均轉換為此統一結構。它在 ContentRef 基礎上移除了未安裝狀態下的 origin 欄位，並擴充了多語言簡介 description（LocalizedText）與目錄檢索屬性。download（CatalogDownload）描述未安裝項目的下載來源資訊；若該欄位為空，代表該資產已存在於本機環境。

目錄與多語言輔助項：

• CATALOG_FORMAT、MARKETPLACE_ITEMS_PATH、CATALOG_KINDS：目錄清單格式版本號、公開目錄 API 路徑（/api/items）與目錄支援的項目類型清單
• isCatalogId、healCatalog、healCatalogItem、healCatalogRows、healSha256：驗證並正規化遠端或本機目錄清單資料
• payloadEntryPath、payloadEntryKey、catalogMediaFile（參數為 CatalogMediaRole）：計算解壓後的目錄資源入口路徑，以及來源目錄下預渲染縮圖與預覽影片的檔案名稱（.thumbnail.avif 與 .preview.webm）
• pickLocalized(text, locale)、healLocalizedText：依目前介面語言從 LocalizedText 中選取相符的顯示文案並正規化多語言物件

空間排版與放置複製錨點連結

2D 螢幕空間以像素為單位，以舞台視窗中心為座標原點（+y 軸向下）；3D 世界空間以公尺為單位。傳輸協定中所有旋轉分量均嚴格採用弧度制表示（控制面板上為便於直觀理解以角度呈現）。

Place2D 與 Place3D 為物體道具對應的排版型別，欄位結構相同並額外包含 opacity 不透明度屬性。

場景項目複製錨點連結

場景設定中的 items 陣列依據渲染深度（Z-order）混合管理模型與物體圖層：

type SceneItem = SceneModelItem | SceneObjectItem;

ObjectContent複製錨點連結

物體圖層承載的實際內容結構依據 kind 欄位區分。除 capture（畫面擷取）外，其餘型別均可在桌面端介面中直接建立，詳見 圖層管理。

type ObjectContent =
  | { kind: "image"; assetId: string }
  | {
      kind: "video";
      assetId: string;
      loop: boolean;
      muted: boolean;
      volume: number;
    }
  | { kind: "prop"; assetId: string }
  | {
      kind: "web";
      url: string;
      width: number;
      height: number;
      fps: number;
      transparent: boolean;
      css: string;
      layer: WebLayer;
      shutdownWhenHidden: boolean;
    }
  | { kind: "capture"; source: CaptureKind; sourceId: string; label: string };

type ObjectSpace = "2d" | "3d";
type WebLayer = "behind" | "front";
type CaptureKind = "display" | "window";

釘附系統複製錨點連結

AttachAnchor複製錨點連結

type AttachAnchor =
  | { kind: "root" }
  | { kind: "bone"; bone: string }
  | {
      kind: "artMesh";
      id: string;
      verts: [number, number, number];
      weights: [number, number, number];
    };

object.anchors 回傳父級物件可供繫結的掛載錨點清單（以 AnchorOption 結構呈現，包含錨點 ID 及對應的可讀名稱）。VRM 模型提供根節點及人形骨骼節點；Live2D 模型提供根節點及各 ArtMesh 部件，並帶有 order 繪製層級序號。

AttachDepth複製錨點連結

type AttachDepth =
  { kind: "front" } | { kind: "behind" } | { kind: "artMesh"; id: string };

depth 用於控制 Live2D 道具 在父模型內部的渲染層深，可置於模型後方、前方，或指定 ArtMesh 的正上方。該屬性僅適用於附著到 Live2D 父模型的 Live2D 實例，透過 instance.attach 設定。

釘附相關的輔助函式：

• depthStops(meshes)：由後到前列出可選的深度檔位（模型後方、按繪製順序排列的各 ArtMesh 上方、模型前方）
• depthStopIndex(meshes, depth)：計算某個深度位於哪個檔位；關聯的 ArtMesh 已不存在時按最頂層處理
• pinRiders(items, instanceId)：遞迴找出直接或間接附著在 instanceId 上的所有實例，用於防止循環附著
• pinnableParents(models, items, instanceId)：產生父級候選清單，並用 ridesThis 標記須停用的非法項
• defaultAttach(parentInstanceId, screenSpace?)：產生預設附著設定（繫結根節點、位於模型最前方、不切分部件、無動態物理參數）；設定 screenSpace（Live2D 模型或 2D 物件）時，還會以預設回應跟隨父模型頭部轉動

場景設定複製錨點連結

背景設定複製錨點連結

type BackgroundMode = "color" | "image";

相機設定複製錨點連結

cameraDistanceLimits(environment, radius) 計算軌道相機在滑鼠導覽時允許的距離範圍。預設最小、最大距離分別為 DISTANCE_MIN（0.35 公尺）與 DISTANCE_MAX（20 公尺）；3D 環境的外框尺寸明顯大於或小於標準空間（約 10 公尺跨度）時，限制會按比例縮放。radius 是 3D 場景的外接球半徑，即 scene.inspect 回傳的 environment.radius；場景載入完成前為 null，此時回傳預設限制。

燈光系統複製錨點連結

type SceneLightType = "directional" | "point" | "ambient" | "area" | "spot";
type ShadowQuality = "off" | "low" | "medium" | "high" | "ultra";
type ShadowFilter = "pcf" | "pcss";

SCENE_LIGHT_TYPES、SHADOW_QUALITY_LEVELS 與 SHADOW_FILTERS 以 as const 陣列提供光源型別、陰影檔位與過濾方式，順序與面板中一致。

SceneLight 的以下三個欄位讓燈光跟隨相機：

• followCamera：將光源的位置與旋轉繫結到相機座標系
• followCameraOptions：選擇哪些運動自由度跟隨相機；DEFAULT_LIGHT_FOLLOW_CAMERA_OPTIONS 啟用全部
• followCameraReference：不跟隨的維度所使用的固定參考變換

若要在不改變燈光實際照射角度的前提下切換跟隨狀態，請呼叫 scene.setLightFollowCamera，不要直接修改這些欄位，詳見 燈光系統。

iblAssetId 與 modelAssetId 分別指定環境貼圖（IBL）與 3D 場景模型；具備 environment-map-model 能力的應用程式版本可以同時使用兩者。

• 更新環境時建議使用 environmentWithAsset()：它設定新的資源、保留另一項現有資源，並清理與舊場景繫結的燈光覆蓋項。
• 選取環境貼圖會自動關閉 bakeFromModel；只有此前兩項均為空時，載入新 3D 場景才會預設開啟烘焙。
• environmentClearPatch(environment, slot) 產生清除 'model' 或 'map' 的修補程式；slot 為 null 時兩者都清除。
• applyEnvironmentLighting() 與 applyEnvironmentLook() 對應面板中的快捷操作，分別用於啟用環境燈光與整體套用 EnvironmentLook 視覺風格。

體積光照依光源單獨開啟，透過 SceneLight.volumetric 設定。相關輔助項：

• SCENE_VOLUMETRIC_LIGHTING_SPECS：體積霧各滑桿的取值範圍
• defaultSceneVolumetricLighting()：預設的體積霧設定
• healSceneVolumetricLighting()：將越界參數限制在合法範圍內
• sceneLightCanHaze(type)：判斷某種光源型別能否產生體積光
• sceneLightHazes(light)：判斷某個光源目前是否正在產生體積光

特效系統複製錨點連結

SceneEffects 採用扁平化的資料結構設計：每個具備開關及參數的後製特效均直接掛載於頂層，便於開發工具進行通用的走訪與反射處理。具體特效在使用者介面中的呈現分組屬於檢視層設計，不影響底層協定結構。

特效在 圖層清單 中的呈現順序由 environment.effectLayers 獨立維護（為 ToggleEffectKey 陣列）。該清單與特效自身的 enabled 狀態相互獨立：enabled 控制特效管線的運算開關，effectLayers 決定其在 UI 面板中是否作為圖層列出。當透過 Patch 啟用某個特效時，系統會自動補齊對應的圖層項目，因此外掛開發時通常只需修改 enabled 屬性。

type SceneToneMapping = "none" | "neutral" | "aces" | "agx";

漸層特效提供 24 種混合模式 EffectBlendMode，EFFECT_BLEND_MODES 依面板中的順序列出它們。

rain（降雨）與 snow（降雪）在資料結構上與其他特效保持一致，但在管線行為上具有本質區別：它們在場景中以實際的 3D 粒子幾何體形式存在並參與渲染，而非傳統的畫面空間後製通道，詳見 雨景特效 與 雪景特效。

虛擬形象與物體圖層也有各自的特效管線。SceneModelItem 與 SceneObjectItem 上的 effects 與 effectLayers 先於全螢幕場景特效執行，透過 instance.setEffects 修改。

• 圖層特效支援 LayerEffectKey 定義的子集：color、levels、colorWheels、colorShift、selectColors、gradient、blur、bloom、diffusion、sketch、rim、outline 與 dropShadow。
• 輝光特效的顏色過濾僅在圖層層級生效，詳見 圖層特效。

轉場過渡複製錨點連結

transition 用於設定場景啟動時的視覺過渡效果，詳見 場景轉場（未宣告 scene-transitions 能力的版本不提供該特性）。SCENE_TRANSITION_TYPES 列出所有合法轉場型別，defaultSceneTransition() 回傳預設的直接切換，healSceneTransition() 用於將參數校正至合法範圍。

environment.itemTransition 控制場景內模型、道具及動態生成物體的出現與消失動效，詳見 顯示與隱藏。ITEM_TRANSITION_STYLES 列出全部支援的過渡風格，defaultItemTransition() 預設採用 300 ms 的 glitch 故障效果，ITEM_TRANSITION_MAX_MS 限制最長過渡時間為 5000 ms。

場景預設複製錨點連結

presets 依顯示順序列出場景已儲存的 場景預設；未宣告 scene-presets 能力的版本不提供該欄位。可透過 preset.create、preset.update、preset.rename、preset.setTransition、preset.delete 與 preset.apply 管理目前場景的預設，詳見 外掛 API：場景預設。

• SCENE_PRESET_TRANSITIONS：全部轉場方式
• scenePresetIsCurrent()：判斷舞台目前配置是否與某個預設吻合，桌面端與 Web 主控台據此醒目提示對應預設
• capturePresetItems()：擷取圖層配置
• presetStep()：計算套用預設時各圖層的變化

執行階段狀態複製錨點連結

instance.list 動態回傳目前舞台上每個活動實例支援的實際能力集，用戶端可據此在 UI 層面精確停用不支援的操作控制項，而無需依賴被動攔截 RPC 例外狀況：

type InstanceCapability =
  | "motions"
  | "expressions"
  | "placement-2d"
  | "placement-3d"
  | "mtoon"
  | "idle-clips"
  | "idle-motions"
  | "pose"
  | "breath"
  | "expression-weights"
  | "live2d-params"
  | "speech"
  | "post-fx";