Persona

Persona 執行一個本機 WebSocket 伺服器，供外部應用程式連線與驅動：切換場景、新增並排列圖層、開關表情、播放動作、播放帶口型的語音、讀取追蹤狀態，以及直接寫入模型參數。

API 服務預設處於關閉狀態。可在 設定 → 外掛 API 中啟用服務、建立 API 金鑰，並將產生的權杖填入外掛或外部整合中。

服務設定複製錨點連結

啟用區域網路存取後，Persona 會顯示目前主機的區域網路 IP 與連接埠，便於遠端裝置或 Web 主控台設定連線。

若指定連接埠已被其他處理程序佔用，設定面板將直接顯示錯誤狀態提示。

API 金鑰複製錨點連結

所有外部連線均須經過身分驗證，未經認證的連線將被直接拒絕。點擊 建立金鑰 可指定金鑰名稱，系統將產生權杖並完整顯示一次；後續亦可隨時點擊對應列右側的複製按鈕取得完整權杖。

各金鑰列會即時顯示 已連線、從未使用 或最近使用的相對時間。用戶端在連線交握中宣告身分後，該列將記錄其名稱與版本資訊，即便離線後仍可識別呼叫來源。

權杖安全儲存在作業系統的憑證儲存區（如 macOS Keychain、Windows Credential Manager 等）。在不支援安全憑證儲存的環境中，金鑰建立操作將明確傳回失敗原因，杜絕明文儲存風險。

外掛程式目錄與資源註冊複製錨點連結

外掛程式可透過 API 請求 Persona 註冊並載入模型或素材資源。model.register 與 asset.register 僅接受位於使用者在設定中（透過系統對話框）明確設定的 外掛程式目錄 下的絕對路徑，路徑驗證會自動解析兩端的符號連結，存取其餘任何路徑均會被系統以 forbidden-path 錯誤拒絕。

具備 asset-import 能力時，自同一台電腦（本機回送位址）連線的用戶端還可呼叫 registry.pluginFolders（傳回 { folders }）讀取已設定的外掛程式目錄，或呼叫 asset.import { path, want? } 將本機檔案匯入素材庫：

• 位於外掛程式目錄內或已在素材庫中的檔案會直接完成註冊，不彈出提示；其餘路徑會在桌面控制面板中彈出確認提示（加入檔案，顯示用戶端名稱與 API 金鑰名稱，開啟串流模式時隱藏所在資料夾名稱）。使用者拒絕或在 45 秒（ASSET_IMPORT_PROMPT_MS）內未回應時傳回 forbidden-path；已有匯入提示等待確認期間再次發起匯入將傳回 invalid-state。非本機回送位址的遠端用戶端呼叫這兩個方法均直接傳回 forbidden-path。
• asset.register 與 asset.import 均會等待舞台重新整理資源清單後再傳回，隨後即可直接呼叫 object.add 載入該素材。

註冊的資源 ID 採用內容定址（sha256(path) 前綴），重新啟動後保持不變，真實路徑也無需透過網路傳輸。ModelRef 與 AssetRef 的 origin: 'bundled' 同時涵蓋應用程式隨附的內建內容與桌面端從 Persona 目錄按需下載的內容；尚未下載的目錄項目不會出現在清單中，API 也不提供目錄下載方法。

asset.register 的 want 欄位宣告素材種類，不相符時傳回 invalid-params：

• image、video、prop、ibl、lut
• animation 與 cameraMotion：共用 .vmd 副檔名，由檔案標頭特徵自動區分
• audio（WAV、MP3、OGG、FLAC、M4A 或 AAC 檔案）與 lyrics（.lrc 檔案）：屬於素材/清單資源類型，而非 ObjectContent，註冊後不會在舞台上建立獨立的場景圖層

模型參照以 entryFile 攜帶進入點檔案的基準名稱；.vtube.json 設定檔的基準名稱 vtubeFile 僅在 model.list 中傳回（未設定時為 null，且不是完整目錄路徑）。SDK 的 modelMatchesFile 即基於這些名稱配對模型載入快速鍵，因此配對快速鍵時應比對 model.list 的傳回結果，而非場景項目參照。

已連線的用戶端複製錨點連結

服務執行期間，控制面板將列出所有已建立連線的用戶端工作階段，顯示其宣告的用戶端名稱、版本、開發者識別碼、使用的 API 金鑰以及連線來源 IP。Web 瀏覽器用戶端將一併顯示其頁面 Origin。

未宣告身分資訊的用戶端將歸類為 未識別的用戶端，其 API 呼叫權限不受影響。點擊工作階段列右側的中斷按鈕可主動終止該連線，並通知用戶端停止重新連線。

每當建立新連線時，系統將發送一則無聲系統通知，提示用戶端名稱、金鑰與連線來源 IP。若作業系統權限阻止發送通知（如未簽章的開發版本或系統通知權限關閉），控制面板開啟時會在其中改為顯示彈出提示。通知不會在舞台渲染視窗中重疊顯示，避免污染直播擷取畫面。

Web 主控台複製錨點連結

這些控制項的說明請見 Web 主控台。

Stream Deck複製錨點連結

Persona 官方提供的 Stream Deck 外掛 是基於該 API 開發的另一款第一方整合，將模型與場景切換、快速鍵觸發、表情與動作控制以及虛擬形象位移縮放直接對應至實體按鍵。

MCP 伺服器複製錨點連結

@laplace.live/persona-mcp 為基於 Model Context Protocol 建構的官方服務，將該套 API 封裝為面向 AI 助手（如 Claude、Cursor、Codex 等）的任務專用工具組與通用的 call_api 介面，並提供 stage.capture 供代理即時觀測畫面狀態。

SDK複製錨點連結

@laplace.live/persona-sdk 是官方提供的型別安全用戶端程式庫，同時支援 Node.js、Bun、Web 瀏覽器以及 OBS 瀏覽器來源等執行環境。

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

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

await persona.call("expression.toggle", { name: "Smile" });
persona.on("motion.started", (m) => console.log("playing", m.group));

SDK 內所有方法呼叫均由同一份強型別 Schema 定義，呼叫的參數簽章與回應結構均由方法名稱自動推導。SDK 參考文件 詳細介紹了安裝、用戶端設定、身分驗證、參數租約以及所有匯出的型別定義。

事件複製錨點連結

用戶端只會收到已訂閱的事件。若發生斷線重新連線，SDK 將自動復原先前的所有訂閱。

方法一覽複製錨點連結

所有以模型為作用域的 API 方法均接受選用的 instanceId 參數，省略時預設作用於目前場景的 主模型。

scene.create 會追加一個空白場景並立即啟用，行為與桌面端新增場景一致。回應中的 activeSceneId 即為新場景 ID；請直接使用該值，不要比對前後兩次的場景清單，以免與其他工作階段並行建立場景時產生時序衝突。

scene.patch 用於修改目前場景的背景、相機、燈光、環境以及 場景轉場；場景內的項目則透過 instance.* 與 object.* 修改。

燈光的 enabled 設為 false 時，燈光與其投射的陰影一同關閉，其他設定保持不變。該欄位預設為 true；不支援單獨關閉燈光的舊版本不包含該欄位。

相機複製錨點連結

vrmCamera 支援整組覆寫設定：orbit、fov（1 – 179°）、roll（繞視線軸旋轉的弧度）、projection（perspective 或 orthographic）以及 clipAssetId。

• 環繞角度接受任意弧度值，distance 支援負值（滑鼠互動導覽保留相對受限的範圍）。
• 正交投影下，視圖寬度為 abs(distance)，fov 保留但不參與計算；distance 為負時兩個軸向均會翻轉。
• 呼叫 stage.resetCamera 會一併重設相機滾轉與投影模式。
• 舊版本不包含 roll 與 projection，依 0 與 perspective 處理；呈現對應控制項前，應先檢查傳回結果中是否存在這兩個欄位。

vrmCamera.follow 讓相機跟隨某個圖層取景：{ instanceId, anchor, binding, damping }。預設為 null，需要 camera-follow 能力。

• orbit 決定目標位於原點時的構圖。跟隨期間，相機隨目標的位移、走動、動作與動態捕捉一起移動，不會改寫 orbit。
• 切換到其他圖層或錨點時平滑過渡；移除被跟隨的圖層或將其移入 2D 時，follow 重設為 null。
• 正在播放的相機運鏡會覆寫跟隨；stage.resetCamera 重新對準目標並保留 follow。

vrmCamera.aim 讓相機原地轉動鏡頭，使目標保持在畫面的指定區域：{ instanceId, anchor, screenX, screenY, deadZone, softZone, bias, damping, lookahead }。預設為 null，需要 camera-aim 能力。

• 相機機位座標與視距保持不變，僅視線朝向轉動：以世界 Y 軸偏航、以自身橫軸俯仰，並保持鏡頭滾轉。
• 拖曳舞台控制手柄或模型載入時，鏡頭保持靜止。
• 清除規則與 follow 一致；相機運鏡軌跡動畫會覆寫注視效果。

vrmCamera.focus 在 景深 開啟時，把焦平面鎖定在指定圖層或錨點上，而非注視點距離。預設為 null，需要 camera-focus 能力；damping 預設為 0.2 秒。

• 錨點位於相機視錐背面時，自動回退至常規注視距離。
• 相機運鏡軌跡回放期間依然生效；景深關閉時不產生可見效果。

vrmCamera.handheld 以連續平滑噪訊為相機加入手持拍攝般的微幅晃動。預設為 { enabled: false, intensity: 0.5, speed: 1 }，需要 camera-handheld 能力；intensity 範圍 0 – 1，speed 範圍 0 – 2。

• 開關或修改強度時，在約 1 秒內平滑過渡。
• 不會儲存至場景檔案；播放相機運鏡軌跡時被覆寫，拖曳舞台控制手柄時自動暫停。

物件與文字複製錨點連結

object.add 支援傳入 place2d 或 place3d 空間擺放參數，在建立物件的同一異動中直接放到指定位置，避免先在預設原點處渲染一個影格；取值規則同 object.setPlacement。

object.addMany { objects } 在單次場景編輯中批次新增最多 100 個項目，僅觸發一次儲存，復原也只計一步，並按請求順序傳回 instanceIds。任意一個素材無法解析時，整批操作將整體復原。

具備 object-text 能力時，ObjectContent 可以是文字圖層：{ kind: 'text', text, font, size, color, shear, letterSpacing, wordSpacing, lineHeight, align, verticalAlign, boxWidth, boxHeight, overflow, stroke, shadow, plate, sung, extrude, bevel, bevelResolution, roughness, metalness, emission, faceCamera }。單一圖層共用同一樣式。

• 在 3D 空間中，文字呈現為類似 Blender 的幾何擠出立體字；兩個空間各自保留對方的特有屬性，不予丟棄。
• 所有欄位均即時生效。對文字圖層呼叫 object.setContent 會像拖曳一樣直接編輯，每次輸入停頓計為一步復原。
• fonts.list 傳回桌面主機已安裝的字型家族與字形，供遠端控制面板選擇。
• 未宣告該能力的舊版主機無法正確解析文字圖層，會將其丟棄。

object.setText { instanceId, text, transient? } 僅更新文字圖層的文字內容，即時套用，輸入停頓合併為單步復原。

• 傳入 transient: true 時僅顯示暫存文字，不寫入 scenes.json，也不記錄復原歷史；暫存文字保留至傳入 text: null、儲存真實文字，或該圖層移出舞台（被移除或啟用另一場景）為止。scene.inspect 會將其作為該物件的 liveText 傳回。
• 對非文字物件呼叫將傳回 unsupported-for-format 錯誤。
• 超出 TEXT_LENGTH_MAX 的文字將被截斷。

具備 object-video-sound 能力時，可透過 object.setContent 像拖曳一樣直接修改影片圖層的 loop、muted 與 volume 屬性，每次停頓計為一步復原，避免重新載入場景；影片聲音透過桌面主機設定的音訊輸出裝置播放。未宣告該能力的舊版主機每次修改都會重新載入場景並記錄獨立的復原歷史，聲音則在系統預設裝置上播放。

具備 object-chroma-key 能力時，圖片、影片與網頁圖層可設定 chromaKey 色度鍵參數（{ enabled, color, similarity, smoothness, spill }），用於去除純色背景。呼叫 object.setContent 會直接更新圖層，拖曳調整停止時合併記錄為單步復原。未宣告該能力的舊版主機會在正規化時丟棄該欄位。

instance.attach { instanceId, attach } 可將 Live2D 實例作為 物品 附加至另一個 Live2D 模型，參數結構與 object.attach 一致；傳入 null 可在目前位置解除附加。

• object.anchors 傳回的各項目包含 order 欄位，即查詢時該 ArtMesh 的繪製順序，深度控制面板依此排列選項。
• 附加關係形成循環相依時傳回 invalid-params 錯誤；對 VRM 實例呼叫傳回 unsupported-for-format。
• 在具備 object-pin-depth 能力的主機上，釘選到 Live2D 模型的 2D 圖片、影片或網頁同樣按 attach.depth 深度交錯渲染在父模型圖層內部（整體繪製，不支援 split 切割）；3D 物件目前僅 front 模式生效。
• object-pin-depth 還讓 2D 網頁作為標準場景圖層參與圖層排序與後製特效，並移除舊版專用的 layer 屬性。未宣告該能力的舊版主機會忽略物件的深度設定，依場景順序疊放釘選的媒體，並透過 layer 將 2D 網頁整體置於舞台前後。

舞台複製錨點連結

stage.resetTransform { instanceId? } 重設指定圖層的空間轉換擺放；未傳入 instanceId 時作用於應用程式內目前選取的圖層，未選取時作用於主模型。已載入的模型會在約 ⅓ 秒內平滑回到原位。

stage.capture 傳回舞台檢視區目前畫面的帶透明度通道 PNG 截圖：{ dataUrl, width, height }。需要 stage-capture 應用程式能力；最長邊縮放至不超過 maxEdge（64 – 2048，預設 1024），且不會放大。

• 該方法主要供無介面用戶端（如透過 MCP 伺服器 整合的 AI 助手）確認操作效果。
• 截圖會讓渲染管線暫停一個影格，建議按需呼叫，避免高頻輪詢。
• renderer-unavailable 錯誤表示舞台視窗未就緒或沒有可供複製的影格緩衝區；舞台崩潰重新載入後，首影格完成渲染前均會傳回該錯誤，用戶端應重試。

能力宣告複製錨點連結

應用程式層級與實例層級的能力表（Capabilities）宣告目前執行版本支援哪些特性。請始終依據能力表進行功能相容性處理，不要透過剖析版本號字串來推斷。

應用程式層級能力由連線交握回應 hello 與 app.info 傳回：

各能力標識以其擴充的模組作為命名主體（如 light-spot、object-text）。伺服器端會同時列出重新命名前的歷史標識，以相容舊版本用戶端；SDK 用戶端會自動將舊名稱對應為目前名稱。

各模型實例的能力表透過 instance.list 傳回的 capabilities 宣告；呼叫目前實例格式不支援的方法將傳回 unsupported-for-format 錯誤。instance.list 與 instance.get 還會傳回 loadError?: string | null，說明最近一次載入失敗的原因（已載入或正在載入時為 null，舊版主機省略該欄位）。

控制器複製錨點連結

controllers 對應 controller.*（查詢已連線裝置與預設設定檔、重新命名、設定死區、移除設定檔及發起通道對應），並允許透過 settings.patch 設定 controller.enabled 全域開關。這裡的裝置指連接至桌面主機實體介面的硬體。

instance.setControllerMovement 用於更新實例的 搖桿移動 設定：enabled、slot（預設槽位編號）、moveSpeed、turnSpeed、smoothing；對 VRM 模型還包含 walkEnabled、walkClip、walkSpeed 與 faceMovement。walkClip 的參照格式與 instance.setIdle 完全一致。超出範圍的數值將被修正至邊界值；對非模型物件呼叫將傳回 unsupported-for-format。

參數繫結複製錨點連結

model-editing 對應 instance.setBreath 與 binding.*，後者用於查詢、預覽、寫入與釋放模型參數對應。

• binding.override 用於短時間覆寫輸入。
• binding.inputs 傳回 { inputs, outputs }：inputs 為即時追蹤輸入資料，outputs 包含各被對應參數在完成動作、表情與物理模擬後的目前讀取值，模型未宣告的輸出項目不予傳回。
• Time24h 與 Time12h 為內建的時間繫結輸入通道，取值範圍為 0..1。它們每個渲染影格取樣一次桌面主機的本機時鐘，獨立於臉部動態捕捉，同時驅動 Live2D 與 VRM 繫結（詳見 時間參數繫結）。SDK 透過 TIME_INPUT_NAMES、TIME_INPUT_RANGES 與 isTimeInputName 匯出相關定義。

binding-calibration 新增逐輸入校正表 calibration：

• binding.get 會一併傳回 calibration：未校正時為 {}，未宣告該能力的舊版主機不包含該欄位。
• binding.preview 與 binding.set 支援單獨或同時傳入 connections 與 calibration，未傳入的一側在即時預覽與磁碟寫入時均保持原狀。
• 僅儲存校正不會向 <model>.persona.json 寫入 bindings，因此 .vtube.json 的既有繫結仍繼續生效。

binding-random-pulses 新增內建隨機脈衝輸入 RandomPulse1 – RandomPulse8（取值範圍 0..1，獨立於臉部追蹤）以及依模型儲存的觸發設定表 randomPulses：

• 僅由隨機脈衝驅動的對應會疊加在驅動同一參數的其他對應之上（觸發時向 outRange[1] 過渡，靜止時不覆蓋，除非其靜止輸出與參數預設值不同），因此可與一般對應共用同一輸出參數（詳見 參數對應）。
• binding.get 一併傳回 randomPulses：未自訂任何脈衝時為 {}，未宣告該能力的舊版主機不包含該欄位。每項設定為 { intervalSeconds: [min, max], durationSeconds: [min, max], fadeInSeconds, fadeOutSeconds }（單位為秒，間隔與持續時長範圍 0.1 – 3600，淡入與淡出範圍 0 – 3600）；未單獨設定的脈衝採用 DEFAULT_RANDOM_PULSE_SCHEDULE（間隔 0.5 – 4.5 秒、持續 0.58 秒、淡入淡出各 0.29 秒，與 VTube Studio 自動眨眼一致）。
• binding.preview 與 binding.set 支援任意組合傳入 connections、calibration 與 randomPulses，省略的部分在即時預覽與磁碟寫入時均保持原狀；僅儲存 randomPulses 同樣不會將 .vtube.json 的 bindings 複製到 <model>.persona.json。

模型整體移動複製錨點連結

具備 model-movement 能力時，可透過 model.getMovement 與 model.setMovement 讀取與設定 Live2D 模型的 模型整體移動 設定，相容 VTube Studio。

• modelId 省略時預設作用於目前主模型；模型不存在傳回 not-found，對 VRM 模型呼叫傳回 unsupported-for-format。
• 該設定作用於模型定義而非單一實例：優先儲存在模型的 .vtube.json，不存在時寫入 .persona.json，與 VTube Studio 共用。
• 整體移動直接作用於模型擺放位置而不寫入參數，與模型自有的 FacePosition* 對應疊加生效。
• 預設值沿用 VTube Studio 標準（啟用，6/8/11）；每次設定變更均會觸發 model.movement { modelId, movement } 事件。

model-movement-pivot 允許在 movement 中攜帶前後縮放中心 pivot：{ kind: 'root' } 為預設值，指向模型中心；也可傳入 ArtMesh 錨點 { kind: 'artMesh', id, verts, weights }。

• 即使模型存在 .vtube.json 檔案，縮放中心仍儲存在 .persona.json 中。
• 縮放中心基於模型的靜止姿態計算，避免頭部轉動帶動模型偏移。

表情群組複製錨點連結

具備 expression-groups 能力時，可透過 expression.getGroups 與 expression.setGroups 讀寫模型的 表情群組，規則與 VTube Studio 的 Expression Groups 一致：在啟用的群組內，一個成員顯示時，其餘已顯示的成員自動隱藏，使同群組的表情一次只顯示一個。

• expression 為成員的表情鍵：Live2D 為 .exp3.json 檔名，VRM 為表情名稱，比對時不區分大小寫。
• 表情被開啟，或 inverted（反轉）成員被關閉，即視為「顯示」（反轉成員關閉時算作顯示，適合預設戴帽模型上的「脫帽」表情）。成員顯示時，其所在各啟用群組內其他已顯示的成員隨之隱藏：一般成員關閉，反轉成員開啟，各自依自身的 fadeSeconds 過渡。隱藏一個成員不會顯示另一個，因此群組內可以一個都不顯示；同一表情屬於多個群組且結果衝突時，以後面的群組為準。
• 具備 expression-groups-hide-first 能力時，群組可設定 hideFirst: true（先隱藏再顯示）：當某成員變為顯示時，會等待該群組隱藏的所有其他成員完全淡出後（包含淡入隱藏的反轉成員）再開始淡入；省略或設為 false 時採用預設的交叉淡化（與 VTube Studio 一致）。由群組觸發的隱藏、清除全部表情、還原表情、群組整理以及將表情權重設為 0 均不會等待；未宣告該能力的舊版主機會捨棄 hideFirst。
• 成員的 fadeSeconds 取代觸發切換一方的淡入淡出時長，包括快速鍵的 fadeSeconds；停用的群組連同其淡入淡出時長一併被忽略。
• 表情群組對所有切換途徑生效：expression.toggle、快速鍵、自動化、清除全部表情（之後每個群組重新整理，保留第一個顯示的成員）以及還原記住的表情；實際切換結果透過 expression.changed 推送。
• expression.setGroups 切換群組的啟用狀態，或增刪、反轉成員時，會立即整理舞台上該模型目前顯示的表情；僅重新命名、調整淡入淡出時長或修改 hideFirst 不觸發整理，與 VTS 編輯器一致。
• 若 .persona.json 尚未儲存表情群組，Persona 會以唯讀方式匯入 .vtube.json 的 ExpressionGroups（edited: false）；一旦透過 expression.setGroups 或面板編輯了表情群組，完整清單即寫入 .persona.json 並從此優先於 .vtube.json（同時存在 .vtube.json 時 edited: true），不會改寫 .vtube.json。在表情編輯器中重新命名或刪除 .exp3.json 時，則會原地更新 .vtube.json（不觸發 .persona.json 接管）及已存在的 .persona.json 中的對應項目。
• 每次變更（包括表情檔案重新命名或刪除引起的變更）均觸發 expression.groups { modelId, groups, edited } 事件（舊版主機省略 edited）。

版本歷史複製錨點連結

具備 model-history 能力時，可讀取與管理模型已儲存的版本，對應桌面端模型詳細資訊中的 版本 區塊（詳見 版本歷史）。所有方法均接受 modelId，省略時作用於主模型；對內建模型呼叫傳回 invalid-state。除非明確要求，系統不會自動儲存版本。

• ModelVersion 為 { id, parentId, time, kind, message, name, notes, current }：kind 取自 MODEL_VERSION_KINDS（first、saved、backup），其他 Git 工具建立的提交為 null，此時 message 為其提交訊息首行；current 標記磁碟上目前檔案基於的版本。
• 切換或還原將覆寫存在未儲存變更的檔案時，若未傳入 unsavedChanges（MODEL_VERSION_UNSAVED_ACTIONS），傳回 invalid-state：'save' 先將全部未儲存變更儲存為 backup 版本並在 backup 中傳回；'discard' 捨棄將被覆寫的變更。
• 版本歷史關閉時，儲存、切換與還原傳回 invalid-state；列出、比較與命名仍可讀取先前保留的歷史。
• 模型檔案遺失時，開啟版本歷史、儲存、切換與還原傳回 not-found；為版本歷史無法讀取的資料夾（UNC 共用路徑，或 macOS 與 Linux 上名稱含反斜線的資料夾）開啟時傳回 invalid-state。
• 遇到 Persona 無法寫入的檔案，或其他 Git 工具留下的未完成狀態（已暫存的檔案、合併進行中、無分支）時，傳回 invalid-state 且不做任何變更。
• 版本名稱最長 80 字元（MODEL_VERSION_NAME_MAX_LENGTH），備註最長 2000 字元（MODEL_VERSION_NOTES_MAX_LENGTH）。
• 每次變更均觸發 model.versions { modelId } 事件；其他應用程式對檔案的修改不會觸發。舊版主機不提供上述方法。

動作與待機複製錨點連結

motion.list 用於查詢模型的動作群組清單。針對 Live2D 模型，系統會自動掃描模型目錄下未在 .model3.json 中明確宣告的 .motion3.json 檔案，並以檔案名稱自動產生對應動作群組。在桌面端透過 動作 分區 錄製儲存的動作 無需重新載入模型即可直接出現在清單中。

motion.stop 結束目前播放中的單次動作，並讓模型平滑回到待機狀態而非瞬間跳變（motion.ended 立即觸發，不等待過渡結束），需要應用程式能力 motion-stop。若目前僅有待機動畫在播放，該呼叫不執行任何操作並傳回 { stopped: false }。

motion.playing 傳回的 oneShot 欄位（motion.started 事件中同樣包含）表示目前動作是否為疊加在待機層之上的單次動作，即由 stop 負責停止的類型；舊版本不傳回該欄位。

instance.setIdle 用於更新指定實例的待機設定：

呼叫 instance.get 會同步傳回上述待機設定。

燈光複製錨點連結

具備 light-area 能力時，SceneLight 支援 area 類型：一塊位於 x/y/z 處的矩形面光源。

• 面光源可照亮 PBR 材質與 MToon 虛擬形象（MToon 在卡通著色管線中採用 4 個光照採樣點近似模擬矩形光照），但不影響 Live2D 圖層，也不投射陰影。
• 其 range 與陰影設定會在資料層保留，便於之後切換燈光類型。

具備 light-spot 能力時，SceneLight 支援 spot 類型：一盞位於 x/y/z 空間座標處的聚光燈。

• 光照強度範圍 0 – 20，與點光源一致。
• 聚光燈可照亮 PBR 與 MToon 材質，支援設定陰影品質等級與柔化半徑，並可參與體積光照渲染。面光源與聚光燈的新增與類型切換僅在具備對應能力的版本中可用。

shadowFilter 可為每盞平行光、點光源或聚光燈單獨選擇 pcf（預設）或 pcss，兩種演算法可在同一場景中混用。是否可用須依據 light-shadow-filter 能力判斷，即便在不支援的版本上，本機新增的燈光物件也可能攜帶 shadowFilter 欄位；載入舊版場景時預設使用 PCF。

followCamera 讓燈光跟隨相機移動，需要 light-camera-follow 能力，環境光會忽略此設定。該屬性預設關閉（false）；啟用時，燈光的空間座標與朝向相對於相機即時計算，隨相機的互動移動及鏡頭軌跡動畫同步平移旋轉。

followCameraOptions 用於選取跟隨哪些變換分量，各項預設均為 true：

• 單純修改 fov 視角不會讓燈光產生位移。
• 未啟用的分量會凍結在 followCameraReference 中的定格值（包含 targetX、targetY、targetZ、distance 以及世界空間旋轉四元數）；缺少參考值時，依原點、單位旋轉與零距離處理。

scene.setLightFollowCamera { lightId, followCamera, options? } 可切換目前場景中指定燈光的跟隨狀態或合併更新 options，同時保持燈光的世界空間位置與朝向不變。它與 followCamera 一樣，須依據 light-camera-follow 能力判斷是否可用。

• 桌面端會根據目前檢視區中的相機變換（包含正在播放的相機軌跡）反算燈光座標，並傳回換算後的 { light }（燈光已被刪除時傳回 light: null）。
• scene.patch 與場景載入則直接依寫入的原始數值生效，不做換算。

SceneLight.volumetric 用於為單個點光源、聚光燈或面光源啟用體積光（受光照亮的霧氣效果），預設處於關閉狀態（false），其他類型燈光將忽略該設定。舊版本不包含此欄位，而是採用全域統一的場景層級開關；載入使用全域開關儲存的歷史場景時，所有支援霧氣的燈光均會自動啟用 volumetric。

SceneEnvironment 新增了 volumetricLighting 與 clusteredLighting 兩個選用設定項。舊版本不包含這些屬性，提供相應控制項前應預先檢查欄位是否存在。

volumetricLighting 決定全場景霧氣的外觀表現，其自身不設全域開關，僅當場景中至少存在一盞啟用了霧氣效果的活躍光源時，體積霧才會渲染生效。目前版本會傳回完整的霧氣參數設定，可透過 scene.patch 更新：

體積霧圍繞啟用了霧氣的光源產生散射，受深度遮蔽，未受照亮區域保持完全透明；只要場景中存在任意一盞啟用了霧氣的活躍光源，3D 物件與環境模型內建的點光源、聚光燈和面光源亦會共同激發散射。

體積霧要求使用透視相機：在正交投影下設定參數予以保留，但不進行體積霧渲染。平行光與環境光不參與體積霧計算，Live2D 圖層亦不產生遮蔽。

clusteredLighting: true 用於在 WebGPU 透視相機管線下，為 1 – 64 盞具備有效照射範圍且不投射陰影的點光源提供叢集光照著色加速，預設關閉（false）。若點光源未設有效照射範圍、光源數量超出上限，或執行在不支援的渲染器/相機投影下，系統將自動回退至常規光照管線。叢集著色不會降低陰影渲染開銷，亦不影響體積光照的採樣光源。

在支援 environment-map-model 能力的版本中，SceneEnvironment 可同時包含 iblAssetId 與 modelAssetId：

• bakeFromModel 決定是否從 3D 環境模型產生環境光照探針，並將環境貼圖作為輸入；設為 false 時直接採用環境貼圖照明，若無貼圖則回退至模型內建天空。
• showSkybox 僅控制背景渲染：無論由何種方式提供環境照明，背景始終渲染貼圖或模型天空。
• 清除其中一項資源將完整保留另一項，可透過 SDK 的 environmentClearPatch() 產生對應的補丁物件。舊版本同一時刻僅允許設定一項環境資源，設定新資源時須明確清空另一項。

此外，可透過 scene.patch 設定全景環境貼圖的以下三個選用屬性。這些屬性僅在支援的版本中存在，應先確認欄位可用後再顯示對應控制項：

物理模擬複製錨點連結

SceneEnvironment.physics 為場景的 物理模擬 全域開關：啟用後 3D 物件將受到重力作用墜落至舞台地面，並與 VRM 虛擬形象產生碰撞接觸。該欄位預設為 false，舊版本不包含該屬性。物理引擎模擬產生的動態姿態不會寫入檔案儲存，透過 API 讀取的物件座標始終為初始擺放數值；關閉 physics 後，所有物件將立即重設回歸初始座標。

stage.spawn 將已註冊的 prop 道具素材批次生成為受物理驅動的動態物件，投放至舞台中。需要 stage-spawn 能力；成功時傳回 { spawned, alive }，其中 alive 為舞台上所有物理物件的目前存活總數。

這些物理物件僅存在於渲染器記憶體中：不建立獨立場景項目，不佔用圖層清單，不可復原，也不隨場景儲存。同一素材的所有物理複本共用幾何體網格、紋理與批次繪製呼叫，即便有數百個實例依然具備高效能。目前場景未啟用 physics 時，呼叫傳回 invalid-state 錯誤；素材未註冊時傳回 not-found，素材不是 prop 類型時傳回 invalid-params。

超出有效範圍的參數值將被自動截斷修正至邊界值。物理物件將在 ttlMs 逾時、切換場景或關閉全域 physics 開關時自動銷毀；亦可呼叫 stage.clearSpawned {} 主動清空；該呼叫會傳回 { cleared }，並取消尚未完成素材載入的產生任務。

場景轉場複製錨點連結

呼叫 scene.activate 將等待目標場景資源完全載入並接管舞台渲染（在此載入期間原場景保持正常執行並支援即時編輯），但不會等待轉場動畫完全結束。若在轉場過程中發起新的場景切換請求，後發請求將覆蓋搶佔前序任務，因此回應傳回的 activeSceneId 代表實際最終生效的場景。SDK 預設為場景切換操作預留 120 秒逾時時間，設定了 requestTimeoutMs 時以明確設定為準。

支援 scene-transitions 能力的版本會在 Scene.transition 中包含各場景設定的 場景轉場 參數（即進入該場景時播放的視覺過渡）。呼叫 scene.patch { transition } 可整組替換轉場設定，但不會立即觸發播放：

無論何種場景切換途徑，均統一執行目標場景中定義的轉場效果。除無過渡的直接硬切（cut）外，所有轉場均會立即啟動並在後台資源載入完成前持續遮蔽舞台，若目標場景載入耗時較長，遮罩將自動延長超越 durationMs。影片素材轉場全程靜音播放，播放速率根據時長自動縮放適配，等待場景就緒期間畫面將自動定格在 switchPoint 對應的影格上。

場景預設複製錨點連結

支援 scene-presets 能力的版本會在 Scene.presets 中依顯示順序列出該場景已儲存的 場景預設，每項為 { id, name, transition, items }。舊版本主機不包含 presets 欄位。

• items 以實例 ID 為鍵，值為 { visible, place }。
• Live2D 模型與 2D 物件的 place 為 { space: '2d', x, y, scale, rotation }，其餘為 { space: '3d', x, y, z, rotX, rotY, rotZ, scale }。不透明度不屬於預設。
• 儲存預設後新增的圖層沒有對應條目，套用預設時保持原狀。

preset.* 方法均作用於目前作用中的場景：

create、update、rename 與 setTransition 傳回 { preset }，delete 與 apply 傳回 {}。

transition 決定舞台如何移至預設配置，圖層的顯隱變化同樣遵循該方式：

• 在過渡進行中儲存，記錄的是圖層即將停駐的位置；對舞台正在前往的預設再次呼叫 apply 不會產生變化。
• 目前場景中不存在的預設 ID 傳回 not-found；預設 ID 僅在單一場景內唯一，複製場景會保留原有 ID。
• 桌面端的編輯與套用均計為場景復原步驟，每次變更都會透過 scene.changed 推送。
• 鍵盤、遊戲控制器與 Stream Deck 透過包含套用預設操作的自動化（或 Stream Deck 的 Apply Preset 按鍵）觸發預設。

背景透明度複製錨點連結

支援 background-alpha 能力的版本允許 SceneBackground.color 攜帶 Alpha 位元組（#rrggbbaa）。透明舞台即 Alpha 為 00 的 color 背景，不再是獨立的背景模式（詳見 舞台背景）。主機仍接受舊版 transparent 模式（LEGACY_TRANSPARENT_BACKGROUND），並將其儲存為同一顏色的零 Alpha 版本。

未宣告該能力的舊版主機仍使用 transparent 模式，並會將帶 Alpha 的顏色修正為預設顏色。SDK 用戶端會自動適配此類主機：

• 將其傳回的 transparent 讀取為零 Alpha 顏色。
• 傳送 scene.patch 時，把 Alpha 為 00 的 color 背景轉換為 transparent。
• 移除其餘背景顏色的 Alpha 位元組。

顯示與隱藏複製錨點連結

SceneEnvironment.itemTransition { style, durationMs } 用於設定場景內圖層的 顯示與隱藏 過渡規則：定義模型、物件及產生道具在登場與退場時的動畫表現。舊版本不包含該屬性。style 可選：

durationMs 範圍為 0 – 5000 毫秒，預設 300。當樣式為 cut 或 durationMs 設為 0 時，圖層將瞬時出現或消失。可透過 scene.patch 更新環境設定。

圖層特效複製錨點連結

支援 layer-effects 能力的版本允許為單個模型或物件掛載專屬的 畫面特效，在圖層併入全場景合成前先行渲染。每個場景項目均具備獨立的 effects 與 effectLayers 結構，與全場景特效規範完全一致，可透過 instance.setEffects { instanceId, effects, effectLayers? } 進行編輯：

• effects 接受 color、levels、colorWheels、colorShift、selectColors、gradient、blur、bloom、diffusion、sketch、rim、outline 與 dropShadow 的局部參數設定，未宣告項保留原值
• 傳入 effectLayers 時將完整覆蓋已新增的特效階層清單；處於啟用狀態的特效始終包含在清單中

介面回應將傳回校正後的完整設定：超出範圍的數值將被限制在邊界內，未知欄位將被自動過濾捨棄。若傳入參數存在格式錯誤，整個呼叫將在任何修改套用前失敗結束。

泛光（bloom）的光照強度遵循 Warudo 的 Camera Bloom（Beautify 規格）：

邊緣光（rim）採用類似 VTube Studio 的背光演算法：白色輪廓截斷為純白，並自然衰減融入主體固有色。它不包含 blendMode 屬性（舊版傳入將被丟棄），預設顏色為 #ffeb74，預設大小為 0.5。

輪廓（outline）接受正規化的 size、color、opacity、quality（low、medium、high）以及 roundness：正規化的圓角平滑半徑，用於填補狹窄縫隙並平滑轉角，設為 0 時嚴格貼合剪影原貌。

素描特效（sketch）基於 Jaume Sanchez 的 NPR 素描著色器，可作為全場景特效（environment.effects.sketch）或圖層特效使用：

• 全場景層級下 paperBackground: true 會以紙張底色填補透明背景；圖層層級則始終保留來源圖層的透明通道。
• 較舊版本的主機回傳的特效集合中不包含 sketch。

魚眼特效（fisheye）僅可作為全場景特效使用（environment.effects.fisheye）：畫面依魚眼鏡頭的成像從中心向外鼓起。strength（0 – 1，預設 0.5）控制彎曲程度，1 相當於畫面對角線 150° 的魚眼。四角保持不動，因此畫面始終填滿，邊緣中段會被裁切。較舊版本的主機回傳的特效集合中不包含 fisheye。

圖層特效支援作用於虛擬形象模型及位於 2D 或 3D 空間的物件。2D 空間中的影像、影片、網頁與文字需主機宣告 layer-effects-2d 能力，其特效在該物件於圖層堆疊中的位置合成（無論是否釘選），並隨物件不透明度一同淡變；舊版本主機針對 2D 空間物件呼叫將傳回 unsupported-for-format 錯誤，但會保留已儲存的特效設定。切換物件空間時，已儲存的特效設定同樣予以保留。

追蹤來源複製錨點連結

Persona 支援並行執行多個已設定的動作與面部追蹤來源。settings.tracking.sources 列出目前所有追蹤來源，可透過 tracking.addSource、tracking.updateSource 與 tracking.removeSource 進行管理。

instance.setTrackingSources 支援依追蹤來源 ID 將實例的面部、姿態與手部通道（faceSourceId、poseSourceId、handSourceId）分別路由至指定來源。若將某個通道設定為 null 或傳入不存在的 ID，將停止該通道的動作驅動。新建立的實例預設綁定各通道的系統全域預設來源；單個追蹤來源可並行驅動多個舞台實例。

instance.setTrackingSources 還支援設定 handTrackingMode：arms 模式下捕捉的手部將同時連動驅動 VRM 的手臂、手腕與手指關節；fingers 模式下僅驅動手指關節點，手臂姿態交由 VMC 或 mocopi 等身體姿態來源控制。

面部與姿態追蹤來源支援以下類型：

• 面部追蹤來源可透過選用的 phoneIp 繫結指定的傳送裝置。
• 新增來源時省略 port，將從該類型的預設連接埠起自動選用第一個空閒連接埠。
• 若連接埠已被其他處理程序或追蹤來源佔用，設定請求將被拒絕；同類 ifacialmocap 或同類 persona-ios 實例間支援共用同一底層通訊端。
• 已廢棄的 vts-ios-native 會在協定層直接被拒絕。

mediapipe 為內建的 網路攝影機追蹤來源，全域單例執行，無需設定 port 或 phoneIp。其設定物件包含：

預設設定為鏡像開啟、基於 CPU 執行，啟用面部與手部追蹤並關閉身體追蹤。tracking.addSource 與 tracking.updateSource 接受局部選項設定，未宣告的參數保持原有狀態。捕捉到的手部姿態資料亦會同步驅動 參數注入 規範中宣告的手部輸入項。

tracking.status 傳回網路面部來源與姿態來源的彙總執行狀態，並在 sources 對應表中提供每個已設定追蹤來源（包含攝影機）的獨立狀態物件；tracking.status 事件具備相同的酬載結構，當任一獨立追蹤來源的狀態發生變動時均會觸發通知。

舊版單一來源控制方法依然有效，預設作用於對應通道的第一個網路追蹤來源：

• tracking.setSource 切換其類型。
• pose.setSource 切換其協定（尚無該追蹤來源時自動建立），並傳回指派的連接埠。
• pose.setPort 用於修改該連接埠。
• tracking.setEnabled 與 pose.setEnabled 為網路面部與姿態來源的全域總開關。

攝影機追蹤來源僅遵從自身的 enabled 狀態，可透過 tracking.updateSource 設定；停用期間，其任務開關與模型通道綁定關係完整保留。攝影機推論依賴桌面端的攝影機追蹤附加元件，API 不提供附加元件下載方法；桌面端尚未安裝該附加元件時，mediapipe 來源狀態保持為 waiting。

麥克風口型同步複製錨點連結

口型同步 利用桌面主機的音訊輸入裝置驅動模型嘴型。音訊輸入裝置清單與音訊擷取都在執行 Persona 的桌面主機本機完成。原始音訊與校正係數只保留在桌面端，既不經過 API 傳輸，也不會出現在公開設定中。音訊分析演算輸出的資料亦會同步驅動 參數注入 中列出的音訊輸入項。

上述設定亦對應至 settings.lipSync，可透過 settings.patch 直接修改。

校準流程使用桌面端目前選定的麥克風，並與桌面控制面板保持狀態同步，分為以下步驟：

錄製指令發起後會立即傳回，進度狀態應輪詢 lipSync.state：酬載中的 calibration 將回報目前階段 phase（ready、recording 或 verifying）、正在錄製的音素及已完成的音素清單。在不相符的階段呼叫對應步驟將傳回 invalid-state 錯誤。

instance.setLipSync { instanceId?, mode } 用於設定麥克風是否驅動指定模型：always（始終驅動，預設）、when-untracked（僅在面部追蹤遺失時介入）或 off（關閉）。對非模型物件呼叫將傳回 unsupported-for-format 錯誤。

語音驅動複製錨點連結

speech.play 可播放指定音訊串流，並基於音訊能量即時驅動模型口型。該方法僅適用於能力表宣告包含 speech 的模型實例（目前支援所有已載入的 Live2D 模型）。可用性判斷始終基於實例執行階段的動態能力宣告，而非格式靜態推斷（如 0.53 及更早版本在舊版 WebGL 渲染管線下不宣告該能力）。

單個模型實例同一時刻僅能播放一段語音，後發呼叫的語音將自動搶占中斷目前播放。呼叫成功傳回即表示音訊串流已開始解碼播放，若無法啟動則傳回 invalid-state 錯誤。播放生命週期由 speech.started 與 speech.ended 事件完整包圍；亦可呼叫 speech.stop 提前終止播放。

虛擬形象快速鍵複製錨點連結

模型內建的 快速鍵 由以下三個方法進行讀寫控制，均支援選用的 modelId 參數，省略時作用於目前場景的主模型：

舞台上所有模型均各自維護一套生效的快速鍵設定，無論其是否為主模型，亦無論其為 Live2D 還是 VRM 格式：當按下某個全域組合鍵時，所有綁定了該快速鍵的模型將各自觸發對應的動作並在各自模型上生效。若 hotkey.trigger 指向的模型不在目前舞台上，系統會直接略過該呼叫，不擲出異常。

Hotkey 設定物件包含四個繼承自 VTube Studio 規範的選用屬性：

較舊版本的主機不傳回這些欄位；若在 hotkey.set 中未傳入某項設定，系統將保留其已有數值，防止舊用戶端覆寫抹除進階設定。

由於 hotkey.trigger 是單次事件呼叫、不存在按鍵放開動作，對於標記為 hold 的快速鍵，透過該介面觸發將作為狀態翻轉開關（Toggle）處理。透過 hold 或 deactivateAfterSeconds 臨時啟用的表情狀態，無論透過何種途徑觸發，均不會隨模型狀態儲存至檔案。

Hotkey.accelerator 由最多三個以 + 連接的標記組成，依同時按住的集合觸發：修飾鍵（MODIFIER_TOKENS：Control、Alt、Shift、Super）、Electron 命名的按鍵、滑鼠按鍵 LeftMouseButton、RightMouseButton 與 MiddleMouseButton，或同一控制器的 Controller* 按鈕。由於順序不影響比對，比較兩個組合時請使用 SDK 的 comboKey，而非直接比較字串；在介面上顯示按鍵時，可使用 acceleratorLabel(accelerator, app.platform) 依 hello 回報的桌面端平台產生對應的鍵帽標籤陣列。

HotkeyState.registered 列出目前在 Persona 處於背景時仍會回應的快速鍵：桌面端透過讀取按鍵狀態而非向系統註冊來監聽快速鍵，因此任何開啟 global 的組合鍵（包括單一按鍵）都會列入。舊版主機僅列出其向系統註冊的含 Control、Alt 或 Super 的組合鍵。

自動化複製錨點連結

支援 automations 能力的版本支援查詢並遠端觸發應用程式中的 自動化工作流程，即由快速鍵、系統事件或 API 請求連動觸發的一組舞台動作序列；具備 automation-editing 與 automation-transport 能力時，還可讀寫完整的時間軸定義並控制時間軸播放。

automation.list 傳回輕量摘要欄位：id、title、accelerator、registered（目前在 Persona 處於背景時是否仍會回應；舊版主機表示是否已向系統註冊）、enabled，以及 actionKinds 與 triggerKinds 兩個動作與觸發條件類型陣列，足以支撐主控台渲染操作面板，而無需讀取完整時間軸。

若 title 為 null，可根據 actionKinds 拼接語意化顯示標籤（SDK 內建的 automationLabel 工具函式即為此設計）。actionSceneIds 陣列與 actionKinds 保持索引對應，記錄每個 scene-switch 動作的目標場景 ID（其他類型動作對應位置為 null），以便顯示目標場景名稱。

每條自動化均為一條時間軸序列，actionKinds 陣列的順序不代表實際執行的時間順序。動作種類採用類別優先命名：

• delay 動作已廢棄移除，時間軸上的空白間隙即代表延遲等待。
• 音訊播放不開放獨立 API：音訊檔案解碼、播放控制與輸出裝置管理均執行在桌面本機，外部用戶端若需播放音訊，應觸發或播放包含 audio-play 的自動化規則。
• 舊版主機發送的舊動作命名（定義於 LEGACY_AUTOMATION_ACTION_KINDS，涵蓋 actionKinds 與 Hotkey.action）在 SDK 用戶端接收時會自動正規化對應；亦可透過 canonicalActionKind 工具函式轉換。
• triggerKinds 列出該規則在快速鍵之外支援的事件觸發條件類型，目前涵蓋 scene、model-loaded、motion、face-tracking、microphone 與 parameter。

具備 automation-editing 能力時，automation.get 傳回完整的 AppAutomation（包含 durationMs、autoDuration、帶 id/startMs/durationMs/sourceInMs 的 actions、triggers、cooldownMs、accelerator、global 與 enabled）：

• automation.create 與 automation.update 接受 AutomationDefinition（由 AutomationDefinitionSchema 驗證，欄位或時間範圍不合法時傳回 invalid-params）。
• 新增的自動化預設處於關閉狀態（enabled: false），不綁定快速鍵（accelerator: null、global: false），並由伺服端重新指派所有 ID，在使用者手動啟用前不會自動觸發。
• automation.update 會整體取代動作、觸發條件、時長與冷卻時間並重新產生步驟 ID，同時保留已儲存的快速鍵 accelerator、global 與 enabled 開關。
• 透過 API 建立、更新或刪除自動化不支援復原，並會清空桌面端時間軸編輯器針對該自動化保留的復原歷史。

具備 automation-transport 能力時，automation.control 與 automation.status 可驅動並查詢桌面端時間軸播放（AutomationRunStatus：{ automationId, phase, positionMs, durationMs, error, steps }，目前工作階段尚未執行、預覽或預熱過該自動化時 run 為 null）：

• play 會播放完整時間軸（即使 enabled 為 false 也會播放到底；處於暫停或拖曳定位狀態時從目前位置繼續），pause 暫停時間軸，prepare 預先載入媒體與動畫素材，seek 將播放頭移至 positionMs 並在舞台上即時預覽 畫面效果片段、鏡頭機位、圖層可見性、設定文字 與 播放歌詞，stop 停止播放並釋放預覽狀態。
• 最近一次控制某條自動化播放的工作階段持有其控制所有權：若該用戶端中斷連線，處於暫停、預覽或失敗狀態的執行會自動停止，使快速鍵與事件觸發條件恢復回應；正在播放或預熱的執行若隨後進入暫停或失敗狀態，也會自動停止。

未綁定鍵盤、滑鼠或控制器快速鍵的自動化規則其 accelerator 欄位為 null，仍可透過 automation.run 正常遠端觸發。處於停用狀態的規則其 enabled 為 false，將忽略所有觸發（包含 automation.run，但仍可透過 automation.control 的 play 試播）。automation.run 發起後會立即傳回確認，不阻塞等待時間軸執行結束。當自動化清單、定義、啟用狀態或背景回應狀態發生改變時，系統將透過 automation.state 事件推送完整的最新摘要清單。

應用程式設定複製錨點連結

settings.get 與 settings.patch 用於讀取和更新受限許可清單內的應用程式全域設定（視窗釘選、系統匣、效能參數、手把開關等），而非底層原始設定庫。

回應結果及 settings.changed 事件中附帶唯讀的視窗尺寸資訊：

• window.stageSize: { width, height }：舞台檢視區目前的裝置無關像素尺寸，隨視窗拉伸即時重新整理
• window.stageReferenceSize: { width, height }：用於校準舞台擺放單位與模型適配的基準尺寸。其高度決定縮放比例：未固定的 ScreenPlacement 單個 x/y 座標單位在渲染時對應距離檢視區中心 stageSize.height / stageReferenceSize.height 個裝置無關像素

渲染管線在任何外觀比例下均會填滿目前檢視區視窗。對於 2D 內容與透視 3D 檢視，調整視窗寬度僅會在水平方向擴展或裁切畫面，不會重新縮放內容或產生黑邊；正交 3D 檢視保持其寬度為 abs(orbit.distance)。儲存的擺放參數在視窗縮放與應用程式重啟後保持不變；繪製擺放控制項的用戶端應以目前 stageSize 的外觀比例為準。較舊版本的主機可能不傳回上述尺寸欄位，視窗在桌面上的實體螢幕位置始終對外保密。

效能設定包含 showFps、fpsLimit、effectsQuality 與 renderScale（舊版本選用）。手把預設設定在設定中為唯讀屬性，需透過專門的 controller.* 方法進行修改。回應結果與 settings.changed 事件中亦包含唯讀的 ui.streamMode（串流模式），以便遠端面板對敏感網頁 URL 進行遮蔽保護（舊版本主機可能省略該欄位）。

外掛儲存區複製錨點連結

storage.* 為外部外掛提供鍵值儲存（KV Storage），以 API 金鑰 為命名空間進行資料隔離。使用同一 API 金鑰的所有工作階段共用該儲存分區，撤銷金鑰將同步清空其對應的全部資料。儲存的值支援任意合法的 JSON 序列化資料。

儲存配額限制為：單個鍵名最大 128 字元，單個值序列化後最大 64 KB，每個 API 金鑰上限儲存 256 個鍵。若呼叫 storage.set 超出最大鍵數配額，介面將傳回 invalid-state 錯誤。

錯誤代碼複製錨點連結

當伺服端回傳錯誤影格時，persona.call 以攜帶 code（屬於 API_ERROR_CODES）的 PersonaApiError 拒絕：

上述錯誤代碼為正式通訊協定規範的一部分：用戶端將自動捨棄攜帶未知錯誤代碼的異常影格，因此新增錯誤代碼僅隨協定大版本一同發布，常規業務錯誤均對應至現有錯誤列舉中。

當用戶端自身或底層傳輸層無法完成 connect() 或 call() 時，則會以攜帶 reason（屬於 CLIENT_ERROR_REASONS）的 PersonaClientError 拒絕：

• connect() 可能遇到 connect-timeout、connection-closed 或 client-closed（若 url 本身無法發起連線，例如格式不合法，則直接以執行環境的原生例外如 TypeError 拒絕 Promise，不會同步擲出）。
• call() 可能遇到 not-connected、request-timeout、connection-closed 或 client-closed。

中斷連線複製錨點連結

SDK 用戶端在遇到非預期的網路中斷時會自動執行指數退避重新連線。以下 WebSocket 關閉碼表示不可復原的終止狀態，將停止自動重新連線機制：

接收到上述關閉碼後，用戶端將最終轉換至 closed 狀態。若初始化時設定了 onClose 回呼，終止事件將發送至該回呼並略過 onWarning；若未設定 onClose 則回退發送至 onWarning。標準關閉碼 1001（Going Away）不在此列，該代碼代表 Persona 伺服端正在正常關閉或重啟，用戶端將持續嘗試重新連線。

撤銷金鑰將立即捨棄所有待傳送的待處理訊息影格，並以 4001 關閉所有持有該金鑰的活躍連線。正在等待舞台渲染管線回應的未決請求將被立即中斷取消；已投遞至舞台管線的渲染指令可能執行完畢，但其回應將被伺服端直接捨棄。

協定版本演進複製錨點連結

通訊協定內建主版本號（Protocol Version），若用戶端與伺服端版本不相符，SDK 將輸出警告記錄。訂閱舊版本 Persona 不支援的事件不會導致嚴重錯誤，SDK 將自動降級回退至逐個獨立訂閱模式，保留可用的事件通道，並輸出警告記錄不受支援的事件清單。

目前協定主版本為 4。歷史演進中從協定中精簡與規範了部分介面，面向舊協定編寫的外掛需進行相應遷移適配：