Blender

ディレクトリ構成

skills/blender/
  SKILL.md
  references/
    python-api-core/
      README.md
      bpy-data.md
      bpy-context.md
      bpy-ops.md
      bpy-types.md
      bpy-props.md
      bpy-utils.md
      bpy-app.md
      bpy-info.md
    python-api-modules/
      README.md
      bmesh.md
      mathutils.md
      gpu.md
      bpy-extras.md
      other-modules.md
    modeling/
      README.md
      mesh-basics.md
      modifiers.md
      geometry-nodes.md
      curves-surfaces.md
      sculpting.md
    scripting/
      README.md
      headless-cli.md
      addon-development.md
      text-editor.md
      extending.md
    animation-rigging/
      README.md
      keyframes.md
      drivers.md
      constraints.md
      armatures.md
      shape-keys.md
      actions-nla.md
    rendering-shading/
      README.md
      cycles.md
      eevee.md
      materials-nodes.md
      lighting.md
      render-output.md
      freestyle.md
    physics/
      README.md
      rigid-body.md
      cloth.md
      soft-body.md
      particles.md
      fluid.md
      collision-forces.md
    compositing/
      README.md
      compositor-nodes.md
      render-passes.md
      common-setups.md
    scene-objects/
      README.md
      objects-transform.md
      collections.md
      empties-cameras-lights.md
      data-system.md
      world-scene.md
  samples/
    README.md
    object-creation.md
    bmesh-editing.md
    modifier-workflow.md
    material-shading.md
    headless-render.md
    scene-management.md
    addon-template.md
    animation-keyframes.md
    rigging-armature.md
    physics-simulation.md
    rendering-setup.md
    compositing-nodes.md
  scripts/
    README.md
    cli-commands.md
    addon-lifecycle.md
    python-environment.md

探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す 2. そのカテゴリの README.md を参照して目的のページを特定する 3. 該当ページの .md を Read して詳細を確認する

タスク → カテゴリ マッピング

Actions & NLA

An Action is a named data-block that stores F-Curves (keyframe animation) for one object or one armature pose. The NLA Editor (Non-Linear Animation) layers and blends multiple Actions as reusable strips.

Overview

Object.animation_data
  ├─ action           ← currently active Action (editable in Graph/Dope Sheet)
  └─ nla_tracks[]
       └─ strips[]    ← each strip references an Action and a frame range

An Action becomes a reusable clip once pushed down to the NLA stack.

Key Operations

Create and assign an Action manually

import bpy

obj = bpy.context.object
anim = obj.animation_data_create()

action = bpy.data.actions.new(name="Walk")
anim.action = action

# Add keyframes to the active action as usual
obj.location = (0, 0, 0)
obj.keyframe_insert("location", frame=1)
obj.location = (5, 0, 0)
obj.keyframe_insert("location", frame=24)

Push action down to NLA (operator)

# Object must be active and have an action assigned
bpy.context.view_layer.objects.active = obj
bpy.ops.nla.action_pushdown(track_index=0)

After push-down, obj.animation_data.action becomes None and a new NLA strip is created.

Add an NLA strip via data API

anim = obj.animation_data_create()
track = anim.nla_tracks.new()
track.name = "Walk Track"

walk_action = bpy.data.actions["Walk"]
strip = track.strips.new(name="Walk", start=1, action=walk_action)

strip.action_frame_start = 1
strip.action_frame_end   = 24
strip.frame_start        = 1
strip.frame_end          = 24
strip.blend_type         = 'REPLACE'   # or 'ADD', 'COMBINE', 'SUBTRACT', 'MULTIPLY'
strip.influence          = 1.0
strip.extrapolation      = 'HOLD'      # 'NOTHING' | 'HOLD' | 'HOLD_FORWARD'

Blend two actions additively

base_track = anim.nla_tracks.new()
base_strip = base_track.strips.new("Idle", 1, bpy.data.actions["Idle"])
base_strip.blend_type = 'REPLACE'

add_track = anim.nla_tracks.new()
add_strip = add_track.strips.new("Breathe", 1, bpy.data.actions["Breathe"])
add_strip.blend_type = 'ADD'
add_strip.influence = 0.5

Iterate all actions in the file

for action in bpy.data.actions:
    print(action.name, len(action.fcurves))

Remove an NLA strip

track = anim.nla_tracks["Walk Track"]
strip = track.strips["Walk"]
track.strips.remove(strip)

Options / Props

Notes

• While AnimData.action is set (i.e., the active action is not pushed down), the NLA tracks are in a "tweaking" state and NLA evaluation may be bypassed for that object.
• bpy.ops.nla.action_pushdown() requires an active object with a non-None action and an NLA Editor area in the UI context; prefer the data API (track.strips.new()) in headless scripts.
• Actions are shared data-blocks: multiple objects can reference the same Action. Use action.copy() before modifying if independent copies are needed.
• COMBINE blend type handles additive vs. multiplicative blending automatically per channel type (e.g., quaternion rotations blend with quaternion math).

Related

• keyframes.md
• drivers.md
• shape-keys.md

Armatures

An Armature is a skeleton-like object consisting of Bones. It deforms meshes (via the Armature Modifier) and stores pose animation data. Blender uses three distinct bone data structures depending on the active mode.

Overview

Critical: Do not hold references to EditBone objects after leaving Edit Mode — this crashes Blender.

Key Operations

Create an armature and add bones

import bpy
from mathutils import Vector

# Create armature data-block and object
arm_data = bpy.data.armatures.new("MyArmature")
arm_obj  = bpy.data.objects.new("MyArmature", arm_data)
bpy.context.collection.objects.link(arm_obj)

# Activate and enter Edit Mode
bpy.context.view_layer.objects.active = arm_obj
bpy.ops.object.mode_set(mode='EDIT')

# Add bones
root = arm_obj.data.edit_bones.new("Root")
root.head = Vector((0, 0, 0))
root.tail = Vector((0, 0, 1))

child = arm_obj.data.edit_bones.new("Child")
child.head = Vector((0, 0, 1))
child.tail = Vector((0, 0, 2))
child.parent = root
child.use_connect = True   # connect child head to parent tail

bpy.ops.object.mode_set(mode='OBJECT')
# -- Do NOT use root/child references after this line --

Access pose bones and transform

bpy.ops.object.mode_set(mode='POSE')
pb = arm_obj.pose.bones["Child"]
pb.location = (0.1, 0, 0)
pb.rotation_mode = 'XYZ'
pb.rotation_euler = (0.2, 0, 0)

Add an IK constraint via Python

import math
bpy.ops.object.mode_set(mode='POSE')

hand_pb = arm_obj.pose.bones["Hand"]
ik = hand_pb.constraints.new(type='IK')
ik.target      = arm_obj
ik.subtarget   = "IK_Target"
ik.chain_count = 3
ik.pole_target    = arm_obj
ik.pole_subtarget = "Pole"
ik.pole_angle     = math.radians(90)

Parent a mesh to the armature with automatic weights

mesh_obj = bpy.data.objects["Body"]
mesh_obj.parent = arm_obj
mod = mesh_obj.modifiers.new(name="Armature", type='ARMATURE')
mod.object = arm_obj
mod.use_vertex_groups = True
# Then use Weight Paint mode or bpy.ops.object.parent_set(type='ARMATURE_AUTO')

Inspect bone names and hierarchy

for bone in arm_obj.data.bones:
    parent_name = bone.parent.name if bone.parent else "None"
    print(f"{bone.name} -> parent: {parent_name}, deform: {bone.use_deform}")

Options / Props

Notes

• Mode switching is required: edit bones are only available in Edit Mode; pose data is only actionable in Pose Mode.
• Always call bpy.ops.object.mode_set(mode='OBJECT') to finalize edits before accessing obj.data.bones or obj.pose.bones.
• The Armature Modifier on a mesh uses vertex groups whose names match bone names to drive deformation weights.
• For programmatic weight painting, set vertex group weights via mesh_obj.vertex_groups["BoneName"].add([vert_index], weight, 'REPLACE').
• B-Bones (Bendy Bones) add curvature along a single bone; controlled via EditBone.bbone_segments, .bbone_x, .bbone_z.

Related

• constraints.md
• shape-keys.md
• keyframes.md

Constraints

Constraints restrict or direct an object's (or bone's) transformations based on rules or targets. They are evaluated every frame and do not bake data unless explicitly applied.

Overview

Constraints live in object.constraints (object-level) or pose_bone.constraints (bone-level). Both collections expose the same .new() / .remove() interface.

Key Operations

Add a constraint

import bpy

obj = bpy.data.objects["Cube"]

# Copy the location of a target object
c = obj.constraints.new(type='COPY_LOCATION')
c.target = bpy.data.objects["Empty"]
c.use_offset = True
c.influence = 1.0

Add a constraint to a pose bone

arm_obj = bpy.data.objects["Armature"]
pb = arm_obj.pose.bones["Hand"]

ik = pb.constraints.new(type='IK')
ik.target = arm_obj
ik.subtarget = "IK_Target"   # name of a bone in the same armature
ik.chain_count = 3            # 0 = full chain to root
ik.pole_target = arm_obj
ik.pole_subtarget = "Pole"
ik.pole_angle = 1.5708        # radians (90°)

Remove a constraint

c = obj.constraints["Copy Location"]
obj.constraints.remove(c)

Iterate constraints

for c in obj.constraints:
    print(c.name, c.type, c.influence)

Common Constraint Types

Options / Props (common to all constraints)

Notes

• Constraints are evaluated in list order (top to bottom); use obj.constraints.move(from_index, to_index) to reorder.
• The IK constraint requires Pose Mode and only works on pose bones, not regular objects.
• CHILD_OF has a set_inverse_pending property; call bpy.ops.constraint.childof_set_inverse(...) after setting the target to compute the offset correctly.
• influence is animatable — keyframe it to blend a constraint in/out over time.

Related

• armatures.md
• keyframes.md
• drivers.md

Drivers

A Driver is a special F-Curve that computes its value from a Python expression or from another property, rather than from manually placed keyframe points. Drivers enable procedural relationships between object properties.

Overview

Drivers are stored as F-Curves in object.animation_data.drivers (not in an Action). Each driver has a driver sub-object (Driver) that holds the expression and variables.

Key Operations

Add a driver with a simple expression

import bpy

obj = bpy.context.object

# Drive Z location with a sine wave
fc = obj.driver_add("location", 2)          # index 2 = Z axis
fc.driver.type = 'SCRIPTED'
fc.driver.expression = "sin(frame / 10)"

driver_add(data_path, index=-1) returns an FCurve whose .driver is the Driver object.

Add a variable referencing another property

fc = obj.driver_add("location", 2)
drv = fc.driver
drv.type = 'SCRIPTED'

var = drv.variables.new()
var.name = "my_x"
var.type = 'SINGLE_PROP'
var.targets[0].id_type = 'OBJECT'
var.targets[0].id = bpy.data.objects["ControlObject"]
var.targets[0].data_path = "location[0]"

drv.expression = "my_x * 2"

Use TRANSFORMS variable type

var = drv.variables.new()
var.name = "rot"
var.type = 'TRANSFORMS'
tgt = var.targets[0]
tgt.id = bpy.data.objects["Ctrl"]
tgt.transform_type = 'ROT_Z'           # LOC_X/Y/Z, ROT_X/Y/Z, SCALE_X/Y/Z
tgt.transform_space = 'LOCAL_SPACE'    # WORLD_SPACE | LOCAL_SPACE

Extend the driver namespace with a custom function

def smooth_step(x):
    return x * x * (3 - 2 * x)

bpy.app.driver_namespace["smooth_step"] = smooth_step
# Expression can now use: smooth_step(var)

Register the namespace extension via a load_post handler so it persists across file loads.

Remove a driver

obj.driver_remove("location", 2)

Iterate existing drivers

for fc in obj.animation_data.drivers:
    print(fc.data_path, fc.array_index, fc.driver.expression)

Options / Props

Notes

• Security: By default, Blender blocks Python driver execution. Enable Edit → Preferences → Save & Load → Auto Run Python Scripts (or run Blender with --enable-autoexec) for scripted expressions to evaluate.
• Simple math expressions (no function calls) are optimized and run without the Python interpreter overhead.
• Drivers are re-evaluated every frame; avoid expensive computations in expressions.
• use_self (drv.use_self = True) makes self available in the expression, referencing the object that owns the driver.

Related

• keyframes.md
• actions-nla.md
• shape-keys.md

Keyframes

A keyframe stores the value of a property at a specific point in time. Blender interpolates between keyframes on an F-Curve to produce smooth animation.

Overview

Animation data is organized in a hierarchy:

Object.animation_data → Action → FCurves → Keyframe points

Each F-Curve (FCurve) represents one channel of one property (e.g., location[0] = X position).

Key Operations

Insert a keyframe

import bpy

obj = bpy.context.object
bpy.context.scene.frame_set(1)
obj.location = (0, 0, 0)
obj.keyframe_insert(data_path="location", frame=1)

obj.location = (2, 0, 0)
obj.keyframe_insert(data_path="location", frame=24)

data_path accepts any animatable property path (e.g., "rotation_euler", "scale", "["my_prop"]"). The optional index parameter targets a specific axis (0=X, 1=Y, 2=Z); omit it to key all axes.

Delete a keyframe

obj.keyframe_delete(data_path="location", frame=24)

Low-level F-Curve creation

anim = obj.animation_data_create()
action = bpy.data.actions.new(name="MyAction")
anim.action = action

fc = action.fcurves.new(data_path="location", index=0)  # X axis
fc.keyframe_points.insert(frame=1,  value=0.0)
fc.keyframe_points.insert(frame=24, value=2.0)
fc.update()

Access existing F-Curves

action = obj.animation_data.action
for fc in action.fcurves:
    print(fc.data_path, fc.array_index)
    for kp in fc.keyframe_points:
        print(f"  frame={kp.co[0]:.1f}  value={kp.co[1]:.4f}  interp={kp.interpolation}")

Set interpolation mode

for fc in obj.animation_data.action.fcurves:
    for kp in fc.keyframe_points:
        kp.interpolation = 'BEZIER'   # 'CONSTANT' | 'LINEAR' | 'BEZIER'
        kp.easing = 'AUTO'            # 'AUTO' | 'EASE_IN' | 'EASE_OUT' | 'EASE_IN_OUT'

Evaluate an F-Curve at a frame

fc = obj.animation_data.action.fcurves.find("location", index=0)
value_at_frame_10 = fc.evaluate(10)

Options / Props

Notes

• Always call fc.update() after inserting points manually to rebuild the curve handles.
• keyframe_insert() reads the property's current value at the current frame unless frame is given explicitly.
• The Graph Editor and Dope Sheet are the UI counterparts; they visualize the same Action / FCurve data.
• Easing types (SINE, QUAD, CUBIC, BACK, BOUNCE, ELASTIC, …) apply additional easing to BEZIER interpolation.

Related

• actions-nla.md
• drivers.md
• shape-keys.md

Animation & Rigging — Index

Shape Keys

Shape Keys (also called morph targets or blend shapes) store per-vertex position offsets relative to a Basis shape. They are commonly used for facial animation and corrective shapes.

Overview

Shape key data lives on obj.data.shape_keys (a Key data-block). Each individual shape is a ShapeKey accessible via key_blocks.

Object.data.shape_keys (Key)
  └─ key_blocks[0]  ← "Basis"   (reference shape)
  └─ key_blocks[1]  ← "Smile"   (relative shape)
  └─ key_blocks[2]  ← "Angry"

Key Operations

Add shape keys

import bpy

obj = bpy.data.objects["Head"]
bpy.context.view_layer.objects.active = obj

# First call creates the Basis key
bpy.ops.object.shape_key_add(from_mix=False)

# Subsequent calls add relative keys
bpy.ops.object.shape_key_add(from_mix=False)
obj.data.shape_keys.key_blocks[-1].name = "Smile"

Alternatively, use the data-level method (no operator context required):

basis = obj.shape_key_add(name="Basis")
smile = obj.shape_key_add(name="Smile", from_mix=False)

Set vertex offsets on a shape key

import bmesh

obj.active_shape_key_index = 1   # select "Smile"
bpy.ops.object.mode_set(mode='EDIT')
bm = bmesh.from_edit_mesh(obj.data)
# move a vertex
bm.verts[4].co.x += 0.5
bmesh.update_edit_mesh(obj.data)
bpy.ops.object.mode_set(mode='OBJECT')

Set value (influence slider)

sk = obj.data.shape_keys.key_blocks["Smile"]
sk.value = 0.75    # 0.0 = no influence, 1.0 = full influence

Animate value with keyframes

sk = obj.data.shape_keys.key_blocks["Smile"]
sk.value = 0.0
sk.keyframe_insert(data_path="value", frame=1)
sk.value = 1.0
sk.keyframe_insert(data_path="value", frame=20)

Assign a vertex group (masked blend)

sk = obj.data.shape_keys.key_blocks["Smile"]
sk.vertex_group = "LeftFace"   # only vertices in this group are affected

Drive a shape key from a bone rotation

sk = obj.data.shape_keys.key_blocks["Smile"]
fc = sk.driver_add("value")
drv = fc.driver
drv.type = 'SCRIPTED'

var = drv.variables.new()
var.name = "rot"
var.type = 'TRANSFORMS'
var.targets[0].id = bpy.data.objects["Armature"]
var.targets[0].bone_target = "Jaw"
var.targets[0].transform_type = 'ROT_X'
var.targets[0].transform_space = 'LOCAL_SPACE'

drv.expression = "rot / 0.5"

Options / Props

Notes

• The Basis key is always key_blocks[0]. Its value is always 1.0 and cannot be changed.
• Modifying the Basis key vertex positions in Object Mode (via basis.data[i].co) can desync from the mesh; prefer Edit Mode edits.
• Shape keys only exist on mesh, lattice, curve, and surface objects.
• To remove a shape key: obj.active_shape_key_index = idx; bpy.ops.object.shape_key_remove().
• Shape key animation integrates with the NLA via the Action stored on obj.data.shape_keys.animation_data.

Related

• keyframes.md
• drivers.md
• armatures.md

Common Compositing Setups

Practical node graph patterns for the most frequent compositing tasks in Blender. Each section includes an equivalent Python construction.

Overview

All setups use the canonical helpers defined in compositor-nodes.md. Copy both functions (get_compositor_tree and add_output_node) into your script before using any setup below.

import bpy

scene = bpy.context.scene
tree, links = get_compositor_tree(scene)
nodes = tree.nodes
nodes.clear()  # remove any existing nodes; rebuild explicitly

After nodes.clear(), always create Render Layers and an output node explicitly — no default nodes remain.

---

Z-Depth Depth of Field (Defocus)

Uses the Z render pass to drive the Defocus node for a post-process DOF effect.

Required passes: use_pass_z = True

vl = scene.view_layers["ViewLayer"]
vl.use_pass_z = True

rl    = nodes.new("CompositorNodeRLayers"); rl.location = (0, 0); rl.scene = scene
defoc = nodes.new("CompositorNodeDefocus"); defoc.location = (300, 0)

defoc.use_zbuffer = True
defoc.f_stop      = 5.6
defoc.bokeh       = 'HEXAGON'
defoc.max_blur    = 24.0

links.new(rl.outputs["Image"], defoc.inputs["Image"])
links.new(rl.outputs["Depth"], defoc.inputs["Z"])

add_output_node(tree, defoc.outputs["Image"], location=(600, 0))

Notes: The Defocus node reads the camera's focal distance from the active scene camera. Set camera.data.dof.focus_distance to control focus depth.

---

Glare / Bloom

Adds a glow or bloom around bright regions (useful for lights, emissive surfaces).

rl    = nodes.new("CompositorNodeRLayers"); rl.location = (0, 0); rl.scene = scene
glare = nodes.new("CompositorNodeGlare");   glare.location = (300, 0)

glare.glare_type = 'FOG_GLOW'   # soft bloom; use 'STREAKS' for lens streaks
glare.quality    = 'HIGH'
glare.threshold  = 0.8
glare.size       = 8             # glow radius exponent (2^size pixels)
glare.mix        = 0.0           # 0 = original + glow; 1 = glow only

links.new(rl.outputs["Image"], glare.inputs["Image"])

add_output_node(tree, glare.outputs["Image"], location=(600, 0))

---

Render Layer Compositing (Alpha Over)

Composites multiple View Layers or objects on separate layers into a single output.

rl_bg = nodes.new("CompositorNodeRLayers"); rl_bg.location = (0, 100); rl_bg.scene = scene
rl_fg = nodes.new("CompositorNodeRLayers"); rl_fg.location = (0, -100); rl_fg.scene = scene
rl_fg.layer = "ForegroundLayer"  # name of the second View Layer

alpha_over = nodes.new("CompositorNodeAlphaOver"); alpha_over.location = (350, 0)

alpha_over.premul = 0.0   # straight alpha (set >0 for premultiplied)

# Background → input 1; Foreground → input 2
links.new(rl_bg.outputs["Image"], alpha_over.inputs[1])
links.new(rl_fg.outputs["Image"], alpha_over.inputs[2])

add_output_node(tree, alpha_over.outputs["Image"], location=(600, 0))

---

Color Grading (Basic Flow)

A simple lift/gamma/gain grade followed by an RGB curves tweak.

rl      = nodes.new("CompositorNodeRLayers");     rl.location = (0, 0); rl.scene = scene
balance = nodes.new("CompositorNodeColorBalance"); balance.location = (250, 0)
curves  = nodes.new("CompositorNodeCurveRGB");    curves.location = (500, 0)

# Lift/Gamma/Gain mode (default)
balance.correction_method = 'LIFT_GAMMA_GAIN'
# Adjust via balance.lift / balance.gamma / balance.gain (Color vectors)

links.new(rl.outputs["Image"],      balance.inputs["Image"])
links.new(balance.outputs["Image"], curves.inputs["Image"])

add_output_node(tree, curves.outputs["Image"], location=(750, 0))

---

File Output Node (Multi-Pass Export)

Writes multiple passes to separate image files (e.g., EXR layers) for external compositing.

vl = scene.view_layers["ViewLayer"]
vl.use_pass_diffuse_direct = True
vl.use_pass_glossy_direct  = True
vl.use_pass_z              = True

rl      = nodes.new("CompositorNodeRLayers");    rl.location = (0, 0); rl.scene = scene
fileout = nodes.new("CompositorNodeOutputFile"); fileout.location = (400, 0)

fileout.base_path              = "/tmp/render/"
fileout.format.file_format     = 'OPEN_EXR_MULTILAYER'

# Add file slots for each pass (Blender ≤ 4.4 API)
fileout.file_slots.new("Beauty")
fileout.file_slots.new("DiffDir")
fileout.file_slots.new("GlossDir")
fileout.file_slots.new("Depth")

links.new(rl.outputs["Image"],   fileout.inputs["Beauty"])
links.new(rl.outputs["DiffDir"], fileout.inputs["DiffDir"])
links.new(rl.outputs["GlossDir"],fileout.inputs["GlossDir"])
links.new(rl.outputs["Depth"],   fileout.inputs["Depth"])

---

Denoise Setup

Denoises a Cycles render using albedo and normal auxiliary passes for best quality.

Required passes: Denoising Data (use_pass_denoising_data = True)

vl = scene.view_layers["ViewLayer"]
vl.use_pass_denoising_data = True

rl      = nodes.new("CompositorNodeRLayers"); rl.location = (0, 0); rl.scene = scene
denoise = nodes.new("CompositorNodeDenoise"); denoise.location = (300, 0)

denoise.prefilter = 'ACCURATE'
denoise.quality   = 'HIGH'
denoise.use_hdr   = True

links.new(rl.outputs["Noisy Image"],      denoise.inputs["Image"])
links.new(rl.outputs["Denoising Albedo"], denoise.inputs["Albedo"])
links.new(rl.outputs["Denoising Normal"], denoise.inputs["Normal"])

add_output_node(tree, denoise.outputs["Image"], location=(600, 0))

Notes

• Blender 5.0+: scene.use_nodes / scene.node_tree are removed. CompositorNodeComposite is also removed. All version branching is handled by get_compositor_tree() and add_output_node() — do not add if hasattr(scene, 'compositing_node_group') in individual setup scripts.
• Blender ≤ 4.4: CompositorNodeComposite is the required final output node; without it, compositing results are not applied to the render.
• File Output — Blender 5.0+: file_slots, layer_slots, and base_path were removed. Use directory, file_name, and file_output_items instead. The exact Python API for file_output_items (e.g., .new() signature and socket indexing) differs from the file_slots pattern shown above; consult the Blender 5.0 release notes for the migration guide.
• When building trees from Python, call nodes.clear() and add all required nodes explicitly to avoid stale links or duplicate nodes.
• Access Render Layers pass sockets by name (rl.outputs["Depth"]), not by index — enabled passes shift socket indices.
• Alpha Over's two image inputs are accessed as inputs[1] (Background) and inputs[2] (Foreground) in Python.
• The CompositorNodeOutputFile requires a valid base_path (Blender ≤ 4.4) or directory (Blender 5.0+); Blender will not create missing intermediate directories automatically.

Related

• compositor-nodes.md
• render-passes.md

Compositor Nodes

The Blender Compositor is a node-based post-processing system that operates on rendered images, passes, and external images to produce final output.

Overview

The compositor API changed between Blender 4.x and 5.0.

Blender ≤ 4.4: Enable with scene.use_nodes = True; access the tree via scene.node_tree.

Blender 5.0+: scene.use_nodes and the "Use Nodes" checkbox were removed. Create a CompositorNodeTree node group and assign it to scene.compositing_node_group instead.

For cross-version scripts, use these two canonical helpers. All code examples in this skill call these helpers rather than duplicating the branching logic.

import bpy

def get_compositor_tree(scene):
    """Return (tree, links) for the compositor. Idempotent across Blender 4.x / 5.0+."""
    if hasattr(scene, 'compositing_node_group'):
        # Blender 5.0+: reuse existing group to avoid orphaning datablocks
        tree = scene.compositing_node_group
        if tree is None:
            tree = bpy.data.node_groups.new("Compositor", "CompositorNodeTree")
            scene.compositing_node_group = tree
    else:
        # Blender ≤ 4.4
        scene.use_nodes = True
        tree = scene.node_tree
    return tree, tree.links


def add_output_node(tree, source_socket, location=(700, 0)):
    """Create the final output node (version-aware) and link source_socket to it."""
    scene = bpy.context.scene
    if hasattr(scene, 'compositing_node_group'):
        # Blender 5.0+: NodeGroupOutput; ensure a Color OUTPUT socket exists on the interface
        out = tree.nodes.new('NodeGroupOutput')
        if not any(
            getattr(s, 'in_out', None) == 'OUTPUT'
            for s in tree.interface.items_tree
        ):
            tree.interface.new_socket(
                name="Image", socket_type='NodeSocketColor', in_out='OUTPUT'
            )
        tree.links.new(source_socket, out.inputs[0])
    else:
        # Blender ≤ 4.4: CompositorNodeComposite
        out = tree.nodes.new('CompositorNodeComposite')
        tree.links.new(source_socket, out.inputs["Image"])
    out.location = location
    return out

Key Nodes

Input Nodes

Output Nodes

Color Nodes

Filter Nodes

Python API Mapping

Enabling and Accessing the Node Tree

Use get_compositor_tree() defined in the Overview section. It handles both versions and is idempotent — calling it again on a scene that already has a compositor tree reuses the existing group rather than creating a new orphaned datablock.

import bpy

scene = bpy.context.scene
tree, links = get_compositor_tree(scene)
nodes = tree.nodes

Adding and Connecting Nodes

# Clear any existing nodes, then build from scratch
nodes.clear()

# Always create Render Layers explicitly — never rely on default nodes after clear()
rl = nodes.new("CompositorNodeRLayers")
rl.location = (0, 0)
rl.scene = scene

# Add a Blur node
blur = nodes.new("CompositorNodeBlur")
blur.filter_type = 'GAUSS'
blur.size_x = 10
blur.size_y = 10
blur.location = (300, 0)

# Connect: Render Layers Image → Blur → output
links.new(rl.outputs["Image"], blur.inputs["Image"])

# Output node: use add_output_node() to keep version branching in one place
add_output_node(tree, blur.outputs["Image"], location=(600, 0))

Key Node Properties

CompositorNodeBlur

CompositorNodeGlare

CompositorNodeDefocus

CompositorNodeDenoise

Notes

• Version branching: Keep all 4.x / 5.0+ branching inside get_compositor_tree() and add_output_node(). Never duplicate if hasattr(scene, 'compositing_node_group') in individual scripts.
• Idempotency: get_compositor_tree() reuses an existing compositing_node_group rather than calling bpy.data.node_groups.new() every time. This prevents orphaned Compositor.001, Compositor.002 … datablocks accumulating in the blend file.
• Blender 5.0+: scene.use_nodes and scene.node_tree are removed. CompositorNodeComposite is also removed; use NodeGroupOutput instead. The node group's first Color OUTPUT interface socket drives the render result.
• Blender ≤ 4.4: CompositorNodeComposite is required; without it, compositing results are not applied to the final render.
• After `nodes.clear()`: All default nodes (Render Layers, Composite) are gone. Always recreate them explicitly with nodes.new(...).
• Use socket names (outputs["Image"]) rather than indices — enabled passes shift socket indices on the Render Layers node.
• The Denoise node works best when paired with the Denoising Albedo and Denoising Normal passes (enable via view_layer.use_pass_denoising_data).

Related

• render-passes.md
• common-setups.md

Compositing — Index

Render Passes and AOVs

Render passes split a render into individual shading components (diffuse, glossy, Z-depth, etc.) for flexible compositing. AOVs (Arbitrary Output Variables) add custom shader data as additional passes.

Overview

Passes are enabled per View Layer in the Render Properties → View Layer panel. Once enabled, they appear as output sockets on the Render Layers compositor node and are accessible in bpy.types.ViewLayer.

Standard Render Passes

Combined and Utility

Diffuse, Glossy, Transmission, Subsurface

Each light interaction type has three sub-passes:

Examples: use_pass_diffuse_direct, use_pass_glossy_color, use_pass_transmission_indirect, use_pass_subsurface_direct.

Cryptomatte Passes

Cryptomatte encodes per-pixel object/material/asset IDs for accurate mattes in compositing.

Use the Cryptomatte compositor node (CompositorNodeCryptomatteV2) to pick mattes interactively from the passes.

Custom AOVs (Arbitrary Output Variables)

AOVs let shader graphs write arbitrary color or scalar data into named render passes.

Setup Steps

1. In the View Layer properties → Passes → Shader AOVs panel, click + to add an AOV and give it a name (e.g., "MyColor"). 2. In a material shader graph, add a AOV Output node (ShaderNodeOutputAOV), set its name to match, and route a Color or Value into it. 3. After rendering, the named pass appears as an output socket on the Render Layers compositor node.

Python API Mapping

Enabling Passes

import bpy

scene = bpy.context.scene
vl = scene.view_layers["ViewLayer"]   # bpy.types.ViewLayer

# Utility passes
vl.use_pass_z            = True
vl.use_pass_normal       = True
vl.use_pass_mist         = True
vl.use_pass_ambient_occlusion = True

# Diffuse / Glossy
vl.use_pass_diffuse_direct   = True
vl.use_pass_diffuse_color    = True
vl.use_pass_glossy_direct    = True

# Emission
vl.use_pass_emit = True

# Cryptomatte
vl.use_pass_cryptomatte_object   = True
vl.use_pass_cryptomatte_material = True
vl.pass_cryptomatte_depth        = 6

Adding an AOV via Python

# Add a custom AOV named "MyColor" to the active view layer
vl = bpy.context.scene.view_layers["ViewLayer"]
aov = vl.aovs.add()
aov.name = "MyColor"
aov.type = 'COLOR'   # 'COLOR' or 'VALUE'

Accessing Pass Sockets in Compositor

Use get_compositor_tree() from compositor-nodes.md to obtain the tree in a version-safe, idempotent way. After clearing existing nodes, create a Render Layers node explicitly.

import bpy

scene = bpy.context.scene
tree, links = get_compositor_tree(scene)
nodes = tree.nodes
nodes.clear()

# Always create Render Layers explicitly — never assume default nodes exist
rl = nodes.new("CompositorNodeRLayers")
rl.scene = scene

# Access enabled pass outputs by name (not by index — enabled passes shift indices)
z_socket      = rl.outputs["Depth"]
normal_socket = rl.outputs["Normal"]
diffuse_dir   = rl.outputs["DiffDir"]
aov_socket    = rl.outputs["MyColor"]   # custom AOV

Notes

• Pass socket names on the Render Layers node match Blender UI labels, not Python property names (e.g., property use_pass_z → socket "Depth").
• Enabling many passes increases render time and memory usage.
• Cryptomatte passes require Cycles or a renderer that supports them; EEVEE support varies by version.
• AOV type must match the shader AOV Output node's data type (Color vs. Value).
• The Denoising Data passes (use_pass_denoising_data) enable Albedo and Normal inputs for the Denoise compositor node.
• Blender 5.0+: Access the compositor tree via scene.compositing_node_group instead of scene.node_tree. See compositor-nodes.md for the cross-version helper pattern.

Related

• compositor-nodes.md
• common-setups.md

Curves, Surfaces, Metaballs & Text

Blender supports several non-mesh object types for modeling: Bezier and NURBS curves/surfaces, Metaball objects, and Text objects. All can be converted to meshes via Object > Convert > Mesh.

Bezier Curves

Bezier curves are defined by control points, each with two handles that control the tangent direction and curvature on either side.

Handle Types

Key Edit Mode Operations

Curve Extrusion and Bevel

Curves can be given 3D volume via the curve data properties:

• Extrude — extends the curve profile along its normal
• Bevel Depth — adds a circular bevel profile around the curve spine
• Bevel Object — uses a custom 2D curve shape as the bevel profile

NURBS Curves and Surfaces

NURBS (Non-Uniform Rational B-Splines) use weighted control points. Blender supports NURBS curves and NURBS surface patches.

• Control point weight influences how strongly each point pulls the curve
• Order (U and V directions) controls how many points influence any given segment
• NURBS surfaces are useful for precise CAD-like shapes

Metaballs

Metaball objects are implicit surfaces defined by a scalar field. Objects in the same group blend together organically based on a shared threshold.

Element Types

Threshold controls the isosurface level (0.0–5.0). Lower values produce a smoother, larger merged surface.

Text Objects

Text objects render 3D extruded text with full control over font, size, alignment, and character spacing. Convert to mesh (Alt+C) for further polygon editing.

Key text properties: Font face, Size, Shear, Extrude depth, Bevel, Horizontal/Vertical alignment, Character spacing.

Python API Mapping

Creating a Bezier Curve

import bpy

curve_data = bpy.data.curves.new(name="MyCurve", type='CURVE')
curve_data.dimensions = '3D'

spline = curve_data.splines.new('BEZIER')
spline.bezier_points.add(2)  # adds 2 more points (total 3)

# Set control point positions and handle types
p0 = spline.bezier_points[0]
p0.co = (0, 0, 0)
p0.handle_left_type  = 'AUTO'
p0.handle_right_type = 'AUTO'

p1 = spline.bezier_points[1]
p1.co = (1, 1, 0)
p1.handle_left_type  = 'ALIGNED'
p1.handle_right_type = 'ALIGNED'

# Wrap in an object and link to scene
curve_obj = bpy.data.objects.new("MyCurveObj", curve_data)
bpy.context.collection.objects.link(curve_obj)

Curve Extrusion and Bevel via Python

import bpy

curve_data = bpy.data.curves["MyCurve"]
curve_data.extrude = 0.1          # extrusion depth
curve_data.bevel_depth = 0.05     # bevel radius
curve_data.bevel_resolution = 4   # bevel smoothness
curve_data.use_fill_caps = True   # close the ends

Creating a NURBS Curve

import bpy

curve_data = bpy.data.curves.new(name="NurbsCurve", type='CURVE')
curve_data.dimensions = '3D'

spline = curve_data.splines.new('NURBS')
spline.points.add(3)  # total 4 control points

import mathutils
spline.points[0].co = mathutils.Vector((0, 0, 0, 1))   # (x, y, z, weight)
spline.points[1].co = mathutils.Vector((1, 2, 0, 1))
spline.points[2].co = mathutils.Vector((2, 0, 0, 1))
spline.points[3].co = mathutils.Vector((3, 1, 0, 1))

spline.order_u = 4  # cubic NURBS

curve_obj = bpy.data.objects.new("NurbsObj", curve_data)
bpy.context.collection.objects.link(curve_obj)

Creating Metaballs

import bpy

# Each metaball object in the same scene family shares the same global metaball data
mball = bpy.data.metaballs.new("Meta")
mball.threshold = 0.6
mball.resolution = 0.2  # viewport resolution

# Add elements
el = mball.elements.new()
el.type = 'BALL'
el.co = (0.0, 0.0, 0.0)
el.radius = 1.0

el2 = mball.elements.new()
el2.type = 'CAPSULE'
el2.co = (1.5, 0.0, 0.0)
el2.radius = 0.8

meta_obj = bpy.data.objects.new("MetaObj", mball)
bpy.context.collection.objects.link(meta_obj)

Curve-Related Operators

import bpy

# Subdivide selected segments (in Edit Mode)
bpy.ops.curve.subdivide(number_cuts=1)

# Set all selected handle types
bpy.ops.curve.handle_type_set(type='AUTO')

# Toggle cyclic
bpy.ops.curve.cyclic_toggle()

# Convert curve to mesh
bpy.ops.object.convert(target='MESH')

Notes

• NURBS control points use 4D vectors (x, y, z, weight); weight defaults to 1.0
• Metaball objects are grouped by name prefix: e.g., Meta, Meta.001, Meta.002 all belong to the same family and blend together
• Converting a Text or Curve object to mesh (Object > Convert > Mesh) is destructive; the original curve data is replaced
• bpy.data.curves holds both Curve and Surface object data; check curve_data.type ('CURVE' vs 'SURFACE')
• Spline types available via splines.new(): 'POLY', 'BEZIER', 'BSPLINE', 'CARDINAL', 'NURBS'

Related

• Mesh Basics
• Modifiers

Geometry Nodes

Geometry Nodes is Blender's node-based procedural modeling system. A Geometry Nodes modifier holds a node tree that takes geometry as input, transforms it through connected nodes, and outputs the result.

Overview

The workflow is: 1. Add a Geometry Nodes modifier to a mesh object 2. A new node tree is created automatically with a Group Input and Group Output node 3. Connect nodes between them to build the procedural operation 4. Expose parameters via Group Input sockets to control from the modifier panel

Key Nodes

Geometry

Mesh Primitives

Instances

Fields & Attributes

Utilities

Python API Mapping

Creating a Geometry Nodes Modifier and Node Tree

import bpy

obj = bpy.context.active_object

# Add the modifier
mod = obj.modifiers.new(name="GeometryNodes", type='NODES')

# Create a new node tree (or assign an existing one)
node_tree = bpy.data.node_groups.new(name="MyGeoNodes", type='GeometryNodeTree')
mod.node_group = node_tree

Adding Nodes and Linking Them

import bpy

node_tree = bpy.data.node_groups["MyGeoNodes"]
nodes = node_tree.nodes
links = node_tree.links

# Clear default nodes if any
nodes.clear()

# Add Group Input and Output
input_node  = nodes.new("NodeGroupInput")
output_node = nodes.new("NodeGroupOutput")
input_node.location  = (-300, 0)
output_node.location = (300, 0)

# Add a Set Position node
set_pos = nodes.new("GeometryNodeSetPosition")
set_pos.location = (0, 0)

# Link: Group Input → Set Position → Group Output
links.new(input_node.outputs["Geometry"], set_pos.inputs["Geometry"])
links.new(set_pos.outputs["Geometry"], output_node.inputs["Geometry"])

Defining Group Interface Sockets (Blender 4.0+)

import bpy

node_tree = bpy.data.node_groups["MyGeoNodes"]

# Add a Geometry input socket
node_tree.interface.new_socket(
    name="Geometry",
    in_out='INPUT',
    socket_type='NodeSocketGeometry'
)

# Add a Float input for offset amount
node_tree.interface.new_socket(
    name="Offset",
    in_out='INPUT',
    socket_type='NodeSocketFloat'
)

# Add a Geometry output socket
node_tree.interface.new_socket(
    name="Geometry",
    in_out='OUTPUT',
    socket_type='NodeSocketGeometry'
)

Adding a Mesh Primitive Node

import bpy

node_tree = bpy.data.node_groups["MyGeoNodes"]
nodes = node_tree.nodes
links = node_tree.links

# Add a UV Sphere primitive
sphere = nodes.new("GeometryNodeMeshUVSphere")
sphere.inputs["Segments"].default_value = 32
sphere.inputs["Rings"].default_value = 16

# Add Join Geometry
join = nodes.new("GeometryNodeJoinGeometry")

# Connect sphere → join
links.new(sphere.outputs["Mesh"], join.inputs["Geometry"])

Notes

• In Blender 4.0+, group input/output sockets are managed via node_tree.interface.new_socket() rather than the older node_tree.inputs.new() / node_tree.outputs.new() API
• Node type identifiers (e.g., "GeometryNodeSetPosition") can be found in the Blender Python API reference or by hovering over nodes in the Info editor when adding them via the UI
• Fields (Position, Index, etc.) are evaluated lazily per-element; they are not scalar values
• The NODES modifier type (obj.modifiers.new(..., type='NODES')) is the entry point; the actual node graph lives in modifier.node_group
• Use the NodeToPython add-on to auto-generate Python code from an existing Geometry Nodes tree

Related

• Modifiers
• Mesh Basics

Mesh Basics

Blender meshes consist of vertices, edges, faces, and loops. Edit Mode exposes tools for extruding, cutting, beveling, and transforming geometry. The bmesh Python module provides low-level programmatic access to these same operations.

Overview

A mesh object's data block is made of:

• Vertex — a point in 3D space; stores position and links to its disk cycle of edges
• Edge — a connection between two vertices
• Face — a polygon (tri, quad, or n-gon) that references a loop cycle on its boundary
• Loop — the per-face-vertex element; stores per-face-vertex data (UVs, vertex colors, etc.)

Key Operations

Selection Modes

Transform

Core Editing Operations

Python API Mapping

Accessing Mesh Data (Object Mode)

import bpy

obj = bpy.context.active_object
mesh = obj.data  # bpy.types.Mesh

for v in mesh.vertices:
    print(v.index, v.co)  # position as mathutils.Vector

for e in mesh.edges:
    print(e.vertices[0], e.vertices[1])

for f in mesh.polygons:
    print(f.vertices[:])  # vertex indices of the face

Accessing Mesh Data via BMesh (Edit Mode)

import bpy, bmesh

obj = bpy.context.edit_object
bm = bmesh.from_edit_mesh(obj.data)

for v in bm.verts:
    print(v.co)
for e in bm.edges:
    print(e.verts[0].index, e.verts[1].index)
for f in bm.faces:
    print([v.index for v in f.verts])

bmesh.update_edit_mesh(obj.data)

BMesh Operations

import bpy, bmesh

obj = bpy.context.edit_object
bm = bmesh.from_edit_mesh(obj.data)

# Extrude selected faces
selected_faces = [f for f in bm.faces if f.select]
result = bmesh.ops.extrude_face_region(bm, geom=selected_faces)
bmesh.ops.translate(bm, vec=(0, 0, 1), verts=[v for v in result['geom'] if isinstance(v, bmesh.types.BMVert)])

# Inset faces
bmesh.ops.inset_region(bm, faces=selected_faces, thickness=0.1, depth=0.0)

# Bevel edges
selected_edges = [e for e in bm.edges if e.select]
bmesh.ops.bevel(bm, geom=selected_edges, offset=0.1, segments=2, affect='EDGES')

bmesh.update_edit_mesh(obj.data)

Using bpy.ops.mesh in Edit Mode

import bpy

bpy.ops.object.mode_set(mode='EDIT')

# Set selection mode
bpy.context.tool_settings.mesh_select_mode = (False, False, True)  # face select

bpy.ops.mesh.extrude_region_move(TRANSFORM_OT_translate={"value": (0, 0, 1)})
bpy.ops.mesh.inset(thickness=0.1, depth=0.0)
bpy.ops.mesh.loopcut(number_cuts=1, smoothness=0.0)
bpy.ops.mesh.bevel(offset=0.1, segments=2, affect='EDGES')
bpy.ops.mesh.merge(type='CENTER')
bpy.ops.mesh.dissolve_verts()
bpy.ops.mesh.fill()

Notes

• Loops store per-face-vertex data (UVs, vertex colors); each edge generally has two loops (one per adjacent face)
• bmesh.from_edit_mesh() gives direct access to edit-mode data without toggling modes; call bmesh.update_edit_mesh() after modifications
• bpy.ops.mesh.* operators require the context to be in Edit Mode and will only affect the active object
• N-gons (faces with more than 4 vertices) can cause shading and subdivision issues; prefer quads where possible
• Knife tool: press C to constrain to angles, Z to cut through, Enter or Space to confirm

Related

• Modifiers
• Sculpting

Modifiers

Modifiers are non-destructive operations that transform an object's geometry. They are evaluated from top to bottom in the stack; each modifier receives the output of the modifier above it.

Overview

Modifiers are added via the wrench icon in the Properties panel, or via Python through obj.modifiers.new(name, type). They can be applied (made permanent) or removed without affecting the base mesh.

Generate Modifiers

Deform Modifiers

Physics Modifiers (Overview)

Python API Mapping

Adding a Modifier

import bpy

obj = bpy.context.active_object

# Add a Subdivision Surface modifier
mod = obj.modifiers.new(name="Subdivision", type='SUBSURF')
mod.levels = 2          # viewport subdivision level
mod.render_levels = 3   # render subdivision level

# Add a Mirror modifier
mirror = obj.modifiers.new(name="Mirror", type='MIRROR')
mirror.use_axis[0] = True   # mirror on X
mirror.use_bisect_axis[0] = True

# Add a Boolean modifier
bool_mod = obj.modifiers.new(name="Boolean", type='BOOLEAN')
bool_mod.operation = 'DIFFERENCE'
bool_mod.object = bpy.data.objects["Cutter"]

Applying a Modifier

import bpy

obj = bpy.context.active_object
bpy.context.view_layer.objects.active = obj

# Apply by modifier name
bpy.ops.object.modifier_apply(modifier="Subdivision")

# Apply all modifiers on the object (snapshot names first; applying mutates the stack)
for mod_name in [m.name for m in obj.modifiers]:
    bpy.ops.object.modifier_apply(modifier=mod_name)

Configuring Common Modifiers

import bpy

obj = bpy.context.active_object

# Array modifier — 3 copies along X with 2-unit offset
arr = obj.modifiers.new(name="Array", type='ARRAY')
arr.count = 3
arr.relative_offset_displace[0] = 1.5  # X offset multiplier

# Bevel modifier
bev = obj.modifiers.new(name="Bevel", type='BEVEL')
bev.width = 0.05
bev.segments = 3
bev.limit_method = 'ANGLE'

# Decimate modifier — reduce to 50% of original polygons
dec = obj.modifiers.new(name="Decimate", type='DECIMATE')
dec.ratio = 0.5

# Solidify modifier
sol = obj.modifiers.new(name="Solidify", type='SOLIDIFY')
sol.thickness = 0.02
sol.offset = -1.0  # grow inward

Notes

• Stack order matters: Boolean before Subdivision Surface avoids topology artifacts; Mirror before Subdivision Surface can cause seam issues if the order is reversed
• bpy.ops.object.modifier_apply() requires the object to be active and in Object Mode
• To apply a modifier without bpy.ops, use obj.to_mesh() (read-only evaluated mesh) or bpy.ops.object.convert(target='MESH') to destructively apply all modifiers
• The NODES modifier type is the Geometry Nodes modifier — it holds a node_group pointer
• Physics modifiers (Cloth, Soft Body, Fluid) require baking via bpy.ops.ptcache.bake() or the Cache panel

Related

• Mesh Basics
• Geometry Nodes

Modeling — Index

Sculpting

Sculpt Mode allows freeform mesh editing using brushes that push, pull, smooth, or otherwise deform geometry. It is accessed by switching the interaction mode to Sculpt Mode from the viewport header.

Overview

Sculpt Mode operates on the active mesh object. Brushes apply strokes using a radius and strength falloff. For dynamic topology changes, Dyntopo adds and removes geometry on the fly; alternatively, Voxel Remesh regenerates a uniform topology before sculpting.

Core Brushes

Mask

Masks prevent sculpt brushes from affecting masked areas. Masks are stored as a vertex attribute (0 = unmasked, 1 = fully masked).

Face Sets

Face Sets group polygon regions for isolation, masking, and sculpting workflows. Each face set has a unique integer ID visualized by color.

Dyntopo

Dynamic Topology (Dyntopo) adds and removes mesh triangles during sculpting strokes to maintain a target detail level.

• Enable via Sculpt Mode header → Dyntopo checkbox
• Detail Size — controls the target edge length (Relative Detail mode)
• Detail Type: Relative, Constant Detail, Brush Detail
• Dyntopo converts the mesh to triangles; not suitable for production topology

Voxel Remesh

Generates a new all-quad (via Duals) or voxel-based mesh topology. Use before detail sculpting to get uniform geometry.

• Voxel Size — controls grid resolution; smaller = more polygons
• Accessed via right-click header → Remesh, or Properties → Data → Remesh
• Preserves volume but discards UV maps and vertex groups

Python API Mapping

Accessing Sculpt Settings

import bpy

# Access the sculpt settings
sculpt = bpy.context.scene.tool_settings.sculpt

# Set symmetry
sculpt.use_symmetry_x = True
sculpt.use_symmetry_y = False

# Enable Dyntopo settings (requires Sculpt Mode active)
sculpt.use_edge_collapse = True
sculpt.constant_detail_resolution = 9.0  # for Constant Detail mode

Entering Sculpt Mode and Setting the Active Brush

import bpy

obj = bpy.context.active_object
bpy.context.view_layer.objects.active = obj

# Switch to Sculpt Mode
bpy.ops.object.mode_set(mode='SCULPT')

# Set active brush by name
bpy.ops.wm.tool_set_by_id(name="builtin_brush.Draw")

Applying Voxel Remesh

import bpy

obj = bpy.context.active_object
# Set voxel size on the mesh data
obj.data.remesh_voxel_size = 0.05
obj.data.remesh_voxel_adaptivity = 0.0

# Apply the remesh
bpy.ops.object.voxel_remesh()

Mask Operations via Python

import bpy

# Invert mask on active sculpt object
bpy.ops.sculpt.mask_filter(filter_type='INVERT', auto_smooth_iterations=0)

# Smooth mask weights
bpy.ops.sculpt.mask_filter(filter_type='SMOOTH')

# Fill (set all to 1) or clear (set all to 0)
bpy.ops.paint.mask_flood_fill(mode='VALUE', value=1.0)  # fill
bpy.ops.paint.mask_flood_fill(mode='VALUE', value=0.0)  # clear

# Hide a face set by ID
bpy.ops.sculpt.face_set_change_visibility(mode='TOGGLE')

Reading Mask Data from Mesh

import bpy

obj = bpy.context.active_object
mesh = obj.data

# Vertex paint / mask attribute layer
if ".sculpt_mask" in mesh.attributes:
    mask_attr = mesh.attributes[".sculpt_mask"]
    for val in mask_attr.data:
        print(val.value)

Notes

• Sculpt Mode operates on triangle topology internally; Dyntopo always triangulates the mesh
• Face Sets are stored as an integer face attribute named .sculpt_face_set; values correspond to the face set ID
• The Mask attribute is stored as a float vertex attribute named .sculpt_mask (0.0 = unmasked, 1.0 = masked)
• bpy.ops.sculpt.* operators generally require the active mode to be 'SCULPT'
• Smooth brush shortcut: hold Shift while using any brush to temporarily switch to smooth
• Multires modifier preserves subdivided sculpt detail at multiple levels; Dyntopo and Multires are mutually exclusive

Related

• Mesh Basics
• Modifiers

Cloth Simulation

Cloth simulation is applied via the Cloth modifier (type='CLOTH'). Settings are split across ClothSettings (structural behaviour), ClothCollisionSettings (collision), and PointCache (caching/baking).

Overview

• Add the modifier with obj.modifiers.new(name="Cloth", type='CLOTH')
• ClothSettings is accessed via mod.settings
• ClothCollisionSettings is accessed via mod.collision_settings
• Baking writes to mod.point_cache

Key Settings

ClothSettings (mod.settings)

ClothCollisionSettings (mod.collision_settings)

Python API Mapping

import bpy

obj = bpy.context.active_object

# Add Cloth modifier
mod = obj.modifiers.new(name="Cloth", type='CLOTH')
settings = mod.settings
coll = mod.collision_settings

# Physical properties
settings.quality = 10
settings.mass = 0.5
settings.tension_stiffness = 20.0
settings.bending_stiffness = 1.0

# Pin group (vertices that stay fixed)
settings.vertex_group_mass = "Pin"    # must exist as a vertex group

# Enable object collision
coll.use_collision = True
coll.distance_min = 0.01
coll.friction = 10.0

# Enable self-collision
coll.use_self_collision = True
coll.self_distance_min = 0.01

# Bake (Blender 3.2+ context override)
with bpy.context.temp_override(
    scene=bpy.context.scene,
    active_object=obj,
    object=obj,
    point_cache=mod.point_cache,
):
    bpy.ops.ptcache.bake(bake=True)

Notes

• Cloth collision with other objects requires those objects to have a Collision modifier (see collision-forces.md)
• Higher quality values improve simulation accuracy but increase computation time
• vertex_group_mass is the pin group (despite its name): vertices with weight 1.0 are fully pinned; weight 0.0 simulates freely. The property name is a historical artifact — the UI labels it "Pin Group" under Cloth > Shape
• Baked cache is invalidated by any modifier-order change or settings edit; free the bake before re-simulating

Related

• collision-forces.md
• soft-body.md

Collision & Force Fields

Two independent systems enable objects to affect physics simulations: the Collision modifier (passive deflection surface for cloth, soft body, and particles) and Force Fields (active forces applied to simulations via obj.field).

Overview

• Collision modifier: add to any mesh that should deflect cloth/soft body/particles
• Force fields: created via bpy.ops.object.effector_add(type=...) or by setting obj.field.type
• Both systems use Effector Weights to control per-simulation influence

Collision Modifier

Add with obj.modifiers.new(name="Collision", type='COLLISION'). Settings via mod.settings (CollisionSettings).

CollisionSettings

Force Fields

Force fields are configured via obj.field (FieldSettings). Create a dedicated force field empty with bpy.ops.object.effector_add(type=...).

FieldSettings (obj.field)

Force Field Types

Effector Weights

Each simulation (cloth, soft body, particles, fluid) exposes an effector_weights object to scale per-category force-field influence:

# Example: particle system effector weights
ps = obj.particle_systems[0].settings
ps.effector_weights.gravity = 0.5      # reduce gravity to 50%
ps.effector_weights.wind = 1.0         # full wind effect
ps.effector_weights.vortex = 0.0       # ignore vortex fields

Python API Mapping

import bpy

# Add Collision modifier to a mesh
coll_obj = bpy.data.objects["Ground"]
mod = coll_obj.modifiers.new(name="Collision", type='COLLISION')
mod.settings.cloth_friction = 20.0
mod.settings.damping = 0.8

# Create a Wind force field
bpy.ops.object.effector_add(type='WIND', location=(0, 0, 2))
wind = bpy.context.active_object
wind.field.strength = 5.0
wind.field.noise = 1.5        # add turbulence to wind

# Create a Vortex
bpy.ops.object.effector_add(type='VORTEX', location=(0, 0, 0))
vortex = bpy.context.active_object
vortex.field.strength = 3.0
vortex.field.inflow = 0.5

# Create a Force field with falloff
bpy.ops.object.effector_add(type='FORCE', location=(0, 0, 0))
ff = bpy.context.active_object
ff.field.strength = -10.0     # negative = attraction
ff.field.use_max_distance = True
ff.field.distance_max = 5.0
ff.field.falloff_power = 2.0

Notes

• Collision modifier must be before any deforming modifier in the stack to detect the correct shape
• Force fields apply to all simulations in the scene by default; use Effector Weights or Collection constraints to restrict influence
• 'WIND' blows along the object's local −Z axis; rotate the empty to change wind direction
• 'TURBULENCE' uses the noise, size, and seed properties; 'WIND' uses wind_factor for surface-parallel reduction
• For cloth, force fields only work when the cloth has no bake (or during interactive simulation playback)

Related

• cloth.md
• soft-body.md
• particles.md
• rigid-body.md

Fluid Simulation (Mantaflow)

Blender's fluid system (since 2.82) is powered by Mantaflow. Three modifier roles define the simulation: Domain (volume where simulation occurs), Flow (fluid emitter/inflow/outflow), and Effector (collision or guide object).

Overview

• All objects use a single Fluid modifier (type='FLUID'); the role is set via mod.fluid_type
• Domain supports 'LIQUID' (FLIP solver) and 'GAS' (smoke/fire)
• Baking is modular: particles, mesh, and noise can be baked independently

Key Settings

Domain — mod.domain_settings (FluidDomainSettings)

Gas-specific (domain_type = 'GAS')

Liquid-specific (domain_type = 'LIQUID')

Flow — mod.flow_settings (FluidFlowSettings)

Effector — mod.effector_settings (FluidEffectorSettings)

Python API Mapping

import bpy

# --- Domain ---
domain_obj = bpy.data.objects["FluidDomain"]
mod = domain_obj.modifiers.new(name="Fluid", type='FLUID')
mod.fluid_type = 'DOMAIN'
ds = mod.domain_settings
ds.domain_type = 'LIQUID'
ds.resolution_max = 64
ds.cache_directory = "//cache/fluid"
ds.cache_type = 'ALL'

# --- Flow (inflow) ---
flow_obj = bpy.data.objects["FluidFlow"]
mod_f = flow_obj.modifiers.new(name="Fluid", type='FLUID')
mod_f.fluid_type = 'FLOW'
fs = mod_f.flow_settings
fs.flow_type = 'LIQUID'
fs.flow_behavior = 'INFLOW'

# --- Effector (collision) ---
eff_obj = bpy.data.objects["Collider"]
mod_e = eff_obj.modifiers.new(name="Fluid", type='FLUID')
mod_e.fluid_type = 'EFFECTOR'
mod_e.effector_settings.effector_type = 'COLLISION'

# Bake (requires context with domain object active)
bpy.ops.fluid.bake_all()

Notes

• All objects that participate in the simulation must be inside the Domain object's bounding box
• cache_type = 'MODULAR' allows baking particles, mesh, and noise separately; 'ALL' bakes everything at once
• Gas simulations (smoke/fire) require domain_type = 'GAS'; liquid and gas cannot coexist in one domain
• use_mesh = True (liquid) generates a surface mesh from particles using a marching-cubes-like algorithm — bake mesh separately after baking particles
• OpenVDB (cache_data_format = 'OPENVDB') gives smaller cache files with lossless compression

Related

• collision-forces.md
• rigid-body.md

Particle System

Blender's particle system supports two modes: Emitter (dynamically spawned particles) and Hair (static or groomed strands). Each object can have multiple particle systems stacked as modifiers.

Overview

• Add via obj.modifiers.new(name="ParticleSystem", type='PARTICLE_SYSTEM')
• The new modifier exposes mod.particle_system (ParticleSystem)
• Simulation settings are in psys.settings (ParticleSettings)
• Multiple systems stack on the same object

Key Settings

ParticleSettings (psys.settings)

Emission

Velocity

Physics

Rendering

Children

Hair-specific

Python API Mapping

Emitter System

import bpy

obj = bpy.context.active_object

# Add particle system modifier
mod  = obj.modifiers.new(name="EmitterPS", type='PARTICLE_SYSTEM')
psys = mod.particle_system
ps   = psys.settings

# Emitter configuration
ps.type       = 'EMITTER'
ps.count      = 5000
ps.lifetime   = 80
ps.frame_start = 1
ps.frame_end  = 100
ps.emit_from  = 'FACE'

# Initial velocity
ps.normal_factor = 2.0
ps.factor_random = 0.5

# Children (optional, for emitter)
ps.child_type          = 'SIMPLE'
ps.child_percent       = 5
ps.rendered_child_count = 50

Hair System

The Hair system is a separate particle system (or a new modifier slot). The snippet below adds a second modifier; do not run it in the same context as the Emitter snippet above without intending to stack two systems.

import bpy

obj = bpy.context.active_object

# Add a separate particle system modifier for hair
mod  = obj.modifiers.new(name="HairPS", type='PARTICLE_SYSTEM')
psys = mod.particle_system
ps   = psys.settings

# Hair configuration
ps.type       = 'HAIR'
ps.hair_length = 0.5
ps.hair_step  = 8

# Children (interpolated works well for hair)
ps.child_type = 'INTERPOLATED'

Notes

• effector_weights on ParticleSettings controls which force fields affect the system (see collision-forces.md)
• Hair dynamics (cloth-like simulation) is enabled via ps.use_hair_dynamics = True; this exposes a ClothSettings-like subobject
• For GPU rendering with Cycles, render_type = 'PATH' is required for hair strands
• Each modifier slot can use a different ParticleSettings data-block (reusable via bpy.data.particles)

Related

• collision-forces.md
• cloth.md

Physics — Index

Rigid Body

Rigid body simulation in Blender uses the Bullet physics engine. Objects are added to the Rigid Body World and simulated as non-deforming bodies. Active objects are driven by the simulation; Passive objects are controlled by animation.

Overview

• Rigid Body World is created automatically on first rigidbody.object_add()
• Simulation is stored in a point cache and can be baked to keyframes
• Constraints connect rigid body objects (hinge, slider, generic spring, etc.)

Key Settings

Rigid Body World (bpy.context.scene.rigidbody_world)

Rigid Body Object (obj.rigid_body)

Collision Shapes

Python API Mapping

import bpy

# Create Rigid Body World
bpy.ops.rigidbody.world_add()

# Add active rigid body to selected object
bpy.ops.rigidbody.object_add(type='ACTIVE')

obj = bpy.context.active_object
rb = obj.rigid_body

# Configure properties
rb.mass = 5.0
rb.friction = 0.8
rb.restitution = 0.3
rb.collision_shape = 'CONVEX_HULL'

# Passive collider (floor) — must be a SEPARATE object, made active first
bpy.ops.mesh.primitive_plane_add(size=20, location=(0, 0, -2))
floor = bpy.context.active_object
bpy.ops.rigidbody.object_add(type='PASSIVE')   # applies to `floor` (now active)
floor.rigid_body.friction = 1.0

# Bake all physics to cache
bpy.ops.ptcache.bake_all(bake=True)

# Free bake
bpy.ops.ptcache.free_bake_all()

# Bake to keyframes
bpy.ops.rigidbody.bake_to_keyframes(frame_start=1, frame_end=250, step=1)

Notes

• 'MESH' collision shape is only stable for PASSIVE bodies; use 'CONVEX_HULL' for ACTIVE bodies with complex geometry
• kinematic mode lets you animate a body while still generating collision contacts
• Baking writes simulation data to a .blend-internal cache; re-bake after changing settings
• substeps_per_frame and solver_iterations directly trade accuracy for performance

Related

• collision-forces.md

Soft Body

Soft body simulation makes meshes deform elastically under forces. The Soft Body modifier (type='SOFT_BODY') exposes settings via SoftBodySettings. Three main subsystems: Goal (attraction to rest pose), Edges (spring network), and Self Collision.

Overview

• Add via obj.modifiers.new(name="Softbody", type='SOFT_BODY')
• Settings accessed via mod.settings (SoftBodySettings)
• Point cache via mod.point_cache

Key Settings

Goal — vertices attracted to animated position

Edges — spring network

Self Collision

Aerodynamics & General

Python API Mapping

import bpy

obj = bpy.context.active_object

# Add Soft Body modifier
mod = obj.modifiers.new(name="Softbody", type='SOFT_BODY')
sb = mod.settings

# Goal: pin the top vertices
sb.use_goal = True
sb.vertex_group_goal = "Top"   # vertex group: weight 1 = pinned
sb.goal_spring = 0.8
sb.goal_friction = 5.0

# Edge springs
sb.use_edges = True
sb.pull = 0.8
sb.push = 0.8
sb.bend = 0.5
sb.damping = 1.0

# Self collision
sb.use_self_collision = True
sb.ball_size = 0.3
sb.ball_stiff = 1.0

# Bake
bpy.ops.ptcache.bake_all(bake=True)

Notes

• use_goal = False with use_edges = True produces a fully jelly-like object; combining both gives elastic cloth-like behaviour
• Self collision is computationally expensive — keep ball_size small and only enable when needed
• goal_min / goal_max rescale the vertex group weights: a vertex with weight 0.5 maps to goal_min + 0.5 * (goal_max - goal_min)
• Aerodynamics requires use_edges = True to function

Related

• cloth.md
• collision-forces.md

bpy.app

Provides read-only application metadata (version, build info, runtime flags) and three submodules for event handling (handlers), deferred execution (timers), and localization (translations).

Signature / Usage

import bpy

# Version check
if bpy.app.version >= (4, 0, 0):
    print("Running Blender 4+")

# Handler with @persistent (survives file loads)
from bpy.app.handlers import persistent

@persistent
def on_load(*args):
    # load_post receives dummy args; read the path from bpy.data
    print("File loaded:", bpy.data.filepath)

bpy.app.handlers.load_post.append(on_load)

# Timer: run once after 2 seconds
def my_timer():
    print("Timer fired")
    return None  # returning None unregisters the timer

bpy.app.timers.register(my_timer, first_interval=2.0)

Options / Props

Version Attributes

Runtime State Flags

File Paths

bpy.app.handlers

Event callback lists. Append callables to subscribe; remove to unsubscribe.

`@persistent` decorator: by default handlers are freed on file load. Decorate with @persistent from bpy.app.handlers to keep them active across file loads.

from bpy.app.handlers import persistent

@persistent
def my_handler(scene):
    print("Frame:", scene.frame_current)

bpy.app.handlers.frame_change_pre.append(my_handler)
# Remove:
bpy.app.handlers.frame_change_pre.remove(my_handler)

bpy.app.timers

def make_countdown(start):
    state = {"n": start}
    def tick():
        print(state["n"])
        if state["n"] <= 0:
            return None  # unregister the timer
        state["n"] -= 1
        return 1.0       # run again in 1 second
    return tick

bpy.app.timers.register(make_countdown(5))

bpy.app.translations

Notes

• Handler callbacks for frame_change_pre/post during rendering are called from the render thread, while viewport updates occur on a different thread. Modifying scene data in these handlers without locking can cause crashes — lock the interface before rendering if handlers mutate data.
• Timer functions run on the main thread between UI events; they are safe for data modifications but should complete quickly to avoid UI stutter.
• bpy.app.timers.register with persistent=True preserves the timer across file loads, analogous to @persistent for handlers.
• The driver_namespace dict (bpy.app.driver_namespace) is reset on file load; populate it in a load_post handler or via a registered text data-block.

Related

• bpy.context
• bpy.utils
• bpy.info

bpy.context

Provides read-only access to the active window, area, scene, and selection state. Values depend on which editor area is currently active. All context values are read-only; modify them via the data API or by running operators.

Signature / Usage

import bpy

# Common access patterns
obj = bpy.context.active_object
selected = bpy.context.selected_objects
scene = bpy.context.scene
mode = bpy.context.mode  # e.g. 'OBJECT', 'EDIT_MESH'

# Temporary context override
with bpy.context.temp_override(area=my_area):
    bpy.ops.view3d.view_all()

Options / Props

Core Context Attributes

Object Collection Attributes

Bone / Pose Attributes

Methods

Notes

• Read-only constraint: Assigning to bpy.context.active_object = obj raises AttributeError. Use bpy.context.view_layer.objects.active = obj instead.
• Area-dependent members: Some attributes (e.g., space_data) are only available when the appropriate editor area is active. Accessing them outside that context returns None or raises an error.
• temp_override usage: Pass keyword arguments matching bpy.types.Context attribute names. Commonly used to supply a valid area or region when calling operators from a script:

  # Force operator to run in a VIEW_3D area
  for area in bpy.context.screen.areas:
      if area.type == 'VIEW_3D':
          with bpy.context.temp_override(area=area):
              bpy.ops.view3d.view_all()
          break

• Background mode: area, space_data, and region are None when Blender runs headless (--background). Operators that require a window context will fail.

Related

• bpy.data
• bpy.ops
• bpy.types

bpy.data

The primary interface for accessing and managing all Blender data-blocks from Python. Backed by bpy.types.BlendData, it provides typed collections for every ID type in a .blend file.

Signature / Usage

import bpy

# Iterate all objects
for obj in bpy.data.objects:
    print(obj.name)

# Key-based lookup
cube = bpy.data.objects["Cube"]

# Safe lookup
mat = bpy.data.materials.get("MyMaterial")  # None if missing

# Create a new data-block
mesh = bpy.data.meshes.new(name="MyMesh")

# Remove a data-block
bpy.data.meshes.remove(mesh)

# Current .blend file path
print(bpy.data.filepath)

Options / Props

Main Collections

File Attributes

Collection Methods (common to all collections)

Notes

• Data-blocks with zero users are not automatically deleted; call .remove() explicitly or use do_unlink=True.
• Modifying a data-block directly (e.g., mesh.vertices) requires the object not to be in Edit Mode — use bpy.ops.object.mode_set(mode='OBJECT') first.
• Linked data-blocks (from external .blend files) appear in the same collections but have library set to a Library object. They cannot be edited directly without making them local.
• Library overrides allow editing linked data: use datablock.override_create(remap_local_usages=True).

Related

• bpy.context
• bpy.types
• bpy.ops

bpy.ops

Provides access to Blender's operator system. Operators are organized into submodules by category (e.g., bpy.ops.object, bpy.ops.mesh). All arguments must be passed as keyword arguments.

Signature / Usage

import bpy

# Basic call
bpy.ops.object.shade_smooth()

# With keyword arguments
bpy.ops.mesh.subdivide(number_cuts=3, smoothness=0.5)

# Poll before calling to avoid errors
if bpy.ops.object.mode_set.poll():
    bpy.ops.object.mode_set(mode='EDIT')

# With execution context (triggers invoke path / shows dialog)
bpy.ops.object.collection_instance_add('INVOKE_DEFAULT')

# Context override via temp_override
for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        with bpy.context.temp_override(area=area):
            bpy.ops.object.delete()
        break

Options / Props

Operator Call Signature

bpy.ops.<category>.<name>([execution_context, undo,] **kwargs)

Execution Context Values

Return Values

Operators return a set containing one or more status strings:

Major Operator Categories

Notes

• All kwargs only: Operators accept no positional arguments for properties — bpy.ops.mesh.subdivide(3) raises TypeError.
• Error reporting: If the operator logs errors internally, a RuntimeError is raised after execution even if it returns {'FINISHED'}. Wrap calls in try/except RuntimeError when errors are expected.
• Poll failures: Calling an operator when poll() returns False raises RuntimeError: Operator bpy.ops.xxx.yyy.poll() failed. Use .poll() to check first.
• Context requirements: Many operators require a specific area type (e.g., VIEW_3D) or mode. Use bpy.context.temp_override() to supply the correct context from a script.
• Operators vs direct API: Prefer direct data manipulation (obj.location.x = 1.0) over operators for performance and reliability in scripts. Operators carry overhead and context constraints. Use operators when undo integration or user-facing side effects are required.

Related

• bpy.context
• bpy.types
• bpy.data

Python API Core