blender-addon-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Add-on (Extension) Development

Add-on(Extension)开发

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
.
执行模型位于
blender-core
。从
assets/addon_template/
开始(已在 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).
  1. 复制模板,然后设置
    id
    (lowercase_underscores,永久不变)、
    name
    、
    tagline
    (末尾不要加句点,≤ 64 个字符)、
    maintainer
    、
    version
    (semver)、
    license
    (SPDX;使用 bpy 的代码应采用 GPL-3.0-or-later),以及
    blender_version_min = "4.2.0"
    ;如果使用较新的 API,则设置更高的版本,例如 GN
    properties.inputs
    API 对应
    "5.2.0"
    。
  2. 编写类时遵循前缀约定:
    MYTOOL_OT_x
    (operator)、
    _PT_
    (panel)、
    _MT_
    (menu)、
    _PG_
    (property group)、
    _AP_
    (preferences)、
    _UL_
    (UI list)。operator 的
    bl_idname
    应为
    my_tool.verb_noun
    。
  3. 验证并构建:
    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. 进行 headless 测试:在进程内注册 package,使用
    temp_override
    调用 operators,并对数据进行断言(参见本仓库中的
    tests/test_addon.py
    )。

Rules (extension-era, 5.x)

规则(extension 时代,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)
    .
  • 仅使用相对导入(
    from . import ops
    )。package 名称由 Blender 决定,因此 preferences 使用
    bl_idname = __package__
    。
  • 不使用
    bl_info
    (extension 会忽略它)。所有信息都写入 manifest。
  • 导入或注册时不得访问网络或文件。 声明
    [permissions]
    (
    files
    、
    network
    、
    clipboard
    、
    camera
    、
    microphone
    )及其原因。任何网络调用前都要检查
    bpy.app.online_access
    。
  • 第三方 Python packages:将
    .whl
    文件放在
    ./wheels/
    中,并在
    wheels = [...]
    下列出。绝不要在运行时执行
    pip install
    。平台专用 wheels 需要通过
    platforms = [...]
    声明。
  • Properties(5.0+):
    bpy.props
    的值是属性,而不是字典条目(
    scene["my_prop"]
    将无法再访问这些值)。只读 props 使用
    options={'READ_ONLY'}
    。
    get_transform
    /
    set_transform
    在保留存储方式的同时调整值。在 ID type 上使用
    PointerProperty(type=PG)
    注册,并在 unregister 时将其
    del
    。
  • Operators:需要 undo 时使用
    bl_options={"REGISTER","UNDO"}
    ,并提供 redo 面板。
    poll()
    用于限制运行上下文。返回
    {"FINISHED"}
    /
    {"CANCELLED"}
    。使用
    self.report({"WARNING"}, msg)
    向用户提供反馈。如果存在对应的 data API,不要在循环中调用其他 operators。
  • UI:
    layout.use_property_split = True
    可实现符合现代规范的布局。N-panel 中的 panels 使用
    bl_region_type="UI"
    和
    bl_category
    。通过
    VIEW3D_MT_*.append(func)
    添加菜单项,并在 unregister 时移除。
  • Unregister:按相反顺序注销所有内容(classes、props、menus、handlers、timers、keymaps、draw handlers)。资源泄漏会破坏重新加载。
  • 绘制(overlays):使用
    gpu
    module 和
    gpu_extras.batch
    。
    bgl
    已在 5.0 中移除。Textures 来自
    gpu.texture.from_image(img)
    。对于 scene-linear images,使用
    draw_texture_2d(..., is_scene_linear_with_rec709_srgb_target=True)
    。
  • 耗时任务:使用带 timer(
    wm.event_timer_add
    )的 modal operator,或使用
    bpy.app.timers.register
    分块处理工作。切勿让 UI 阻塞数秒。
  • Handlers:为持久运行的 handler 添加
    @bpy.app.handlers.persistent
    装饰器。保持其执行成本低(它们会在每帧或每次 depsgraph 更新时运行)。
  • Keymaps:将快捷键添加到
    wm.keyconfigs.addon
    ,保存
    (km, kmi)
    对,并在 unregister 时移除。
  • 翻译 / 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 应放在网站列表中。更新时需要提供更高的
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
    .
  • 在某些 editors 中,draw function 内的
    context.scene
    可能为
    None
    ,需要进行保护。
  • 在 Python globals 中存储 Blender 数据引用(
    bpy.types.ID
    )会导致 undo 或文件加载后崩溃。应存储名称或
    session_uid
    ,然后重新查找对应数据。
  • 如果 properties 的 annotations 使用
    =
    而不是
    :
    ,
    bpy.utils.register_class
    将失败。
  • 5.0 将多个内置 modules 设为私有(
    rna_info
    、
    bl_ui_utils
    等),不要导入它们。
  • 5.1 默认不再加载用户的 site-packages。应捆绑 wheels,而不是依赖用户自行安装。
  • 5.2:
    PreferencesFilePaths.active_asset_library
    的索引存在偏移("All"/"Essentials" 条目排在最前)。
    UILayout.template_palette(color=)
    已被移除。新增:
    UILayout.link
    、
    UILayout.textbox
    、
    bpy.data.all_ids
    、
    Window.screenshot
    。