zhongwei/gh-dev-gom-claude-code-marketplace-plugins-blender-toolkit

Fork 0

Files

Zhongwei Li d80558b1cf Initial commit

2025-11-29 18:18:51 +08:00

20 KiB

Raw Permalink Blame History

Addon API Reference

Complete reference for Blender Toolkit Python Addon WebSocket API.

Overview
WebSocket Protocol
Command Categories
Geometry API
Object API
Material API
Collection API
Armature API
Animation API
Bone Mapping API
Retargeting API
Modifier API
Import API
Error Handling

Overview

The Blender Toolkit addon provides a WebSocket-based JSON-RPC API for controlling Blender programmatically.

Key Features:

Real-time Blender control via WebSocket
JSON-RPC 2.0 protocol
Comprehensive API coverage
Type-safe commands
Error reporting
Security validation

Architecture:

Client (TypeScript)     WebSocket      Blender Addon (Python)
─────────────────────   ─────────      ──────────────────────
BlenderClient.sendCommand()  ──────►   Command Handler
    {                                   │
      method: "Geometry.createCube",    │
      params: {...}                     ▼
    }                               Execute Command
                                        │
Response ◄──────────────────────────────┘
    {
      result: {...},
      error: null
    }

WebSocket Protocol

Connection

Endpoint:

ws://localhost:9400/

Port Range: 9400-9500

Connection Example:

import { BlenderClient } from './blender/client';

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

// Send command
const result = await client.sendCommand('Geometry.createCube', {
  location: [0, 0, 0],
  size: 2.0
});

await client.disconnect();

Message Format

Request (JSON-RPC 2.0):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Geometry.createCube",
  "params": {
    "location": [0, 0, 0],
    "size": 2.0,
    "name": "MyCube"
  }
}

Response (Success):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "name": "Cube",
    "location": [0.0, 0.0, 0.0],
    "vertices": 8,
    "faces": 6
  },
  "error": null
}

Response (Error):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Object 'MyCube' not found"
  }
}

Command Categories

Category	Description	Commands
Geometry	Create and modify meshes	createCube, createSphere, subdivide, etc.
Object	Object manipulation	list, transform, duplicate, delete
Material	Material management	create, assign, setColor, etc.
Collection	Collection organization	create, addObject, removeObject
Armature	Armature operations	getBones, getBoneInfo
Animation	Animation control	import, bake, addToNLA
BoneMapping	Bone correspondence	generate, display, apply
Retargeting	Animation retargeting	Full workflow commands
Modifier	Modifier management	add, apply, toggle, modify
Import	File import	importFBX, importDAE

Geometry API

Geometry.createCube

Create a cube primitive.

Method: Geometry.createCube

Parameters:

{
  location?: [number, number, number];  // Default: [0, 0, 0]
  size?: number;                        // Default: 2.0
  name?: string;                        // Optional custom name
}

Returns:

{
  name: string;
  location: [number, number, number];
  vertices: number;
  faces: number;
}

Example:

# Blender Python equivalent
import bpy
bpy.ops.mesh.primitive_cube_add(
    size=2.0,
    location=(0, 0, 0)
)

Geometry.createSphere

Create a sphere primitive.

Method: Geometry.createSphere

Parameters:

{
  location?: [number, number, number];  // Default: [0, 0, 0]
  radius?: number;                      // Default: 1.0
  segments?: number;                    // Default: 32
  ringCount?: number;                   // Default: 16
  name?: string;
}

Returns:

{
  name: string;
  location: [number, number, number];
  vertices: number;
  faces: number;
}

Geometry.createCylinder

Create a cylinder primitive.

Method: Geometry.createCylinder

Parameters:

{
  location?: [number, number, number];
  radius?: number;                      // Default: 1.0
  depth?: number;                       // Height, default: 2.0
  vertices?: number;                    // Default: 32
  name?: string;
}

Geometry.createPlane

Create a plane primitive.

Method: Geometry.createPlane

Parameters:

{
  location?: [number, number, number];
  size?: number;                        // Default: 2.0
  name?: string;
}

Geometry.createCone

Create a cone primitive.

Method: Geometry.createCone

Parameters:

{
  location?: [number, number, number];
  radius1?: number;                     // Base radius
  depth?: number;                       // Height
  vertices?: number;
  name?: string;
}

Geometry.createTorus

Create a torus primitive.

Method: Geometry.createTorus

Parameters:

{
  location?: [number, number, number];
  majorRadius?: number;                 // Default: 1.0
  minorRadius?: number;                 // Tube thickness, default: 0.25
  majorSegments?: number;               // Default: 48
  minorSegments?: number;               // Default: 12
  name?: string;
}

Geometry.subdivideMesh

Subdivide a mesh to add detail.

Method: Geometry.subdivideMesh

Parameters:

{
  name: string;                         // Object name (required)
  cuts?: number;                        // Subdivision cuts, default: 1
}

Returns:

{
  name: string;
  vertices: number;
  edges: number;
  faces: number;
}

Geometry.getVertices

Get all vertices of a mesh.

Method: Geometry.getVertices

Parameters:

{
  name: string;                         // Object name (required)
}

Returns:

Array<{
  index: number;
  co: [number, number, number];       // Coordinate
}>

Geometry.moveVertex

Move a specific vertex.

Method: Geometry.moveVertex

Parameters:

{
  objectName: string;
  vertexIndex: number;
  newPosition: [number, number, number];
}

Returns:

{
  object: string;
  vertex_index: number;
  position: [number, number, number];
}

Object API

Object.list

List all objects in the scene.

Method: Object.list

Parameters:

{
  type?: string;                        // Filter: MESH, ARMATURE, CAMERA, LIGHT
}

Returns:

Array<{
  name: string;
  type: string;
  location: [number, number, number];
  rotation: [number, number, number];
  scale: [number, number, number];
}>

Object.transform

Transform an object (move, rotate, scale).

Method: Object.transform

Parameters:

{
  name: string;                         // Object name (required)
  location?: [number, number, number];
  rotation?: [number, number, number];  // Radians
  scale?: [number, number, number];
}

Returns:

{
  name: string;
  location: [number, number, number];
  rotation: [number, number, number];
  scale: [number, number, number];
}

Object.duplicate

Duplicate an object.

Method: Object.duplicate

Parameters:

{
  name: string;                         // Source object (required)
  newName?: string;
  location?: [number, number, number];
}

Returns:

{
  name: string;                         // New object name
  type: string;
  location: [number, number, number];
}

Object.delete

Delete an object.

Method: Object.delete

Parameters:

{
  name: string;                         // Object name (required)
}

Returns:

{
  message: string;                      // "Object 'X' deleted successfully"
}

Material API

Material.create

Create a new material.

Method: Material.create

Parameters:

{
  name: string;                         // Material name (required)
  useNodes?: boolean;                   // Default: true
}

Returns:

{
  name: string;
  use_nodes: boolean;
}

Material.list

List all materials.

Method: Material.list

Parameters: {}

Returns:

Array<{
  name: string;
  use_nodes: boolean;
}>

Material.delete

Delete a material.

Method: Material.delete

Parameters:

{
  name: string;                         // Material name (required)
}

Material.assign

Assign material to object.

Method: Material.assign

Parameters:

{
  objectName: string;                   // Object name (required)
  materialName: string;                 // Material name (required)
  slotIndex?: number;                   // Default: 0
}

Returns:

{
  object: string;
  material: string;
  slot: number;
}

Material.listObjectMaterials

List materials on an object.

Method: Material.listObjectMaterials

Parameters:

{
  objectName: string;                   // Object name (required)
}

Returns:

Array<{
  slot: number;
  material: string | null;
}>

Material.setBaseColor

Set material base color.

Method: Material.setBaseColor

Parameters:

{
  materialName: string;                 // Material name (required)
  color: [number, number, number, number]; // RGBA (0-1)
}

Returns:

{
  material: string;
  base_color: [number, number, number, number];
}

Material.setMetallic

Set metallic value.

Method: Material.setMetallic

Parameters:

{
  materialName: string;
  metallic: number;                     // 0.0 - 1.0
}

Material.setRoughness

Set roughness value.

Method: Material.setRoughness

Parameters:

{
  materialName: string;
  roughness: number;                    // 0.0 - 1.0
}

Material.setEmission

Set emission color and strength.

Method: Material.setEmission

Parameters:

{
  materialName: string;
  color: [number, number, number, number];
  strength?: number;                    // Default: 1.0
}

Material.getProperties

Get all material properties.

Method: Material.getProperties

Parameters:

{
  materialName: string;
}

Returns:

{
  name: string;
  use_nodes: boolean;
  base_color?: [number, number, number, number];
  metallic?: number;
  roughness?: number;
  // ... other properties
}

Collection API

Collection.create

Create a new collection.

Method: Collection.create

Parameters:

{
  name: string;                         // Collection name (required)
}

Collection.list

List all collections.

Method: Collection.list

Parameters: {}

Returns:

Array<{
  name: string;
  objects: number;                      // Count of objects
}>

Collection.addObject

Add object to collection.

Method: Collection.addObject

Parameters:

{
  objectName: string;
  collectionName: string;
}

Collection.removeObject

Remove object from collection.

Method: Collection.removeObject

Parameters:

{
  objectName: string;
  collectionName: string;
}

Collection.delete

Delete a collection.

Method: Collection.delete

Parameters:

{
  name: string;
}

Armature API

Armature.getBones

Get all bones in an armature.

Method: Armature.getBones

Parameters:

{
  armatureName: string;
}

Returns:

Array<string>                           // Bone names

Armature.getBoneInfo

Get detailed bone information.

Method: Armature.getBoneInfo

Parameters:

{
  armatureName: string;
  boneName: string;
}

Returns:

{
  name: string;
  head: [number, number, number];
  tail: [number, number, number];
  parent: string | null;
  children: string[];
}

Animation API

Animation.import

Import animation from FBX.

Method: Animation.import

Parameters:

{
  filePath: string;
  removeNamespace?: boolean;            // Default: true
}

Returns:

{
  imported: string;                     // Armature name
  frames: number;
}

Animation.bake

Bake animation to keyframes.

Method: Animation.bake

Parameters:

{
  armatureName: string;
  startFrame: number;
  endFrame: number;
}

Animation.addToNLA

Add animation to NLA track.

Method: Animation.addToNLA

Parameters:

{
  armatureName: string;
  trackName: string;
  actionName: string;
}

Bone Mapping API

BoneMapping.generate

Generate automatic bone mapping.

Method: BoneMapping.generate

Parameters:

{
  sourceArmature: string;
  targetArmature: string;
  threshold?: number;                   // Default: 0.6
}

Returns:

{
  mapping: Record<string, string>;      // source -> target
  quality: {
    total_mappings: number;
    critical_bones_mapped: string;      // "8/9"
    quality: string;                    // excellent/good/fair/poor
    summary: string;
  };
}

BoneMapping.display

Display mapping in Blender UI.

Method: BoneMapping.display

Parameters:

{
  sourceArmature: string;
  targetArmature: string;
  mapping: Record<string, string>;
  quality: object;
}

Effect:

Creates UI panel in View3D sidebar
Shows mapping table
Allows user editing
Provides "Apply" button

BoneMapping.getUserConfirmation

Wait for user confirmation.

Method: BoneMapping.getUserConfirmation

Parameters: {}

Returns:

{
  confirmed: boolean;
  mapping: Record<string, string>;      // Updated mapping
}

Behavior:

Blocks until user clicks "Apply Retargeting"
Returns updated mapping (after user edits)

Retargeting API

Retargeting.apply

Apply retargeting with constraints.

Method: Retargeting.apply

Parameters:

{
  sourceArmature: string;
  targetArmature: string;
  mapping: Record<string, string>;
  startFrame: number;
  endFrame: number;
}

Process:

Creates Copy Rotation constraints
Sets constraint targets
Bakes animation to keyframes
Removes constraints
Cleans up

Returns:

{
  success: boolean;
  frames_baked: number;
}

Retargeting.cleanup

Clean up temporary objects.

Method: Retargeting.cleanup

Parameters:

{
  sourceArmature: string;
}

Effect:

Removes imported Mixamo armature
Cleans up temporary data

Modifier API

Modifier.add

Add a modifier to object.

Method: Modifier.add

Parameters:

{
  objectName: string;
  modifierType: string;                 // SUBSURF, MIRROR, ARRAY, etc.
  name?: string;
  properties?: Record<string, any>;
}

Modifier Types:

SUBSURF - Subdivision Surface
MIRROR - Mirror
ARRAY - Array
BEVEL - Bevel
SOLIDIFY - Solidify
BOOLEAN - Boolean
And many more...

Modifier.apply

Apply a modifier.

Method: Modifier.apply

Parameters:

{
  objectName: string;
  modifierName: string;
}

Modifier.list

List modifiers on object.

Method: Modifier.list

Parameters:

{
  objectName: string;
}

Returns:

Array<{
  name: string;
  type: string;
  show_viewport: boolean;
  show_render: boolean;
  // Type-specific properties
}>

Modifier.remove

Remove a modifier.

Method: Modifier.remove

Parameters:

{
  objectName: string;
  modifierName: string;
}

Modifier.toggle

Toggle modifier visibility.

Method: Modifier.toggle

Parameters:

{
  objectName: string;
  modifierName: string;
  viewport?: boolean;
  render?: boolean;
}

Modifier.modify

Modify modifier properties.

Method: Modifier.modify

Parameters:

{
  objectName: string;
  modifierName: string;
  properties: Record<string, any>;
}

Example Properties:

// Subdivision Surface
{
  levels: 2,
  render_levels: 3
}

// Bevel
{
  width: 0.1,
  segments: 4
}

// Array
{
  count: 5,
  relative_offset_displace: [2, 0, 0]
}

Modifier.getInfo

Get detailed modifier info.

Method: Modifier.getInfo

Parameters:

{
  objectName: string;
  modifierName: string;
}

Modifier.reorder

Reorder modifier in stack.

Method: Modifier.reorder

Parameters:

{
  objectName: string;
  modifierName: string;
  direction: 'UP' | 'DOWN';
}

Import API

Import.importFBX

Import FBX file.

Method: Import.importFBX

Parameters:

{
  filePath: string;
  useImageSearch?: boolean;
  globalScale?: number;
  applyTransform?: boolean;
  removeNamespace?: boolean;
}

Import.importDAE

Import Collada (DAE) file.

Method: Import.importDAE

Parameters:

{
  filePath: string;
  fixOrientation?: boolean;
  importUnits?: boolean;
}

Error Handling

Error Codes

Standard JSON-RPC error codes:

Code	Name	Description
`-32700`	Parse error	Invalid JSON
`-32600`	Invalid Request	Invalid JSON-RPC
`-32601`	Method not found	Unknown method
`-32602`	Invalid params	Invalid parameters
`-32603`	Internal error	Server error

Custom Error Codes

Code	Name	Description
`1001`	Object not found	Specified object doesn't exist
`1002`	Invalid operation	Operation not allowed
`1003`	File error	File not found or unreadable
`1004`	Validation error	Parameter validation failed

Error Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null,
  "error": {
    "code": 1001,
    "message": "Object not found",
    "data": {
      "object_name": "NonExistent",
      "details": "No object named 'NonExistent' in scene"
    }
  }
}

Error Handling in Client

try {
  const result = await client.sendCommand('Object.transform', {
    name: 'NonExistent'
  });
} catch (error) {
  if (error.code === 1001) {
    console.error('Object not found:', error.data.object_name);
  } else {
    console.error('Error:', error.message);
  }
}

Security

Input Validation

All commands validate inputs:

Type checking
Range validation
Path sanitization
Object existence verification

Path Security

File paths are validated to prevent:

Directory traversal (../../../)
Absolute path exploits
Symbolic link attacks

Command Whitelist

Only registered commands are allowed:

No arbitrary Python code execution
No system commands
No file system write access (except designated dirs)

Performance Tips

Batch Commands: Group related operations
Reuse Connections: Don't reconnect for each command
Use Appropriate Timeouts: Long operations need longer timeouts
Cache Data: Store repeated query results
Minimize Data Transfer: Only request needed data

20 KiB Raw Permalink Blame History

Addon API Reference

Table of Contents

Overview

WebSocket Protocol

Connection

Message Format

Command Categories

Geometry API

Geometry.createCube

Geometry.createSphere

Geometry.createCylinder

Geometry.createPlane

Geometry.createCone

Geometry.createTorus

Geometry.subdivideMesh

Geometry.getVertices

Geometry.moveVertex

Object API

Object.list

Object.transform

Object.duplicate

Object.delete

Material API

Material.create

Material.list

Material.delete

Material.assign

Material.listObjectMaterials

Material.setBaseColor

Material.setMetallic

Material.setRoughness

Material.setEmission

Material.getProperties

Collection API

Collection.create

Collection.list

Collection.addObject

Collection.removeObject

Collection.delete

Armature API

Armature.getBones

Armature.getBoneInfo

Animation API

Animation.import

Animation.bake

Animation.addToNLA

Bone Mapping API

BoneMapping.generate

BoneMapping.display

BoneMapping.getUserConfirmation

Retargeting API

Retargeting.apply

Retargeting.cleanup

Modifier API

Modifier.add

Modifier.apply

Modifier.list

Modifier.remove

Modifier.toggle

Modifier.modify

Modifier.getInfo

Modifier.reorder

Import API

Import.importFBX

Import.importDAE

Error Handling

Error Codes

Custom Error Codes

Error Response Format

Error Handling in Client

Security

Input Validation

Path Security

Command Whitelist

Performance Tips

20 KiB

Raw Permalink Blame History