設定

Blender Probe の動作には Blender ランタイムが必要です。そのため、プラグインの各機能を使用する前にランタイムの設定を行ってください。

オプションA: `blup` による自動設定 🦀

blup で Blender のバージョンを管理している場合、追加の設定は不要です。プラグインがプロジェクトの .blender-version ファイルまたはグローバルデフォルトに基づいて、Blender 実行ファイルを自動的に検出します。

（テスト対象の Blender バージョンを頻繁に変える、あるいは型スタブ生成機能のバージョン間 diff を取ることで API 変更を追跡するなどが容易になります。これはデイリービルドに関しても同様であるため、いち早い対応が可能になります。）

オプションB: 手動パス設定

blup を使わない場合、プラグインを使用する前にBlender実行ファイルのパスを設定する必要があります。

Settings/Preferences > Tools > Blender Probe を開きます。
Blender Executable Path を設定します:
- Windows: C:\Program Files\Blender Foundation\Blender 5.0\blender.exe
- macOS: /Applications/Blender.app/Contents/MacOS/Blender
- Linux: /usr/bin/blender
OK をクリックします。

新しいアドオンプロジェクトの作成

ごくシンプルなアドオンとテストや CI がセットアップされた構成で開発を始められます。

File > New Project を選択します。
左側のジェネレーター一覧から Blender addon を選択します。
プロジェクトの作成場所を設定し、Create をクリックします。

Blender addonジェネレーターを使用したNew Projectウィザード

Blender 4.2 以降の Extensions に準拠したクリーンなプロジェクト構成が生成されます:

my_addon_package/: アドオンのPythonパッケージ。ウィザードで入力した名前のパッケージが作成されます。
tests/: すぐに実行可能なテストスイート。
.github/: GitHub Actions用のCIワークフロー。
LICENSE: GPLv3ライセンスファイル。
pyproject.toml: Pythonツール設定ファイル。

コードスタブの生成（自動補完）

bpy やその他の Blender モジュールのコード補完を有効にするために:

PyCharm でプロジェクトを開きます。
Tools > Regenerate Blender Stubs を選択します。
プログレスバーが完了するまで待ちます。プロジェクトルートに隠しフォルダ .blender_stubs が作成され、自動的に Source Root としてマークされます。

Regenerate Blender Stubsアクションを表示するPyCharmメニュー

💡 ヒント: .blender_stubs フォルダには生成されたファイルが含まれており、バージョン管理する必要はありません。プロジェクトの .gitignore ファイルに .blender_stubs/ を追加することを推奨します。 （Blender addon ウィザードでプロジェクトを作成した場合、これは既に設定済みです。） 💡 ヒント: Blender の API は非常に動的であるため、PyCharm が自動的に型を推論できない場合があります。完全な自動補完を得るには、型ヒントを使用してください:
def my_func(context: bpy.types.Context):
    obj: bpy.types.Object = context.active_object
    print(obj.location) # 自動補完が機能します
💡 ヒント: 生成されたスタブがニーズに合わない場合は、.blender_stubs を削除して fake-bpy-module などの静的スタブを使用することもできます。 💡 ヒント: 異なる環境や新しいBlenderバージョン間で一貫した型チェック（mypy/pyright/pyrefly/ty）を行うために、.blender_stubs ディレクトリをgitリポジトリに含めることも選択肢になりえます（その際には、用途に応じ .gitattributes を設定することを推奨します）。一方で、そのような目的がない場合は、前述の通り .blender_stubs を .gitignore に追加してください。

アドオンの実行とデバッグ

アドオンを読み込んだ状態で Blender を起動したり、あるいはデバッガーを使用したりすることが可能です。

セットアップ

Run/Debug Configurations を開きます（右上のドロップダウン > Edit Configurations）。
+ ボタンをクリックし、Blender を選択します。
Name: 名前を付けます（例: “BlenderRun”）。
OK をクリックします。

Run/Debug Configurationへの導線

実行またはデバッグ

実行

Run ボタンをクリックするだけです。（プラグインが blender_manifest.toml によりアドオンルートを自動検出します。）

デバッグ

Pythonコードにブレークポイントを設定します（行番号の横のガターをクリック）。
Debug（バグアイコン）ボタンをクリックします。
Blenderが起動し、PyCharmが自動的にアタッチします。ブレークポイントに到達すると、実行が一時停止します。
ビューポートの強制再描画: ブレークポイントで一時停止中に、Blender の UI/ビューポートを強制的に再描画して現在の状態を確認できます。（⚠️ 注意: シーンによっては重い操作になる場合があります。連打は避けてください。）
- Windows / Linux: Ctrl + Alt + Shift + D
- macOS: Cmd + Opt + Shift + D

ホットリロード

ホットリロードを使用して変更を即座に反映でき、UIパネルやオペレーター等のコード変更を素早く確認できます。

PyCharm の Run または Debug から、Blender が実行中であるとします。
Python コードを変更します。
以下のいずれかの方法でリロードがトリガーされます。
- 自動: PyCharm から Blender にフォーカスを切り替えるだけです。（System Settings > Autosave の Save files when switching to a different application が有効になっている必要があります。）
- 手動: 上記設定が無効の場合、ファイルセーブ（Ctrl/Cmd + S等）を手動実行することで、トリガーされます。
Blender コンソールまたは PyCharm の通知で確認します。アドオンが更新されたコードで実行されています。

注意: これはアドオンの登録解除、sys.modules から関連モジュールのパージ、再登録を行う「ディープリロード」を実行します。ほとんどのコード変更に対応しますが、複雑な状態変更には再起動が必要な場合があります。

テスト

🚀 クイックスタート: Project Wizard を使用した場合、完全に設定済みのテストファイル（tests/run_tests.py と tests/test_sample.py）が既に含まれています。

💡 ヒント: 実際の Blender インスタンス上で動作するテストを、PyCharm（TeamCity）にネイティブ統合しつつ、CI でもまったく同じ設定で実行できるようにセットアップすることは、本質的に複雑な設定が必要となります。既存のプロジェクトにテストをセットアップする最も簡単な方法は、一時的なプロジェクトで Project Wizard を使用してテストファイルを生成し、それを自分のプロジェクトにコピー＆ペーストすることです。

PyCharmネイティブユニットテスト

PyCharm の unittest を使用できます。

Run/Debug Configurations を開きます。
+ ボタンをクリックし、Blender Test を選択します。
Name: 名前を付けます（例: “All Tests”）。
Test Directory: テストスクリプトが含まれるフォルダを選択します。
テストフォルダにこのテンプレートのような run_tests.py ファイルを作成します。
Run ボタンをクリックします。

テストの書き方

設定が完了したら、以下のようにテストを実装してTDDを実践できます。

# test_sample.py
import unittest
import bpy
# from my_addon_package import operators  <-- 自動的に動作します！

class TestSampleOperator(unittest.TestCase):
    """
    カスタムオペレーターの統合テスト。
    Blender Probe経由でBlender内で実行されます。
    """

    def setUp(self):
        # 1. Blenderをクリーンな状態にリセット
        bpy.ops.wm.read_homefile(use_empty=True)
        # 2. テストシーンのセットアップ（キューブを作成）
        bpy.ops.mesh.primitive_cube_add()
        self.test_obj = bpy.context.object
        self.test_obj.name = "TestCube"

    def test_operator_logic(self):
        """オペレーターがオブジェクトの名前を変更し、プロパティを追加することを検証"""
        # [Arrange]
        # 初期状態を確認
        self.assertEqual(self.test_obj.name, "TestCube")
        self.assertNotIn("is_processed", self.test_obj)
        # [Act]
        # カスタムオペレーターを実行（例: アドオンで定義されたもの）
        # コンテキストはBlenderが自動的に処理します。
        result = bpy.ops.object.sample_operator()
        # [Assert]
        # 1. 戻り値を確認
        self.assertIn("FINISHED", result)
        # 2. 副作用を確認（ロジックの検証）
        self.assertEqual(self.test_obj.name, "TestCube_processed")
        self.assertTrue(self.test_obj.get("is_processed"))

if __name__ == "__main__":
    unittest.main()

CI

Blender addon ウィザードで作成されたプロジェクトには、事前設定済みの GitHub Actions ワークフロー（.github/workflows/ci.yml）が含まれています。

設定不要: コードを GitHub にプッシュするだけです。
自動テスト: ワークフローがヘッドレス版の Blender（Linux）を自動的にインストールし、IDE と同じランナーロジックでテストを実行します。
リンティング: Ruff がコードスタイルをチェックします。
Dependabot: アクションと依存関係を最新の状態に保ちます。

Keyboard shortcuts

Blender Probe 操作ガイド