diff --git a/tutorials/editor/img/project_settings_advanced.webp b/tutorials/editor/img/project_settings_advanced.webp new file mode 100644 index 000000000..2c720b0c3 Binary files /dev/null and b/tutorials/editor/img/project_settings_advanced.webp differ diff --git a/tutorials/editor/img/project_settings_basic.webp b/tutorials/editor/img/project_settings_basic.webp new file mode 100644 index 000000000..dbd5c02f6 Binary files /dev/null and b/tutorials/editor/img/project_settings_basic.webp differ diff --git a/tutorials/editor/project_settings.rst b/tutorials/editor/project_settings.rst index 03d651e27..b03b5fd40 100644 --- a/tutorials/editor/project_settings.rst +++ b/tutorials/editor/project_settings.rst @@ -1,16 +1,138 @@ -:article_outdated: True - .. _doc_project_settings: Project Settings ================ -This page explains how to use the Project Settings window. If you would like to access and modify project settings via code, see :ref:`ProjectSettings `. +There are dozens of settings you can change to control a project's execution, +including physics, rendering, and windowing settings. These settings can be +changed from the **Project Settings** window, from code, or by manually editing +the ``project.godot`` file. You can see a full list of settings in the +:ref:`ProjectSettings ` class. -Godot stores the project settings in a project.godot file, a plain text file in INI format. There are dozens of settings you can change to control a project's execution. To simplify this process, Godot provides a project settings dialog, which acts as a front-end to editing a project.godot file. +Internally, Godot stores the settings for a project in a ``project.godot`` file, +a plain text file in INI format. While this is human-readable and version control +friendly, it's not the most convenient to edit. For that reason, the +**Project Settings** window is available to edit these settings. To open the +Project Settings, select **Project > Project Settings** from the main menu. -To access that dialog, select Project -> Project Settings. +.. figure:: img/project_settings_basic.webp + :align: center -Once the window opens, let's select a main scene. Locate the `Application/Run/Main Scene` property and click on it to select 'hello.tscn'. + The Project Settings window -The project settings dialog provides a lot of options that can be saved to a project.godot file and shows their default values. If you change a value, a tick appears to the left of its name. This means that the property will be saved in the project.godot file and remembered. +The **Project Settings** window is mainly used to change settings in the +**General** tab. Additionally, there are tabs for the +:ref:`Input Map `, +:ref:`Localization `, +:ref:`Globals `, +:ref:`Plugins `, and +**Import Defaults**. Usage of these other tabs is documented elsewhere. + +Changing project settings +------------------------- + +The **General** tab of the project settings window works much like the inspector. +It displays a list of project settings which you can change, just like inspector +properties. There is a list of categories on the left, which you can use to select +related groups of settings. You can also search for a specific setting with the +**Filter Settings** field. + +Each setting has a default value. Settings can be reset to their default values +by clicking the circular arrow **Reset** button next to each property. + +Changing project settings from code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use :ref:`set_setting() ` to +change a setting's value from code: + +.. tabs:: + .. code-tab:: gdscript GDScript + + ProjectSettings.set_setting("application/run/max_fps", 60) + ProjectSettings.set_setting("display/window/size/mode", DisplayServer.WINDOW_MODE_WINDOWED) + + .. code-tab:: csharp + + ProjectSettings.SetSetting("application/run/max_fps", 60); + ProjectSettings.SetSetting("display/window/size/mode", (int)DisplayServer.WindowMode.Windowed); + +However, many project settings are only read once when the game starts. After +that, changing the setting with ``set_setting()`` will have no effect. Instead, +most settings have a corresponding property or method on a runtime class like +:ref:`Engine ` or :ref:`DisplayServer `: + +.. tabs:: + .. code-tab:: gdscript GDScript + + Engine.max_fps = 60 + DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_WINDOWED) + + .. code-tab:: csharp + + Engine.MaxFps = 60; + DisplayServer.WindowSetMode(DisplayServer.WindowMode.Windowed); + +In general, project settings are duplicated at runtime in the +:ref:`Engine `, :ref:`PhysicsServer2D `, +:ref:`PhysicsServer3D `, +:ref:`RenderingServer `, +:ref:`Viewport `, or :ref:`Window ` classes. In the +:ref:`ProjectSettings ` class reference, settings +links to their equivalent runtime property or method. + +Reading project settings +------------------------ + +You can read project settings with +:ref:`get_setting() ` or +:ref:`get_setting_with_override() `: + +.. tabs:: + .. code-tab:: gdscript GDScript + + var max_fps = ProjectSettings.get_setting("application/run/max_fps") + var window_mode = ProjectSettings.get_setting("display/window/size/mode") + + .. code-tab:: csharp + + int maxFps = (int)ProjectSettings.GetSetting("application/run/max_fps"); + var windowMode = (DisplayServer.WindowMode)(int)ProjectSettings.GetSetting("display/window/size/mode"); + +Since many project settings are only read once at startup, the value in the +project settings may no longer be accurate. In these cases, it's better to read +the value from the runtime equivalent property or method: + +.. tabs:: + .. code-tab:: gdscript GDScript + + var max_fps = Engine.max_fps + var window_mode = DisplayServer.window_get_mode() + + .. code-tab:: csharp + + int maxFps = Engine.MaxFps; + DisplayServer.WindowMode windowMode = DisplayServer.WindowGetMode(); + +Manually editing project.godot +------------------------------ + +You can open the ``project.godot`` file using a text editor and manually +change project settings. Note that if the ``project.godot`` file does not have a +stored value for a particular setting, it is implicitly the default value of +that setting. This means that if you are are manually editing the file, you may +have to write in both the setting name *and* the value. + +In general, it is recommended to use the Project Settings window rather than +manually edit ``project.godot``. + +Advanced project settings +------------------------- + +.. figure:: img/project_settings_advanced.webp + :align: center + + The advanced project settings + +By default, only some project settings are shown. To see all the project +settings, enable the **Advanced Settings** toggle. diff --git a/tutorials/inputs/input_examples.rst b/tutorials/inputs/input_examples.rst index 727d15c95..a5a36b4b5 100644 --- a/tutorials/inputs/input_examples.rst +++ b/tutorials/inputs/input_examples.rst @@ -149,6 +149,8 @@ avoid this, make sure to test the event type first: } } +.. _doc_input_examples_input_map: + InputMap -------- diff --git a/tutorials/plugins/editor/installing_plugins.rst b/tutorials/plugins/editor/installing_plugins.rst index 0be8a0cda..2e68d6ce1 100644 --- a/tutorials/plugins/editor/installing_plugins.rst +++ b/tutorials/plugins/editor/installing_plugins.rst @@ -53,6 +53,8 @@ plugin's ``addons/`` folder into your project folder to merge the new folder contents with the existing one. Your file manager may ask you whether to write into the folder; answer **Yes**. No files will be overwritten in the process. +.. _doc_installing_plugins_enabling_a_plugin: + Enabling a plugin ~~~~~~~~~~~~~~~~~