tmhsdigital/blender-developer-tools

bl-info-migration

Migrate a legacy blinfo add-on to the Extensions Platform in three steps, with a before/after diff and the dual-format pattern.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/tmhsdigital/blender-developer-tools --skill bl-info-migration

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

bl_info Migration to the Extensions Platform

Trigger

Use this skill when the user:

  • Has an existing add-on with a bl_info = {...} dictionary at the top of __init__.py
  • Wants to publish to extensions.blender.org or distribute as a .zip for the Extensions Platform
  • Asks "is bl_info dead?" or "do I have to migrate?"
  • Sees a deprecation warning at install time about legacy add-ons
  • Mentions blender_manifest.toml, "Install legacy Add-on", or "the new extension system"

Is bl_info still supported?

Yes, with caveats.

  • In 5.2 LTS (current stable; 5.1 is prior stable): bl_info is supported as a fallback for legacy add-ons. The Edit > Preferences > Add-ons panel still has "Install legacy Add-on" and recognizes bl_info dicts.
  • For the Extensions Platform (extensions.blender.org and the new add-ons UI): you need a blender_manifest.toml. bl_info is ignored.
  • Dual format is officially recognized: ship a blender_manifest.toml and keep the bl_info dict. The platform reads the manifest; legacy installers read bl_info. Both code paths work without conditional logic.

The Blender Foundation's stated direction is that the Extensions Platform is the future and bl_info-only add-ons will degrade in discoverability over time, but they are not announcing a removal date.

The three migration steps

A migration from a bl_info-only add-on to the Extensions Platform takes three small mechanical changes.

Step 1: Generate blender_manifest.toml

Create a new file blender_manifest.toml next to __init__.py. Translate the bl_info fields:

bl_info keyManifest keyNotes
"name"name = "..."Same string
"version": (1, 2, 3)version = "1.2.3"Tuple becomes a string
"blender": (4, 5, 0)blender_version_min = "4.5.0"Renamed; semantics same
"author"maintainer = "Author <email>"Email recommended
"description"tagline = "..."Renamed
"category"tags = ["..."]Now a list of allowed tags
"location", "warning"(no equivalent)Drop
(none)id = "..."New required field; a Python identifier such as my_tool (no dots, so not reverse-DNS; no __; no leading or trailing _)
(none)schema_version = "1.0.0"Required
(none)type = "add-on"Required
(none)license = ["SPDX:..."]Required SPDX expression

Minimal manifest:

toml
schema_version = "1.0.0"

id = "my_addon"
version = "1.2.3"
name = "My Addon"
tagline = "What it does in one sentence"
maintainer = "Author Name <author@example.com>"
type = "add-on"

blender_version_min = "4.5.0"

license = [
    "SPDX:GPL-3.0-or-later",
]

tags = ["3D View", "Mesh"]

The full schema and allowed tag list live in the Blender extensions documentation.

Step 2: Delete bl_info (or keep both)

If you only want to support 5.x and the Extensions Platform: delete the bl_info = {...} block from __init__.py.

If you want to keep working with the 4.x "Install legacy Add-on" path while also publishing to the platform: leave bl_info in place. This is the dual-format pattern. The two metadata sources do not need to agree perfectly; the platform reads only the manifest, the legacy installer reads only bl_info.

Step 3: Convert imports to relative or __package__

Legacy add-ons commonly use absolute imports:

python
from my_addon import operators
from my_addon.ui import panels

These break under the Extensions Platform because the package name is no longer my_addon at runtime; it's a generated synthetic name like bl_ext.user_default.my_addon. Two fixes that work everywhere:

Relative imports:

python
from . import operators
from .ui import panels

`__package__` lookup (when you need the full package name as a string):

python
import importlib

operators = importlib.import_module(f"{__package__}.operators")

Both forms are stable across the legacy and Extensions Platform load paths.

Step 4: Replace hard-coded add-on names with __package__

Imports are not the only place the old module name hides. Any string literal that names the add-on breaks the same way after migration, because the module is now bl_ext.<repo>.<id>:

python
# Before: breaks once installed as an extension
prefs = context.preferences.addons["my_addon"].preferences  # KeyError

class MyAddonPrefs(bpy.types.AddonPreferences):
    bl_idname = __name__  # wrong when this class lives in a submodule
python
# After: __package__ carries the full runtime name
prefs = context.preferences.addons[__package__].preferences

class MyAddonPrefs(bpy.types.AddonPreferences):
    bl_idname = __package__

Measured on 5.2.1 LTS with an installed test extension (bl_ext.user_default.probe_good):

  • context.preferences.addons["probe_good"] raises KeyError. The add-on is listed only under bl_ext.user_default.probe_good.
  • In a submodule prefs.py, __name__ is bl_ext.user_default.probe_good.prefs and __package__ is bl_ext.user_default.probe_good.
  • An AddonPreferences subclass with bl_idname = __name__ in that submodule still registers without an error, but addons[pkg].preferences is None. The preferences silently disappear. With bl_idname = __package__ it returns the class instance.

__package__ names the root only one level down. In a deeper module such as ui/panels.py it is bl_ext.<repo>.<id>.ui. Take the root name from the top-level __init__.py (where __package__ == __name__) and pass it down, rather than slicing strings. Grep the add-on for its old name in quotes ("my_addon", 'my_addon') and for bl_idname = __name__. The `custom-properties` skill shows the AddonPreferences pattern with __package__.

Worked example: before and after

Before (legacy, single file __init__.py)

python
bl_info = {
    "name": "Cube Tools",
    "author": "Acme <acme@example.com>",
    "version": (1, 0, 0),
    "blender": (4, 5, 0),
    "location": "View3D > Sidebar > Cube",
    "description": "Quick cube operations",
    "category": "Object",
}

import bpy
from cube_tools import operators
from cube_tools.ui import panels


def register():
    operators.register()
    panels.register()


def unregister():
    panels.unregister()
    operators.unregister()

After (Extensions Platform)

blender_manifest.toml:

toml
schema_version = "1.0.0"

id = "cube_tools"
version = "1.0.0"
name = "Cube Tools"
tagline = "Quick cube operations"
maintainer = "Acme <acme@example.com>"
type = "add-on"

blender_version_min = "4.5.0"

license = [
    "SPDX:GPL-3.0-or-later",
]

tags = ["Object"]

__init__.py:

python
import bpy

from . import operators
from .ui import panels


def register():
    operators.register()
    panels.register()


def unregister():
    panels.unregister()
    operators.unregister()

The bl_info dict is gone; the imports are now relative; everything else is identical.

After (dual format, supports both load paths)

Same blender_manifest.toml as above, plus keeping a slimmed bl_info for 4.x legacy users:

python
bl_info = {
    "name": "Cube Tools",
    "author": "Acme",
    "version": (1, 0, 0),
    "blender": (4, 5, 0),
    "category": "Object",
}

import bpy
from . import operators
from .ui import panels

Note: the imports are still relative. Relative imports work in both load paths; absolute imports only work in the legacy path.

Packaging for distribution

Once the manifest exists, build the Extension .zip:

powershell
blender --command extension build --source-dir .\cube_tools --output-dir .\dist

This produces a .zip in dist\ that the user installs via Edit > Preferences > Add-ons > Install... or that you upload to extensions.blender.org.

Common AI mistakes

  • Forgetting `id` in the manifest. id is required and must be a stable slug; changing it later is a breaking change that disconnects users from updates.
  • Using a tuple for `version` in the manifest. bl_info uses tuples, the manifest uses a string. Dot-separated semver, e.g., "1.2.3".
  • Keeping absolute imports during dual-format migration. They break at runtime under the Extensions Platform load path. Convert to relative.
  • Skipping SPDX in `license`. The platform rejects manifests without a license expression. ["SPDX:GPL-3.0-or-later"] matches typical Blender add-on practice; commercial add-ons use other SPDX strings.
  • Misnaming the file. It must be exactly blender_manifest.toml, lowercase, in the package root.
  • Mixing `permissions` defaults. The manifest has a permissions key for network, file IO, etc. Default to declaring nothing if you don't need elevated permissions; over-declaration triggers user warnings.

Version correctness

Topic4.5 LTS5.1 / 5.2 LTS
bl_info recognizedYes (legacy; Extensions is the primary path since 4.2)Yes (legacy fallback only)
blender_manifest.toml recognizedYes (Extensions Platform was added in 4.2)Yes
Synthetic package namebl_ext.<repo>.<id>Same
extension build commandAvailableAvailable
Schema version1.0.01.0.0

The Extensions Platform shipped in Blender 4.2. Migrations done now will work on 4.2+ and 5.x without further changes. Code targeting 4.1 or earlier still needs the bl_info path.

See also

  • Skill addon-scaffolding: scaffolding a new Extensions Platform add-on from scratch.
  • Rule target-extensions-platform-format: encodes the policy that new add-ons should be Extensions-first.
  • Template extension-addon-template: a working starter to compare your migration against.

<!-- examples:begin (generated by scripts/buildexamplesindex.py from examples/skills.json; do not edit) -->

Runnable examples

Each example runs headless, asserts the contract, and exits non-zero when it breaks. Run one with blender --background --python <script> --; pass a falsifier flag to watch the check fail.

  • `addon-register-lifecycle`: Check-only witness for the first things every add-on author writes. Falsify: --drop-manifest (exit 3).

<!-- examples:end -->

References

  • Blender Extensions documentation: https://developer.blender.org/docs/handbook/extensions/
  • blender_manifest.toml schema: https://developer.blender.org/docs/handbook/extensions/schema/
  • Blender 4.2 release notes (Extensions Platform launch): https://developer.blender.org/docs/release_notes/4.2/extensions/
  • SPDX license expression list: https://spdx.org/licenses/
同じリポジトリから

関連する Skills

すべての Skills
tmhsdigital
コミュニティ

bake-high-to-low

Cage-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, saverender). Use when the user wants a normal map from a dense mesh onto a game-resolution or decimated LOD, mentions cageextrusion or useselectedtoactive, or gets a bake that returns CANCELLED, comes out black or flat, or fails with 'No active UV layer found'. Targets 5.2 LTS with 4.5 LTS fallback.

1時間の導入数
1
GitHub Stars
20
更新日
11月3日
tmhsdigital
コミュニティ

drivers-and-app-handlers

Drive properties from expressions with the Driver API (driveradd, drivernamespace for custom Python functions) and react to events with bpy.app.handlers (loadpost, savepre, framechangepost, depsgraphupdatepost, exitpre in 5.1+). Use when the user wants one property to follow another, runs code on load, save, frame change or exit, or has a driver failing with NameError or the Python security block, including drivers that die after reopening a file.

1時間の導入数
1
GitHub Stars
20
更新日
11月3日
tmhsdigital
コミュニティ

engine-export-presets

Export presets for Unity, Godot and Unreal. glTF is +Y up and meters by spec, so every engine gets exportyup=True with no scale bake (Unreal converts to centimeters on import); FBX takes axisforward/axisup plus globalscale. Use when the user exports for a game engine, mentions exportyup, axisforward, axisup, globalscale, Y-up or centimeters, passes FBX axis kwargs to exportscene.gltf, or gets a model that imports lying on its back or 100x too large. Targets 5.2 LTS with 4.5 LTS fallback.

1時間の導入数
1
GitHub Stars
20
更新日
11月3日