Use when exchanging 3D data between Blender and Speckle, handling mesh/curve conversion, or managing materials. Prevents attempting Linux usage (unsupported), sending cameras/lights (unsupported), and losing custom properties on receive. Covers Blender 4.2-5.0 connector (Win/Mac), mesh and curve support, 4 shader types (Principled/Diffuse/Emission/Glass), Apply Modifiers option, block loading modes, and known limitations (no Linux, no cameras/lights/textures, no custom properties on receive). Keywords: speckle blender, blender connector, mesh, curves, materials, shader, principled bsdf, publish, receive, send from Blender, Blender to Speckle.
Use when exchanging 3D data between Blender and Speckle, handling mesh/curve conversion, or managing materials. Prevents attempting Linux usage (unsupported), sending cameras/lights (unsupported), and losing custom properties on receive. Covers Blender 4.2-5.0 connector (Win/Mac), mesh and curve support, 4 shader types (Principled/Diffuse/Emission/Glass), Apply Modifiers option, block loading modes, and known limitations (no Linux, no cameras/lights/textures, no custom properties on receive). Keywords: speckle blender, blender connector, mesh, curves, materials, shader, principled bsdf, publish, receive, send from Blender, Blender to Speckle.
license
MIT
compatibility
Designed for Claude Code. Requires Blender 4.2-5.0 (Windows/Mac), Speckle Connector for Blender (latest).
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
speckle-impl-blender
Quick Reference
Platform Support
Platform
Supported
Windows
Yes
macOS
Yes
Linux
NO — NEVER use the Blender connector on Linux
Supported Blender Versions
Version
Status
Blender 4.2
Supported
Blender 4.3
Supported
Blender 4.4
Supported
Blender 4.5
Supported
Blender 5.0
Supported
Supported Geometry Types
Type
Publish
Load
Mesh objects
Yes
Yes
Bezier curves
Yes
Yes
Bezier circles
Yes
Yes
NURBS curves
Yes
Yes
NURBS circles
Yes
Yes
Cameras
NO
NO
Lights
NO
NO
Textures
NO
NO
Recognized Shader Types
Shader
Supported
Notes
Principled BSDF
Yes
Full property transfer (color, metallic, roughness, opacity)
Diffuse BSDF
Yes
Color transfer
Emission
Yes
Color and strength transfer
Glass BSDF
Yes
Color and IOR transfer
Any other shader
Fallback
Reverts to basic material attributes only
Critical Warnings
NEVER attempt to use the Blender connector on Linux. The connector supports Windows and macOS ONLY, despite Blender itself running on Linux. Installation and operation on Linux will fail.
NEVER publish cameras or lights from Blender. These object types are NOT supported by the Speckle connector and will be silently excluded from the publish operation.
NEVER expect custom properties to survive a receive operation. Properties are NOT loaded and attached to received objects in Blender. Properties are preserved in Speckle's data model and visible in the web viewer, but Blender does NOT attach them to loaded objects.
NEVER rely on texture data transferring through Speckle. Speckle does NOT support textures across ANY connector. Only material properties (color, opacity, metallic, roughness) transfer. UV mapping data does NOT survive the pipeline.
ALWAYS use one of the four supported shader types (Principled, Diffuse, Emission, Glass) for predictable material transfer. Any other shader type falls back to basic material attributes, resulting in lost material fidelity.
Publishing from Blender
What Gets Published
The Blender connector publishes visible mesh and curve objects along with their collection hierarchy. Each object carries:
Geometry data (vertices, faces, edges for meshes; control points for curves)
Material assignments (limited to the 4 supported shader types)
Collection hierarchy (Blender collections map to Speckle collections)
Object names
Apply Modifiers Setting
The connector provides an "Apply Modifiers" toggle in the publish settings:
Enabled: Objects are published with all modifiers applied (baked). The published geometry reflects the final modifier stack result.
Disabled: Objects are published in their base state, WITHOUT modifier effects.
ALWAYS enable "Apply Modifiers" when the downstream consumer needs the final visual geometry (e.g., sending to Revit, viewer, or Power BI). Disable it ONLY when the base geometry is intentionally needed.
Publishing Workflow
Select the Speckle project and model in the connector panel
The connector converts visible objects to Speckle format and sends them to the server
What Does NOT Get Published
Cameras — silently excluded
Lights — silently excluded
Textures — NOT supported by Speckle
Armatures and animation data — NOT supported
Particle systems — NOT supported (unless baked to mesh via Apply Modifiers)
Loading into Blender
Block Loading Modes
When receiving models that contain block instances (e.g., from Revit families, Rhino blocks, AutoCAD blocks), the Blender connector offers two loading modes:
Mode
Behavior
Use Case
Collection Instances (default)
Block definitions become Blender collections; instances reference those collections
Memory-efficient for models with many repeated elements
Linked Duplicates
Block instances are created as linked duplicate objects
When individual instance editing is needed
Material Persistence
Material modifications made in Blender persist across version updates. When loading a new version of a model:
Existing materials with matching names are reused
Manual material edits (color changes, shader adjustments) survive the update
New materials from the updated model are added alongside existing ones
Version Selection
The connector loads the latest version by default
Specific versions are selectable through the connector panel version history
What Loads Successfully
Mesh geometry with faces, edges, vertices
Curve geometry (Bezier and NURBS)
Material assignments (4 shader types)
Collection hierarchy from the source application
Object names
What Does NOT Load
Custom properties — properties are NOT loaded and attached to loaded objects
Cameras — NOT supported
Lights — NOT supported
Textures — NOT supported
Material Handling
Shader Mapping on Publish
The connector inspects each Blender material's shader node tree. It recognizes EXACTLY four shader types:
Principled BSDF: Maps Base Color, Metallic, Roughness, Alpha to Speckle RenderMaterial properties
Diffuse BSDF: Maps Color to Speckle RenderMaterial
Emission: Maps Color and Strength to Speckle RenderMaterial
Glass BSDF: Maps Color and IOR to Speckle RenderMaterial
For ANY other shader type, the connector falls back to basic material attributes (typically just the viewport display color).
Shader Mapping on Load
When loading models from other applications, Speckle RenderMaterial properties map to Blender's Principled BSDF shader:
Speckle Property
Blender Principled BSDF Input
diffuse (RGB)
Base Color
opacity
Alpha
metalness
Metallic
roughness
Roughness
Material Round-Trip Behavior
Blender → Speckle → Blender: Materials survive if using supported shader types
Other App → Speckle → Blender: Materials load as Principled BSDF with mapped properties
Blender → Speckle → Other App: Material fidelity depends on the receiving connector's capabilities
Data Schema
Object Types Produced
The Blender connector produces Geometry Objects (not DataObjects). Published objects are pure geometric primitives:
Blender collections map directly to Speckle collections, preserving the organizational structure:
Blender Scene Collection
├── Building
│ ├── Walls (mesh objects)
│ └── Floors (mesh objects)
└── Site
└── Terrain (mesh objects)
Becomes in Speckle:
Root Collection
├── Building
│ ├── Walls
│ └── Floors
└── Site
└── Terrain
Proxy Types
The Blender connector uses the RenderMaterial proxy type to share material definitions across multiple objects. A single RenderMaterial proxy can reference many mesh objects that share the same material.
Cross-Application Workflows
Receiving Revit Models in Blender
When loading a Revit model into Blender:
Revit elements arrive as mesh geometry organized by the Revit hierarchy (Level > Category > Type)
Materials map to Principled BSDF shaders
Revit parameters are visible in the Speckle web viewer but are NOT attached to Blender objects
Block instances (Revit families) load based on the selected block loading mode
Receiving Rhino Models in Blender
When loading a Rhino model into Blender:
Rhino geometry arrives as meshes and curves
Rhino layers map to Blender collections
Render materials transfer to Principled BSDF
Block definitions load based on the selected block loading mode
Publishing Blender Models to Other Applications
When publishing from Blender for use in other applications:
ALWAYS enable Apply Modifiers if the receiving application needs final geometry
ALWAYS use supported shader types for material transfer
Receiving applications will see mesh/curve geometry with basic material properties
The Blender collection hierarchy is preserved as Speckle collections
Limitations Summary
Limitation
Severity
Detail
No Linux support
Critical
Windows and macOS ONLY
No cameras
High
Cameras are silently excluded on publish and not created on load
No lights
High
Lights are silently excluded on publish and not created on load
No textures
High
Speckle does not support textures across any connector
No custom properties on receive
High
Properties visible in web viewer but NOT attached in Blender
Only 4 shader types
Medium
Other shaders fall back to basic material attributes
