ProjectSettings

Inherits: Object

Stores globally-accessible variables.

Description

Stores variables that can be accessed from everywhere. Use get_setting, set_setting or has_setting to access them. Variables stored in project.godot are also loaded into ProjectSettings, making this object very useful for reading custom game configuration options.

When naming a Project Settings property, use the full path to the setting including the category. For example, "application/config/name" for the project name. Category and property names can be viewed in the Project Settings dialog.

Feature tags: Project settings can be overridden for specific platforms and configurations (debug, release, …) using feature tags.

Overriding: Any project setting can be overridden by creating a file named override.cfg in the project’s root directory. This can also be used in exported projects by placing this file in the same directory as the project binary. Overriding will still take the base project settings’ feature tags in account. Therefore, make sure to also override the setting with the desired feature tags if you want them to override base project settings on all platforms and configurations.

Tutorials

• 3D Physics Tests Demo

• 3D Platformer Demo

• OS Test Demo

Properties

Methods

Signals

settings_changed ( )

Emitted when any setting is changed, up to once per process frame.

Property Descriptions

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

Background color for the boot splash.

bool application/boot_splash/fullsize = true

If true, scale the boot splash image to the full window size (preserving the aspect ratio) when the engine starts. If false, the engine will leave it at the default pixel size.

String application/boot_splash/image = ""

Path to an image used as the boot splash. If left empty, the default Godot Engine splash will be displayed instead.

Note: Only effective if application/boot_splash/show_image is true.

Note: The only supported format is PNG. Using another image format will result in an error.

int application/boot_splash/minimum_display_time = 0

Minimum boot splash display time (in milliseconds). It is not recommended to set too high values for this setting.

bool application/boot_splash/show_image = true

If true, displays the image specified in application/boot_splash/image when the engine starts. If false, only displays the plain color specified in application/boot_splash/bg_color.

bool application/boot_splash/use_filter = true

If true, applies linear filtering when scaling the image (recommended for high-resolution artwork). If false, uses nearest-neighbor interpolation (recommended for pixel art).

bool application/config/auto_accept_quit = true

If true, the application automatically accepts quitting requests.

String application/config/custom_user_dir_name = ""

This user directory is used for storing persistent data (user:// filesystem). If a custom directory name is defined, this name will be appended to the system-specific user data directory (same parent folder as the Godot configuration folder documented in OS.get_user_data_dir).

The application/config/use_custom_user_dir setting must be enabled for this to take effect.

String application/config/description = ""

The project’s description, displayed as a tooltip in the Project Manager when hovering the project.

String application/config/icon = ""

Icon used for the project, set when project loads. Exporters will also use this icon as a fallback if necessary.

String application/config/macos_native_icon = ""

Icon set in .icns format used on macOS to set the game’s icon. This is done automatically on start by calling DisplayServer.set_native_icon.

String application/config/name = ""

The project’s name. It is used both by the Project Manager and by exporters. The project name can be translated by translating its value in localization files. The window title will be set to match the project name automatically on startup.

Note: Changing this value will also change the user data folder’s path if application/config/use_custom_user_dir is false. After renaming the project, you will no longer be able to access existing data in user:// unless you rename the old folder to match the new project name. See Data paths in the documentation for more information.

Dictionary application/config/name_localized = {}

Translations of the project’s name. This setting is used by OS tools to translate application name on Android, iOS and macOS.

String application/config/project_settings_override = ""

Specifies a file to override project settings. For example: user://custom_settings.cfg. See “Overriding” in the ProjectSettings class description at the top for more information.

Note: Regardless of this setting’s value, res://override.cfg will still be read to override the project settings.

bool application/config/quit_on_go_back = true

If true, the application quits automatically when navigating back (e.g. using the system “Back” button on Android).

bool application/config/use_custom_user_dir = false

If true, the project will save user data to its own user directory. If application/config/custom_user_dir_name is empty, <OS user data directory>/<project name> directory will be used. If false, the project will save user data to <OS user data directory>/Godot/app_userdata/<project name>.

See also File paths in Godot projects. This setting is only effective on desktop platforms.

bool application/config/use_hidden_project_data_directory = true

If true, the project will use a hidden directory (.godot) for storing project-specific data (metadata, shader cache, etc.).

If false, a non-hidden directory (godot) will be used instead.

Note: Restart the application after changing this setting.

Note: Changing this value can help on platforms or with third-party tools where hidden directory patterns are disallowed. Only modify this setting if you know that your environment requires it, as changing the default can impact compatibility with some external tools or plugins which expect the default .godot folder.

String application/config/version = ""

The project’s human-readable version identifier. This is used by exporters if the version identifier isn’t overridden there. If application/config/version is an empty string and the version identifier isn’t overridden in an exporter, the exporter will use 1.0.0 as a version identifier.

String application/config/windows_native_icon = ""

Icon set in .ico format used on Windows to set the game’s icon. This is done automatically on start by calling DisplayServer.set_native_icon.

bool application/run/delta_smoothing = true

Time samples for frame deltas are subject to random variation introduced by the platform, even when frames are displayed at regular intervals thanks to V-Sync. This can lead to jitter. Delta smoothing can often give a better result by filtering the input deltas to correct for minor fluctuations from the refresh rate.

Note: Delta smoothing is only attempted when display/window/vsync/vsync_mode is set to enabled, as it does not work well without V-Sync.

It may take several seconds at a stable frame rate before the smoothing is initially activated. It will only be active on machines where performance is adequate to render frames at the refresh rate.

bool application/run/disable_stderr = false

If true, disables printing to standard error. If true, this also hides error and warning messages printed by @GlobalScope.push_error and @GlobalScope.push_warning. See also application/run/disable_stdout.

Changes to this setting will only be applied upon restarting the application.

bool application/run/disable_stdout = false

If true, disables printing to standard output. This is equivalent to starting the editor or project with the --quiet command line argument. See also application/run/disable_stderr.

Changes to this setting will only be applied upon restarting the application.

bool application/run/flush_stdout_on_print = false

If true, flushes the standard output stream every time a line is printed. This affects both terminal logging and file logging.

When running a project, this setting must be enabled if you want logs to be collected by service managers such as systemd/journalctl. This setting is disabled by default on release builds, since flushing on every printed line will negatively affect performance if lots of lines are printed in a rapid succession. Also, if this setting is enabled, logged files will still be written successfully if the application crashes or is otherwise killed by the user (without being closed “normally”).

Note: Regardless of this setting, the standard error stream (stderr) is always flushed when a line is printed to it.

Changes to this setting will only be applied upon restarting the application.

bool application/run/flush_stdout_on_print.debug = true

Debug build override for application/run/flush_stdout_on_print, as performance is less important during debugging.

Changes to this setting will only be applied upon restarting the application.

int application/run/frame_delay_msec = 0

Forces a constant delay between frames in the main loop (in milliseconds). In most situations, application/run/max_fps should be preferred as an FPS limiter as it’s more precise.

This setting can be overridden using the --frame-delay <ms;> command line argument.

bool application/run/low_processor_mode = false

If true, enables low-processor usage mode. This setting only works on desktop platforms. The screen is not redrawn if nothing changes visually. This is meant for writing applications and editors, but is pretty useless (and can hurt performance) in most games.

int application/run/low_processor_mode_sleep_usec = 6900

Amount of sleeping between frames when the low-processor usage mode is enabled (in microseconds). Higher values will result in lower CPU usage.

String application/run/main_loop_type = "SceneTree"

The name of the type implementing the engine’s main loop.

String application/run/main_scene = ""

Path to the main scene file that will be loaded when the project runs.

int application/run/max_fps = 0

Maximum number of frames per second allowed. A value of 0 means “no limit”. The actual number of frames per second may still be below this value if the CPU or GPU cannot keep up with the project logic and rendering.

Limiting the FPS can be useful to reduce system power consumption, which reduces heat and noise emissions (and improves battery life on mobile devices).

If display/window/vsync/vsync_mode is set to Enabled or Adaptive, it takes precedence and the forced FPS number cannot exceed the monitor’s refresh rate.

If display/window/vsync/vsync_mode is Enabled, on monitors with variable refresh rate enabled (G-Sync/FreeSync), using a FPS limit a few frames lower than the monitor’s refresh rate will reduce input lag while avoiding tearing.

If display/window/vsync/vsync_mode is Disabled, limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios.

See also physics/common/physics_ticks_per_second.

This setting can be overridden using the --max-fps <fps> command line argument (including with a value of 0 for unlimited framerate).

Note: This property is only read when the project starts. To change the rendering FPS cap at runtime, set Engine.max_fps instead.

float audio/buses/channel_disable_threshold_db = -60.0

Audio buses will disable automatically when sound goes below a given dB threshold for a given time. This saves CPU as effects assigned to that bus will no longer do any processing.

float audio/buses/channel_disable_time = 2.0

Audio buses will disable automatically when sound goes below a given dB threshold for a given time. This saves CPU as effects assigned to that bus will no longer do any processing.

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

Default AudioBusLayout resource file to use in the project, unless overridden by the scene.

String audio/driver/driver

Specifies the audio driver to use. This setting is platform-dependent as each platform supports different audio drivers. If left empty, the default audio driver will be used.

The Dummy audio driver disables all audio playback and recording, which is useful for non-game applications as it reduces CPU usage. It also prevents the engine from appearing as an application playing audio in the OS’ audio mixer.

Note: The driver in use can be overridden at runtime via the --audio-driver command line argument.

bool audio/driver/enable_input = false

If true, microphone input will be allowed. This requires appropriate permissions to be set when exporting to Android or iOS.

Note: If the operating system blocks access to audio input devices (due to the user’s privacy settings), audio capture will only return silence. On Windows 10 and later, make sure that apps are allowed to access the microphone in the OS’ privacy settings.

int audio/driver/mix_rate = 44100

The mixing rate used for audio (in Hz). In general, it’s better to not touch this and leave it to the host operating system.

int audio/driver/mix_rate.web = 0

Safer override for audio/driver/mix_rate in the Web platform. Here 0 means “let the browser choose” (since some browsers do not like forcing the mix rate).

int audio/driver/output_latency = 15

Specifies the preferred output latency in milliseconds for audio. Lower values will result in lower audio latency at the cost of increased CPU usage. Low values may result in audible cracking on slower hardware.

Audio output latency may be constrained by the host operating system and audio hardware drivers. If the host can not provide the specified audio output latency then Godot will attempt to use the nearest latency allowed by the host. As such you should always use AudioServer.get_output_latency to determine the actual audio output latency.