Contents
Blender 5.1 における Extensions API の全体像
Blender 5.1 からは Extensions API が本格化し、アドオンと同様の手順で機能を配布できるようになりました。この記事では、Extension Manager と連携した「カスタム UI テーマ」開発の流れを、プロジェクト作成・コード実装・パッケージ化まで一貫して解説します。
- 何が変わったか：拡張機能は bl_info と register()/unregister() だけで認識され、フォルダ構成もシンプルに保てます。
- 読者への価値：公式マニュアルだけでは掴みにくい「実装上の落とし穴」や「安全に配布するコツ」を具体例と共に示します。
1. Extensions の開発フローを俯瞰する
このセクションでは、Blender 5.1 で拡張機能を作る際の全体像を示します。
ポイントは「プロジェクト作成 → コード実装 → テスト → パッケージ化 → 配布」の４ステップです。各ステップがどんな入力・出力を持つかを把握すれば、途中で手戻りするリスクが大幅に減ります。
1‑1. プロジェクト作成と bl_info の必須項目
bl_info は拡張機能の「身分証明書」のような役割を果たします。公式マニュアル（Extensions – Blender Manual）に記載されている必須キーは以下です。
| キー | 意味・注意点 |
|---|---|
name |
ユーザーが UI で目にする名前。日本語可。 |
author |
製作者名または組織名。 |
version |
タプル (メジャー, マイナー, パッチ)。配布ごとに必ず更新すること。 |
blender |
動作対象の Blender バージョン。最低 (5, 1, 0) を指定。 |
location |
UI 上で機能が現れる場所（任意）。 |
description |
簡潔な概要文。検索結果に表示される重要情報。 |
category |
"Interface"、"3D View" など公式カテゴリのいずれか。 |
実装上のヒント
-bl_info["blender"]が現在起動中の Blender バージョン未満の場合はインストールを拒否させるチェックを入れると、ユーザー側で不整合が発生しにくくなります。
コード例（__init__.py の冒頭）
|
1 2 3 4 5 6 7 8 9 10 |
bl_info = { "name": "MyThemeExtension", "author": "Your Name", "version": (1, 0, 0), "blender": (5, 1, 0), # 必須：5.1 以上で動作 "location": "Preferences > Themes", "description": "カスタム UI カラーテーマを Extensions として配布します。", "category": "Interface" } |
2. 推奨フォルダ構成とファイル配置
導入文
拡張機能は Python パッケージとして認識されるため、余計なファイルが混在するとロードエラーの原因になります。ここでは「最小構成」と「実務で便利な補助モジュール」の例を示します。
2‑1. 最小構成
|
1 2 3 4 5 |
MyThemeExtension/ │ ├─ __init__.py # エントリーポイントと bl_info、register 系 └─ theme_utils.py # テーマ操作用ユーティリティ（任意） |
__init__.pyが唯一のエントリポイントであることを保証すれば、Extension Manager は自動的に認識します。- 追加モジュールは必ず
import .theme_utilsのように相対インポートしてください。
2‑2. 補助モジュール例（theme_utils.py）
|
1 2 3 4 5 6 7 |
# theme_utils.py def rgb(*values): """0〜1 の float タプルへ正規化するヘルパー""" if len(values) == 3: return tuple(v / 255.0 for v in values) raise ValueError("RGB は 3 要素が必要です") |
3. カスタムテーマの作成とプロパティ取得
3‑1. UI で新規テーマを生成する手順（公式ドキュメントに準拠）
Blender の Preferences > Themes パネルから「+」ボタンで空テーマが作れます。作成したテーマは bpy.context.preferences.themes に Python オブジェクトとして保持され、.blend ファイル内に保存されます（XML 形式のファイルは存在しません）。この点は公式マニュアルと食い違う情報が散見するため、正しく認識しておくことが重要です。
3‑2. Python コンソールでプロパティ名を調べる方法
外部アドオンに依存せず、標準の Python コンソールだけで目的のプロパティ名を取得できます。以下は「3D Viewport のグリッド色」を探す例です。
|
1 2 3 4 5 6 7 8 9 10 |
import bpy # 現在選択中のテーマ（最初がデフォルト、2番目以降にユーザー作成テーマが入る） theme = bpy.context.preferences.themes[1] # ユーザーが「+」で追加したテーマと仮定 # すべてのプロパティを列挙し、'grid' が含まれるものだけ表示 for prop in dir(theme.space_3d): if "grid" in prop.lower(): print(prop) |
実務的なコツ
-bpy.context.preferences.themesはインデックスで管理されますが、名前で検索した方が保守性が高いです。次節のユーティリティ関数を活用してください。
4. 安全かつ堅牢な register / unregister の実装
4‑1. バージョンチェックと例外処理のベストプラクティス
単に register() を呼び出すだけでは、以下のような問題が起こり得ます。
- バージョンミスマッチ：5.0 以前でロードすると RuntimeError が発生する。
- プロパティ名変更：Blender の内部 API が将来更新された場合に属性エラーが出る。
そこで、拡張機能側で事前にチェックし、失敗したときは明示的な例外を投げてインストール自体を中止させます。
完全版サンプルコード（__init__.py の続き）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
import bpy from . import theme_utils # ------------------------------ # 1. ユーティリティ関数群 # ------------------------------ def _blender_version_ok(min_version=(5, 1, 0)): """起動中の Blender が最低バージョンを満たすか判定""" cur = bpy.app.version return cur >= min_version def _find_theme_by_name(name: str): """名前一致でテーマオブジェクトを取得。見つからなければ None を返す""" for th in bpy.context.preferences.themes: if th.name == name: return th return None # ------------------------------ # 2. カラー適用ロジック（例示） # ------------------------------ CUSTOM_THEME_NAME = "MyCustomTheme" def apply_theme_colors(theme): """3D Viewport のグリッド色と UI 背景色を上書きする""" try: # Theme Property Finder 等で取得した正しい属性名を使用 theme.space_3d.grid_color = theme_utils.rgb(30, 80, 150) # RGB → (0‑1) 正規化 theme.user_interface.wcol_menu_item.inner = theme_utils.rgb(40, 45, 50) except AttributeError as e: raise RuntimeError(f"テーマ属性が見つかりません: {e}") except Exception as e: raise RuntimeError(f"カラー適用中に予期しないエラーが発生しました: {e}") def restore_default_theme(): """デフォルトテーマへ安全にリセット""" default = bpy.context.preferences.themes[0] # 通常はインデックス 0 がデフォルト try: default.space_3d.grid_color = theme_utils.rgb(50, 50, 50) default.user_interface.wcol_menu_item.inner = theme_utils.rgb(51, 51, 52) except Exception as e: print(f"[MyThemeExtension] デフォルト復元時にエラー: {e}") # ------------------------------ # 3. register / unregister エントリ # ------------------------------ def register(): # (1) バージョンチェック if not _blender_version_ok(): raise RuntimeError( f"MyThemeExtension は Blender 5.1 以上が必要です（現在のバージョン: {bpy.app.version_string}）" ) # (2) カスタムテーマ取得 theme = _find_theme_by_name(CUSTOM_THEME_NAME) if theme is None: print(f"[MyThemeExtension] カスタムテーマ '{CUSTOM_THEME_NAME}' が見つかりません。デフォルトで動作します。") return # (3) カラー適用 apply_theme_colors(theme) def unregister(): try: restore_default_theme() except Exception as e: print(f"[MyThemeExtension] アンインストール時にエラーが発生しました: {e}") # ------------------------------ # 4. 必要ならクラス登録（今回は UI パネルなしの最小構成） # ------------------------------ if __name__ == "__main__": register() |
ポイントまとめ
1. 起動バージョンが条件を満たさない場合は RuntimeError を投げてインストール自体を失敗させる。
2. テーマ取得は名前検索で行い、見つからなければ安全にスキップ（ログ出力のみ）。
3. すべての属性操作は try/except で包み、原因が分かりやすい例外メッセージを提供する。
5. デバッグ・検証フロー
5‑1. ログ出力とコンソール活用
Extension Manager の「Console」タブは print() 出力先です。開発中は 詳細ログ を残すことで、インストール失敗の原因を迅速に特定できます。
|
1 2 3 |
def _log(msg): print(f"[MyThemeExtension] {msg}") |
5‑2. ユニットテスト的検証手順
- クリーン環境でのインストール：Blender を
--factory-startupオプションで起動し、拡張機能だけをインストール。 - テーマが正しく適用されたか確認：3D Viewport のグリッド色が期待通りに変化しているか目視チェック。
- アンインストール後の復元：
unregister()がデフォルトに戻すことを再度確認。
6. パッケージ化と配布の実務手順
6‑1. ZIP 圧縮の正しいやり方
| 手順 | 操作内容 |
|---|---|
| ① | プロジェクトフォルダ（例：MyThemeExtension/）全体を選択 |
| ② | OS の「圧縮」機能で .zip を作成。フォルダ名がそのまま拡張子内部に残ることを確認 |
| ③ | __init__.py がトップレベルにある状態で ZIP が完成 |
注意点：ZIP 内に余計な
__MACOSX/や.DS_Storeが入らないようにする（特に macOS 利用者は要チェック）。
6‑2. Extension Manager からのインストール手順
- Blender のメニュー Edit → Preferences → Extensions を開く。
- 「Install from File…」をクリックし、先ほど作成した
.zipファイルを選択。 - インストールが成功すれば一覧に表示されるのでチェックして有効化する。
6‑3. 配布時に添付すべきファイル
| ファイル | 内容 |
|---|---|
README.md |
インストール手順、カスタマイズ例、既知の制限事項を記載。 |
LICENSE.txt |
GPL‑2.0 or later（Blender 本体と同一）か、別途明示したライセンス文書。 |
CHANGELOG.md (任意) |
バージョンごとの変更点を履歴として残す。 |
6‑4. ライセンスと互換性に関する注意事項
- GPL：Blender は GPL‑2.0 or later の下で配布されているため、拡張機能も同ライセンスで公開するか、明示的に別ライセンスを付与しても問題ありません（ただし GPL と互換性のあるものに限る）。
- バージョン表記：
bl_info["blender"]が (5, 1, 0) 以上であることは必須です。古いバージョン向けに後方互換性を持たせたい場合は、コード内で条件分岐し「機能制限」旨のメッセージを出す実装が望ましいです。
7. まとめと次のアクション
Blender 5.1 の Extensions API を利用したカスタムテーマ開発は、正確な bl_info 記述 → シンプルなフォルダ構成 → 安全な register/unregister 実装 → 正式な ZIP 配布という流れで完結します。この記事で示したベストプラクティスを踏まえれば、以下が実現できます。
- インストール時に自動適用されるテーマ拡張が手軽に作れる。
- バージョンチェックと例外処理により、ユーザー側での不具合発生リスクを最小化できる。
- 公式マニュアルのみを情報源としているため、将来的な仕様変更にも比較的耐性がある。
ぜひ手元の Blender で本稿のサンプルプロジェクトを作成し、実際にテーマが適用される様子を確認してみてください。その上で独自の UI カラーパレットや配色ロジックを加えることで、オリジナルの拡張機能として公開できるようになります。
本稿は 2026 年 5 月時点の公式情報に基づいて執筆しています。Blender のバージョンが更新された場合は、必ず最新マニュアルを参照してください。