blender-python-scripting

Blender Python スクリプティングのエキスパート

概要

このスキルでは、Blender 5.x の Python スクリプティングに関する専門的なガイダンスを提供します。カスタムオペレーターの作成、UI パネルの構築、アドオンの開発、コンテキストの管理、ハンドラーやタイマーの使用、プロパティシステムの操作、バッチ処理、Blender のデータモデルへのアクセスを扱います。リファレンスファイルには、完全なテンプレートとデータモデルの階層が記載されています。

MCP 優先のアプローチ

実行中の Blender セッションでスクリプトを実行し、データブロックを調査し、シーンの状態を直接変更するには、公式 Blender MCP Server（Blender Lab、Blender 5.1 以降）を優先してください。MCP サーバーに接続されていない場合に限り、Python スクリプトを出力してください。

検出： セッション開始時に、execute_blender_code、get_objects_summary、search_api_docs に一致する名前のツールを探してください。これらは公式の blender-mcp サーバーに属しています。いずれかが存在すれば、MCP を利用できます。

このスキルで使用するツール：

• execute_blender_code — ライブセッションで bpy Python を実行します（主なアクション）
• get_objects_summary、get_object_detail_summary — 変更前にシーンの状態を調査します
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — ファイルの内容を一覧表示します
• search_api_docs、get_python_api_docs、search_manual_docs — API／オペレーター名が正しいことを確認してから呼び出します
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 視覚的な結果を確認します
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 変更が見えるように UI を操作します
• render_thumbnail_to_path、render_viewport_to_path — 手早く視覚的なフィードバックを取得します

ワークフロー： get_* / search_* ツールで調査 → execute_blender_code で変更 → スクリーンショットまたは概要ツールで確認。失敗箇所を特定しやすいよう、コードブロックは小さく、冪等性を保ってください。

セットアップについては、docs/blender-mcp-setup.md を参照してください。

タスクの判断ツリー

• 「カスタムオペレーターを作成する」 → references/python_api.md のオペレーターテンプレートを参照してください
• 「UI パネルを構築する」 → references/python_api.md のパネルテンプレートを参照してください
• 「Blender アドオンを開発する」 → 以下の「アドオンの構成」に従ってください
• 「ファイル／レンダーをバッチ処理する」 → バッチ処理のパターンを参照してください
• 「シーン／オブジェクトのデータにアクセスする」 → references/data_model_reference.md を参照してください
• 「プロパティを登録する」 → references/python_api.md のプロパティシステムを参照してください
• 「フレーム変更時／ファイル読み込み時にコードを実行する」 → references/python_api.md のハンドラーパターンを参照してください
• 「コンテキストエラー／poll の失敗」 → 以下の「コンテキスト管理」を参照してください

Blender 5.1 の Python に関する変更

Python 3.13 へのアップグレード

1. Blender 5.1 には Python 3.13 がバンドルされています（5.0 の 3.12 から更新）
2. アドオンのバージョン判定には bl_info["blender"] を (5, 1, 0) に更新してください
3. 型ヒントの構文（Optional[int] ではなく int | None）を使用してください。完全にサポートされるようになりました
4. CPython 3.13 ではパフォーマンスが向上しています。関数呼び出しの高速化と GC の改善が含まれます

削除されたオペレーター

1. bpy.ops.anim.convert_legacy_action — 削除されました。レイヤー化アクションが自動的に処理します

API の追加

1. bpy.ops.pose.apply_to_basis() — 現在のポーズをレストポーズとしてベイクします
2. ノードソケット型：フォントデータ用の NodeSocketFont
3. ジオメトリノード用のボリュームグリッドノード型（blender-geometry-nodes スキルを参照）

アドオンの構成

適切な Blender アドオンは、次の構成に従います。

my_addon/
├── __init__.py       # bl_info, register(), unregister()
├── operators.py      # Custom operators
├── panels.py         # UI panels
├── properties.py     # PropertyGroups
├── preferences.py    # AddonPreferences (optional)
└── utils.py          # Shared utilities

最小限の単一ファイルアドオン

bl_info = {
    "name": "My Add-on",
    "author": "Author",
    "version": (1, 0, 0),
    "blender": (5, 0, 0),
    "location": "View3D > Sidebar > My Tab",
    "description": "Short description",
    "category": "Object",
}

import bpy

class MY_OT_my_operator(bpy.types.Operator):
    bl_idname = "my.my_operator"
    bl_label = "My Operator"
    bl_options = {'REGISTER', 'UNDO'}

    @classmethod
    def poll(cls, context):
        return context.active_object is not None

    def execute(self, context):
        # ... do work ...
        return {'FINISHED'}

class MY_PT_my_panel(bpy.types.Panel):
    bl_label = "My Panel"
    bl_idname = "MY_PT_my_panel"
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'
    bl_category = "My Tab"

    def draw(self, context):
        layout = self.layout
        layout.operator("my.my_operator")

classes = (MY_OT_my_operator, MY_PT_my_panel)

def register():
    for cls in classes:
        bpy.utils.register_class(cls)

def unregister():
    for cls in classes:
        bpy.utils.unregister_class(cls)

if __name__ == "__main__":
    register()

命名規則

• オペレーター：ADDON_OT_name → bl_idname = "addon.name"
• パネル：ADDON_PT_name
• メニュー：ADDON_MT_name
• UILists：ADDON_UL_name
• PropertyGroups：ADDON_PG_name（慣例であり、強制ではありません）
• ヘッダー：ADDON_HT_name

コンテキスト管理

一般的なコンテキストの問題

Blender の操作は、現在のコンテキスト（アクティブオブジェクト、モード、エリアタイプ）に依存します。多くの bpy.ops.* 呼び出しは、コンテキストが正しくないと失敗します。

ルール：オペレーターを呼び出す前に、必ずコンテキストを確認してください。poll() メソッドを使ってオペレーターをガードしてください。

コンテキストのオーバーライド（Blender 4.x+ / 5.x）

# Modern context override using temp_override (4.0+)
with bpy.context.temp_override(active_object=obj, selected_objects=[obj]):
    bpy.ops.object.delete()

# Override with area/region for UI-dependent ops
area = next(a for a in bpy.context.screen.areas if a.type == 'VIEW_3D')
region = next(r for r in area.regions if r.type == 'WINDOW')
with bpy.context.temp_override(area=area, region=region):
    bpy.ops.view3d.camera_to_view()

モードの切り替え

# Safe mode switch
if bpy.context.object and bpy.context.object.mode != 'EDIT':
    bpy.ops.object.mode_set(mode='EDIT')

# Always return to object mode when done
bpy.ops.object.mode_set(mode='OBJECT')

よくあるコンテキストの注意点

1. バックグラウンドモードでの bpy.ops：多くのビューポートオペレーターは --background モードでは失敗します。代わりに直接データ API（bpy.data.*）を使ってください。
2. ハンドラー内のオペレーターコンテキスト：ハンドラーは通常のコンテキスト外で実行されます。bpy.context.temp_override() を使うか、ハンドラー内での bpy.ops の使用を避けてください。
3. アクティブオブジェクトが None：操作の前に、必ず context.active_object is not None を確認してください。
4. モードの不一致：オブジェクトモードのオペレーターは編集モードで失敗し、その逆も同様です。context.object.mode を確認してください。
5. Depsgraph が更新されていない：データを変更した後、必要に応じて bpy.context.view_layer.update() または depsgraph.update() を呼び出してください。
6. display_type の値はオブジェクトタイプによって異なります：'PLAIN_AXES' は Empty でのみ有効です。メッシュオブジェクトでは 'BOUNDS'、'WIRE'、'SOLID'、または 'TEXTURED' を使います。

バッチ処理

バッチレンダリング

import bpy, os

scenes_dir = "/path/to/blend/files"
output_dir = "/path/to/output"

for filename in os.listdir(scenes_dir):
    if filename.endswith(".blend"):
        filepath = os.path.join(scenes_dir, filename)
        bpy.ops.wm.open_mainfile(filepath=filepath)
        bpy.context.scene.render.filepath = os.path.join(
            output_dir, filename.replace(".blend", ".png")
        )
        bpy.ops.render.render(write_still=True)

オブジェクトのバッチ処理

import bpy

for obj in bpy.data.objects:
    if obj.type == 'MESH':
        # Select only this object
        bpy.ops.object.select_all(action='DESELECT')
        obj.select_set(True)
        bpy.context.view_layer.objects.active = obj
        # Apply all modifiers
        for mod in obj.modifiers:
            bpy.ops.object.modifier_apply(modifier=mod.name)

コマンドラインでのバッチ処理

blender --background scene.blend --python my_script.py
blender --background --python batch_render.py -- --input /files --output /renders

-- の後にカスタム引数へアクセスします：

import sys
argv = sys.argv[sys.argv.index("--") + 1:]

デバッグのヒント

1. システムコンソール：ウィンドウ > システムコンソールを切り替え（Windows）、またはターミナルから Blender を実行します
2. Python コンソール：Python コンソールのエディターエリアを開き、対話形式でテストします
3. 情報エディター：GUI 操作に対応する Python コードを表示します。API 呼び出しの調査に便利です
4. dir() と help()：Python コンソールで使い、API オブジェクトを調べます
5. bpy.context.copy()：現在のコンテキストを辞書として返し、内容を確認できます
6. モーダルオペレーターのエラー：print() 文を追加するか、例外ハンドラー内で traceback.print_exc() を使います

プロパティシステムのクイックリファレンス

種類	登録	値
BoolProperty	bpy.props.BoolProperty()	True/False
IntProperty	bpy.props.IntProperty()	min、max、default、step
FloatProperty	bpy.props.FloatProperty()	min、max、default、precision
StringProperty	bpy.props.StringProperty()	default、maxlen、subtype
EnumProperty	bpy.props.EnumProperty()	items=[(id, name, desc)]
FloatVectorProperty	bpy.props.FloatVectorProperty()	size、default、subtype
IntVectorProperty	bpy.props.IntVectorProperty()	size、default
BoolVectorProperty	bpy.props.BoolVectorProperty()	size、default
PointerProperty	bpy.props.PointerProperty()	type=PropertyGroup
CollectionProperty	bpy.props.CollectionProperty()	type=PropertyGroup

プロパティのサブタイプ

• Float/Int：'PIXEL'、'PERCENTAGE'、'FACTOR'、'ANGLE'、'TIME'、'DISTANCE'
• FloatVector：'COLOR'、'TRANSLATION'、'DIRECTION'、'VELOCITY'、'ACCELERATION'、'EULER'、'QUATERNION'、'XYZ'
• String：'FILE_PATH'、'DIR_PATH'、'FILE_NAME'、'BYTE_STRING'、'PASSWORD'

Python API リファレンス

オペレーター（基本、モーダル、ファイルダイアログ、プロパティ付きの呼び出し）、パネル（条件付き、サブパネル、折りたたみ可能）、PropertyGroup、ハンドラー、タイマー、キーマップ、コンテキストのオーバーライドを含む完全なテンプレートについては、references/python_api.md を参照してください。

データモデルのリファレンス

Blender の完全なデータ階層（bpy.data.*）、ID タイプ、オブジェクトタイプ、メッシュ／カーブ／アーマチュアのデータアクセスパターン、depsgraph の使用方法については、references/data_model_reference.md を参照してください。