表情

表情ツールは顔のウェイト、リアクションプリセット、アニメーション再生、視線追従動作を制御します。

set_expression

アクティブキャラクターの表情ウェイトを設定します。ウェイトの範囲は 0.0--1.0 です。

一般的な表情名：happy、sad、angry、surprised、relaxed、neutral、aa、ih、ou、ee、oh、blink。

パラメータ	型	デフォルト	説明
expressions	Record<string, number>	--	表情名からウェイトへのマップ。mode が "clear" でない限り必須。
mode	"set" | "modify" | "clear"	"modify"	"modify" は指定した表情のみ更新、"set" はすべて置換、"clear" はアニメーション制御状態にリセット。

例 -- やわらかい笑顔：

{
  "expressions": { "happy": 0.8, "relaxed": 0.3 },
  "mode": "modify"
}

サウンドやアニメーションを含むプリセットリアクションには、代わりに play_reaction を使用してください。

---

play_reaction

アクティブキャラクターで名前付きリアクションプリセットを再生します。各プリセットは表情、オプションの VRMA アニメーション、オプションの効果音を組み合わせたものです。

リアクションはグレースフルに劣化します -- アニメーションやサウンドアセットがインストールされていない場合でも、表情は再生されます。

パラメータ	型	デフォルト	説明
reaction	string	必須	リアクション名（下表を参照）
message	string	--	リアクションに関連するオプションのテキストメッセージ

利用可能なリアクション：

名前	表情	アニメーション	サウンド
happy	happy 1.0	idle-happy	success
sad	sad 0.8	--	--
confused	surprised 0.4	--	--
error	angry 0.3, sad 0.4	--	error
success	happy 0.9	celebrate	success
thinking	neutral 0.5	thinking	--
surprised	surprised 0.9	--	notification
neutral	--	--	--

---

play_animation

アクティブキャラクターで VRMA アニメーションを再生します。利用可能な VRMA アセット ID を確認するには homunculus://assets リソースを使用してください。

パラメータ	型	デフォルト	説明
asset	string	必須	VRMA アニメーションアセット ID（例：vrma:idle-maid）
repeat	"never" | "forever" | string	"never"	"never" は1回再生、"forever" はループ、数字の文字列（例："3"）で N 回繰り返し
transition_secs	number	0.3	クロスフェードトランジション時間（秒）
wait	boolean	false	アニメーション完了を待ってから返す
reset_spring_bones	boolean	false	トランジション時にスプリングボーン（SpringBone）の物理をリセットしてバウンスを防止

例 -- アイドルアニメーションをループ：

{
  "asset": "vrma:idle-maid",
  "repeat": "forever",
  "transition_secs": 0.5
}

---

set_look_at

アクティブキャラクターの視線方向を制御します。

パラメータ	型	デフォルト	説明
mode	"cursor" | "none"	必須	"cursor" はマウスポインタを追従、"none" は視線追従を無効化