9.2 编辑器插件与自动化工作流

9.2 编辑器插件与自动化工作流

本节摘要：编辑器插件把你的工具长进编辑器本体——一个插件就是一个带配置文件的目录，激活即挂载，能加面板、改检查器、响应编辑事件。工具注解让脚本在编辑态运行。命令行接口让"导出、导入、校验"全部脚本化，串成自动化流水线。本节合并讲解插件开发与自动化（原书两节内容）。

数一数你每天重复的操作：导出贴图设置逐个调、关卡数据手工核对、测试构建手动打包。第十次重复做同一件事时，就该写工具了。Godot 的独特优势在这里显形——编辑器本身就是引擎做的，你给游戏写脚本的全部技能，直接用来改造编辑器。

插件的骨架：一个目录加一份清单

插件就是一个文件夹：一份配置清单（声明名字与入口脚本）加实现代码。放进项目的插件目录、在设置里激活，入口脚本的启用钩子被调用——插件上线。禁用时走禁用钩子，该清理的清理。

# 插件入口：继承编辑器插件基类
@tool
extends EditorPlugin

var _panel: Control

func _enter_tree() -> void:
    _panel = preload("res://addons/ore_tools/panel.tscn").instantiate()
    add_control_to_dock(DOCK_SLOT_LEFT_BR, _panel)      # 面板挂进停靠区
    print("矿石工具面板已挂载")

func _exit_tree() -> void:
    remove_control_from_docks(_panel)                    # 成对清理
    _panel.queue_free()
​

入口脚本能做的事横跨编辑器全身：往停靠区加自定义面板、往检查器注入属性编辑器、往主界面加新标签页、监听场景保存事件做自动校验。启动钩子与退出钩子成对出现——挂了什么，卸载时就要摘什么，这个纪律和第 2 章"连接要有断开"一脉相承。

工具注解：编辑态运行的脚本

普通脚本只在游戏运行时执行；加工具注解后，编辑器里也执行。用途是"编辑期效果预览"：地形生成脚本在编辑器里实时画出地形、瓦片自动对齐脚本随修改即时生效、自定义示波器节点在编辑视图里显示参考线。

@tool
extends Node2D

@export var radius := 100.0:
    set(v):
        radius = v
        queue_redraw()          # 参数一改 立即重画

func _draw() -> void:
    draw_circle(Vector2.ZERO, radius, Color(1, 0.4, 0.3, 0.3))
​

工具脚本是双刃：它在编辑器里跑，崩溃就是编辑器崩溃；编辑态与运行态的时序与输入并不相同，涉及时钟与输入的代码要用守卫条件区分环境。纪律：工具脚本里不做重活、不做无守卫的定时逻辑。

一个完整的小插件案例

需求很真实：矿工的矿石散在几十个场景里，数值改版时要逐个打开检查。做法：插件扫描项目里的全部矿石资源，在面板上列出清单，勾选若干项批量改数值。

三步实现。第一步建面板：控制节点搭一个列表加几个按钮（第 7 章技能直接复用）。第二步接数据：面板脚本扫描目录，把每份矿石资源读进列表显示。第三步做批量操作：勾选项、改数值、逐份保存。

# 面板脚本核心：扫描与批量改
@tool
extends PanelContainer

func _on_scan_pressed() -> void:
    %List.clear()
    for path in _find_ore_files():
        var ore := load(path) as OreConfig
        %List.add_item("%s 值%d" % [ore.display_name, ore.value])

func _on_buff_pressed(mult: float) -> void:
    for path in _find_ore_files():
        var ore := load(path) as OreConfig
        ore.value = int(ore.value * mult)
        ResourceSaver.save(ore)          # 逐份落盘
    _on_scan_pressed()                    # 刷新清单
​

这个案例的要点不在代码量，而在杠杆率：半天投入，换每次数值改版省一小时，十次改版回本，之后全是净赚。插件开发的选题就该这么算账。

自动化：命令行串起流水线

编辑器有无界面模式——命令行拉起、跑完脚本、退出。这让"导出全平台、批量重导资源、跑校验"全部可以进脚本，脚本再进持续集成系统，提交代码自动构建测试。常用两个入口：跑脚本模式（执行一段脚本后退出）与导出模式（按预设的导出配置打包某平台）。

# 自动化流水线的三段示意（命令行调用编辑器无界面模式）
# 一 导入与校验
headless --import --path 项目目录
# 二 跑自定义校验脚本
headless --script 校验脚本 --path 项目目录
# 三 按预设导出目标平台
headless --export-release 预设名 输出目录
​

流水线的价值按团队规模放大：独立开发者用它做"睡前自动出全平台包"；团队用它做"每次提交自动构建、跑冒烟测试、产物归档"。校验脚本能拦住的事故都是实打实的：资源引用断链检查、命名规范检查、场景里孤儿节点检查——全都能在构建期自动拦截，而不是等到试玩时炸开。

⚠️ 常见坑：导出配置里的密钥与签名信息直接写进配置文件进了版本库。凭据放环境变量或独立的不入库文件，配置里引用——安全习惯从第一台构建机养成。

资产库与自研的分界

编辑器插件生态里有大量现成货：地形生成、行为树编辑器、对话系统、动画重定向。选题前先查资产库（第 10 章讲生态），能用现成的就不自研——自研的理由只有三条：现成的不满足需求、项目要长期维护不想带依赖、或者学习目的本身。三个理由都不占，就用现成的，把工程时间花在游戏性上。

图 1 工程化工具的分层地图

本节要点回顾

• 插件即目录加清单：启用禁用钩子成对，挂了什么卸载时摘什么
• 工具注解双刃：编辑态实时预览是红利，崩溃与双态差异是风险，重活不进工具脚本
• 选题算账：次数乘时长大于开发成本才自研；先查资产库再决定
• 命令行三段式：导入、校验、导出全部脚本化，持续集成按团队规模放大价值
• 校验脚本拦事故：断链、命名、孤儿节点在构建期拦，别等试玩炸
• 凭据安全：密钥进环境变量不进版本库

工具链立起来了，下一节给开发装上仪表盘：性能诊断怎么看、优化从哪下手。