blenderwright tool reference

add_driver

add_driver(object_name: str, data_path: str, expression: str = '', index: int = -1, driver_type: str = 'SCRIPTED', variables: list[dict[str, Any]] | None = None)

Drive a property from other properties or the frame: a door that opens as a handle turns, a wheel that spins as a car moves, a light that dims with distance. Expressions use Blender's simple subset, evaluated without Python: numbers, + - * / % //, comparisons, and/or/not, "a if c else b", parentheses, the variables below, frame, pi, and sin cos tan asin acos atan atan2 sqrt abs fabs floor ceil trunc round int min max radians degrees exp log pow fmod lerp clamp smoothstep. No ** (use pow).

Returns Dict with the driven path, index, expression and variables.

add_fcurve_modifier

add_fcurve_modifier(object_name: str, data_path: str, modifier: str, index: int = -1, settings: dict[str, Any] | None = None)

Add a modifier to animation curves of the object's active action.

Returns Dict with how many curves got the modifier.

add_nla_strip

add_nla_strip(object_name: str, action_name: str, frame_start: int = 1, track_name: str = '', blend_type: str = 'REPLACE', repeat: float = 1.0, scale: float = 1.0, extrapolation: str = 'HOLD_FORWARD', blend_in: float = 0.0, blend_out: float = 0.0, influence: float | None = None)

Place an action on the NLA timeline as a strip: repeat a walk cycle, sequence clips, or layer a wave on top of a walk.

Returns Dict with the track, strip, and its frame range.

clear_animation

clear_animation(object_name: str)

Remove all animation data from an object.

Returns Confirmation dict.

create_animation_path

create_animation_path(object_name: str, path_object: str)

Make an object follow a path (curve) using a Follow Path constraint.

Returns Confirmation dict with constraint details.

delete_keyframe

delete_keyframe(object_name: str, data_path: str, frame: int)

Remove a keyframe from an object property at a specific frame.

Returns Confirmation dict.

insert_keyframe

insert_keyframe(object_name: str, data_path: str, frame: int, value: float | list[float] | None = None)

Insert a keyframe on an object property at a specific frame.

Returns Confirmation dict with keyframe details.

keyframe_property

keyframe_property(data_path: str, frame: int, value: Any = None, object_name: str = '', target: str = 'OBJECT', index: int = -1)

Keyframe any animatable property: material colours, light power, world strength, modifier settings, camera lens and more. Optionally sets the value first, so "turn red at frame 24" is one call. For location, rotation and scale, insert_keyframe is simpler.

Returns Dict with the data block keyed, its path, the frame and the value.

list_drivers

list_drivers(object_name: str)

List the drivers on an object with their expressions and variables.

Returns Dict with each driver's path, index, type, expression, variables and whether Blender considers it valid.

list_keyframes

list_keyframes(object_name: str)

List all keyframes on an object.

Returns List of dicts with data_path, frame, and value for each keyframe.

list_nla

list_nla(object_name: str)

List an object's NLA tracks and strips, top to bottom.

Returns Dict with each track and its strips (action, frames, blend, repeat).

manage_action

manage_action(object_name: str, operation: str, action_name: str = '')

Work with an object's actions (its saved animations).

Returns Dict with the object's active action and slot, and the file's actions.

remove_driver

remove_driver(object_name: str, data_path: str, index: int = -1)

Remove a driver so the property goes back to its own value.

Returns Dict with how many drivers were removed.

set_frame

set_frame(frame: int)

Set the current frame in the timeline.

Returns Confirmation dict with the new current frame.

set_frame_range

set_frame_range(start: int, end: int)

Set the start and end frames of the scene timeline.

Returns Confirmation dict with the new frame range.

set_interpolation

set_interpolation(object_name: str, data_path: str, interpolation: str = 'BEZIER')

Set the interpolation type for keyframes on a property.

Returns Confirmation dict.

add_bone

add_bone(armature_name: str, bone_name: str, head: list[float] | tuple[float, ...] = (0, 0, 0), tail: list[float] | tuple[float, ...] = (0, 0, 1), parent_bone: str = '')

Add a bone to an armature. Enters edit mode automatically.

Returns Dict with the created bone's name, head, and tail positions.

add_constraint

add_constraint(object_name: str, bone_name: str = '', constraint_type: str = '', properties: dict[str, Any] | None = None)

Add a constraint to an object or bone.

Returns Dict with the created constraint's name and type.

create_armature

create_armature(name: str = 'Armature', location: list[float] | tuple[float, ...] = (0, 0, 0))

Create a new armature object.

Returns Dict with the created armature's name and location.

manage_bone_collection

manage_bone_collection(armature_name: str, action: str, collection_name: str, bones: list[str] | None = None, parent: str = '')

Organise an armature's bones into collections and show or hide them. Typical rig layout: "Deform" (hidden), "Controls" (visible), "Mechanism" (hidden).

Returns Dict with the armature's collections, their bones and visibility.

parent_mesh_to_armature

parent_mesh_to_armature(mesh_name: str, armature_name: str, type: str = 'ARMATURE_AUTO')

Parent a mesh object to an armature with automatic weights or other methods.

Returns Confirmation dict.

set_bone_property

set_bone_property(armature_name: str, bone_name: str, property: str, value: Any)

Set a property on a bone in an armature.

Returns Confirmation dict with bone name, property, and new value.

set_pose

set_pose(armature_name: str, bone_name: str, location: list[float] | tuple[float, ...] | None = None, rotation: list[float] | tuple[float, ...] | None = None, scale: list[float] | tuple[float, ...] | None = None)

Set the pose of a bone in an armature.

Returns Confirmation dict with the bone's new pose values.

setup_ik_chain

setup_ik_chain(armature_name: str, bone_name: str, target_object: str, target_bone: str = '', chain_count: int = 2, pole_object: str = '', pole_bone: str = '', pole_angle: float = 0.0, use_stretch: bool = False, iterations: int = 500)

Give a limb inverse kinematics: move the target and the chain follows. Put the IK on the last bone of the limb (forearm, shin). A pole target (an empty or bone in front of the knee or behind the elbow) keeps the joint bending the right way.

Returns Dict with the constraint and chain details.

bake_texture

bake_texture(object_name: str, bake_type: str, filepath: str, resolution: int = 1024, source_object: str = '', cage_extrusion: float = 0.0, max_ray_distance: float = 0.0, margin: int = 16, samples: int = 64, diffuse_color_only: bool = True, normal_space: str = 'TANGENT')

Bake a texture map from an object's materials (or a high-poly source) into an image. The object needs UVs (smart_uv_project) and a material. Cycles is used for the bake and the render engine is put back afterwards.

Returns Dict with the file written, its size and the image name in Blender.

booltool_auto_difference

booltool_auto_difference(object_name: str, target_name: str)

Auto boolean difference: subtract the target object from the main object. The target object is used as a cutter and removed after the operation. This is the default choice for a cut. Use boolean_operation instead only when the cutter must stay editable as a modifier. Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

Returns Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

booltool_auto_intersect

booltool_auto_intersect(object_name: str, target_name: str)

Auto boolean intersect: keep only the overlapping volume of two objects. The target object is removed after the operation. This is the default choice for an intersection. Use boolean_operation instead only when the cutter must stay editable as a modifier. Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

Returns Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

booltool_auto_slice

booltool_auto_slice(object_name: str, target_name: str)

Auto boolean slice: split the main object using the target as a cutter. Creates two separate pieces from the intersection. The target object is removed after the operation. Slice has no modifier equivalent: boolean_operation offers UNION, DIFFERENCE and INTERSECT only. Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

Returns Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

booltool_auto_union

booltool_auto_union(object_name: str, target_name: str)

Auto boolean union: merge two mesh objects into one, destructively. The target object is consumed and joined into the main object. This is useful for permanently joining meshes so parts don't float away from their bodies. This is the default choice for a union. Use boolean_operation instead only when the cutter must stay editable as a modifier. Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

Returns Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

capture_viewport

capture_viewport(filepath: str = '', width: int = 1920, height: int = 1080)

Render the viewport to a file or return as base64.

Returns Dict with filepath or base64 image data.

create_camera

create_camera(name: str = 'Camera', location: list = [0, 0, 0], rotation: list = [0, 0, 0], lens: float = 50.0)

Create a new camera in the scene.

Returns Confirmation dict with camera name and properties.

point_camera_at

point_camera_at(camera_name: str, target: str = '', location: list | None = None)

Point a camera at an object or a specific location using a Track To constraint.

Returns Confirmation dict.

set_active_camera

set_active_camera(object_name: str)

Set the active scene camera.

Returns Confirmation dict.

set_camera_from_view

set_camera_from_view()

Match the active camera to the current 3D viewport view.

Returns Confirmation dict with the camera's new location and rotation.

set_camera_property

set_camera_property(object_name: str, property: str, value: Any)

Set a property on a camera.

Returns Confirmation dict.

execute_blender_code

execute_blender_code(code: str)

Run Python inside Blender. OFF BY DEFAULT; prefer the structured tools. The user must tick "Allow raw Python" in the blenderwright N-panel (View3D > Sidebar > blenderwright) for the current Blender session. Until they do, this tool returns an error saying so; relay that to the user and do not retry. Never ask the user to enable it just to do something a structured tool already covers. The code runs in a restricted namespace that blocks obvious mistakes (import os/subprocess/socket, exec/eval/open/compile). That is a guard against accidents, not a security boundary: the code runs in-process with full bpy. Every snippet is echoed to Blender's system console and listed in the panel so the user can see what ran.

Returns Dict with 'output' (captured stdout) and 'success' boolean.

create_collection

create_collection(name: str, parent: str = '')

Create a new collection, optionally nested under a parent collection.

Returns Dict with the created collection's name and parent.

create_collection_instance

create_collection_instance(collection_name: str, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0), rotation: list[float] | tuple[float, ...] = (0, 0, 0), scale: list[float] | tuple[float, ...] = (1, 1, 1))

Place a collection as a lightweight instance (an empty that shows it). Instances share the collection's data, so a hundred trees cost little more than one, and editing the collection updates every copy. Works with local and linked collections.

Returns Dict with the instance object's name and its collection.

delete_collection

delete_collection(collection_name: str, delete_objects: bool = False)

Delete a collection.

Returns Confirmation dict.

make_instances_real

make_instances_real(object_name: str, keep_hierarchy: bool = False)

Turn a collection instance into real, separately editable objects.

Returns Dict with the names of the new objects.

manage_view_layer

manage_view_layer(action: str, view_layer: str | None = None, new_name: str | None = None, material_override: str | None = None, world_override: str | None = None, use_for_render: bool | None = None)

List, add, remove, rename or configure view layers (separate render layers). Each view layer renders the scene with its own collection settings (see set_layer_collection) and passes, e.g. a foreground layer and a background layer composited together, or a clay layer. Pass, light group and AOV tools act on the active view layer: SET_ACTIVE first.

Returns Dict with every view layer (name, active, use_for_render, overrides).

move_to_collection

move_to_collection(object_names: list[str], collection_name: str)

Move objects to a collection, unlinking them from their current collections.

Returns Dict with the moved objects and destination collection.

set_collection_visibility

set_collection_visibility(collection_name: str, visible: bool, viewport: bool = True, render: bool = True)

Set collection visibility in viewport and/or render.

Returns Confirmation dict with visibility state.

set_layer_collection

set_layer_collection(collection_name: str, view_layer: str | None = None, exclude: bool | None = None, holdout: bool | None = None, indirect_only: bool | None = None)

Set how a collection takes part in one view layer.

Returns Dict with the collection, the layer and its exclude/holdout/indirect_only.

add_compositor_effect

add_compositor_effect(effect: str, settings: dict[str, Any] | None = None)

Add a post-processing effect at the end of the compositor chain. Effects apply to every render in order, so add glare before film grain.

Returns Dict with the new node's name (use it to edit or remove the effect) and its input names.

list_compositor

list_compositor()

List the compositor chain from render to output with each effect's settings.

Returns Dict with the tree name and the chain of effects in order.

remove_compositor_effect

remove_compositor_effect(node_name: str)

Remove an effect and reconnect the chain around it.

Returns Dict with the removed name and the remaining chain.

set_compositor_effect

set_compositor_effect(node_name: str, settings: dict[str, Any])

Change the settings of an effect already in the compositor.

Returns Dict with the node name and its inputs after the change.

setup_compositor

setup_compositor(reset: bool = False)

Make sure the scene has a compositor: Render Layers into the output. add_compositor_effect calls this itself, so it is only needed to start over. Effects then stack between the render and the output.

Returns Dict with the tree name and the effect chain, render to output.

add_curve_point

add_curve_point(curve_name: str, location: list[float] | tuple[float, ...] = (0, 0, 0), handle_type: str = 'AUTOMATIC')

Add a control point to an existing curve.

Returns Dict with curve name and new point count.

convert_curve_to_mesh

convert_curve_to_mesh(curve_name: str)

Convert a curve object to a mesh object.

Returns Dict with the converted object name.

create_curve

create_curve(type: str = 'BEZIER', name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0))

Create a new curve object.

Returns Dict with created curve name and type.

create_text

create_text(text: str, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0), size: float = 1.0, font: str = '')

Create a 3D text object.

Returns Dict with created text object name.

set_curve_property

set_curve_property(curve_name: str, property: str, value: Any)

Set a property on a curve object.

Returns Confirmation dict with property name and new value.

set_handle_type

set_handle_type(curve_name: str, handle_type: str = 'AUTOMATIC')

Set the handle type for all control points of a curve.

Returns Dict with confirmation of handle type change.

smooth_curve

smooth_curve(curve_name: str)

Smooth the control points of a curve.

Returns Dict with confirmation of smoothing.

subdivide_curve

subdivide_curve(curve_name: str, number_cuts: int = 1)

Subdivide a curve by adding control points between existing ones.

Returns Dict with confirmation of subdivision.

switch_curve_direction

switch_curve_direction(curve_name: str)

Switch the direction of a curve's splines.

Returns Dict with confirmation of direction switch.

toggle_cyclic

toggle_cyclic(curve_name: str)

Toggle the cyclic (closed loop) state of a curve.

Returns Dict with confirmation of cyclic toggle.

add_shape_key

add_shape_key(object_name: str, key_name: str, from_mix: bool = False)

Add a shape key (blend shape). The first call also creates the Basis. Shape keys store alternative vertex positions blended by a 0-1 value: facial expressions, morphs, corrective shapes. Shape it with move_shape_key_vertices, blend with set_shape_key, animate with keyframe_shape_key. A new key starts at value 1.0 (fully on), so edits show straight away; set it to 0 to hide it.

Returns Dict with the new key and every key on the object.

assign_vertex_group

assign_vertex_group(object_name: str, group_name: str, vertex_indices: list[int] | None = None, weight: float = 1.0, mode: str = 'REPLACE', selection: str = 'ALL')

Put vertices into a vertex group with a weight, creating the group if needed. Vertex groups drive armature skinning, and limit modifiers (Displace, Solidify, Mask) and shape keys to part of a mesh.

Returns Dict with the group name, its index and how many vertices changed.

create_lattice

create_lattice(object_name: str, resolution: list[int] | None = None, interpolation: str = 'KEY_LINEAR', lattice_name: str = '')

Wrap an object in a lattice cage and deform it through the cage. The lattice is fitted to the object's bounding box and a Lattice modifier is added. Then bend, taper or bulge the whole shape with move_lattice_points instead of editing vertices.

Returns Dict with the lattice name, its point count and the modifier name.

keyframe_shape_key

keyframe_shape_key(object_name: str, key_name: str, frame: int, value: float | None = None)

Keyframe a shape key's value so the blend shape animates.

Returns Dict with the key, frame and keyed value.

list_shape_keys

list_shape_keys(object_name: str)

List an object's shape keys with values, ranges and options.

Returns Dict with the reference key and each key's settings.

list_vertex_groups

list_vertex_groups(object_name: str)

List an object's vertex groups with vertex counts and weight ranges.

Returns Dict with each group's name, index, vertex count, min and max weight.

move_lattice_points

move_lattice_points(lattice_name: str, offset: list[float] | None = None, scale: list[float] | None = None, axis: str | None = None, sign: str = 'POS', point_indices: list[int] | None = None, reset: bool = False)

Move or scale lattice points to deform everything the lattice is bound to. Pick points by side (axis and sign, split at the middle of the lattice) or by index; with neither, every point moves. Scaling is about the lattice centre, per axis: scale [0.2, 0.2, 1] on the top tapers it to a point.

Returns Dict with how many points moved and the lattice's point count.

move_shape_key_vertices

move_shape_key_vertices(object_name: str, key_name: str, offset: list[float], vertex_indices: list[int] | None = None, vertex_group: str = '')

Move vertices inside a shape key, building the blend shape. The offset is in the object's local space. With a vertex group, each vertex moves by offset times its weight, which gives soft falloff: weight the cheeks, then move them out to puff them.

Returns Dict with the number of vertices moved.

paint_color_attribute

paint_color_attribute(object_name: str, color: list[float], attribute_name: str = 'Color', domain: str = 'CORNER', data_type: str = 'BYTE_COLOR', vertex_indices: list[int] | None = None, selection: str = 'ALL')

Fill a color attribute (vertex colors) on a mesh, creating it if needed. The attribute becomes the active and render color. Read it in a material with a ShaderNodeVertexColor node whose layer_name is the attribute name. Game engines and glTF export pick it up as vertex color.

Returns Dict with the attribute, its domain and type, whether it was created, how many elements were painted, and all color attribute names.

remove_color_attribute

remove_color_attribute(object_name: str, attribute_name: str)

Delete a color attribute from a mesh.

Returns Dict with the removed name and the color attributes left.

remove_shape_key

remove_shape_key(object_name: str, key_name: str)

Delete a shape key.

Returns Dict with the removed key and the keys left.

remove_vertex_group

remove_vertex_group(object_name: str, group_name: str)

Delete a vertex group and every weight in it.

Returns Dict with the removed group and the groups left.

set_shape_key

set_shape_key(object_name: str, key_name: str, value: float | None = None, slider_min: float | None = None, slider_max: float | None = None, mute: bool | None = None, vertex_group: str | None = None, relative_key: str = '')

Set how strongly a shape key applies, and its options.

Returns Dict with the key's settings after the change.

vertex_group_operation

vertex_group_operation(object_name: str, group_name: str, operation: str, factor: float = 0.5, repeat: int = 1, threshold: float = 0.0, offset: float = 0.0, gain: float = 1.0, max_groups: int = 4, steps: int = 4)

Clean up or reshape the weights in a vertex group.

Returns Dict with the group's vertex count and weight range afterwards.

export_file

export_file(filepath: str, type: str = '', selected_only: bool = False, options: dict[str, Any] | None = None)

Export scene or selected objects to a 3D file. Supports FBX, OBJ, GLTF/GLB, USD, STL, PLY, and Alembic (ABC) formats.

Returns Dict with exported file path and format.

import_file

import_file(filepath: str, type: str = '')

Import a 3D file into Blender. Supports FBX, OBJ, GLTF/GLB, USD, STL, PLY, Alembic (ABC), and SVG formats. Auto-detects format from file extension if type is empty.

Returns Dict with imported file path and format.

link_or_append

link_or_append(filepath: str, data_type: str, names: list[str], link: bool = False)

Bring objects, collections, materials and more in from another .blend file. Append copies the data into this file so it can be edited. Link keeps a live reference: edits to the source file show up here, but the data is read-only. A linked collection is placed as an instance; appended objects and collections go into the scene. Scripts in the file are never run.

Returns Dict with each requested name and the name it has here (appends may gain a .001 suffix), plus any instance created for a linked collection.

list_asset_libraries

list_asset_libraries()

List the asset libraries this Blender can use: Essentials (bundled with Blender) and the local libraries set in Preferences. Online libraries are never listed or fetched.

Returns Dict with each library's name and folder.

list_assets

list_assets(library: str, asset_type: str = '')

List the assets in a library, by file, for place_asset.

Returns Dict with assets (file relative to the library, type, name), and truncated if the library has more files than one call reads.

list_blend_contents

list_blend_contents(filepath: str)

List what another .blend file contains without opening it. Use before link_or_append to find the names to bring in. Scripts in the file are never run.

Returns Dict of data type (objects, collections, materials, node_groups, worlds, meshes) to the names in the file.

list_recent_files

list_recent_files()

List recently opened files from Blender preferences.

Returns List of file path strings.

manage_external_paths

manage_external_paths(action: str, directory: str | None = None)

Check and fix the external files (textures, sounds, libraries) a .blend uses.

Returns Dict with each external file (type, name, path, exists) and the missing count, after the action.

manage_linked_data

manage_linked_data(action: str, data_name: str | None = None, data_type: str = 'OBJECT', library: str | None = None)

Work with data linked from other .blend files (link_or_append, place_asset). Linked data is read-only here. MAKE_LOCAL copies it into this file and cuts the link; OVERRIDE keeps the link but makes it editable, so library updates still come through for anything not changed here.

Returns Dict with what changed, or for LIST the libraries, linked data and overrides.

open_file

open_file(filepath: str)

Open a .blend file.

Returns Dict with the opened file path.

pack_resources

pack_resources(autopack: bool | None = None)

Pack every external image, sound, font and volume into the .blend file. Makes the file self-contained so it can be moved or shared without missing textures.

Returns Dict with the packed items (type, name) and whether autopack is on.

place_asset

place_asset(library: str, file: str, asset_type: str, asset_name: str, link: bool = False)

Bring an asset from a library into the scene (append, or link to keep it in sync with the library). Find it with list_assets first.

Returns Dict with the name it got in this file, and any collection instance.

save_file

save_file(filepath: str = '')

Save the current Blender file. If filepath is empty, saves to the current file path (overwrite). If filepath is provided, performs a "Save As" to the given path.

Returns Dict with the saved file path.

unpack_resources

unpack_resources(overwrite: bool = False)

Write packed files out to folders next to the saved .blend (textures/, sounds/, ...). Files only ever go beside the .blend, never to paths stored in the file. The .blend must be saved first.

Returns Dict with each unpacked item (type, name, filepath relative to the .blend).

add_essentials_modifier

add_essentials_modifier(object_name: str, modifier: str, settings: dict[str, Any] | None = None)

Add one of Blender's ready-made node modifiers, with its inputs set. These are full node setups that would take dozens of add_geometry_node calls. Change inputs later with set_geometry_node_input.

Returns Dict with the modifier name and every input with its value.

add_geometry_node

add_geometry_node(modifier_name: str, node_type: str, location: list[float] | tuple[float, ...] = (0, 0))

Add a node to a geometry nodes modifier's node group.

Returns Dict with the created node's name and type.

build_geometry_nodes

build_geometry_nodes(object_name: str, spec: dict[str, Any], modifier_name: str = 'GeometryNodes')

Build a whole geometry node graph on an object in one call. The graph is built in a new node group and only put on the modifier if every step works; on any error nothing changes. The group always gets a Geometry input and output, wired through nodes named "Group Input" and "Group Output". Read a graph back with get_geometry_node_tree.

Returns Dict with the modifier, the node group, and the node and link counts.

connect_geometry_nodes

connect_geometry_nodes(modifier_name: str, from_node: str, from_socket: int, to_node: str, to_socket: int)

Connect two nodes in a geometry nodes modifier's node group.

Returns Confirmation dict with connection details.

create_geometry_nodes

create_geometry_nodes(object_name: str, name: str = 'GeometryNodes')

Create a Geometry Nodes modifier on an object.

Returns Dict with modifier name and node group name.

get_geometry_node_tree

get_geometry_node_tree(object_name: str, modifier_name: str)

Read a geometry nodes modifier's graph: group interface, nodes with their settings and unlinked input values, and links.

Returns Dict with interface, nodes and links, in the shape build_geometry_nodes takes.

list_geometry_node_inputs

list_geometry_node_inputs(object_name: str, modifier_name: str)

List all available inputs on a geometry nodes modifier.

Returns List of dicts with input name, type, and current value.

set_geometry_node_input

set_geometry_node_input(object_name: str, modifier_name: str, input_name: str, value: Any)

Set an input value on a geometry nodes modifier.

Returns Confirmation dict with the input name and new value.

add_annotation_layer

add_annotation_layer(annotation_name: str, layer_name: str)

Add a layer to an annotation. Layers organize annotation strokes. Each layer can have its own blend mode, opacity, and color.

Returns Confirmation dict with annotation and layer names.

add_annotation_stroke

add_annotation_stroke(annotation_name: str, layer_name: str, points: list[list[float]])

Add a stroke to an annotation layer. Creates a new stroke with the given points on the specified layer. Annotation points in 5.2 are a position only: no pressure or strength.

Returns Confirmation dict with point count.

add_gp_stroke

add_gp_stroke(object_name: str, points: list[list[float]], layer: str = '', frame: int = 1, radius: float | list[float] = 0.02, cyclic: bool = False, material: str = '')

Draw one stroke in a Grease Pencil object. Points are in the object's local space. cyclic closes the outline.

Returns Dict with the layer, frame and stroke count on that frame.

add_lineart

add_lineart(source: str = 'SCENE', source_name: str = '', name: str = 'LineArt', thickness: float = 0.01, color: list[float] | tuple[float, ...] = (0, 0, 0, 1), crease_angle: float = 2.443, use_intersection: bool = True)

Add Line Art: inked outlines generated from 3D geometry, as seen by the active camera. Gives renders a comic, technical or toon look.

Returns Dict with the Line Art object and its source.

create_annotation

create_annotation(name: str = '')

Create a new annotation data block. Annotations are viewport overlays used for drawing marks, notes, and guides. Unlike Grease Pencil objects, annotations are not positioned in 3D space.

Returns Dict with the created annotation's name.

create_gp_material

create_gp_material(name: str, color: list[float] | tuple[float, ...] = (0, 0, 0, 1))

Create a Grease Pencil material: the stroke colour. Fills are not offered: in Blender 5.2, strokes built from a script do not render their fill.

Returns Dict with the material and its colour.

create_grease_pencil

create_grease_pencil(name: str = 'Drawing', location: list[float] | tuple[float, ...] = (0, 0, 0), layer_name: str = 'Lines')

Create a Grease Pencil object to draw 2D strokes in 3D space. Draw into it with add_gp_stroke; colour strokes with create_gp_material. For notes on the viewport use the annotation tools instead.

Returns Dict with the object, layer and frame created.

remove_annotation_layer

remove_annotation_layer(annotation_name: str, layer_name: str)

Remove a layer from an annotation.

Returns Confirmation dict.

set_annotation_stroke_property

set_annotation_stroke_property(annotation_name: str, layer_name: str, stroke_index: int, property: str, value: Any)

Set a property on an annotation stroke.

Returns Confirmation dict.

create_light

create_light(type: str, name: str = '', location: list = [0, 0, 0], energy: float = 1000.0, color: list = [1.0, 1.0, 1.0])

Create a new light in the scene.

Returns Confirmation dict with light name and properties.

create_light_rig

create_light_rig(type: str, target: str = '', intensity: float = 1000.0)

Create a pre-built lighting rig (multiple lights arranged for common setups).

Returns Confirmation dict with names of all created lights.

delete_light

delete_light(object_name: str)

Delete a light object from the scene.

Returns Confirmation dict.

list_lights

list_lights()

List all light objects in the scene.

Returns List of dicts with light name, type, energy, color, and location.

set_light_linking

set_light_linking(light_name: str, objects: list[str], role: str = 'RECEIVERS', mode: str = 'INCLUDE')

Limit which objects a light lights, or which objects block its shadows. Classic uses: a rim light that touches only the hero, or a fill light that skips the background. Replaces the light's list each call; an empty list removes the link so the light affects everything again.

Returns Dict with the light, the link collection and its objects.

set_light_property

set_light_property(object_name: str, property: str, value: Any)

Set a property on a light object.

Returns Confirmation dict.

set_shadow_settings

set_shadow_settings(object_name: str, use_shadow: bool = True, shadow_soft_size: float = 0.25)

Configure shadow settings for a light.

Returns Confirmation dict.

set_world_background

set_world_background(color: list | None = None, hdri_path: str | None = None, builtin_hdri: str | None = None, strength: float = 1.0, rotation: float = 0.0)

Set the world background to a solid colour or an HDRI environment. An HDRI lights the whole scene and gives metal and glass something to reflect; without one, metals look dull. Give exactly one of color, hdri_path or builtin_hdri.

Returns Confirmation dict.

set_world_sky

set_world_sky(sky_type: str = 'MULTIPLE_SCATTERING', sun_elevation: float = 0.2618, sun_rotation: float = 0.0, sun_intensity: float = 1.0, sun_disc: bool = True, altitude: float = 100.0, air_density: float = 1.0, aerosol_density: float = 1.0, ozone_density: float = 1.0, strength: float = 1.0)

Light the scene with a physically based procedural sky and sun. Realistic daylight for any time of day with no image file. Low sun elevation gives golden hour; negative gives dusk. Pair with AgX colour management (set_color_management) for natural results.

Returns Dict with the sky settings applied.

add_color_ramp_element

add_color_ramp_element(material_name: str, node_name: str, position: float, color: list)

Add a colour stop to a ColorRamp (ShaderNodeValToRGB) node. A new ramp starts with two stops, black at 0.0 and white at 1.0. Add stops to shape a gradient: fire needs dark red, orange, yellow, white bunched toward the top; rust needs a hard break between metal and oxide.

Returns Dict with the new element's index, position, and color.

add_shader_node

add_shader_node(material_name: str, node_type: str, location: list = [0, 0])

Add a shader node to a material's node tree.

Returns Dict with material, node_name, and node_type.

add_texture_node

add_texture_node(material_name: str, image_path: str, label: str = 'Image Texture')

Add an image texture node to a material and connect it to the Principled BSDF Base Color.

Returns Confirmation dict.

assign_material

assign_material(object_name: str, material_name: str)

Assign a material to an object. An object with no material, or a single one (like the default cube's "Material"), takes the new material on every face. An object that already has several materials keeps them and gains an extra slot that no face uses yet.

Returns Dict with the slot used and the action: "assigned", "replaced" (with the replaced material's name), "added_slot" or "already_assigned".

connect_shader_nodes

connect_shader_nodes(material_name: str, from_node: str, from_socket: str, to_node: str, to_socket: str)

Connect two shader nodes in a material's node tree.

Returns Confirmation dict.

create_material

create_material(name: str)

Create an empty material: a bare Principled BSDF at default values. Use this only when you will wire the node tree yourself with add_shader_node and connect_shader_nodes. For a plain surface with a colour, metallic and roughness set in one call, use create_principled_material. For wood, marble, fire and other patterned surfaces, use create_procedural_material.

Returns Confirmation dict with the created material name.

create_principled_material

create_principled_material(name: str, color: list = [0.8, 0.8, 0.8, 1.0], metallic: float = 0.0, roughness: float = 0.5, specular: float = 0.5, emission_strength: float = 0.0, emission_color: list = [1.0, 1.0, 1.0, 1.0], alpha: float = 1.0, transmission: float = 0.0, ior: float = 1.45)

Create a plain-surface material with colour, metallic, roughness and more set in one call. The usual choice for painted, metal, glass or plastic surfaces of a single colour. For a patterned surface (wood, marble, fire, veins) use create_procedural_material instead. create_material makes the same Principled BSDF with nothing set, for when you will build the node tree by hand.

Returns Confirmation dict with material name and all set properties.

create_procedural_material

create_procedural_material(name: str, pattern: str, scale: float = 5.0, detail: float = 2.0, distortion: float = 0.0, roughness: float = 0.5, metallic: float = 0.0, colors: list | None = None, banded: bool = False, connect_to_bsdf: bool = True)

Create a patterned material (wood, marble, fire, veins) as a full node graph in one call. For a single flat colour use create_principled_material instead; for an empty material you will wire by hand use create_material. Prefer this over hand-wiring texture nodes. It creates the full graph ( coordinates, mapping, the pattern's texture nodes, a tuned colour ramp, and the Principled BSDF) and returns the node names so you can adjust anything afterwards with set_shader_node_input or the colour ramp tools. Procedural beats image textures here: no files, no UV unwrap needed, and it stays sharp at any camera distance. Call list_procedural_patterns() to see what each pattern looks like.

Returns Dict with the material name, the created node names, and ignored_params listing any arguments this pattern could not use.

create_raster_texture

create_raster_texture(name: str, pattern: str, size: int = 512, count: int = 12, seed: int = 0, foreground: list | None = None, background: list | None = None)

Generate an image texture for patterns shader nodes cannot express. Use this only for patterns that place discrete marks. Shader nodes evaluate a function per point and have no way to say "draw a glyph here, then another over there", so runes need real pixels. Everything else should go through create_procedural_material, which stays sharp at any resolution. The image is packed into the blend file. No file is written to disk.

Returns Dict with the image name, size, and mark count.

delete_material

delete_material(material_name: str)

Delete a material by name.

Returns Confirmation dict.

disconnect_shader_nodes

disconnect_shader_nodes(material_name: str, node_name: str, socket_name: str, is_input: bool = True)

Disconnect all links from a specific socket on a shader node.

Returns Confirmation dict.

duplicate_material

duplicate_material(material_name: str, new_name: str)

Duplicate a material with a new name.

Returns Confirmation dict with the new material name.

get_color_ramp

get_color_ramp(material_name: str, node_name: str)

Read every stop on a ColorRamp node. Use this before editing to learn the current indices and positions, since add and move operations reorder stops.

Returns Dict with elements (index, position, color), interpolation, color_mode.

get_node_tree

get_node_tree(material_name: str)

Get the full node tree of a material (all nodes and links).

Returns Dict with nodes (name, type, location, input and output names, the values of unlinked inputs, and the node's own settings) and links.

list_materials

list_materials()

List all materials in the current Blender file.

Returns List of dicts with material name and user count.

list_procedural_patterns

list_procedural_patterns()

List every procedural pattern with a description of what it looks like. Read this before calling create_procedural_material so you pick a pattern that matches the surface you are trying to make.

Returns Dict with the sorted pattern names and a description of each.

remove_color_ramp_element

remove_color_ramp_element(material_name: str, node_name: str, index: int)

Remove a colour stop from a ColorRamp node. Blender requires at least one stop to remain; removing the last one fails.

Returns Dict with the removed index and the remaining element count.

remove_shader_node

remove_shader_node(material_name: str, node_name: str)

Remove a shader node from a material's node tree.

Returns Confirmation dict.

set_color_ramp_element

set_color_ramp_element(material_name: str, node_name: str, index: int, position: float | None = None, color: list | None = None)

Move or recolor an existing ColorRamp stop. At least one of position or color must be given. Moving a stop past a neighbour reorders the ramp, so indices may shift after this call. Read the ramp back with get_color_ramp if you need certainty.

Returns Dict with the element's resulting position and color.

set_color_ramp_interpolation

set_color_ramp_interpolation(material_name: str, node_name: str, interpolation: str, color_mode: str = '')

Set how a ColorRamp blends between its stops. 'CONSTANT' gives hard-edged bands with no blending, which is what turns a noise or voronoi texture into discrete regions: scale plates, cracked mud, stylised cel shading. 'EASE' and 'B_SPLINE' give softer falloff than 'LINEAR'. Set color_mode to 'HSV' to sweep through hues between two stops rather than blending through grey.

Returns Dict with the applied interpolation and color mode.

set_material_blend_mode

set_material_blend_mode(material_name: str, mode: str)

Set the blend mode of a material (EEVEE).

Returns Confirmation dict.

set_material_color

set_material_color(material_name: str, color: list)

Set the base color of a material's Principled BSDF node.

Returns Confirmation dict.

set_material_property

set_material_property(material_name: str, property: str, value: Any)

Set a property on a material's Principled BSDF node.

Returns Confirmation dict.

set_shader_node_input

set_shader_node_input(material_name: str, node_name: str, socket: str | int, value: float | bool | list)

Set the default value of an unconnected input socket on a shader node. This is how you dial in a procedural texture: Noise 'Scale' and 'Detail', Mapping 'Scale' and 'Rotation', a Principled BSDF 'Roughness', and so on. A socket that has a link into it ignores its default value, so disconnect it first if you want the default to take effect.

Returns Dict with the node, socket, and the value that was applied.

set_shader_node_property

set_shader_node_property(material_name: str, node_name: str, property: str, value: str | float | bool)

Set a node-level property (not a socket) on a shader node. These are the dropdowns and checkboxes on the node body rather than its input sockets: Math 'operation', Mix 'blend_type', Voronoi 'feature' (use 'DISTANCE_TO_EDGE' for vein and crack patterns), Wave 'wave_type' and 'bands_direction', Noise 'noise_dimensions'.

Returns Dict with the node, property, and the value that was applied.

bisect_mesh

bisect_mesh(object_name: str, plane_point: list[float] | tuple[float, ...] = (0, 0, 0), plane_normal: list[float] | tuple[float, ...] = (0, 0, 1), clear_inner: bool = False, clear_outer: bool = False, fill: bool = False, selection: str = 'ALL')

Slice a mesh with a plane, optionally deleting one side and capping the cut. Cuts a new edge loop where the plane crosses, which is also a clean way to halve a model before adding a Mirror modifier.

Returns Dict with the vertex count afterwards.

dissolve_edges

dissolve_edges(object_name: str, selection: str = 'ALL')

Dissolve all edges, merging adjacent faces. Simplifies topology by removing unnecessary edge loops while preserving the overall shape.

Returns Confirmation dict.

dissolve_faces

dissolve_faces(object_name: str, selection: str = 'ALL')

Dissolve all faces, merging them into surrounding geometry. Removes faces while keeping the surrounding mesh structure intact. Cleaner than deleting faces which leaves holes.

Returns Confirmation dict.

dissolve_verts

dissolve_verts(object_name: str, selection: str = 'ALL')

Dissolve all vertices, merging connected edges and faces. Removes vertices while preserving surrounding geometry.

Returns Confirmation dict.

edit_mesh_operation

edit_mesh_operation(object_name: str, operation: str, selection: str = 'ALL', factor: float = 0.5, repeat: int = 1, offset: float = 0.0, thickness: float = 0.02)

Run one of the common edit-mode operations on a mesh.

Returns Dict with the operation and the mesh's vertex and face counts after it.

fill_faces

fill_faces(object_name: str, selection: str = 'ALL')

Fill selected edges with a face. Creates faces from a closed edge loop. Useful for closing gaps in meshes or capping open ends.

Returns Confirmation dict.

flip_normals

flip_normals(object_name: str, selection: str = 'ALL')

Flip the direction of all face normals on a mesh. Reverses inside/outside of all faces. Use recalculate_normals instead if normals are inconsistent rather than uniformly wrong.

Returns Confirmation dict.

grid_fill

grid_fill(object_name: str, span: int = 1, offset: int = 0, selection: str = 'ALL')

Fill a closed edge loop with a grid of quads. Creates a clean quad grid between edge loops. Better than fill_faces for maintaining good topology.

Returns Confirmation dict.

inset_faces

inset_faces(object_name: str, thickness: float = 0.1, depth: float = 0.0, selection: str = 'ALL')

Inset all faces of a mesh, creating a border/frame around each face. Core hard-surface modeling operation for adding detail, panel lines, or preparing faces for extrusion. On a closed mesh, selection="ALL" does nothing: a region with no boundary has nothing to inset from, and Blender reports success having changed nothing. Measured on a default cube in 5.1, the vertex, edge and face counts are identical afterwards. Select the faces you mean and pass selection="CURRENT".

Returns Confirmation dict.

knife_project

knife_project(object_name: str, cutter_name: str)

Project a cutter object's outline onto a mesh to cut it. The cutter object (curve or mesh) is projected from the viewport onto the target mesh, cutting new edges into it.

Returns Confirmation dict.

loop_tools

loop_tools(object_name: str, operation: str, factor: float = 1.0, radius: float | None = None, selection: str = 'CURRENT')

Reshape selected loops: make them round, even or flat. Blender 5.2's built-in versions of the LoopTools add-on. Select a loop or region first with the select_* tools.

Returns Dict with the operation and the object.

mark_seam

mark_seam(object_name: str, clear: bool = False, selection: str = 'ALL')

Mark or clear UV seams on all edges of a mesh. UV seams guide the UV unwrapping process. Edges marked as seams define where the mesh is "cut" when unwrapped to 2D.

Returns Confirmation dict.

mark_sharp

mark_sharp(object_name: str, clear: bool = False, selection: str = 'ALL')

Mark or clear sharp edges on a mesh. Sharp edges control auto-smooth shading. Edges marked as sharp will have a hard edge in the shading even with smooth shading enabled.

Returns Confirmation dict.

quads_to_tris

quads_to_tris(object_name: str, selection: str = 'ALL')

Convert all quad faces to triangles. Useful for game engine export or when triangulated geometry is required.

Returns Confirmation dict.

recalculate_normals

recalculate_normals(object_name: str, inside: bool = False, selection: str = 'ALL')

Recalculate face normals to be consistent (all pointing outward or inward). Fixes meshes with flipped or inconsistent normals that cause shading artifacts.

Returns Confirmation dict.

select_linked

select_linked(object_name: str)

Grow the current mesh selection to everything connected to it. Expands selection to include all connected vertices, edges, and faces. Useful for isolating mesh islands or selecting connected components. Needs a starting selection: set one with select_by_index or select_by_axis first. Works inside one mesh; to select whole objects use select_objects.

Returns Confirmation dict.

set_edge_crease

set_edge_crease(object_name: str, value: float = 1.0, selection: str = 'ALL')

Set edge crease value on all edges for subdivision surface control. Crease values control how sharp edges remain when a Subdivision Surface modifier is applied. 0 = fully smooth, 1 = fully sharp.

Returns Confirmation dict.

spin_mesh

spin_mesh(object_name: str, angle: float = math.tau, steps: int = 12, axis: list[float] | tuple[float, ...] = (0, 0, 1), center: list[float] | tuple[float, ...] = (0, 0, 0), selection: str = 'ALL')

Spin (lathe) mesh geometry around an axis. Creates rotational geometry by duplicating and rotating the selected geometry around a center point. Great for creating round shapes like vases, columns, or wheels.

Returns Confirmation dict.

symmetrize_mesh

symmetrize_mesh(object_name: str, direction: str = 'NEGATIVE_X', threshold: float = 0.0001, selection: str = 'ALL')

Make a mesh symmetrical by copying one half onto the other. Fixes a model that drifted out of symmetry, or builds the second half of a half-modelled object. Works in the object's local axes.

Returns Dict with the direction and the vertex count afterwards.

tris_to_quads

tris_to_quads(object_name: str, selection: str = 'ALL')

Convert adjacent triangle pairs to quad faces where possible. Improves topology for subdivision and deformation. Not all triangles can be merged: only adjacent pairs with compatible angles.

Returns Confirmation dict.

analyze_mesh_quality

analyze_mesh_quality(object_name: str)

Analyze mesh topology quality and return a structured defect report. Checks for non-manifold edges, loose vertices, zero-area faces, duplicate vertices, and wire edges. Returns counts and sample indices (capped at 50 per category) for each defect type.

Returns Dict with vertex/edge/face counts, defect counts and sample indices, and an issues_found boolean.

decimate_mesh

decimate_mesh(object_name: str, ratio: float = 0.5)

Reduce a mesh's polygon count, collapsing edges to hit a target. The counterpart to subdivision: an agent that has stacked Subdivision modifiers has otherwise no way back down, and a dense mesh slows every later operation.

Returns Dict with the face count before and after.

repair_mesh

repair_mesh(object_name: str, remove_loose: bool = True, dissolve_degenerate: bool = True, fill_holes: bool = False)

Repair the defects analyze_mesh_quality reports. Pairs with analyze_mesh_quality: run that first, then call this with the repairs the report calls for. Removing loose geometry and dissolving degenerate faces cannot change a well-formed mesh, so both are on by default. Filling holes creates new geometry and is opt-in.

Returns Dict with the counts before and after, so the effect is visible.

add_modifier

add_modifier(object_name: str, modifier_type: str, name: str = '')

Add a modifier to a mesh object (non-destructive workflow). TIP: For BOOLEAN type, consider using booltool_auto_union/difference/intersect/slice instead: they apply the boolean immediately and handle cutter cleanup automatically. Only use add_modifier with BOOLEAN when you want a non-destructive modifier stack.

Returns Confirmation dict with modifier details.

apply_modifier

apply_modifier(object_name: str, modifier_name: str)

Apply a modifier to an object, making its effect permanent.

Returns Confirmation dict.

bevel_edges

bevel_edges(object_name: str, width: float = 0.1, segments: int = 1, selection: str = 'ALL')

Bevel all edges of a mesh.

Returns Confirmation dict.

boolean_operation

boolean_operation(object_name: str, target_name: str, operation: str = 'DIFFERENCE')

Perform a boolean operation between two objects using a modifier. NOTE: For destructive booleans, prefer the booltool_auto_* tools instead (booltool_auto_union, booltool_auto_difference, booltool_auto_intersect, booltool_auto_slice). They handle selection and cutter cleanup automatically. Use this tool only when you need a non-destructive boolean modifier workflow.

Returns Confirmation dict with operation details.

bridge_edge_loops

bridge_edge_loops(object_name: str, segments: int = 1, profile_shape_factor: float = 0.0)

Bridge two edge loops to create connecting geometry. Select two edge loops on a mesh before calling this. The operation creates faces connecting the two loops, useful for connecting separate mesh parts, creating holes between surfaces, or building tube-like geometry.

Returns Confirmation dict with bridge details.

extrude_faces

extrude_faces(object_name: str, offset: float = 1.0, selection: str = 'ALL')

Extrude all faces of a mesh along their normals.

Returns Confirmation dict.

loop_cut

loop_cut(object_name: str, cuts: int = 1, selection: str = 'ALL')

Add loop cuts to a mesh object.

Returns Confirmation dict.

merge_vertices

merge_vertices(object_name: str, threshold: float = 0.0001, selection: str = 'ALL')

Merge vertices by distance.

Returns Confirmation dict with number of removed vertices.

remove_modifier

remove_modifier(object_name: str, modifier_name: str)

Remove a modifier from an object.

Returns Confirmation dict.

separate_mesh

separate_mesh(object_name: str, type: str = 'SELECTED')

Separate a mesh into parts.

Returns Confirmation dict.

set_modifier_property

set_modifier_property(object_name: str, modifier_name: str, property: str, value: Any)

Set a property on a modifier (e.g., levels, count, offset, angle).

Returns Confirmation dict with updated property.

set_smooth_shading

set_smooth_shading(object_name: str, smooth: bool = True)

Set smooth or flat shading on an object. TIP: For production use, prefer shade_auto_smooth which provides angle-based auto-smooth shading: it gives better results on hard-surface models by only smoothing faces within the angle threshold.

Returns Confirmation dict.

subdivide_mesh

subdivide_mesh(object_name: str, cuts: int = 1, selection: str = 'ALL')

Subdivide a mesh.

Returns Confirmation dict.

convert_object

convert_object(object_name: str, target: str = 'MESH')

Convert an object to a different type.

Returns Confirmation dict.

create_metaball

create_metaball(name: str = 'Metaball', elements: list[dict[str, Any]] | None = None, location: list[float] | None = None, resolution: float = 0.2, threshold: float = 0.6)

Create a metaball: soft elements that melt into one smooth surface. Good for organic blobs, liquid drops and quick character blocking. Turn it into an editable mesh with convert_object(target="MESH").

Returns Dict with the object name and element count.

create_object

create_object(type: str, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0), rotation: list[float] | tuple[float, ...] = (0, 0, 0), scale: list[float] | tuple[float, ...] = (1, 1, 1))

Create a primitive object in the scene.

Returns Dict with the created object's name, type, location, dimensions, and world-space bounds (min and max corner). Place the next part from the bounds: a nose cone sits at bounds.max z plus half its own height.

create_polygon_prism

create_polygon_prism(sides: int, radius: float = 1.0, depth: float = 2.0, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0), rotation: list[float] | tuple[float, ...] = (0, 0, 0), scale: list[float] | tuple[float, ...] = (1, 1, 1))

Create an N-sided regular prism (polygon-based cylinder). Useful for hex sockets, octagonal columns, triangular prisms, or any straight-sided geometry where a 32-sided round cylinder is the wrong primitive. For a hex socket cutter on an M3 button-head screw, use sides=6.

Returns Dict with the created object's name, type, location, and sides.

create_threaded_shaft

create_threaded_shaft(diameter: float, length: float, pitch: float, thread_depth: float = 0.0, segments: int = 32, thread_runout: float = -1.0, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0))

Create a cylindrical shaft with helical external threads. Produces a single mesh object: a threaded rod at the given diameter and length, with helical thread ridges following the specified pitch. Suitable for boolean-union onto a screw-head or direct use as a threaded fastener. Thread geometry: a 60-degree V profile swept along a Z-axis helix via the Screw modifier.

Returns Dict with the created object's name, diameter, length, pitch, and the number of thread iterations actually generated.

delete_object

delete_object(object_name: str)

Delete an object from the scene by name.

Returns Confirmation dict.

duplicate_object

duplicate_object(object_name: str, linked: bool = False)

Duplicate an object.

Returns Dict with the new object's name.

get_object_info

get_object_info(object_name: str)

Get detailed information about an object.

Returns Dict with type, location (as set), world_location (where it really is after parents, constraints and simulation), rotation, scale, dimensions, modifiers, materials, parent, children, and visibility.

join_objects

join_objects(names: list[str])

Join multiple mesh objects into one (keeps all geometry as-is). This merges objects into a single datablock without modifying geometry. The meshes remain separate inside the object (no boolean merge). TIP: If you want to truly fuse overlapping meshes into one solid shape, use booltool_auto_union instead: it performs a boolean union that merges the geometry and removes internal faces.

Returns Dict with the resulting object's name, the names that no longer exist, and a note saying so.

list_objects

list_objects(type_filter: str = '')

List all objects in the scene, optionally filtered by type.

Returns List of dicts with object name, type, and location.

make_single_user

make_single_user(object_name: str, object: bool = True, data: bool = True)

Make an object's data single-user (unlink shared datablocks).

Returns Confirmation dict.

parent_objects

parent_objects(child: str, parent: str)

Set parent-child relationship between two objects.

Returns Confirmation dict.

rename_object

rename_object(old_name: str, new_name: str)

Rename an object.

Returns Dict with old and new names.

select_objects

select_objects(names: list[str], deselect_others: bool = True)

Select whole objects in the scene by name. This is object-level selection, the kind that join_objects and delete_object act on. To select vertices, edges or faces inside one mesh, use select_by_index, select_by_axis or the other select_* tools in the Selection group.

Returns Dict with list of selected object names.

set_object_visibility

set_object_visibility(object_name: str, visible: bool, viewport: bool = True, render: bool = True)

Set object visibility in viewport and/or render.

Returns Confirmation dict with visibility state.

shade_auto_smooth

shade_auto_smooth(object_name: str, angle: float = 0.523599)

Apply angle-based auto-smooth shading to an object. Smooths faces only where the angle between adjacent face normals is below the given threshold, giving clean results on hard-surface models.

Returns Confirmation dict.

add_cloth_sim

add_cloth_sim(object_name: str, quality: int = 5, mass: float = 0.3)

Add a cloth physics simulation to an object.

Returns Confirmation dict with cloth settings.

add_collision

add_collision(object_name: str, thickness: float = 0.02, damping: float = 0.1, friction: float = 5.0, stickiness: float = 0.0, permeability: float = 0.0)

Make an object solid to cloth, particles and soft bodies. Without it, a cloth falls straight through the floor.

Returns Dict with the collision settings.

add_fluid_sim

add_fluid_sim(object_name: str, type: str = 'DOMAIN', domain_type: str = 'GAS')

Add a fluid physics simulation to an object.

Returns Confirmation dict with fluid settings.

add_force_field

add_force_field(type: str, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0), rotation: list[float] | tuple[float, ...] = (0, 0, 0), strength: float = 1.0, flow: float = 0.0, noise: float = 0.0, seed: int = 1, falloff_type: str = 'SPHERE', falloff_power: float = 0.0, max_distance: float = 0.0)

Add a force field that pushes cloth, particles, soft and rigid bodies.

Returns Dict with the field object's name and settings.

add_particle_system

add_particle_system(object_name: str, count: int = 1000, lifetime: float = 50.0, emit_from: str = 'FACE')

Add a particle system to an object.

Returns Confirmation dict with particle system settings.

add_rigid_body

add_rigid_body(object_name: str, type: str = 'ACTIVE', mass: float = 1.0, friction: float = 0.5, restitution: float = 0.0)

Add a rigid body physics simulation to an object.

Returns Confirmation dict with rigid body settings.

add_rigid_body_constraint

add_rigid_body_constraint(object1: str, object2: str, type: str = 'FIXED', empty_name: str = 'Constraint', location: list[float] | None = None, rotation: list[float] | None = None, breaking_threshold: float | None = None, disable_collisions: bool = True, settings: dict[str, Any] | None = None)

Join two rigid bodies with a physics constraint (glue, hinge, slider, spring, motor). Both objects need add_rigid_body first. The constraint lives on a new empty, placed at the midpoint unless location is given; HINGE turns around the empty's Z axis, SLIDER and PISTON move along its X.

Returns Dict with the empty, the type and the two objects.

add_soft_body

add_soft_body(object_name: str, mass: float = 1.0, goal: bool = True, goal_strength: float = 0.7, pull: float = 0.5, push: float = 0.5, bend: float = 0.0, damping: float = 0.5, friction: float = 0.5, self_collision: bool = False)

Make an object soft and wobbly: jelly, cushions, bellies, antennae. Bake it with bake_physics. With goal on, vertices are pulled back to their shape (higher goal_strength is stiffer); with goal off the object sags and bounces freely, like a water balloon. Add collision to the floor.

Returns Dict with the soft body settings.

bake_physics

bake_physics(object_name: str, physics_type: str = '')

Bake a physics simulation for an object.

Returns Confirmation dict.

delete_particle_system

delete_particle_system(object_name: str, particle_system_name: str = '')

Remove a particle system from an object.

Returns Confirmation dict.

set_particle_rendering

set_particle_rendering(object_name: str, render_type: str = 'PATH', instance_object: str = '', instance_collection: str = '')

Set rendering mode for an object's particle system.

Returns Confirmation dict.

set_particle_velocity

set_particle_velocity(object_name: str, normal: float = 1.0, tangent: float = 0.0, object_align_factor: list[float] | tuple[float, ...] = (0, 0, 0))

Set velocity settings for an object's particle system.

Returns Confirmation dict.

set_physics_property

set_physics_property(object_name: str, physics_type: str, property: str, value: Any)

Set a property on an existing physics simulation.

Returns Confirmation dict with property name and new value.

set_rigid_body_world

set_rigid_body_world(enabled: bool | None = None, time_scale: float | None = None, substeps_per_frame: int | None = None, solver_iterations: int | None = None, use_split_impulse: bool | None = None)

Tune the rigid body simulation for the scene, creating it if needed. Raise substeps_per_frame and solver_iterations when fast or stacked objects jitter, pass through each other, or joints stretch.

Returns Every rigid body world setting after the change.

check_3d_printability

check_3d_printability(object_name: str, checks: list[str] | None = None, overhang_angle: float | None = None, min_thickness: float | None = None, sharp_angle: float | None = None, nonplanar_angle: float | None = None, zero_threshold: float | None = None)

Check whether a mesh will 3D print, using Blender's 3D Print Toolbox. Catches three defects a mesh can carry while still passing analyze_mesh_quality, because each one leaves the mesh manifold, watertight and free of degenerate faces: - Bad contiguous edges: a shell whose normals agree with each other but collectively face inward. Recalculating normals reports nothing to fix, and the slicer rejects the file as having reversed faces. - Intersect faces: the surface passing through itself. - Thin faces: walls thinner than the nozzle, which slice away to nothing. It also reports shell count, zero-area faces and edges, non-flat faces, sharp edges and overhanging faces. Index lists are capped at 50 samples and can be fed straight to select_by_index to see the problem in Blender. Requires the 3D Print Toolbox extension, which ships with Blender but is off by default. If it is disabled this returns an error saying how to enable it; suggest_extensions also reports whether it is on.

Returns Dict with a count (and sample indices) per check that ran, plus checks_run, issues_found, and print_blocking: the defects that stop a print, as opposed to overhangs and sharp edges which are advisory.

manage_aov

manage_aov(action: str, name: str | None = None, type: str = 'COLOR')

List, add or remove shader AOVs: custom render passes written by materials. In a material, an Output AOV node (ShaderNodeOutputAOV, its aov_name set to this name) writes a color or value into the pass. Use for masks and IDs in compositing. The Render Layers node gets an output with the AOV name.

Returns Dict with every AOV (name, type).

set_color_management

set_color_management(view_transform: str = '', look: str = '', exposure: float | None = None, gamma: float | None = None, display_device: str = '', white_balance_temperature: float | None = None, working_space: str = '', convert_colors: bool = True)

Set how the scene's light becomes final pixel colours. AgX (the default) handles bright highlights gracefully; Standard is for flat graphics and UI shots; Khronos PBR Neutral keeps product colours true. A look adds contrast on top. Leave anything unset to keep it.

Returns Dict with the full colour management state after the change.

set_cycles_sampling

set_cycles_sampling(adaptive: bool | None = None, noise_threshold: float | None = None, min_samples: int | None = None, time_limit: float | None = None, clamp_direct: float | None = None, clamp_indirect: float | None = None, path_guiding: bool | None = None, seed: int | None = None, animated_seed: bool | None = None)

Tune how Cycles spends samples. Set the sample count with set_render_samples. Leave anything unset to keep it.

Returns Dict with the sampling settings after the change.

set_denoising

set_denoising(enabled: bool | None = None, denoiser: str = '', quality: str = '', prefilter: str = '', input_passes: str = '', use_gpu: bool | None = None, viewport: bool | None = None)

Configure Cycles denoising for final renders and the viewport. Denoising lets a render use far fewer samples: 128 denoised samples often beat 2048 raw ones. Leave anything unset to keep it.

Returns Dict with the denoising settings after the change.

set_eevee_quality

set_eevee_quality(raytracing: bool | None = None, ray_tracing_method: str = '', fast_gi: bool | None = None, fast_gi_method: str = '', shadow_pool_size: int | None = None, shadow_rays: int | None = None, shadow_steps: int | None = None, volumetric_samples: int | None = None, volumetric_tile_size: int | None = None, volumetric_shadows: bool | None = None, clamp_direct: float | None = None, clamp_indirect: float | None = None)

Tune EEVEE's reflections, global illumination, shadows and volumes. Leave anything unset to keep it.

Returns Dict with the EEVEE settings after the change.

set_film

set_film(transparent: bool | None = None, transparent_glass: bool | None = None, filter_width: float | None = None)

Set film options: transparent background and pixel filter.

Returns Dict with the film settings after the change.

set_freestyle

set_freestyle(enabled: bool = True, thickness: float | None = None, color: list[float] | None = None, edges: list[str] | None = None, crease_angle: float | None = None, as_render_pass: bool | None = None)

Draw ink lines over the render: outlines, toon, technical-drawing looks. Applies to the active view layer's line set (created if needed).

Returns Dict with the Freestyle state after the change.

set_light_group

set_light_group(group: str, objects: list[str] | None = None, world: bool = False, remove: bool = False)

Put lights (or emissive objects, or the world) into a light group. Each light group renders as its own pass (Cycles), so light balance can be changed in the compositor without re-rendering: the Render Layers node gets a Combined_<group> output. The group is created if needed.

Returns Dict with the group name used and every light group with its members.

set_light_paths

set_light_paths(total: int | None = None, diffuse: int | None = None, glossy: int | None = None, transmission: int | None = None, volume: int | None = None, transparent: int | None = None, caustics_reflective: bool | None = None, caustics_refractive: bool | None = None, filter_glossy: float | None = None)

Set Cycles light bounce limits and caustics. Fewer bounces render faster; glass and liquids need enough transmission bounces or they turn black. Each bounce count is 0 to 1024. Leave anything unset to keep it.

Returns Dict with the light path settings after the change.

set_motion_blur

set_motion_blur(enabled: bool | None = None, shutter: float | None = None, position: str = '', eevee_steps: int | None = None)

Set render motion blur for moving objects and cameras.

Returns Dict with the motion blur settings after the change.

set_object_ray_visibility

set_object_ray_visibility(object_name: str, camera: bool | None = None, diffuse: bool | None = None, glossy: bool | None = None, transmission: bool | None = None, volume_scatter: bool | None = None, shadow: bool | None = None, holdout: bool | None = None, shadow_catcher: bool | None = None)

Choose which rays see an object: hide it from the camera but keep its shadow, keep it out of reflections, or turn it into a shadow catcher. Leave anything unset to keep it.

Returns Dict with every visibility flag after the change.

set_render_passes

set_render_passes(passes: list[str], enabled: bool = True)

Turn render passes on or off for the active view layer. Passes are extra images saved with a multilayer EXR or used in the compositor: depth for fog and focus, mist, normals, cryptomatte masks for picking objects later.

Returns Dict with the view layer name and the passes changed.

set_render_performance

set_render_performance(simplify: bool | None = None, max_subdivision: int | None = None, texture_limit: str = '', texture_resolution: float | None = None, persistent_data: bool | None = None, auto_tile: bool | None = None, tile_size: int | None = None, anisotropic_filter: int | None = None)

Speed up heavy renders or fit them in memory. Leave anything unset to keep it.

Returns Dict with the performance settings after the change.

render_animation

render_animation(filepath: str = '', format: str = 'PNG')

Render the animation sequence to image files.

Returns Confirmation dict with output details.

render_image

render_image(filepath: str = '')

Render the current scene to an image file.

Returns Confirmation dict with the output file path.

set_eevee_light_path

set_eevee_light_path(direct_intensity: float | None = None, indirect_intensity: float | None = None)

Set EEVEE light intensity controls (Blender 5.1+). Scales how strongly direct and indirect lighting contribute. Only applies when the render engine is EEVEE.

Returns Dict with both intensities after the change.

set_output_format

set_output_format(format: str, filepath: str = '')

Set the render output format and optionally the output file path.

Returns Confirmation dict with the new output settings.

set_render_engine

set_render_engine(engine: str)

Set the render engine.

Returns Confirmation dict with the active render engine.

set_render_resolution

set_render_resolution(width: int, height: int, percentage: int = 100)

Set the render resolution.

Returns Confirmation dict with the new resolution settings.

set_render_samples

set_render_samples(samples: int)

Set the number of render samples.

Returns Confirmation dict with the new sample count.

create_scene

create_scene(name: str)

Create a new scene.

Returns Confirmation dict with the created scene name.

delete_scene

delete_scene(scene_name: str)

Delete a scene by name.

Returns Confirmation dict.

get_scene_info

get_scene_info()

Get full scene information including object tree, hierarchy, counts, frame range, fps, and render engine. Returns a dict with scene name, object list with hierarchy, object type counts, frame range (start, end, current), fps, and active render engine.

list_scenes

list_scenes()

List all scenes in the current Blender file. Returns a list of dicts, each containing the scene name and object count.

set_scene_property

set_scene_property(property: str, value: Any)

Set a scene property such as frame_start, frame_end, frame_current, fps, unit_system, or render_engine.

Returns Confirmation dict with the property name and new value.

set_units

set_units(system: str | None = None, scale_length: float | None = None, length_unit: str | None = None, mass_unit: str | None = None, time_unit: str | None = None, temperature_unit: str | None = None, rotation: str | None = None, use_separate: bool | None = None)

Set the scene's units, for real-world sizes (e.g. a 3D print in millimetres). Only the settings given are changed. Unit names depend on the system: METRIC lengths are KILOMETERS, METERS, CENTIMETERS, MILLIMETERS, MICROMETERS; IMPERIAL lengths are MILES, FEET, INCHES, THOU. ADAPTIVE picks per value.

Returns Every unit setting after the change.

suggest_extensions

suggest_extensions(task_description: str = '')

Suggest helpful Blender extensions for a planned task. Analyzes the task description and recommends free Blender extensions that could improve the workflow. Already-installed extensions are excluded.

Returns Dict with 'suggestions' list of recommended extensions and 'installed' list of already-installed extension IDs.

add_multires_modifier

add_multires_modifier(object_name: str, levels: int = 2)

Add a Multiresolution modifier for sculpting detail.

Returns Dict with object name and modifier info.

enable_dyntopo

enable_dyntopo(object_name: str, detail_size: float = 12.0, detail_mode: str = 'RELATIVE')

Enable dynamic topology (dyntopo) for adaptive sculpting resolution. Dyntopo adds and removes mesh detail dynamically as you sculpt, allowing unlimited detail where needed without uniform subdivision.

Returns Confirmation dict with dyntopo settings.

enter_sculpt_mode

enter_sculpt_mode(object_name: str)

Enter sculpt mode for a mesh object.

Returns Confirmation dict with object name and mode.

exit_sculpt_mode

exit_sculpt_mode()

Exit sculpt mode and return to object mode.

Returns Confirmation dict with current mode.

remesh

remesh(object_name: str, voxel_size: float = 0.1, mode: str = 'VOXEL')

Remesh an object to create a clean topology.

Returns Dict with object name and new vertex count.

set_brush_property

set_brush_property(property: str, value: Any)

Set a property on the active sculpt brush.

Returns Confirmation dict with property name and new value.

set_face_sets

set_face_sets(object_name: str, mode: str, face_indices: list[int] | None = None, face_set: int = 1)

Split a mesh into face sets: colored regions for sculpting one part at a time. In sculpt mode, face sets can be hidden or isolated, and brushes and automasking can stay within one set.

Returns Dict with the number of distinct face sets.

set_sculpt_brush

set_sculpt_brush(brush_type: str)

Set the active sculpt brush.

Returns Confirmation dict with active brush type.

set_sculpt_mask

set_sculpt_mask(object_name: str, value: float = 1.0, vertex_indices: list[int] | None = None, vertex_group: str | None = None, invert: bool = False, clear: bool = False)

Mask part of a mesh so sculpt brushes and filters leave it alone. 1.0 is fully protected, 0.0 is free to sculpt. Works in any mode.

Returns Dict with how many vertices are masked (above 0) and the vertex count.

set_sculpt_symmetry

set_sculpt_symmetry(use_x: bool = True, use_y: bool = False, use_z: bool = False)

Set sculpt symmetry axes. Enables symmetrical sculpting across the specified axes. X-axis symmetry is the most common for character modeling.

Returns Confirmation dict with symmetry settings.

get_selection

get_selection(object_name: str)

Report what is currently selected on a mesh. Without this a caller cannot see the result of its own selection, and the mesh tools that act on the current selection would be operating blind.

Returns Dict with selected and total counts per element type, and the first 50 selected indices of each, so a caller can confirm before acting.

select_all_geometry

select_all_geometry(object_name: str, action: str = 'SELECT')

Select, deselect or invert all vertices, edges and faces on one mesh. Acts inside a mesh. To select whole objects in the scene, use select_objects.

Returns Dict with the counts selected afterwards.

select_by_axis

select_by_axis(object_name: str, axis: str = 'Z', sign: str = 'POS', extend: bool = False)

Select the vertices, edges and faces on one side of a mesh along an axis. The usual way to say "the top", "the front" or "the left half" of one object. To select whole objects in the scene, use select_objects.

Returns Dict with how many elements were selected.

select_by_index

select_by_index(object_name: str, element: str, indices: list[int], extend: bool = False)

Select specific vertices, edges or faces of one mesh by index. The deterministic way to select: no operator, no viewport, no guessing. analyze_mesh_quality reports sample indices for each defect it finds, so this is how to act on them. To select whole objects in the scene, use select_objects.

Returns Dict with how many elements were selected and the mesh's totals.

select_faces_by_sides

select_faces_by_sides(object_name: str, number: int = 4, comparison: str = 'EQUAL', extend: bool = False)

Select faces of one mesh by how many sides they have. The direct way to find ngons (GREATER than 4) or triangles (EQUAL to 3), which is what topology cleanup usually needs. Works inside one mesh; to select whole objects use select_objects.

Returns Dict with how many faces were selected.

select_similar

select_similar(object_name: str, type: str = 'FACE_AREA', threshold: float = 0.0)

Grow the current mesh selection to vertices, edges or faces that resemble it. Requires something to already be selected: it compares against that. Works inside one mesh; it does not pick objects (see select_objects).

Returns Dict with how many elements were selected.

add_image_sequence_strip

add_image_sequence_strip(first_frame: str, name: str = '', channel: int = 1, frame_start: int = 1)

Add rendered frames to the sequencer as one image strip. Give the first frame of a numbered sequence, such as the output of render_animation. Every file in the same folder that shares its prefix and extension is added in numeric order, one image per timeline frame.

Returns Dict with the strip name, image count, and the frames it covers.

add_sequencer_strip

add_sequencer_strip(kind: str, name: str = '', channel: int = 1, frame_start: int = 1, length: int = 25, text: str = '', font_size: float = 60.0, color: list[float] | None = None, filepath: str = '')

Add a text, solid colour or movie strip to the video sequencer. Higher channels draw on top. Style text or move any strip afterwards with set_strip_property; fade it with add_strip_fade.

Returns Dict with the strip's name, type, channel and frame range.

add_sound_strip

add_sound_strip(filepath: str, name: str = '', channel: int = 2, frame_start: int = 1, start_offset: float = 0.0, volume: float = 1.0)

Add an audio file to the sequencer as a sound strip.

Returns Dict with the strip name and the frames it covers.

add_strip_fade

add_strip_fade(strip_name: str, fade_in: int = 0, fade_out: int = 0)

Fade a strip in from black and/or out to black (sound strips fade their volume).

Returns Dict with the strip and the frames keyed.

list_strips

list_strips()

List every strip in the sequencer.

Returns List of dicts with name, type, channel, and first and last frame.

remove_strip

remove_strip(strip_name: str)

Remove a strip from the sequencer by name.

Returns Confirmation dict.

render_video

render_video(filepath: str = '', container: str = 'MPEG4', quality: str = 'HIGH', audio_codec: str = 'AAC')

Render the scene's frame range to a single video file, with sound. Sequencer strips are used when there are any, so frames already rendered with render_animation can be assembled with a sound strip in seconds. With an empty sequencer the 3D scene is rendered. Playback speed follows the scene fps.

Returns Dict with the output path, frame range, and fps.

set_strip_property

set_strip_property(strip_name: str, settings: dict[str, Any] | None = None, transform: dict[str, float] | None = None, crop: dict[str, float] | None = None)

Change a sequencer strip: its own settings, position and crop.

Returns Dict with the strip's name, type, channel and frame range.

analyze_sweep_path

analyze_sweep_path(path_points: list[list[float]], radius: float = 1.0, resolution: int = 0)

Check whether a path can carry a profile of a given radius, without building it. Where a path's radius of curvature falls below the profile radius, the swept rings pass through each other on the inside of the bend. The result still reports as watertight and manifold with no degenerate faces, so no ordinary mesh check catches it. Call this before sweeping, or to find where an existing path needs widening.

Returns Dict with min_clearance_ratio (curvature radius over profile radius at the tightest station; below 1.0 self-intersects), tightest_index, tightest_point, self_intersects, and counts of stations below 1.0 and below 1.5. Aim for 1.5 or more for a clean surface.

sweep_profile_along_path

sweep_profile_along_path(path_points: list[list[float]], profile: str = 'CIRCLE', radius: float = 1.0, sides: int = 16, resolution: int = 0, twist: float = 0.0, caps: bool = True, name: str = 'Sweep')

Sweep a closed profile along a 3D path to make a solid tube, pipe, cable or rope. Use this for anything that follows a route: hoses, handrails, wires, vines, tentacles, roads. It orients the profile with parallel transport, so the tube never creases or folds where the path turns vertical, and it reports whether any bend is too tight for the profile to fit around.

Returns Dict with the object name, vertex and face counts, and a validity report: min_clearance_ratio (path curvature radius over profile radius at the tightest point), tightest_point, and self_intersects. A ratio below 1.0 means rings overlap inside the bend, so the result is watertight but is not a solid.

apply_transforms

apply_transforms(object_name: str, location: bool = True, rotation: bool = True, scale: bool = True)

Apply (freeze) transforms on an object, making current transforms the new basis.

Returns Confirmation dict.

set_location

set_location(object_name: str, location: Vector3)

Set the position of an object.

Returns Dict with the object name and new location.

set_origin

set_origin(object_name: str, type: str = 'GEOMETRY')

Set the origin point of an object.

Returns Confirmation dict with new origin location.

set_rotation

set_rotation(object_name: str, rotation: Vector3, mode: str = 'EULER')

Set the rotation of an object.

Returns Dict with the object name and new rotation.

set_scale

set_scale(object_name: str, scale: Vector3)

Set the scale of an object.

Returns Dict with the object name and new scale.

snap_to_grid

snap_to_grid(object_name: str, grid_size: float = 1.0)

Snap an object's location to the nearest grid point.

Returns Dict with the object name and snapped location.

get_texel_density

get_texel_density(object_name: str, texture_size: int = 1024)

Measure texel density: how many texture pixels cover one metre of surface. Matching density across assets keeps texture sharpness consistent; game art often targets 512 or 1024 px/m.

Returns Dict with density in px/m, surface area in m^2 (world scale), and the share of UV space used.

manage_uv_map

manage_uv_map(object_name: str, action: str, uv_map: str = 'UVMap', new_name: str | None = None, copy_active: bool = True)

List, add, remove, rename UV maps, or choose which one is edited or rendered. A mesh holds up to 8 UV maps. Common use: ADD a "Lightmap" map, then smart_uv_project or pack_uv_islands on it for non-overlapping bake UVs, while textures keep using the first map. UV tools work on the active map; materials and export use the render map unless a UV Map node picks one.

Returns Dict with every UV map (name, active, render).

pack_uv_islands

pack_uv_islands(object_name: str, margin: float = 0.001, rotate: bool = True, rotate_method: str = 'ANY', scale: bool = True)

Pack UV islands to fit efficiently within the UV space.

Returns Confirmation dict with object name.

set_texel_density

set_texel_density(object_name: str, density: float, texture_size: int = 1024)

Scale an object's UVs to hit a target texel density. Islands keep their layout and scale about their shared centre, so they may spill outside the 0-1 square; pack afterwards with pack_uv_islands(scale=False) to bring them back without undoing this.

Returns Dict with the density before and after.

set_uv_projection

set_uv_projection(object_name: str, projection: str)

Apply a projection-based UV mapping to a mesh object.

Returns Confirmation dict with object name and projection type.

smart_uv_project

smart_uv_project(object_name: str, angle_limit: float = 66.0, island_margin: float = 0.0, area_weight: float = 0.0)

Apply Smart UV Project to a mesh object. Automatically unwraps the mesh using angle-based projection.

Returns Confirmation dict with object name and UV map info.

uv_island_operation

uv_island_operation(object_name: str, operation: str, selection: str = 'ALL', iterations: int = 20, rotation: float = 0.0, scale_variation: float = 0.0, offset: float = 0.0, seed: int = 0, margin: float = 0.05, threshold: float = 0.0001)

Tidy UV islands after unwrapping.

Returns Dict with the operation and the object.

uv_unwrap

uv_unwrap(object_name: str, method: str = 'ANGLE_BASED')

Unwrap a mesh object's UVs using standard unwrap. Requires seams to be marked for best results.

Returns Confirmation dict with object name.

focus_on_object

focus_on_object(object_name: str)

Frame/focus the viewport on a specific object. Selects the object and uses View Selected to center the viewport on it.

Returns Confirmation dict.

set_viewport_overlay

set_viewport_overlay(overlay: str, enabled: bool)

Toggle a viewport overlay setting.

Returns Confirmation dict with the overlay name and state.

set_viewport_shading

set_viewport_shading(mode: str)

Set the viewport shading mode.

Returns Confirmation dict with the new shading mode.

get_viewport_screenshot

get_viewport_screenshot(max_size: int = 1000, mode: str = 'fast')

Capture a screenshot of the current Blender 3D viewport.

Returns Dict with base64-encoded PNG image data, width, height, format, and mode.