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))),
          ]

然后我们创建网格数据块，并将其命名为“四面体”

        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 个元素，边为 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 视图窗口。删除默认的立方体以避免它遮挡其他物体，然后按下空格键 (Blender 2.8 和 Blender 3 中为 F3)。这将弹出一个可搜索的菜单，包含当前文档中定义的所有操作符。在搜索框中，输入你为该bl_label属性定义的字符串的一部分或全部（输入“tetra”应该足够）。这将限制菜单只显示包含该字符串的项目，其中应该包括你的操作符名称；用鼠标左键点击它，或选中它并按下回车键。如果一切顺利，你应该会看到你的四面体对象出现！如果它没有出现，请确保在偏好设置编辑器中，界面/显示的“开发者额外功能”复选框被选中。

如果遇到错误

如果在编译或运行脚本时遇到任何错误，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 上，消息会出现在控制台窗口中。

	介绍	• 目录 • 术语表	你的插件的用户界面