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