scenario-roblox-animation

Roblox のアニメーションとキャラクター

対象環境：macOS 上の Roblox Studio（2026 年 10 月ビルド）。scenario-roblox-expert ツールキットを使用します。

ここでいうエキスパートレベルとは、すべてのクリップ、レイヤー、IK チェーン、顔について、Studio で数値を用いて検証済みであることを意味します。どのトラックが各ジョイントに優先されるか、各マーカーがいつ発火するか、サーバー側では何が見えるか、ステップ実行したポーズが元データと一致するかを確認します。エージェントは Animation Editor を操作できないため、コードでクリップを作成し、Edit でステップ実行し、プレイテストで再生して、完了と判断する前にジョイントとトラックを測定します。ここに記載された兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で作業を続ける場合は、ツールのスキーマに基づいて進め、不足している機能を明記してください。

必須の背景知識： scenario-roblox-expert（チャンネル、レビューの反復、ツールキット、現行 Roblox で注意すべき点）。

方針（エキスパートとして押さえるべき点）

1. アバターのジョイントは Motor6D ではなく AnimationConstraint です。 Avatar Joint Upgrade により、R15 の C0 と C1 は読み取り専用になりました（L1、L8）。プロシージャルな動きは PreSimulation で Transform に乗算され、遅延バッチとして適用されるため、レプリケートされません（Suphi Kaner、BRYp2-rdpXQ 00:00:33）。ジョイントを検索するコードは、どちらのクラスにも対応する必要があります。
2. リグを所有する側から Animator を通じて読み込みます。 所有クライアントは自分のキャラクターのトラックを再生し、サーバー側にもその再生が見えます（L6）。サーバーは NPC のトラックを再生し、クライアント側にもその再生が見えます（L7）。Humanoid:LoadAnimation は非推奨です。
3. 優先度はジョイントごとに適用され、キーによって対象が決まります。 高い優先度が勝つのは、そのトラックがキーを設定したジョイントだけです。恒等キーでも、そのジョイントは確保されます（L4）。コードでクリップを作成する場合、パス上にあるだけの親 Pose は Weight 0 にする必要があります。そうしないと、下位のトラックを上書きします［追加］（L4）。
4. ゲームプレイのタイミングには必ずマーカーを使い、wait は使いません。 パラメーター付きでイベント名を 1 つ使います（Develuper、d5GGIJJyMpg 00:02:52）。GetMarkerReachedSignal は 1 フレーム以内に発火しました（L6）。KeyframeReached には名前付きキーフレームが必要です（BrawlDev、zSK7bOoxuig 00:25:25）。
5. 顔はプロパティを書き換えるのではなく、クリップとして再生します。 プレイヤーのダイナミックヘッドでは、すべてのトラックを停止していても、FaceControls の書き込みや完了したトゥイーンは 0.5 秒以内に 0 に戻ります［追加］（L10、L16）。顔のクリップなら状態を保持し、レプリケートされ、ムードアニメーションにも上書きされません。
6. IKControls はサーバー上で作成し、look-at の Weight は 0.999 にします。 Weight が 1 の場合、ターゲットが背後を通ると首がねじれます。IKControl.Priority でソルブの順序を指定し、Pole はコードから設定します（Suphi Kaner、8fV-XOOj6O4 00:18:56、00:53:00、00:54:40）。
7. Blender のクリップは 24 fps、アーマチュアのみとし、スケールキーは設定しません。 Leaf bones、NLA strips、All Actions はオフにし、Force Start/End Keying と Simplify 0 はオンのままにします（Mykaiju、NI7GXKLwk6U 00:23:45～00:27:07）。60 fps にしてもゲームプレイ上の利点はなく、キーが 2 倍になるだけです（Nisky、EM9u4gIHoRg 00:07:55）。
8. 一時 ID はテスト用のフィクスチャです。 RegisterKeyframeSequence のハッシュと active:// ID は Studio でのみ機能します。リリースするゲームでは、エクスペリエンスの所有者が公開した rbxassetid:// ID を参照します（Animation Editor のドキュメント）。

最初に確認すること

• リグの種類。 R15 アバター（AnimationConstraint、BallSocket の制限）、カスタムパーツリグ（Motor6D）、 スキンメッシュ（Bones）、または AnimationController を使うクリーチャーです。推測せずに P1 を実行してください。
• 誰が何を再生するか。 プレイヤーのクリップはクライアントで、NPC のクリップはサーバーで、装飾レイヤーはローカルで再生します。
• サーバーオーソリティ。 有効にすると、Animator が保持するアクティブなトラックは最大 8 つになり、トラックはキャッシュせず、 毎ティック GetTrackByAnimationId で検索します。
• キャラクターコントローラーライブラリ。 有効にすると、移動は ControllerManager とアビリティによって制御されます。 アビリティのコールバックでは yield しません。
• 顔。 ダイナミックヘッド（Head に FaceControls がある）ですか？
• モーションソース。 Blender の FBX、Scenario で生成されたリグまたはモーション、Animation Editor、あるいはコードです。
• 公開者。 ユーザーまたはグループです。クリップはエクスペリエンスのオーナー名義で公開する必要があります。
• デフォルト：R15、ゲームプレイ用クリップは Action、ロコモーションは Idle と Movement、24 fps、マーカー名はイベント名とし、パラメーターを付けます。

手順

各ステップのコードは references/procedures.md（P1 から P15）にあり、実行したテストとその数値も記載されています。

1. リグを調査する（P1）。 モデルに対して AnimRig.joints、AnimRig.tree、AnimRig.path を実行します。 ゲート：ジョイントのクラスが判明しており、アニメーションするすべてのパーツにルートからのパスがあり、Animator が存在すること。
2. クリップを作成または取り込む（P2、P3、P10）。 コードで作成するクリップには AnimClip.keyframes または AnimClip.curves を使い、 AnimClip.register で登録してから AnimClip.load で読み込みます。Length > 0 になるまで待機します。Blender のクリップは blender_roblox_anim.py（監査、エクスポート、サンプル取得）を経由し、AnimClip.fromSamples を使います。ゲート：ステップ補間された ジョイント角度がキーと 0.3 度以内で一致すること。Blender のボーンの先端が 0.01 スタッド以内で一致すること。
3. レイヤーとタイミングを設定する（P4）。 優先度、ウェイト、フェードを設定し、各クリップが所有するジョイントだけにキーを設定します。 接地フレームにマーカーを置きます。ゲート：AnimClip.tracks(animator) に各ジョイントの想定される優先トラックが表示され、 各マーカーが 1 サイクルごとに 1 回だけ発火すること。
4. 編集モードでプレビューする（P5）。 まず AnimClip.settle を呼び出します。自然終了したクリップも次のクリップにブレンドされます（P3）。 rbx_animation.pose_sheet は Animator:StepAnimations でトラックを進め、各時点をキャプチャしてコンタクトシートを 1 つ作成します。 ゲート：シートを読み、フレーム差分がゼロより大きいことを確認します。プレースを保存する前に AnimRig.reset を実行し、ポーズが残った ジョイントがないことを確認します。
5. プレイテストする（P6、P8）。 プレイヤーのクリップはクライアントから、NPC のクリップはサーバーから再生します。両側でジョイントを読み取ります。 ゲート：サーバーがクライアントのトラックを検出し、両側で同じジョイント角度が報告され、キャプチャにポーズが表示されること。
6. レイヤー、IK、顔を設定する（P9、P12、P7）。 プロシージャルオフセットは PreSimulation で Transform に設定し、 Animator.EvaluationThrottled が true の場合はスキップします。IK には AnimIK.reach と AnimIK.lookAt、顔には AnimFace.clip を使います。 ゲート：サーバーで測定した首のヨー角、IK のギャップ、顔の値を確認し、それぞれキャプチャも取得すること。
7. デフォルト設定と監査（P13、P14）。 Animate の値を使ってデフォルトアニメーションを置き換え、AnimAudit.all を実行します。 ゲート：エラーや警告の検出がないこと。状態変更後にクライアントが新しいクリップを再生することを、ID ではなく Length とジョイント角度で確認します。
8. 公開リスト。 公開するすべてのクリップ、その優先度、ループ設定、マーカー、オーナーを一覧にします。 ゲート：配布コードに一時 ID が含まれていないこと（AnimAudit ルール temp-animation-id）。

数値

値	数値	対象
優先順位	Core < Idle < Movement < Action < Action2 < Action3 < Action4	Enum.AnimationPriority
デフォルトの Animate トラック	idle は Core、mood は Idle	L6、プレイヤーアバター
フェード	Play(0.4) は 0.1 秒ごとに重みが 0.25 ずつ増加します	L4
同じ優先順位でのブレンド	加重平均：重みが等しい場合、90 度と 60 度は 75 度、重みが 1 と 0.25 の場合は 84 度になります	L4
重み 0.5 の Action を Idle に重ねる	90 度と 30 度の間の 60 度になります	L4
再生開始から 0.25 秒のマーカー	266 ms で発火、フレームは 16.3 ms	L6、速度 2
Stopped と Ended	0.5 秒の再生で、それぞれ 500 ms と 816 ms	L6
自然終了後に新しいクリップを再生	古いポーズが 0.25～0.375 秒間ブレンドされます（0.25 秒時点では 22.5 度ではなく 31.8 度）	L3
初回読み込み	LoadAnimation 時の Length は 0、Edit での読み込みに 14 ms	L2
45 度の Neck レイヤー	関節では 41.9 度、頭部はルートから 45.5 度ずれています	L8
IK のリーチ	リーチ可能なターゲットから手が 0.20～0.23 studs の位置に 0.1 秒以内に到達し、クライアントでも同じです	L9
IK の制限	リーチ不可能なターゲットから 4.17 studs、Weight 0.5 では 1.13	L9
IK SmoothTime 0.5	0.6 秒間で間隔が 1.81 studs から 0.37 studs に縮まります	L9
視線	Weight は 0.999、頭部はターゲットから 0.05 度以内	L9、Suphi Kaner
顔への書き込みまたはトゥイーン	0.5 秒以内に 0 に戻ります	L10
顔クリップ	クライアントとサーバーで JawDrop は 0.55、キャプチャでは口が開いています	L10
Blender から Studio への変換	10 個のボーン、25 フレームで、ボーンテールの最大誤差は 0.0002 studs	L12
スキンウェイト	頂点あたり最大 4 個のインフルエンス	スキニングのドキュメント
Server Authority	Animator あたり最大 8 個のアクティブなトラック	Server Authority のドキュメント
Dynamic head	4,000 個の三角形。検証では 17 個の FACS ポーズから 5 個のアニメーションをチェックします	仕様書、Roblox Learn、OwhkWzSBnf0

品質ゲート

測定可能な項目：

• AnimAudit.all(game) がエラーも警告も返さないこと（P14）。
• コードで再生する各トラックについて、静止時に Length > 0、意図した優先度、および WeightCurrent が 1 と報告されること（AnimClip.tracks）。
• コードがリッスンする各マーカーが、各サイクルで指定時刻に1回、1フレーム以内の誤差で発火すること。
• レプリケートされたトラックについて、サーバーとクライアントが同じ関節角度を報告すること。
• Blender からエクスポートしたデータが、検出事項なしで audit に合格し、P10 の末端誤差が 0.01 スタッド未満であること。
• プレースを保存する前に、すべてのリグで AnimRig.dirty が空であること。

視覚的な項目（1,600 px 以下のコンタクトシート、rbx_review.contact_sheet）：

• 各クリップの4～6時点のポーズシート：シルエットが読み取れること、動作の軌道が自然であること、相互貫通がないこと、ループが閉じていること。
• プレイテストのキャプチャ：プレイヤーのクリップ、NPC のクリップ、ターゲットが見える IK のリーチ、ニュートラル状態のキャプチャと並べた顔のクローズアップ。
• references/critique.md を参考に評価してください。

よくある間違い

間違い	症状	対処
Core または Idle にクリップを設定する	再生されますが、デフォルトのアイドルアニメーションが優先されます	ゲームプレイ用クリップには Action を指定します
Action クリップで脚のキーを設定する	歩行中に脚が固まります	クリップが制御するジョイントだけにキーを設定します
Weight 1 の親を持つ、コードで構築したクリップ	上半身がアイドルアニメーションと歩行を上書きします	パスのみの Pose（AnimClip.keyframes）には Weight 0 を指定します
新規登録の直後に再生する	動きがなく、Length が 0 です	AnimClip.load は Length > 0 になるまで待機します
アバターのジョイントに C0 を書き込む	「プロパティは読み取り専用です」	PreSimulation で Transform に乗算します
R15 で FindFirstChildOfClass("Motor6D") を使う	アップグレード済みのアバターでは nil が返ります	AnimRig.joint は両方のクラスを受け入れます
FaceControls を Tween する	表情が一瞬表示された後、中立に戻ります	Animator で再生する AnimFace.clip を使用します
ヒットのタイミングに task.wait を使う	速度や遅延によってヒットのタイミングがずれます	パラメーター付きのマーカーを使用します
Edit でプレビューのポーズを残したままにする	保存したプレースにそのポーズが表示されます	AnimRig.reset(rig) を実行します
Custom のスキニング済みインポートで rig.HumanoidRootPart を使う	nil になります：インポーターはルートを RootPart（2 x 2 x 1）と命名し、ボーンは衝突しません	AnimRig.prepareImport を実行します。実行前に作成したクリップもバインドされます（references/characters.md）
別のクリップの終了直後に測定する	最初の 0.3 秒間、古い終了ポーズに向かってブレンドされます	Edit では AnimClip.settle を使用し、ゲーム内では意図的にフェードさせます
ID で置き換え後のデフォルトを確認する	古いクリップの再生中でも ID は一致します	状態変更後に Length とジョイントを確認します
Blender で 60 fps またはスケールキーを使う	クリップが重くなり、スケールは無視されます	24 fps にし、回転と位置のみを使用します
LookAt Weight 1	ターゲットが後方にあると首がねじれます	0.999
一時的な ID を公開する	Studio では動作しますが、ライブ環境では失敗します	エクスペリエンスの所有者として公開します
共有リグ用の Animator をクライアントで作成する	他のユーザーには表示されません	サーバーで作成します

引き継ぎ

• scenario-roblox-assets から受け取るもの: インポート済みのリグとスキニング済みメッシュ。scenario-3d で生成されたリグ付きキャラクターとモーションも含まれます。モーションは FBX または Blender ファイルとして届き、P10 を経由します。リグは Model として届き、P1 で検査します。
• scenario-roblox-gameplay に渡すもの: 接触フレームにマーカーを設定したクリップとそのパラメーター。これらを呼び出すヒットボックス、状態、NPC の振る舞いは gameplay が担当します。
• scenario-roblox-vfx-audio に渡すもの: 足音、衝撃、軌跡のマーカー名と時刻。
• scenario-roblox-networking と連携する内容: 視線方向のレプリケーション、Server Authority のトラックルール、クライアント専用の装飾レイヤー。
• scenario-roblox-performance と連携する内容: Animator の数、NPC のカリング（範囲外ではアンカーを設定し、Animator を無効化。RDC 2025 rwLEnBtXr30 00:09:24）、stepAnimation のコスト。
• scenario-roblox-architecture と連携する内容: アニメーションコントローラーの配置場所（プレイヤーキャラクター用のクライアントモジュール、NPC 用のサーバーサービス）。
• ユーザーに依頼すること: 記載されたクリップを公開してもらいます。エージェントがアップロードすることはありません。

現在の Roblox に関する注意点

• Avatar Joint Upgrade：R15 アバターは、15 個の AnimationConstraint ジョイントと 14 個の BallSocketConstraints を持ってスポーンします（L1）。
• Workspace.AuthorityMode はプラグインレベルの Luau から読み取れません（RobloxScript の機能が必要です）。Server Authority が有効かどうか、ユーザーに確認してください。
• Character Controller Library はオプトイン方式です。無効の場合、クライアントでは require("@rbx/AvatarAbilities") が戻らず、サーバーではテーブルが返されます（L15）。
• Adaptive Animation：HumanoidRigDescription:AutoRig には RobloxScript の機能が必要です。ジョイントのマッピングと T ポーズは Adaptive Animation ツール（GUI）で設定します。コードからジョイントをマッピングしても、名前を変更したパーツにクリップをリターゲットできませんでした（L14）。
• AnimationGraphDefinition は存在します。グラフは Graph Editor（GUI）で編集します。
• 現在の UI では、Avatar > Clip Editor から Animation Editor を開きます。

参考資料

• references/procedures.md：P1 から P15 までの完全なコード、テスト ID、結果。
• references/characters.md：カスタムスキニング済みメッシュのリグへのインポート、プレイヤーと NPC の再生スクリプト、クリーチャーの足の接地、動的ヘッドケージと検証、FBX インポートのチェック、キャラクターのコスト。
• references/expert-notes.md：専門家別の原則とタイムスタンプ。
• references/critique.md：アニメーション作業を評価するためのルーブリック。
• references/gui-paths.md：人間またはコンピューター操作エージェント向けの Animation Editor、インポート、顔、ベータ版の切り替え手順。
• references/sources.md：認証情報とタイムスタンプを含むすべてのソース。
• scripts/rbx_animation.py：キットのインライン化、Blender ラッパー、サンプルローダー、Edit ポーズシート。
• scripts/blender_roblox_anim.py：ヘッドレス Blender テストリグ、監査、FBX エクスポート、再インポート、サンプル。
• scripts/agentkit/animation/：AnimRig、AnimClip、AnimAudit、AnimIK、AnimFace の Luau モジュール。