Up to date

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

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

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.

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/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 delay between frames in the main loop (in milliseconds). This may be useful if you plan to disable vertical synchronization.

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.

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.

Note: This setting is ignored on all versions of Windows prior to Windows 10.

int audio/driver/output_latency.web = 50

Safer override for audio/driver/output_latency in the Web platform, to avoid audio issues especially on mobile devices.

float audio/general/2d_panning_strength = 0.5

The base strength of the panning effect for all AudioStreamPlayer2D nodes. The panning strength can be further scaled on each Node using AudioStreamPlayer2D.panning_strength. A value of 0.0 disables stereo panning entirely, leaving only volume attenuation in place. A value of 1.0 completely mutes one of the channels if the sound is located exactly to the left (or right) of the listener.

The default value of 0.5 is tuned for headphones. When using speakers, you may find lower values to sound better as speakers have a lower stereo separation compared to headphones.

float audio/general/3d_panning_strength = 0.5

The base strength of the panning effect for all AudioStreamPlayer3D nodes. The panning strength can be further scaled on each Node using AudioStreamPlayer3D.panning_strength. A value of 0.0 disables stereo panning entirely, leaving only volume attenuation in place. A value of 1.0 completely mutes one of the channels if the sound is located exactly to the left (or right) of the listener.

The default value of 0.5 is tuned for headphones. When using speakers, you may find lower values to sound better as speakers have a lower stereo separation compared to headphones.

bool audio/general/text_to_speech = false

If true, text-to-speech support is enabled, see DisplayServer.tts_get_voices and DisplayServer.tts_speak.

Note: Enabling TTS can cause addition idle CPU usage and interfere with the sleep mode, so consider disabling it if TTS is not used.

int audio/video/video_delay_compensation_ms = 0

Setting to hardcode audio delay when playing video. Best to leave this untouched unless you know what you are doing.

int compression/formats/gzip/compression_level = -1

The default compression level for gzip. Affects compressed scenes and resources. Higher levels result in smaller files at the cost of compression speed. Decompression speed is mostly unaffected by the compression level. -1 uses the default gzip compression level, which is identical to 6 but could change in the future due to underlying zlib updates.

int compression/formats/zlib/compression_level = -1

The default compression level for Zlib. Affects compressed scenes and resources. Higher levels result in smaller files at the cost of compression speed. Decompression speed is mostly unaffected by the compression level. -1 uses the default gzip compression level, which is identical to 6 but could change in the future due to underlying zlib updates.

int compression/formats/zstd/compression_level = 3

The default compression level for Zstandard. Affects compressed scenes and resources. Higher levels result in smaller files at the cost of compression speed. Decompression speed is mostly unaffected by the compression level.

bool compression/formats/zstd/long_distance_matching = false

Enables long-distance matching in Zstandard.

int compression/formats/zstd/window_log_size = 27

Largest size limit (in power of 2) allowed when compressing using long-distance matching with Zstandard. Higher values can result in better compression, but will require more memory when compressing and decompressing.

bool debug/file_logging/enable_file_logging = false

If true, logs all output to files.

bool debug/file_logging/enable_file_logging.pc = true

Desktop override for debug/file_logging/enable_file_logging, as log files are not readily accessible on mobile/Web platforms.

String debug/file_logging/log_path = "user://logs/godot.log"

Path at which to store log files for the project. Using a path under user:// is recommended.

int debug/file_logging/max_log_files = 5

Specifies the maximum number of log files allowed (used for rotation).

int debug/gdscript/warnings/assert_always_false = 1

When set to warn or error, produces a warning or an error respectively when an assert call always evaluates to false.

int debug/gdscript/warnings/assert_always_true = 1

When set to warn or error, produces a warning or an error respectively when an assert call always evaluates to true.

int debug/gdscript/warnings/confusable_identifier = 1

When set to warn or error, produces a warning or an error respectively when an identifier contains characters that can be confused with something else, like when mixing different alphabets.

int debug/gdscript/warnings/constant_used_as_function = 1

When set to warn or error, produces a warning or an error respectively when a constant is used as a function.

int debug/gdscript/warnings/deprecated_keyword = 1

When set to warn or error, produces a warning or an error respectively when deprecated keywords are used.

int debug/gdscript/warnings/empty_file = 1

When set to warn or error, produces a warning or an error respectively when an empty file is parsed.

bool debug/gdscript/warnings/enable = true

If true, enables specific GDScript warnings (see debug/gdscript/warnings/* settings). If false, disables all GDScript warnings.

bool debug/gdscript/warnings/exclude_addons = true

If true, scripts in the res://addons folder will not generate warnings.

int debug/gdscript/warnings/function_used_as_property = 1

When set to warn or error, produces a warning or an error respectively when using a function as if it is a property.

int debug/gdscript/warnings/get_node_default_without_onready = 2

When set to warn or error, produces a warning or an error respectively when Node.get_node (or the shorthand $) is used as default value of a class variable without the @onready annotation.

int debug/gdscript/warnings/incompatible_ternary = 1

When set to warn or error, produces a warning or an error respectively when a ternary operator may emit values with incompatible types.

int debug/gdscript/warnings/inference_on_variant = 2

When set to warn or error, produces a warning or an error respectively when a static inferred type uses a Variant as initial value, which makes the static type to also be Variant.

int debug/gdscript/warnings/int_as_enum_without_cast = 1

When set to warn or error, produces a warning or an error respectively when trying to use an integer as an enum without an explicit cast.

int debug/gdscript/warnings/int_as_enum_without_match = 1

When set to warn or error, produces a warning or an error respectively when trying to use an integer as an enum when there is no matching enum member for that numeric value.

int debug/gdscript/warnings/integer_division = 1

When set to warn or error, produces a warning or an error respectively when dividing an integer by another integer (the decimal part will be discarded).

int debug/gdscript/warnings/narrowing_conversion = 1

When set to warn or error, produces a warning or an error respectively when passing a floating-point value to a function that expects an integer (it will be converted and lose precision).

int debug/gdscript/warnings/native_method_override = 2

When set to warn or error, produces a warning or an error respectively when a method in the script overrides a native method, because it may not behave as expected.

int debug/gdscript/warnings/onready_with_export = 2

When set to warn or error, produces a warning or an error respectively when the @onready annotation is used together with the @export annotation, since it may not behave as expected.