文檔教程游戲開發(fā)【免費下載鏈接】godot-docsGodot Engine official documentation項目地址https://gitcode.com/GitHub_Trending/go/godot-docs點擊查看免費下載在 Godot 4 編輯器中當(dāng)你在文件系統(tǒng)停靠面板FileSystemDock中懸停一個資源文件時默認只會彈出一個包含文件名、類型和大小信息的簡單提示。而EditorResourceTooltipPlugin正是官方提供的一套擴展機制允許開發(fā)者針對自己處理的資源類型生成增強版懸浮提示例如Texture2D的提示會顯示更大的預(yù)覽圖和紋理尺寸。本篇指南以 classes/class_editorresourcetooltipplugin.rst 為核心結(jié)合 FileSystemDock、EditorResourcePreviewGenerator、EditorResourcePreview 等相關(guān)類的文檔完整講解該插件的注冊流程、三個核心方法的實現(xiàn)細節(jié)、異步縮略圖加載方式以及性能注意事項讀完即可在編輯器插件中落地一個自定義資源提示。一、EditorResourceTooltipPlugin 是什么EditorResourceTooltipPlugin繼承自RefCounted進而繼承自O(shè)bject是一段高級工具提示插件A plugin that advanced tooltip for its handled resource type。它在編輯器中的定位非常明確由 FileSystemDock 使用用來為特定資源生成定制化懸浮提示。官方文檔給出的典型例子是Texture2D資源的提示會展示一個更大的預(yù)覽圖以及紋理的尺寸信息。從源碼結(jié)構(gòu)看該插件本身并不直接掛接到編輯器 UI 上而是遵循一套注冊—回調(diào)的工作流插件實例首先必須通過 FileSystemDock.add_resource_tooltip_plugin() 注冊當(dāng)用戶把鼠標(biāo)懸停在文件系統(tǒng)?？棵姘逯小⒂稍摬寮撠?zé)的資源文件上時編輯器會調(diào)用_make_tooltip_for_path()來創(chuàng)建提示內(nèi)容該機制與 Control._make_custom_tooltip() 的工作方式類似——返回一個Control節(jié)點作為提示界面。這套機制的典型使用場景包括為自定義資源類型顯示作者、版本、關(guān)鍵參數(shù)等元信息為音頻資源顯示采樣時長、聲道數(shù)為圖片/紋理資源顯示真實預(yù)覽圖和分辨率為三維模型顯示縮略圖與三角形數(shù)量等。二、核心 API 一覽EditorResourceTooltipPlugin共暴露 3 個方法其中兩個是需要開發(fā)者重寫的虛方法virtual一個是工具方法方法簽名類型說明_handles(type: String) - boolvirtual, const返回true表示本插件會處理給定的Resource類型_make_tooltip_for_path(path: String, metadata: Dictionary, base: Control) - Controlvirtual, const創(chuàng)建并返回用戶懸停指定path資源時顯示的懸浮提示request_thumbnail(path: String, control: TextureRect) - voidconst為給定的TextureRect請求縮略圖縮略圖由EditorResourcePreview異步生成生成完畢后自動設(shè)置到該控件上兩個虛方法都帶有const標(biāo)記|const|表示該方法沒有副作用不修改實例成員變量且都通常需要被用戶重寫才有效果|virtual|的語義。下面逐個深入解析。三、第一步注冊插件FileSystemDock.add_resource_tooltip_plugin所有資源提示插件在使用前必須先注冊。注冊入口是 FileSystemDock.add_resource_tooltip_plugin(plugin)它接收一個EditorResourceTooltipPlugin實例并完成注冊與之對應(yīng)FileSystemDock.remove_resource_tooltip_plugin(plugin) 用于注銷插件如果該插件之前沒有被添加過注銷會失敗Fails if the plugin wasnt previously added。由于FileSystemDock是編輯器的內(nèi)置?？棵姘瀚@取它的標(biāo)準(zhǔn)途徑是通過 EditorInterface.get_file_system_dock()var fs_dock: FileSystemDock EditorInterface.get_file_system_dock() fs_dock.add_resource_tooltip_plugin(my_plugin)在實際項目中注冊動作通常放在編輯器插件的生命周期回調(diào)里完成。一個最小可用的plugin.cfg加主腳本如下插件目錄約定參考 tutorials/plugins/editor/making_plugins.rst# res://addons/my_resource_tooltip/plugin.cfg [plugin] nameMy Resource Tooltip description為自定義資源在文件系統(tǒng)面板中顯示增強懸浮提示。 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()是插件的進入與退出回調(diào)參見 classes/class_editorplugin.rst務(wù)必在_exit_tree()中注銷插件并釋放引用避免編輯器熱重載時重復(fù)注冊。四、第二步實現(xiàn)_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由于該方法在每個被懸停的資源上都會調(diào)用實現(xiàn)時應(yīng)保持輕量、快速不要在這里做 IO 或加載操作。五、第三步實現(xiàn)_make_tooltip_for_path()構(gòu)造提示界面這是插件最核心的方法簽名與職責(zé)如下_make_tooltip_for_path(path: String, metadata: Dictionary, base: Control) - Control當(dāng)用戶在文件系統(tǒng)停靠面板中懸停某個被本插件處理的path資源時該方法被調(diào)用來創(chuàng)建并返回要顯示的懸浮提示。三個參數(shù)的含義分別是path被懸停資源的文件路徑字符串metadata由預(yù)覽生成器提供的元數(shù)據(jù)字典——它來自 EditorResourcePreviewGenerator._generate() 寫入的內(nèi)容比如圖片尺寸、音頻采樣長度等base默認的基礎(chǔ)提示節(jié)點它本身是一個VBoxContainer包含文件名、類型和大小三個標(biāo)簽。如果已經(jīng)有其他插件處理過同一文件類型base則是上一個插件的輸出結(jié)果。為了獲得最佳效果建議讓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調(diào)用request_thumbnail(path, t_rect)請求異步縮略圖把TextureRect追加到baseVBoxContainer底部返回base讓默認信息與新增預(yù)覽同時出現(xiàn)在提示中。在此基礎(chǔ)上還可以結(jié)合metadata展示更豐富的信息。例如為紋理資源顯示尺寸func _make_tooltip_for_path(path, metadata, base): # 在基礎(chǔ)提示之上追加一行自定義信息 if metadata.has(size): var label Label.new() label.text 尺寸: %s x %s % [metadata[size].x, metadata[size].y] base.add_child(label) # 追加縮略圖預(yù)覽 var t_rect TextureRect.new() request_thumbnail(path, t_rect) base.add_child(t_rect) return base六、第四步用request_thumbnail()異步加載預(yù)覽圖request_thumbnail(path: String, control: TextureRect) - void是唯一一個非虛的公開方法Requests a thumbnail for the givenTextureRect. The thumbnail is createdasynchronouslybyEditorResourcePreviewand automatically set when available.也就是說你只需要把目標(biāo)TextureRect傳給它縮略圖會由EditorResourcePreview在后臺線程異步生成生成完成后自動設(shè)置到該控件上不需要再手動接收回調(diào)。這是官方刻意推薦的做法因為懸浮提示創(chuàng)建階段不適合做同步加載。相關(guān)類的文檔可以交叉印證EditorResourcePreview是一個用于生成資源/文件預(yù)覽的節(jié)點它不應(yīng)被直接實例化而是通過 EditorInterface.get_resource_previewer() 獲取單例其內(nèi)部還提供queue_resource_preview()、queue_edited_resource_preview()等方法以及preview_invalidated(path)信號參見 classes/class_editorresourcepreview.rst。七、metadata 從哪來配合 EditorResourcePreviewGenerator_make_tooltip_for_path()的第二個參數(shù)metadata并不需要你自行填充——它由預(yù)覽生成器提供。文檔明確指出Themetadatadictionary is provided by preview generator (seeEditorResourcePreviewGenerator._generate()).在 EditorResourcePreviewGenerator._generate() 中開發(fā)者可以在生成預(yù)覽時把文件特有的信息寫入metadata字典例如圖片尺寸、采樣長度等這些信息隨后會原樣出現(xiàn)在提示插件的metadata參數(shù)里。_generate_from_path()也有同樣的約定[classes/class_editorresourcepreviewgenerator.rst#L87-L99]。一個典型的配合流程是實現(xiàn)EditorResourcePreviewGenerator._handles(type)聲明負責(zé)的資源類型在_generate()或_generate_from_path()中寫入metadata注意這兩個方法總是從后臺線程被調(diào)用不能操作場景樹在EditorResourceTooltipPlugin._make_tooltip_for_path()中讀取metadata展示給用戶。例如在預(yù)覽生成器側(cè)寫入音頻時長# 預(yù)覽生成器EditorResourcePreviewGenerator 子類片段 func _generate_from_path(path, size, metadata): var stream: AudioStream load(path) metadata[duration] stream.get_length() # 把時長寫入 metadata # ... 生成并返回預(yù)覽紋理然后在提示插件側(cè)讀取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()的描述中給出了兩條重要的實踐準(zhǔn)則1. 不要在提示創(chuàng)建時同步加載資源Its unadvised to useResourceLoader.load(), especially with heavy resources like models or textures, because it will make the editor unresponsive when creating the tooltip.用戶懸停資源的瞬間就創(chuàng)建提示如果此刻同步加載模型或紋理這類重型資源會讓編輯器卡頓無響應(yīng)。如需在提示中展示預(yù)覽請改用request_thumbnail()走異步路徑。2. 丟棄 base 時必須手動釋放If you decide to discard thebase, make sure to callNode.queue_free(), because its not freed automatically.base節(jié)點不會自動釋放。如果你返回了一個全新構(gòu)建的 Control而沒有把base作為其子節(jié)點包含進去請務(wù)必手動調(diào)用base.queue_free()避免內(nèi)存泄漏func _make_tooltip_for_path(path, metadata, base): # 完全自定義的提示不用默認 base var panel VBoxContainer.new() # ... 構(gòu)建自定義內(nèi)容 ... base.queue_free() # 手動釋放默認提示 return panel3. 與 Control._make_custom_tooltip() 的差異兩者機制相似但有兩點區(qū)別值得注意參見 Control._make_custom_tooltip() 的文檔_make_custom_tooltip()返回的節(jié)點同樣會在提示消失時被釋放因此每次都要返回新的實例不能復(fù)用場景樹中的既有節(jié)點自定義提示節(jié)點會被添加為PopupPanel的子節(jié)點且提示會收縮到最小尺寸——如果內(nèi)容較多記得為根節(jié)點設(shè)置custom_minimum_size并保證返回節(jié)點的visible為true否則視口無法可靠計算最小尺寸。這些約束對EditorResourceTooltipPlugin同樣適用因為兩者本質(zhì)上是同一套提示渲染管線。九、C# 實現(xiàn)方式Godot 4 的 C# 側(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()中調(diào)用EditorInterface.Singleton.GetFileSystemDock().AddResourceTooltipPlugin(...)與RemoveResourceTooltipPlugin(...)。十、完整示例為自定義資源實現(xiàn)帶預(yù)覽的懸浮提示下面把前面所有環(huán)節(jié)串起來給出一個完整的、可運行的編輯器插件示例為自定義資源類型MyDataResource顯示縮略圖與元信息提示。1. 資源類型定義# res://my_data_resource.gd class_name MyDataResource extends Resource export var display_name: String export var note: String 2. 預(yù)覽生成器可選負責(zé)向 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 表示讓其他生成器繼續(xù)處理 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啟用該插件后在文件系統(tǒng)停靠面板中懸停任意MyDataResource類型的.tres文件即可看到由默認信息、元數(shù)據(jù)標(biāo)簽和異步加載的縮略圖共同組成的增強提示。十一、相關(guān)資源速查本文核心類EditorResourceTooltipPlugin注冊/注銷入口FileSystemDock.add_resource_tooltip_plugin 與 remove_resource_tooltip_plugin預(yù)覽元數(shù)據(jù)來源EditorResourcePreviewGenerator異步預(yù)覽服務(wù)EditorResourcePreview通過 EditorInterface.get_resource_previewer() 獲取編輯器停靠面板獲取方式EditorInterface.get_file_system_dock()類似機制參考Control._make_custom_tooltip()編輯器插件入門tutorials/plugins/editor/making_plugins.rst以上所有類參考文檔均位于本倉庫classes/目錄下可直接按路徑查閱原始.rst源文件以獲取最新的方法簽名與說明。贊分享文檔教程游戲開發(fā)【免費下載鏈接】godot-docsGodot Engine official documentation項目地址https://gitcode.com/GitHub_Trending/go/godot-docs點擊查看免費下載相關(guān)推薦Handsontable Comments 插件源碼深度解析單元格批注與懸浮編輯器的完整實現(xiàn)指南Handsontable Comments 插件源碼深度解析單元格批注與懸浮編輯器的完整實現(xiàn)指南 本文以 Handsontable 倉庫中 handsonta前端UI組件ComfyUI-WanVideoWrapper基于稀疏注意力與混合精度計算的視頻生成性能突破ComfyUI WanVideoWrapper基于稀疏注意力與混合精度計算的視頻生成性能突破 技術(shù)痛點與解決方案定位 在AI視頻生成領(lǐng)域開發(fā)者長期面臨計算人工智能大模型媒體生成3步打造Godot編輯器擴展GDNative插件開發(fā)指南3步打造Godot編輯器擴展GDNative插件開發(fā)指南 你還在為Godot編輯器功能不足而煩惱本文將通過3個核心步驟帶你從零開始構(gòu)建強大的GDNativ游戲開發(fā)圖形學(xué)跨平臺上一篇APITable Widget 上傳預(yù)簽名 URL API 實戰(zhàn)指南從 SDK 調(diào)用到對象存儲實現(xiàn)原理下一篇DeepSeek Harness Web 能力縫Capability Seam架構(gòu)解析用穩(wěn)定的 web_search/web_fetch 工具契約駕馭多供應(yīng)商后端創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考