blender-rulesBlender Python anti-pattern rules (bmesh leaks, bpy.ops in loops, deprecated context-copy overrides, bulk mesh writes, prop annotations and context guards, Extensions manifest, import scale, export modifiers, glTF/FBX axis RNA, the removed bgl module, the normals API removed in 4.1). Use when writin
live-blender-sessionWork against the user's running Blender through the Blender Lab MCP server (the blender tools): read the scene with the summary, screenshot and docs tools before touching anything, save before any execute_blender_code call that mutates, prototype live, then hand back a script proven with blender --b
addon-scaffoldingScaffold a Blender add-on as an Extensions Platform package: blender_manifest.toml, modular file layout, register_classes_factory, symmetric register/unregister. Use when the user starts a new add-on or extension, writes or fixes blender_manifest.toml, asks which layout or registration pattern to us
ai-mesh-cleanupOrdered cleanup for an imported generated or scanned mesh before it goes to an engine: scene units, apply rotation and scale, origin to base, recalculate normals, evaluated triangle count, decimate to a budget, convex collider. Use when the user has a GLB, glTF or FBX that is not engine-ready, menti
bake-high-to-lowCage-bake high-poly surface detail onto a low-poly target as a tangent-space normal map with bpy.ops.object.bake (Cycles, selected-to-active, active Image Texture node, UV layer, save_render). Use when the user wants a normal map from a dense mesh onto a game-resolution or decimated LOD, mentions ca
bl-info-migrationMigrate a legacy bl_info add-on to the Extensions Platform in three steps, with a before/after diff and the dual-format pattern. Use when the user has a bl_info dictionary in __init__.py, asks whether bl_info is deprecated or still supported, wants to publish to extensions.blender.org or ship an ext
compositor-nodesBuild and render through the scene compositor from Python across the 4.5 LTS to 5.x split: scene.use_nodes plus scene.node_tree and a Composite node on 4.5, a CompositorNodeTree node group assigned to scene.compositing_node_group with interface sockets and a Group Output on 5.x, a Render Layers to G
constraints-and-parentingParent objects without moving them, aim them with constraints, and author empties as engine attach sockets, all on the data API: child.parent plus matrix_parent_inverse = parent.matrix_world.inverted(), stale matrix_world until view_layer.update(), Object.constraints.new('DAMPED_TRACK') read back th
curves-and-textBuild legacy Curve and TextCurve datablocks from Python: bpy.data.curves.new(type='CURVE' or 'FONT'), splines.new('BEZIER'), bezier_points.add, handle types, bevel_depth, bevel_resolution, resolution_u, use_fill_caps, extrude, TextCurve.body, align_x/align_y, the built-in Bfont, and reading the tess
custom-propertiesDefine and bind custom properties with bpy.props annotations, PropertyGroup and PointerProperty, and choose where to store them (Scene, Object, WindowManager, AddonPreferences). Use when the user attaches settings or data to datablocks so it survives save and load, is unsure where add-on settings be
depsgraph-and-evaluated-dataRead the evaluated geometry the user actually sees through the dependency graph instead of raw obj.data: evaluated_depsgraph_get, evaluated_get, to_mesh and to_mesh_clear lifetimes. Use when the user writes an exporter, measurement or inspection script, reports that modifiers, shape keys, armatures
drivers-and-app-handlersDrive properties from expressions with the Driver API (driver_add, driver_namespace for custom Python functions) and react to events with bpy.app.handlers (load_post, save_pre, frame_change_post, depsgraph_update_post, exit_pre in 5.1+). Use when the user wants one property to follow another, runs c
engine-export-presetsExport presets for Unity, Godot and Unreal. glTF is +Y up and meters by spec, so every engine gets export_yup=True with no scale bake (Unreal converts to centimeters on import); FBX takes axis_forward/axis_up plus global_scale. Use when the user exports for a game engine, mentions export_yup, axis_f
extension-runtime-and-packagingShip and run a Blender extension after its first install: bundled wheels, user data that survives upgrades via bpy.utils.extension_path_user, the network permission and bpy.app.online_access, bl_ext package names, and blender --command extension validate/build/server-generate in CI. Use when the use
geometry-nodes-pythonBuild Geometry Nodes trees from Python: node_groups.new, tree.interface sockets, nodes by RNA identifier, links, Repeat and for-each zones, Bundles, and applying the tree as a NODES modifier including the 5.1 vs 5.2 modifier input API. Use when the user generates a GeometryNodeTree in a script, sets
gpu-drawing-and-overlaysDraw viewport overlays and offscreen images with the gpu module instead of the removed bgl: SpaceView3D.draw_handler_add/remove symmetry, gpu.shader.from_builtin names, gpu_extras.batch.batch_for_shader, gpu.state for blending, depth and line width (POLYLINE shaders), blf text, tag_redraw, and GPUOf
grease-pencil-v3Create and inspect Grease Pencil v3 (GPv3) data from Python: the datablock address split (bpy.data.grease_pencils_v3 on 4.5 LTS, bpy.data.grease_pencils on 5.x), layers.new -> frames.new(n).drawing -> add_strokes([counts]) -> per-point position/radius/opacity/vertex_color, lazily materialized drawin
headless-batch-scriptingRun Blender unattended with blender --background --python, arguments after the -- separator, --factory-startup and --python-exit-code, and temp_override for operators that need context. Use when the user renders, exports or processes .blend files from a CLI, CI job or batch script, passes arguments
images-and-pixelsCreate and edit bpy.types.Image pixel buffers from Python: bpy.data.images.new, Image.pixels bulk access with foreach_get/foreach_set, the flat always-RGBA bottom-left-origin layout, byte vs float_buffer storage, colorspace_settings, and saving PNG vs OpenEXR with alpha through Image.save (filepath_
mesh-editing-and-bmeshCreate, edit and read meshes efficiently: when to use bpy.data, bpy.ops or bmesh, the bmesh.new / try / finally / free pattern, foreach_get and foreach_set for bulk data, and evaluated meshes for modifier results. Use when the user writes mesh-generating or mesh-editing Python, mentions bmesh, from_
operatorsAuthor bpy.types.Operator classes: bl_idname naming, poll / invoke / execute / modal lifecycle, bl_options (REGISTER, UNDO, INTERNAL, BLOCKING), operator properties and defensive context handling. Use when the user creates an operator for a button, menu, keymap or script, asks why its properties are
porting-to-blender-5Port an add-on or script from Blender 3.x/4.x to 5.x (5.2 LTS) while keeping 4.5 LTS working: a triage recipe that runs the code headless on the target version and maps each traceback to its fix, and one table of every break the pack covers (bgl, action.fcurves, use_auto_smooth, Principled sockets,
procedural-materials-and-shadersBuild materials and shader node graphs from Python: bpy.data.materials, node_tree, Principled BSDF and its 4.0+ socket names, default values, links and shader node groups, for EEVEE and Cycles. Use when the user creates or edits materials in a script, generates many material variations, hits a KeyEr
slotted-actions-animationCreate and edit animation from Python under Slotted Actions (Blender 4.4+): Action, slots, layers, strips, channelbags. Bind the action slot, then reach F-curves through a channelbag; action_ensure_channelbag_for_slot exists only on 5.0+, so use strip.channelbag(slot, ensure=True) on 4.5 LTS. Use wh
timers-modal-and-threadingRun long or repeated work in a Blender add-on without freezing or crashing it: bpy.app.timers return values and persistent=True, modal operators driven by event_timer_add, and worker threads that hand results to the main thread through a queue. Use when the user polls, animates or downloads from an
ui-panelsAuthor bpy.types.Panel UI: bl_space_type, bl_region_type, bl_category sidebar tabs, declarative draw(), layout row, column and split, sub-panels, and conditional UI with enabled and active. Use when the user adds an N-panel tab or properties-editor panel, exposes add-on properties or operator button
uv-and-mesh-attributesAuthor per-loop and per-vertex mesh data from Python: UV layers (mesh.uv_layers.new, bmesh loops.layers.uv, the calc_uvs=True silent no-op), a second lightmap UV channel and its active / active_render flags, loop tangents (calc_tangents, bitangent_sign), color attributes and their CORNER vs POINT do
vse-pythonBuild and inspect Video Sequence Editor timelines from Python: SequenceEditor.strips vs the removed .sequences, new_effect length vs frame_end, strip transforms, and the 5.2 COLOR strip width/height bake from scene resolution. Use when the user scripts the sequencer, hits AttributeError on sequence_