⚠️ Installation Check (READ THIS FIRST)

IMPORTANT: Before using this skill, check Blender addon installation status.

Config location: Check the shared config file for your installation status:

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

Always run scripts with --help first to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.

Required actions based on config:

1. If Blender Not Detected (blenderExecutable: null)

Blender was not found during initialization. Please:

Install Blender 4.0+ from https://www.blender.org Restart Claude Code session to trigger auto-detection Check logs: .blender-toolkit/init-log.txt 2. If Multiple Versions Detected (detectedBlenderVersions array)

The system detected multiple Blender installations. If you want to use a different version:

Open config file (path shown above) Edit blenderExecutable field to your preferred version path Restart Claude Code session

Example:

{ "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" }

1. If Addon Not Installed (addonInstalled: false)

The addon needs to be installed manually. Follow these steps:

Manual Installation Steps:

Method 1: Install from ZIP (Recommended)

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"

Method 2: Install from Source

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"

Start WebSocket Server:

Open 3D View → Sidebar (press N key) Find "Blender Toolkit" tab Click "Start Server" button Default port: 9400 (auto-assigned per project)

Update Config:

Open config file (path shown above) Set "addonInstalled": true Save file

Verify Connection:

Try a simple command: node .blender-toolkit/bt.js list-objects If successful, you'll see a list of objects in your scene

Troubleshooting:

If Blender path is incorrect: Update blenderExecutable in config If port is in use: System will auto-assign next available port (9401-9500) Check logs: .blender-toolkit/init-log.txt Check Blender console for error messages 4. If Everything is Ready (addonInstalled: true)

✅ You're all set! You can use all Blender Toolkit commands.

blender-toolkit

Automate Blender workflows with WebSocket-based real-time control. Create geometry, manage materials and modifiers, and retarget Mixamo animations to custom rigs with intelligent bone mapping.

Purpose

Provide comprehensive Blender automation through:

🎨 Geometry Creation - Primitives (cube, sphere, cylinder, plane, cone, torus) 🎭 Material Management - Create, assign, and configure materials 🔧 Modifier Control - Add, apply, and manage modifiers 🎬 Animation Retargeting - Mixamo to custom rigs with automatic bone mapping When to Use

Use this skill when:

Creating 3D Geometry: User wants to create primitives or manipulate meshes Managing Materials: User needs to create or assign materials with PBR properties Adding Modifiers: User wants subdivision, mirror, array, or other modifiers Retargeting Animations: User needs to apply Mixamo animations to custom characters Batch Operations: User wants to process multiple objects or animations

Note: Mixamo does not provide an official API. Users must manually download FBX files from Mixamo.com.

Quick Start Prerequisites Checklist

Before starting, ensure:

Blender 4.0+ installed Blender Toolkit addon installed and enabled WebSocket server started in Blender (default port: 9400) Character rig loaded (for animation retargeting)

Install Addon:

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"

Common Operations

Create Geometry:

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

Manage Objects:

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

Materials:

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

Retarget Animation:

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

Architecture

WebSocket-Based Design:

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

Key Components:

WebSocket Server: Python addon in Blender (ports 9400-9500) TypeScript Client: Sends commands via JSON-RPC Bone Mapping System: Fuzzy matching with UI confirmation Two-Phase Workflow: Generate → Review → Apply Core Workflows 1. Geometry Creation Workflow

Extract Requirements:

Primitive type (cube, sphere, cylinder, etc.) Position (x, y, z coordinates) Size parameters (radius, depth, segments) Optional object name

Execute:

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);

1. Material Assignment Workflow

Steps:

Create material Assign to object Configure properties (color, metallic, roughness)

Execute:

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"

1. Animation Retargeting Workflow ⭐

Most Common Use Case

Phase 1: Setup & Generate Mapping

1. User provides:
2. Target character armature name
3. Animation FBX file path

4. (Optional) Animation name for NLA track

5. System executes:

6. Connects to Blender WebSocket
7. Imports FBX file
8. Analyzes bone structure
9. Auto-generates bone mapping (fuzzy matching)

10. Displays mapping in Blender UI for review

11. Quality Assessment:

12. Excellent (8-9 critical bones) → Safe to auto-apply
13. Good (6-7 critical bones) → Quick review recommended
14. Fair (4-5 critical bones) → Thorough review required
15. Poor (< 4 critical bones) → Manual mapping needed

Phase 2: User Confirmation

1. User reviews mapping in Blender:
2. View3D → Sidebar (N) → "Blender Toolkit" → "Bone Mapping Review"
3. Check source → target correspondence
4. Edit incorrect mappings using dropdowns

5. Use "Auto Re-map" button to regenerate if needed

6. User confirms:

7. Click "Apply Retargeting" button in Blender

8. System completes:

9. Creates constraint-based retargeting
10. Bakes animation to keyframes
11. Adds to NLA track
12. Cleans up temporary objects

Example:

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 });

Skip Confirmation (For Known-Good Mappings):

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

Key Features Auto Bone Mapping with UI Review 🌟

Recommended Workflow for unknown or custom rigs:

How It Works:

Fuzzy Matching Algorithm

Normalizes bone names (handles various conventions) Calculates similarity scores (0.0-1.0) Applies bonuses for: Substring matches (+0.15) Common prefixes: left, right (+0.1) Common suffixes: .L, .R, _l, _r (+0.1) Number matching: Spine1, Spine2 (+0.1) Anatomical keywords: arm, leg, hand (+0.05)

Quality Assessment

Tracks 9 critical bones (Hips, Spine, Head, Arms, Legs, Hands) Provides quality rating (Excellent/Good/Fair/Poor) Recommends action based on quality

UI Confirmation Panel

Shows complete mapping table Editable dropdowns for each mapping "Auto Re-map" button (regenerate) "Apply Retargeting" button (proceed)

Benefits:

Works with any rig structure No manual configuration needed User verifies before application Prevents animation errors Three Bone Mapping Modes

1. Auto Mode (Recommended) ⭐

Default: Auto-generate with UI confirmation

blender-toolkit retarget --target "Hero" --file "./Walk.fbx"

Fuzzy matching algorithm UI review workflow Best for unknown rigs

1. Rigify Mode

Preset for Rigify control rigs

blender-toolkit retarget --target "Hero" --file "./Walk.fbx" --mapping mixamo_to_rigify

Predefined Mixamo → Rigify mapping Instant application Highest accuracy for Rigify

1. Custom Mode

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

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

Full control Reusable across animations For non-standard rigs Multi-Project Support

Automatic Port Management:

Projects automatically assigned unique ports (9400-9500) Configuration persists across sessions Multiple Blender instances can run simultaneously

Configuration Storage:

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

Important Guidelines When to Ask User

Use AskUserQuestion tool if:

Character armature name is unclear Multiple rigs exist (ambiguous target) Animation FBX path not provided Blender WebSocket connection fails User needs Mixamo download guidance

DO NOT guess:

Character names File paths Rig structures Mixamo Download Process

Since Mixamo has no API, users must manually download:

Provide Instructions:

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

Wait for User:

Guide user through Mixamo.com download Get file path after download completes Then proceed with retargeting Troubleshooting "Blender is not running"

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"

"Target armature not found" Verify exact armature name (case-sensitive) Check character is in current scene Use list-objects --type ARMATURE to see available armatures "Poor quality" bone mapping Review bone names in Blender (Edit Mode) Create custom mapping for critical bones Lower similarity threshold (default: 0.6) Check rig has proper hierarchy "Twisted or inverted limbs" Check left/right bone mapping Verify bone roll in Edit Mode Review constraint axes Test with simple animation first Best Practices

🌟 Use Auto Mode with UI Confirmation

Most reliable for unknown rigs Always review critical bones (Hips, Spine, Arms, Legs) Edit incorrect mappings before applying

Test Simple Animations First

Start with Idle or Walking Verify bone mapping works correctly Check root motion (Hips bone) Then proceed to complex animations

Download Correct Format from Mixamo

Format: FBX (.fbx) Skin: Without Skin FPS: 30 fps Keyframe Reduction: None

Check Quality Before Auto-Apply

Excellent (8-9 critical) → Safe to skip confirmation Good (6-7 critical) → Quick review Fair (4-5 critical) → Thorough review Poor (< 4 critical) → Use custom mapping

Save Custom Mappings for Reuse

Document successful mappings Reuse for same character's animations Share with team members

Let System Manage Ports

Don't manually configure ports System handles multi-project conflicts Configuration persists automatically References

Detailed documentation in references/ folder:

commands-reference.md - Complete CLI command reference

All geometry, object, material, modifier commands Detailed options and examples Port management and tips

bone-mapping-guide.md - Bone matching system details

Fuzzy matching algorithm explained Quality assessment metrics Common mapping patterns (Rigify, UE4, Unity) Troubleshooting mapping issues

workflow-guide.md - Complete workflow documentation

Step-by-step retargeting workflow Mixamo download process Two-phase confirmation details Batch processing workflows Multi-project workflows

addon-api-reference.md - WebSocket API documentation

JSON-RPC protocol details All API methods and parameters Error handling Security and performance tips

When to Load References:

User needs detailed command options Troubleshooting complex issues Understanding bone mapping algorithm Setting up advanced workflows API integration requirements Output Structure .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

Notes Port range: 9400-9500 (Browser Pilot uses 9222-9322) File formats: FBX recommended, Collada (.dae) supported Blender version: 4.0+ required (2023+) Auto-initialization: SessionStart hook installs and builds scripts No manual daemon management: System handles everything WebSocket protocol: JSON-RPC 2.0