blender-addon-development

アドオン（拡張機能）の開発

実行モデルは blender-core にあります。CI で検証、ビルド、登録済みの assets/addon_template/ から始めます。内容は blender_manifest.toml、__init__.py、operators.py、ui.py です。

手順

1. テンプレートをコピーし、id（小文字とアンダースコアを使用し、変更不可）、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（オペレーター）、_PT_（パネル）、_MT_（メニュー）、_PG_（プロパティグループ）、_AP_（プリファレンス）、_UL_（UI リスト）のプレフィックス規則を使用します。オペレーターの 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. ヘッドレスでテストします。パッケージをプロセス内で登録し、temp_override を使ってオペレーターを呼び出し、データを検証します（このリポジトリの tests/test_addon.py を参照）。

ルール（拡張機能時代、5.x）

• 相対インポートのみを使用します（from . import ops）。パッケージ名は Blender が決定するため、プリファレンスでは bl_idname = __package__ を使用します。
• bl_info は使用しません（拡張機能では無視されます）。すべてマニフェストに記述します。
• インポート時や登録時にネットワークやファイルへアクセスしないでください。 [permissions] に理由とともに（files、network、clipboard、camera、microphone）を宣言します。ネットワークにアクセスする前に bpy.app.online_access を確認します。
• サードパーティの Python パッケージ：.whl ファイルを ./wheels/ に同梱し、wheels = [...] に記載します。実行時に pip install してはいけません。プラットフォーム固有のホイールには platforms = [...] が必要です。
• プロパティ（5.0 以降）：bpy.props の値は属性であり、辞書エントリーではありません（scene["my_prop"] ではアクセスできなくなりました）。読み取り専用プロパティには options={'READ_ONLY'} を使用します。get_transform／set_transform は、保存値を維持したまま値を変換します。ID 型に PointerProperty(type=PG) を使って登録し、登録解除時に del で削除します。
• オペレーター：元に戻す機能とやり直しパネルには bl_options={"REGISTER","UNDO"} を使用します。コンテキストは poll() で確認します。{"FINISHED"}／{"CANCELLED"} を返します。ユーザーへのフィードバックには self.report({"WARNING"}, msg) を使用します。データ API がある場合は、ループ内で他のオペレーターを呼び出さないでください。
• UI：layout.use_property_split = True を設定すると、現代的な配置になります。N パネル内のパネルには bl_region_type="UI" と bl_category を使用します。VIEW3D_MT_*.append(func) でメニュー項目を追加し、登録解除時に削除します。
• クラス、プロパティ、メニュー、ハンドラー、タイマー、キーマップ、描画ハンドラーのすべてを、逆順に登録解除します。リークがあると再読み込みに支障をきたします。
• 描画（オーバーレイ）：gpu モジュールと gpu_extras.batch を使用します。bgl は 5.0 で削除されました。テクスチャは gpu.texture.from_image(img) から取得します。シーンリニア画像には draw_texture_2d(..., is_scene_linear_with_rec709_srgb_target=True) を使用します。
• 長時間のタスク：タイマー（wm.event_timer_add）を使うモーダルオペレーター、または分割処理を行う bpy.app.timers.register を使用します。数秒間 UI をブロックしてはいけません。
• ハンドラー：永続化するハンドラーには @bpy.app.handlers.persistent を付けます。処理は軽く保ちます（フレームや depsgraph の更新ごとに実行されます）。
• キーマップ：wm.keyconfigs.addon に追加し、(km, kmi) のペアを保存して、登録解除時に削除します。
• 翻訳／i18n：bpy.app.translations.register(__package__, dict) を使用します。

公開（extensions.blender.org）

Blender ID アカウントからビルド済みの zip をアップロードします。要件は、有効なマニフェスト、GPL と互換性のあるライセンス、難読化されていないコード、ソースなしのバイナリを同梱していないこと、および権限の宣言です。スクリーンショットと README はウェブサイトの掲載ページに追加します。更新時は version をより高い値にします。

注意点

• 描画関数内の context.scene は、一部のエディターでは None になることがあります。ガードしてください。
• Blender データ参照（bpy.types.ID）を Python のグローバル変数に保存すると、Undo やファイルの読み込み後にクラッシュします。名前または session_uid を保存し、再度検索してください。
• プロパティのアノテーションで : の代わりに = を使うと、bpy.utils.register_class は失敗します。
• 5.0 では、複数の同梱モジュール（rna_info、bl_ui_utils など）が非公開になりました。インポートしないでください。
• 5.1 では、ユーザーの site-packages がデフォルトで読み込まれなくなりました。ユーザーによるインストールに依存せず、wheel を同梱してください。
• 5.2：PreferencesFilePaths.active_asset_library のインデックスはずれています（「All」／「Essentials」の項目が先にあります）。UILayout.template_palette(color=) は削除されました。新機能：UILayout.link、UILayout.textbox、bpy.data.all_ids、Window.screenshot。