AGENT SKILL

blender-addon-development

Write Blender 5.2 add-ons as extensions - blender_manifest.toml, operators/panels/menus/property groups/preferences, bpy.props rules after 5.0, undo/redo, modal and timer patterns, gpu drawing (no bgl), bundling Python wheels, CLI validate/build/install, testing headless, extensions platform publishing. Use when creating or fixing a Blender add-on, tool, or UI.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1
Forks
1

01 前言 Front Matter

name
blender-addon-development
license
MIT
metadata
{ "author": "blender-agent-skills", "version": "1.2.0" }
description
Write Blender 5.2 add-ons as extensions - blender_manifest.toml, operators/panels/menus/property groups/preferences, bpy.props rules after 5.0, undo/redo, modal and timer patterns, gpu drawing (no bgl), bundling Python wheels, CLI validate/build/install, testing headless, extensions platform publishing. Use when creating or fixing a Blender add-on, tool, or UI.

02 资源文件 4

03 SKILL.md 正文

Add-on (Extension) Development

The execution model is in blender-core. Start from assets/addon_template/ (validated, built, and registered in CI): blender_manifest.toml, __init__.py, operators.py, ui.py.

Procedure

  1. Copy the template, then set id (lowercase_underscores, permanent), name, tagline (no trailing period, ≤ 64 chars), maintainer, version (semver), license (SPDX, GPL-3.0-or-later for code using bpy), and blender_version_min = "4.2.0" or higher if you use newer APIs (e.g. "5.2.0" for the GN properties.inputs API).
  2. Write classes with the prefix convention MYTOOL_OT_x (operator), _PT_ (panel), _MT_ (menu), _PG_ (property group), _AP_ (preferences), _UL_ (UI list). bl_idname for operators is my_tool.verb_noun.
  3. Validate and build:
    blender --command extension validate ./my_tool
    blender --command extension build --source-dir ./my_tool --output-dir ./dist
    blender --command extension install-file -r user_default -e ./dist/my_tool-1.0.0.zip
    
  4. Test headless: register the package in-process, call operators with temp_override, and assert on data (see tests/test_addon.py in this repo).

Rules (extension-era, 5.x)

  • Relative imports only (from . import ops). The package name is decided by Blender, so preferences use bl_idname = __package__.
  • No bl_info (it's ignored for extensions). Everything goes in the manifest.
  • No network or file access at import/register time. Declare [permissions] (files, network, clipboard, camera, microphone) with a reason. Check bpy.app.online_access before any network call.
  • Third-party Python packages: ship .whl files in ./wheels/ and list them under wheels = [...]. Never pip install at runtime. Platform-specific wheels require platforms = [...].
  • Properties (5.0+): bpy.props values are attributes, not dict entries (scene["my_prop"] no longer reaches them). For read-only props use options={'READ_ONLY'}. get_transform/set_transform adapt values while keeping storage. Register with PointerProperty(type=PG) on an ID type, and del it on unregister.
  • Operators: bl_options={"REGISTER","UNDO"} for undo plus a redo panel. poll() guards the context. Return {"FINISHED"}/{"CANCELLED"}. self.report({"WARNING"}, msg) for user feedback. Don't call other operators in loops if a data API exists.
  • UI: layout.use_property_split = True gives modern alignment. Panels in the N-panel use bl_region_type="UI" + bl_category. Append menu entries with VIEW3D_MT_*.append(func) and remove them on unregister.
  • Unregister everything in reverse order (classes, props, menus, handlers, timers, keymaps, draw handlers). Leaks break reloading.
  • Drawing (overlays): gpu module + gpu_extras.batch. bgl was removed in 5.0. Textures come from gpu.texture.from_image(img). For scene-linear images use draw_texture_2d(..., is_scene_linear_with_rec709_srgb_target=True).
  • Long tasks: a modal operator with a timer (wm.event_timer_add), or bpy.app.timers.register with chunked work. Never block the UI for seconds.
  • Handlers: decorate persistent ones with @bpy.app.handlers.persistent. Keep them cheap (they run every frame/depsgraph update).
  • Keymaps: add them to wm.keyconfigs.addon, store (km, kmi) pairs, and remove them on unregister.
  • Translations / i18n: bpy.app.translations.register(__package__, dict).

Publishing (extensions.blender.org)

The Blender ID account uploads the built zip. Requirements: a valid manifest, a GPL-compatible license, no obfuscated code, no bundled binaries without source, and permissions declared. Screenshots/README go on the website listing. Update with a higher version.

Gotchas

  • context.scene inside a draw function can be None in some editors. Guard it.
  • Storing Blender data references (bpy.types.ID) in Python globals crashes after undo or file load. Store names or session_uid, and look them up again.
  • bpy.utils.register_class fails if annotations use = instead of : for properties.
  • 5.0 made several bundled modules private (rna_info, bl_ui_utils...). Don't import them.
  • 5.1 no longer loads the user site-packages by default. Bundle wheels instead of relying on user installs.
  • 5.2: PreferencesFilePaths.active_asset_library indices are offset (the "All"/"Essentials" entries come first). UILayout.template_palette(color=) is removed. New: UILayout.link, UILayout.textbox, bpy.data.all_ids, Window.screenshot.

04 同仓库更多 Skills

MattMakes
MattMakes/multi-herdr

blender-workflow-recipes

End-to-end Blender 5.2 playbooks chaining the blender-* skills with QA gates - game props (mid-poly, high-to-low), game characters (sculpt/AI mesh to rigged, animated export), Roblox props/accessories/avatars, AI or downloaded asset cleanup, procedural environments, web/AR assets, product turntables, mood/weather shots (night, rain, snow, fog). Use for complete multi-stage asset requests.

★ 1
MattMakes
MattMakes/multi-herdr

blender-weather-fx

Weather effects in Blender 5.2 - looping Geometry Nodes rain, snow, dust, ash and embers with ground hits and splashes, wet surfaces, puddles with animated ripples, wall streaks, snow cover (shader + real snow geometry), storm lightning with multi-stroke flashes and bolts, engine-ready weather masks. Use for rain, storm, snow, wet street, puddle, dust or ember scenes.

★ 1
MattMakes
MattMakes/multi-herdr

blender-video-editing

Video in Blender 5.2 - Video Sequencer edits from Python (clips, image sequences, crossfades, titles, music fades, proxies, color management, H.264/AAC output) and motion tracking (feature detection, camera solve, scene orientation, tripod and plane tracking, stabilization) for VFX shots. Use to cut renders/footage together or match-move a camera.

★ 1
MattMakes
MattMakes/multi-herdr

blender-time-of-day

Time of day and atmosphere in Blender 5.2 - measured sky + sun for dawn, morning, noon, golden hour, sunset, blue hour, overcast, night/moonlight with stars and city glow, exposure balance, height fog from visibility, god rays, Cycles vs EEVEE volumes, compositor grade, stylized moods (cyberpunk neon, horror, underwater, desert). Use for any day/night, sunset, foggy or mood lighting scene.

★ 1
MattMakes
MattMakes/multi-herdr

blender-texturing

Texture authoring in Blender 5.2 - smart-material layers (edge wear, cavity grime, dust, rust, roughness breakup) from curvature/AO masks, z-fight-safe decal and sticker placement, trim sheets, tiling + vertex-color blends, texture painting, baking the look to game texture sets. Use when a material needs wear, dirt, a decal, trims or hand painting, not just wiring.

★ 1
MattMakes
MattMakes/multi-herdr

blender-texture-baking

Bake texture maps in Blender 5.2 Cycles - high-to-low normal maps with cage/extrusion, AO, curvature, ID, thickness, base color/roughness/metallic from procedurals, ORM packing, OpenGL vs DirectX, margins, GPU baking, fixing skewing/waviness/seams. Use when transferring sculpt or high-poly detail to game meshes or converting procedural materials to textures.

★ 1