文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载在 Godot 4 编辑器中当你在文件系统停靠面板FileSystemDock中悬停一个资源文件时默认只会弹出一个包含文件名、类型和大小信息的简单提示。而EditorResourceTooltipPlugin正是官方提供的一套扩展机制允许开发者针对自己处理的资源类型生成增强版悬浮提示例如Texture2D的提示会显示更大的预览图和纹理尺寸。本篇指南以 classes/class_editorresourcetooltipplugin.rst 为核心结合 FileSystemDock、EditorResourcePreviewGenerator、EditorResourcePreview 等相关类的文档完整讲解该插件的注册流程、三个核心方法的实现细节、异步缩略图加载方式以及性能注意事项读完即可在编辑器插件中落地一个自定义资源提示。一、EditorResourceTooltipPlugin 是什么EditorResourceTooltipPlugin继承自RefCounted进而继承自Object是一段高级工具提示插件A plugin that advanced tooltip for its handled resource type。它在编辑器中的定位非常明确由 FileSystemDock 使用用来为特定资源生成定制化悬浮提示。官方文档给出的典型例子是Texture2D资源的提示会展示一个更大的预览图以及纹理的尺寸信息。从源码结构看该插件本身并不直接挂接到编辑器 UI 上而是遵循一套注册—回调的工作流插件实例首先必须通过 FileSystemDock.add_resource_tooltip_plugin() 注册当用户把鼠标悬停在文件系统停靠面板中、由该插件负责的资源文件上时编辑器会调用_make_tooltip_for_path()来创建提示内容该机制与 Control._make_custom_tooltip() 的工作方式类似——返回一个Control节点作为提示界面。这套机制的典型使用场景包括为自定义资源类型显示作者、版本、关键参数等元信息为音频资源显示采样时长、声道数为图片/纹理资源显示真实预览图和分辨率为三维模型显示缩略图与三角形数量等。二、核心 API 一览EditorResourceTooltipPlugin共暴露 3 个方法其中两个是需要开发者重写的虚方法virtual一个是工具方法方法签名类型说明_handles(type: String) - boolvirtual, const返回true表示本插件会处理给定的Resource类型_make_tooltip_for_path(path: String, metadata: Dictionary, base: Control) - Controlvirtual, const创建并返回用户悬停指定path资源时显示的悬浮提示request_thumbnail(path: String, control: TextureRect) - voidconst为给定的TextureRect请求缩略图缩略图由EditorResourcePreview异步生成生成完毕后自动设置到该控件上两个虚方法都带有const标记|const|表示该方法没有副作用不修改实例成员变量且都通常需要被用户重写才有效果|virtual|的语义。下面逐个深入解析。三、第一步注册插件FileSystemDock.add_resource_tooltip_plugin所有资源提示插件在使用前必须先注册。注册入口是 FileSystemDock.add_resource_tooltip_plugin(plugin)它接收一个EditorResourceTooltipPlugin实例并完成注册与之对应FileSystemDock.remove_resource_tooltip_plugin(plugin) 用于注销插件如果该插件之前没有被添加过注销会失败Fails if the plugin wasnt previously added。由于FileSystemDock是编辑器的内置停靠面板获取它的标准途径是通过 EditorInterface.get_file_system_dock()var fs_dock: FileSystemDock EditorInterface.get_file_system_dock() fs_dock.add_resource_tooltip_plugin(my_plugin)在实际项目中注册动作通常放在编辑器插件的生命周期回调里完成。一个最小可用的plugin.cfg加主脚本如下插件目录约定参考 tutorials/plugins/editor/making_plugins.rst# res://addons/my_resource_tooltip/plugin.cfg [plugin] nameMy Resource Tooltip description为自定义资源在文件系统面板中显示增强悬浮提示。 authorYour Name version1.0 scriptplugin.gd# res://addons/my_resource_tooltip/plugin.gd tool extends EditorPlugin var tooltip_plugin: EditorResourceTooltipPlugin func _enter_tree() - void: tooltip_plugin MyTooltipPlugin.new() EditorInterface.get_file_system_dock().add_resource_tooltip_plugin(tooltip_plugin) func _exit_tree() - void: EditorInterface.get_file_system_dock().remove_resource_tooltip_plugin(tooltip_plugin) tooltip_plugin null注意EditorPlugin的_enter_tree()/_exit_tree()是插件的进入与退出回调参见 classes/class_editorplugin.rst务必在_exit_tree()中注销插件并释放引用避免编辑器热重载时重复注册。四、第二步实现_handles()声明处理的资源类型_handles(type: String) - bool是第一个需要重写的虚方法Returntrueif the plugin is going to handle the givenResourcetype.它接收一个资源类型名字符串如Texture2D、AudioStreamWAV返回true表示该插件愿意接管此类资源的悬浮提示。extends EditorResourceTooltipPlugin func _handles(type: String) - bool: return type Texture2D or type ImageTexture由于该方法在每个被悬停的资源上都会调用实现时应保持轻量、快速不要在这里做 IO 或加载操作。五、第三步实现_make_tooltip_for_path()构造提示界面这是插件最核心的方法签名与职责如下_make_tooltip_for_path(path: String, metadata: Dictionary, base: Control) - Control当用户在文件系统停靠面板中悬停某个被本插件处理的path资源时该方法被调用来创建并返回要显示的悬浮提示。三个参数的含义分别是path被悬停资源的文件路径字符串metadata由预览生成器提供的元数据字典——它来自 EditorResourcePreviewGenerator._generate() 写入的内容比如图片尺寸、音频采样长度等base默认的基础提示节点它本身是一个VBoxContainer包含文件名、类型和大小三个标签。如果已经有其他插件处理过同一文件类型base则是上一个插件的输出结果。为了获得最佳效果建议让base成为最终返回Control的一部分。官方提供了一个最简单的扩展示例class_editorresourcetooltipplugin.rstfunc _make_tooltip_for_path(path, metadata, base): var t_rect TextureRect.new() request_thumbnail(path, t_rect) base.add_child(t_rect) # The TextureRect will appear at the bottom of the tooltip. return base这段代码的含义新建一个TextureRect调用request_thumbnail(path, t_rect)请求异步缩略图把TextureRect追加到baseVBoxContainer底部返回base让默认信息与新增预览同时出现在提示中。在此基础上还可以结合metadata展示更丰富的信息。例如为纹理资源显示尺寸func _make_tooltip_for_path(path, metadata, base): # 在基础提示之上追加一行自定义信息 if metadata.has(size): var label Label.new() label.text 尺寸: %s x %s % [metadata[size].x, metadata[size].y] base.add_child(label) # 追加缩略图预览 var t_rect TextureRect.new() request_thumbnail(path, t_rect) base.add_child(t_rect) return base六、第四步用request_thumbnail()异步加载预览图request_thumbnail(path: String, control: TextureRect) - void是唯一一个非虚的公开方法Requests a thumbnail for the givenTextureRect. The thumbnail is createdasynchronouslybyEditorResourcePreviewand automatically set when available.也就是说你只需要把目标TextureRect传给它缩略图会由EditorResourcePreview在后台线程异步生成生成完成后自动设置到该控件上不需要再手动接收回调。这是官方刻意推荐的做法因为悬浮提示创建阶段不适合做同步加载。相关类的文档可以交叉印证EditorResourcePreview是一个用于生成资源/文件预览的节点它不应被直接实例化而是通过 EditorInterface.get_resource_previewer() 获取单例其内部还提供queue_resource_preview()、queue_edited_resource_preview()等方法以及preview_invalidated(path)信号参见 classes/class_editorresourcepreview.rst。七、metadata 从哪来配合 EditorResourcePreviewGenerator_make_tooltip_for_path()的第二个参数metadata并不需要你自行填充——它由预览生成器提供。文档明确指出Themetadatadictionary is provided by preview generator (seeEditorResourcePreviewGenerator._generate()).在 EditorResourcePreviewGenerator._generate() 中开发者可以在生成预览时把文件特有的信息写入metadata字典例如图片尺寸、采样长度等这些信息随后会原样出现在提示插件的metadata参数里。_generate_from_path()也有同样的约定[classes/class_editorresourcepreviewgenerator.rst#L87-L99]。一个典型的配合流程是实现EditorResourcePreviewGenerator._handles(type)声明负责的资源类型在_generate()或_generate_from_path()中写入metadata注意这两个方法总是从后台线程被调用不能操作场景树在EditorResourceTooltipPlugin._make_tooltip_for_path()中读取metadata展示给用户。例如在预览生成器侧写入音频时长# 预览生成器EditorResourcePreviewGenerator 子类片段 func _generate_from_path(path, size, metadata): var stream: AudioStream load(path) metadata[duration] stream.get_length() # 把时长写入 metadata # ... 生成并返回预览纹理然后在提示插件侧读取func _make_tooltip_for_path(path, metadata, base): if metadata.has(duration): var label Label.new() label.text 时长: %.2f 秒 % metadata[duration] base.add_child(label) return base八、性能注意事项与最佳实践官方文档在_make_tooltip_for_path()的描述中给出了两条重要的实践准则1. 不要在提示创建时同步加载资源Its unadvised to useResourceLoader.load(), especially with heavy resources like models or textures, because it will make the editor unresponsive when creating the tooltip.用户悬停资源的瞬间就创建提示如果此刻同步加载模型或纹理这类重型资源会让编辑器卡顿无响应。如需在提示中展示预览请改用request_thumbnail()走异步路径。2. 丢弃 base 时必须手动释放If you decide to discard thebase, make sure to callNode.queue_free(), because its not freed automatically.base节点不会自动释放。如果你返回了一个全新构建的 Control而没有把base作为其子节点包含进去请务必手动调用base.queue_free()避免内存泄漏func _make_tooltip_for_path(path, metadata, base): # 完全自定义的提示不用默认 base var panel VBoxContainer.new() # ... 构建自定义内容 ... base.queue_free() # 手动释放默认提示 return panel3. 与 Control._make_custom_tooltip() 的差异两者机制相似但有两点区别值得注意参见 Control._make_custom_tooltip() 的文档_make_custom_tooltip()返回的节点同样会在提示消失时被释放因此每次都要返回新的实例不能复用场景树中的既有节点自定义提示节点会被添加为PopupPanel的子节点且提示会收缩到最小尺寸——如果内容较多记得为根节点设置custom_minimum_size并保证返回节点的visible为true否则视口无法可靠计算最小尺寸。这些约束对EditorResourceTooltipPlugin同样适用因为两者本质上是同一套提示渲染管线。九、C# 实现方式Godot 4 的 C# 侧同样支持该插件。以官方在Control._make_custom_tooltip()中展示的 C# 写法为参照classes/class_control.rst#L2869-L2876EditorResourceTooltipPlugin的 C# 版本如下using Godot; [Tool] public partial class MyTooltipPlugin : EditorResourceTooltipPlugin { public override bool _Handles(string type) { return type Texture2D; } public override Control _MakeTooltipForPath(string path, Godot.Collections.Dictionary metadata, Control baseControl) { var preview new TextureRect(); RequestThumbnail(path, preview); baseControl.AddChild(preview); return baseControl; } }注册逻辑与 GDScript 一致在编辑器插件脚本的_EnterTree()/_ExitTree()中调用EditorInterface.Singleton.GetFileSystemDock().AddResourceTooltipPlugin(...)与RemoveResourceTooltipPlugin(...)。十、完整示例为自定义资源实现带预览的悬浮提示下面把前面所有环节串起来给出一个完整的、可运行的编辑器插件示例为自定义资源类型MyDataResource显示缩略图与元信息提示。1. 资源类型定义# res://my_data_resource.gd class_name MyDataResource extends Resource export var display_name: String export var note: String 2. 预览生成器可选负责向 metadata 写信息# res://addons/my_resource_tooltip/my_preview_generator.gd tool extends EditorResourcePreviewGenerator func _handles(type: String) - bool: return type MyDataResource func _generate(resource, size, metadata): if resource is MyDataResource: metadata[display_name] resource.display_name metadata[note] resource.note # 返回 null 表示让其他生成器继续处理 return null3. 悬浮提示插件# res://addons/my_resource_tooltip/my_tooltip_plugin.gd tool extends EditorResourceTooltipPlugin func _handles(type: String) - bool: return type MyDataResource func _make_tooltip_for_path(path, metadata, base): if metadata.has(display_name): var name_label Label.new() name_label.text 名称: %s % metadata[display_name] base.add_child(name_label) if metadata.has(note): var note_label Label.new() note_label.text 备注: %s % metadata[note] base.add_child(note_label) var preview TextureRect.new() request_thumbnail(path, preview) base.add_child(preview) return base4. 编辑器插件入口# res://addons/my_resource_tooltip/plugin.gd tool extends EditorPlugin var tooltip_plugin: EditorResourceTooltipPlugin var preview_generator: EditorResourcePreviewGenerator func _enter_tree() - void: tooltip_plugin preload(my_tooltip_plugin.gd).new() EditorInterface.get_file_system_dock().add_resource_tooltip_plugin(tooltip_plugin) preview_generator preload(my_preview_generator.gd).new() EditorInterface.get_resource_previewer().add_preview_generator(preview_generator) func _exit_tree() - void: EditorInterface.get_file_system_dock().remove_resource_tooltip_plugin(tooltip_plugin) EditorInterface.get_resource_previewer().remove_preview_generator(preview_generator) tooltip_plugin null preview_generator null启用该插件后在文件系统停靠面板中悬停任意MyDataResource类型的.tres文件即可看到由默认信息、元数据标签和异步加载的缩略图共同组成的增强提示。十一、相关资源速查本文核心类EditorResourceTooltipPlugin注册/注销入口FileSystemDock.add_resource_tooltip_plugin 与 remove_resource_tooltip_plugin预览元数据来源EditorResourcePreviewGenerator异步预览服务EditorResourcePreview通过 EditorInterface.get_resource_previewer() 获取编辑器停靠面板获取方式EditorInterface.get_file_system_dock()类似机制参考Control._make_custom_tooltip()编辑器插件入门tutorials/plugins/editor/making_plugins.rst以上所有类参考文档均位于本仓库classes/目录下可直接按路径查阅原始.rst源文件以获取最新的方法签名与说明。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Handsontable Comments 插件源码深度解析单元格批注与悬浮编辑器的完整实现指南Handsontable Comments 插件源码深度解析单元格批注与悬浮编辑器的完整实现指南 本文以 Handsontable 仓库中 handsonta前端UI组件ComfyUI-WanVideoWrapper基于稀疏注意力与混合精度计算的视频生成性能突破ComfyUI WanVideoWrapper基于稀疏注意力与混合精度计算的视频生成性能突破 技术痛点与解决方案定位 在AI视频生成领域开发者长期面临计算人工智能大模型媒体生成3步打造Godot编辑器扩展GDNative插件开发指南3步打造Godot编辑器扩展GDNative插件开发指南 你还在为Godot编辑器功能不足而烦恼本文将通过3个核心步骤带你从零开始构建强大的GDNativ游戏开发图形学跨平台上一篇APITable Widget 上传预签名 URL API 实战指南从 SDK 调用到对象存储实现原理下一篇DeepSeek Harness Web 能力缝Capability Seam架构解析用稳定的 web_search/web_fetch 工具契约驾驭多供应商后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考