Kx VRC ARKit BlendShape Generator
顔トラ機材を投入するのにBlendShapeが無いアバターをどうにかするために既存表情からARKit用BlendShapeを生成するやつをClaude Codeに作らせました
あくまで自分用の簡易的なもので100%生成したコードなのでメンテは期待しないでください
以下生成した説明文
VRChat/MMDのBlendShapeからARKit用BlendShapeを自動生成するNDMFプラグインです。
Jerry's Templatesと組み合わせて使用することで、フェイストラッキング非対応アバターを簡単に対応させることができます。
必要要件
- Unity 2022.3.6f1以降
- NDMF 1.5.0以降（プレビュー機構がNDMF 1.5.0で追加されたため、1.4系ではコンパイルできません）
- VRChat SDK (Avatars)
インストール
VCC/ALCOM経由（推奨）
- VPMリポジトリをVCC/ALCOMに追加
- プロジェクトに「Kx VRC ARKit BlendShape Generator」を追加
手動インストール
- Releasesからzipファイルをダウンロード
- VCCのプロジェクト管理画面で「Add Package」→「Add from Archive」を選択
- ダウンロードしたzipファイルを選択
booth版（unitypackage）
Releasesの VRCARKitBlendShapeGenerator_<バージョン>.zip に、unitypackageが1つ入っています。
展開してUnityへドラッグすると Assets/AtelierKairox/VRCARKitBlendShapeGenerator/ へ取り込まれます。
VPM版と同時に入れないでください。
どちらもアセンブリ名が同じため、1つのプロジェクトへ両方を入れるとコンパイルが通りません。
更新は下の「更新の確認」の通知から行えます。
手で入れ直す場合の手順は docs/update-check.md にまとめています。
更新の確認
新しいバージョンが出ているかを、エディタの読み込み時に自動でReleasesへ問い合わせます。
エディタから外部へ通信しますが、送るのはリリース情報の取得要求だけで、1日1回までです。
通信を望まない場合は Preferences > ARKit BlendShape Generator から止められ、止めれば問い合わせを行わず更新の通知も出ません。
知らせるのは安定版が出たときだけです。
Packages/ 配下（VCC/ALCOM経由）の場合は、新しいバージョンが出ていることをインスペクタで知らせるだけにとどめ、更新はVCC/ALCOMで行います。
Assets/ 配下（unitypackageから導入）の場合は、通知のダイアログか、インスペクタの先頭に出る「更新する」ボタンからそのまま更新できます。
更新の仕組みと注意点（取り込み前の控え、フォルダを移動している場合の制限など）は docs/update-check.md にまとめています。
使用方法
基本的な使い方
- アバターのルートオブジェクトまたは顔メッシュを持つオブジェクトを選択
- Inspector > Add Component > KxVRCARKitBlendShapeGenerator > Kx VRC ARKit BlendShape Generator を追加
- Jerry's Templates (MA版) をアバターに追加
- アップロード時に自動的にARKit BlendShapeが生成されます
設定項目
| 項目 | 説明 |
|---|
| Target Renderer | 対象のSkinnedMeshRenderer（空の場合はBody/Face/Headを自動検出） |
| Intensity Multiplier | 生成時の強度係数（0.5〜1.5推奨） |
| Enable Left Right Split | 頂点のX座標による左右分割を行う（まばたき等を左右別々に生成）。OFFにするとカスタムマッピングのSide指定も無視され、両側に適用される |
| Blend Width | 左右分割時のグラデーション幅（中央付近で左右をブレンドする範囲、0.001〜0.1。メッシュローカル座標で中心から片側への幅を指定するため、グラデーション全体は指定値の2倍） |
| Overwrite Existing | 既存のARKit BlendShapeを上書きする |
| Output Naming | 生成するBlendShapeの名前の体系（デフォルト: ARKit）。Unified Expressionsと両方は実験的な選択肢で、後述の「出力名の種別（実験的）」を参照 |
| Write Native FT Blendshapes Set | ビルド時に、VRChatのネイティブフェイストラッキング用のBlendshapes SetをAvatar Descriptorへ書き込む（デフォルト: 無効）。後述の「ネイティブフェイストラッキングのBlendshapes Set（実験的）」を参照 |
| Enable Procedural Mouth Shapes | 既存シェイプキーから生成できない口周りのBlendShapeを頂点移動で自動生成する（デフォルト: 無効） |
| Procedural Mouth Intensity | 手続き的生成の変形量係数（0.1〜2.0） |
| Enable Mouth Cancellation | 生成した口関連BlendShapeに、指定したBlendShapeの打ち消し成分を焼き込む（デフォルト: 無効） |
| Mouth Cancellation Strength | 打ち消し量の全体係数（0.0〜1.0） |
| Custom Mappings | 自動マッピングできないBlendShapeを手動で指定 |
| Debug Mode | デバッグログを出力する |
Target Renderer が空のときは、コンポーネントの直下にある Body / body / Face / face / Head / head のいずれかの名前を持つSkinnedMeshRendererを優先し、見つからなければ自身を含む子孫の最初のSkinnedMeshRendererを対象にします。
どちらの検索も非アクティブなオブジェクトを含みます。
この探索順序はビルド、プレビュー、インスペクタ表示のすべてで共通です。
カスタムマッピング
自動マッピングで対応できない場合は、カスタムマッピングを使用して手動でBlendShapeを指定できます。
- Custom Mappingsセクションを展開
- 「+」ボタンで新しいマッピングを追加
- ARKit名（例:
eyeBlinkLeft）とソースBlendShapeを指定
- 必要に応じてWeight（重み）とSide（左右フィルタ）を調整
ソースBlendShapeの名前はシェイプキー名との完全一致で照合します（大文字小文字や前後の空白も区別されます）。
Sideの詳しい扱いや、特定のBlendShapeを生成させない設定、同名マッピングの重複判定は docs/mapping.md にまとめています。
NDMFプレビュー
NDMFのプレビュー機能を使用して、生成結果をリアルタイムで確認できます。
- Unityメニュー > Tools > NDM Framework > Configure Previews を開く
- 「Kx VRC ARKit BlendShape Generator」のプレビューを有効化
- 生成されるBlendShapeをシーンビューで確認
コンポーネントのインスペクタにある「NDMF Preview」のON/OFFボタンからも同じ設定を切り替えられます。
表情改変の修正ツールとの併用
表情改変で崩れたシェイプキーをビルド時に直すNDMFツールと併用できます。
生成は修正後のシェイプキーから行われるため、まばたきや口の修正がARKit BlendShapeにも反映されます。
対応を確認しているのは次の2つです。
Avatar Blink Fixのプレビュー中は、ソースBlendShapeの一覧に ---Avatar Blink Fix--- という名前のシェイプキーが現れます。
修正済みであることを示す目印で、変形を持たないため、ソースには選ばないでください。
Avatar Blink Fixのプレビューを止めているあいだは、本ツールのプレビューだけが修正前の形から生成されます。ビルドでは修正後の形から生成されます。
Face BlendShape Fixのプレビューは、元のシェイプキーを書き換えずに確認用のシェイプキーを別名で足す作りです。
そのため本ツールのプレビューは修正前の形から生成され、修正後の形から生成されるビルド結果とは一致しません。
修正が反映された形を見るには、ビルド結果で確認してください。
対応BlendShape
以下のARKit BlendShapeを自動生成します：
- 目: eyeBlinkLeft/Right, eyeSquintLeft/Right, eyeWideLeft/Right
- 視線: eyeLookUpLeft/Right, eyeLookDownLeft/Right, eyeLookInLeft/Right, eyeLookOutLeft/Right
- 眉: browDownLeft/Right, browInnerUp, browOuterUpLeft/Right
- 口: jawOpen, jawLeft/Right/Forward, mouthFunnel, mouthSmileLeft/Right, mouthFrownLeft/Right, mouthLeft/Right, mouthUpperUpLeft/Right, mouthLowerDownLeft/Right, mouthStretchLeft/Right, mouthClose, mouthShrugUpper/Lower, mouthPress
- 頬: cheekPuff, cheekSquintLeft/Right
- 鼻: noseSneerLeft/Right
- 舌: tongueOut
VRChat/MMDの標準的なBlendShape名（vrc.blink, まばたき, あ, い, う等）から自動的にマッピングされます。
自動マッピングでは、対応するシェイプキーがアバターに無いものは生成されません（口の一部は後述の手続き的生成で補えます）。
視線（Eye Look）は EyeUp_L や 目上 といったシェイプキーを持つアバターが少ないため、多くの場合はカスタムマッピングでの手動設定が必要です。
ARKit名ごとの対応シェイプキー名は、インスペクタの「自動マッピング一覧（参照用）」で確認できます。
mouthPucker だけは口元が破綻しやすいため自動生成せず、理由と経緯は docs/mapping.md にまとめています。
出力名の種別（実験的）
Output Naming で、生成するBlendShapeの名前の体系を選べます。
- ARKit（デフォルト）: Jerry's TemplatesのARKitテンプレート向けで、これまでどおりの動作です
- Unified Expressions: VRCFTが定めるUnified Expressionsの名前で生成します
- 両方: ARKit名とUnified Expressions名の両方を生成します
ARKit以外は、VRChatのネイティブフェイストラッキング（High Fidelity Face Tracking）への対応に向けた実験的な機能です。
SDKの仕様が公開されるまで、Unified Expressions名への対応表と分割のしかたは変わる可能性があります。
生成の中身はどの種別でもARKit名を基準に決まり、名前の変換はメッシュへ書く直前に行われます。
そのため、カスタムマッピングと口の打ち消しの焼き込み先はARKit名のまま指定します。
ARKit名として知らない名前をカスタムマッピングに付けた場合は、変換せずそのまま出します。
Unified Expressions名を出すとき、メッシュに同名のARKit BlendShape（jawOpen など）が既にあれば、VRChat/MMDのシェイプキーから作り直さず、そのARKit BlendShapeを変換元にします。
変換は形を変えない複写で、フレーム構成もそのまま写します。強度係数と口の打ち消しは掛かりません。
カスタムマッピングで同じARKit名を指定している場合は、そちらが優先されます。
Unified ExpressionsでARKitの1つが左右や上下に分かれる名前は、変形を分割して出します。
左右（BrowInnerUpLeft/Right など）は左右分割の設定に従い、上下（LipFunnelUpper/Lower、MouthUpperLeft + MouthLowerLeft など）は口の手続き的生成と同じ口領域の検出で唇の境界線を求めて分けます。
口のシェイプキー（vrc.v_aa、あ など）が無く境界線を求められないアバターでは、上下どちらにも元の形を半分の強度で出します。
対応表の全体は docs/mapping.md にまとめています。
「両方」では使われない側のBlendShapeがメッシュに残ります。
AAO: Avatar Optimizer の Trace and Optimize など、未使用のBlendShapeを取り除くツールと併用してください。
ネイティブフェイストラッキングのBlendshapes Setが参照する側は、AAO 1.9.21以降ならAAO自身が使用中と判定して残します（後述の「AAO: Avatar Optimizer との併用」を参照）。
ネイティブフェイストラッキングのBlendshapes Set（実験的）
VRChatのネイティブフェイストラッキングは、Avatar Descriptorの Blendshapes Sets に書かれた「トラッキングキー → シェイプキー名」の対応だけを動かします。
キーと同じ名前のシェイプキーがあっても、自動では対応づけられません。
対応を埋めるSDKの自動入力（Auto Fill）はエディタ上のメッシュを見るため、ビルド中にしか存在しない本ツールの生成物は見つけられません。
Write Native FT Blendshapes Set を有効にすると、ビルド時に次を行います。
- Unified Expressionsのトラッキングキーごとに、生成したBlendShapeへの対応を持つBlendshapes Setを1つ、Avatar Descriptorへ追加する（既に本ツールが追加したSetがあれば置き換える）
- 対象のSkinnedMeshRendererを Face Tracking Meshes に加える
- Descriptorのフェイストラッキング（Enable Face Tracking）と、全トラッキングキーの受信（Use All Tracking Keys）を有効にする。後者が無効だと受け取るキーが視線とまばたきに限られ、Setに書いた口や頬の割り当てが動かないため
対応は、生成されたBlendShapeの名前から決めます。
Unified Expressions名を出していればその名前を、ARKit名しか無いキーはARKit名を使い、どちらも生成されていないキーは空のままにします。
Unified Expressionsで左右や上下に分かれているキーのうち、本ツールが1つのBlendShapeで出すもの（LipSuckUpper、LipPucker など）は、分かれたキーのそれぞれへ同じBlendShapeを割り当てます。
キーごとの対応表は docs/mapping.md にまとめています。
アップロード前の警告について。
SDKのアップロード前チェックはビルド前のアバターに対して行われるため、生成物を参照するSetの対応は「解決できない（unresolved）」として警告されます。
この警告はアップロードを止めません。
ビルドの成果物では対応が解決され、Face Tracking Operationsのパフォーマンスランクにも反映されます。
視線（EyeLook*）とまぶた（EyeClosed*）の割り当ては、Avatar DescriptorのEye LookとEyelidsがFace Trackingになっているときだけ使われます。
どちらもアバターの見え方を変える設定なので本ツールは書き換えません。ボーンの視線やアニメーションのまばたきを使い続けるなら、そのままで構いません（目以外の割り当ては影響を受けません）。
ネイティブフェイストラッキングに対応していないVRChat SDK（3.10.6より前。3.10.6のベータ版を含む）では、この設定を有効にしても何も書き込みません。
Jerry's Templatesと同時に使うと、同じBlendShapeをアニメーターとネイティブフェイストラッキングの両方が動かすため、どちらか一方にしてください。
Kx VRC NativeFT Managerを同じアバターで使う場合は、この設定を無効のままにしておいて構いません。
NativeFT Managerの「Generatorコンポーネントを使う」（既定で有効）が、ビルド用の複製の上でだけこの設定を有効にします。シーンの設定は変わりません。
本ツールのコンポーネントを付けていないアバターでも、本ツールがプロジェクトに入っていれば、NativeFT Managerは本ツールと同じ対応表でARKit名のシェイプキーからSetを作れます（対応するNativeFT Managerの版が必要です）。
この設定が既定で無効なのは、Jerry's Templatesを使い続けるアバターで、同じBlendShapeを二重に動かさないためです。
AAO: Avatar Optimizer との併用
AAO: Avatar Optimizer と併用する場合は、AAO 1.9.21以降を使ってください。
1.9.21以降のAAOは、Avatar DescriptorのBlendshapes SetとParameter Behaviorsが動かすBlendShapeを使用中と判定し、名前を変えたときはSetも書き直します。
1.9.20以前のAAOは、Blendshapes Setからの参照を見ません。
Trace and Optimizeがネイティブフェイストラッキング用のBlendShapeを未使用として固定・統合し、Setの対応が解決できなくなります。
本ツールの以前の版はこれを防ぐ仮対応を持っていましたが、AAO本体が対応したため取り除きました。
口の手続き的生成
Enable Procedural Mouth Shapes を有効にすると、対応するシェイプキーがアバターに存在しない場合でも、以下の口周りBlendShapeが頂点の移動により自動生成されます（既存シェイプキーは口領域の検出にのみ使用されます）：
- mouthLeft / mouthRight（口の左右移動）
- jawLeft / jawRight / jawForward（顎の左右・前方移動）
- mouthShrugUpper / mouthShrugLower
- mouthUpperUpLeft/Right, mouthLowerDownLeft/Right
口領域の検出には vrc.v_aa、あ、vrc.v_nn、ん などの口のシェイプキーが必要です。
いずれも見つからないアバターでは、有効にしても何も生成されません。
シェイプキーから生成できた場合はそちらが優先され、手続き的生成はフォールバックとして動作します。デフォルトでは無効です。変形量は Procedural Mouth Intensity で調整できます。変形は口の前面（唇側）が最も大きく、奥の頂点ほど減衰するため、単純な平行移動よりも自然な動きになります。
口の打ち消し
Enable Mouth Cancellation を有効にすると、生成した口関連BlendShapeに、指定したBlendShapeの変形を打ち消す成分（逆方向のデルタ）を焼き込みます。
口角調整などのBlendShapeを常時適用しているアバターで、その変形とフェイストラッキングによる口の動きが二重に適用されるのを防ぐ用途を想定しています。
生成元のBlendShapeの側で既に修正済み（打ち消したい変形を含まない形で作られている）の場合、この設定は不要です。
設定手順:
Enable Mouth Cancellation を有効化- 「打ち消すBlendShape」に対象のBlendShapeを追加し、重みにアバター側での適用量を指定（1.0 = ウェイト100）
- Sideはアバター側での適用範囲を表すため、
Enable Left Right Split がOFFでも指定どおりに適用されます（カスタムマッピングのSideとは扱いが異なります）
- 「焼き込み先のARKit BlendShape」で、打ち消しを入れるARKit名を選択（デフォルト:
jawOpen）
BlendShapeは線形合成されるため、焼き込み先を複数選ぶと、それらが同時に適用されたときに打ち消しが重なって対象の変形を通り越し、逆向きに変形します。焼き込み先は必要最小限（多くの場合は jawOpen のみ）に絞ってください。打ち消し量は Mouth Cancellation Strength で弱めることもできます。
開発
開発者向けの情報は docs/ にまとめています。
ライセンス
MIT License
作者
kairox (@limit7412)
