Table of Contents

Class ProjectSettings

Namespace
Godot
Assembly
GodotSharp.dll

Stores variables that can be accessed from everywhere. Use GetSetting(string, Variant), SetSetting(string, Variant) or HasSetting(string) 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.

public static class ProjectSettings
Inheritance
ProjectSettings
Inherited Members

Properties

Singleton 

public static ProjectSettingsInstance Singleton { get; }

Property Value

ProjectSettingsInstance

Methods

AddPropertyInfo(Dictionary)

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

- "name": string (the property's name)

- "type": int (see Variant.Type)

- optionally "hint": int (see PropertyHint) and "hint_string": string

Example: 

ProjectSettings.Singleton.Set("category/property_name", 0);

var propertyInfo = new Godot.Collections.Dictionary
{
{"name", "category/propertyName"},
{"type", (int)Variant.Type.Int},
{"hint", (int)PropertyHint.Enum},
{"hint_string", "one,two,three"},
};


ProjectSettings.AddPropertyInfo(propertyInfo);
public static void AddPropertyInfo(Dictionary hint)

Parameters

hint Dictionary

Clear(string)

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

public static void Clear(string name)

Parameters

name string

GetGlobalClassList()

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://.

public static Array<Dictionary> GetGlobalClassList()

Returns

Array<Dictionary>

GetOrder(string)

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

public static int GetOrder(string name)

Parameters

name string

Returns

int

GetSetting(string, Variant)

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

Example: 

GD.Print(ProjectSettings.GetSetting("application/config/name"));
  GD.Print(ProjectSettings.GetSetting("application/config/custom_description", "No description specified."));

Note: This method doesn't take potential feature overrides into account automatically. Use GetSettingWithOverride(StringName) to handle seamlessly.

public static Variant GetSetting(string name, Variant defaultValue = default)

Parameters

name string
defaultValue Variant

Returns

Variant

GetSettingWithOverride(StringName)

Similar to GetSetting(string, Variant), but applies feature tag overrides if any exists and is valid.

Example:

If the following setting override exists "application/config/name.windows", and the following code is executed:

GD.Print(ProjectSettings.GetSettingWithOverride("application/config/name"));

Then the overridden setting will be returned instead if the project is running on the Windows operating system.

public static Variant GetSettingWithOverride(StringName name)

Parameters

name StringName

Returns

Variant

GlobalizePath(string)

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 LocalizePath(string).

Note: GlobalizePath(string) 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")
public static string GlobalizePath(string path)

Parameters

path string

Returns

string

HasSetting(string)

Returns true if a configuration value is present.

public static bool HasSetting(string name)

Parameters

name string

Returns

bool

LoadResourcePack(string, bool, int)

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 replaceFiles 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.

public static bool LoadResourcePack(string pack, bool replaceFiles = true, int offset = 0)

Parameters

pack string
replaceFiles bool
offset int

Returns

bool

LocalizePath(string)

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

public static string LocalizePath(string path)

Parameters

path string

Returns

string

Save()

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 SaveCustom(string) to save override.cfg file.

public static Error Save()

Returns

Error

SaveCustom(string)

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.

public static Error SaveCustom(string file)

Parameters

file string

Returns

Error

SetAsBasic(string, 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.

public static void SetAsBasic(string name, bool basic)

Parameters

name string
basic bool

SetAsInternal(string, 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.

public static void SetAsInternal(string name, bool @internal)

Parameters

name string
internal bool

SetInitialValue(string, Variant)

Sets the specified setting's initial value. This is the value the setting reverts to.

public static void SetInitialValue(string name, Variant value)

Parameters

name string
value Variant

SetOrder(string, int)

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

public static void SetOrder(string name, int position)

Parameters

name string
position int

SetRestartIfChanged(string, 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 SetRestartIfChanged(string, bool) does not delay the setting being set when changed.

public static void SetRestartIfChanged(string name, bool restart)

Parameters

name string
restart bool

SetSetting(string, Variant)

Sets the value of a setting.

Example: 

ProjectSettings.SetSetting("application/config/name", "Example");

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

public static void SetSetting(string name, Variant value)

Parameters

name string
value Variant

Events

SettingsChanged

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

public static event Action SettingsChanged

Event Type

Action
Edit this page