blender-addon-development
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAdd-on (Extension) Development
Add-on(Extension)开发
The execution model is in . Start from (validated, built, and registered in CI): , , , .
blender-coreassets/addon_template/blender_manifest.toml__init__.pyoperators.pyui.py执行模型位于 。从 开始(已在 CI 中完成验证、构建和注册):、、、。
blender-coreassets/addon_template/blender_manifest.toml__init__.pyoperators.pyui.pyProcedure
操作步骤
- Copy the template, then set (lowercase_underscores, permanent),
id,name(no trailing period, ≤ 64 chars),tagline,maintainer(semver),version(SPDX, GPL-3.0-or-later for code using bpy), andlicenseor higher if you use newer APIs (e.g.blender_version_min = "4.2.0"for the GN"5.2.0"API).properties.inputs - Write classes with the prefix convention (operator),
MYTOOL_OT_x(panel),_PT_(menu),_MT_(property group),_PG_(preferences),_AP_(UI list)._UL_for operators isbl_idname.my_tool.verb_noun - 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 - Test headless: register the package in-process, call operators with , and assert on data (see
temp_overridein this repo).tests/test_addon.py
- 复制模板,然后设置 (lowercase_underscores,永久不变)、
id、name(末尾不要加句点,≤ 64 个字符)、tagline、maintainer(semver)、version(SPDX;使用 bpy 的代码应采用 GPL-3.0-or-later),以及license;如果使用较新的 API,则设置更高的版本,例如 GNblender_version_min = "4.2.0"API 对应properties.inputs。"5.2.0" - 编写类时遵循前缀约定:(operator)、
MYTOOL_OT_x(panel)、_PT_(menu)、_MT_(property group)、_PG_(preferences)、_AP_(UI list)。operator 的_UL_应为bl_idname。my_tool.verb_noun - 验证并构建:
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 - 进行 headless 测试:在进程内注册 package,使用 调用 operators,并对数据进行断言(参见本仓库中的
temp_override)。tests/test_addon.py
Rules (extension-era, 5.x)
规则(extension 时代,5.x)
- Relative imports only (). The package name is decided by Blender, so preferences use
from . import ops.bl_idname = __package__ - No (it's ignored for extensions). Everything goes in the manifest.
bl_info - No network or file access at import/register time. Declare (
[permissions],files,network,clipboard,camera) with a reason. Checkmicrophonebefore any network call.bpy.app.online_access - Third-party Python packages: ship files in
.whland list them under./wheels/. Neverwheels = [...]at runtime. Platform-specific wheels requirepip install.platforms = [...] - Properties (5.0+): values are attributes, not dict entries (
bpy.propsno longer reaches them). For read-only props usescene["my_prop"].options={'READ_ONLY'}/get_transformadapt values while keeping storage. Register withset_transformon an ID type, andPointerProperty(type=PG)it on unregister.del - Operators: for undo plus a redo panel.
bl_options={"REGISTER","UNDO"}guards the context. Returnpoll()/{"FINISHED"}.{"CANCELLED"}for user feedback. Don't call other operators in loops if a data API exists.self.report({"WARNING"}, msg) - UI: gives modern alignment. Panels in the N-panel use
layout.use_property_split = True+bl_region_type="UI". Append menu entries withbl_categoryand remove them on unregister.VIEW3D_MT_*.append(func) - Unregister everything in reverse order (classes, props, menus, handlers, timers, keymaps, draw handlers). Leaks break reloading.
- Drawing (overlays): module +
gpu.gpu_extras.batchwas removed in 5.0. Textures come frombgl. For scene-linear images usegpu.texture.from_image(img).draw_texture_2d(..., is_scene_linear_with_rec709_srgb_target=True) - Long tasks: a modal operator with a timer (), or
wm.event_timer_addwith chunked work. Never block the UI for seconds.bpy.app.timers.register - Handlers: decorate persistent ones with . Keep them cheap (they run every frame/depsgraph update).
@bpy.app.handlers.persistent - Keymaps: add them to , store
wm.keyconfigs.addonpairs, and remove them on unregister.(km, kmi) - Translations / i18n: .
bpy.app.translations.register(__package__, dict)
- 仅使用相对导入()。package 名称由 Blender 决定,因此 preferences 使用
from . import ops。bl_idname = __package__ - 不使用 (extension 会忽略它)。所有信息都写入 manifest。
bl_info - 导入或注册时不得访问网络或文件。 声明 (
[permissions]、files、network、clipboard、camera)及其原因。任何网络调用前都要检查microphone。bpy.app.online_access - 第三方 Python packages:将 文件放在
.whl中,并在./wheels/下列出。绝不要在运行时执行wheels = [...]。平台专用 wheels 需要通过pip install声明。platforms = [...] - Properties(5.0+):的值是属性,而不是字典条目(
bpy.props将无法再访问这些值)。只读 props 使用scene["my_prop"]。options={'READ_ONLY'}/get_transform在保留存储方式的同时调整值。在 ID type 上使用set_transform注册,并在 unregister 时将其PointerProperty(type=PG)。del - Operators:需要 undo 时使用 ,并提供 redo 面板。
bl_options={"REGISTER","UNDO"}用于限制运行上下文。返回poll()/{"FINISHED"}。使用{"CANCELLED"}向用户提供反馈。如果存在对应的 data API,不要在循环中调用其他 operators。self.report({"WARNING"}, msg) - UI:可实现符合现代规范的布局。N-panel 中的 panels 使用
layout.use_property_split = True和bl_region_type="UI"。通过bl_category添加菜单项,并在 unregister 时移除。VIEW3D_MT_*.append(func) - Unregister:按相反顺序注销所有内容(classes、props、menus、handlers、timers、keymaps、draw handlers)。资源泄漏会破坏重新加载。
- 绘制(overlays):使用 module 和
gpu。gpu_extras.batch已在 5.0 中移除。Textures 来自bgl。对于 scene-linear images,使用gpu.texture.from_image(img)。draw_texture_2d(..., is_scene_linear_with_rec709_srgb_target=True) - 耗时任务:使用带 timer()的 modal operator,或使用
wm.event_timer_add分块处理工作。切勿让 UI 阻塞数秒。bpy.app.timers.register - Handlers:为持久运行的 handler 添加 装饰器。保持其执行成本低(它们会在每帧或每次 depsgraph 更新时运行)。
@bpy.app.handlers.persistent - Keymaps:将快捷键添加到 ,保存
wm.keyconfigs.addon对,并在 unregister 时移除。(km, kmi) - 翻译 / i18n:使用 。
bpy.app.translations.register(__package__, dict)
Publishing (extensions.blender.org)
发布(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由 Blender ID 账户上传构建后的 zip。要求包括:有效的 manifest、与 GPL 兼容的 license、无混淆代码、捆绑二进制文件时提供相应源代码,以及声明 permissions。Screenshots 和 README 应放在网站列表中。更新时需要提供更高的 。
versionGotchas
常见问题
- inside a draw function can be
context.scenein some editors. Guard it.None - Storing Blender data references () in Python globals crashes after undo or file load. Store names or
bpy.types.ID, and look them up again.session_uid - fails if annotations use
bpy.utils.register_classinstead of=for properties.: - 5.0 made several bundled modules private (,
rna_info...). Don't import them.bl_ui_utils - 5.1 no longer loads the user site-packages by default. Bundle wheels instead of relying on user installs.
- 5.2: indices are offset (the "All"/"Essentials" entries come first).
PreferencesFilePaths.active_asset_libraryis removed. New:UILayout.template_palette(color=),UILayout.link,UILayout.textbox,bpy.data.all_ids.Window.screenshot
- 在某些 editors 中,draw function 内的 可能为
context.scene,需要进行保护。None - 在 Python globals 中存储 Blender 数据引用()会导致 undo 或文件加载后崩溃。应存储名称或
bpy.types.ID,然后重新查找对应数据。session_uid - 如果 properties 的 annotations 使用 而不是
=,:将失败。bpy.utils.register_class - 5.0 将多个内置 modules 设为私有(、
rna_info等),不要导入它们。bl_ui_utils - 5.1 默认不再加载用户的 site-packages。应捆绑 wheels,而不是依赖用户自行安装。
- 5.2:的索引存在偏移("All"/"Essentials" 条目排在最前)。
PreferencesFilePaths.active_asset_library已被移除。新增:UILayout.template_palette(color=)、UILayout.link、UILayout.textbox、bpy.data.all_ids。Window.screenshot