blender-toolkit

⚠️ 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:

1. Install Blender 4.0+ from https://www.blender.org
2. Restart Claude Code session to trigger auto-detection
3. 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:

1. Open config file (path shown above)
2. Edit blenderExecutable field to your preferred version path
3. 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"
}

3. 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:

1. Open 3D View → Sidebar (press N key)
2. Find "Blender Toolkit" tab
3. Click "Start Server" button
4. 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`);

2. Material Assignment Workflow

Steps:

1. Create material
2. Assign to object
3. 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"

3. Animation Retargeting Workflow ⭐

Most Common Use Case

Phase 1: Setup & Generate Mapping

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

Phase 2: User Confirmation

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

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',        

---

*Content truncated.*