ProjectSettings

继承： Object

存储全局变量。

描述

储存可以从任何地方访问的变量。请使用 get_setting、set_setting、has_setting 访问。存储在 project.godot 中的变量也会被加载到 ProjectSettings 中，因此这个对象常用于读取自定义游戏配置选项。

指定“项目设置”的属性时，请使用设置的完整路径，包括类别。例如项目名称应使用 "application/config/name"。类别和属性名称可以在“项目设置”对话框中查看。

特性标签：可以使用特性标签来针对特定的平台和配置（调试、发布……）做项目设置的覆盖。

覆盖：在项目的根目录下创建名为 override.cfg 的文件，就可以对任意项目设置进行覆盖。对于已导出的项目，把这个文件放在与项目二进制文件相同的目录下，也可以达到覆盖的目的。覆盖时仍会考虑基础项目设置的特性标签。因此，如果你想让它们在所有平台和配置上覆盖基础项目设置，请确保也用所需的特性标签覆盖该设置。

教程

• 3D 物理测试演示

• 3D 平台跳跃演示

• 操作系统测试演示

属性

方法

信号

settings_changed ( )

任何设置项发生改变的时候发出，每个处理帧最多一次。

属性说明

Color application/boot_splash/bg_color = Color(0.14, 0.14, 0.14, 1)

启动界面的背景色。

bool application/boot_splash/fullsize = true

如果为 true，引擎启动时会将启动界面图像缩放到整个窗口的大小（保持长宽比）。如果为 false，引擎将保持其默认像素大小。

String application/boot_splash/image = ""

图像的路径，会作为启动画面使用。留空时将使用默认的 Godot 引擎启动画面。

注意：仅在 application/boot_splash/show_image 为 true 时有效。

注意：只支持 PNG 格式。使用其他图像格式会导致出错。

int application/boot_splash/minimum_display_time = 0

启动画面的最小显示时间（单位为毫秒）。不建议设置为过高的值。

bool application/boot_splash/show_image = true

如果为 true，将在引擎启动时显示 application/boot_splash/image 所指定的图像。为 false 时，仅显示 application/boot_splash/bg_color 所指定的纯色。

bool application/boot_splash/use_filter = true

如果为 true，则在缩放图像时会应用线性过滤（推荐用于高分辨率图稿）。如果为 false，则使用最近邻插值（推荐用于像素画）。

bool application/config/auto_accept_quit = true

如果为 true，则该应用程序会自动接受退出请求。

String application/config/custom_user_dir_name = ""

该用户目录用于存储持久数据（user:// 文件系统）。如果定义了自定义目录名称，则该名称将被追加到系统特定的用户数据目录（与 OS.get_user_data_dir 中记录的 Godot 配置文件夹相同的父文件夹）。

application/config/use_custom_user_dir 设置必须被启用，该设置才能生效。

String application/config/description = ""

项目的描述，在项目管理器中悬停时显示为工具提示。

String application/config/icon = ""

项目所使用的图标，在项目加载时设置。导出器也会在必要时使用此图标作为回退。

String application/config/macos_native_icon = ""

设置 macOS 上游戏的图标，使用 .icns 图标集格式。启动时会通过调用 DisplayServer.set_native_icon 自动完成。

String application/config/name = ""

项目名称。会在项目管理器和导出器中使用。可以通过翻译本地化文件中的值来翻译项目名称。窗口标题将设置为在启动时自动匹配项目名称。

注意：如果 application/config/use_custom_user_dir 为 false，更改此值也会更改用户数据文件夹的路径。重命名项目后，你将无法再访问 user:// 中的现有数据，除非你重命名旧文件夹以匹配新项目名称。有关更多信息，请参阅文档中的 《数据路径》。

Dictionary application/config/name_localized = {}

项目名称的翻译。操作系统工具会使用此设置来翻译 Android、iOS 和 macOS 上的应用程序名称。

String application/config/project_settings_override = ""

指定一个文件来覆盖项目设置。例如：user://custom_settings.cfg。参见 ProjectSettings 顶部类描述中的“Overriding”以获取更多信息。

注意：不管这个设置的值如何，res://override.cfg 仍然会被读取来覆盖项目设置。

bool application/config/quit_on_go_back = true

如果为 true，则该应用程序会在导航返回时自动退出（例如在 Android 上使用系统“返回”键）。

bool application/config/use_custom_user_dir = false

如果为 true，项目会将用户数据保存到它自己的用户目录中。如果 application/config/custom_user_dir_name 为空，将使用 <操作系统用户数据目录>/<项目名称> 目录。如果为 false，项目会将用户数据保存到 <操作系统用户数据目录>/Godot/app_userdata/<项目名称>。

另见 Godot 项目中的文件路径。该设置仅在桌面平台上有效。

bool application/config/use_hidden_project_data_directory = true

如果为 true，该项目会使用隐藏目录（.godot）来存储项目特定的数据（元数据、着色器缓存等）。

如果为 false，将改用非隐藏目录（godot）。

注意：请在更改此设置后重新启动应用程序。

注意：修改这个值可能有助于在禁止使用隐藏目录模式的平台或第三方工具上使用。但是，仅在你确定你的环境需要更改此设置时才进行修改，因为某些外部工具或插件可能使用默认的 .godot 文件夹，因此更改默认设置可能会影响它们的使用。

String application/config/version = ""

项目的人类可读版本标识符。如果导出器中没有覆盖版本标识符，就会使用这个标识符。如果 application/config/version 为空字符串，并且导出器中没有覆盖版本标识符，则导出器会使用 1.0.0 作为版本标识符。

String application/config/windows_native_icon = ""

设置 Windows 上游戏的图标，使用 .ico 图标集格式。启动时会通过调用 DisplayServer.set_native_icon 自动完成。

bool application/run/delta_smoothing = true

帧增量的时间样本可能会受到平台带来的随机影响，即使垂直同步能够让帧按照固定的间隔显示也无济于事。因此可能导致卡顿。增量平滑通常能够带来更好的效果，会通过过滤输入增量来修改刷新率带来的微小波动。

注意：只会在 display/window/vsync/vsync_mode 为 enabled 时尝试进行增量平滑，因为没有垂直同步时无法很好地工作。

最开始激活平滑前可能会需要有若干秒的稳定帧率。只会在性能足以让渲染帧与刷新率匹配的机器上激活。

bool application/run/disable_stderr = false

如果为 true，则禁用打印到标准错误。如果为 true，也会隐藏由 @GlobalScope.push_error 和 @GlobalScope.push_warning 打印的错误和警告消息。另见 application/run/disable_stdout。

对该设置项的更改将只在重新启动应用程序后生效。

bool application/run/disable_stdout = false

如果为 true，则禁用打印到标准输出。相当于使用 --quiet 命令行参数启动编辑器或项目。另见 application/run/disable_stderr。

对该设置项的更改将只在重新启动应用程序后生效。

bool application/run/flush_stdout_on_print = false

如果为 true，则每次打印一行时刷新标准输出流。这会影响终端日志记录和文件日志记录。

运行项目时，如果希望由 systemd/journalctl 等服务管理器收集日志，则必须启用此设置。默认情况下，在发布版本中禁用此设置，因为如果快速连续打印大量行，则在每个打印行上刷新都会对性能产生负面影响。此外，如果启用此设置，如果应用程序崩溃或以其他方式被用户杀死（不会“正常”关闭），则仍会成功写入日志文件。

注意：无论此设置如何，标准错误流 (stderr) 在打印一行时总是被刷新。

对此设置的更改只会在重新启动应用程序时应用。

bool application/run/flush_stdout_on_print.debug = true

调试构建覆盖application/run/flush_stdout_on_print，因为在调试过程中性能不那么重要。

仅在重新启动应用程序时才会应用此设置的更改。

int application/run/frame_delay_msec = 0

强制主循环中的帧之间有恒定的延迟（以毫秒为单位）。在大多数情况下，应首选 application/run/max_fps 作为 FPS 限制器，因为它更精确。

可以使用 --frame-delay <ms;> 命令行参数覆盖该设置。

bool application/run/low_processor_mode = false

如果为 true，则启用低处理器使用模式。此设置仅适用于桌面平台。如果视觉上没有任何变化，屏幕不会被重绘。这是为了编写应用程序和编辑器，但在大多数游戏中这是非常无用的（并可能损害性能）。

int application/run/low_processor_mode_sleep_usec = 6900

启用低处理器使用模式时帧间的睡眠量（以微秒计）。值越高，CPU占用率越低。

String application/run/main_loop_type = "SceneTree"

实现引擎主循环的类型名称。

String application/run/main_scene = ""

项目运行时将加载的主场景文件的路径。

int application/run/max_fps = 0

每秒允许的最大帧数。0 表示“不限制”。如果 CPU 或 GPU 无法满足项目逻辑和渲染，则实际每秒的帧数可能仍然比这个值小。

限制 FPS 可以降低系统对电源的消耗，能够降低发热、减少噪音（延长移动设备的电池寿命）。

display/window/vsync/vsync_mode 为 Enabled 或 Adaptive 时，该设置优先生效，强制的 FPS 数无法超过显示器的刷新率。

display/window/vsync/vsync_mode 为 Enabled 时，在启用了可变刷新率（G-Sync/FreeSync）的显示器上使用比显示器刷新率略低几帧的 FPS 限制会降低输入延迟，避免画面撕裂。

display/window/vsync/vsync_mode 为 Disabled 时，与不限制帧率相比，将 FPS 限制设为系统所能达到的较高值能够降低输入延迟。因为原理是确保 GPU 负载低于 100%，所以只有在 GPU 为瓶颈时才会降低延迟，无法缓解 CPU 瓶颈导致的延迟。

另见 physics/common/physics_ticks_per_second。

这个设置可以使用 --max-fps <fps> 命令行参数覆盖（设为 0 则是不限制帧率）。

注意：这个属性仅在项目启动时读取。要在运行时修改渲染 FPS 上限，请改为设置 Engine.max_fps。

float audio/buses/channel_disable_threshold_db = -60.0

当声音在给定的时间内低于给定的 dB 阈值时，音频总线将自动关闭。这可以节省 CPU，因为分配给该总线的效果将不再做任何处理。

float audio/buses/channel_disable_time = 2.0

当声音在给定的时间内低于给定的 dB 阈值时，音频总线将自动关闭。这可以节省 CPU，因为分配给该总线的效果将不再做任何处理。

String audio/buses/default_bus_layout = "res://default_bus_layout.tres"

项目中使用的默认 AudioBusLayout 资源文件，除非被场景覆盖。

String audio/driver/driver

指定要使用的音频驱动程序。这个设置与平台有关，因为不同的平台支持不同的音频驱动。如果留空，将使用默认的音频驱动程序。

Dummy 音频驱动程序会禁用所有的音频播放和录制，对非游戏应用程序很有用，因为会减少对 CPU 的使用。它还可以防止引擎作为正在播放音频的应用程序出现在操作系统的音频混合器中。

注意：运行时可以通过 --audio-driver 命令行参数覆盖所使用的驱动程序。

bool audio/driver/enable_input = false

如果为 true，会允许麦克风输入。导出到 Android 和 iOS 时需要设置合适的权限。

注意：如果操作系统（根据该用户的隐私设置）阻止了对音频输入设备的访问，那么音频捕获只会返回静音。自 Windows 10 起，请确保在操作系统的隐私设置中允许应用对麦克风的访问。

int audio/driver/mix_rate = 44100

用于音频的混合率（单位：Hz）。一般来说，最好不要碰这个，把它留给主机操作系统。

int audio/driver/mix_rate.web = 0

audio/driver/mix_rate 在 Web 平台上更安全的覆盖项。这里的 0 表示“让浏览器选择”（因为有些浏览器不喜欢强制混合率）。

int audio/driver/output_latency = 15

指定音频的首选输出延迟，单位为毫秒。较低的值将导致较低的音频延迟，但会增加 CPU 使用率。低值可能会导致在较慢的硬件上发出可听见的破裂声。

音频输出延迟可能会受到主机操作系统和音频硬件驱动程序的限制。如果主机无法提供指定的音频输出延迟，那么 Godot 将尝试使用主机允许的最近延迟。因此，应该始终使用 AudioServer.get_output_latency 来确定实际的音频输出延迟。