Blender 3D：從新手到專業/高階教程/Blender 指令碼/外掛剖析

	簡介	• 目錄 • 詞彙表	您的外掛的使用者介面

簡介

一個外掛是一個 Python 指令碼，它可以以多種方式擴充套件 Blender 的功能。它可以位於 Blender 使用者首選項目錄中的一個檔案中，也可以儲存在 Blender 文件中的一個文字塊中。在前一種情況下，外掛需要在您想要使用它的每個 Blender 文件中啟用，方法是在該文件的使用者首選項視窗中的“附加元件”列表中選中其條目中的複選框。在後一種情況下，可以透過在文字編輯器視窗中按 ALT + P 來執行指令碼；或者您可以在文字編輯器中選中該指令碼的“註冊”複選框，使外掛在文件載入到 Blender 中時自動啟用。

外掛指令碼通常執行的主要功能是定義一個或多個新的運算子。Blender 中的所有使用者介面功能都是由運算子執行的；這些運算子透過與選單項、按鈕或熱鍵關聯來呼叫。每個運算子都是bpy.types.Operator類的子類。您在 Python 中為類提供的名稱在定義它的指令碼之外是無關緊要的；它將在 Blender 中透過其運算子名稱來引用，該名稱在文件中必須是唯一的。同樣，您的指令碼可以透過使用帶有運算子名稱的 Blender API 函式來呼叫其他地方定義的運算子。

文字塊

Blender 文件可以包含文字塊，它們與 3D 場景中的文字物件不同（雖然前者可以轉換為後者）。除了生成文字物件外，文字塊還可以滿足您喜歡的任何目的；例如，使用它將工作流程說明與文件一起傳遞給同事；在使用者開啟文件時看到的初始佈局中顯示版權或幫助訊息；或者儲存一個 Python 指令碼，使用者可以執行該指令碼來執行與文件相關的某些有用操作。

您的第一個運算子

開啟一個新的、空的 Blender 文件。在任何方便的視窗中調出文字編輯器；您將看到一個空的灰色矩形。在您開始輸入文字之前，需要建立一個文字塊；透過點選視窗標題欄中標記為“新建”的大按鈕來建立文字塊。您一這樣做，應該會看到一個彈出選單出現，列出您文件中的所有文字塊，當前（唯一）的條目名為“文字”。您還應該看到一個紅色的插入光標出現在左上角，表明您可以開始輸入。

與控制檯視窗不同，不會自動為您匯入任何內容。因此，與其他任何 Python 指令碼一樣，您需要提及您要訪問的每個模組。

您將運算子定義為的子類。bpy.types.Operator。它必須具有一個bl_idname類屬性，該屬性提供運算子名稱，而bl_label提供在空格鍵選單中顯示的使用者可見名稱。前者必須具有有效的 Python 語法作為名稱，包括一個點；點左邊的部分必須是有效運算子類別之一的名稱，您可以在控制檯視窗中鍵入

dir(bpy.ops)

來找到它們。

讓我們定義一個運算子，它將為文件新增一個新的四面體物件。類定義應該以類似以下內容開頭

class MakeTetrahedron(bpy.types.Operator) :
    bl_idname = "mesh.make_tetrahedron"
    bl_label = "Add Tetrahedron"

它必須定義一個invoke方法，該方法以類似以下內容開頭

    def invoke(self, context, event) :

該invoke方法執行運算子的實際功能；它完成後，必須返回一個字串集，告訴 Blender 一些事情，例如運算子是否仍在模態狀態下執行，或者操作是否已完成，如果是，是否成功。要指示成功完成：在invoke方法的末尾加上以下內容

        return {"FINISHED"}

無論如何，讓我們計算四面體頂點的座標：如果邊長為 1 個 Blender 單位，則合適的數值為 $(0,-{\frac {1}{\sqrt {3}}},0)$ ， $({\frac {1}{2}},{\frac {1}{2{\sqrt {3}}}},0)$ ， $(-{\frac {1}{2}},{\frac {1}{2{\sqrt {3}}}},0)$ 和 $(0,0,{\sqrt {\frac {2}{3}}})$ 。或者用 Python

        Vertices = \
          [
            mathutils.Vector((0, -1 / math.sqrt(3),0)),
            mathutils.Vector((0.5, 1 / (2 * math.sqrt(3)), 0)),
            mathutils.Vector((-0.5, 1 / (2 * math.sqrt(3)), 0)),
            mathutils.Vector((0, 0, math.sqrt(2 / 3))),
          ]

然後我們建立網格資料塊，並將其命名為“Tetrahedron”

        NewMesh = bpy.data.meshes.new("Tetrahedron")

用上面的頂點定義和相關的面填充它

        NewMesh.from_pydata \
          (
            Vertices,
            [],
            [[0, 2, 1], [0, 1, 3], [1, 2, 3], [2, 0, 3]]
          )

該Mesh.from_pydata方法目前在 Blender API 中沒有很好的文件，但它的第一個引數是Vector定義頂點的陣列，第二個引數是邊定義的陣列，第三個引數是面定義的陣列。每個邊或面都定義為一個頂點索引列表（邊中每個列表有 2 個元素，面中每個列表有 3 個或 4 個元素），以通常的 Python 風格從 0 開始，是您傳遞的頂點定義陣列中的索引。請注意，您傳遞的是邊定義或面定義，而不是兩者：另一個應該作為空列表傳遞。如果此函式使用不正確，會導致 Blender 崩潰。

我們還需要新增以下內容，告訴Blender網格已更改並需要更新（就好像它自己無法弄清楚一樣）。

        NewMesh.update()

（省略此操作會導致一個輕微的怪癖：右鍵單擊新建立的四面體不會像其他物件一樣以橙色突出顯示其輪廓，但如果您進入物件的編輯模式並再次退出，問題就會消失。）

現在建立物件資料塊（我也給它命名為“四面體”），並將其連結到網格。

        NewObj = bpy.data.objects.new("Tetrahedron", NewMesh)

但是，在將物件連結到場景之前，使用者將看不到它。

        context.scene.objects.link(NewObj)

回顧一下，這是完整的指令碼。

import math
import bpy
import mathutils

class MakeTetrahedron(bpy.types.Operator) :
    bl_idname = "mesh.make_tetrahedron"
    bl_label = "Add Tetrahedron"
    def invoke(self, context, event) :
        Vertices = \
          [
            mathutils.Vector((0, -1 / math.sqrt(3),0)),
            mathutils.Vector((0.5, 1 / (2 * math.sqrt(3)), 0)),
            mathutils.Vector((-0.5, 1 / (2 * math.sqrt(3)), 0)),
            mathutils.Vector((0, 0, math.sqrt(2 / 3))),
          ]
        NewMesh = bpy.data.meshes.new("Tetrahedron")
        NewMesh.from_pydata \
          (
            Vertices,
            [],
            [[0, 2, 1], [0, 1, 3], [1, 2, 3], [2, 0, 3]]
          )
        NewMesh.update()
        NewObj = bpy.data.objects.new("Tetrahedron", NewMesh)
        # Blender 2.79: context.scene.objects.link(NewObj)
        context.collection.objects.link(NewObj)
        return {"FINISHED"}
    #end invoke
#end MakeTetrahedron

bpy.utils.register_class(MakeTetrahedron)

注意添加了register_class呼叫，以使Blender將您的運算子新增到其內建集合中。

現在透過鍵入 ALT + P 執行您的指令碼。如果一切順利，不應該發生任何事情；Blender 將定義該類並將其註冊為您請求的新運算子，準備使用。

如果您遇到任何語法錯誤，Blender 應該會在彈出視窗中顯示這些錯誤；返回並更正它們，並使用 ALT + P 重新執行指令碼。

呼叫您的運算子

我們還沒有（尚未）為該運算子定義任何使用者介面；那麼我們如何呼叫它呢？很簡單。

轉到 3D 檢視視窗。刪除預設立方體以避免它遮擋物體，然後按 SPACE （Blender 2.8 和 Blender 3 中為 F3）。這將開啟一個可搜尋選單，其中包含為當前文件定義的每個運算子。在搜尋框中，鍵入您為bl_label屬性（鍵入“tetra”可能就足夠了）。這將限制選單僅顯示包含該字串的專案，其中應包括您的運算子的名稱；使用 LMB 單擊此運算子或突出顯示它並按 ENTER 。如果一切順利，您應該看到四面體物件出現！。如果它沒有出現，請確保在“首選項編輯器”的“介面/顯示”中選中“開發者附加功能”框。

如果您遇到錯誤

如果編譯或執行指令碼時出現任何錯誤，Blender 應該會在彈出視窗中顯示此錯誤。例如，以下簡單的單行指令碼

raise RuntimeError("Uh-oh")

顯示此彈出視窗

完整的 Python 回溯訊息將寫入標準錯誤，並且看起來像這樣

Traceback (most recent call last):
  File "/Text", line 1, in <module>
RuntimeError: Uh-Oh!

在 Linux/Unix 系統上，如果您從命令列呼叫 Blender，則該訊息將出現在終端會話中；否則，如果您從 GUI 啟動 Blender，則該訊息將附加到您的~/.xsessionerrors檔案。在 Windows 上，該訊息出現在控制檯視窗中。

	簡介	• 目錄 • 詞彙表	您的外掛的使用者介面