blender-toolkit

⚠️ インストールの確認（最初にお読みください）

重要：このスキルを使用する前に、Blender アドオンのインストール状況を確認してください。

設定ファイルの場所：共有設定ファイルでインストール状況を確認してください。

~/.claude/plugins/marketplaces/dev-gom-plugins/blender-config.json

スクリプトは必ず最初に --help を付けて実行し、使い方を確認してください。スクリプトを実行してみて、カスタマイズした解決策がどうしても必要だとわかるまでは、ソースを読まないでください。これらのスクリプトは非常に大きく、コンテキストウィンドウを圧迫する可能性があります。コンテキストウィンドウに読み込むのではなく、ブラックボックスのスクリプトとして直接呼び出すことを想定しています。

設定に応じて必要な操作：

1. Blender が検出されない場合（blenderExecutable: null）

初期化中に Blender が見つかりませんでした。次の操作を行ってください。

1. https://www.blender.org から Blender 4.0 以降をインストールしてください。
2. 自動検出を実行するため、Claude Code のセッションを再起動してください。
3. ログを確認してください：.blender-toolkit/init-log.txt

2. 複数のバージョンが検出された場合（detectedBlenderVersions 配列）

複数の Blender のインストールが検出されました。別のバージョンを使用する場合は、次の操作を行ってください。

1. 設定ファイルを開きます（上記のパスを参照してください）。
2. blenderExecutable フィールドを編集して、使用するバージョンのパスを指定します。
3. Claude Code のセッションを再起動してください。

例：

{
  "detectedBlenderVersions": [
    {"version": "4.2.0", "path": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe"},
    {"version": "4.1.0", "path": "C:\\Program Files\\Blender Foundation\\Blender 4.1\\blender.exe"}
  ],
  "blenderExecutable": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe"
}

3. アドオンがインストールされていない場合（addonInstalled: false）

アドオンを手動でインストールする必要があります。次の手順に従ってください。

手動インストール手順：

方法 1：ZIP からインストール（推奨）

# 1. Open Blender 4.0+
# 2. Edit > Preferences > Add-ons > Install
# 3. Select: .blender-toolkit/blender-toolkit-addon-v*.zip
# 4. Enable "Blender Toolkit WebSocket Server"

方法 2：ソースからインストール

# 1. Open Blender 4.0+
# 2. Edit > Preferences > Add-ons > Install
# 3. Select: plugins/blender-toolkit/skills/addon/__init__.py
# 4. Enable "Blender Toolkit WebSocket Server"

WebSocket サーバーを起動：

1. 3D ビュー → サイドバーを開きます（N キーを押します）。
2. 「Blender Toolkit」タブを見つけます。
3. 「Start Server」ボタンをクリックします。
4. デフォルトのポート：9400（プロジェクトごとに自動割り当て）

設定を更新：

• 設定ファイルを開きます（上記のパスを参照してください）。
• "addonInstalled": true に設定します。
• ファイルを保存します。

接続を確認：

• 簡単なコマンドを試します：node .blender-toolkit/bt.js list-objects
• 成功すると、シーン内のオブジェクトの一覧が表示されます。

トラブルシューティング：

• Blender のパスが正しくない場合：設定の blenderExecutable を更新します。
• ポートが使用中の場合：システムが次に利用可能なポート（9401～9500）を自動的に割り当てます。
• ログを確認してください：.blender-toolkit/init-log.txt
• Blender のコンソールでエラーメッセージを確認してください。

4. すべて準備できている場合（addonInstalled: true）

✅ 準備完了です！すべての Blender Toolkit コマンドを使用できます。

---

blender-toolkit

WebSocket によるリアルタイム制御で Blender のワークフローを自動化します。ジオメトリの作成、マテリアルやモディファイアーの管理、インテリジェントなボーンマッピングによる Mixamo アニメーションのカスタムリグへのリターゲットが可能です。

目的

次の機能を通じて、包括的な Blender の自動化を提供します。

• 🎨 ジオメトリの作成 - プリミティブ（立方体、球体、円柱、平面、円錐、トーラス）
• 🎭 マテリアル管理 - マテリアルの作成、割り当て、設定
• 🔧 モディファイアー制御 - モディファイアーの追加、適用、管理
• 🎬 アニメーションのリターゲット - 自動ボーンマッピングによる Mixamo からカスタムリグへのリターゲット

使用する場面

次のような場合に、このスキルを使用してください。

• 3D ジオメトリの作成： ユーザーがプリミティブを作成したり、メッシュを操作したりしたい場合
• マテリアルの管理： ユーザーが PBR プロパティを持つマテリアルを作成または割り当てる必要がある場合
• モディファイアーの追加： ユーザーがサブディビジョン、ミラー、配列などのモディファイアーを使用したい場合
• アニメーションのリターゲット： ユーザーが Mixamo アニメーションをカスタムキャラクターに適用する必要がある場合
• 一括操作： ユーザーが複数のオブジェクトまたはアニメーションを処理したい場合

注： Mixamo は公式 API を提供していません。ユーザーは Mixamo.com から FBX ファイルを手動でダウンロードする必要があります。

クイックスタート

前提条件のチェックリスト

開始する前に、次の項目を確認してください。

• Blender 4.0 以降がインストールされている
• Blender Toolkit アドオンがインストールされ、有効になっている
• Blender で WebSocket サーバーが起動している（デフォルトのポート：9400）
• キャラクターのリグが読み込まれている（アニメーションのリターゲットの場合）

アドオンのインストール：

1. Open Blender → Edit → Preferences → Add-ons
2. Click "Install" → Select plugins/blender-toolkit/skills/addon/__init__.py
3. Enable "Blender Toolkit WebSocket Server"
4. Start server: View3D → Sidebar (N) → "Blender Toolkit" → "Start Server"

よくある操作

ジオメトリの作成：

# Create cube at origin
blender-toolkit create-cube --size 2.0

# Create sphere with custom settings
blender-toolkit create-sphere --radius 1.5 --segments 64

# Subdivide mesh
blender-toolkit subdivide --name "Cube" --cuts 2

オブジェクトの管理：

# List all objects
blender-toolkit list-objects

# Transform object
blender-toolkit transform --name "Cube" --loc-x 5 --loc-y 0 --scale-x 2

# Duplicate object
blender-toolkit duplicate --name "Cube" --new-name "Cube.001" --x 3

マテリアル：

# Create material
blender-toolkit material create --name "RedMaterial"

# Assign to object
blender-toolkit material assign --object "Cube" --material "RedMaterial"

# Set color
blender-toolkit material set-color --material "RedMaterial" --r 1.0 --g 0.0 --b 0.0

アニメーションのリターゲット：

# Basic retargeting with UI confirmation
blender-toolkit retarget \
  --target "HeroRig" \
  --file "./Walking.fbx" \
  --name "Walking"

# Rigify preset (skip confirmation)
blender-toolkit retarget \
  --target "MyRigifyCharacter" \
  --file "./Walking.fbx" \
  --mapping mixamo_to_rigify \
  --skip-confirmation

# Show Mixamo download instructions
blender-toolkit mixamo-help Walking

アーキテクチャ

WebSocket ベースの設計：

┌──────────────┐         ┌─────────────┐    WebSocket    ┌──────────────┐
│ Claude Code  │   IPC   │ TypeScript  │◄──────────────►│   Blender    │
│   (Skill)    │────────►│   Client    │   Port 9400+   │  (Addon)     │
└──────────────┘         └─────────────┘                └──────────────┘
                              │                               │
                              ▼                               ▼
                     ┌─────────────────┐         ┌────────────────────┐
                     │  - Geometry     │         │  - WebSocket       │
                     │  - Material     │         │    Server          │
                     │  - Modifier     │         │  - Command         │
                     │  - Retargeting  │         │    Handlers        │
                     │  - Bone Mapping │         │  - Bone Mapping UI │
                     └─────────────────┘         └────────────────────┘

主なコンポーネント：

• WebSocket サーバー： Blender 内の Python アドオン（ポート 9400-9500）
• TypeScript クライアント： JSON-RPC 経由でコマンドを送信
• ボーンマッピングシステム： UI での確認を伴うファジーマッチング
• 2 段階のワークフロー： 生成 → 確認 → 適用

主なワークフロー

1. ジオメトリ作成ワークフロー

要件を抽出：

• プリミティブの種類（立方体、球体、円柱など）
• 位置（x、y、z 座標）
• サイズのパラメーター（半径、深度、セグメント数）
• オブジェクト名（任意）

実行：

import { BlenderClient } from 'blender-toolkit';

const client = new BlenderClient();
await client.connect(9400);

// Create sphere
const result = await client.sendCommand('Geometry.createSphere', {
  location: [0, 0, 2],
  radius: 1.5,
  segments: 64,
  name: 'MySphere'
});

console.log(`✅ Created ${result.name} with ${result.vertices} vertices`);

2. マテリアル割り当てワークフロー

手順：

1. マテリアルを作成
2. オブジェクトに割り当て
3. プロパティを設定（色、メタリック、粗さ）

実行：

# Create and configure material
blender-toolkit material create --name "Metal"
blender-toolkit material set-color --material "Metal" --r 0.8 --g 0.8 --b 0.8
blender-toolkit material set-metallic --material "Metal" --value 1.0
blender-toolkit material set-roughness --material "Metal" --value 0.2

# Assign to object
blender-toolkit material assign --object "Sphere" --material "Metal"

3. アニメーションのリターゲティングワークフロー ⭐

最も一般的なユースケース

フェーズ 1：セットアップとマッピングの生成

1. User provides:
   - Target character armature name
   - Animation FBX file path
   - (Optional) Animation name for NLA track

2. System executes:
   - Connects to Blender WebSocket
   - Imports FBX file
   - Analyzes bone structure
   - Auto-generates bone mapping (fuzzy matching)
   - Displays mapping in Blender UI for review

3. Quality Assessment:
   - Excellent (8-9 critical bones) → Safe to auto-apply
   - Good (6-7 critical bones) → Quick review recommended
   - Fair (4-5 critical bones) → Thorough review required
   - Poor (< 4 critical bones) → Manual mapping needed

フェーズ 2：ユーザーによる確認

1. User reviews mapping in Blender:
   - View3D → Sidebar (N) → "Blender Toolkit" → "Bone Mapping Review"
   - Check source → target correspondence
   - Edit incorrect mappings using dropdowns
   - Use "Auto Re-map" button to regenerate if needed

2. User confirms:
   - Click "Apply Retargeting" button in Blender

3. System completes:
   - Creates constraint-based retargeting
   - Bakes animation to keyframes
   - Adds to NLA track
   - Cleans up temporary objects

例：

import { AnimationRetargetingWorkflow } from 'blender-toolkit';

const workflow = new AnimationRetargetingWorkflow();

// If user doesn't have FBX yet
console.log(workflow.getManualDownloadInstructions('Walking'));

// After user downloads FBX
await workflow.run({
  targetCharacterArmature: 'HeroRig',
  animationFilePath: './Walking.fbx',
  animationName: 'Walking',
  boneMapping: 'auto',           // Auto-generate with fuzzy matching
  skipConfirmation: false        // Enable UI review workflow
});

確認を省略（適切なマッピングが既知の場合）：

# Rigify preset - instant application
blender-toolkit retarget \
  --target "RigifyCharacter" \
  --file "./Walking.fbx" \
  --mapping mixamo_to_rigify \
  --skip-confirmation

# Excellent quality - trusted auto-mapping
blender-toolkit retarget \
  --target "MyCharacter" \
  --file "./Walking.fbx" \
  --skip-confirmation

主な機能

UI レビュー付き自動ボーンマッピング 🌟

不明またはカスタムのリグに推奨されるワークフロー：

動作の仕組み：

1. ファジーマッチングアルゴリズム

   • ボーン名を正規化します（さまざまな命名規則に対応）
   • 類似度スコア（0.0～1.0）を計算します
   • 次の条件にボーナスを適用します：
     • 部分文字列の一致（+0.15）
     • 一般的な接頭辞：left、right（+0.1）
     • 一般的な接尾辞：.L、.R、_l、_r（+0.1）
     • 数字の一致：Spine1、Spine2（+0.1）
     • 解剖学上のキーワード：arm、leg、hand（+0.05）

2. 品質評価

   • 9 個の重要なボーン（Hips、Spine、Head、腕、脚、手）を追跡します
   • 品質評価（優秀／良好／普通／低品質）を提示します
   • 品質に基づいて推奨アクションを示します

3. UI 確認パネル

   • マッピング全体を表形式で表示します
   • 各マッピングに編集可能なドロップダウンを用意します
   • 「自動再マッピング」ボタン（再生成）
   • 「リターゲティングを適用」ボタン（続行）

メリット：

• あらゆるリグ構造に対応します
• 手動で設定する必要がありません
• 適用前にユーザーが確認できます
• アニメーションのエラーを防止します

3 種類のボーンマッピングモード

1. 自動モード（推奨） ⭐

# Default: Auto-generate with UI confirmation
blender-toolkit retarget --target "Hero" --file "./Walk.fbx"

• ファジーマッチングアルゴリズム
• UI レビューワークフロー
• 不明なリグに最適

2. Rigify モード

# Preset for Rigify control rigs
blender-toolkit retarget --target "Hero" --file "./Walk.fbx" --mapping mixamo_to_rigify

• Mixamo → Rigify の事前定義済みマッピング
• 即座に適用
• Rigify で最も高い精度

3. カスタムモード

// Explicit bone mapping
const customMapping = {
  "Hips": "root_bone",
  "Spine": "torso_01",
  "LeftArm": "l_upper_arm",
  // ... complete mapping
};

await workflow.run({
  boneMapping: customMapping,
  skipConfirmation: true
});

• 完全な制御
• アニメーション間で再利用可能
• 標準外のリグ向け

複数プロジェクトへの対応

ポートの自動管理：

• プロジェクトには一意のポート（9400-9500）が自動的に割り当てられます
• 設定はセッションをまたいで保持されます
• 複数の Blender インスタンスを同時に実行できます

設定の保存先：

// ~/.claude/plugins/.../blender-config.json
{
  "projects": {
    "/path/to/project-a": { "port": 9400 },
    "/path/to/project-b": { "port": 9401 }
  }
}

重要なガイドライン

ユーザーに確認するタイミング

次の場合は AskUserQuestion ツールを使用します：

• キャラクターのアーマチュア名が不明な場合
• 複数のリグが存在する場合（対象が曖昧）
• アニメーションの FBX パスが指定されていない場合
• Blender の WebSocket 接続に失敗した場合
• ユーザーに Mixamo のダウンロード方法を案内する必要がある場合

次の項目を推測してはいけません：

• キャラクター名
• ファイルパス
• リグ構造

Mixamo のダウンロード手順

Mixamo には API がないため、ユーザーが手動でダウンロードする必要があります：

手順を案内：

// Show download help
const workflow = new AnimationRetargetingWorkflow();
console.log(workflow.getManualDownloadInstructions('Walking'));
console.log(workflow.getRecommendedSettings());

ユーザーの対応を待つ：

• Mixamo.com からのダウンロードを案内します
• ダウンロード完了後にファイルパスを確認します
• その後、リターゲティングを進めます

トラブルシューティング

「Blender が実行されていません」

# Check connection
blender-toolkit daemon-status

# If failed:
1. Verify Blender is open
2. Check addon is enabled
3. Start server: Blender → N → "Blender Toolkit" → "Start Server"

「対象のアーマチュアが見つかりません」

• アーマチュアの正確な名前を確認します（大文字と小文字を区別します）
• キャラクターが現在のシーンにあることを確認します
• list-objects --type ARMATURE を使って、使用可能なアーマチュアを確認します

ボーンマッピングの「品質が低い」

1. Blender でボーン名を確認します（編集モード）
2. 重要なボーンにカスタムマッピングを作成します
3. 類似度のしきい値を下げます（デフォルト：0.6）
4. リグに適切な階層があることを確認します

「手足がねじれる、または反転する」

• 左右のボーンマッピングを確認します
• 編集モードでボーンロールを確認します
• コンストレイントの軸を確認します
• まず簡単なアニメーションでテストします

ベストプラクティス

1. 🌟 UI で確認しながら自動モードを使用する

   • 未知のリグで最も信頼性が高い方法です
   • 重要なボーン（Hips、Spine、Arms、Legs）を必ず確認してください
   • 適用する前に、誤ったマッピングを編集してください

2. まずはシンプルなアニメーションをテストする

   • Idle または Walking から始めます
   • ボーンマッピングが正しく機能することを確認します
   • ルートモーション（Hips ボーン）を確認します
   • その後、複雑なアニメーションに進みます

3. Mixamo から正しい形式をダウンロードする

   • 形式：FBX (.fbx)
   • スキン：スキンなし
   • FPS：30 fps
   • キーフレーム削減：なし

4. 自動適用する前に品質を確認する

   • 優秀（重要なボーンが8～9個）→ 確認を省略しても安全です
   • 良好（重要なボーンが6～7個）→ 手早く確認します
   • 普通（重要なボーンが4～5個）→ 入念に確認します
   • 不良（重要なボーンが4個未満）→ カスタムマッピングを使用します

5. カスタムマッピングを保存して再利用する

   • 成功したマッピングを記録します
   • 同じキャラクターのアニメーションで再利用します
   • チームメンバーと共有します

6. ポート管理はシステムに任せる

   • ポートを手動で設定しないでください
   • システムが複数プロジェクト間の競合を処理します
   • 設定は自動的に保持されます

参考資料

詳細なドキュメントは references/ フォルダーにあります。

• commands-reference.md - CLI コマンドの完全なリファレンス

  • すべてのジオメトリ、オブジェクト、マテリアル、モディファイアのコマンド
  • 詳細なオプションと例
  • ポート管理とヒント

• bone-mapping-guide.md - ボーンマッチングシステムの詳細

  • ファジーマッチングアルゴリズムの解説
  • 品質評価の指標
  • 一般的なマッピングパターン（Rigify、UE4、Unity）
  • マッピング問題のトラブルシューティング

• workflow-guide.md - ワークフローの完全なドキュメント

  • リターゲティングの手順
  • Mixamo のダウンロード手順
  • 2段階確認の詳細
  • バッチ処理のワークフロー
  • 複数プロジェクトのワークフロー

• addon-api-reference.md - WebSocket API のドキュメント

  • JSON-RPC プロトコルの詳細
  • すべての API メソッドとパラメーター
  • エラー処理
  • セキュリティとパフォーマンスのヒント

参考資料を読み込むタイミング：

• ユーザーがコマンドオプションの詳細を必要としている場合
• 複雑な問題のトラブルシューティングを行う場合
• ボーンマッピングアルゴリズムを理解する場合
• 高度なワークフローを設定する場合
• API 統合の要件がある場合

出力構造

.blender-toolkit/
├── skills/scripts/          # Local TypeScript scripts (auto-initialized)
│   ├── src/                 # Source code
│   ├── dist/                # Compiled JavaScript
│   └── node_modules/        # Dependencies
├── bt.js                    # CLI wrapper
├── logs/                    # Log files
│   ├── typescript.log
│   ├── blender-addon.log
│   └── error.log
└── .gitignore

Shared config:
~/.claude/plugins/.../blender-config.json

メモ

• ポート範囲： 9400-9500（Browser Pilot は 9222-9322 を使用します）
• ファイル形式： FBX を推奨します。Collada (.dae) にも対応しています
• Blender のバージョン： 4.0 以降が必要です（2023 年以降）
• 自動初期化： SessionStart フックがスクリプトをインストールしてビルドします
• デーモンの手動管理は不要： すべてシステムが処理します
• WebSocket プロトコル： JSON-RPC 2.0