Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Godot 專案中的檔路徑

本頁面會講解 Godot 專案中檔路徑的工作原理。你會學到如何在專案中使用 res://user:// 標記來存取路徑,以及 Godot 會在你的以及使用者系統上的哪些位置儲存專案和編輯器檔。

路徑分隔符號

為了讓支援跨平臺更方便,Godot 使用 UNIX 風格的路徑分隔符號**(正斜杠 ``/``)。在所有平臺上都可以使用,**包括 Windows

在 Godot 裡寫的不是類似 ''C:ProjectsGame'' 的路徑,而應該寫 ''C:/Projects/Game''。

有些路徑相關的方法也支援 Windows 風格的路徑分隔符(反斜杠'''''),不過需要寫兩個(''''),因為 '''' 一般是用來進行字元轉義的,有特殊含義。

這樣就能夠處理其他 Windows 程式所返回的路徑了。我們仍然建議在您自己的程式碼裡只使用正斜杠,這樣才能確保一切都能正常工作。

新增檔案至專案

只要資料夾中存在名叫 project.godot 的文字檔,即便是空檔,Godot 也會認為這個資料夾中包含了一個專案。包含這個檔的資料夾是你的專案的根資料夾。

相對於這個資料夾的任何檔,都可以通過以 res:// 開頭的路徑存取,這個前綴代表“資源”(resource)。例如,在程式碼中,你可以通過 res://character.png 來存取位於專案根資料夾的 character.png 圖片。

存取場景節點

要儲存持久化資料檔案,比如玩家的存檔、設定等,你會想要使用 user:// 作為路徑前綴,而不是 res://。這是因為遊戲運作時,專案的檔案系統很可能是唯讀的。

user:// 前綴指向的是使用者裝置上的其他目錄。與 res:// 不同,即便在匯出後的專案中,user:// 指向的這個目錄也會自動建立並且*保證*可寫。

user:// 資料夾的位置由“專案設定”中的配置決定:

  • 預設情況下,user:// 資料夾是在:ref:編輯器資料路徑 <doc_data_paths_editor_data_paths>`中建立的 ``app_userdata/[專案名稱]` 資料夾。使用這一預設值的目的是讓原型和測試專案能夠在 Godot 的資料檔案夾中達到自包含。

  • 如果“專案設定”中啟用了 application/config/use_custom_user_diruser:// 資料夾會與 Godot 編輯器的資料路徑*同級*,即程式資料的標準位置。

    • 預設情況下,資料夾名稱是從專案名稱推匯出來的,但可以使用 application/config/custom_user_dir_name 進行進一步的自訂。這個路徑可以包含路徑分隔符號,那麼比如你就可以把給定工作室的專案都群組到 工作室名稱/遊戲名稱 這樣的目錄結構之下。

在桌面平臺上,user:// 的實際目錄路徑為:

型別

位置

預設

Windows:%APPDATA%\Godot\script_templates\
macOS:$HOME/Library/Application Support/Godot/script_templates/
Linux: $HOME/.local/share/godot/templates/<版本>/

自定功能

Windows:%APPDATA%\Godot\script_templates\
macOS:$HOME/Library/Application Support/Godot/script_templates/
Linux: $HOME/.local/share/godot/templates/<版本>/

自定 AudioStream

Windows:%APPDATA%\Godot\script_templates\
macOS:$HOME/Library/Application Support/Godot/script_templates/
Linux: $HOME/.local/share/godot/templates/<版本>/

[專案名稱] 基於的是專案設定中定義的應用名稱,不過你可以使用:ref:`功能標籤 <doc_feature_tags>`來為不同平臺單獨進行覆蓋。

在移動平臺上,這個路徑是與專案相關的,每個專案都不一樣,並且出於安全原因無法被其他應用程式存取。

在 HTML5 匯出中,user:// 會指向裝置上由 IndexedDB 實作的虛擬檔案系統。(與主檔案系統的互動仍然可以通過 JavaScript 進行。)

將路徑轉換為絕對路徑或“本地”路徑

你可以使用 ProjectSettings.globalize_path() 將類似 res://path/to/file.txt 的本地路徑轉換為作業系統的絕對路徑。例如,可以使用 ProjectSettings.globalize_path() 在作業系統的檔案管理員中通過 OS.shell_open() 打開“本地”路徑,因為這個函式只接受原生作業系統路徑。

要將作業系統絕對路徑轉換為以 res://user:// 開頭的“本地”路徑,請使用 ProjectSettings.localize_path()。只對指向專案根目錄或者 user:// 資料夾中的檔案或資料夾有效。

編輯器資料路徑

根據平臺的不同,編輯器會使用不同的路徑來儲存編輯器資料、編輯器設定、快取。預設情況下,這些路徑是:

型別

位置

編輯器使用手冊

Windows: %APPDATA%\Godot\
macOS:~/Library/Application Support/Godot/
Linux: $HOME/.local/share/godot/templates/<版本>/

編輯器設定

Windows: %APPDATA%\Godot\
macOS:~/Library/Application Support/Godot/
Linux:~/.config/godot/

快取

Windows: %TEMP%\Godot\
macOS:~/Library/Caches/Godot/
Linux:~/.cache/godot/
  • **編輯器資料**包含匯出範本和具體專案資料。

  • **編輯器設定**包含主編輯器設定的配置,以及各種針對使用者的自訂資訊(編輯器佈局、功能配置、腳本範本等)。

  • **快取**包含編輯器生成的資料,或者臨時儲存的資料。當 Godot 關閉時可以放心地移除。

Godot 在所有平臺上都遵守 XDG 基本目錄規範。可以根據規範通過覆蓋環境變數來更改編輯器和專案的資料路徑。

備註

如果您使用的是 Flatpak 打包的 Godot,編輯器資料路徑將位於 ~/.var/app/org.godotengine.godot/ 的子資料夾中。

自包含模式

如果您在編輯器二進位檔案所在的目錄下建立了名為 ._sc__sc_ 的檔(macOS 編輯器 .app 組合包則是在 MacOS/Contents/ 下),Godot 就會開啟*自包含模式*。這種模式下,Godot 會將所有編輯器資料、設定、快取都寫入一個與編輯器二進位檔案位於同一目錄中的名為 editor_data/ 的目錄。你可以用它來建立便攜安裝的編輯器。

Steam 版本的 Godot 預設使用自包含模式。

備註

匯出後的專案目前不支援自包含模式。要對相對於可執行檔路徑的檔進行讀寫,請使用 OS.get_executable_path()。注意,只有可執行檔位於可寫的位置時,才能夠對可執行檔路徑上的檔進行寫操作(即**不在** Program Files 或者其他普通使用者唯讀的目錄中)。