コードの入力と実行

PME のコード欄へ Python を書くときの前提と、入力・実行の仕様をまとめています。対象は PME 2.1 です。

重要

コード欄の編集方法を選ぶ

  • Blender 5.2 以上では Multi-line Command Editor を有効にすると、Command / Custom と Context Router の Target を複数行で編集できます。Shift+Enter で改行し、Enter で欄の編集を終えてからスロットを保存します。PME の popup editor は1行欄のままなので、複数行の編集には Preferences を使います。

  • 設定がオフ、または以前の Blender では従来の1行欄を使います。メニューの Poll、Property、description 式の欄は変わりません。

  • 長い処理や再利用する処理には外部の Python ファイルも使えます。execute_script("scripts/my_action.py") で呼び出します。

Command / Custom の保存と Blender 標準 UI 経由の実行には、PME 独自の文字数上限はありません。Context Router の Target も同じです。編集設定が変えるのは欄の表示であり、保存する本文や実行経路は変わりません。

GPU メニュー(Floating Panel / Vector Menu)に描く通常の Command スロットと Context Router の Command Target は、共通の operator 引数運搬により、文字列1つにつき4,096文字までです。本文や文字列引数がこの運搬上限を超えると実行されず、operator_property_string_too_long 診断が出ます。通常の Command を Blender operator へ直接変換できる場合は引数を個別に運ぶため、各文字列引数が上限内なら本文全体が4,096文字を超えても通ることがあります。Blender 標準 UI のメニューを使うか、この経路には外部スクリプトの短い呼び出しを置いてください。

関数・変数と引数の仕様は API リファレンス、メニューの利用条件は Poll Method を参照してください。

コード欄には貼り付け用の1行を用意する

1行欄で Command / Custom を編集する場合やメニューの Poll では、短い処理を1行にして入力します。複数行の Command / Custom には、上記の編集設定を使います。

書きたい処理

1行の形

注意点

単純な文を順番に実行

x = 1; print(x)

; は実行順を作る。対話操作の終了待ちにはならない

条件によって値を選ぶ

value_if_true if condition else value_if_false

各名前を実際の式に置き換える

条件を満たすときだけ実行

condition and action()

左側が真のときだけ右側を評価する

Poll の結果を返す

return C.mode == 'OBJECT'

メニューの Poll 用。Command では使わない

if / for / def のブロックを、改行から ; への置換だけで変換することはできません。Command / Custom のブロックには複数行エディターを使い、再利用する処理は 外部ファイルへ分けられます。

複数行の操作履歴を取り込む場合

操作記録の取り込みには、オペレーター呼び出しや代入を抽出して1行にまとめる経路があります。任意の Python スクリプトをそのまま保存する機能ではありません。取り込み後の内容も確認してください。

設定先と実行タイミング

設定先

評価されるとき

書く内容

Command

項目を実行したとき

オペレーターの呼び出し、値の変更

Custom

UI を描画するとき。再描画で繰り返す

L を使う UI の配置。描画そのものではデータを変更しない

メニューの Poll

メニューが利用できるかを調べるとき

条件を読み、return で判定結果を返す。データを変更しない

Property の Getter / Setter / Update

値の取得・書き込み・更新時

役割ごとの処理。コールバックの仕様を参照

execute_script() で呼ぶファイル

呼び出し元が評価されたとき

呼び出し元の役割に応じた処理。Custom から呼べば描画時に実行される

たとえば Custom に bpy.ops.mesh.primitive_cube_add() と書くと、描画時に追加処理を実行してしまいます。ボタンを置くなら L.operator("mesh.primitive_cube_add") を使います。

PME が用意する名前と、自分で用意する名前

PME のコード欄には便利な名前が用意されています。ただし、すべての設定先で 同じ値が揃うわけではありません。次の表は、Command / Custom と、そこから execute_script() で呼ぶファイルを読むための入口です。

名前

用途

前提・注意点

C / context

その実行・描画で PME が提供するコンテキストを読む

bpy.context と同じオブジェクトとは限らない。対象のないメンバーは None の場合がある

bpy

Blender の API を使う

描画経路によって bpy.context の見え方を PME が調整する場合がある

D

Blender のデータへのアクセス

bpy.data のショートカット。特定オブジェクトが存在する保証はない

O

Blender のオペレーターを呼ぶ

bpy.ops のショートカット。呼び出し条件は省略されない

T

Blender の型へのアクセス

bpy.types のショートカット

L

現在のレイアウトに UI 部品を描く

Custom など、レイアウトを受け取る描画時に使う。Command 用の操作対象ではない

E

その処理に渡された入力イベントを調べる

イベントのない評価では名前自体が提供されない場合がある

U

PME のセッション内で一時的な値を共有する

保存先ではない。PME の再登録や Blender の再起動をまたぐ値に使わない

pm、pmi、menu などの名前は、設定先ごとの意味を確認してください。 たとえば Property のコールバックでの menu は Property ID です。 別のスロットの例をそのまま流用せず、Property のコールバック の説明を使います。

外部ファイルで独自の関数、mathutils.Vector、他のモジュールを使う場合は、 そのファイル自身で定義・インポートします。PME が現在提供する名前と、 以前 Python Console に入力した変数を混同しないでください。

外部ファイルを実行する

長い処理は通常の Python ファイルへ書き、PME から execute_script() で呼びます。

ファイルブラウザーから選ぶ

スロットを Edit Slot で開き、タブ右端のメニューから Call External Script を選びます。 Quick Locations の登録名を押すと、そのリソースフォルダーの scripts/ へ移動します。 .py ファイルを選び、Use Script As で用途を指定して Open Script を押します。

My Studioのscriptsフォルダーを開いたファイルブラウザー。Use Script AsにCommand TabとCustom Tab、Quick Locationsに登録名が並ぶ

My Studio の scripts/ を開いた例。Script Examples からは PME 同梱のスクリプト例を開けます。

  • Command Tab — メニューの項目を実行したときにスクリプトを呼びます。

  • Custom Tab — メニューの描画時にスクリプトを呼びます。L で UI を配置するスクリプトに使います。

選んだファイルを呼ぶコードがスロットへ入り、OK で確定します。 登録先の中にあるファイルは、scripts/modeling/bevel_selected.py や tools/bevel_selected.py のような、登録フォルダーからの相対参照で保存します。 登録先の外にあるファイルは絶対パスを保持します。場所の登録と同名ファイルの扱いは、保存先とフォルダ構成を参照してください。

バージョン 2.2.0 で変更: Quick Locations から各登録先の scripts/ を開けるようになり、そこから選んだファイルは登録フォルダーからの相対パスで保存されます。

引数を渡して実行する

次は、選択中のオブジェクト数を表示する例です。ファイルの呼び出しはコード欄へ直接入力することもできます。

1. ファイルを置く — 保存先とフォルダ構成にあるユーザースクリプトのフォルダへ、selection_report.py を保存します。

ファイル本文(複数行):

return_value = False

def build_report(context, prefix):
    objects = getattr(context, "selected_objects", ()) or ()
    return f"{prefix}: {len(objects)}"

report = build_report(C, str(kwargs.get("prefix", "Selection")))
message_box(report)
return_value = report

2. 呼び出しを設定する — パイメニューのスロット → Command に、次の1行を貼り付けます。

execute_script("scripts/selection_report.py", prefix="Selected objects")

3. 確認する — 3D Viewport の Object Mode でオブジェクトを選び、この項目を実行します。選択数のメッセージが出ます。選択を外して実行すると 0 と表示されます。

ファイルの場所と引数

項目

意味

scripts/selection_report.py

登録したリソースフォルダーが基準。全登録先を検索し、一意に見つかったファイルを実行。重複した場合は実行せず、候補がなければアドオン本体の中を検索

tools/selection_report.py

どの相対パスも同じ規則。scripts/ は普通のフォルダー名

絶対パス

そのファイルを直接実行

kwargs

呼び出しで渡した引数の辞書。prefix という変数が自動で作られるわけではない

__file__

実際に読み込んだファイルのパス

return_value

execute_script() の戻り値。ファイル直下では return 文を使わず、これに代入する

戻り値を使う場合は呼び出し側で変数へ代入します。戻り値は自動表示されないため、上の例では message_box() を呼んでいます。PME 2.1 ではファイル先頭のインポートや定義を、同じ実行で定義した関数からも参照できます。

外部ファイルに移しても、呼び出し元のコンテキストや評価タイミングは変わりません。設定をほかの環境へ渡す場合は、ファイルも一緒に用意します。

戻り値を成功判定に使うとき

return_value の既定値は True です。例外を捕捉した経路でもその値が返る場合があり、戻り値だけを汎用的な成功判定にはできません。例では冒頭に False、処理の最後に結果を設定しています。エラー出力と実際の結果も確認してください。この代入は、途中まで行ったデータ変更を取り消す仕組みではありません。

オペレーターの実行場所とタイミング

bpy.ops の呼び出しには、引数だけでなく実行場所の条件があります。 同じ文字列でも、3D Viewport からの実行と Preferences 上のボタンでは結果が異なり得ます。

  • 必要なエディターとリージョンにいるか。

  • 必要なモードか。アクティブな対象と選択対象は揃っているか。

  • 引数名と値が、使っている Blender のバージョンに存在するか。

  • 操作をその場で確定するのか、マウスで調整する操作を始めるのか。

EXEC_DEFAULT は指定した値で実行する経路、INVOKE_DEFAULT はオペレーターの 開始処理を呼ぶ経路です。後者はダイアログやマウス操作に進む場合がありますが、 すべてのオペレーターが両方の使い方を提供するわけではありません。 詳しくは Blender の Operator APIを参照してください。

オペレーターが RUNNING_MODAL を返すと、ユーザーによる操作がまだ続いています。 その呼び出しの後ろに ; で書いた Python が、操作の確定まで待つとは考えないでください。 ユーザーの調整を挟む手順には Macro Operatorも検討します。

コンテキストエラーのたびに、見つかった最初のエリアへ切り替えるコードを足すと、 意図しないビューで動く原因になります。まず本来のエディターから呼び出し、 ホットキーの範囲を確認します。別エリアを対象にする必要がある場合だけ、 対象の選び方と、見つからないときの動作を決めます。

別のエリアを対象にする

たとえば、UV Editor に置いたボタンから 3D Viewport のオーバーレイを切り替えたいとします。 C.space_data はボタンのあるエリア、つまり UV Editor の設定です。そのまま書くと UV Editor 側が切り替わります。

override_context() で対象のエリアを指定してから、コードを書き、最後に exit() を呼びます。

oc = override_context('VIEW_3D'); C.space_data.overlay.show_overlays ^= True; oc.exit()
  • override_context() から oc.exit() までの間、C は指定したエリアを指します。 bpy.ops の呼び出しも、そのエリアで実行されます。

  • この1行の例では ; でつなぎます。Blender 標準の bpy.context.temp_override(...) を with ブロックで使う場合は、複数行の Command 欄か外部スクリプトを使います。

  • exit() は必ず呼びます。呼び忘れた override は元に戻りません。

  • 第1引数は Space Type Items の文字列('VIEW_3D' など)か、bpy.types.Area です。文字列のときは、同じ種類の エリアが複数あれば最初に見つかったエリアが対象です。特定のエリアを指したい場合は、 bpy.types.Area をそのまま渡します。

  • 指定したエリアが見つからない場合は、現在のエリアのままです。

引数の詳細は API リファレンス の override_context() を参照してください。 Python Console で同じことをする場合は、 Context Browser の Area Picker が with C.temp_override(...): の形で入力を包みます。PME のコード欄では、この節の override_context() を使います。

エラーを切り分ける

Blender の Python Console に入力したコードの結果と、PME の print() の出力先は 同じとは限りません。print() や Python の例外は、Blender の標準出力・エラー出力を 確認します。macOS では Blender を起動したターミナルなどが出力先になります。

症状

最初に確認すること

NameError

必要な名前を、そのファイル内でインポート・定義しているか。L や E を使える設定先か

ModuleNotFoundError

依存モジュールが Blender の Python に存在するか。システムの Python に入れただけではないか

AttributeError / NoneType

対象なしの状態、オブジェクト型、プロパティ名、Blender のバージョン

poll() failed

Blender オペレーターが要求するエディター、リージョン、モード、選択状態

コード末尾の構文エラー

貼り付けたコードが元の内容と一致しているか

Text Editor では動くが PME では動かない

不足しているインポート、別の実行で残った変数、実行場所の違い

処理は進むが期待した結果にならない

CANCELLED などのオペレーター結果、対象の選び方、非同期の操作が続いていないか

対象の状態だけを出力する短い Command を、本来使うエディターから呼ぶと、 エラーの起きる状態を絞れます。

print("PME context:", getattr(C.area, "type", None), C.mode, C.active_object)

まず一つの処理で結果を確かめてから、分岐や連続操作を追加します。 データ変更を伴う場合は、対象がある場合・ない場合の両方と、Undo / Redo を確認します。 ; で連続させたことや EXEC_DEFAULT を使ったことだけでは、 一つの Undo にまとまるとは限りません。履歴を見ずに bpy.ops.ed.undo_push() を 機械的に追加しないでください。

関連するリファレンス