Godot 项目中的文件路径

本页面会讲解 Godot 项目中文件路径的工作原理。你会学到如何在项目中使用 res://user:// 访问路径,以及 Godot 会在硬盘的哪些位置存储用户文件。

路径分隔符

为了支持尽可能多的平台,Godot 只接受 UNIX 风格的路径分隔符(/)。所有平台上都可以使用,包括 Windows。

以前写成 C:\Projects 的路径,在 Godot 中,就应该写 C:/Projects

访问项目文件夹中的文件

只要文件夹中存在名叫 project.godot 的文本文件,即便是空文件,Godot 也会认为这个文件夹中包含了一个项目。包含这个文件的文件夹是你的项目的根文件夹。

相对于这个文件夹的任何文件,都可以通过以 res:// 开头的路径访问,这个前缀代表“资源”(resource)。例如,在代码中,你可以通过 res://纹理名称.png 来访问位于项目根文件夹的 character.png 图片。

访问持久化用户数据

要存储持久化数据文件,比如玩家的存档、设置等,你会想要使用 user:// 作为路径前缀,而不是 res://。这是因为游戏运行时,项目的文件系统很可能是只读的。

user:// 前缀指向的是用户设备上的另一个目录。在移动设备和主机上,对项目来说此路径是唯一的。在桌面平台,引擎存储用户文件的位置在 Linux 上是 ~/.local/share/godot/app_userdata/[项目名称],在 macOS(Catalina 及后续版本)上是 ~/Library/Application Support/Godot/app_userdata/[项目名称],在 Windows 上则是 %APPDATA%\Godot\app_userdata\[项目名称][项目名称] 取自“项目设置”中定义的应用程序名称,但它可被特性标签针对不同的平台进行覆盖。

在 HTML5 导出中,user:// 会指向设备上由 IndexedDB 实现的虚拟文件系统。(与主文件系统的交互仍然可以通过 JavaScript 进行。)

编辑器数据路径

编辑器根据平台使用不同的路径来存储用户数据、用户设置、缓存。默认情况下,这些路径是:

类型

位置

用户数据

  • Windows:%APPDATA%\Godot\app_userdata\[项目名称]

  • macOS:~/Library/Application Support/Godot/[项目名称]

  • Linux:~/.local/share/godot/[项目名称]

用户数据(项目设置 use_custom_user_dirtrue 时)

  • Windows:%APPDATA%\[项目名称]

  • macOS:~/Library/Application Support/Godot/[项目名称]

  • Linux:~/.local/share/godot/[项目名称]

用户设置

  • 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_ 的文件,Godot 就会开启自包含模式。这种模式下,Godot 会将所有用户数据都写入一个与编辑器二进制文件位于同一目录中的名为 editor_data/ 的目录。你可以用它来创建便携安装的编辑器。

Steam 版本的 Godot 默认使用自包含模式。