Struct ProjectSettings

pub struct ProjectSettings { /* private fields */ }

Expand description

Godot class ProjectSettings.

Inherits Object.

Related symbols:

project_settings: sidecar module with related enum/flag types
SignalsOfProjectSettings: signal collection

§Singleton

This class is a singleton. You can get the one instance using Singleton::singleton().

§Final class

This class is final, meaning you cannot inherit from it, and it comes without I* interface trait. It is still possible that other Godot classes inherit from it, but that is limited to the engine itself.

§Godot docs

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.

Implementations§

§

impl ProjectSettings

pub fn has_setting(&self, name: impl AsArg<GString>) -> bool

Returns true if a configuration value is present.

Note: In order to be be detected, custom settings have to be either defined with set_setting, or exist in the project.godot file. This is especially relevant when using set_initial_value.

pub fn set_setting(&mut self, name: impl AsArg<GString>, value: &Variant)

Sets the value of a setting.

ProjectSettings.set_setting("application/config/name", "Example")

This can also be used to erase custom project settings. To do this change the setting value to null.

pub fn get_setting(&self, name: impl AsArg<GString>) -> Variant

To set the default parameters, use get_setting_ex and its builder methods. See the book for detailed usage instructions. Returns the value of the setting identified by name. If the setting doesn’t exist and default_value is specified, the value of default_value is returned. Otherwise, null is returned.

print(ProjectSettings.get_setting("application/config/name"))
print(ProjectSettings.get_setting("application/config/custom_description", "No description specified."))

Note: This method doesn’t take potential feature overrides into account automatically. Use get_setting_with_override to handle seamlessly.

See also has_setting to check whether a setting exists.

pub fn get_setting_ex<'ex>( &'ex self, name: impl AsArg<GString> + 'ex, ) -> ExGetSetting<'ex>

Returns the value of the setting identified by name. If the setting doesn’t exist and default_value is specified, the value of default_value is returned. Otherwise, null is returned.

print(ProjectSettings.get_setting("application/config/name"))
print(ProjectSettings.get_setting("application/config/custom_description", "No description specified."))

Note: This method doesn’t take potential feature overrides into account automatically. Use get_setting_with_override to handle seamlessly.

See also has_setting to check whether a setting exists.

pub fn get_setting_with_override(&self, name: impl AsArg<StringName>) -> Variant

Similar to get_setting, but applies feature tag overrides if any exists and is valid.

Example: If the setting override "application/config/name.windows" exists, and the following code is executed on a Windows operating system, the overridden setting is printed instead:

print(ProjectSettings.get_setting_with_override("application/config/name"))

pub fn get_global_class_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns an Array of registered global classes. Each global class is represented as a Dictionary that contains the following entries:

base is a name of the base class;
class is a name of the registered global class;
icon is a path to a custom icon of the global class, if it has any;
language is a name of a programming language in which the global class is written;
path is a path to a file containing the global class.

Note: Both the script and the icon paths are local to the project filesystem, i.e. they start with res://.

pub fn get_setting_with_override_and_custom_features( &self, name: impl AsArg<StringName>, features: &PackedArray<GString>, ) -> Variant

Similar to get_setting_with_override, but applies feature tag overrides instead of current OS features.

pub fn set_order(&mut self, name: impl AsArg<GString>, position: i32)

Sets the order of a configuration value (influences when saved to the config file).

pub fn get_order(&self, name: impl AsArg<GString>) -> i32

Returns the order of a configuration value (influences when saved to the config file).

pub fn set_initial_value(&mut self, name: impl AsArg<GString>, value: &Variant)

Sets the specified setting’s initial value. This is the value the setting reverts to. The setting should already exist before calling this method. Note that project settings equal to their default value are not saved, so your code needs to account for that.

extends EditorPlugin

const SETTING_NAME = "addons/my_setting"
const SETTING_DEFAULT = 10.0

func _enter_tree():
	if not ProjectSettings.has_setting(SETTING_NAME):
		ProjectSettings.set_setting(SETTING_NAME, SETTING_DEFAULT)

	ProjectSettings.set_initial_value(SETTING_NAME, SETTING_DEFAULT)

If you have a project setting defined by an EditorPlugin, but want to use it in a running project, you will need a similar code at runtime.

pub fn set_as_basic(&mut self, name: impl AsArg<GString>, basic: bool)

Defines if the specified setting is considered basic or advanced. Basic settings will always be shown in the project settings. Advanced settings will only be shown if the user enables the “Advanced Settings” option.

pub fn set_as_internal(&mut self, name: impl AsArg<GString>, internal: bool)

Defines if the specified setting is considered internal. An internal setting won’t show up in the Project Settings dialog. This is mostly useful for addons that need to store their own internal settings without exposing them directly to the user.

pub fn add_property_info(&mut self, hint: &AnyDictionary)

Adds a custom property info to a property. The dictionary must contain:

"name": String (the property’s name)
"type": int (see [enum Variant.Type])
optionally "hint": int (see [enum PropertyHint]) and "hint_string": String

ProjectSettings.set("category/property_name", 0)

var property_info = {
	"name": "category/property_name",
	"type": TYPE_INT,
	"hint": PROPERTY_HINT_ENUM,
	"hint_string": "one,two,three"
}

ProjectSettings.add_property_info(property_info)

Note: Setting "usage" for the property is not supported. Use set_as_basic, set_restart_if_changed, and set_as_internal to modify usage flags.

pub fn set_restart_if_changed( &mut self, name: impl AsArg<GString>, restart: bool, )

Sets whether a setting requires restarting the editor to properly take effect.

Note: This is just a hint to display to the user that the editor must be restarted for changes to take effect. Enabling set_restart_if_changed does not delay the setting being set when changed.

pub fn clear(&mut self, name: impl AsArg<GString>)

Clears the whole configuration (not recommended, may break things).

pub fn localize_path(&self, path: impl AsArg<GString>) -> GString

Returns the localized path (starting with res://) corresponding to the absolute, native OS path. See also globalize_path.

pub fn globalize_path(&self, path: impl AsArg<GString>) -> GString

Returns the absolute, native OS path corresponding to the localized path (starting with res:// or user://). The returned path will vary depending on the operating system and user preferences. See File paths in Godot projects to see what those paths convert to. See also localize_path.

Note: globalize_path with res:// will not work in an exported project. Instead, prepend the executable’s base directory to the path when running from an exported project:

var path = ""
if OS.has_feature("editor"):
	# Running from an editor binary.
	# `path` will contain the absolute path to `hello.txt` located in the project root.
	path = ProjectSettings.globalize_path("res://hello.txt")
else:
	# Running from an exported project.
	# `path` will contain the absolute path to `hello.txt` next to the executable.
	# This is *not* identical to using `ProjectSettings.globalize_path()` with a `res://` path,
	# but is close enough in spirit.
	path = OS.get_executable_path().get_base_dir().path_join("hello.txt")

pub fn save(&mut self) -> Error

Saves the configuration to the project.godot file.

Note: This method is intended to be used by editor plugins, as modified ProjectSettings can’t be loaded back in the running app. If you want to change project settings in exported projects, use save_custom to save override.cfg file.

pub fn load_resource_pack(&mut self, pack: impl AsArg<GString>) -> bool

To set the default parameters, use load_resource_pack_ex and its builder methods. See the book for detailed usage instructions. Loads the contents of the .pck or .zip file specified by pack into the resource filesystem (res://). Returns true on success.

Note: If a file from pack shares the same path as a file already in the resource filesystem, any attempts to load that file will use the file from pack unless replace_files is set to false.

Note: The optional offset parameter can be used to specify the offset in bytes to the start of the resource pack. This is only supported for .pck files.

Note: DirAccess will not show changes made to the contents of res:// after calling this function.

pub fn load_resource_pack_ex<'ex>( &'ex mut self, pack: impl AsArg<GString> + 'ex, ) -> ExLoadResourcePack<'ex>

Loads the contents of the .pck or .zip file specified by pack into the resource filesystem (res://). Returns true on success.

Note: If a file from pack shares the same path as a file already in the resource filesystem, any attempts to load that file will use the file from pack unless replace_files is set to false.

Note: The optional offset parameter can be used to specify the offset in bytes to the start of the resource pack. This is only supported for .pck files.

Note: DirAccess will not show changes made to the contents of res:// after calling this function.

pub fn save_custom(&mut self, file: impl AsArg<GString>) -> Error

Saves the configuration to a custom file. The file extension must be .godot (to save in text-based ConfigFile format) or .binary (to save in binary format). You can also save override.cfg file, which is also text, but can be used in exported projects unlike other formats.

pub fn get_changed_settings(&self) -> PackedArray<GString>

Gets an array of the settings which have been changed since the last save. Note that internally changed_settings is cleared after a successful save, so generally the most appropriate place to use this method is when processing settings_changed.

pub fn check_changed_settings_in_group( &self, setting_prefix: impl AsArg<GString>, ) -> bool

Checks if any settings with the prefix setting_prefix exist in the set of changed settings. See also get_changed_settings.

Methods from Deref<Target = Object>§

pub fn get_script(&self) -> Option<Gd<Script>>

pub fn set_script(&mut self, script: impl AsArg<Option<Gd<Script>>>)

pub fn connect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, ) -> Error

pub fn connect_flags( &mut self, signal: impl AsArg<StringName>, callable: &Callable, flags: ConnectFlags, ) -> Error

pub fn get_class(&self) -> GString

Returns the object’s built-in class name, as a String. See also is_class.

Note: This method ignores class_name declarations. If this object’s script has defined a class_name, the base, built-in class name is returned instead.

pub fn is_class(&self, class: impl AsArg<GString>) -> bool

Returns true if the object inherits from the given class. See also get_class.

var sprite2d = Sprite2D.new()
sprite2d.is_class("Sprite2D") # Returns true
sprite2d.is_class("Node")     # Returns true
sprite2d.is_class("Node3D")   # Returns false

Note: This method ignores class_name declarations in the object’s script.

pub fn set(&mut self, property: impl AsArg<StringName>, value: &Variant)

Assigns value to the given property. If the property does not exist or the given value’s type doesn’t match, nothing happens.

var node = Node2D.new()
node.set("global_scale", Vector2(8, 2.5))
print(node.global_scale) # Prints (8.0, 2.5)

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn get(&self, property: impl AsArg<StringName>) -> Variant

Returns the Variant value of the given property. If the property does not exist, this method returns null.

var node = Node2D.new()
node.rotation = 1.5
var a = node.get("rotation") # a is 1.5

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn set_indexed( &mut self, property_path: impl AsArg<NodePath>, value: &Variant, )

Assigns a new value to the property identified by the property_path. The path should be a NodePath relative to this object, and can use the colon character (:) to access nested properties.

var node = Node2D.new()
node.set_indexed("position", Vector2(42, 0))
node.set_indexed("position:y", -10)
print(node.position) # Prints (42.0, -10.0)

Note: In C#, property_path must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn get_indexed(&self, property_path: impl AsArg<NodePath>) -> Variant

Gets the object’s property indexed by the given property_path. The path should be a NodePath relative to the current object and can use the colon character (:) to access nested properties.

Examples: "position:x" or "material:next_pass:blend_mode".

var node = Node2D.new()
node.position = Vector2(5, -10)
var a = node.get_indexed("position")   # a is Vector2(5, -10)
var b = node.get_indexed("position:y") # b is -10

Note: In C#, property_path must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

Note: This method does not support actual paths to nodes in the SceneTree, only sub-property paths. In the context of nodes, use get_node_and_resource instead.

pub fn get_property_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns the object’s property list as an Array of dictionaries. Each Dictionary contains the following entries:

name is the property’s name, as a String;
class_name is an empty StringName, unless the property is VariantType::OBJECT and it inherits from a class;
type is the property’s type, as an int (see [enum Variant.Type]);
hint is how the property is meant to be edited (see [enum PropertyHint]);
hint_string depends on the hint (see [enum PropertyHint]);
usage is a combination of [enum PropertyUsageFlags].

Note: In GDScript, all class members are treated as properties. In C# and GDExtension, it may be necessary to explicitly mark class members as Godot properties using decorators or attributes.

pub fn get_method_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns this object’s methods and their signatures as an Array of dictionaries. Each Dictionary contains the following entries:

name is the name of the method, as a String;
args is an Array of dictionaries representing the arguments;
default_args is the default arguments as an Array of variants;
flags is a combination of [enum MethodFlags];
id is the method’s internal identifier int;
return is the returned value, as a Dictionary;

Note: The dictionaries of args and return are formatted identically to the results of get_property_list, although not all entries are used.

pub fn property_can_revert(&self, property: impl AsArg<StringName>) -> bool

Returns true if the given property has a custom default value. Use property_get_revert to get the property’s default value.

Note: This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_can_revert] to customize the default value. If [method _property_can_revert] is not implemented, this method returns false.

pub fn property_get_revert(&self, property: impl AsArg<StringName>) -> Variant

Returns the custom default value of the given property. Use property_can_revert to check if the property has a custom default value.

Note: This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_get_revert] to customize the default value. If [method _property_get_revert] is not implemented, this method returns null.

pub fn set_meta(&mut self, name: impl AsArg<StringName>, value: &Variant)

Adds or changes the entry name inside the object’s metadata. The metadata value can be any Variant, although some types cannot be serialized correctly.

If value is null, the entry is removed. This is the equivalent of using remove_meta. See also has_meta and get_meta.