1. 项目概述为什么我们需要自己的游戏工具集如果你用Godot引擎做过几个项目尤其是稍微复杂一点的你大概率会和我有同样的感受引擎本身很强大但总有些重复性的、琐碎的、或者引擎原生支持不那么顺手的工作需要自己动手去“补全”。比如批量重命名资源、快速生成特定类型的占位符、自动化处理动画帧、管理游戏配置表甚至是处理一些特定的美术资源格式。每次新开项目这些工具要么得重新写要么就得从旧项目里翻找、复制粘贴效率低下不说还容易出错。“Godot Game Tools 项目教程”这个标题指向的正是解决这个痛点。它不是一个教你做某个具体游戏玩法的教程而是一个教你如何为Godot引擎“打造趁手兵器”的指南。它的核心价值在于将你从一个被动的引擎使用者转变为一个能主动扩展引擎工作流、提升开发效率的“工具锻造者”。这背后涉及的核心领域是游戏开发工具链的定制化潜在需求是提升团队协作效率、规范开发流程、减少人为错误。核心技术点则围绕Godot EditorPlugin编辑器插件系统、GDScript/Python自动化脚本、以及如何将零散脚本组织成可维护、可复用的工具集。简单来说这个项目适合所有不满足于Godot“开箱即用”功能希望让自己的开发过程更丝滑、更专业的开发者。无论你是独立开发者想提升个人效率还是团队技术负责人希望统一团队工具从这里都能找到思路和落地方案。2. 核心思路从散装脚本到系统化工具集很多人的“工具集”起步于一个混乱的scripts/或utils/文件夹里面塞满了各种.gd脚本。需要用时要么在编辑器里手动运行要么写个简单的按钮界面。这种做法初期很快但随着工具增多会面临管理混乱、依赖不清、使用不便需要记住脚本路径和参数等问题。一个成熟的“Game Tools”项目应该追求以下几个目标集成化工具应该无缝集成到Godot编辑器的界面中通过菜单、面板、右键菜单等方式触发降低使用心智负担。可配置化工具的行为应该可以通过友好的UI如Inspector面板进行配置而不是硬编码在脚本里。可复用与可分发工具集应该易于打包、分享并能被其他项目直接引用。健壮性具备良好的错误处理和用户反馈避免因工具使用不当导致项目数据损坏。基于这些目标我们的核心实现路径就是Godot EditorPlugin编辑器插件。这是Godot官方提供的、用于扩展编辑器功能的强大系统。通过它我们可以创建自定义的Dock停靠面板、在菜单栏添加项、为特定资源类型添加Inspector插件甚至修改编辑器的部分视图。2.1 工具集的常见分类与设计在动手之前我们先对常见的游戏开发工具做个分类这有助于我们规划工具集的结构资源处理工具这是最普遍的一类。例如精灵图/纹理处理批量裁剪、缩放、格式转换、生成九宫格信息。音频处理批量导入、标准化音量、生成播放列表。字体管理动态字体生成与预览。场景预处理自动为场景中的节点添加特定组件、检查场景规范。数据管理工具本地化/多语言工具提取场景和脚本中的文本生成CSV或JSON表格并支持导入回填。游戏配置表编辑器一个可视化的表格编辑器用于编辑平衡数值、关卡数据等并能导出为Godot可读的Resource或脚本。存档数据编辑器在编辑器中模拟查看和修改游戏存档结构。开发辅助工具性能分析助手一键生成当前场景的性能报告Draw Call、节点数、脚本内存等。快速原型工具一键生成带有基础移动、碰撞的玩家角色预制体。版本与构建工具自定义构建管道自动化处理构建前/后的资源打包、版本号递增等。注意工具开发本身也是开发要避免“过度工程化”。一个好的原则是“三次法则”当某个手动操作重复第三次时就应该考虑将其工具化。先从解决自己最痛的一个点开始。3. 实战构建一个资源批量重命名工具让我们从一个最实用、也最经典的工具开始资源批量重命名。这个工具将展示一个完整EditorPlugin的创建、UI设计、与编辑器交互的全过程。3.1 创建插件项目结构与入口首先我们不在游戏项目里直接写工具而是创建一个独立的插件项目。这样便于管理和分发。新建Godot项目命名为GodotGameTools。项目结构清晰是关键。创建插件目录和文件在项目根目录创建addons/godot_game_tools/文件夹。这是Godot插件的标准存放位置。在godot_game_tools/下创建plugin.cfg文件。这是插件的“身份证”。# plugin.cfg [plugin] nameGodot Game Tools descriptionA collection of handy tools for Godot game development. authorYour Name version1.0.0 scriptplugin.gd在godot_game_tools/下创建plugin.gd文件。这是插件的入口脚本。# plugin.gd tool # 必须添加表明这是一个编辑器工具脚本 extends EditorPlugin const MainDock preload(res://addons/godot_game_tools/ui/main_dock.tscn) var main_dock_instance: Control func _enter_tree(): # 插件激活时调用 main_dock_instance MainDock.instantiate() # 将我们的自定义Dock添加到编辑器界面 add_control_to_dock(EditorPlugin.DOCK_SLOT_LEFT_BR, main_dock_instance) print(Godot Game Tools 插件已加载。) func _exit_tree(): # 插件停用时调用 if main_dock_instance: remove_control_from_docks(main_dock_instance) main_dock_instance.queue_free() print(Godot Game Tools 插件已卸载。)激活插件在Godot编辑器顶部菜单栏进入项目 - 项目设置 - 插件你应该能看到“Godot Game Tools”。勾选“启用”复选框。如果一切正常你会在编辑器界面通常是左下角或右下角看到一个空白的Dock面板并且输出栏会打印加载信息。3.2 设计批量重命名工具的UI现在我们来为这个Dock添加内容。创建ui/main_dock.tscn场景。场景根节点创建一个VBoxContainer命名为MainDock。添加UI控件在VBoxContainer下添加一个Label文本设为“批量重命名工具”。添加一个HSeparator作为分隔线。添加一个GridContainer列数设为2用于排列参数输入。第一行Label“目标文件夹” LineEdit命名为target_folder_edit用于显示路径。第二行Label“查找文本” LineEdit命名为find_text_edit。第三行Label“替换文本” LineEdit命名为replace_text_edit。在GridContainer下添加一个Button文本设为“选择文件夹”命名为select_folder_btn。我们将用它来打开文件夹选择对话框。添加一个CheckBox文本设为“包含子目录”命名为recursive_checkbox。添加一个TextEdit命名为log_text将其设为只读用于显示操作日志。最后添加一个Button文本设为“执行重命名”命名为execute_btn。UI布局大致如下[批量重命名工具] ------------------- 目标文件夹[LineEdit] [选择文件夹] 查找文本 [LineEdit] 替换文本 [LineEdit] [ ] 包含子目录 [执行重命名] ------------------- [Log TextEdit]3.3 实现核心重命名逻辑创建脚本ui/main_dock.gd并附加到MainDock根节点。# main_dock.gd tool extends VBoxContainer onready var target_folder_edit: LineEdit $GridContainer/target_folder_edit onready var find_text_edit: LineEdit $GridContainer/find_text_edit onready var replace_text_edit: LineEdit $GridContainer/replace_text_edit onready var select_folder_btn: Button $select_folder_btn onready var recursive_checkbox: CheckBox $recursive_checkbox onready var log_text: TextEdit $log_text onready var execute_btn: Button $execute_btn func _ready(): select_folder_btn.pressed.connect(_on_select_folder_pressed) execute_btn.pressed.connect(_on_execute_pressed) _log_message(批量重命名工具就绪。) func _on_select_folder_pressed(): # 使用EditorFileDialog来选择文件夹 var dialog EditorFileDialog.new() dialog.file_mode EditorFileDialog.FILE_MODE_OPEN_DIR dialog.access EditorFileDialog.ACCESS_RESOURCES dialog.dir_selected.connect(_on_folder_selected) # 将对话框添加到编辑器界面 EditorInterface.get_base_control().add_child(dialog) dialog.popup_centered_ratio(0.7) func _on_folder_selected(dir_path: String): target_folder_edit.text dir_path _log_message(已选择文件夹: dir_path) func _on_execute_pressed(): var target_dir: String target_folder_edit.text.strip_edges() var find_str: String find_text_edit.text var replace_str: String replace_text_edit.text var recursive: bool recursive_checkbox.button_pressed if target_dir.is_empty(): _log_message(错误请先选择目标文件夹。, true) return if find_str.is_empty(): _log_message(错误查找文本不能为空。, true) return _log_message(开始批量重命名...) _log_message(目录: target_dir) _log_message(查找: \ find_str \ 替换为: \ replace_str \) var renamed_count _rename_files_in_directory(target_dir, find_str, replace_str, recursive) _log_message(操作完成。共重命名了 str(renamed_count) 个文件。) func _rename_files_in_directory(dir_path: String, find: String, replace: String, recursive: bool) - int: var dir DirAccess.open(dir_path) if not dir: _log_message(错误无法访问目录 - dir_path, true) return 0 var count 0 dir.list_dir_begin() # 开始遍历 while true: var file_name dir.get_next() if file_name : break if file_name . or file_name ..: continue var full_path dir_path.path_join(file_name) if dir.current_is_dir(): if recursive: # 递归处理子目录 count _rename_files_in_directory(full_path, find, replace, recursive) else: # 处理文件 if find in file_name: var new_file_name file_name.replace(find, replace) var new_full_path dir_path.path_join(new_file_name) var error dir.rename(full_path, new_full_path) if error OK: _log_message(重命名: file_name - new_file_name) count 1 else: _log_message(失败: file_name (错误码: str(error) ), true) dir.list_dir_end() return count func _log_message(msg: String, is_error: bool false): var prefix [ERROR] if is_error else [INFO] log_text.text prefix msg \n # 自动滚动到底部 log_text.scroll_vertical log_text.get_line_count()3.4 关键点解析与避坑指南tool关键字这是灵魂。任何需要在编辑器中运行的脚本包括插件主脚本、工具脚本、以及插件内的场景脚本都必须在顶部添加tool。没有它你的代码在编辑器中不会执行。使用EditorFileDialog在插件中我们不能用普通的FileDialog而必须使用EditorFileDialog。它是编辑器感知的能正确显示项目资源目录。注意获取EditorInterface.get_base_control()作为其父节点。路径处理res://是项目资源路径。我们的工具主要操作这个范围内的文件。使用DirAccess类进行文件遍历和重命名操作。list_dir_begin()、get_next()、list_dir_end()是标准遍历模式。重命名操作DirAccess.rename()是原地重命名。这是一个危险操作所以在工具中我们加入了详细的日志输出并且在执行前做了基本的参数校验。在实际更复杂的工具中应该考虑加入“预览”或“撤销”功能。线程与性能如果处理成千上万个文件上述同步操作会阻塞编辑器UI。对于重型工具需要考虑使用Thread或Worker在后台处理并通过call_deferred更新UI。实操心得在开发编辑器工具时养成频繁使用print()或像我们这样写日志面板的习惯。因为工具脚本的调试不如游戏运行时直观清晰的日志是排查问题的生命线。另外工具的第一个版本可以只实现核心功能快速验证可行性。像“撤销”这种高级功能可以在后续迭代中加入。4. 进阶打造一个简易的本地化文本提取工具资源重命名工具展示了基础的文件操作。现在我们挑战一个更复杂、也更实用的工具从场景和脚本中提取所有需要本地化的字符串并导出为CSV文件。这个工具涉及对Godot项目资源的深度解析。4.1 设计思路与数据结构我们需要扫描两种主要资源场景文件.tscn提取所有Label、Button、RichTextLabel等控件的text属性。GDScript文件.gd提取所有被标记的字符串例如通过特定的函数调用如tr(...)或自定义标记。输出是一个CSV文件结构如下key,source_text,zh_CN,en_US,ja_JP ui.main.title,主菜单,Main Menu,メインメニュー dialog.intro.001,你好冒险者,Hello, Adventurer!,こんにちは、冒険者さん4.2 实现场景文件解析器创建脚本utils/scene_parser.gd。# scene_parser.gd tool extends RefCounted class_name SceneParser # 定义需要提取text属性的节点类型和属性名 const TEXT_NODES : { Label: text, Button: text, CheckBox: text, CheckButton: text, LinkButton: text, MenuButton: text, # 注意MenuButton的text属性可能在其PopupMenu中 OptionButton: text, # 需要特殊处理其项是数组 RichTextLabel: text, LineEdit: [text, placeholder_text], TextEdit: text, Window: title, } func parse_scene_file(file_path: String) - Dictionary: var result : {strings: [], errors: []} if not FileAccess.file_exists(file_path): result[errors].append(文件不存在: file_path) return result var file FileAccess.open(file_path, FileAccess.READ) if not file: result[errors].append(无法打开文件: file_path) return result var content file.get_as_text() file.close() # 简单解析.tscn文件这是一个文本格式的资源文件 # 我们寻找形如 text 某段文字 的键值对 # 注意这是一个简化解析器复杂的嵌套结构需要更健壮的解析器如正则表达式或官方解析API var lines content.split(\n) var inside_node false var current_node_type var string_matches [] for line in lines: line line.strip_edges() if line.begins_with([): inside_node line.begins_with([node ) if inside_node: # 提取节点类型例如 type Label var type_match line.match(type ([^])) if type_match: current_node_type type_match[1] else: current_node_type continue if inside_node and not current_node_type.is_empty(): # 检查这个节点类型是否在我们关注的列表中 if TEXT_NODES.has(current_node_type): var prop_name TEXT_NODES[current_node_type] var prop_names [] if prop_name is String: prop_names.append(prop_name) else: # 是数组 prop_names prop_name for p_name in prop_names: # 匹配 pattern: prop_name value var pattern p_name ([^]) var regex RegEx.new() regex.compile(pattern) var match_result regex.search(line) if match_result: var extracted_text match_result.get_string(1) if extracted_text and not extracted_text.is_empty(): # 生成一个简单的key例如scene_file_path/path/to/node::property # 这里简化处理只存储文本和来源 string_matches.append({ text: extracted_text, source: file_path ( current_node_type . p_name ), type: scene }) result[strings] string_matches return result4.3 实现脚本文件解析器创建脚本utils/script_parser.gd。这里我们重点查找tr()函数调用这是Godot推荐的国际化函数。# script_parser.gd tool extends RefCounted class_name ScriptParser func parse_script_file(file_path: String) - Dictionary: var result : {strings: [], errors: []} if not FileAccess.file_exists(file_path): result[errors].append(文件不存在: file_path) return result var file FileAccess.open(file_path, FileAccess.READ) if not file: result[errors].append(无法打开文件: file_path) return result var content file.get_as_text() file.close() # 使用正则表达式查找 tr(...) 调用 var regex RegEx.new() # 这个正则匹配 tr(...)并考虑了可能的转义引号和嵌套简单情况 regex.compile(tr\\(\\s*([^\\\\]*(?:\\\\.[^\\\\]*)*)\\s*\\)) var matches regex.search_all(content) for match in matches: var extracted_text match.get_string(1) # 处理字符串中的转义字符例如 \\n, \\ extracted_text extracted_text.replace(\\n, \n).replace(\\, ).replace(\\\\, \\) if extracted_text and not extracted_text.is_empty(): result[strings].append({ text: extracted_text, source: file_path (tr()), type: script }) return result4.4 集成到主插件并创建UI现在我们需要在主Dock中新增一个标签页或面板来承载这个本地化工具。修改UI在main_dock.tscn中添加一个TabContainer。第一个标签放我们之前的重命名工具第二个标签新建一个VBoxContainer用于本地化工具。本地化工具UI在第二个标签页内添加以下控件Button“扫描项目”用于开始扫描。Tree用于显示扫描出的字符串列表显示Key、源文本、来源文件。LineEdit“Key前缀”让用户自定义生成Key的前缀如ui.。Button“导出为CSV”。TextEdit用于显示扫描日志。实现扫描逻辑在main_dock.gd中为“扫描项目”按钮连接信号。其回调函数需要使用DirAccess递归遍历res://目录。对每个.tscn文件调用SceneParser.parse_scene_file。对每个.gd文件调用ScriptParser.parse_script_file。将收集到的所有字符串去重、合并并显示在Tree控件中。实现导出逻辑用户可以在Tree中编辑生成的Key或使用自动生成的Key如source_text.md5的一部分然后点击“导出为CSV”将Tree中的数据按照CSV格式写入文件。注意事项这个文本提取器是“启发式”的并不完美。Godot的场景文件格式.tscn本质上是文本但解析它需要考虑嵌套、资源引用、多行字符串等多种复杂情况。上述的简单字符串匹配可能会漏掉一些情况或产生误匹配。对于生产环境有两种更可靠的方法一是使用Godot引擎内部的ResourceLoader加载场景为PackedScene然后实例化并遍历节点树来读取属性但这在编辑器插件中可能带来性能开销和副作用二是寻找或编写更完善的.tscn文件解析库。我们的版本作为教程和起点已经能处理80%的常见情况。5. 工具集的打包、分享与进阶方向5.1 插件打包与分发当你开发了一套好用的工具集自然会想分享给团队成员或其他开发者。清理与测试确保插件代码整洁移除调试用的print语句或者将其改为可开关的调试日志。创建发布包最简单的方式就是直接将addons/godot_game_tools/文件夹压缩成ZIP包。接收者只需解压到其项目的addons/目录下然后在插件设置中启用即可。使用Git子模块或Godot资产库对于团队协作可以将工具集作为一个独立的Git仓库然后通过Git子模块引入到各个游戏项目中。更正式的做法是将其发布到Godot的官方或第三方资产库如 godotengine/asset-library 但这需要遵循更严格的规范和提供元数据。5.2 进阶工具开发方向掌握了基础插件开发后你可以探索更强大的功能自定义Inspector插件为特定的Resource或Node创建属性编辑器。例如为一个“敌人配置”资源创建一个可视化的属性表格而不是在Inspector里填一堆纯文本。编辑器视图扩展比如在2D编辑器视图中绘制自定义的辅助线、网格或碰撞体预览。与外部工具集成通过OS.execute()调用命令行工具比如调用Aseprite命令行进行精灵图处理或者调用ImageMagick进行批量图片转换。创建独立的工具窗口不仅仅是Dock你可以创建浮动、可停靠的独立窗口用于更复杂的管理界面比如一个完整的对话树编辑器。5.3 常见问题与排查实录Q1我的插件按钮点击后没反应也没有错误日志。A1首先检查脚本顶部是否有tool。其次检查信号连接是否正确。在_ready()函数里用print()确认函数被调用。最后检查代码逻辑特别是文件路径和权限问题。Q2插件在编辑器中运行正常但游戏导出后工具功能消失了。A2这是正常现象。tool脚本和EditorPlugin只在编辑器中运行不会包含在导出的游戏运行时中。这是设计使然。Q3我修改了插件代码但编辑器里看不到变化。A3Godot对编辑器插件的热重载支持有限。最可靠的方法是在项目设置的插件页面先禁用插件再重新启用。这会触发_exit_tree()和_enter_tree()重新加载插件。Q4工具操作文件时Godot编辑器报“资源正在被使用”错误。A4如果你尝试重命名或删除一个当前在编辑器中打开或被引用的资源Godot会阻止你。一种策略是在操作前使用EditorInterface.get_resource_filesystem()获取文件系统实例并尝试让编辑器释放该资源或者直接提示用户关闭相关场景/资源。Q5如何让工具支持“撤销/重做”功能A5Godot编辑器提供了EditorUndoRedoManager。在进行任何会修改项目数据的操作前你需要创建一个撤销操作组。例如在重命名文件前调用undo_redo.create_action(Batch Rename)然后为每个文件重命名调用undo_redo.add_do_method(obj, rename, old, new)和undo_redo.add_undo_method(obj, rename, new, old)最后undo_redo.commit_action()。这需要更精细的设计。开发Godot编辑器工具是一个深入理解引擎架构的过程。从解决自己的一个小麻烦开始逐步构建起一个强大的个性化工具集这种成就感不亚于完成一个游戏关卡。记住最好的工具永远是那个为你自己的工作流量身定做的工具。
Godot编辑器插件开发：从零构建游戏开发工具集
1. 项目概述为什么我们需要自己的游戏工具集如果你用Godot引擎做过几个项目尤其是稍微复杂一点的你大概率会和我有同样的感受引擎本身很强大但总有些重复性的、琐碎的、或者引擎原生支持不那么顺手的工作需要自己动手去“补全”。比如批量重命名资源、快速生成特定类型的占位符、自动化处理动画帧、管理游戏配置表甚至是处理一些特定的美术资源格式。每次新开项目这些工具要么得重新写要么就得从旧项目里翻找、复制粘贴效率低下不说还容易出错。“Godot Game Tools 项目教程”这个标题指向的正是解决这个痛点。它不是一个教你做某个具体游戏玩法的教程而是一个教你如何为Godot引擎“打造趁手兵器”的指南。它的核心价值在于将你从一个被动的引擎使用者转变为一个能主动扩展引擎工作流、提升开发效率的“工具锻造者”。这背后涉及的核心领域是游戏开发工具链的定制化潜在需求是提升团队协作效率、规范开发流程、减少人为错误。核心技术点则围绕Godot EditorPlugin编辑器插件系统、GDScript/Python自动化脚本、以及如何将零散脚本组织成可维护、可复用的工具集。简单来说这个项目适合所有不满足于Godot“开箱即用”功能希望让自己的开发过程更丝滑、更专业的开发者。无论你是独立开发者想提升个人效率还是团队技术负责人希望统一团队工具从这里都能找到思路和落地方案。2. 核心思路从散装脚本到系统化工具集很多人的“工具集”起步于一个混乱的scripts/或utils/文件夹里面塞满了各种.gd脚本。需要用时要么在编辑器里手动运行要么写个简单的按钮界面。这种做法初期很快但随着工具增多会面临管理混乱、依赖不清、使用不便需要记住脚本路径和参数等问题。一个成熟的“Game Tools”项目应该追求以下几个目标集成化工具应该无缝集成到Godot编辑器的界面中通过菜单、面板、右键菜单等方式触发降低使用心智负担。可配置化工具的行为应该可以通过友好的UI如Inspector面板进行配置而不是硬编码在脚本里。可复用与可分发工具集应该易于打包、分享并能被其他项目直接引用。健壮性具备良好的错误处理和用户反馈避免因工具使用不当导致项目数据损坏。基于这些目标我们的核心实现路径就是Godot EditorPlugin编辑器插件。这是Godot官方提供的、用于扩展编辑器功能的强大系统。通过它我们可以创建自定义的Dock停靠面板、在菜单栏添加项、为特定资源类型添加Inspector插件甚至修改编辑器的部分视图。2.1 工具集的常见分类与设计在动手之前我们先对常见的游戏开发工具做个分类这有助于我们规划工具集的结构资源处理工具这是最普遍的一类。例如精灵图/纹理处理批量裁剪、缩放、格式转换、生成九宫格信息。音频处理批量导入、标准化音量、生成播放列表。字体管理动态字体生成与预览。场景预处理自动为场景中的节点添加特定组件、检查场景规范。数据管理工具本地化/多语言工具提取场景和脚本中的文本生成CSV或JSON表格并支持导入回填。游戏配置表编辑器一个可视化的表格编辑器用于编辑平衡数值、关卡数据等并能导出为Godot可读的Resource或脚本。存档数据编辑器在编辑器中模拟查看和修改游戏存档结构。开发辅助工具性能分析助手一键生成当前场景的性能报告Draw Call、节点数、脚本内存等。快速原型工具一键生成带有基础移动、碰撞的玩家角色预制体。版本与构建工具自定义构建管道自动化处理构建前/后的资源打包、版本号递增等。注意工具开发本身也是开发要避免“过度工程化”。一个好的原则是“三次法则”当某个手动操作重复第三次时就应该考虑将其工具化。先从解决自己最痛的一个点开始。3. 实战构建一个资源批量重命名工具让我们从一个最实用、也最经典的工具开始资源批量重命名。这个工具将展示一个完整EditorPlugin的创建、UI设计、与编辑器交互的全过程。3.1 创建插件项目结构与入口首先我们不在游戏项目里直接写工具而是创建一个独立的插件项目。这样便于管理和分发。新建Godot项目命名为GodotGameTools。项目结构清晰是关键。创建插件目录和文件在项目根目录创建addons/godot_game_tools/文件夹。这是Godot插件的标准存放位置。在godot_game_tools/下创建plugin.cfg文件。这是插件的“身份证”。# plugin.cfg [plugin] nameGodot Game Tools descriptionA collection of handy tools for Godot game development. authorYour Name version1.0.0 scriptplugin.gd在godot_game_tools/下创建plugin.gd文件。这是插件的入口脚本。# plugin.gd tool # 必须添加表明这是一个编辑器工具脚本 extends EditorPlugin const MainDock preload(res://addons/godot_game_tools/ui/main_dock.tscn) var main_dock_instance: Control func _enter_tree(): # 插件激活时调用 main_dock_instance MainDock.instantiate() # 将我们的自定义Dock添加到编辑器界面 add_control_to_dock(EditorPlugin.DOCK_SLOT_LEFT_BR, main_dock_instance) print(Godot Game Tools 插件已加载。) func _exit_tree(): # 插件停用时调用 if main_dock_instance: remove_control_from_docks(main_dock_instance) main_dock_instance.queue_free() print(Godot Game Tools 插件已卸载。)激活插件在Godot编辑器顶部菜单栏进入项目 - 项目设置 - 插件你应该能看到“Godot Game Tools”。勾选“启用”复选框。如果一切正常你会在编辑器界面通常是左下角或右下角看到一个空白的Dock面板并且输出栏会打印加载信息。3.2 设计批量重命名工具的UI现在我们来为这个Dock添加内容。创建ui/main_dock.tscn场景。场景根节点创建一个VBoxContainer命名为MainDock。添加UI控件在VBoxContainer下添加一个Label文本设为“批量重命名工具”。添加一个HSeparator作为分隔线。添加一个GridContainer列数设为2用于排列参数输入。第一行Label“目标文件夹” LineEdit命名为target_folder_edit用于显示路径。第二行Label“查找文本” LineEdit命名为find_text_edit。第三行Label“替换文本” LineEdit命名为replace_text_edit。在GridContainer下添加一个Button文本设为“选择文件夹”命名为select_folder_btn。我们将用它来打开文件夹选择对话框。添加一个CheckBox文本设为“包含子目录”命名为recursive_checkbox。添加一个TextEdit命名为log_text将其设为只读用于显示操作日志。最后添加一个Button文本设为“执行重命名”命名为execute_btn。UI布局大致如下[批量重命名工具] ------------------- 目标文件夹[LineEdit] [选择文件夹] 查找文本 [LineEdit] 替换文本 [LineEdit] [ ] 包含子目录 [执行重命名] ------------------- [Log TextEdit]3.3 实现核心重命名逻辑创建脚本ui/main_dock.gd并附加到MainDock根节点。# main_dock.gd tool extends VBoxContainer onready var target_folder_edit: LineEdit $GridContainer/target_folder_edit onready var find_text_edit: LineEdit $GridContainer/find_text_edit onready var replace_text_edit: LineEdit $GridContainer/replace_text_edit onready var select_folder_btn: Button $select_folder_btn onready var recursive_checkbox: CheckBox $recursive_checkbox onready var log_text: TextEdit $log_text onready var execute_btn: Button $execute_btn func _ready(): select_folder_btn.pressed.connect(_on_select_folder_pressed) execute_btn.pressed.connect(_on_execute_pressed) _log_message(批量重命名工具就绪。) func _on_select_folder_pressed(): # 使用EditorFileDialog来选择文件夹 var dialog EditorFileDialog.new() dialog.file_mode EditorFileDialog.FILE_MODE_OPEN_DIR dialog.access EditorFileDialog.ACCESS_RESOURCES dialog.dir_selected.connect(_on_folder_selected) # 将对话框添加到编辑器界面 EditorInterface.get_base_control().add_child(dialog) dialog.popup_centered_ratio(0.7) func _on_folder_selected(dir_path: String): target_folder_edit.text dir_path _log_message(已选择文件夹: dir_path) func _on_execute_pressed(): var target_dir: String target_folder_edit.text.strip_edges() var find_str: String find_text_edit.text var replace_str: String replace_text_edit.text var recursive: bool recursive_checkbox.button_pressed if target_dir.is_empty(): _log_message(错误请先选择目标文件夹。, true) return if find_str.is_empty(): _log_message(错误查找文本不能为空。, true) return _log_message(开始批量重命名...) _log_message(目录: target_dir) _log_message(查找: \ find_str \ 替换为: \ replace_str \) var renamed_count _rename_files_in_directory(target_dir, find_str, replace_str, recursive) _log_message(操作完成。共重命名了 str(renamed_count) 个文件。) func _rename_files_in_directory(dir_path: String, find: String, replace: String, recursive: bool) - int: var dir DirAccess.open(dir_path) if not dir: _log_message(错误无法访问目录 - dir_path, true) return 0 var count 0 dir.list_dir_begin() # 开始遍历 while true: var file_name dir.get_next() if file_name : break if file_name . or file_name ..: continue var full_path dir_path.path_join(file_name) if dir.current_is_dir(): if recursive: # 递归处理子目录 count _rename_files_in_directory(full_path, find, replace, recursive) else: # 处理文件 if find in file_name: var new_file_name file_name.replace(find, replace) var new_full_path dir_path.path_join(new_file_name) var error dir.rename(full_path, new_full_path) if error OK: _log_message(重命名: file_name - new_file_name) count 1 else: _log_message(失败: file_name (错误码: str(error) ), true) dir.list_dir_end() return count func _log_message(msg: String, is_error: bool false): var prefix [ERROR] if is_error else [INFO] log_text.text prefix msg \n # 自动滚动到底部 log_text.scroll_vertical log_text.get_line_count()3.4 关键点解析与避坑指南tool关键字这是灵魂。任何需要在编辑器中运行的脚本包括插件主脚本、工具脚本、以及插件内的场景脚本都必须在顶部添加tool。没有它你的代码在编辑器中不会执行。使用EditorFileDialog在插件中我们不能用普通的FileDialog而必须使用EditorFileDialog。它是编辑器感知的能正确显示项目资源目录。注意获取EditorInterface.get_base_control()作为其父节点。路径处理res://是项目资源路径。我们的工具主要操作这个范围内的文件。使用DirAccess类进行文件遍历和重命名操作。list_dir_begin()、get_next()、list_dir_end()是标准遍历模式。重命名操作DirAccess.rename()是原地重命名。这是一个危险操作所以在工具中我们加入了详细的日志输出并且在执行前做了基本的参数校验。在实际更复杂的工具中应该考虑加入“预览”或“撤销”功能。线程与性能如果处理成千上万个文件上述同步操作会阻塞编辑器UI。对于重型工具需要考虑使用Thread或Worker在后台处理并通过call_deferred更新UI。实操心得在开发编辑器工具时养成频繁使用print()或像我们这样写日志面板的习惯。因为工具脚本的调试不如游戏运行时直观清晰的日志是排查问题的生命线。另外工具的第一个版本可以只实现核心功能快速验证可行性。像“撤销”这种高级功能可以在后续迭代中加入。4. 进阶打造一个简易的本地化文本提取工具资源重命名工具展示了基础的文件操作。现在我们挑战一个更复杂、也更实用的工具从场景和脚本中提取所有需要本地化的字符串并导出为CSV文件。这个工具涉及对Godot项目资源的深度解析。4.1 设计思路与数据结构我们需要扫描两种主要资源场景文件.tscn提取所有Label、Button、RichTextLabel等控件的text属性。GDScript文件.gd提取所有被标记的字符串例如通过特定的函数调用如tr(...)或自定义标记。输出是一个CSV文件结构如下key,source_text,zh_CN,en_US,ja_JP ui.main.title,主菜单,Main Menu,メインメニュー dialog.intro.001,你好冒险者,Hello, Adventurer!,こんにちは、冒険者さん4.2 实现场景文件解析器创建脚本utils/scene_parser.gd。# scene_parser.gd tool extends RefCounted class_name SceneParser # 定义需要提取text属性的节点类型和属性名 const TEXT_NODES : { Label: text, Button: text, CheckBox: text, CheckButton: text, LinkButton: text, MenuButton: text, # 注意MenuButton的text属性可能在其PopupMenu中 OptionButton: text, # 需要特殊处理其项是数组 RichTextLabel: text, LineEdit: [text, placeholder_text], TextEdit: text, Window: title, } func parse_scene_file(file_path: String) - Dictionary: var result : {strings: [], errors: []} if not FileAccess.file_exists(file_path): result[errors].append(文件不存在: file_path) return result var file FileAccess.open(file_path, FileAccess.READ) if not file: result[errors].append(无法打开文件: file_path) return result var content file.get_as_text() file.close() # 简单解析.tscn文件这是一个文本格式的资源文件 # 我们寻找形如 text 某段文字 的键值对 # 注意这是一个简化解析器复杂的嵌套结构需要更健壮的解析器如正则表达式或官方解析API var lines content.split(\n) var inside_node false var current_node_type var string_matches [] for line in lines: line line.strip_edges() if line.begins_with([): inside_node line.begins_with([node ) if inside_node: # 提取节点类型例如 type Label var type_match line.match(type ([^])) if type_match: current_node_type type_match[1] else: current_node_type continue if inside_node and not current_node_type.is_empty(): # 检查这个节点类型是否在我们关注的列表中 if TEXT_NODES.has(current_node_type): var prop_name TEXT_NODES[current_node_type] var prop_names [] if prop_name is String: prop_names.append(prop_name) else: # 是数组 prop_names prop_name for p_name in prop_names: # 匹配 pattern: prop_name value var pattern p_name ([^]) var regex RegEx.new() regex.compile(pattern) var match_result regex.search(line) if match_result: var extracted_text match_result.get_string(1) if extracted_text and not extracted_text.is_empty(): # 生成一个简单的key例如scene_file_path/path/to/node::property # 这里简化处理只存储文本和来源 string_matches.append({ text: extracted_text, source: file_path ( current_node_type . p_name ), type: scene }) result[strings] string_matches return result4.3 实现脚本文件解析器创建脚本utils/script_parser.gd。这里我们重点查找tr()函数调用这是Godot推荐的国际化函数。# script_parser.gd tool extends RefCounted class_name ScriptParser func parse_script_file(file_path: String) - Dictionary: var result : {strings: [], errors: []} if not FileAccess.file_exists(file_path): result[errors].append(文件不存在: file_path) return result var file FileAccess.open(file_path, FileAccess.READ) if not file: result[errors].append(无法打开文件: file_path) return result var content file.get_as_text() file.close() # 使用正则表达式查找 tr(...) 调用 var regex RegEx.new() # 这个正则匹配 tr(...)并考虑了可能的转义引号和嵌套简单情况 regex.compile(tr\\(\\s*([^\\\\]*(?:\\\\.[^\\\\]*)*)\\s*\\)) var matches regex.search_all(content) for match in matches: var extracted_text match.get_string(1) # 处理字符串中的转义字符例如 \\n, \\ extracted_text extracted_text.replace(\\n, \n).replace(\\, ).replace(\\\\, \\) if extracted_text and not extracted_text.is_empty(): result[strings].append({ text: extracted_text, source: file_path (tr()), type: script }) return result4.4 集成到主插件并创建UI现在我们需要在主Dock中新增一个标签页或面板来承载这个本地化工具。修改UI在main_dock.tscn中添加一个TabContainer。第一个标签放我们之前的重命名工具第二个标签新建一个VBoxContainer用于本地化工具。本地化工具UI在第二个标签页内添加以下控件Button“扫描项目”用于开始扫描。Tree用于显示扫描出的字符串列表显示Key、源文本、来源文件。LineEdit“Key前缀”让用户自定义生成Key的前缀如ui.。Button“导出为CSV”。TextEdit用于显示扫描日志。实现扫描逻辑在main_dock.gd中为“扫描项目”按钮连接信号。其回调函数需要使用DirAccess递归遍历res://目录。对每个.tscn文件调用SceneParser.parse_scene_file。对每个.gd文件调用ScriptParser.parse_script_file。将收集到的所有字符串去重、合并并显示在Tree控件中。实现导出逻辑用户可以在Tree中编辑生成的Key或使用自动生成的Key如source_text.md5的一部分然后点击“导出为CSV”将Tree中的数据按照CSV格式写入文件。注意事项这个文本提取器是“启发式”的并不完美。Godot的场景文件格式.tscn本质上是文本但解析它需要考虑嵌套、资源引用、多行字符串等多种复杂情况。上述的简单字符串匹配可能会漏掉一些情况或产生误匹配。对于生产环境有两种更可靠的方法一是使用Godot引擎内部的ResourceLoader加载场景为PackedScene然后实例化并遍历节点树来读取属性但这在编辑器插件中可能带来性能开销和副作用二是寻找或编写更完善的.tscn文件解析库。我们的版本作为教程和起点已经能处理80%的常见情况。5. 工具集的打包、分享与进阶方向5.1 插件打包与分发当你开发了一套好用的工具集自然会想分享给团队成员或其他开发者。清理与测试确保插件代码整洁移除调试用的print语句或者将其改为可开关的调试日志。创建发布包最简单的方式就是直接将addons/godot_game_tools/文件夹压缩成ZIP包。接收者只需解压到其项目的addons/目录下然后在插件设置中启用即可。使用Git子模块或Godot资产库对于团队协作可以将工具集作为一个独立的Git仓库然后通过Git子模块引入到各个游戏项目中。更正式的做法是将其发布到Godot的官方或第三方资产库如 godotengine/asset-library 但这需要遵循更严格的规范和提供元数据。5.2 进阶工具开发方向掌握了基础插件开发后你可以探索更强大的功能自定义Inspector插件为特定的Resource或Node创建属性编辑器。例如为一个“敌人配置”资源创建一个可视化的属性表格而不是在Inspector里填一堆纯文本。编辑器视图扩展比如在2D编辑器视图中绘制自定义的辅助线、网格或碰撞体预览。与外部工具集成通过OS.execute()调用命令行工具比如调用Aseprite命令行进行精灵图处理或者调用ImageMagick进行批量图片转换。创建独立的工具窗口不仅仅是Dock你可以创建浮动、可停靠的独立窗口用于更复杂的管理界面比如一个完整的对话树编辑器。5.3 常见问题与排查实录Q1我的插件按钮点击后没反应也没有错误日志。A1首先检查脚本顶部是否有tool。其次检查信号连接是否正确。在_ready()函数里用print()确认函数被调用。最后检查代码逻辑特别是文件路径和权限问题。Q2插件在编辑器中运行正常但游戏导出后工具功能消失了。A2这是正常现象。tool脚本和EditorPlugin只在编辑器中运行不会包含在导出的游戏运行时中。这是设计使然。Q3我修改了插件代码但编辑器里看不到变化。A3Godot对编辑器插件的热重载支持有限。最可靠的方法是在项目设置的插件页面先禁用插件再重新启用。这会触发_exit_tree()和_enter_tree()重新加载插件。Q4工具操作文件时Godot编辑器报“资源正在被使用”错误。A4如果你尝试重命名或删除一个当前在编辑器中打开或被引用的资源Godot会阻止你。一种策略是在操作前使用EditorInterface.get_resource_filesystem()获取文件系统实例并尝试让编辑器释放该资源或者直接提示用户关闭相关场景/资源。Q5如何让工具支持“撤销/重做”功能A5Godot编辑器提供了EditorUndoRedoManager。在进行任何会修改项目数据的操作前你需要创建一个撤销操作组。例如在重命名文件前调用undo_redo.create_action(Batch Rename)然后为每个文件重命名调用undo_redo.add_do_method(obj, rename, old, new)和undo_redo.add_undo_method(obj, rename, new, old)最后undo_redo.commit_action()。这需要更精细的设计。开发Godot编辑器工具是一个深入理解引擎架构的过程。从解决自己的一个小麻烦开始逐步构建起一个强大的个性化工具集这种成就感不亚于完成一个游戏关卡。记住最好的工具永远是那个为你自己的工作流量身定做的工具。
