Godot 编辑器工具

编辑器内的扩展：@tool 脚本、数据编辑、Inspector 定制、插件、导入。默认：数据编辑器做成 Inspector 编辑的 Resource，不做独立工具窗口。

范围

先查内置

做法

数据编辑器

数据做成 @tool 的 Resource，Inspector 自带撤销、拖拽引用、复制粘贴与 diff。

@tool
class_name SpawnRule
extends Resource

enum Kind { ONCE, TIMED }

@export var kind: Kind = Kind.ONCE:
	set(value):
		kind = value
		notify_property_list_changed()
		emit_changed()
@export var interval: float = 1.0:
	set(value):
		interval = value
		emit_changed()
@export var scene: PackedScene

func _validate_property(property: Dictionary) -> void:
	if property.name == "interval" and kind != Kind.TIMED:
		property.usage = PROPERTY_USAGE_NO_EDITOR

• 资源加 @tool，_validate_property 才在编辑器里运行
• PROPERTY_USAGE_NO_EDITOR 只隐藏，值照常存盘
• 只读：property.usage |= PROPERTY_USAGE_READ_ONLY
• 整张表用数据库资源持有 Array[SpawnRule]，Inspector 里增删排序
• 重置箭头：重写 _property_can_revert 与 _property_get_revert
• 图形数据如对话树、空间数据如地图，才考虑主屏幕插件或 GraphEdit
• 自定义界面只是另一个编辑入口，数据仍存 Resource

@tool 脚本

@tool
extends Node2D

@export var rule: SpawnRule:
	set(value):
		if rule != null and rule.changed.is_connected(queue_redraw):
			rule.changed.disconnect(queue_redraw)
		rule = value
		if rule != null:
			rule.changed.connect(queue_redraw)
		queue_redraw()

func _draw() -> void:
	if rule != null and Engine.is_editor_hint():
		draw_circle(Vector2.ZERO, 16.0, Color.RED)

func _process(delta: float) -> void:
	if Engine.is_editor_hint():
		return
	position.x += 10.0 * delta

• @tool 脚本的 _process _physics_process _input 在编辑器里都跑
• 游戏逻辑用 Engine.is_editor_hint() 挡住
• @export 的 setter 在进树前调用，用子节点先判断 is_node_ready()
• 改资源内部属性不触发持有者的 setter
• 资源的 setter 里 emit_changed()，持有者连 changed，换资源时断开旧的
• _init 里读 @export 得到默认值，Inspector 的值在之后赋入
• 子类脚本不继承 @tool，要再写一遍

• 脚本对节点的改动没有撤销，场景也不标为未保存
• 批量改动走 EditorUndoRedoManager，否则调 EditorInterface.mark_scene_as_unsaved()

动态属性

属性集合由其他数据决定时才重写 _get_property_list，配合 _get 与 _set。

@tool
class_name WaveTable
extends Resource

@export var wave_count: int = 3:
	set(value):
		wave_count = clampi(value, 1, 20)
		counts.resize(wave_count)
		notify_property_list_changed()

var counts: PackedInt32Array = PackedInt32Array([5, 8, 12])

func _get_property_list() -> Array[Dictionary]:
	var props: Array[Dictionary] = []
	for i in wave_count:
		props.append({
			"name": "wave_%d_count" % i,
			"type": TYPE_INT,
			"usage": PROPERTY_USAGE_DEFAULT,
		})
	return props

func _get(property: StringName) -> Variant:
	if property.begins_with("wave_") and property.ends_with("_count"):
		return counts[property.get_slice("_", 1).to_int()]
	return null

func _set(property: StringName, value: Variant) -> bool:
	if property.begins_with("wave_") and property.ends_with("_count"):
		counts[property.get_slice("_", 1).to_int()] = value
		return true
	return false

• 可变长度数据先用 @export var counts: Array[int]，Inspector 原生增删
• 属性要带 PROPERTY_USAGE_STORAGE 才存盘，PROPERTY_USAGE_DEFAULT 已含
• 结构变了调 notify_property_list_changed()，Inspector 才重建
• _validate_property 不处理这些属性，usage 直接写在返回字典里
• _get_property_list 可能在保存线程调用，不碰场景树
• JSON 键值伪装成属性要自己做撤销与存盘，数据改成 Resource

Inspector 按钮与校验

@tool
extends Node2D

@export var target: Node2D:
	set(value):
		target = value
		update_configuration_warnings()
@export_tool_button("Snap To Target", "Reload") var snap_action: Callable = snap_to_target

func _get_configuration_warnings() -> PackedStringArray:
	var warnings := PackedStringArray()
	if target == null:
		warnings.append("target 未设置")
	return warnings

func snap_to_target() -> void:
	var ur := EditorInterface.get_editor_undo_redo()
	ur.create_action("Snap To Target", UndoRedo.MERGE_DISABLE, self)
	ur.add_do_property(self, &"global_position", target.global_position)
	ur.add_undo_property(self, &"global_position", global_position)
	ur.commit_action()

• @export_tool_button 第二个参数是编辑器内置图标名
• 按钮回调的改动走 EditorUndoRedoManager
• EditorInterface.get_editor_undo_redo() 4.4+，插件里 get_undo_redo() 是同一对象
• _get_configuration_warnings 要求脚本 @tool，条件变了调 update_configuration_warnings()
• Resource 没有警告三角，校验用 tool 按钮加 push_warning
• 游戏里也运行的脚本不能直接写 EditorInterface，编辑器部分拆到单独脚本

插件

目录 addons/<名>/ 放 plugin.cfg 与 plugin.gd，在 Project Settings 的 Plugins 页启用。

• _enter_tree 注册，_exit_tree 反注册并 queue_free 自建控件
• 文件变化连 EditorFileSystem 的 filesystem_changed 与 resources_reimported
• 尺寸乘 EditorInterface.get_editor_scale()
• 快捷键用 Shortcut 资源
• 节点与资源图标用 class_name 加 @icon，不用 add_custom_type
• 图标和面板场景写 res://addons/<名>/... 完整路径

导入外部数据

• 导入器用自定义后缀，游戏里 load 源文件路径得到资源

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法，[Tool] 与热重载
• references/export-annotations.md：@export_* 注解一览，C# 特性对照
• references/inspector-plugin.md：EditorInspectorPlugin 与 EditorProperty
• references/import-plugin.md：EditorImportPlugin 与 EditorScenePostImport
• references/editor-recipes.md：插件骨架、Dock、Autoload、主屏幕、主题、快捷键、菜单、文件变化、项目设置、EditorScript、撤销
• https://docs.godotengine.org/en/stable/tutorials/plugins/running_code_in_the_editor.html
• https://docs.godotengine.org/en/stable/tutorials/plugins/editor/index.html