godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'godotengine:master' into export_file-breaking-change-doc

Browse Source
This commit is contained in:
Ayush Raj
2025-07-27 19:44:00 +05:30
committed by GitHub
parent 7ba0a7cf0e b2dcf6a650
commit 21a2761a93
127 changed files with 2348 additions and 1098 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/ci.yml vendored
View File

@@ -19,6 +19,10 @@ jobs:
- name: Style checks via pre-commit
uses: pre-commit/action@v3.0.1
- name: Custom RST checks (check-rst.sh)
run: |
bash ./_tools/check-rst.sh
- name: Get Python version
id: pythonv
run: |

19
_static/css/custom.css
View File

@@ -150,6 +150,8 @@
--kbd-shadow-color: #b0b7bf;
--kbd-text-color: #444d56;
--role-button-background-color: #d3d7e1;
--code-example-good-color: #3fb950;
--code-example-bad-color: #f85149;
@@ -279,6 +281,8 @@
--kbd-outline-color: #3d4144;
--kbd-shadow-color: #1e2023;
--kbd-text-color: #e2f2ff;
--role-button-background-color: #22252d;
--code-example-good-color: #3fb950;
--code-example-bad-color: #f85149;
@@ -1844,3 +1848,18 @@ p + .classref-constant {
#godot-giscus {
margin-bottom: 1em;
}
/* Custom Sphinx roles for editor UI */
/* The :ui: and :inspector: roles just render as bold. */
.role-ui {
font-weight: 700;
}
.role-button, .role-menu {
font-size: 80%;
border-radius: 4px;
padding: 2.4px 6px;
margin: auto 2px;
border: 0px solid #7fbbe3;
background: var(--role-button-background-color);
}

10
_tools/check-rst.sh Executable file
View File

@@ -0,0 +1,10 @@
#!/usr/bin/env bash
set -uo pipefail
output=$(grep -r -P '^(?!\s*\.\.).*\S::$' --include='*.rst' --exclude='docs_writing_guidelines.rst' .)
if [[ -n $output ]]; then
echo 'The shorthand codeblock syntax (trailing `::`) is not allowed.'
echo "$output"
exit 1
fi

2
about/faq.rst
View File

@@ -579,7 +579,7 @@ general-purpose library, but we had special requirements for Godot.
* We use our custom String type, as the one provided by STL is too basic and lacks proper
internationalization support.
Check out :ref:`Godot's container types <doc_cpp_godot_types>` for alternatives.
Check out :ref:`Godot's container types <doc_core_types>` for alternatives.
Why does Godot not use exceptions?
----------------------------------

7
about/list_of_features.rst
View File

@@ -36,6 +36,13 @@ Platforms
- :ref:`Web browsers <doc_using_the_web_editor>`. Experimental in 4.0,
using Godot 3.x is recommended instead when targeting HTML5.
.. note::
Linux supports rv64 (RISC-V), ppc64 & ppc32 (PowerPC), and loongarch64. However
you must compile the editor for that platform (as well as export templates)
yourself, no official downloads are currently provided. RISC-V compiling
instructions can be found on the :ref:`doc_compiling_for_linuxbsd` page.
**Runs exported projects:**
- iOS.

45
about/system_requirements.rst
View File

@@ -23,17 +23,18 @@ Desktop or laptop PC - Minimum
.. which can run up to macOS 10.13.
+----------------------+-----------------------------------------------------------------------------------------+
| **CPU** | - **Windows:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv8 CPU |
| **CPU** | - **Windows:** x86_32 CPU with SSE2 support, x86_64 CPU with SSE4.2 support, ARMv8 CPU |
| | |
| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Snapdragon X Elite* |
| | - *Example: Intel Core 2 Duo E8200, AMD FX-4100, Snapdragon X Elite* |
| | |
| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) |
| | |
| | - *Example: Intel Core 2 Duo SU9400, Apple M1* |
| | |
| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU |
| | - **Linux:** x86_32 CPU with SSE2 support, x86_64 CPU with SSE4.2 support, ARMv7 or |
| | ARMv8 CPU |
| | |
| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Raspberry Pi 4* |
| | - *Example: Intel Core 2 Duo E8200, AMD FX-4100, Raspberry Pi 4* |
+----------------------+-----------------------------------------------------------------------------------------+
| **GPU** | - **Forward+ renderer:** Integrated graphics with full Vulkan 1.0 support |
| | |
@@ -62,9 +63,14 @@ Desktop or laptop PC - Minimum
.. note::
Vulkan drivers for these Windows versions are known to have issues with
memory leaks. As a result, it's recommended to stick to the Compatibility
renderer when running Godot on a Windows version older than 10.
If your x86_64 CPU does not support SSE4.2, you can still run the 32-bit Godot
executable which only has a SSE2 requirement (all x86_64 CPUs support SSE2).
While supported on Linux, we have no official minimum requirements for running on
rv64 (RISC-V), ppc64 & ppc32 (PowerPC), and loongarch64. In addition you must
compile the editor for that platform (as well as export templates) yourself,
no official downloads are currently provided. RISC-V compiling instructions can
be found on the :ref:`doc_compiling_for_linuxbsd` page.
Mobile device (smartphone/tablet) - Minimum
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -107,7 +113,7 @@ Desktop or laptop PC - Recommended
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------+---------------------------------------------------------------------------------------------+
| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more, ARMv8 CPU|
| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 support, with 4 physical cores or more, ARMv8 CPU |
| | |
| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Snapdragon X Elite* |
| | |
@@ -115,7 +121,7 @@ Desktop or laptop PC - Recommended
| | |
| | - *Example: Intel Core i5-8500, Apple M1* |
| | |
| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU |
| | - **Linux:** x86_64 CPU with SSE4.2 support, ARMv7 or ARMv8 CPU |
| | |
| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* |
+----------------------+---------------------------------------------------------------------------------------------+
@@ -202,17 +208,19 @@ Desktop or laptop PC - Minimum
.. which can run up to macOS 10.13.
+----------------------+-----------------------------------------------------------------------------------------+
| **CPU** | - **Windows:** x86_32 CPU with SSE2 instructions, any x86_64 CPU, ARMv8 CPU |
| **CPU** | - **Windows:** x86_32 CPU with SSE2 support, x86_64 CPU with SSE4.2 support, |
| | ARMv8 CPU |
| | |
| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Snapdragon X Elite* |
| | - *Example: Intel Core 2 Duo E8200, AMD FX-4100, Snapdragon X Elite* |
| | |
| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) |
| | |
| | - *Example: Intel Core 2 Duo SU9400, Apple M1* |
| | |
| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU |
| | - **Linux:** x86_32 CPU with SSE2 support, x86_64 CPU with SSE4.2 support, |
| | ARMv7 or ARMv8 CPU |
| | |
| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Raspberry Pi 4* |
| | - *Example: Intel Core 2 Duo E8200, AMD FX-4100, Raspberry Pi 4* |
+----------------------+-----------------------------------------------------------------------------------------+
| **GPU** | - **Forward+ renderer:** Integrated graphics with full Vulkan 1.0 support, |
| | Metal 3 support (macOS) or Direct3D 12 (12_0 feature level) support (Windows) |
@@ -241,12 +249,6 @@ Desktop or laptop PC - Minimum
| | (including ESR), Chrome and Chromium derivatives, Safari and WebKit derivatives. |
+----------------------+-----------------------------------------------------------------------------------------+
.. note::
Vulkan drivers for these Windows versions are known to have issues with
memory leaks. As a result, it's recommended to stick to the Compatibility
renderer when running Godot on a Windows version older than 10.
Mobile device (smartphone/tablet) - Minimum
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -293,7 +295,7 @@ Desktop or laptop PC - Recommended
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------+----------------------------------------------------------------------------------------------+
| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more, ARMv8 CPU |
| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 support, with 4 physical cores or more, ARMv8 CPU |
| | |
| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Snapdragon X Elite* |
| | |
@@ -301,7 +303,8 @@ Desktop or laptop PC - Recommended
| | |
| | - *Example: Intel Core i5-8500, Apple M1* |
| | |
| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU |
| | - **Linux:** x86_64 CPU with SSE4.2 support, with 4 physical cores or more, |
| | ARMv7 or ARMv8 CPU |
| | |
| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* |
+----------------------+----------------------------------------------------------------------------------------------+

2
classes/class_animationmixer.rst
View File

@@ -169,6 +169,8 @@ Notifies when an animation list is changed.
Notifies when an animation starts playing.
\ **Note:** This signal is not emitted if an animation is looping.
.. rst-class:: classref-item-separator
----

6
classes/class_displayserver.rst
View File

@@ -2128,7 +2128,9 @@ The window background can be transparent.
\ **Note:** This flag has no effect if :ref:`is_window_transparency_available()<class_DisplayServer_method_is_window_transparency_available>` returns ``false``.
\ **Note:** Transparency support is implemented on Android, Linux (X11/Wayland), macOS, and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities.
\ **Note:** Transparency support is implemented on Linux (X11/Wayland), macOS, and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities.
\ **Note:** Transparency support is implemented on Android, but can only be enabled via :ref:`ProjectSettings.display/window/per_pixel_transparency/allowed<class_ProjectSettings_property_display/window/per_pixel_transparency/allowed>`. This flag has no effect on Android.
.. _class_DisplayServer_constant_WINDOW_FLAG_NO_FOCUS:
@@ -5987,6 +5989,8 @@ Unregisters an :ref:`Object<class_Object>` representing an additional output, th
Returns the on-screen keyboard's height in pixels. Returns 0 if there is no keyboard or if it is currently hidden.
\ **Note:** On Android 7 and 8, the keyboard height may return 0 the first time the keyboard is opened in non-immersive mode. This behavior does not occur in immersive mode.
.. rst-class:: classref-item-separator
----

4
classes/class_editorexportplatformextension.rst
View File

@@ -62,7 +62,7 @@ Methods
+------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`_get_name<class_EditorExportPlatformExtension_private_method__get_name>`\ (\ ) |virtual| |required| |const| |
+------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`ImageTexture<class_ImageTexture>` | :ref:`_get_option_icon<class_EditorExportPlatformExtension_private_method__get_option_icon>`\ (\ device\: :ref:`int<class_int>`\ ) |virtual| |const| |
| :ref:`Texture2D<class_Texture2D>` | :ref:`_get_option_icon<class_EditorExportPlatformExtension_private_method__get_option_icon>`\ (\ device\: :ref:`int<class_int>`\ ) |virtual| |const| |
+------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`_get_option_label<class_EditorExportPlatformExtension_private_method__get_option_label>`\ (\ device\: :ref:`int<class_int>`\ ) |virtual| |const| |
+------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -330,7 +330,7 @@ Returns export platform name.
.. rst-class:: classref-method
:ref:`ImageTexture<class_ImageTexture>` **_get_option_icon**\ (\ device\: :ref:`int<class_int>`\ ) |virtual| |const| :ref:`🔗<class_EditorExportPlatformExtension_private_method__get_option_icon>`
:ref:`Texture2D<class_Texture2D>` **_get_option_icon**\ (\ device\: :ref:`int<class_int>`\ ) |virtual| |const| :ref:`🔗<class_EditorExportPlatformExtension_private_method__get_option_icon>`
Returns the item icon for the specified ``device`` in the one-click deploy menu. The icon should be 16×16 pixels, adjusted for the current editor scale (see :ref:`EditorInterface.get_editor_scale()<class_EditorInterface_method_get_editor_scale>`).

38
classes/class_editorexportplatformweb.rst
View File

@@ -75,12 +75,12 @@ Properties
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`progressive_web_app/orientation<class_EditorExportPlatformWeb_property_progressive_web_app/orientation>` |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`variant/emscripten_pool_size<class_EditorExportPlatformWeb_property_variant/emscripten_pool_size>` |
| :ref:`int<class_int>` | :ref:`threads/emscripten_pool_size<class_EditorExportPlatformWeb_property_threads/emscripten_pool_size>` |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`threads/godot_pool_size<class_EditorExportPlatformWeb_property_threads/godot_pool_size>` |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`variant/extensions_support<class_EditorExportPlatformWeb_property_variant/extensions_support>` |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`variant/godot_pool_size<class_EditorExportPlatformWeb_property_variant/godot_pool_size>` |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`variant/thread_support<class_EditorExportPlatformWeb_property_variant/thread_support>` |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`vram_texture_compression/for_desktop<class_EditorExportPlatformWeb_property_vram_texture_compression/for_desktop>` |
@@ -335,11 +335,11 @@ The orientation to use when the web application is run through a mobile device.
----
.. _class_EditorExportPlatformWeb_property_variant/emscripten_pool_size:
.. _class_EditorExportPlatformWeb_property_threads/emscripten_pool_size:
.. rst-class:: classref-property
:ref:`int<class_int>` **variant/emscripten_pool_size** :ref:`🔗<class_EditorExportPlatformWeb_property_variant/emscripten_pool_size>`
:ref:`int<class_int>` **threads/emscripten_pool_size** :ref:`🔗<class_EditorExportPlatformWeb_property_threads/emscripten_pool_size>`
The number of threads that emscripten will allocate at startup. A smaller value will allocate fewer threads and consume fewer system resources, but you may run the risk of running out of threads in the pool and needing to allocate more threads at run time which may cause a deadlock.
@@ -349,6 +349,20 @@ The number of threads that emscripten will allocate at startup. A smaller value
----
.. _class_EditorExportPlatformWeb_property_threads/godot_pool_size:
.. rst-class:: classref-property
:ref:`int<class_int>` **threads/godot_pool_size** :ref:`🔗<class_EditorExportPlatformWeb_property_threads/godot_pool_size>`
Override for the default size of the :ref:`WorkerThreadPool<class_WorkerThreadPool>`. This setting is used when :ref:`ProjectSettings.threading/worker_pool/max_threads<class_ProjectSettings_property_threading/worker_pool/max_threads>` size is set to -1 (which it is by default). This size must be smaller than :ref:`threads/emscripten_pool_size<class_EditorExportPlatformWeb_property_threads/emscripten_pool_size>` otherwise deadlocks may occur.
When using threads this size needs to be large enough to accommodate features that rely on having a dedicated thread like :ref:`ProjectSettings.physics/2d/run_on_separate_thread<class_ProjectSettings_property_physics/2d/run_on_separate_thread>` or :ref:`ProjectSettings.rendering/driver/threads/thread_model<class_ProjectSettings_property_rendering/driver/threads/thread_model>`. In general, it is best to ensure that this is at least 4 and is at least 2 or 3 less than :ref:`threads/emscripten_pool_size<class_EditorExportPlatformWeb_property_threads/emscripten_pool_size>`.
.. rst-class:: classref-item-separator
----
.. _class_EditorExportPlatformWeb_property_variant/extensions_support:
.. rst-class:: classref-property
@@ -361,20 +375,6 @@ If ``true`` enables :ref:`GDExtension<class_GDExtension>` support for this web b
----
.. _class_EditorExportPlatformWeb_property_variant/godot_pool_size:
.. rst-class:: classref-property
:ref:`int<class_int>` **variant/godot_pool_size** :ref:`🔗<class_EditorExportPlatformWeb_property_variant/godot_pool_size>`
Override for the default size of the :ref:`WorkerThreadPool<class_WorkerThreadPool>`. This setting is used when :ref:`ProjectSettings.threading/worker_pool/max_threads<class_ProjectSettings_property_threading/worker_pool/max_threads>` size is set to -1 (which it is by default). This size must be smaller than :ref:`variant/emscripten_pool_size<class_EditorExportPlatformWeb_property_variant/emscripten_pool_size>` otherwise deadlocks may occur.
When using threads this size needs to be large enough to accommodate features that rely on having a dedicated thread like :ref:`ProjectSettings.physics/2d/run_on_separate_thread<class_ProjectSettings_property_physics/2d/run_on_separate_thread>` or :ref:`ProjectSettings.rendering/driver/threads/thread_model<class_ProjectSettings_property_rendering/driver/threads/thread_model>`. In general, it is best to ensure that this is at least 4 and is at least 2 or 3 less than :ref:`variant/emscripten_pool_size<class_EditorExportPlatformWeb_property_variant/emscripten_pool_size>`.
.. rst-class:: classref-item-separator
----
.. _class_EditorExportPlatformWeb_property_variant/thread_support:
.. rst-class:: classref-property

8
classes/class_editorimportplugin.rst
View File

@@ -272,19 +272,19 @@ Gets whether the import option specified by ``option_name`` should be visible in
.. code-tab:: gdscript
func _get_option_visibility(option, options):
func _get_option_visibility(path, option_name, options):
# Only show the lossy quality setting if the compression mode is set to "Lossy".
if option == "compress/lossy_quality" and options.has("compress/mode"):
if option_name == "compress/lossy_quality" and options.has("compress/mode"):
return int(options["compress/mode"]) == COMPRESS_LOSSY # This is a constant that you set
return true
.. code-tab:: csharp
public void _GetOptionVisibility(string option, Godot.Collections.Dictionary options)
public override bool _GetOptionVisibility(string path, StringName optionName, Godot.Collections.Dictionary options)
{
// Only show the lossy quality setting if the compression mode is set to "Lossy".
if (option == "compress/lossy_quality" && options.ContainsKey("compress/mode"))
if (optionName == "compress/lossy_quality" && options.ContainsKey("compress/mode"))
{
return (int)options["compress/mode"] == CompressLossy; // This is a constant you set
}

192
classes/class_editorsettings.rst
View File

@@ -833,6 +833,18 @@ Properties
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/comment_color<class_EditorSettings_property_text_editor/theme/highlighting/comment_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/comment_markers/critical_color<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/critical_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`text_editor/theme/highlighting/comment_markers/critical_list<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/critical_list>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/comment_markers/notice_color<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/notice_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`text_editor/theme/highlighting/comment_markers/notice_list<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/notice_list>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/comment_markers/warning_color<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/warning_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`text_editor/theme/highlighting/comment_markers/warning_list<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/warning_list>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/completion_background_color<class_EditorSettings_property_text_editor/theme/highlighting/completion_background_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/completion_existing_color<class_EditorSettings_property_text_editor/theme/highlighting/completion_existing_color>` |
@@ -859,6 +871,18 @@ Properties
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/function_color<class_EditorSettings_property_text_editor/theme/highlighting/function_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/gdscript/annotation_color<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/annotation_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/gdscript/function_definition_color<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/function_definition_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/gdscript/global_function_color<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/global_function_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/gdscript/node_path_color<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/node_path_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/gdscript/node_reference_color<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/node_reference_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/gdscript/string_name_color<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/string_name_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/keyword_color<class_EditorSettings_property_text_editor/theme/highlighting/keyword_color>` |
+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Color<class_Color>` | :ref:`text_editor/theme/highlighting/line_length_guideline_color<class_EditorSettings_property_text_editor/theme/highlighting/line_length_guideline_color>` |
@@ -4010,7 +4034,9 @@ If ``true``, the Scene dock will display buttons to quickly add a root node to a
:ref:`bool<class_bool>` **interface/inspector/auto_unfold_foreign_scenes** :ref:`🔗<class_EditorSettings_property_interface/inspector/auto_unfold_foreign_scenes>`
If ``true``, automatically expands property groups in the Inspector dock when opening a scene that hasn't been opened previously. If ``false``, all groups remain collapsed by default.
If ``true``, automatically unfolds Inspector property groups containing modified values when opening a scene for the first time. Only affects scenes without saved folding preferences and only unfolds groups with properties that have been changed from their default values.
\ **Note:** This setting only works in specific scenarios: when opening a scene brought in from another project, or when opening a new scene that already has modified properties (e.g., from version control). Duplicated scenes are not considered foreign, so this setting will not affect them.
.. rst-class:: classref-item-separator
@@ -4622,6 +4648,8 @@ All update modes will ignore builds with different major versions (e.g. Godot 4
Determines whether online features are enabled in the editor, such as the Asset Library or update checks. Disabling these online features helps alleviate privacy concerns by preventing the editor from making HTTP requests to the Godot website or third-party platforms hosting assets from the Asset Library.
Editor plugins and tool scripts are recommended to follow this setting. However, Godot can't prevent them from violating this rule.
.. rst-class:: classref-item-separator
----
@@ -5492,7 +5520,15 @@ If ``true``, uses :ref:`StringName<class_StringName>` instead of :ref:`String<cl
:ref:`bool<class_bool>` **text_editor/completion/add_type_hints** :ref:`🔗<class_EditorSettings_property_text_editor/completion/add_type_hints>`
If ``true``, adds :doc:`GDScript static typing <../tutorials/scripting/gdscript/static_typing>` hints such as ``-> void`` and ``: int`` when using code autocompletion or when creating onready variables by drag and dropping nodes into the script editor while pressing the :kbd:`Ctrl` key. If ``true``, newly created scripts will also automatically have type hints added to their method parameters and return types.
If ``true``, automatically adds :doc:`GDScript static typing <../tutorials/scripting/gdscript/static_typing>` (such as ``-> void`` and ``: int``) in many situations where it's possible to, including when:
- Accepting a suggestion from code autocompletion;
- Creating a new script from a template;
- Connecting signals from the Node dock;
- Creating variables prefixed with :ref:`@GDScript.@onready<class_@GDScript_annotation_@onready>`, by dropping nodes from the Scene dock into the script editor while holding :kbd:`Ctrl`.
.. rst-class:: classref-item-separator
@@ -5940,6 +5976,84 @@ The script editor's comment color.
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/critical_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/comment_markers/critical_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/critical_color>`
The script editor's critical comment marker text color. These markers are determined by :ref:`text_editor/theme/highlighting/comment_markers/critical_list<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/critical_list>`.
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/critical_list:
.. rst-class:: classref-property
:ref:`String<class_String>` **text_editor/theme/highlighting/comment_markers/critical_list** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/critical_list>`
A comma-separated list of case-sensitive words to highlight in comments. The text will be highlighted in the script editor with the :ref:`text_editor/theme/highlighting/comment_markers/critical_color<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/critical_color>` color. These must not include spaces or symbols or they will not be highlighted.
\ **Note:** This is only implemented in the GDScript syntax highlighter.
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/notice_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/comment_markers/notice_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/notice_color>`
The script editor's notice comment marker text color. These markers are determined by :ref:`text_editor/theme/highlighting/comment_markers/notice_list<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/notice_list>`.
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/notice_list:
.. rst-class:: classref-property
:ref:`String<class_String>` **text_editor/theme/highlighting/comment_markers/notice_list** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/notice_list>`
A comma-separated list of case-sensitive words to highlight in comments. The text will be highlighted in the script editor with the :ref:`text_editor/theme/highlighting/comment_markers/notice_color<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/notice_color>` color. These must not include spaces or symbols or they will not be highlighted.
\ **Note:** This is only implemented in the GDScript syntax highlighter.
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/warning_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/comment_markers/warning_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/warning_color>`
The script editor's warning comment marker text color. These markers are determined by :ref:`text_editor/theme/highlighting/comment_markers/warning_list<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/warning_list>`.
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/warning_list:
.. rst-class:: classref-property
:ref:`String<class_String>` **text_editor/theme/highlighting/comment_markers/warning_list** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/warning_list>`
A comma-separated list of case-sensitive words to highlight in comments. The text will be highlighted in the script editor with the :ref:`text_editor/theme/highlighting/comment_markers/warning_color<class_EditorSettings_property_text_editor/theme/highlighting/comment_markers/warning_color>` color. These must not include spaces or symbols or they will not be highlighted.
\ **Note:** This is only implemented in the GDScript syntax highlighter.
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/completion_background_color:
.. rst-class:: classref-property
@@ -6092,7 +6206,79 @@ The script editor's background line highlighting color for folded code region.
The script editor's function call color.
\ **Note:** When using the GDScript syntax highlighter, this is replaced by the function definition color configured in the syntax theme for function definitions (e.g. ``func _ready():``).
\ **Note:** When using the GDScript syntax highlighter, this is only used when calling some functions since function definitions and global functions have their own colors :ref:`text_editor/theme/highlighting/gdscript/function_definition_color<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/function_definition_color>` and :ref:`text_editor/theme/highlighting/gdscript/global_function_color<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/global_function_color>`.
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/gdscript/annotation_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/gdscript/annotation_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/annotation_color>`
The GDScript syntax highlighter text color for annotations (e.g. ``@export``).
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/gdscript/function_definition_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/gdscript/function_definition_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/function_definition_color>`
The GDScript syntax highlighter text color for function definitions (e.g. the ``_ready`` in ``func _ready():``).
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/gdscript/global_function_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/gdscript/global_function_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/global_function_color>`
The GDScript syntax highlighter text color for global functions, such as the ones in :ref:`@GlobalScope<class_@GlobalScope>` (e.g. ``preload()``).
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/gdscript/node_path_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/gdscript/node_path_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/node_path_color>`
The GDScript syntax highlighter text color for :ref:`NodePath<class_NodePath>` literals (e.g. ``^"position:x"``).
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/gdscript/node_reference_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/gdscript/node_reference_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/node_reference_color>`
The GDScript syntax highlighter text color for node reference literals (e.g. ``$"Sprite"`` and ``%"Sprite"``]).
.. rst-class:: classref-item-separator
----
.. _class_EditorSettings_property_text_editor/theme/highlighting/gdscript/string_name_color:
.. rst-class:: classref-property
:ref:`Color<class_Color>` **text_editor/theme/highlighting/gdscript/string_name_color** :ref:`🔗<class_EditorSettings_property_text_editor/theme/highlighting/gdscript/string_name_color>`
The GDScript syntax highlighter text color for :ref:`StringName<class_StringName>` literals (e.g. ``>"example"``).
.. rst-class:: classref-item-separator

28
classes/class_fileaccess.rst
View File

@@ -1104,7 +1104,7 @@ Sets file UNIX permissions.
:ref:`bool<class_bool>` **store_8**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_8>`
Stores an integer as 8 bits in the file. This advances the file cursor by 1 byte.
Stores an integer as 8 bits in the file. This advances the file cursor by 1 byte. Returns ``true`` if the operation is successful.
\ **Note:** The ``value`` should lie in the interval ``[0, 255]``. Any other value will overflow and wrap around.
@@ -1122,7 +1122,7 @@ To store a signed integer, use :ref:`store_64()<class_FileAccess_method_store_64
:ref:`bool<class_bool>` **store_16**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_16>`
Stores an integer as 16 bits in the file. This advances the file cursor by 2 bytes.
Stores an integer as 16 bits in the file. This advances the file cursor by 2 bytes. Returns ``true`` if the operation is successful.
\ **Note:** The ``value`` should lie in the interval ``[0, 2^16 - 1]``. Any other value will overflow and wrap around.
@@ -1177,7 +1177,7 @@ To store a signed integer, use :ref:`store_64()<class_FileAccess_method_store_64
:ref:`bool<class_bool>` **store_32**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_32>`
Stores an integer as 32 bits in the file. This advances the file cursor by 4 bytes.
Stores an integer as 32 bits in the file. This advances the file cursor by 4 bytes. Returns ``true`` if the operation is successful.
\ **Note:** The ``value`` should lie in the interval ``[0, 2^32 - 1]``. Any other value will overflow and wrap around.
@@ -1195,7 +1195,7 @@ To store a signed integer, use :ref:`store_64()<class_FileAccess_method_store_64
:ref:`bool<class_bool>` **store_64**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_64>`
Stores an integer as 64 bits in the file. This advances the file cursor by 8 bytes.
Stores an integer as 64 bits in the file. This advances the file cursor by 8 bytes. Returns ``true`` if the operation is successful.
\ **Note:** The ``value`` must lie in the interval ``[-2^63, 2^63 - 1]`` (i.e. be a valid :ref:`int<class_int>` value).
@@ -1211,7 +1211,7 @@ Stores an integer as 64 bits in the file. This advances the file cursor by 8 byt
:ref:`bool<class_bool>` **store_buffer**\ (\ buffer\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) :ref:`🔗<class_FileAccess_method_store_buffer>`
Stores the given array of bytes in the file. This advances the file cursor by the number of bytes written.
Stores the given array of bytes in the file. This advances the file cursor by the number of bytes written. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
@@ -1227,7 +1227,7 @@ Stores the given array of bytes in the file. This advances the file cursor by th
Store the given :ref:`PackedStringArray<class_PackedStringArray>` in the file as a line formatted in the CSV (Comma-Separated Values) format. You can pass a different delimiter ``delim`` to use other than the default ``","`` (comma). This delimiter must be one-character long.
Text will be encoded as UTF-8.
Text will be encoded as UTF-8. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
@@ -1241,7 +1241,7 @@ Text will be encoded as UTF-8.
:ref:`bool<class_bool>` **store_double**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_double>`
Stores a floating-point number as 64 bits in the file. This advances the file cursor by 8 bytes.
Stores a floating-point number as 64 bits in the file. This advances the file cursor by 8 bytes. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
@@ -1255,7 +1255,7 @@ Stores a floating-point number as 64 bits in the file. This advances the file cu
:ref:`bool<class_bool>` **store_float**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_float>`
Stores a floating-point number as 32 bits in the file. This advances the file cursor by 4 bytes.
Stores a floating-point number as 32 bits in the file. This advances the file cursor by 4 bytes. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
@@ -1269,7 +1269,7 @@ Stores a floating-point number as 32 bits in the file. This advances the file cu
:ref:`bool<class_bool>` **store_half**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_half>`
Stores a half-precision floating-point number as 16 bits in the file. This advances the file cursor by 2 bytes.
Stores a half-precision floating-point number as 16 bits in the file. This advances the file cursor by 2 bytes. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
@@ -1283,7 +1283,7 @@ Stores a half-precision floating-point number as 16 bits in the file. This advan
:ref:`bool<class_bool>` **store_line**\ (\ line\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_line>`
Stores ``line`` in the file followed by a newline character (``\n``), encoding the text as UTF-8. This advances the file cursor by the length of the line, after the newline character. The amount of bytes written depends on the UTF-8 encoded bytes, which may be different from :ref:`String.length()<class_String_method_length>` which counts the number of UTF-32 codepoints.
Stores ``line`` in the file followed by a newline character (``\n``), encoding the text as UTF-8. This advances the file cursor by the length of the line, after the newline character. The amount of bytes written depends on the UTF-8 encoded bytes, which may be different from :ref:`String.length()<class_String_method_length>` which counts the number of UTF-32 codepoints. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
@@ -1297,7 +1297,7 @@ Stores ``line`` in the file followed by a newline character (``\n``), encoding t
:ref:`bool<class_bool>` **store_pascal_string**\ (\ string\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_pascal_string>`
Stores the given :ref:`String<class_String>` as a line in the file in Pascal format (i.e. also store the length of the string). Text will be encoded as UTF-8. This advances the file cursor by the number of bytes written depending on the UTF-8 encoded bytes, which may be different from :ref:`String.length()<class_String_method_length>` which counts the number of UTF-32 codepoints.
Stores the given :ref:`String<class_String>` as a line in the file in Pascal format (i.e. also store the length of the string). Text will be encoded as UTF-8. This advances the file cursor by the number of bytes written depending on the UTF-8 encoded bytes, which may be different from :ref:`String.length()<class_String_method_length>` which counts the number of UTF-32 codepoints. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
@@ -1313,7 +1313,7 @@ Stores the given :ref:`String<class_String>` as a line in the file in Pascal for
Stores a floating-point number in the file. This advances the file cursor by either 4 or 8 bytes, depending on the precision used by the current Godot build.
If using a Godot build compiled with the ``precision=single`` option (the default), this method will save a 32-bit float. Otherwise, if compiled with the ``precision=double`` option, this will save a 64-bit float.
If using a Godot build compiled with the ``precision=single`` option (the default), this method will save a 32-bit float. Otherwise, if compiled with the ``precision=double`` option, this will save a 64-bit float. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
@@ -1327,7 +1327,7 @@ If using a Godot build compiled with the ``precision=single`` option (the defaul
:ref:`bool<class_bool>` **store_string**\ (\ string\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_string>`
Stores ``string`` in the file without a newline character (``\n``), encoding the text as UTF-8. This advances the file cursor by the length of the string in UTF-8 encoded bytes, which may be different from :ref:`String.length()<class_String_method_length>` which counts the number of UTF-32 codepoints.
Stores ``string`` in the file without a newline character (``\n``), encoding the text as UTF-8. This advances the file cursor by the length of the string in UTF-8 encoded bytes, which may be different from :ref:`String.length()<class_String_method_length>` which counts the number of UTF-32 codepoints. Returns ``true`` if the operation is successful.
\ **Note:** This method is intended to be used to write text files. The string is stored as a UTF-8 encoded buffer without string length or terminating zero, which means that it can't be loaded back easily. If you want to store a retrievable string in a binary file, consider using :ref:`store_pascal_string()<class_FileAccess_method_store_pascal_string>` instead. For retrieving strings from a text file, you can use ``get_buffer(length).get_string_from_utf8()`` (if you know the length) or :ref:`get_as_text()<class_FileAccess_method_get_as_text>`.
@@ -1343,7 +1343,7 @@ Stores ``string`` in the file without a newline character (``\n``), encoding the
:ref:`bool<class_bool>` **store_var**\ (\ value\: :ref:`Variant<class_Variant>`, full_objects\: :ref:`bool<class_bool>` = false\ ) :ref:`🔗<class_FileAccess_method_store_var>`
Stores any Variant value in the file. If ``full_objects`` is ``true``, encoding objects is allowed (and can potentially include code). This advances the file cursor by the number of bytes written.
Stores any Variant value in the file. If ``full_objects`` is ``true``, encoding objects is allowed (and can potentially include code). This advances the file cursor by the number of bytes written. Returns ``true`` if the operation is successful.
Internally, this uses the same encoding mechanism as the :ref:`@GlobalScope.var_to_bytes()<class_@GlobalScope_method_var_to_bytes>` method, as described in the :doc:`Binary serialization API <../tutorials/io/binary_serialization_api>` documentation.

21
classes/class_graphedit.rst
View File

@@ -1272,6 +1272,27 @@ A connection is represented as a :ref:`Dictionary<class_Dictionary>` in the form
keep_alive: bool
}
\ **Example:** Get all connections on a specific port:
::
func get_connection_list_from_port(node, port):
var connections = get_connection_list_from_node(node)
var result = []
for connection in connections:
var dict = {}
if connection["from_node"] == node and connection["from_port"] == port:
dict["node"] = connection["to_node"]
dict["port"] = connection["to_port"]
dict["type"] = "left"
result.push_back(dict)
elif connection["to_node"] == node and connection["to_port"] == port:
dict["node"] = connection["from_node"]
dict["port"] = connection["from_port"]
dict["type"] = "right"
result.push_back(dict)
return result
.. rst-class:: classref-item-separator
----

4
classes/class_httprequest.rst
View File

@@ -119,7 +119,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content
http_request.request_completed.connect(self._http_request_completed)
# Perform the HTTP request. The URL below returns a PNG image as of writing.
var error = http_request.request("https://placehold.co/512")
var error = http_request.request("https://placehold.co/512.png")
if error != OK:
push_error("An error occurred in the HTTP request.")
@@ -150,7 +150,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content
httpRequest.RequestCompleted += HttpRequestCompleted;
// Perform the HTTP request. The URL below returns a PNG image as of writing.
Error error = httpRequest.Request("https://placehold.co/512");
Error error = httpRequest.Request("https://placehold.co/512.png");
if (error != Error.Ok)
{
GD.PushError("An error occurred in the HTTP request.");

4
classes/class_navigationmesh.rst
View File

@@ -330,6 +330,8 @@ The distance to erode/shrink the walkable area of the heightfield away from obst
\ **Note:** While baking, this value will be rounded up to the nearest multiple of :ref:`cell_size<class_NavigationMesh_property_cell_size>`.
\ **Note:** The radius must be equal or higher than ``0.0``. If the radius is ``0.0``, it won't be possible to fix invalid outline overlaps and other precision errors during the baking process. As a result, some obstacles may be excluded incorrectly from the final navigation mesh, or may delete the navigation mesh's polygons.
.. rst-class:: classref-item-separator
----
@@ -349,7 +351,7 @@ The size of the non-navigable border around the bake bounding area.
In conjunction with the :ref:`filter_baking_aabb<class_NavigationMesh_property_filter_baking_aabb>` and a :ref:`edge_max_error<class_NavigationMesh_property_edge_max_error>` value at ``1.0`` or below the border size can be used to bake tile aligned navigation meshes without the tile edges being shrunk by :ref:`agent_radius<class_NavigationMesh_property_agent_radius>`.
\ **Note:** While baking and not zero, this value will be rounded up to the nearest multiple of :ref:`cell_size<class_NavigationMesh_property_cell_size>`.
\ **Note:** If this value is not ``0.0``, it will be rounded up to the nearest multiple of :ref:`cell_size<class_NavigationMesh_property_cell_size>` during baking.
.. rst-class:: classref-item-separator

2
classes/class_navigationpolygon.rst
View File

@@ -303,6 +303,8 @@ Property Descriptions
The distance to erode/shrink the walkable surface when baking the navigation mesh.
\ **Note:** The radius must be equal or higher than ``0.0``. If the radius is ``0.0``, it won't be possible to fix invalid outline overlaps and other precision errors during the baking process. As a result, some obstacles may be excluded incorrectly from the final navigation mesh, or may delete the navigation mesh's polygons.
.. rst-class:: classref-item-separator
----

6
classes/class_projectsettings.rst
View File

@@ -3430,8 +3430,6 @@ Editor-only override for :ref:`debug/settings/crash_handler/message<class_Projec
Whether GDScript call stacks will be tracked in release builds, thus allowing :ref:`Engine.capture_script_backtraces()<class_Engine_method_capture_script_backtraces>` to function.
Enabling this comes at the cost of roughly 40 KiB for every thread that runs any GDScript code.
\ **Note:** This setting has no effect on editor builds or debug builds, where GDScript call stacks are tracked regardless.
.. rst-class:: classref-item-separator
@@ -4796,6 +4794,8 @@ If ``true``, enables a window manager hint that the main window background *can*
\ **Note:** This setting has no effect if :ref:`display/window/per_pixel_transparency/allowed<class_ProjectSettings_property_display/window/per_pixel_transparency/allowed>` is set to ``false``.
\ **Note:** This setting has no effect on Android as transparency is controlled only via :ref:`display/window/per_pixel_transparency/allowed<class_ProjectSettings_property_display/window/per_pixel_transparency/allowed>`.
.. rst-class:: classref-item-separator
----
@@ -11176,7 +11176,7 @@ Sets the sensitivity to edges when using SMAA for antialiasing. Lower values wil
:ref:`bool<class_bool>` **rendering/anti_aliasing/quality/use_debanding** = ``false`` :ref:`🔗<class_ProjectSettings_property_rendering/anti_aliasing/quality/use_debanding>`
If ``true``, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode<class_Environment_property_background_mode>` is :ref:`Environment.BG_CANVAS<class_Environment_constant_BG_CANVAS>`.
If ``true``, uses a fast post-processing filter to make banding significantly less visible. If :ref:`rendering/viewport/hdr_2d<class_ProjectSettings_property_rendering/viewport/hdr_2d>` is ``false``, 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode<class_Environment_property_background_mode>` is :ref:`Environment.BG_CANVAS<class_Environment_constant_BG_CANVAS>`. If :ref:`rendering/viewport/hdr_2d<class_ProjectSettings_property_rendering/viewport/hdr_2d>` is ``true``, debanding will affect all 2D and 3D rendering, including canvas items.
In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.

8
classes/class_renderingdevice.rst
View File

@@ -4460,6 +4460,14 @@ Support for MetalFX temporal upscaling.
Features support for buffer device address extension.
.. _class_RenderingDevice_constant_SUPPORTS_IMAGE_ATOMIC_32_BIT:
.. rst-class:: classref-enumeration-constant
:ref:`Features<enum_RenderingDevice_Features>` **SUPPORTS_IMAGE_ATOMIC_32_BIT** = ``7``
Support for 32-bit image atomic operations.
.. rst-class:: classref-item-separator
----

2
classes/class_renderingserver.rst
View File

@@ -12475,7 +12475,7 @@ Sets when the viewport should be updated.
|void| **viewport_set_use_debanding**\ (\ viewport\: :ref:`RID<class_RID>`, enable\: :ref:`bool<class_bool>`\ ) :ref:`🔗<class_RenderingServer_method_viewport_set_use_debanding>`
If ``true``, enables debanding on the specified viewport. Equivalent to :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_debanding<class_ProjectSettings_property_rendering/anti_aliasing/quality/use_debanding>` or :ref:`Viewport.use_debanding<class_Viewport_property_use_debanding>`.
Equivalent to :ref:`Viewport.use_debanding<class_Viewport_property_use_debanding>`. See also :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_debanding<class_ProjectSettings_property_rendering/anti_aliasing/quality/use_debanding>`.
.. rst-class:: classref-item-separator

14
classes/class_resource.rst
View File

@@ -284,7 +284,7 @@ Override this method to return a custom :ref:`RID<class_RID>` when :ref:`get_rid
|void| **_reset_state**\ (\ ) |virtual| :ref:`🔗<class_Resource_private_method__reset_state>`
For resources that use a variable number of properties, either via :ref:`Object._validate_property()<class_Object_private_method__validate_property>` or :ref:`Object._get_property_list()<class_Object_private_method__get_property_list>`, this method should be implemented to correctly clear the resource's state.
For resources that store state in non-exported properties, such as via :ref:`Object._validate_property()<class_Object_private_method__validate_property>` or :ref:`Object._get_property_list()<class_Object_private_method__get_property_list>`, this method must be implemented to clear them.
.. rst-class:: classref-item-separator
@@ -296,7 +296,7 @@ For resources that use a variable number of properties, either via :ref:`Object.
|void| **_set_path_cache**\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| :ref:`🔗<class_Resource_private_method__set_path_cache>`
Sets the resource's path to ``path`` without involving the resource cache.
Override this method to execute additional logic after :ref:`set_path_cache()<class_Resource_method_set_path_cache>` is called on this object.
.. rst-class:: classref-item-separator
@@ -405,7 +405,7 @@ Generates a unique identifier for a resource to be contained inside a :ref:`Pack
:ref:`String<class_String>` **get_id_for_path**\ (\ path\: :ref:`String<class_String>`\ ) |const| :ref:`🔗<class_Resource_method_get_id_for_path>`
Returns the unique identifier for the resource with the given ``path`` from the resource cache. If the resource is not loaded and cached, an empty string is returned.
From the internal cache for scene-unique IDs, returns the ID of this resource for the scene at ``path``. If there is no entry, an empty string is returned. Useful to keep scene-unique IDs the same when implementing a VCS-friendly custom resource format by extending :ref:`ResourceFormatLoader<class_ResourceFormatLoader>` and :ref:`ResourceFormatSaver<class_ResourceFormatSaver>`.
\ **Note:** This method is only implemented when running in an editor context. At runtime, it returns an empty string.
@@ -443,7 +443,7 @@ Returns the :ref:`RID<class_RID>` of this resource (or an empty RID). Many resou
:ref:`bool<class_bool>` **is_built_in**\ (\ ) |const| :ref:`🔗<class_Resource_method_is_built_in>`
Returns ``true`` if the resource is built-in (from the engine) or ``false`` if it is user-defined.
Returns ``true`` if the resource is saved on disk as a part of another resource's file.
.. rst-class:: classref-item-separator
@@ -455,7 +455,7 @@ Returns ``true`` if the resource is built-in (from the engine) or ``false`` if i
|void| **reset_state**\ (\ ) :ref:`🔗<class_Resource_method_reset_state>`
For resources that use a variable number of properties, either via :ref:`Object._validate_property()<class_Object_private_method__validate_property>` or :ref:`Object._get_property_list()<class_Object_private_method__get_property_list>`, override :ref:`_reset_state()<class_Resource_private_method__reset_state>` to correctly clear the resource's state.
Makes the resource clear its non-exported properties. See also :ref:`_reset_state()<class_Resource_private_method__reset_state>`. Useful when implementing a custom resource format by extending :ref:`ResourceFormatLoader<class_ResourceFormatLoader>` and :ref:`ResourceFormatSaver<class_ResourceFormatSaver>`.
.. rst-class:: classref-item-separator
@@ -467,7 +467,7 @@ For resources that use a variable number of properties, either via :ref:`Object.
|void| **set_id_for_path**\ (\ path\: :ref:`String<class_String>`, id\: :ref:`String<class_String>`\ ) :ref:`🔗<class_Resource_method_set_id_for_path>`
Sets the unique identifier to ``id`` for the resource with the given ``path`` in the resource cache. If the unique identifier is empty, the cache entry using ``path`` is removed if it exists.
In the internal cache for scene-unique IDs, sets the ID of this resource to ``id`` for the scene at ``path``. If ``id`` is empty, the cache entry for ``path`` is cleared. Useful to keep scene-unique IDs the same when implementing a VCS-friendly custom resource format by extending :ref:`ResourceFormatLoader<class_ResourceFormatLoader>` and :ref:`ResourceFormatSaver<class_ResourceFormatSaver>`.
\ **Note:** This method is only implemented when running in an editor context.
@@ -481,7 +481,7 @@ Sets the unique identifier to ``id`` for the resource with the given ``path`` in
|void| **set_path_cache**\ (\ path\: :ref:`String<class_String>`\ ) :ref:`🔗<class_Resource_method_set_path_cache>`
Sets the resource's path to ``path`` without involving the resource cache.
Sets the resource's path to ``path`` without involving the resource cache. Useful for handling :ref:`CacheMode<enum_ResourceFormatLoader_CacheMode>` values when implementing a custom resource format by extending :ref:`ResourceFormatLoader<class_ResourceFormatLoader>` and :ref:`ResourceFormatSaver<class_ResourceFormatSaver>`.
.. rst-class:: classref-item-separator

74
classes/class_richtextlabel.rst
View File

@@ -87,6 +87,8 @@ Properties
+-----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`scroll_following<class_RichTextLabel_property_scroll_following>` | ``false`` |
+-----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`scroll_following_visible_characters<class_RichTextLabel_property_scroll_following_visible_characters>` | ``false`` |
+-----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`selection_enabled<class_RichTextLabel_property_selection_enabled>` | ``false`` |
+-----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`shortcut_keys_enabled<class_RichTextLabel_property_shortcut_keys_enabled>` | ``true`` |
@@ -173,6 +175,8 @@ Methods
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`VScrollBar<class_VScrollBar>` | :ref:`get_v_scroll_bar<class_RichTextLabel_method_get_v_scroll_bar>`\ (\ ) |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Rect2i<class_Rect2i>` | :ref:`get_visible_content_rect<class_RichTextLabel_method_get_visible_content_rect>`\ (\ ) |const| |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_visible_line_count<class_RichTextLabel_method_get_visible_line_count>`\ (\ ) |const| |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_visible_paragraph_count<class_RichTextLabel_method_get_visible_paragraph_count>`\ (\ ) |const| |
@@ -900,6 +904,23 @@ If ``true``, the window scrolls down to display new content automatically.
----
.. _class_RichTextLabel_property_scroll_following_visible_characters:
.. rst-class:: classref-property
:ref:`bool<class_bool>` **scroll_following_visible_characters** = ``false`` :ref:`🔗<class_RichTextLabel_property_scroll_following_visible_characters>`
.. rst-class:: classref-property-setget
- |void| **set_scroll_follow_visible_characters**\ (\ value\: :ref:`bool<class_bool>`\ )
- :ref:`bool<class_bool>` **is_scroll_following_visible_characters**\ (\ )
If ``true``, the window scrolls to display the last visible line when :ref:`visible_characters<class_RichTextLabel_property_visible_characters>` or :ref:`visible_ratio<class_RichTextLabel_property_visible_ratio>` is changed.
.. rst-class:: classref-item-separator
----
.. _class_RichTextLabel_property_selection_enabled:
.. rst-class:: classref-property
@@ -1264,6 +1285,8 @@ Returns the paragraph number of the character position provided. Paragraph and c
Returns the height of the content.
\ **Note:** This method always returns the full content size, and is not affected by :ref:`visible_ratio<class_RichTextLabel_property_visible_ratio>` and :ref:`visible_characters<class_RichTextLabel_property_visible_characters>`. To get the visible content size, use :ref:`get_visible_content_rect()<class_RichTextLabel_method_get_visible_content_rect>`.
\ **Note:** If :ref:`threaded<class_RichTextLabel_property_threaded>` is enabled, this method returns a value for the loaded part of the document. Use :ref:`is_finished()<class_RichTextLabel_method_is_finished>` or :ref:`finished<class_RichTextLabel_signal_finished>` to determine whether document is fully loaded.
.. rst-class:: classref-item-separator
@@ -1278,6 +1301,8 @@ Returns the height of the content.
Returns the width of the content.
\ **Note:** This method always returns the full content size, and is not affected by :ref:`visible_ratio<class_RichTextLabel_property_visible_ratio>` and :ref:`visible_characters<class_RichTextLabel_property_visible_characters>`. To get the visible content size, use :ref:`get_visible_content_rect()<class_RichTextLabel_method_get_visible_content_rect>`.
\ **Note:** If :ref:`threaded<class_RichTextLabel_property_threaded>` is enabled, this method returns a value for the loaded part of the document. Use :ref:`is_finished()<class_RichTextLabel_method_is_finished>` or :ref:`finished<class_RichTextLabel_signal_finished>` to determine whether document is fully loaded.
.. rst-class:: classref-item-separator
@@ -1523,6 +1548,51 @@ Returns the vertical scrollbar.
\ **Warning:** This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`CanvasItem.visible<class_CanvasItem_property_visible>` property.
.. rst-class:: classref-item-separator
----
.. _class_RichTextLabel_method_get_visible_content_rect:
.. rst-class:: classref-method
:ref:`Rect2i<class_Rect2i>` **get_visible_content_rect**\ (\ ) |const| :ref:`🔗<class_RichTextLabel_method_get_visible_content_rect>`
Returns the bounding rectangle of the visible content.
\ **Note:** This method returns a correct value only after the label has been drawn.
.. tabs::
.. code-tab:: gdscript
extends RichTextLabel
@export var background_panel: Panel
func _ready():
await draw
background_panel.position = get_visible_content_rect().position
background_panel.size = get_visible_content_rect().size
.. code-tab:: csharp
public partial class TestLabel : RichTextLabel
{
[Export]
public Panel BackgroundPanel { get; set; }
public override async void _Ready()
{
await ToSignal(this, Control.SignalName.Draw);
BackgroundGPanel.Position = GetVisibleContentRect().Position;
BackgroundPanel.Size = GetVisibleContentRect().Size;
}
}
.. rst-class:: classref-item-separator
----
@@ -1535,6 +1605,8 @@ Returns the vertical scrollbar.
Returns the number of visible lines.
\ **Note:** This method returns a correct value only after the label has been drawn.
\ **Note:** If :ref:`threaded<class_RichTextLabel_property_threaded>` is enabled, this method returns a value for the loaded part of the document. Use :ref:`is_finished()<class_RichTextLabel_method_is_finished>` or :ref:`finished<class_RichTextLabel_signal_finished>` to determine whether document is fully loaded.
.. rst-class:: classref-item-separator
@@ -1549,6 +1621,8 @@ Returns the number of visible lines.
Returns the number of visible paragraphs. A paragraph is considered visible if at least one of its lines is visible.
\ **Note:** This method returns a correct value only after the label has been drawn.
\ **Note:** If :ref:`threaded<class_RichTextLabel_property_threaded>` is enabled, this method returns a value for the loaded part of the document. Use :ref:`is_finished()<class_RichTextLabel_method_is_finished>` or :ref:`finished<class_RichTextLabel_signal_finished>` to determine whether document is fully loaded.
.. rst-class:: classref-item-separator

6
classes/class_spinbox.rst
View File

@@ -208,7 +208,9 @@ Changes the alignment of the underlying :ref:`LineEdit<class_LineEdit>`.
- |void| **set_custom_arrow_step**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_custom_arrow_step**\ (\ )
If not ``0``, :ref:`Range.value<class_Range_property_value>` will always be rounded to a multiple of :ref:`custom_arrow_step<class_SpinBox_property_custom_arrow_step>` when interacting with the arrow buttons of the **SpinBox**.
If not ``0``, sets the step when interacting with the arrow buttons of the **SpinBox**.
\ **Note:** :ref:`Range.value<class_Range_property_value>` will still be rounded to a multiple of :ref:`Range.step<class_Range_property_step>`.
.. rst-class:: classref-item-separator
@@ -583,7 +585,7 @@ Up button icon when the button is being pressed.
:ref:`Texture2D<class_Texture2D>` **updown** :ref:`🔗<class_SpinBox_theme_icon_updown>`
Single texture representing both the up and down buttons icons. It is displayed in the middle of the buttons and does not change upon interaction. It is recommended to use individual :ref:`up<class_SpinBox_theme_icon_up>` and :ref:`down<class_SpinBox_theme_icon_down>` graphics for better usability. This can also be used as additional decoration between the two buttons.
Single texture representing both the up and down buttons icons. It is displayed in the middle of the buttons and does not change upon interaction. If a valid icon is assigned, it will replace :ref:`up<class_SpinBox_theme_icon_up>` and :ref:`down<class_SpinBox_theme_icon_down>`.
.. rst-class:: classref-item-separator

84
classes/class_splitcontainer.rst
View File

@@ -82,27 +82,33 @@ Theme Properties
.. table::
:widths: auto
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`int<class_int>` | :ref:`autohide<class_SplitContainer_theme_constant_autohide>` | ``1`` |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`int<class_int>` | :ref:`minimum_grab_thickness<class_SplitContainer_theme_constant_minimum_grab_thickness>` | ``6`` |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`int<class_int>` | :ref:`separation<class_SplitContainer_theme_constant_separation>` | ``12`` |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`grabber<class_SplitContainer_theme_icon_grabber>` | |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`h_grabber<class_SplitContainer_theme_icon_h_grabber>` | |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`h_touch_dragger<class_SplitContainer_theme_icon_h_touch_dragger>` | |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`touch_dragger<class_SplitContainer_theme_icon_touch_dragger>` | |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`v_grabber<class_SplitContainer_theme_icon_v_grabber>` | |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`v_touch_dragger<class_SplitContainer_theme_icon_v_touch_dragger>` | |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
| :ref:`StyleBox<class_StyleBox>` | :ref:`split_bar_background<class_SplitContainer_theme_style_split_bar_background>` | |
+-----------------------------------+-------------------------------------------------------------------------------------------+--------+
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Color<class_Color>` | :ref:`touch_dragger_color<class_SplitContainer_theme_color_touch_dragger_color>` | ``Color(1, 1, 1, 0.3)`` |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Color<class_Color>` | :ref:`touch_dragger_hover_color<class_SplitContainer_theme_color_touch_dragger_hover_color>` | ``Color(1, 1, 1, 0.6)`` |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Color<class_Color>` | :ref:`touch_dragger_pressed_color<class_SplitContainer_theme_color_touch_dragger_pressed_color>` | ``Color(1, 1, 1, 1)`` |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`int<class_int>` | :ref:`autohide<class_SplitContainer_theme_constant_autohide>` | ``1`` |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`int<class_int>` | :ref:`minimum_grab_thickness<class_SplitContainer_theme_constant_minimum_grab_thickness>` | ``6`` |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`int<class_int>` | :ref:`separation<class_SplitContainer_theme_constant_separation>` | ``12`` |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`grabber<class_SplitContainer_theme_icon_grabber>` | |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`h_grabber<class_SplitContainer_theme_icon_h_grabber>` | |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`h_touch_dragger<class_SplitContainer_theme_icon_h_touch_dragger>` | |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`touch_dragger<class_SplitContainer_theme_icon_touch_dragger>` | |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`v_grabber<class_SplitContainer_theme_icon_v_grabber>` | |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`v_touch_dragger<class_SplitContainer_theme_icon_v_touch_dragger>` | |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
| :ref:`StyleBox<class_StyleBox>` | :ref:`split_bar_background<class_SplitContainer_theme_style_split_bar_background>` | |
+-----------------------------------+--------------------------------------------------------------------------------------------------+-------------------------+
.. rst-class:: classref-section-separator
@@ -413,6 +419,42 @@ Returns the drag area :ref:`Control<class_Control>`. For example, you can move a
Theme Property Descriptions
---------------------------
.. _class_SplitContainer_theme_color_touch_dragger_color:
.. rst-class:: classref-themeproperty
:ref:`Color<class_Color>` **touch_dragger_color** = ``Color(1, 1, 1, 0.3)`` :ref:`🔗<class_SplitContainer_theme_color_touch_dragger_color>`
The color of the touch dragger.
.. rst-class:: classref-item-separator
----
.. _class_SplitContainer_theme_color_touch_dragger_hover_color:
.. rst-class:: classref-themeproperty
:ref:`Color<class_Color>` **touch_dragger_hover_color** = ``Color(1, 1, 1, 0.6)`` :ref:`🔗<class_SplitContainer_theme_color_touch_dragger_hover_color>`
The color of the touch dragger when hovered.
.. rst-class:: classref-item-separator
----
.. _class_SplitContainer_theme_color_touch_dragger_pressed_color:
.. rst-class:: classref-themeproperty
:ref:`Color<class_Color>` **touch_dragger_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗<class_SplitContainer_theme_color_touch_dragger_pressed_color>`
The color of the touch dragger when pressed.
.. rst-class:: classref-item-separator
----
.. _class_SplitContainer_theme_constant_autohide:
.. rst-class:: classref-themeproperty

2
classes/class_tilemaplayer.rst
View File

@@ -21,7 +21,7 @@ Description
Node for 2D tile-based maps. A **TileMapLayer** uses a :ref:`TileSet<class_TileSet>` which contain a list of tiles which are used to create grid-based maps. Unlike the :ref:`TileMap<class_TileMap>` node, which is deprecated, **TileMapLayer** has only one layer of tiles. You can use several **TileMapLayer** to achieve the same result as a :ref:`TileMap<class_TileMap>` node.
For performance reasons, all TileMap updates are batched at the end of a frame. Notably, this means that scene tiles from a :ref:`TileSetScenesCollectionSource<class_TileSetScenesCollectionSource>` may be initialized after their parent. This is only queued when inside the scene tree.
For performance reasons, all TileMap updates are batched at the end of a frame. Notably, this means that scene tiles from a :ref:`TileSetScenesCollectionSource<class_TileSetScenesCollectionSource>` are initialized after their parent. This is only queued when inside the scene tree.
To force an update earlier on, call :ref:`update_internals()<class_TileMapLayer_method_update_internals>`.

2
classes/class_tilesetscenescollectionsource.rst
View File

@@ -21,7 +21,7 @@ Description
When placed on a :ref:`TileMapLayer<class_TileMapLayer>`, tiles from **TileSetScenesCollectionSource** will automatically instantiate an associated scene at the cell's position in the TileMapLayer.
Scenes are instantiated as children of the :ref:`TileMapLayer<class_TileMapLayer>` when it enters the tree. If you add/remove a scene tile in the :ref:`TileMapLayer<class_TileMapLayer>` that is already inside the tree, the :ref:`TileMapLayer<class_TileMapLayer>` will automatically instantiate/free the scene accordingly.
Scenes are instantiated as children of the :ref:`TileMapLayer<class_TileMapLayer>` after it enters the tree, at the end of the frame (their creation is deferred). If you add/remove a scene tile in the :ref:`TileMapLayer<class_TileMapLayer>` that is already inside the tree, the :ref:`TileMapLayer<class_TileMapLayer>` will automatically instantiate/free the scene accordingly.
\ **Note:** Scene tiles all occupy one tile slot and instead use alternate tile ID to identify scene index. :ref:`TileSetSource.get_tiles_count()<class_TileSetSource_method_get_tiles_count>` will always return ``1``. Use :ref:`get_scene_tiles_count()<class_TileSetScenesCollectionSource_method_get_scene_tiles_count>` to get a number of scenes in a **TileSetScenesCollectionSource**.

6
classes/class_translation.rst
View File

@@ -30,6 +30,8 @@ Tutorials
- :doc:`Internationalizing games <../tutorials/i18n/internationalizing_games>`
- :doc:`Localization using gettext <../tutorials/i18n/localization_using_gettext>`
- :doc:`Locales <../tutorials/i18n/locales>`
.. rst-class:: classref-reftable-group
@@ -153,6 +155,8 @@ Adds a message involving plural translation if nonexistent, followed by its tran
An additional context could be used to specify the translation context or differentiate polysemic words.
\ **Note:** Plurals are only supported in :doc:`gettext-based translations (PO) <../tutorials/i18n/localization_using_gettext>`, not CSV.
.. rst-class:: classref-item-separator
----
@@ -215,6 +219,8 @@ Returns a message's translation involving plurals.
The number ``n`` is the number or quantity of the plural object. It will be used to guide the translation system to fetch the correct plural form for the selected language.
\ **Note:** Plurals are only supported in :doc:`gettext-based translations (PO) <../tutorials/i18n/localization_using_gettext>`, not CSV.
.. rst-class:: classref-item-separator
----

2
classes/class_viewport.rst
View File

@@ -1945,7 +1945,7 @@ If ``true``, the viewport should render its background as transparent.
- |void| **set_use_debanding**\ (\ value\: :ref:`bool<class_bool>`\ )
- :ref:`bool<class_bool>` **is_using_debanding**\ (\ )
If ``true``, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode<class_Environment_property_background_mode>` is :ref:`Environment.BG_CANVAS<class_Environment_constant_BG_CANVAS>`.
If ``true``, uses a fast post-processing filter to make banding significantly less visible. If :ref:`use_hdr_2d<class_Viewport_property_use_hdr_2d>` is ``false``, 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode<class_Environment_property_background_mode>` is :ref:`Environment.BG_CANVAS<class_Environment_constant_BG_CANVAS>`. If :ref:`use_hdr_2d<class_Viewport_property_use_hdr_2d>` is ``true``, debanding will only be applied if this is the root **Viewport** and will affect all 2D and 3D rendering, including canvas items.
In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.

17
conf.py
View File

@@ -231,6 +231,23 @@ linkcheck_anchors = False
linkcheck_timeout = 10
# -- Custom Sphinx roles for UI -------------------------------------------
rst_prolog = """
.. role:: button
:class: role-button role-ui
.. role:: menu
:class: role-menu role-ui
.. role:: inspector
:class: role-ui
.. role:: ui
:class: role-ui
"""
# -- I18n settings --------------------------------------------------------
# Godot localization is handled via https://github.com/godotengine/godot-docs-l10n

4
contributing/development/code_style_guidelines.rst
View File

@@ -73,8 +73,8 @@ To set up:
::
pip install pre-commit
pre-commit install
pip install pre-commit
pre-commit install
You can also run the hook manually with ``pre-commit run``.

4
contributing/development/compiling/compiling_for_android.rst
View File

@@ -204,9 +204,9 @@ next to your export templates.
However, if you are writing your custom modules or custom C++ code, you
might instead want to configure your template binaries as custom export templates
here:
in the project export menu. You must have **Advanced Options** enabled to set this.
.. image:: img/andtemplates.png
.. image:: img/andtemplates.webp
You don't even need to copy them, you can just reference the resulting
file in the ``bin\`` directory of your Godot source folder, so that the

24
contributing/development/compiling/compiling_for_linuxbsd.rst
View File

@@ -314,12 +314,15 @@ And then use the ``--headless`` command line argument:
./bin/godot.linuxbsd.editor.x86_64 --headless
To compile a debug *server* build which can be used with
:ref:`remote debugging tools <doc_command_line_tutorial>`, use::
:ref:`remote debugging tools <doc_command_line_tutorial>`, use:
::
scons platform=linuxbsd target=template_debug
To compile a *server* build which is optimized to run dedicated game servers,
use::
To compile a *server* build which is optimized to run dedicated game servers, use:
::
scons platform=linuxbsd target=template_release production=yes
@@ -363,7 +366,7 @@ must be copied to:
and named like this (even for \*BSD which is seen as "Linux/X11" by Godot):
::
.. code:: text
linux_debug.arm32
linux_debug.arm64
@@ -376,9 +379,10 @@ and named like this (even for \*BSD which is seen as "Linux/X11" by Godot):
However, if you are writing your custom modules or custom C++ code, you
might instead want to configure your binaries as custom export templates
here:
in the project export menu. You must have **Advanced Options** enabled
to set this.
.. image:: img/lintemplates.png
.. image:: img/lintemplates.webp
You don't even need to copy them, you can just reference the resulting
files in the ``bin/`` directory of your Godot source folder, so the next
@@ -449,7 +453,7 @@ indicates to Clang the target architecture, and OS we want to build for.
If all went well, you should now see a ``bin`` directory, and within it,
a binary similar to the following:
::
.. code:: text
godot.linuxbsd.editor.rv64.llvm
@@ -486,7 +490,7 @@ link-time optimization, making the resulting binaries smaller and faster.
If this error occurs:
::
.. code:: text
/usr/bin/ld: cannot find -l:libatomic.a: No such file or directory
@@ -517,7 +521,9 @@ repositories, so you will have to install its binaries manually.
PATH="$HOME/.local/share/mold/bin:$PATH"
- Open a new terminal (or run ``source "$HOME/.bash_profile"``),
then use the following SCons command when compiling Godot::
then use the following SCons command when compiling Godot:
::
scons platform=linuxbsd linker=mold

64
contributing/development/compiling/compiling_for_macos.rst
View File

@@ -53,11 +53,15 @@ Compiling
Start a terminal, go to the root directory of the engine source code.
To compile for Intel (x86-64) powered Macs, use::
To compile for Intel (x86-64) powered Macs, use:
::
scons platform=macos arch=x86_64
To compile for Apple Silicon (ARM64) powered Macs, use::
To compile for Apple Silicon (ARM64) powered Macs, use:
::
scons platform=macos arch=arm64
@@ -102,7 +106,9 @@ run the above two commands and then use ``lipo`` to bundle them together:
lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal
To create a ``.app`` bundle, you need to use the template located in ``misc/dist/macos_tools.app``. Typically, for an optimized
editor binary built with ``dev_build=yes``::
editor binary built with ``dev_build=yes``:
::
cp -r misc/dist/macos_tools.app ./bin/Godot.app
mkdir -p bin/Godot.app/Contents/MacOS
@@ -116,7 +122,9 @@ editor binary built with ``dev_build=yes``::
for the MoltenVK Vulkan portability library. By default, it will be linked
statically from your installation of the Vulkan SDK for macOS.
You can also choose to link it dynamically by passing ``use_volk=yes`` and
including the dynamic library in your ``.app`` bundle::
including the dynamic library in your ``.app`` bundle:
::
mkdir -p <Godot bundle name>.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib <Godot bundle name>.app/Contents/Frameworks/libMoltenVK.dylib
@@ -138,12 +146,15 @@ And then use the ``--headless`` command line argument:
./bin/godot.macos.editor.x86_64 --headless
To compile a debug *server* build which can be used with
:ref:`remote debugging tools <doc_command_line_tutorial>`, use::
:ref:`remote debugging tools <doc_command_line_tutorial>`, use:
::
scons platform=macos target=template_debug
To compile a release *server* build which is optimized to run dedicated game servers,
use::
To compile a release *server* build which is optimized to run dedicated game servers, use:
::
scons platform=macos target=template_release production=yes
@@ -157,17 +168,21 @@ the editor: ``target=template_release`` (release template) and
Official templates are *Universal 2* binaries which support both ARM64 and Intel
x86_64 architectures.
- To support ARM64 (Apple Silicon) + Intel x86_64::
- To support ARM64 (Apple Silicon) + Intel x86_64:
scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64
scons platform=macos target=template_debug arch=x86_64
scons platform=macos target=template_release arch=x86_64 generate_bundle=yes
::
- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware)::
scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64
scons platform=macos target=template_debug arch=x86_64
scons platform=macos target=template_release arch=x86_64 generate_bundle=yes
scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64 generate_bundle=yes
- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware):
::
scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64 generate_bundle=yes
To create a ``.app`` bundle like in the official builds, you need to use the
template located in ``misc/dist/macos_template.app``. This process can be automated by using
@@ -181,7 +196,9 @@ a *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both were
library. By default, it will be linked statically from your installation of
the Vulkan SDK for macOS. You can also choose to link it dynamically by
passing ``use_volk=yes`` and including the dynamic library in your ``.app``
bundle::
bundle:
::
mkdir -p macos_template.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib
@@ -206,8 +223,9 @@ Windows using the Windows Subsystem for Linux). For that, you'll need to install
as a target. First, follow the instructions to install it:
Clone the `OSXCross repository <https://github.com/tpoechtrager/osxcross>`__
somewhere on your machine (or download a ZIP file and extract it somewhere),
e.g.::
somewhere on your machine (or download a ZIP file and extract it somewhere), e.g.:
::
git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"
@@ -218,7 +236,9 @@ e.g.::
After that, you will need to define the ``OSXCROSS_ROOT`` as the path to
the OSXCross installation (the same place where you cloned the
repository/extracted the zip), e.g.::
repository/extracted the zip), e.g.:
::
export OSXCROSS_ROOT="$HOME/osxcross"
@@ -228,7 +248,9 @@ Now you can compile with SCons like you normally would:
scons platform=macos
If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument::
If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument:
::
scons platform=macos osxcross_sdk=darwin15
@@ -242,7 +264,7 @@ If you get a compilation error of this form early on, it's likely because
the Xcode command line tools installation needs to be repaired after
a macOS or Xcode update:
::
.. code:: text
./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
45 | #include <cstdint>

24
contributing/development/compiling/compiling_for_windows.rst
View File

@@ -301,9 +301,11 @@ By default, Godot is built with dynamically linked ANGLE, you can use it by plac
To compile Godot with statically linked ANGLE:
- Download pre-built static libraries from `godot-angle-static library <https://github.com/godotengine/godot-angle-static/releases>`_, and unzip them.
- When building Godot, add ``angle_libs={path}`` to tell SCons where to look for the ANGLE libraries::
- When building Godot, add ``angle_libs={path}`` to tell SCons where to look for the ANGLE libraries:
scons platform=windows angle_libs=<...>
::
scons platform=windows angle_libs=<...>
.. note:: You can optionally build the godot-angle-static libraries yourself with
the following steps:
@@ -414,7 +416,9 @@ Where ``/path/to/mingw`` is the path containing the ``bin`` directory where
To make sure you are doing things correctly, executing the following in
the shell should result in a working compiler (the version output may
differ based on your system)::
differ based on your system):
::
${MINGW_PREFIX}/bin/x86_64-w64-mingw32-gcc --version
# x86_64-w64-mingw32-gcc (GCC) 13.2.0
@@ -432,15 +436,18 @@ Cross-compiling from some Ubuntu versions may lead to
`this bug <https://github.com/godotengine/godot/issues/9258>`_,
due to a default configuration lacking support for POSIX threading.
You can change that configuration following those instructions,
for 64-bit::
You can change that configuration following those instructions, for 64-bit:
::
sudo update-alternatives --config x86_64-w64-mingw32-gcc
<choose x86_64-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config x86_64-w64-mingw32-g++
<choose x86_64-w64-mingw32-g++-posix from the list>
And for 32-bit::
And for 32-bit:
::
sudo update-alternatives --config i686-w64-mingw32-gcc
<choose i686-w64-mingw32-gcc-posix from the list>
@@ -489,12 +496,11 @@ With the following names:
However, if you are using custom modules or custom engine code, you
may instead want to configure your binaries as custom export templates
here:
in the project export menu. You must have **Advanced Options** enabled
to set this.
.. image:: img/wintemplates.webp
Select matching architecture in the export config.
You don't need to copy them in this case, just reference the resulting
files in the ``bin\`` directory of your Godot source folder, so the next
time you build, you will automatically have the custom templates referenced.

4
contributing/development/compiling/compiling_with_dotnet.rst
View File

@@ -64,7 +64,9 @@ Building the managed libraries
------------------------------
Once you have generated the .NET glue, you can build the managed libraries with
the ``build_assemblies.py`` script::
the ``build_assemblies.py`` script:
::
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin

6
contributing/development/compiling/compiling_with_script_encryption_key.rst
View File

@@ -22,12 +22,6 @@ with that same key.
It is absolutely **required** to compile your own export templates to use
PCK encryption.
.. warning::
By default, Android exports store assets directly in the APK file and
aren't affected by PCK encryption. To use PCK encryption on Android, enable
**APK expansion** in the export options.
Step by step
------------

4
contributing/development/compiling/getting_source.rst
View File

@@ -40,7 +40,9 @@ and click on the link for the release you want.
You can then download and extract the source from the download link on the page.
With ``git``, you can also clone a stable release by specifying its branch or tag
after the ``--branch`` (or just ``-b``) argument::
after the ``--branch`` (or just ``-b``) argument:
::
# Clone the continuously maintained stable branch (`4.4` as of writing).
git clone https://github.com/godotengine/godot.git -b 4.4

BIN
contributing/development/compiling/img/andtemplates.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 27 KiB

BIN
contributing/development/compiling/img/andtemplates.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
contributing/development/compiling/img/lintemplates.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 22 KiB

BIN
contributing/development/compiling/img/lintemplates.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
contributing/development/compiling/img/wintemplates.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 55 KiB

After

Width:  |  Height:  |  Size: 19 KiB

14
contributing/development/compiling/introduction_to_the_buildsystem.rst
View File

@@ -49,12 +49,16 @@ Using multi-threading
The build process may take a while, depending on how powerful your system is. By default, Godot's
SCons setup is configured to use all CPU threads but one (to keep the system responsive during
compilation). If you want to adjust how many CPU threads SCons will use, use the ``-j <threads>``
compilation). If the system has 4 CPU threads or fewer, it will use all threads by default.
If you want to adjust how many CPU threads SCons will use, use the ``-j<threads>``
parameter to specify how many threads will be used for the build.
Example for using 4 threads::
Example for using 12 threads:
scons -j4
::
scons -j12
Platform selection
------------------
@@ -68,7 +72,9 @@ SCons is invoked by just calling ``scons``. If no platform is specified,
SCons will detect the target platform automatically based on the host platform.
It will then start building for the target platform right away.
To list the available target platforms, use ``scons platform=list``::
To list the available target platforms, use ``scons platform=list``:
.. code:: text
scons platform=list
scons: Reading SConscript files ...

13
contributing/development/configuring_an_ide/clion.rst
View File

@@ -17,6 +17,19 @@ CLion can import a project's `compilation database file <https://clang.llvm.org/
Then, open the Godot root directory with CLion. CLion will import the compilation database, index the codebase, and provide autocompletion and other advanced code navigation and refactoring functionality.
.. note:: Windows Users:
For ``compile_commands.json`` to load correctly in CLion, you must first have the Visual Studio toolchain configured for CLion.
- Navigate to **Preferences > Build, Execution, Deployment > Toolchains**
- Click the **+** button and select ``Visual Studio``
- CLion will attempt to detect your Visual Studio installation. If it is unsuccessful, use the file icon to the right of ``Toolset:`` to select the directory with your Visual Studio installation.
You may exit and reload CLion and it will reload ``compile_commands.json``
.. figure:: img/clion_visual_studio_toolchain.webp
:align: center
Compiling and debugging the project
-----------------------------------

BIN
contributing/development/configuring_an_ide/img/clion_visual_studio_toolchain.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

196
contributing/development/core_and_modules/core_types.rst
View File

@@ -20,20 +20,17 @@ more difficult to read.
In general, care is not taken to use the most efficient datatype for a
given task unless using large structures or arrays. ``int`` is used
through most of the code unless necessary. This is done because nowadays
every device has at least a 32 bits bus and can do such operations in
every device has at least a 32-bit bus and can do such operations in
one cycle. It makes code more readable too.
For files or memory sizes, ``size_t`` is used, which is warranted to be
64 bits.
For files or memory sizes, ``size_t`` is used, which is guaranteed to be
64-bit.
For Unicode characters, CharType instead of wchar_t is used, because
many architectures have 4 bytes long wchar_t, where 2 bytes might be
desired. However, by default, this has not been forced and CharType maps
directly to wchar_t.
References:
~~~~~~~~~~~
- `core/typedefs.h <https://github.com/godotengine/godot/blob/master/core/typedefs.h>`__
Memory model
@@ -63,7 +60,7 @@ remain constant. In other words, leave 10-20% of your memory free
and perform all small allocations and you are fine.
Godot ensures that all objects that can be allocated dynamically are
small (less than a few kb at most). But what happens if an allocation is
small (less than a few kB at most). But what happens if an allocation is
too large (like an image or mesh geometry or large array)? In this case
Godot has the option to use a dynamic memory pool. This memory needs to
be locked to be accessed, and if an allocation runs out of memory, the
@@ -85,20 +82,21 @@ For C-style allocation, Godot provides a few macros:
memrealloc()
memfree()
These are equivalent to the usual malloc, realloc, free of the standard C
library.
These are equivalent to the usual ``malloc()``, ``realloc()``, and ``free()``
of the C standard library.
For C++-style allocation, special macros are provided:
.. code-block:: none
memnew( Class / Class(args) )
memdelete( instance )
memnew(Class / Class(args))
memdelete(instance)
memnew_arr( Class , amount )
memdelete_arr( pointer to array )
memnew_arr(Class, amount)
memdelete_arr(pointer_to_array)
which are equivalent to new, delete, new[] and delete[].
These are equivalent to ``new``, ``delete``, ``new[]``, and ``delete[]``
respectively.
memnew/memdelete also use a little C++ magic and notify Objects right
after they are created, and right before they are deleted.
@@ -128,84 +126,110 @@ its storage strategy. Prefer ``Vector<>`` (or ``LocalVector<>``) over
``List<>`` unless you're sure you need it, as cache locality and memory
fragmentation tend to be more important with small collections.
References:
~~~~~~~~~~~
- `core/os/memory.h <https://github.com/godotengine/godot/blob/master/core/os/memory.h>`__
Containers
----------
Godot provides also a set of common containers:
Godot provides its own set of containers, which means STL containers like ``std::string``
and ``std::vector`` are generally not used in the codebase. See :ref:`doc_faq_why_not_stl` for more information.
- Vector
- List
- Set
- Map
A 📜 icon denotes the type is part of :ref:`Variant <doc_variant_class>`. This
means it can be used as a parameter or return value of a method exposed to the
scripting API.
They aim to be as minimal as possible, as templates
in C++ are often inlined and make the binary size much fatter, both in
debug symbols and code. List, Set and Map can be iterated using
pointers, like this:
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| Godot datatype | Closest C++ STL datatype | Comment |
+=======================+==========================+=======================================================================================+
| |string| 📜 | ``std::string`` | **Use this as the "default" string type.** ``String`` uses UTF-32 encoding |
| | | to improve performance thanks to its fixed character size. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |vector| | ``std::vector`` | **Use this as the "default" vector type.** Uses copy-on-write (COW) semantics. |
| | | This means it's generally slower but can be copied around almost for free. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |hash_set| | ``std::unordered_set`` | **Use this as the "default" set type.** |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |a_hash_map| | ``std::unordered_map`` | **Use this as the "default" map type.** Does not preserve insertion order. |
| | | Note that pointers into the map, as well as iterators, are not stable under mutations.|
| | | If either of these affordances are needed, use ``HashMap`` instead. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |string_name| 📜 | ``std::string`` | Uses string interning for fast comparisons. Use this for static strings that are |
| | | referenced frequently and used in multiple locations in the engine. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |local_vector| | ``std::vector`` | Closer to ``std::vector`` in semantics. In most situations, ``Vector`` should be |
| | | preferred. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |array| 📜 | ``std::vector`` | Values can be of any Variant type. No static typing is imposed. |
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
| | | Uses Vector<Variant> internally. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |typed_array| 📜 | ``std::vector`` | Subclass of ``Array`` but with static typing for its elements. |
| | | Not to be confused with ``Packed*Array``, which is internally a ``Vector``. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |packed_array| 📜 | ``std::vector`` | Alias of ``Vector``, e.g. ``PackedColorArray = Vector<Color>``. |
| | | Only a limited list of packed array types are available |
| | | (use ``TypedArray`` otherwise). |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |list| | ``std::list`` | Linked list type. Generally slower than other array/vector types. Prefer using |
| | | other types in new code, unless using ``List`` avoids the need for type conversions. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |fixed_vector| | ``std::array`` | Vector with a fixed capacity (more similar to ``boost::container::static_vector``). |
| | | This container type is more efficient than other vector-like types because it makes |
| | | no heap allocations. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |span| | ``std::span`` | Represents read-only access to a contiguous array without needing to copy any data. |
| | | See `pull request description <https://github.com/godotengine/godot/pull/100293>`__ |
| | | for details. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |rb_set| | ``std::set`` | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black_tree>`__ |
| | | for faster access. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |v_set| | ``std::flat_set`` | Uses copy-on-write (COW) semantics. |
| | | This means it's generally slower but can be copied around almost for free. |
| | | The performance benefits of ``VSet`` aren't established, so prefer using other types. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |hash_map| | ``std::unordered_map`` | Defensive (robust but slow) map type. Preserves insertion order. |
| | | Pointers to keys and values, as well as iterators, are stable under mutation. |
| | | Use this map type when either of these affordances are needed. Use ``AHashMap`` |
| | | otherwise. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |rb_map| | ``std::map`` | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black-tree>`__ |
| | | for faster access. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |dictionary| 📜 | ``std::unordered_map`` | Keys and values can be of any Variant type. No static typing is imposed. |
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
| | | Preserves insertion order. Uses ``HashMap<Variant>`` internally. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |typed_dictionary| 📜 | ``std::unordered_map`` | Subclass of ``Dictionary`` but with static typing for its keys and values. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
| |pair| | ``std::pair`` | Stores a single key-value pair. |
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
.. code-block:: cpp
for(List<int>::Element *E=somelist.front();E;E=E->next()) {
print_line(E->get()); // print the element
}
The Vector<> class also has a few nice features:
- It does copy on write, so making copies of it is cheap as long as
they are not modified.
- It supports multi-threading, by using atomic operations on the
reference counter.
References:
~~~~~~~~~~~
- `core/templates/vector.h <https://github.com/godotengine/godot/blob/master/core/templates/vector.h>`__
- `core/templates/list.h <https://github.com/godotengine/godot/blob/master/core/templates/list.h>`__
- `core/templates/set.h <https://github.com/godotengine/godot/blob/master/core/templates/hash_set.h>`__
- `core/templates/map.h <https://github.com/godotengine/godot/blob/master/core/templates/hash_map.h>`__
String
------
Godot also provides a String class. This class has a huge amount of
features, full Unicode support in all the functions (like case
operations) and utf8 parsing/extracting, as well as helpers for
conversion and visualization.
References:
~~~~~~~~~~~
- `core/string/ustring.h <https://github.com/godotengine/godot/blob/master/core/string/ustring.h>`__
StringName
----------
StringNames are like a String, but they are unique. Creating a
StringName from a string results in a unique internal pointer for all
equal strings. StringNames are useful for using strings as
identifier, as comparing them is basically comparing a pointer.
Creation of a StringName (especially a new one) is slow, but comparison
is fast.
References:
~~~~~~~~~~~
- `core/string/string_name.h <https://github.com/godotengine/godot/blob/master/core/string/string_name.h>`__
.. |string| replace:: `String <https://github.com/godotengine/godot/blob/master/core/string/ustring.h>`__
.. |vector| replace:: `Vector <https://github.com/godotengine/godot/blob/master/core/templates/vector.h>`__
.. |hash_set| replace:: `HashSet <https://github.com/godotengine/godot/blob/master/core/templates/hash_set.h>`__
.. |hash_map| replace:: `HashMap <https://github.com/godotengine/godot/blob/master/core/templates/hash_map.h>`__
.. |string_name| replace:: `StringName <https://github.com/godotengine/godot/blob/master/core/string/string_name.h>`__
.. |local_vector| replace:: `LocalVector <https://github.com/godotengine/godot/blob/master/core/templates/local_vector.h>`__
.. |array| replace:: `Array <https://github.com/godotengine/godot/blob/master/core/variant/array.h>`__
.. |typed_array| replace:: `TypedArray <https://github.com/godotengine/godot/blob/master/core/variant/array.h>`__
.. |packed_array| replace:: `Packed*Array <https://github.com/godotengine/godot/blob/master/core/variant/array.h>`__
.. |list| replace:: `List <https://github.com/godotengine/godot/blob/master/core/templates/list.h>`__
.. |fixed_vector| replace:: `FixedVector <https://github.com/godotengine/godot/blob/master/core/templates/fixed_vector.h>`__
.. |span| replace:: `Span <https://github.com/godotengine/godot/blob/master/core/templates/span.h>`__
.. |rb_set| replace:: `RBSet <https://github.com/godotengine/godot/blob/master/core/templates/rb_set.h>`__
.. |v_set| replace:: `VSet <https://github.com/godotengine/godot/blob/master/core/templates/vset.h>`__
.. |a_hash_map| replace:: `AHashMap <https://github.com/godotengine/godot/blob/master/core/templates/a_hash_map.h>`__
.. |rb_map| replace:: `RBMap <https://github.com/godotengine/godot/blob/master/core/templates/rb_map.h>`__
.. |dictionary| replace:: `Dictionary <https://github.com/godotengine/godot/blob/master/core/variant/dictionary.h>`__
.. |typed_dictionary| replace:: `TypedDictionary <https://github.com/godotengine/godot/blob/master/core/variant/dictionary.h>`__
.. |pair| replace:: `Pair <https://github.com/godotengine/godot/blob/master/core/templates/pair.h>`__
Math types
----------
There are several linear math types available in the core/math
directory.
References:
~~~~~~~~~~~
There are several linear math types available in the ``core/math``
directory:
- `core/math <https://github.com/godotengine/godot/tree/master/core/math>`__
@@ -213,22 +237,16 @@ NodePath
--------
This is a special datatype used for storing paths in a scene tree and
referencing them fast.
References:
~~~~~~~~~~~
referencing them in an optimized manner:
- `core/string/node_path.h <https://github.com/godotengine/godot/blob/master/core/string/node_path.h>`__
RID
---
RIDs are resource IDs. Servers use these to reference data stored in
RIDs are *Resource IDs*. Servers use these to reference data stored in
them. RIDs are opaque, meaning that the data they reference can't be
accessed directly. RIDs are unique, even for different types of
referenced data.
References:
~~~~~~~~~~~
referenced data:
- `core/templates/rid.h <https://github.com/godotengine/godot/blob/master/core/templates/rid.h>`__

68
contributing/development/cpp_usage_guidelines.rst
View File

@@ -55,75 +55,13 @@ as Godot provides its own data types (among other things).
See :ref:`doc_faq_why_not_stl` for more information.
This means that pull requests should **not** use ``std::string``,
``std::vector`` and the like. Instead, use Godot's datatypes as described below.
``std::vector`` and the like. Instead, use Godot's datatypes as described in
the :ref:`doc_core_types` documentation.
A 📜 icon denotes the type is part of :ref:`Variant <doc_variant_class>`. This
means it can be used as a parameter or return value of a method exposed to the
scripting API.
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| Godot datatype | Closest C++ STL datatype | Comment |
+========================+==========================+=======================================================================================+
| ``String`` 📜 | ``std::string`` | **Use this as the "default" string type.** ``String`` uses UTF-32 encoding |
| | | to improve performance thanks to its fixed character size. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``StringName`` 📜 | ``std::string`` | Uses string interning for fast comparisons. Use this for static strings that are |
| | | referenced frequently and used in multiple locations in the engine. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``Vector`` | ``std::vector`` | **Use this as the "default" vector type.** Uses copy-on-write (COW) semantics. |
| | | This means it's generally slower but can be copied around almost for free. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``LocalVector`` | ``std::vector`` | Closer to ``std::vector`` in semantics. In most situations, ``Vector`` should be |
| | | preferred. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``Array`` 📜 | ``std::vector`` | Values can be of any Variant type. No static typing is imposed. |
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
| | | Uses Vector<Variant> internally. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``TypedArray`` 📜 | ``std::vector`` | Subclass of ``Array`` but with static typing for its elements. |
| | | Not to be confused with ``Packed*Array``, which is internally a ``Vector``. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``Packed*Array`` 📜 | ``std::vector`` | Alias of ``Vector``, e.g. ``PackedColorArray = Vector<Color>``. |
| | | Only a limited list of packed array types are available |
| | | (use ``TypedArray`` otherwise). |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``List`` | ``std::list`` | Linked list type. Generally slower than other array/vector types. Prefer using |
| | | other types in new code, unless using ``List`` avoids the need for type conversions. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``FixedVector`` | ``std::array`` | Vector with a fixed capacity (more similar to ``boost::container::static_vector``). |
| | | This container type is more efficient than other vector-like types because it makes |
| | | no heap allocations. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``Span`` | ``std::span`` | Represents read-only access to a contiguous array without needing to copy any data. |
| | | See `pull request description <https://github.com/godotengine/godot/pull/100293>`__ |
| | | for details. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``HashSet`` | ``std::unordered_set`` | **Use this as the "default" set type.** |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``RBSet`` | ``std::set`` | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black_tree>`__ |
| | | for faster access. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``VSet`` | ``std::flat_set`` | Uses copy-on-write (COW) semantics. |
| | | This means it's generally slower but can be copied around almost for free. |
| | | The performance benefits of ``VSet`` aren't established, so prefer using other types. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``HashMap`` | ``std::unordered_map`` | **Use this as the "default" map type.** Preserves insertion order. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``AHashMap`` | ``std::unordered_map`` | Array-based implementation of a hash map. Does not preserve insertion order. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``OAHashMap`` | ``std::unordered_map`` | Does not preserve insertion order. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``RBMap`` | ``std::map`` | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black_tree>`__ |
| | | for faster access. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``Dictionary`` 📜 | ``std::unordered_map`` | Keys and values can be of any Variant type. No static typing is imposed. |
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
| | | Preserves insertion order. Uses ``HashMap<Variant>`` internally. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``TypedDictionary`` 📜 | ``std::unordered_map`` | Subclass of ``Dictionary`` but with static typing for its keys and values. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``Pair`` | ``std::pair`` | Stores a single key-value pair. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
``auto`` keyword
~~~~~~~~~~~~~~~~

101
contributing/documentation/docs_writing_guidelines.rst
View File

@@ -814,3 +814,104 @@ Follow these guidelines for when to refer to a specific Godot version:
- If a feature was added in a 3.x major or minor version, **do not specify** when
the feature was added. These features are old enough that the exact version
in which they were added is not relevant.
Use roles for editor UI
-----------------------
Much of the manual involves describing a sequence of UI actions in the editor,
like clicking a button, opening a menu, or setting a property in the inspector.
To keep formatting standardized, we use custom Sphinx roles for UI elements.
The following roles are defined:
- ``:button:`` A button, toggle, or other clickable UI element. If the reader
is meant to click on it, and it's not a menu, use this. Renders as
:button:`bold, with a background`.
- ``:menu:`` A series of menus to click through. When listing a series of
menus, separate them with ``>``. Renders as :menu:`bold, with a background`.
- ``:inspector:`` A property *in the inspector*. When describing a property in
*code*, instead either use ``code style`` or link to the property, as
described earlier. Renders as :inspector:`bold`.
- ``:ui:`` A role for any other editor UI elements. Use this if you would have
otherwise just used **bold style**. Use this for input fields, docks, tabs,
windows, bottom panels, etc. Also used for nested project settings or
inspector sections. Renders as :ui:`bold`.
The first two roles, ``:button:`` and ``:menu:`` are used for editor UI that the
reader is meant to click on, and they use an attention-grabbing visual style. The
other roles, ``:inspector:`` and ``:ui:``, are used for other UI and show up
often in text, so they just use bold text to be less distracting.
Our custom roles are inspired by the Sphinx `guilabel <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-guilabel>`_
and `menuselection <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-menuselection>`_
roles. However, we use our own implementation to better match the specific needs
of Godot's documentation, using `custom RST roles <https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles>`_
and some custom CSS.
Examples
~~~~~~~~
These are some example sections that use the roles, in context. Check the source
of this page to see which roles are used.
Adding a sprite and setting some properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the :ui:`Scene` dock, click :button:`2D Scene` to create a new scene.
Add a new :ref:`Sprite2D <class_Sprite2D>` to the scene by right-clicking on the
root node and choosing :button:`Add Child Node...`. In the :ui:`Create New Node`
window, search for "Sprite2D", select it, and then click :button:`Create`.
On the sprite, under :ui:`Offset`, set :inspector:`Offset` to ``(16, 32)``
and enable :inspector:`Flip H`. Set :inspector:`Animation > HFrames` to ``10``.
In :ui:`CanvasItem > Visibility`, set the :inspector:`Modulate` color to
``ff0000``.
.. tip::
Don't forget to save your scene in :menu:`Scene > Save Scene...`. When the
:ui:`Save Scene As...` window pops up, enter "my_scene.tscn" in the
:ui:`File` field, then click :button:`Save`.
Setting project settings
^^^^^^^^^^^^^^^^^^^^^^^^
Go to :menu:`Project > Project Settings`, then select the
:ref:`Max FPS <class_ProjectSettings_property_application/run/max_fps>`
setting under :ui:`Application > Run`. Don't forget to click the
:button:`Advanced Settings` toggle. Then, in :ui:`Filter Settings`, search for
"physics". Under :ui:`Physics > 3D > Solver`, set
:inspector:`Solver Iterations` to ``16``.
All styles in context
^^^^^^^^^^^^^^^^^^^^^
Use this section to see how the custom roles look, particularly within admonitions.
|styleroles|
.. note::
|styleroles|
.. warning::
|styleroles|
.. danger::
|styleroles|
.. tip::
|styleroles|
.. admonition:: Custom admonition
|styleroles|
.. All the inline roles which are used in the docs. External links don't work in a substitution.
.. |styleroles| replace:: Built-in styles: ``code``, **bold**, and *italics*.
Built-in roles: :kbd:`kbd`, :ref:`ref <doc_about_intro>`, :ref:`ref <class_node>`.
Custom roles: :button:`button`, :menu:`menu > submenu`, :inspector:`inspector`, :ui:`ui`.

32
contributing/documentation/editor_and_docs_localization.rst
View File

@@ -217,13 +217,15 @@ The editor translations originate from C++ strings, and may use:
placed in your translation where necessary for it to be meaningful after
substitution. You may need to refer to the source string location to
understand what kind of content will be substituted if it's not clear from the
sentence. Example (``%s`` will be substituted with a file name or path)::
sentence. Example (``%s`` will be substituted with a file name or path):
# PO file:
"There is no '%s' file."
::
# Weblate:
There is no '%s' file.
# PO file:
"There is no '%s' file."
# Weblate:
There is no '%s' file.
- **C escape characters** such as ``\n`` (line break) or ``\t`` (tabulation). In
the Weblate editor, the ``\n`` characters are replaced by ``↵`` (return) and
@@ -231,15 +233,17 @@ The editor translations originate from C++ strings, and may use:
breaks in the same way as the original English string (Weblate will issue a
warning if you don't). Line breaks might sometimes be used for vertical
spacing, or manual wrapping of long lines which would otherwise be too long
especially in the editor translation). Example::
especially in the editor translation). Example:
# PO file:
"Scene '%s' is currently being edited.\n"
"Changes will only take effect when reloaded."
::
# Weblate:
Scene '%s' is currently being edited.↵
Changes will only take effect when reloaded.
# PO file:
"Scene '%s' is currently being edited.\n"
"Changes will only take effect when reloaded."
# Weblate:
Scene '%s' is currently being edited.↵
Changes will only take effect when reloaded.
.. note::
Only logical order of the characters matters, in the right-to-left text, format
@@ -307,7 +311,9 @@ Some of the tags used are from the original BBCode (e.g. ``[b]Bold[/b]`` and
``[i]Italics[/i]``), while others are Godot-specific and used for advanced
features such as inline code (e.g. ``[code]true[/code]``), linking to another
class (e.g. ``[Node2D]``) or to a property in a given class (e.g.
``[member Node2D.position]``), or for multiline code blocks. Example::
``[member Node2D.position]``), or for multiline code blocks. Example:
::
Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1.
[codeblock]

BIN
getting_started/first_2d_game/img/new_spriteframes.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 11 KiB

BIN
getting_started/first_3d_game/img/01.game_setup/08.create_box_shape3D.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 13 KiB

BIN
getting_started/first_3d_game/img/01.game_setup/11.box_mesh.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 14 KiB

BIN
getting_started/first_3d_game/img/02.player_input/add_capsuleshape3d.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 12 KiB

49
getting_started/step_by_step/nodes_and_scenes.rst
View File

@@ -73,23 +73,24 @@ opening the project, you should see an empty editor.
.. image:: img/nodes_and_scenes_01_empty_editor.webp
In an empty scene, the Scene dock on the left shows several options to add a
root node quickly. "2D Scene" adds a :ref:`Node2D <class_Node2D>` node,
"3D Scene" adds a :ref:`Node3D <class_Node3D>` node,
and "User Interface" adds a :ref:`Control <class_Control>` node.
root node quickly. :button:`2D Scene` adds a :ref:`Node2D <class_Node2D>` node,
:button:`3D Scene` adds a :ref:`Node3D <class_Node3D>` node,
and :button:`User Interface` adds a :ref:`Control <class_Control>` node.
These presets are here for convenience; they are not mandatory.
"Other Node" lets you select any node to be the root node.
In an empty scene, "Other Node" is equivalent to pressing the "Add Child Node"
:button:`Other Node` lets you select any node to be the root node.
In an empty scene, :button:`Other Node` is equivalent to pressing the :button:`Add Child Node`
button at the top-left of the Scene dock, which usually adds
a new node as a child of the currently selected node.
We're going to add a single :ref:`Label <class_Label>` node to our scene. Its function is to draw
text on the screen.
Press the "Add Child Node" button or "Other Node" to create a root node.
Press the :button:`Add Child Node` button or :button:`Other Node` to create a
root node.
.. image:: img/nodes_and_scenes_02_scene_dock.webp
The Create Node dialog opens, showing the long list of available nodes.
The :ui:`Create New Node` dialog opens, showing the long list of available nodes.
.. image:: img/nodes_and_scenes_03_create_node_window.webp
@@ -97,8 +98,8 @@ Select the Label node. You can type its name to filter down the list.
.. image:: img/nodes_and_scenes_04_create_label_window.webp
Click on the Label node to select it and click the Create button at the bottom
of the window.
Click on the Label node to select it and click the :button:`Create` button at
the bottom of the window.
.. image:: img/nodes_and_scenes_05_editor_with_label.webp
@@ -110,11 +111,11 @@ and the node's properties appear in the Inspector dock on the right.
Changing a node's properties
----------------------------
The next step is to change the Label's "Text" property. Let's change it to
"Hello World".
The next step is to change the Label's :inspector:`Text` property. Let's change
it to "Hello World".
Head to the Inspector dock on the right of the viewport. Click inside the field
below the Text property and type "Hello World".
below the :inspector:`Text` property and type "Hello World".
.. image:: img/nodes_and_scenes_06_label_text.webp
@@ -137,17 +138,18 @@ move it to the center of the view delimited by the rectangle.
Running the scene
-----------------
Everything's ready to run the scene! Press the **Run Current Scene** button in
the top-right of the screen or press :kbd:`F6` (:kbd:`Cmd + R` on macOS).
Everything's ready to run the scene! Press the :button:`Run Current Scene`
button in the top-right of the screen or press :kbd:`F6` (:kbd:`Cmd + R` on
macOS).
.. image:: img/nodes_and_scenes_09_play_scene_button.webp
A popup invites you to save the scene, which is required to run it.
Click the Save button in the file browser to save it as ``label.tscn``.
A popup invites you to save the scene, which is required to run it. Click the
:button:`Save` button in the file browser to save it as ``label.tscn``.
.. image:: img/nodes_and_scenes_10_save_scene_as.webp
.. note:: The Save Scene As dialog, like other file dialogs in the editor, only
.. note:: The :ui:`Save Scene As` dialog, like other file dialogs in the editor, only
allows you to save files inside the project. The ``res://`` path at
the top of the window represents the project's root directory and
stands for "resource path". For more information about file paths in
@@ -162,8 +164,8 @@ Close the window or press :kbd:`F8` (:kbd:`Cmd + .` on macOS) to quit the runnin
Setting the main scene
----------------------
To run our test scene, we used the **Run Current Scene** button. Another button
next to it, **Run Project**, allows you to set and run the project's
To run our test scene, we used the :button:`Run Current Scene` button. Another button
next to it, :button:`Run Project`, allows you to set and run the project's
**main scene**. You can also press :kbd:`F5` (:kbd:`Cmd + B` on macOS) to do so.
.. image:: img/nodes_and_scenes_12_play_button.webp
@@ -176,8 +178,8 @@ A popup window appears and invites you to select the main scene.
.. image:: img/nodes_and_scenes_13_main_scene_popup.webp
Click the Select button, and in the file dialog that appears, double click on
``label.tscn``.
Click the :button:`Select` button, and in the file dialog that appears, double
click on ``label.tscn``.
.. image:: img/nodes_and_scenes_14_select_main_scene.webp
@@ -186,9 +188,8 @@ will use this scene as a starting point.
.. note:: The editor saves the main scene's path in a project.godot file in your
project's directory. While you can edit this text file directly to
change project settings, you can also use the "Project -> Project
Settings" window to do so. For more information, see
:ref:`doc_project_settings`.
change project settings, you can also use the :menu:`Project > Project Settings`
window to do so. For more information, see :ref:`doc_project_settings`.
In the next part, we will discuss another key concept in games and in Godot:
creating instances of a scene.

BIN
img/control_gallery.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 84 KiB

BIN
tutorials/2d/img/2d_animation_new_spriteframes.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

BIN
tutorials/2d/img/2d_lights_and_shadows_create_canvastexture.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.6 KiB

After

Width:  |  Height:  |  Size: 6.6 KiB

BIN
tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.0 KiB

After

Width:  |  Height:  |  Size: 7.7 KiB

BIN
tutorials/2d/img/particles_material.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.9 KiB

After

Width:  |  Height:  |  Size: 12 KiB

BIN
tutorials/2d/img/using_tilesets_create_new_tileset.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.8 KiB

After

Width:  |  Height:  |  Size: 11 KiB

35
tutorials/3d/standard_material_3d.rst
View File

@@ -537,6 +537,8 @@ This controls how much light from the lit side (visible to light) is transferred
to the dark side (opposite from the light). This works well for thin objects
such as plant leaves, grass, human ears, etc.
.. image:: img/spatial_material22.png
Refraction
----------
@@ -741,14 +743,35 @@ Point Size
When drawing points, specify the point size in pixels.
Transmission
~~~~~~~~~~~~
Use Particle Trails
~~~~~~~~~~~~~~~~~~~
This controls how much light from the lit side (visible to light) is transferred
to the dark side (opposite from the light). This works well for thin objects
such as plant leaves, grass, human ears, etc.
If true, enables parts of the shader required for GPUParticles3D trails to function.
This also requires using a mesh with appropriate skinning, such as RibbonTrailMesh
or TubeTrailMesh. Enabling this feature outside of materials used in GPUParticles3D
meshes will break material rendering.
.. image:: img/spatial_material22.png
Use Z Clip Scale
~~~~~~~~~~~~~~~~
Scales the object being rendered towards the camera to avoid clipping into things
like walls. This is intended to be used for objects that are fixed with respect to
the camera like player arms, tools, etc. Lighting and shadows will continue to work
correctly when this setting is adjusted, but screen-space effects like SSAO and SSR
may break with lower scales. Therefore, try to keep this setting as close to 1.0 as
possible.
Use FOV Override
~~~~~~~~~~~~~~~~
Overrides the ``Camera3D``'s field of view angle (in degrees).
.. note::
This behaves as if the field of view is set on a ``Camera3D`` with
``Camera3D.keep_aspect`` set to ``Camera3D.KEEP_HEIGHT``. Additionally, it may not
look correct on a non-perspective camera where the field of view setting is
ignored.
Proximity and Distance Fade
---------------------------

2
tutorials/3d/using_transforms.rst
View File

@@ -305,7 +305,9 @@ Jump:
// Keep in mind Y is up-axis
if (Input.IsActionJustPressed("jump"))
{
velocity.Y = JumpSpeed;
}
MoveAndSlide();

247
tutorials/assets_pipeline/importing_3d_scenes/advanced_import_settings.rst Normal file
View File

@@ -0,0 +1,247 @@
.. _doc_advanced_import_settings:
Advanced Import Settings
========================
While the regular import panel provides many essential options for imported 3D
models, the advanced import settings provides per object options, model previews,
and animation previews. To open it select the :button:`Advanced...` button at the
bottom of the import dock.
.. figure:: img/importing_3d_scenes_advanced_import_settings_button.webp
:align: center
This is available for 3D models imported as scenes, as well as animation libraries.
.. note::
This page does not go over options also available in the import dock, or anything
outside of the advanced import settings. For information on those please read the
:ref:`doc_importing_3d_scenes_import_configuration` page.
Using the Advanced Import Settings dialog
-----------------------------------------
The first tab you'll see is the **Scene** tab. The options available in the
panel on the right are identical to the Import dock, but you have access to a 3D
preview. The 3D preview can be rotated by holding down the left mouse button
then dragging the mouse. Zoom can be adjusted using the mouse wheel.
.. figure:: img/importing_3d_scenes_advanced_import_settings_scene.webp
:align: center
:alt: Advanced Import Settings dialog (Scene tab)
Advanced Import Settings dialog (Scene tab).
Credit: `Modern Arm Chair 01 - Poly Haven <https://polyhaven.com/a/modern_arm_chair_01>`__
Configuring node import options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can select individual nodes that compose the scene while in the **Scene**
tab using the tree view at the left:
.. figure:: img/importing_3d_scenes_advanced_import_settings_node.webp
:align: center
:alt: Selecting a node in the Advanced Import Settings dialog (Scene tab)
Selecting a node in the Advanced Import Settings dialog (Materials tab)
This exposes several per-node import options:
- **Skip Import:** If checked, the node will not be present in the final
imported scene. Enabling this disables all other options.
- **Generate > Physics:** If checked, generates a PhysicsBody3D *parent* node
with collision shapes that are *siblings* to the MeshInstance3D node.
- **Generate > NavMesh:** If checked, generates a NavigationRegion3D *child*
node for :ref:`navigation <doc_navigation_overview_3d>`. **Mesh + NavMesh**
will keep the original mesh visible, while **NavMesh Only** will only import
the navigation mesh (without a visual representation). **NavMesh Only** is
meant to be used when you've manually authored a simplified mesh for navigation.
- **Generate > Occluder:** If checked, generates an OccluderInstance3D *sibling*
node for :ref:`occlusion culling <doc_occlusion_culling>` using the mesh's
geometry as a basis for the occluder's shape. **Mesh + Occluder** will keep
the original mesh visible, while **Occluder Only** will only import the
occluder (without a visual representation). **Occluder Only** is meant to be
used when you've manually authored a simplified mesh for occlusion culling.
These options are only visible if some of the above options are enabled:
- **Physics > Body Type:** Only visible if **Generate > Physics** is enabled.
Controls the PhysicsBody3D that should be created. **Static** creates a
StaticBody3D, **Dynamic** creates a RigidBody3D, **Area** creates an Area3D.
- **Physics > Shape Type:** Only visible if **Generate > Physics** is enabled.
**Trimesh** allows for precise per-triangle collision, but it can only be used
with a **Static** body type. Other types are less precise and may require
manual configuration, but can be used with any body type. For static level
geometry, use **Trimesh**. For dynamic geometry, use primitive shapes if
possible for better performance, or use one of the convex decomposition modes
if the shape is large and complex.
- **Decomposition > Advanced:** Only visible if **Physics > Shape Type** is
**Decompose Convex**. If checked, allows adjusting advanced decomposition
options. If disabled, only a preset **Precision** can be adjusted (which is
usually sufficient).
- **Decomposition > Precision:** Only visible if **Physics > Shape Type** is
**Decompose Convex**. Controls the precision to use for convex decomposition.
Higher values result in more detailed collision, at the cost of slower
generation and increased CPU usage during physics simulation. To improve
performance, it's recommended to keep this value as low as possible for your
use cases.
- **Occluder > Simplification Distance:** Only visible if **Generate >
Occluder** is set to **Mesh + Occluder** or **Occluder Only**. Higher values
result in an occluder mesh with fewer vertices (resulting in decreased CPU
utilization), at the cost of more occlusion culling issues (such as false
positives or false negatives). If you run into objects disappearing when they
shouldn't when the camera is near a certain mesh, try decreasing this value.
Configuring mesh and material import options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the Advanced Import Settings dialog, there are 2 ways to select individual
meshes or materials:
- Switch to the **Meshes** or **Materials** tab in the top-left corner of the dialog.
- Stay in the **Scene** tab, but unfold the options on the tree view on the
left. After choosing a mesh or material, this presents the same information as
the **Meshes** and **Materials** tabs, but in a tree view instead of a list.
If you select a mesh, different options will appear in the panel on the right:
.. figure:: img/importing_3d_scenes_advanced_import_settings_meshes.webp
:align: center
:alt: Advanced Import Settings dialog (Meshes tab)
Advanced Import Settings dialog (Meshes tab)
The options are as follows:
- **Save to File:** Saves the :ref:`class_Mesh` *resource* to an external file
(this isn't a scene file). You generally don't need to use this for placing
the mesh in a 3D scene – instead, you should instance the 3D scene directly.
However, having direct access to the Mesh resource is useful for specific
nodes, such as :ref:`class_MeshInstance3D`, :ref:`class_MultiMeshInstance3D`,
:ref:`class_GPUParticles3D` or :ref:`class_CPUParticles3D`.
- You will also need to specify an output file path using the option that
appears after enabling **Save to File**. It's recommended to use the ``.res``
output file extension for smaller file sizes and faster loading speeds, as
``.tres`` is inefficient for writing large amounts of data.
- **Generate > Shadow Meshes:** Per-mesh override for the **Meshes > Create
Shadow Meshes** scene-wide import option described in
:ref:`doc_importing_3d_scenes_using_the_import_dock`. **Default** will use the
scene-wide import option, while **Enable** or **Disable** can forcibly enable
or disable this behavior on a specific mesh.
- **Generate > Lightmap UV:** Per-mesh override for the **Meshes > Light
Baking** scene-wide import option described in
:ref:`doc_importing_3d_scenes_using_the_import_dock`. **Default** will use the
scene-wide import option, while **Enable** or **Disable** can forcibly enable
or disable this behavior on a specific mesh.
- Setting this to **Enable** on a scene with the **Static** light baking mode
is equivalent to configuring this mesh to use **Static Lightmaps**. Setting this
to **Disable** on a scene with the **Static Lightmaps** light baking mode is
equivalent to configuring this mesh to use **Static** instead.
- **Generate > LODs:** Per-mesh override for the **Meshes > Generate LODs**
scene-wide import option described in
:ref:`doc_importing_3d_scenes_using_the_import_dock`. **Default** will use the
scene-wide import option, while **Enable** or **Disable** can forcibly enable
or disable this behavior on a specific mesh.
- **LODs > Normal Merge Angle:** The minimum angle difference between two
vertices required to preserve a geometry edge in mesh LOD generation. If
running into visual issues with LOD generation, decreasing this value may help
(at the cost of less efficient LOD generation).
If you select a material, only one option will appear in the panel on the right:
.. figure:: img/importing_3d_scenes_advanced_import_settings_materials.webp
:align: center
:alt: Advanced Import Settings dialog (Materials tab)
Advanced Import Settings dialog (Materials tab)
When **Use External** is checked and an output path is specified, this lets you
use an external material instead of the material that is included in the
original 3D scene file; see the section below.
Extracting materials to separate files
--------------------------------------
While Godot can import materials authored in 3D modeling software, the default
configuration may not be suitable for your needs. For example:
- You want to configure material features not supported by your 3D application.
- You want to use a different texture filtering mode, as this option is
configured in the material since Godot 4.0 (and not in the image).
- You want to replace one of the materials with an entirely different material,
such as a custom shader.
To be able to modify the 3D scene's materials in the Godot editor, you need to
use *external* material resources.
In the top-left corner of the Advanced Import Settings dialog, choose
**Actions… > Extract Materials**:
.. figure:: img/importing_3d_scenes_advanced_import_settings_extract_materials.webp
:align: center
:alt: Extracting all built-in materials to external resources in the Advanced Import Settings dialog
Extracting all built-in materials to external resources in the Advanced Import Settings dialog
After choosing this option, select a folder to extract material ``.tres`` files
to, then confirm the extraction:
.. figure:: img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp
:align: center
:alt: Confirming material extraction in the Advanced Import Settings subdialog
Confirming material extraction in the Advanced Import Settings subdialog
.. note::
After extracting materials, the 3D scene will automatically be configured to
use external material references. As a result, you don't need to manually
enable **Use External** on every material to make the external ``.tres``
material effective.
When **Use External** is enabled, remember that the Advanced Import Settings
dialog will keep displaying the mesh's original materials (the ones designed in
the 3D modeling software). This means your customizations to the materials won't
be visible within this dialog. To preview your modified materials, you need to
place the imported 3D scene in another scene using the editor.
Godot will not overwrite changes made to extracted materials when the source 3D
scene is reimported. However, if the material name is changed in the source 3D
file, the link between the original material and the extracted material will be
lost. As a result, you'll need to use the Advanced Import Settings dialog to
associate the renamed material to the existing extracted material.
The above can be done in the dialog's **Materials** tab by selecting the
material, enabling **Save to File**, then specifying the save path using the
**Path** option that appears after enabling **Save to File**.
Animation options
-----------------
Several extra options are available for the generated :ref:`class_AnimationPlayer`
nodes, as well as their individual animations when they're selected in the
**Scene** tab.
Optimizer
~~~~~~~~~
When animations are imported, an optimizer is run, which reduces the size of the
animation considerably. In general, this should always be turned on unless you
suspect that an animation might be broken due to it being enabled.
Save to file
~~~~~~~~~~~~
By default, animations are saved as built-in. It is possible to save them to a
file instead. This allows adding custom tracks to the animations and keeping
them after a reimport.
Slices
~~~~~~
It is possible to specify multiple animations from a single timeline as slices.
For this to work, the model must have only one animation that is named
``default``. To create slices, change the slice amount to something greater than
zero. You can then name a slice, specify which frames it starts and stops on, and
choose whether the animation loops or not.

2
tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst
View File

@@ -21,7 +21,7 @@ Godot supports the following 3D *scene file formats*:
- FBX, supported via the `ufbx <https://github.com/ufbx/ufbx>`__ library. The
previous import workflow used `FBX2glTF <https://github.com/godotengine/FBX2glTF>`__
integration. This requires installing an external program that links against the
proprietary FBX SDK, so we recommend using the default ubfx method or other formats
proprietary FBX SDK, so we recommend using the default ufbx method or other formats
listed above (if suitable for your workflow).
Copy the scene file together with the textures and mesh data (if separate) to

BIN
tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_button.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.2 KiB

230
tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst
View File

@@ -40,7 +40,9 @@ This import process is customizable using 3 separate interfaces, depending on yo
FileSystem dock.
- The **Advanced Import Settings** dialog, which can be accessed by double-clicking
the 3D scene in the FileSystem dock or by clicking the **Advanced…** button in
the Import dock. This allows you to customize per-object options in Godot.
the Import dock. This allows you to customize per-object options in Godot, and
preview models and animations. please see the :ref:`doc_advanced_import_settings`
page for more information.
- :ref:`Import hints <doc_importing_3d_scenes_node_type_customization>`, which are special
suffixes added to object names in the 3D modeling software. This allows you to
customize per-object options in the 3D modeling software.
@@ -172,201 +174,6 @@ exported from other tools such as Maya.
Universal** and **Embed as Uncompressed** keeps the textures embedded in the
imported scene, with and without VRAM compression respectively.
Using the Advanced Import Settings dialog
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first tab you'll see is the **Scene** tab. The options available in the
panel on the right are identical to the Import dock, but you have access to a 3D
preview. The 3D preview can be rotated by holding down the left mouse button
then dragging the mouse. Zoom can be adjusted using the mouse wheel.
.. figure:: img/importing_3d_scenes_advanced_import_settings_scene.webp
:align: center
:alt: Advanced Import Settings dialog (Scene tab)
Advanced Import Settings dialog (Scene tab).
Credit: `Modern Arm Chair 01 - Poly Haven <https://polyhaven.com/a/modern_arm_chair_01>`__
**Configuring node import options**
You can select individual nodes that compose the scene while in the **Scene**
tab using the tree view at the left:
.. figure:: img/importing_3d_scenes_advanced_import_settings_node.webp
:align: center
:alt: Selecting a node in the Advanced Import Settings dialog (Scene tab)
Selecting a node in the Advanced Import Settings dialog (Materials tab)
This exposes several per-node import options:
- **Skip Import:** If checked, the node will not be present in the final
imported scene. Enabling this disables all other options.
- **Generate > Physics:** If checked, generates a PhysicsBody3D *parent* node
with collision shapes that are *siblings* to the MeshInstance3D node.
- **Generate > NavMesh:** If checked, generates a NavigationRegion3D *child*
node for :ref:`navigation <doc_navigation_overview_3d>`. **Mesh + NavMesh**
will keep the original mesh visible, while **NavMesh Only** will only import
the navigation mesh (without a visual representation). **NavMesh Only** is
meant to be used when you've manually authored a simplified mesh for navigation.
- **Generate > Occluder:** If checked, generates an OccluderInstance3D *sibling*
node for :ref:`occlusion culling <doc_occlusion_culling>` using the mesh's
geometry as a basis for the occluder's shape. **Mesh + Occluder** will keep
the original mesh visible, while **Occluder Only** will only import the
occluder (without a visual representation). **Occluder Only** is meant to be
used when you've manually authored a simplified mesh for occlusion culling.
These options are only visible if some of the above options are enabled:
- **Physics > Body Type:** Only visible if **Generate > Physics** is enabled.
Controls the PhysicsBody3D that should be created. **Static** creates a
StaticBody3D, **Dynamic** creates a RigidBody3D, **Area** creates an Area3D.
- **Physics > Shape Type:** Only visible if **Generate > Physics** is enabled.
**Trimesh** allows for precise per-triangle collision, but it can only be used
with a **Static** body type. Other types are less precise and may require
manual configuration, but can be used with any body type. For static level
geometry, use **Trimesh**. For dynamic geometry, use primitive shapes if
possible for better performance, or use one of the convex decomposition modes
if the shape is large and complex.
- **Decomposition > Advanced:** Only visible if **Physics > Shape Type** is
**Decompose Convex**. If checked, allows adjusting advanced decomposition
options. If disabled, only a preset **Precision** can be adjusted (which is
usually sufficient).
- **Decomposition > Precision:** Only visible if **Physics > Shape Type** is
**Decompose Convex**. Controls the precision to use for convex decomposition.
Higher values result in more detailed collision, at the cost of slower
generation and increased CPU usage during physics simulation. To improve
performance, it's recommended to keep this value as low as possible for your
use cases.
- **Occluder > Simplification Distance:** Only visible if **Generate >
Occluder** is set to **Mesh + Occluder** or **Occluder Only**. Higher values
result in an occluder mesh with fewer vertices (resulting in decreased CPU
utilization), at the cost of more occlusion culling issues (such as false
positives or false negatives). If you run into objects disappearing when they
shouldn't when the camera is near a certain mesh, try decreasing this value.
**Configuring mesh and material import options**
In the Advanced Import Settings dialog, there are 2 ways to select individual
meshes or materials:
- Switch to the **Meshes** or **Materials** tab in the top-left corner of the dialog.
- Stay in the **Scene** tab, but unfold the options on the tree view on the
left. After choosing a mesh or material, this presents the same information as
the **Meshes** and **Materials** tabs, but in a tree view instead of a list.
If you select a mesh, different options will appear in the panel on the right:
.. figure:: img/importing_3d_scenes_advanced_import_settings_meshes.webp
:align: center
:alt: Advanced Import Settings dialog (Meshes tab)
Advanced Import Settings dialog (Meshes tab)
The options are as follows:
- **Save to File:** Saves the :ref:`class_Mesh` *resource* to an external file
(this isn't a scene file). You generally don't need to use this for placing
the mesh in a 3D scene – instead, you should instance the 3D scene directly.
However, having direct access to the Mesh resource is useful for specific
nodes, such as :ref:`class_MeshInstance3D`, :ref:`class_MultiMeshInstance3D`,
:ref:`class_GPUParticles3D` or :ref:`class_CPUParticles3D`.
- You will also need to specify an output file path using the option that
appears after enabling **Save to File**. It's recommended to use the ``.res``
output file extension for smaller file sizes and faster loading speeds, as
``.tres`` is inefficient for writing large amounts of data.
- **Generate > Shadow Meshes:** Per-mesh override for the **Meshes > Create
Shadow Meshes** scene-wide import option described in
:ref:`doc_importing_3d_scenes_using_the_import_dock`. **Default** will use the
scene-wide import option, while **Enable** or **Disable** can forcibly enable
or disable this behavior on a specific mesh.
- **Generate > Lightmap UV:** Per-mesh override for the **Meshes > Light
Baking** scene-wide import option described in
:ref:`doc_importing_3d_scenes_using_the_import_dock`. **Default** will use the
scene-wide import option, while **Enable** or **Disable** can forcibly enable
or disable this behavior on a specific mesh.
- Setting this to **Enable** on a scene with the **Static** light baking mode
is equivalent to configuring this mesh to use **Static Lightmaps**. Setting this
to **Disable** on a scene with the **Static Lightmaps** light baking mode is
equivalent to configuring this mesh to use **Static** instead.
- **Generate > LODs:** Per-mesh override for the **Meshes > Generate LODs**
scene-wide import option described in
:ref:`doc_importing_3d_scenes_using_the_import_dock`. **Default** will use the
scene-wide import option, while **Enable** or **Disable** can forcibly enable
or disable this behavior on a specific mesh.
- **LODs > Normal Merge Angle:** The minimum angle difference between two
vertices required to preserve a geometry edge in mesh LOD generation. If
running into visual issues with LOD generation, decreasing this value may help
(at the cost of less efficient LOD generation).
If you select a material, only one option will appear in the panel on the right:
.. figure:: img/importing_3d_scenes_advanced_import_settings_materials.webp
:align: center
:alt: Advanced Import Settings dialog (Materials tab)
Advanced Import Settings dialog (Materials tab)
When **Use External** is checked and an output path is specified, this lets you
use an external material instead of the material that is included in the
original 3D scene file; see the section below.
Extracting materials to separate files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
While Godot can import materials authored in 3D modeling software, the default
configuration may not be suitable for your needs. For example:
- You want to configure material features not supported by your 3D application.
- You want to use a different texture filtering mode, as this option is
configured in the material since Godot 4.0 (and not in the image).
- You want to replace one of the materials with an entirely different material,
such as a custom shader.
To be able to modify the 3D scene's materials in the Godot editor, you need to
use *external* material resources.
In the top-left corner of the Advanced Import Settings dialog, choose
**Actions… > Extract Materials**:
.. figure:: img/importing_3d_scenes_advanced_import_settings_extract_materials.webp
:align: center
:alt: Extracting all built-in materials to external resources in the Advanced Import Settings dialog
Extracting all built-in materials to external resources in the Advanced Import Settings dialog
After choosing this option, select a folder to extract material ``.tres`` files
to, then confirm the extraction:
.. figure:: img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp
:align: center
:alt: Confirming material extraction in the Advanced Import Settings subdialog
Confirming material extraction in the Advanced Import Settings subdialog
.. note::
After extracting materials, the 3D scene will automatically be configured to
use external material references. As a result, you don't need to manually
enable **Use External** on every material to make the external ``.tres``
material effective.
When **Use External** is enabled, remember that the Advanced Import Settings
dialog will keep displaying the mesh's original materials (the ones designed in
the 3D modeling software). This means your customizations to the materials won't
be visible within this dialog. To preview your modified materials, you need to
place the imported 3D scene in another scene using the editor.
Godot will not overwrite changes made to extracted materials when the source 3D
scene is reimported. However, if the material name is changed in the source 3D
file, the link between the original material and the extracted material will be
lost. As a result, you'll need to use the Advanced Import Settings dialog to
associate the renamed material to the existing extracted material.
The above can be done in the dialog's **Materials** tab by selecting the
material, enabling **Save to File**, then specifying the save path using the
**Path** option that appears after enabling **Save to File**.
.. _doc_importing_3d_scenes_import_script:
Using import scripts for automation
@@ -450,14 +257,18 @@ match, with support for ``?`` and ``*`` wildcards (using
The script must start with an animation filter statement (as denoted by the line
beginning with an ``@``). For example, if we would like to apply filters to all
imported animations which have a name ending in ``"_Loop"``::
imported animations which have a name ending in ``"_Loop"``:
.. code:: text
@+*_Loop
Similarly, additional patterns can be added to the same line, separated by
commas. Here is a modified example to additionally *include* all animations with
names that begin with ``"Arm_Left"``, but also *exclude* all animations which
have names ending in ``"Attack"``::
have names ending in ``"Attack"``:
.. code:: text
@+*_Loop, +Arm_Left*, -*Attack
@@ -489,29 +300,6 @@ would be retained.
Any track filter lines that do not begin with a ``+`` or ``-`` are ignored.
Storage
~~~~~~~
By default, animations are saved as built-in. It is possible to save them to a
file instead. This allows adding custom tracks to the animations and keeping
them after a reimport.
Optimizer
~~~~~~~~~
When animations are imported, an optimizer is run, which reduces the size of the
animation considerably. In general, this should always be turned on unless you
suspect that an animation might be broken due to it being enabled.
Clips
~~~~~
It is possible to specify multiple animations from a single timeline as clips.
For this to work, the model must have only one animation that is named
``default``. To create clips, change the clip amount to something greater than
zero. You can then name a clip, specify which frames it starts and stops on, and
choose whether the animation loops or not.
Scene inheritance
-----------------

1
tutorials/assets_pipeline/importing_3d_scenes/index.rst
View File

@@ -21,6 +21,7 @@ dialog, and inherited scenes.
model_export_considerations
node_type_customization
import_configuration
advanced_import_settings
.. seealso::

85
tutorials/assets_pipeline/importing_audio_samples.rst
View File

@@ -10,16 +10,15 @@ Godot provides 3 options to import your audio data: WAV, Ogg Vorbis and MP3.
Each format has different advantages:
- WAV files use raw data or light compression (IMA-ADPCM or QOA). Currently
they can only be imported in raw format, but Godot allows compression after
import. They are lightweight to play back on the CPU (hundreds of simultaneous
voices in this format are fine). The downside is that they take up a lot of disk space.
- Ogg Vorbis files use a stronger compression that results in much
smaller file size, but require significantly more processing power to
play back.
- MP3 files use better compression than WAV with IMA-ADPCM or QOA, but worse
than Ogg Vorbis. This means that an MP3 file with roughly equal quality to
Ogg Vorbis will be significantly larger. On the bright side, MP3 requires
- WAV files use raw data or light compression (IMA ADPCM or Quite OK Audio). Currently
they can only be imported in raw format, but Godot allows compression after import.
They are lightweight to play back on the CPU (hundreds of simultaneous voices
in this format are fine). The downside is that they take up a lot of disk space.
- Ogg Vorbis files use a stronger compression that results in much smaller file
size, but require significantly more processing power to play back.
- MP3 files use better compression than WAV with IMA ADPCM or Quite OK Audio, but
worse than Ogg Vorbis. This means that an MP3 file with roughly equal quality
to Ogg Vorbis will be significantly larger. On the bright side, MP3 requires
less CPU usage to play back compared to Ogg Vorbis.
.. note::
@@ -30,23 +29,23 @@ Each format has different advantages:
Here is a comparative chart representing the file size of 1 second of audio with
each format:
+-----------------------------+-------------------+
| Format | 1 second of audio |
+=============================+===================+
| WAV 24-bit, 96 kHz, stereo | 576 KB |
+-----------------------------+-------------------+
| WAV 16-bit, 44 kHz, mono | 88 KB |
+-----------------------------+-------------------+
| WAV IMA-ADPCM, 44 kHz, mono | 22 KB |
+-----------------------------+-------------------+
| WAV QOA, 44 kHz, mono | 17 KB |
+-----------------------------+-------------------+
| MP3 192 Kb/s, stereo | 24 KB |
+-----------------------------+-------------------+
| Ogg Vorbis 128 Kb/s, stereo | 16 KB |
+-----------------------------+-------------------+
| Ogg Vorbis 96 Kb/s, stereo | 12 KB |
+-----------------------------+-------------------+
+------------------------------+-------------------+
| Format | 1 second of audio |
+==============================+===================+
| WAV 24-bit, 96 kHz, stereo | 576 KB |
+------------------------------+-------------------+
| WAV 16-bit, 44 kHz, mono | 88 KB |
+------------------------------+-------------------+
| WAV IMA ADPCM, 44 kHz, mono | 22 KB |
+------------------------------+-------------------+
| Quite OK Audio, 44 kHz, mono | 17 KB |
+------------------------------+-------------------+
| MP3 192 Kb/s, stereo | 24 KB |
+------------------------------+-------------------+
| Ogg Vorbis 128 Kb/s, stereo | 16 KB |
+------------------------------+-------------------+
| Ogg Vorbis 96 Kb/s, stereo | 12 KB |
+------------------------------+-------------------+
Note that the MP3 and Ogg Vorbis figures can vary depending on the encoding
type. The above figures use :abbr:`CBR (Constant Bit Rate)` encoding for
@@ -125,8 +124,8 @@ saving to a waveform, which increases their size unnecessarily and add latency
to the moment they are played back.
Enabling **Trim** will automatically trim the beginning and end of the audio if
it's lower than -50 dB *after* normalization (see **Edit > Normalize** below). A
fade-in/fade-out period of 500 samples is also used during trimming to avoid
it's lower than -50 dB *after* normalization (see **Edit > Normalize** below).
A fade-in/fade-out period of 500 samples is also used during trimming to avoid
audible pops.
Edit > Normalize
@@ -143,13 +142,15 @@ Unlike Ogg Vorbis and MP3, WAV files can contain metadata to indicate whether
they're looping (in addition to loop points). By default, Godot will follow this
metadata, but you can choose to apply a specific loop mode:
- **Detect from WAV:** Uses loop information from the WAV metadata.
- **Disabled:** Don't loop audio, even if metadata indicates the file should be
played back looping.
- **Forward:** Standard audio looping.
- **Ping-Pong:** Play audio forward until it's done playing, then play it
backward and repeat. This is similar to mirrored texture repeat, but for
audio.
- **Backward:** Play audio in reverse and loop back to the end when done playing.
- **Forward:** Standard audio looping. Plays the audio forward from the beginning
to the loop end, then returns to the loop beginning and repeats.
- **Ping-Pong:** Plays the audio forward until the loop end, then backwards to
the loop beginning, repeating this cycle.
- **Backward:** Plays the audio backwards from the loop end to the loop beginning,
then repeats.
When choosing one of the **Forward**, **Ping-Pong** or **Backward** loop modes,
loop points can also be defined to make only a specific part of the sound loop.
@@ -166,12 +167,12 @@ the end of the audio file if set to ``-1``.
Compress > Mode
---------------
Three compression modes can be chosen from for WAV files: **Disabled** (default),
**RAM (Ima-ADPCM)**, or **QOA (Quite OK Audio)**. **RAM (Ima-ADPCM)** reduces
file size and memory usage a little, at the cost of decreasing quality in an
audible manner. **QOA (Quite OK Audio)** reduces file size a bit more than
**RAM (Ima-ADPCM)** and the quality decrease is much less noticeable, at the
cost of higher CPU usage (still much lower than MP3).
Three compression modes can be chosen from for WAV files: **PCM (Uncompressed)**,
**IMA ADPCM**, or **Quite OK Audio** (default). **IMA ADPCM** reduces file size
and memory usage a little, at the cost of decreasing quality in an audible manner.
**Quite OK Audio** reduces file size a bit more than **IMA ADPCM** and the quality
decrease is much less noticeable, at the cost of slightly higher CPU usage (still
much lower than MP3).
Ogg Vorbis and MP3 don't decrease quality as much and can provide greater file
size reductions, at the cost of higher CPU usage during playback. This higher
@@ -265,8 +266,8 @@ music tracks).
.. note::
Unlike WAV files, Ogg Vorbis and MP3 only support a "loop begin" loop point,
not a "loop end" point. Looping can also be only be standard forward
looping, not ping-pong or backward.
not a "loop end" point. Looping can also be only be standard forward looping,
not ping-pong or backward.
.. _doc_importing_audio_samples_best_practices:

2
tutorials/assets_pipeline/importing_images.rst
View File

@@ -27,7 +27,7 @@ Godot can import the following image formats:
- Truevision Targa (``.tga``)
- SVG (``.svg``)
- SVGs are rasterized using `ThorVG <https://www.thorvg.org/>`__
when importing them. `Support is limited <https://www.thorvg.org/about#:~:text=among%20the%20svg%20tiny%20specs%2C%20yet%20unsupported%20features%20in%20the%20thorvg%20are%20the%20following>`__;
when importing them. `Support is limited <https://www.thorvg.org/about#:~:text=certain%20features%20remain%20unsupported%20within%20the%20current%20framework>`__;
complex vectors may not render correctly. :ref:`Text must be converted to paths <doc_importing_images_svg_text>`;
otherwise, it won't appear in the rasterized image.
You can check whether ThorVG can render a certain vector correctly using its

88
tutorials/assets_pipeline/importing_translations.rst
View File

@@ -31,86 +31,16 @@ each string. This allows you to revise the text while it is being
translated to other languages. The unique ID can be a number, a string,
or a string with a number (it's just a unique string anyway).
.. note:: If you need a more powerful file format, Godot also supports
loading translations written in the gettext ``.po`` format. See
:ref:`doc_localization_using_gettext` for details.
Translation format
------------------
Supported formats
-----------------
To complete the picture and allow efficient support for translations,
Godot has a special importer that can read CSV files. Most spreadsheet
editors can export to this format, so the only requirement is that the files
have a special arrangement. The CSV files **must** be saved with UTF-8 encoding
without a `byte order mark <https://en.wikipedia.org/wiki/Byte_order_mark>`__.
editors can export to this format, so the only requirement is that the
files have a special arrangement. See
:ref:`doc_localization_using_spreadsheets` for detailed info on
formatting and importing CSVs.
CSV files must be formatted as follows:
+--------+----------+----------+----------+
| keys | <lang1> | <lang2> | <langN> |
+========+==========+==========+==========+
| KEY1 | string | string | string |
+--------+----------+----------+----------+
| KEY2 | string | string | string |
+--------+----------+----------+----------+
| KEYN | string | string | string |
+--------+----------+----------+----------+
The "lang" tags must represent a language, which must be one of the :ref:`valid
locales <doc_locales>` supported by the engine, or they must start with an underscore (`_`),
which means the related column is served as comment and won't be imported.
The "KEY" tags must be unique and represent a string universally (they are usually in
uppercase, to differentiate from other strings). These keys will be replaced at
runtime by the matching translated string. Note that the case is important,
"KEY1" and "Key1" will be different keys.
The top-left cell is ignored and can be left empty or having any content.
Here's an example:
+-------+-----------------------+------------------------+------------------------------+
| keys | en | es | ja |
+=======+=======================+========================+==============================+
| GREET | Hello, friend! | Hola, amigo! | こんにちは |
+-------+-----------------------+------------------------+------------------------------+
| ASK | How are you? | Cómo está? | 元気ですか |
+-------+-----------------------+------------------------+------------------------------+
| BYE | Goodbye | Adiós | さようなら |
+-------+-----------------------+------------------------+------------------------------+
| QUOTE | "Hello" said the man. | "Hola" dijo el hombre. | 「こんにちは」男は言いました |
+-------+-----------------------+------------------------+------------------------------+
The same example is shown below as a comma-separated plain text file,
which should be the result of editing the above in a spreadsheet.
When editing the plain text version, be sure to enclose with double
quotes any message that contains commas, line breaks or double quotes,
so that commas are not parsed as delimiters, line breaks don't create new
entries and double quotes are not parsed as enclosing characters. Be sure
to escape any double quotes a message may contain by preceding them with
another double quote. Alternatively, you can select another delimiter than
comma in the import options.
.. code-block:: none
keys,en,es,ja
GREET,"Hello, friend!","Hola, amigo!",こんにちは
ASK,How are you?,Cómo está?,元気ですか
BYE,Goodbye,Adiós,さようなら
QUOTE,"""Hello"" said the man.","""Hola"" dijo el hombre.",「こんにちは」男は言いました
CSV importer
------------
Godot will treat CSV files as translations by default. It will import them
and generate one or more compressed translation resource files next to it.
Importing will also add the translation to the list of
translations to load when the game runs, specified in project.godot (or the
project settings). Godot allows loading and removing translations at
runtime as well.
Select the ``.csv`` file and access the **Import** dock to define import
options. You can toggle the compression of the imported translations, and
select the delimiter to use when parsing the CSV file.
.. image:: img/import_csv.webp
Be sure to click **Reimport** after any change to these options.
If you need a more powerful file format, Godot also supports loading
translations written in the gettext ``.po`` format. See
:ref:`doc_localization_using_gettext` for details.

4
tutorials/best_practices/godot_notifications.rst
View File

@@ -166,7 +166,9 @@ delta time methods as needed.
public void _Process(double delta)
{
if (Input.IsActionJustPressed("ui_select"))
{
GD.Print(delta);
}
}
// Called during every input event. Equally true for _input().
@@ -176,7 +178,9 @@ delta time methods as needed.
{
case InputEventKey:
if (Input.IsActionJustPressed("ui_accept"))
{
GD.Print(GetProcessDeltaTime());
}
break;
}
}

78
tutorials/editor/command_line_tutorial.rst
View File

@@ -43,17 +43,19 @@ given build type.
**General options**
+----------------------------+-----------------------------------------------------------------------------+
| Command | Description |
+----------------------------+-----------------------------------------------------------------------------+
| ``-h``, ``--help`` | |release| Display the list of command line options. |
+----------------------------+-----------------------------------------------------------------------------+
| ``--version`` | |release| Display the version string. |
+----------------------------+-----------------------------------------------------------------------------+
| ``-v``, ``--verbose`` | |release| Use verbose stdout mode. |
+----------------------------+-----------------------------------------------------------------------------+
| ``-q``, ``--quiet`` | |release| Quiet mode, silences stdout messages. Errors are still displayed. |
+----------------------------+-----------------------------------------------------------------------------+
+----------------------------+-------------------------------------------------------------------------------+
| Command | Description |
+----------------------------+-------------------------------------------------------------------------------+
| ``-h``, ``--help`` | |release| Display the list of command line options. |
+----------------------------+-------------------------------------------------------------------------------+
| ``--version`` | |release| Display the version string. |
+----------------------------+-------------------------------------------------------------------------------+
| ``-v``, ``--verbose`` | |release| Use verbose stdout mode. |
+----------------------------+-------------------------------------------------------------------------------+
| ``-q``, ``--quiet`` | |release| Quiet mode, silences stdout messages. Errors are still displayed. |
+----------------------------+-------------------------------------------------------------------------------+
| ``--no-header`` | |release| Do not print engine version and rendering method header on startup. |
+----------------------------+-------------------------------------------------------------------------------+
**Run options**
@@ -66,6 +68,9 @@ given build type.
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-p``, ``--project-manager`` | |editor| Start the Project Manager, even if a project is auto-detected. |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--recovery-mode`` | |editor| "Start the editor in recovery mode, which disables features that can typically cause startup crashes, such as tool scripts, editor plugins, |
| | GDExtension addons, and others. |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--debug-server <uri>`` | |editor| Start the editor debug server (``<protocol>://<host/IP>[:<port>]``, e.g. ``tcp://127.0.0.1:6007``) |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--dap-port <port>`` | |editor| Use the specified port for the GDScript Debug Adapter Protocol. Recommended port range ``[1024, 49151]``. |
@@ -81,6 +86,8 @@ given build type.
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--path <directory>`` | |release| Path to a project (``<directory>`` must contain a 'project.godot' file). |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``scene <path>`` | |release| Path or UID of a scene in the project that should be started. |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-u``, ``--upwards`` | |release| Scan folders upwards for 'project.godot' file. |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--main-pack <file>`` | |release| Path to a pack (.pck) file to load. |
@@ -96,6 +103,9 @@ given build type.
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--display-driver <driver>`` | |release| Display driver (and rendering driver). Use ``--help`` first to display the list of available drivers. |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--audio-output-latency`` <ms> | |release| Override audio output latency in milliseconds (default is 15 ms). Lower values make sound playback more reactive but increase CPU usage, and may |
| | result in audio cracking if the CPU can't keep up |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--rendering-method <renderer>`` | |release| Renderer name. Requires driver support. |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--rendering-driver <driver>`` | |release| Rendering driver (depends on display driver). Use ``--help`` first to display the list of available drivers. |
@@ -108,6 +118,9 @@ given build type.
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--headless`` | |release| Enable headless mode (``--display-driver headless --audio-driver Dummy``). Useful for servers and with ``--script``. |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--log-file`` | |release| Write output/error log to the specified path instead of the default location defined by the project. <file> path should be absolute or relative to |
| | the project directory. |
+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--write-movie <file>`` | |release| Run the engine in a way that a movie is written (usually with .avi or .png extension). |
| | ``--fixed-fps`` is forced when enabled, but can be used to change movie FPS. |
| | ``--disable-vsync`` can speed up movie writing but makes interaction more difficult. |
@@ -137,6 +150,11 @@ given build type.
+------------------------------------+----------------------------------------------------------------------------+
| ``--xr-mode <mode>`` | |release| Select XR mode ('default', 'off', 'on'). |
+------------------------------------+----------------------------------------------------------------------------+
| ``--wid <window_id>`` | |release| Request parented to window. |
+------------------------------------+----------------------------------------------------------------------------+
| ``--accessibility <mode>`` | |release| Select accessibility mode ['auto' (when screen reader is running,|
| | default), 'always', 'disabled']. |
+------------------------------------+----------------------------------------------------------------------------+
**Debug options**
@@ -147,6 +165,8 @@ given build type.
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``-b``, ``--breakpoints`` | |release| Breakpoint list as source::line comma-separated pairs, no spaces (use ``%20`` instead). |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--ignore-error-breaks`` | |release| If debugger is connected, prevents sending error breakpoints. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--profiling`` | |release| Enable profiling in the script debugger. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--gpu-profile`` | |release| Show a GPU profile of the tasks that took the most time during frame rendering. |
@@ -155,6 +175,16 @@ given build type.
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--gpu-abort`` | |debug| Abort on GPU errors (usually validation layer errors), may help see the problem if your system freezes. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--generate-spirv-debug-info``| |debug| Generate SPIR-V debug information. This allows source-level shader debugging with RenderDoc. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--extra-gpu-memory-tracking``| |debug| Enables additional memory tracking (see class reference for |
| | `RenderingDevice.get_driver_and_device_memory_report()` and linked methods). Currently only implemented for |
| | Vulkan. Enabling this feature may cause crashes on some systems due to buggy drivers or bugs in the Vulkan |
| | Loader. See https://github.com/godotengine/godot/issues/95967 |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--accurate-breadcrumbs`` | |debug| Force barriers between breadcrumbs. Useful for narrowing down a command causing GPU resets. Currently |
| | only implemented for Vulkan. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--remote-debug <uri>`` | |release| Remote debug (``<protocol>://<host/IP>[:<port>]``, e.g. ``tcp://127.0.0.1:6007``). |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--single-threaded-scene`` | |release| Scene tree runs in single-threaded mode. Sub-thread groups are disabled and run on the main thread. |
@@ -169,7 +199,14 @@ given build type.
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--debug-stringnames`` | |debug| Print all StringName allocations to stdout when the engine quits. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--frame-delay <ms>`` | |release| Simulate high CPU load (delay each frame by <ms> milliseconds). |
| ``--debug-canvas-item-redraw`` | |debug| Display a rectangle each time a canvas item requests a redraw (useful to troubleshoot low processor |
| | mode). |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--max-fps <fps>`` | |release| Set a maximum number of frames per second rendered (can be used to limit power usage). A value of 0 |
| | results in unlimited framerate. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--frame-delay <ms>`` | |release| Simulate high CPU load (delay each frame by <ms> milliseconds). Do not use as a FPS limiter; use |
| | --max-fps instead. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--time-scale <scale>`` | |release| Force time scale (higher values are faster, 1.0 is normal speed). |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
@@ -186,6 +223,8 @@ given build type.
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--print-fps`` | |release| Print the frames per second to the stdout. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
| ``--editor-pseudolocalization``| |editor| Enable pseudolocalization for the editor and the project manager. |
+--------------------------------+-----------------------------------------------------------------------------------------------------------------+
**Standalone tools**
@@ -195,19 +234,27 @@ given build type.
| ``-s``, ``--script <script>`` | |release| Run a script. ``<script>`` must be a resource path relative to the project (``myscript.gd`` will be interpreted as ``res://myscript.gd``) |
| | or an absolute filesystem path (for example on Windows ``C:/tmp/myscript.gd``) |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--main-loop <main_loop_name>`` | |release| Run a MainLoop specified by its global class name. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--check-only`` | |release| Only parse for errors and quit (use with ``--script``). |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--import`` | |editor| Starts the editor, waits for any resources to be imported, and then quits. Implies ``--editor`` and ``--quit``. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--export-release <preset> <path>`` | |editor| Export the project using the given preset and matching release template. The preset name should match one defined in export_presets.cfg. |
| ``--export-release <preset> <path>`` | |editor| Export the project in release mode using the given preset and output path. The preset name should match one defined in 'export_presets.cfg'. |
| | ``<path>`` should be absolute or relative to the project directory, and include the filename for the binary (e.g. 'builds/game.exe'). The target |
| | directory should exist. Implies ``--import``. |
| | directory must exist. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--export-debug <preset> <path>`` | |editor| Like ``--export-release``, but use debug template. Implies ``--import``. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--export-pack <preset> <path>`` | |editor| Like ``--export-release``, but only export the game pack for the given preset. The ``<path>`` extension determines whether it will be in PCK |
| | or ZIP format. Implies ``--import``. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--export-patch <preset> <path>`` | |editor| Export pack with changed files only. See --export-pack description for other considerations. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--patches <paths>`` | |editor| List of patches to use with --export-patch. The list is comma-separated. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--install-android-build-template`` | |editor| Install the Android build template. Used in conjunction with --export-release or --export-debug. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--convert-3to4 [<max_file_kb>] [<max_line_size>]`` | |editor| Convert project from Godot 3.x to Godot 4.x. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]`` | |editor| Show what elements will be renamed when converting project from Godot 3.x to Godot 4.x. |
@@ -232,6 +279,9 @@ given build type.
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--benchmark-file <path>`` | |editor| Benchmark the run time and save it to a given file in JSON format. The path should be absolute. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
|``--test [--help]`` | |editor| Run unit tests. Use --test --help for more information. |
+------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
Path
----

2
tutorials/editor/project_settings.rst
View File

@@ -120,7 +120,7 @@ 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
that setting. This means that if you 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

87
tutorials/export/changing_application_icon_for_windows.rst
View File

@@ -1,34 +1,24 @@
.. _doc_changing_application_icon_for_windows:
Changing application icon for Windows
=====================================
Manually changing application icon for Windows
==============================================
By default, the exported project's icon will be the Godot icon.
You will most likely want to change that for your project. There are two types
of icons that can be changed on Windows: the file icon and the taskbar icon.
Windows applications use a Windows only format called ICO for their file icon and
taskbar icon. Since Godot 4.1, Godot can create an ICO file for you based on the
icon file defined in the Windows export preset. Supported formats are PNG, WebP,
and SVG. If no icon is defined in the Windows export preset, the
:ref:`application/config/icon <class_ProjectSettings_property_application/config/icon>`
project setting is used automatically instead.
This means you no longer need to follow the steps in this section to
manually create an ICO file, unless you wish to have control over the icon
design depending on its displayed size.
Creating a custom ICO file
--------------------------
.. note::
Since Godot 4.1, Godot can create an ICO file for you based on the icon file
defined in the Windows export preset. This icon file can be in PNG, WebP or
SVG format. If no icon is defined in the Windows export preset, the
:ref:`application/config/icon <class_ProjectSettings_property_application/config/icon>`
project setting is used automatically instead.
This means you no longer need to follow the steps in this section to
manually create an ICO file, unless you wish to have control over the icon
design depending on its displayed size. Note that even if Godot creates the
ICO file for you, you still need to
:ref:`set up rcedit <doc_changing_application_icon_for_windows_changing_the_file_icon>`
so that the file icon actually changes.
Windows does not use formats such as PNG or JPEG for application icons. Instead,
it uses a Windows-only format called ICO. You can create your application icon
in any program but you will have to convert it to an ICO file using a program such
as GIMP.
You can create your application icon in any program but you will have to convert it
to an ICO file using a program such as GIMP.
`This video tutorial <https://www.youtube.com/watch?v=uqV3UfM-n5Y>`_ goes over how to
export an ICO file with GIMP.
@@ -79,65 +69,18 @@ use the ``Icon`` setting.
Changing the file icon
----------------------
In Godot 3.5 and later, you can change the file icon without
external tools using `godoticon <https://github.com/pkowal1982/godoticon>`__.
Changing the file icon this way should work for executables containing
an embedded PCK.
The file icon is the icon of the executable that you click on to start
the project.
.. image:: img/icon_file_icon.png
Before selecting it in the export options, you will need to install
an extra tool called **rcedit**.
You can download it `here <https://github.com/electron/rcedit/releases>`_.
After downloading, you need to tell Godot the path to the rcedit executable
on your computer.
Go to **Editor > Editor Settings > Export > Windows**.
Click on the folder icon for the **rcedit** entry.
Navigate to and select the rcedit executable.
.. note::
Linux and macOS users will also need to install
`WINE <https://www.winehq.org/>`_ to use rcedit.
On macOS, make sure to use a 64-bit version of both WINE and rcedit since
32-bit applications aren't supported anymore.
.. image:: img/icon_rcedit.webp
You should now have everything in place to change the file icon.
To do that, you will need to specify the icon when exporting.
Go to **Project > Export**. Assuming you have already created
a Windows Desktop preset, select your icon in ICO format in
the **Application > Icon** field.
.. warning::
All the supplied metadata must be valid. Most importantly, the version
identifiers **must** take the form ``major.minor.patch.revision`` where
every component is required and is a positive integer. For instance,
``1.2.0.0`` is valid but ``1.2.0`` is not.
If you provide invalid metadata in the export preset, the application icon
won't change as rcedit will fail to change the executable's metadata.
.. image:: img/icon_export_settings.webp
.. note::
If rcedit fails to change the icon, you can instead
:ref:`compile your own Windows export templates <doc_compiling_for_windows>`
with the icon changed. To do so, replace
`platform/windows/godot.ico <https://github.com/godotengine/godot/blob/master/platform/windows/godot.ico>`__
with your own ICO file *before* compiling export templates.
Once this is done, you can specify your export templates as custom export
templates in your project's Windows export preset.
Testing the result
------------------
@@ -147,6 +90,6 @@ You can now export the project. If it worked correctly, you should see this:
.. note::
If your icon isn't showing up properly, on Windows 10, try clearing the icon
If your icon isn't showing up properly try clearing the icon
cache. To do so, open the **Run** dialog and enter ``ie4uinit.exe
-ClearIconCache`` or ``ie4uinit.exe -show``.

2
tutorials/export/exporting_for_android.rst
View File

@@ -21,7 +21,7 @@ The following steps detail what is needed to set up the Android SDK and the engi
Install OpenJDK 17
------------------
Download and install `OpenJDK 17 <https://adoptium.net/temurin/releases/?variant=openjdk17>`__.
Download and install `OpenJDK 17 <https://adoptium.net/temurin/releases/?variant=openjdk17&version=17&os=any&arch=any>`__.
.. note::

6
tutorials/export/exporting_for_dedicated_servers.rst
View File

@@ -3,6 +3,8 @@
Exporting for dedicated servers
===============================
.. highlight:: none
If you want to run a dedicated server for your project on a machine that doesn't
have a GPU or display server available, you'll need to run Godot with the ``headless``
display server and ``Dummy`` :ref:`audio driver <class_ProjectSettings_property_audio/driver/driver>`.
@@ -129,8 +131,6 @@ use **Keep** for that particular image.
With the above options used, a PCK for the client (which exports all resources
normally) will look as follows:
.. highlight:: none
::
.
@@ -159,8 +159,6 @@ normally) will look as follows:
The PCK's file structure for the server will look as follows:
.. highlight:: none
::
.

8
tutorials/export/exporting_for_windows.rst
View File

@@ -21,10 +21,10 @@ binary that is smaller, faster and does not contain the editor and debugger.
Changing the executable icon
----------------------------
To change the exported executable icon from the default Godot icon,
you need to set up a tool called *rcedit*. Godot will then call this tool
on export automatically. This process is documented in
:ref:`doc_changing_application_icon_for_windows`.
Godot will automatically use whatever image is set as your project's icon in the project
settings, and convert it to an ICO file for the exported project. If you want to
manually create an ICO file for greater control over how the icon looks at different
resolutions then see the :ref:`doc_changing_application_icon_for_windows` page.
Code signing
------------

8
tutorials/export/feature_tags.rst
View File

@@ -108,6 +108,10 @@ Here is a list of most feature tags in Godot. Keep in mind they are **case-sensi
+--------------------+----------------------------------------------------------+
| **web** | Host OS is a Web browser |
+--------------------+----------------------------------------------------------+
| **nothreads** | Running without threading support |
+--------------------+----------------------------------------------------------+
| **threads** | Running with threading support |
+--------------------+----------------------------------------------------------+
| **web_android** | Host OS is a Web browser running on Android |
+--------------------+----------------------------------------------------------+
| **web_ios** | Host OS is a Web browser running on iOS |
@@ -153,6 +157,10 @@ field in the *export preset* used to generate it:
running the project from the editor, even if the export preset marked as
**Runnable** for your current platform has custom feature tags defined.
Custom feature tags are also not used in :ref:`class_EditorExportPlugin`
scripts. Instead, feature tags in :ref:`class_EditorExportPlugin`
will reflect the device the editor is currently running on.
Overriding project settings
---------------------------

BIN
tutorials/export/img/icon_rcedit.webp
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

BIN
tutorials/export/img/windows_editor_settings.webp
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 12 KiB

BIN
tutorials/i18n/img/icu_data.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 53 KiB

0
tutorials/assets_pipeline/img/import_csv.webp → tutorials/i18n/img/import_csv.webp
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.3 KiB

After

Width:  |  Height:  |  Size: 6.3 KiB

1
tutorials/i18n/index.rst
View File

@@ -8,6 +8,7 @@ Internationalization
:name: toc-learn-features-i18n
internationalizing_games
localization_using_spreadsheets
localization_using_gettext
locales
pseudolocalization

10
tutorials/i18n/internationalizing_games.rst
View File

@@ -311,11 +311,13 @@ It is possible to override text and control layout direction by using the follow
Adding break iterator data to exported project
----------------------------------------------
Some languages are written without spaces, and word and line breaking requires more than rules over character sequences.
Godot includes ICU rule and dictionary based, break iterator data, but this data is not included into exported projects by default.
To include it go to **Project → Project Settings → Localization → Text Server Data** and click **Install support data...**. Break iterator data is about 4 MB large.
Some languages are written without spaces. In those languages,
word and line breaking require more than rules over character sequences.
Godot includes ICU rule and dictionary-based break iterator data, but this data
is not included in exported projects by default.
.. image:: img/icu_data.png
To include it, go to **Project → Project Settings**, enable **Internationalization → Locale → Include Text Server Data**,
then export the project. Break iterator data is about 4 MB in size.
Structured text BiDi override
-----------------------------

7
tutorials/i18n/localization_using_gettext.rst
View File

@@ -3,9 +3,10 @@
Localization using gettext
==========================
In addition to :ref:`doc_importing_translations` in CSV format, Godot
also supports loading translation files written in the GNU gettext
format (text-based ``.po`` and compiled ``.mo`` since Godot 4.0).
In addition to importing translations in
:ref:`CSV format <doc_localization_using_spreadsheets>`, Godot also
supports loading translation files written in the GNU gettext format
(text-based ``.po`` and compiled ``.mo`` since Godot 4.0).
.. note:: For an introduction to gettext, check out
`A Quick Gettext Tutorial <https://www.labri.fr/perso/fleury/posts/programming/a-quick-gettext-tutorial.html>`_.

94
tutorials/i18n/localization_using_spreadsheets.rst Normal file
View File

@@ -0,0 +1,94 @@
.. _doc_localization_using_spreadsheets:
Localization using spreadsheets
===============================
Spreadsheets are one of the most common formats for localizing games.
In Godot, spreadsheets are supported through the CSV format. This
guide explains how to work with CSVs.
The CSV files **must** be saved with UTF-8 encoding
without a `byte order mark <https://en.wikipedia.org/wiki/Byte_order_mark>`__.
.. warning::
By default, Microsoft Excel will always save CSV files with ANSI encoding
rather than UTF-8. There is no built-in way to do this, but there are
workarounds as described
`here <https://stackoverflow.com/questions/4221176/excel-to-csv-with-utf8-encoding>`__.
We recommend using `LibreOffice <https://www.libreoffice.org/>`__ or Google Sheets instead.
Formatting
----------
CSV files must be formatted as follows:
+--------+----------+----------+----------+
| keys | <lang1> | <lang2> | <langN> |
+========+==========+==========+==========+
| KEY1 | string | string | string |
+--------+----------+----------+----------+
| KEY2 | string | string | string |
+--------+----------+----------+----------+
| KEYN | string | string | string |
+--------+----------+----------+----------+
The "lang" tags must represent a language, which must be one of the :ref:`valid
locales <doc_locales>` supported by the engine, or they must start with an underscore (`_`),
which means the related column is served as comment and won't be imported.
The "KEY" tags must be unique and represent a string universally (they are usually in
uppercase, to differentiate from other strings). These keys will be replaced at
runtime by the matching translated string. Note that the case is important,
"KEY1" and "Key1" will be different keys.
The top-left cell is ignored and can be left empty or having any content.
Here's an example:
+-------+-----------------------+------------------------+------------------------------+
| keys | en | es | ja |
+=======+=======================+========================+==============================+
| GREET | Hello, friend! | Hola, amigo! | こんにちは |
+-------+-----------------------+------------------------+------------------------------+
| ASK | How are you? | Cómo está? | 元気ですか |
+-------+-----------------------+------------------------+------------------------------+
| BYE | Goodbye | Adiós | さようなら |
+-------+-----------------------+------------------------+------------------------------+
| QUOTE | "Hello" said the man. | "Hola" dijo el hombre. | 「こんにちは」男は言いました |
+-------+-----------------------+------------------------+------------------------------+
The same example is shown below as a comma-separated plain text file,
which should be the result of editing the above in a spreadsheet.
When editing the plain text version, be sure to enclose with double
quotes any message that contains commas, line breaks or double quotes,
so that commas are not parsed as delimiters, line breaks don't create new
entries and double quotes are not parsed as enclosing characters. Be sure
to escape any double quotes a message may contain by preceding them with
another double quote. Alternatively, you can select another delimiter than
comma in the import options.
.. code-block:: none
keys,en,es,ja
GREET,"Hello, friend!","Hola, amigo!",こんにちは
ASK,How are you?,Cómo está?,元気ですか
BYE,Goodbye,Adiós,さようなら
QUOTE,"""Hello"" said the man.","""Hola"" dijo el hombre.",「こんにちは」男は言いました
CSV importer
------------
Godot will treat CSV files as translations by default. It will import them
and generate one or more compressed translation resource files next to it.
Importing will also add the translation to the list of
translations to load when the game runs, specified in project.godot (or the
project settings). Godot allows loading and removing translations at
runtime as well.
Select the ``.csv`` file and access the **Import** dock to define import
options. You can toggle the compression of the imported translations, and
select the delimiter to use when parsing the CSV file.
.. image:: img/import_csv.webp
Be sure to click **Reimport** after any change to these options.

2
tutorials/inputs/handling_quit_requests.rst
View File

@@ -32,7 +32,9 @@ Handling the notification is done as follows (on any node):
public override void _Notification(int what)
{
if (what == NotificationWMCloseRequest)
{
GetTree().Quit(); // default behavior
}
}
It is important to note that by default, Godot apps have the built-in

4
tutorials/inputs/inputevent.rst
View File

@@ -27,8 +27,12 @@ Here is a quick example, closing your game if the escape key is hit:
public override void _UnhandledInput(InputEvent @event)
{
if (@event is InputEventKey eventKey)
{
if (eventKey.Pressed && eventKey.Keycode == Key.Escape)
{
GetTree().Quit();
}
}
}
However, it is cleaner and more flexible to use the provided :ref:`InputMap <class_InputMap>` feature,

4
tutorials/inputs/mouse_and_input_coordinates.rst
View File

@@ -44,9 +44,13 @@ for example:
{
// Mouse in viewport coordinates.
if (@event is InputEventMouseButton eventMouseButton)
{
GD.Print("Mouse Click/Unclick at: ", eventMouseButton.Position);
}
else if (@event is InputEventMouseMotion eventMouseMotion)
{
GD.Print("Mouse Motion at: ", eventMouseMotion.Position);
}
// Print the size of the viewport.
GD.Print("Viewport Resolution is: ", GetViewport().GetVisibleRect().Size);

BIN
tutorials/navigation/img/path_clip_and_limits.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 307 KiB

BIN
tutorials/navigation/img/path_postprocess_diff.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
tutorials/navigation/img/path_simplification_diff.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

13
tutorials/navigation/navigation_using_navigationagents.rst
View File

@@ -17,6 +17,10 @@ New NavigationAgent nodes will automatically join the default navigation map on
NavigationsAgent nodes are optional and not a hard requirement to use the navigation system.
Their entire functionality can be replaced with scripts and direct calls to the NavigationServer API.
.. tip::
For more advanced uses consider :ref:`doc_navigation_using_navigationpathqueryobjects` over NavigationAgent nodes.
NavigationAgent Pathfinding
---------------------------
@@ -505,7 +509,7 @@ The following sections provides script templates for nodes commonly used with Na
@export var movement_speed: float = 4.0
@onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D")
var movement_delta: float
var physics_delta: float
func _ready() -> void:
navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed))
@@ -514,22 +518,23 @@ The following sections provides script templates for nodes commonly used with Na
navigation_agent.set_target_position(movement_target)
func _physics_process(delta):
# Save the delta for use in _on_velocity_computed.
physics_delta = delta
# Do not query when the map has never synchronized and is empty.
if NavigationServer3D.map_get_iteration_id(navigation_agent.get_navigation_map()) == 0:
return
if navigation_agent.is_navigation_finished():
return
movement_delta = movement_speed * delta
var next_path_position: Vector3 = navigation_agent.get_next_path_position()
var new_velocity: Vector3 = global_position.direction_to(next_path_position) * movement_delta
var new_velocity: Vector3 = global_position.direction_to(next_path_position) * movement_speed
if navigation_agent.avoidance_enabled:
navigation_agent.set_velocity(new_velocity)
else:
_on_velocity_computed(new_velocity)
func _on_velocity_computed(safe_velocity: Vector3) -> void:
global_position = global_position.move_toward(global_position + safe_velocity, movement_delta)
global_position = global_position.move_toward(global_position + safe_velocity, physics_delta * movement_speed)
.. code-tab:: gdscript CharacterBody3D

249
tutorials/navigation/navigation_using_navigationpathqueryobjects.rst
View File

@@ -3,14 +3,22 @@
Using NavigationPathQueryObjects
================================
.. tip::
Path query parameters expose various options to improve pathfinding performance or lower memory consumption.
They cater to more advanced pathfinding needs that the high-level nodes can not always cover.
See the respective option sections below.
``NavigationPathQueryObjects`` can be used together with ``NavigationServer.query_path()``
to obtain a heavily **customized** navigation path including optional **meta data** about the path.
to obtain a heavily **customized** navigation path including optional **metadata** about the path.
This requires more setup compared to obtaining a normal NavigationPath but lets you tailor
the pathfinding and provided path data to the different needs of a project.
NavigationPathQueryObjects consist of a pair of objects, a ``NavigationPathQueryParameters`` object holding the customization options
for the query and a ``NavigationPathQueryResult`` that receives (regular) updates with the resulting path and meta data from the query.
for the query and a ``NavigationPathQueryResult`` that receives (regular) updates with the resulting path and metadata from the query.
2D and 3D versions of ``NavigationPathQueryParameters`` are available as
:ref:`NavigationPathQueryParameters2D<class_NavigationPathQueryParameters2D>` and
@@ -20,18 +28,26 @@ for the query and a ``NavigationPathQueryResult`` that receives (regular) update
:ref:`NavigationPathQueryResult2D<class_NavigationPathQueryResult2D>` and
:ref:`NavigationPathQueryResult3D<class_NavigationPathQueryResult3D>` respectively.
Creating a basic path query
---------------------------
Both parameters and result are used as a pair with the ``NavigationServer.query_path()`` function.
For the available customization options and their use see the class doc of the parameters.
For the available customization options, see further below. See also the descriptions for each parameter in the class reference.
While not a strict requirement, both objects are intended to be created once in advance, stored in a
persistent variable for the agent and reused for every followup path query with updated parameters.
This reuse avoids performance implications from frequent object creation if a project
has a large quantity of simultaneous agents that regularly update their paths.
Reusing the same objects improves performance when frequently creating objects or allocating memory.
The following script creates the objects and provides a ``query_path()`` function to create new navigation paths.
The resulting path is identical to using ``NavigationServer.map_get_path()`` while reusing the objects.
.. tabs::
.. code-tab:: gdscript 2D GDScript
extends Node2D
# Prepare query objects.
var query_parameters := NavigationPathQueryParameters2D.new()
var query_result := NavigationPathQueryResult2D.new()
@@ -40,7 +56,13 @@ has a large quantity of simultaneous agents that regularly update their paths.
if not is_inside_tree():
return PackedVector2Array()
query_parameters.map = get_world_2d().get_navigation_map()
var map: RID = get_world_2d().get_navigation_map()
if NavigationServer2D.map_get_iteration_id(map) == 0:
# This map has never synced and is empty, no point in querying it.
return PackedVector2Array()
query_parameters.map = map
query_parameters.start_position = p_start_position
query_parameters.target_position = p_target_position
query_parameters.navigation_layers = p_navigation_layers
@@ -50,9 +72,10 @@ has a large quantity of simultaneous agents that regularly update their paths.
return path
.. code-tab:: gdscript 3D GDScript
extends Node3D
# Prepare query objects.
var query_parameters := NavigationPathQueryParameters3D.new()
var query_result := NavigationPathQueryResult3D.new()
@@ -61,7 +84,13 @@ has a large quantity of simultaneous agents that regularly update their paths.
if not is_inside_tree():
return PackedVector3Array()
query_parameters.map = get_world_3d().get_navigation_map()
var map: RID = get_world_3d().get_navigation_map()
if NavigationServer3D.map_get_iteration_id(map) == 0:
# This map has never synced and is empty, no point in querying it.
return PackedVector3Array()
query_parameters.map = map
query_parameters.start_position = p_start_position
query_parameters.target_position = p_target_position
query_parameters.navigation_layers = p_navigation_layers
@@ -70,3 +99,207 @@ has a large quantity of simultaneous agents that regularly update their paths.
var path: PackedVector3Array = query_result.get_path()
return path
Path postprocessing options
---------------------------
.. figure:: img/path_postprocess_diff.webp
:align: center
:alt: Path post-processing differences depending on navigation mesh polygon layout
Path post-processing differences depending on navigation mesh polygon layout.
A path query search travels from the closest navigation mesh polygon edge to the closest edge along the available polygons.
If possible it builds a polygon corridor towards the target position polygon.
This raw "search" polygon corridor path is not very optimized and usually a bad fit for agents to travel along.
E.g. the closest edge point on a navigation mesh polygon might cause a huge detour for agents on larger polygons.
In order to improve the quality of paths returned by the query various ``path_postprocessing`` options exist.
- The ``PATH_POSTPROCESSING_CORRIDORFUNNEL`` post-processing shortens paths by funneling paths around corners **inside the available polygon corridor**.
This is the default post-processing and usually also the most useful as it gives the shortest path result **inside the available polygon corridor**.
If the polygon corridor is already suboptimal, e.g. due to a suboptimal navigation mesh layout,
the funnel can snap to unexpected polygon corners causing detours.
- The ``PATH_POSTPROCESSING_EDGECENTERED`` post-processing forces all path points to be placed in the middle of the crossed polygon edges **inside the available polygon corridor**.
This post-processing is usually only useful when used with strictly tile-like navigation mesh polygons that are all
evenly sized and where the expected path following is also constrained to cell centers,
e.g. typical grid game with movement constrained to grid cell centers.
- The ``PATH_POSTPROCESSING_NONE`` post-processing returns the path as is how the pathfinding traveled **inside the available polygon corridor**.
This post-processing is very useful for debug as it shows how the path search traveled from closest edge point to closet edge point and what polygons it picked.
A lot of unexpected or suboptimal path results can be immediately explained by looking at this raw path and polygon corridor.
Path simplification
-------------------
.. tip::
Path simplification can help steering agents or agents that jitter on thin polygon edges.
.. figure:: img/path_simplification_diff.webp
:align: center
:alt: Path point difference with or without path simplification
Path point difference with or without path simplification.
If ``simplify_path`` is enabled a variant of the Ramer-Douglas-Peucker path simplification algorithm is applied to the path.
This algorithm straightens paths by removing less relevant path points depending on the ``simplify_epsilon`` used.
Path simplification helps with all kinds of agent movement problems in "open fields" that are caused by having many unnecessary polygon edges.
E.g. a terrain mesh when baked to a navigation mesh can cause an excessive polygon count due to all the small (but for pathfinding almost meaningless) height variations in the terrain.
Path simplification also helps with "steering" agents because they only have more critical corner path points to aim for.
.. Warning::
Path simplification is an additional final post-processing of the path. It adds extra performance costs to the query so only enable when actually needed.
.. note::
Path simplification is exposed on the NavigationServer as a generic function. It can be used outside of navigation queries for all kinds of position arrays as well.
Path metadata
-------------
.. tip::
Disabling unneeded path metadata options can improve performance and lower memory consumption.
A path query can return additional metadata for every path point.
- The ``PATH_METADATA_INCLUDE_TYPES`` flag collects an array with the primitive information about the point owners, e.g. if a point belongs to a region or link.
- The ``PATH_METADATA_INCLUDE_RIDS`` flag collects an array with the :ref:`RIDs<class_RID>` of the point owners. Depending on point owner primitive, these RIDs can be used with the various NavigationServer functions related to regions or links.
- The ``PATH_METADATA_INCLUDE_OWNERS`` flag collects an array with the ``ObjectIDs`` of the point owners. These object IDs can be used with :ref:`@GlobalScope.instance_from_id()<class_@GlobalScope_method_instance_from_id>` to retrieve the node behind that object instance, e.g. a NavigationRegion or NavigationLink node.
By default all path metadata is collected as this metadata can be essential for more advanced navigation gameplay.
- E.g. to know what path point maps to what object or node owner inside the SceneTree.
- E.g. to know if a path point is the start or end of a navigation link that requires scripted takeover.
For the most basic path uses metadata is not always needed.
Path metadata collection can be selectively disabled to gain some performance and reduce memory consumption.
Excluding or including regions
------------------------------
.. tip::
Region filters can greatly help with performance on large navigation maps that are region partitioned.
Query parameters allow limiting the pathfinding to specific region navigation meshes.
If a large navigation map is well partitioned into smaller regions this can greatly help with performance as the
query can skip a large number of polygons at one of the earliest checks in the path search.
- By default and if left empty all regions of the queried navigation map are included.
- If a region :ref:`RID<class_RID>` is added to the ``excluded_regions`` array the region's navigation mesh will be ignored in the path search.
- If a region :ref:`RID<class_RID>` is added to the ``included_regions`` array the region's navigation mesh will be considered in the path search and also all other regions not included will be ignored as well.
- If a region ends up both included and excluded it is considered excluded.
Region filters are very effective for performance when paired with navigation region chunks that are aligned on a grid.
This way the filter can be set to only include the start position chunk and surrounding chunks instead of the entire navigation map.
Even if the target might be outside these surrounding chunks (can always add more "rings") the pathfinding will
try to create a path to the polygon closest to the target.
This usually creates half-paths heading in the general direction that are good enough,
all for a fraction of the performance cost of a full map search.
The following addition to the basic path query script showcases the idea how to integrate a region chunk mapping with the region filters.
This is not a full working example.
.. tabs::
.. code-tab:: gdscript 2D GDScript
extends Node2D
# ...
var chunk_id_to_region_rid: Dictionary[Vector2i, RID] = {}
func query_path(p_start_position: Vector2, p_target_position: Vector2, p_navigation_layers: int = 1) -> PackedVector2Array:
# ...
var regions_around_start_position: Array[RID] = []
var chunk_rings: int = 1 # Increase for very small regions or more quality.
var start_chunk_id: Vector2i = floor(p_start_position / float(chunk_size))
for y: int in range(start_chunk_id.y - chunk_rings, start_chunk_id.y + chunk_rings):
for x: int in range(start_chunk_id.x - chunk_rings, start_chunk_id.x + chunk_rings):
var chunk_id: Vector2i = Vector2i(x, y)
if chunk_id_to_region_rid.has(chunk_id):
var region: RID = chunk_id_to_region_rid[chunk_id]
regions_around_start_position.push_back(region)
query_parameters.included_regions = regions_around_start_position
# ...
.. code-tab:: gdscript 3D GDScript
extends Node3D
# ...
var chunk_id_to_region_rid: Dictionary[Vector3i, RID] = {}
func query_path(p_start_position: Vector3, p_target_position: Vector3, p_navigation_layers: int = 1) -> PackedVector3Array:
# ...
var regions_around_start_position: Array[RID] = []
var chunk_rings: int = 1 # Increase for very small regions or more quality.
var start_chunk_id: Vector3i = floor(p_start_position / float(chunk_size))
var y: int = 0 # Assume a planar navigation map for simplicity.
for z: int in range(start_chunk_id.z - chunk_rings, start_chunk_id.z + chunk_rings):
for x: int in range(start_chunk_id.x - chunk_rings, start_chunk_id.x + chunk_rings):
var chunk_id: Vector3i = Vector3i(x, y, z)
if chunk_id_to_region_rid.has(chunk_id):
var region: RID = chunk_id_to_region_rid[chunk_id]
regions_around_start_position.push_back(region)
query_parameters.included_regions = regions_around_start_position
# ...
Path clipping and limits
------------------------
.. tip::
Sensibly set limits can greatly help with performance on large navigation maps, especially when targets end up being unreachable.
.. figure:: img/path_clip_and_limits.gif
:align: center
:alt: Clipping returned paths to specific distances
Clipping returned paths to specific distances.
Query parameters allow clipping returned paths to specific lengths.
These options clip the path as a part of post-processing. The path is still searched as if at full length,
so it will have the same quality.
Path length clipping can be helpful in creating paths that better fit constrained gameplay, e.g. tactical games with limited movement ranges.
- The ``path_return_max_length`` property can be used to clip the returned path to a specific max length.
- The ``path_return_max_radius`` property can be used to clip the returned path inside a circle (2D) or sphere (3D) radius around the start position.
Query parameters allow limiting the path search to only search up to a specific distance or a specific number of searched polygons.
These options are for performance and affect the path search directly.
- The ``path_search_max_distance`` property can be used to stop the path search when going over this distance from the start position.
- The ``path_search_max_polygons`` property can be used to stop the path search when going over this searched polygon number.
When the path search is stopped by reaching a limit the path resets and creates a path from the start position polygon
to the polygon found so far that is closest to the target position.
.. warning::
While good for performance, if path search limit values are set too low they can affect the path quality very negatively.
Depending on polygon layout and search pattern the returned paths might go into completely wrong directions instead of the direction of the target.

2
tutorials/networking/high_level_multiplayer.rst
View File

@@ -102,7 +102,7 @@ High-level networking in Godot is managed by the :ref:`SceneTree <class_SceneTre
Each node has a ``multiplayer`` property, which is a reference to the ``MultiplayerAPI`` instance configured for it
by the scene tree. Initially, every node is configured with the same default ``MultiplayerAPI`` object.
It is possible to create a new ``MultiplayerAPI`` object and assign it to a ``NodePath`` in the the scene tree,
It is possible to create a new ``MultiplayerAPI`` object and assign it to a ``NodePath`` in the scene tree,
which will override ``multiplayer`` for the node at that path and all of its descendants.
This allows sibling nodes to be configured with different peers, which makes it possible to run a server
and a client simultaneously in one instance of Godot.

10
tutorials/networking/websocket.rst
View File

@@ -99,9 +99,7 @@ This example will show you how to create a WebSocket connection to a remote serv
This will print something similar to:
.. highlight:: none
::
.. code:: text
Connecting to wss://echo.websocket.org...
< Got text data from server: Request served by 7811941c69e658
@@ -113,8 +111,6 @@ Minimal server example
This example will show you how to create a WebSocket server that listens for remote connections, and how to send and receive data.
.. highlight:: gdscript
::
extends Node
@@ -178,9 +174,7 @@ This example will show you how to create a WebSocket server that listens for rem
When a client connects, this will print something similar to this:
.. highlight:: none
::
.. code:: text
Server started.
+ Peer 2 connected.

20
tutorials/physics/physics_introduction.rst
View File

@@ -202,7 +202,9 @@ or ``set_collision_mask_value(layer_number, value)`` on any given :ref:`Collisio
collider.set_collision_mask_value(3, true)
collider.set_collision_mask_value(4, true)
Export annotations can be used to export bitmasks in the editor with a user-friendly GUI::
Export annotations can be used to export bitmasks in the editor with a user-friendly GUI:
::
@export_flags_2d_physics var layers_2d_physics
@@ -316,15 +318,23 @@ For example, here is the code for an "Asteroids" style spaceship:
public override void _IntegrateForces(PhysicsDirectBodyState2D state)
{
if (Input.IsActionPressed("ui_up"))
{
state.ApplyForce(_thrust.Rotated(Rotation));
}
else
{
state.ApplyForce(new Vector2());
}
var rotationDir = 0;
if (Input.IsActionPressed("ui_right"))
{
rotationDir += 1;
}
if (Input.IsActionPressed("ui_left"))
{
rotationDir -= 1;
}
state.ApplyTorque(rotationDir * _torque);
}
}
@@ -441,7 +451,9 @@ Or to bounce off of the colliding object:
{
var collisionInfo = MoveAndCollide(_velocity * (float)delta);
if (collisionInfo != null)
{
_velocity = _velocity.Bounce(collisionInfo.GetNormal());
}
}
}
@@ -510,11 +522,17 @@ the ground (including slopes) and jump when standing on the ground:
var jump = Input.IsActionPressed("ui_select");
if (IsOnFloor() && jump)
{
velocity.Y = _jumpSpeed;
}
if (right)
{
velocity.X += _runSpeed;
}
if (left)
{
velocity.X -= _runSpeed;
}
Velocity = velocity;
}

2
tutorials/physics/ray-casting.rst
View File

@@ -134,7 +134,9 @@ be empty. If it did hit something, it will contain collision information:
.. code-tab:: csharp
if (result.Count > 0)
{
GD.Print("Hit at point: ", result["position"]);
}
The ``result`` dictionary when a collision occurs contains the following
data:

34
tutorials/physics/soft_body.rst
View File

@@ -2,8 +2,8 @@
.. _doc_soft_body:
Using SoftBody
==============
Using SoftBody3D
================
Soft bodies (or *soft-body dynamics*) simulate movement, changing shape and other physical properties of deformable objects.
This can for example be used to simulate cloth or to create more realistic characters.
@@ -15,7 +15,7 @@ A :ref:`SoftBody3D <class_SoftBody3D>` node is used for soft body simulations.
We will create a bouncy cube to demonstrate the setup of a soft body.
Create a new scene with a ``Node3D`` node as root. Then, create a ``Softbody`` node. Add a ``CubeMesh`` in the ``mesh`` property of the node in the inspector and increase the subdivision of the mesh for simulation.
Create a new scene with a ``Node3D`` node as root. Then, create a ``SoftBody3D`` node. Add a ``CubeMesh`` in the ``mesh`` property of the node in the inspector and increase the subdivision of the mesh for simulation.
.. image:: img/softbody_cube.png
@@ -36,9 +36,9 @@ Let's make a cloak in the Platformer3D demo.
.. note:: You can download the Platformer3D demo on `GitHub <https://github.com/godotengine/godot-demo-projects/tree/master/3d/platformer>`_ or `the Asset Library <https://godotengine.org/asset-library/asset/2748>`_.
Open the ``Player`` scene, add a ``SoftBody`` node and assign a ``PlaneMesh`` to it.
Open the ``Player`` scene, add a ``SoftBody3D`` node and assign a ``PlaneMesh`` to it.
Open the ``PlaneMesh`` properties and set the size(x: 0.5 y: 1) then set ``Subdivide Width`` and ``Subdivide Depth`` to 5. Adjust the ``SoftBody``'s position. You should end up with something like this:
Open the ``PlaneMesh`` properties and set the size(x: 0.5 y: 1) then set ``Subdivide Width`` and ``Subdivide Depth`` to 5. Adjust the ``SoftBody3D``'s position. You should end up with something like this:
.. image:: img/softbody_cloak_subdivide.png
@@ -50,15 +50,15 @@ Add a :ref:`BoneAttachment3D <class_BoneAttachment3D>` node under the skeleton n
.. image:: img/softbody_cloak_bone_attach.png
To create pinned joints, select the upper vertices in the ``SoftBody`` node:
To create pinned joints, select the upper vertices in the ``SoftBody3D`` node:
.. image:: img/softbody_cloak_pinned.png
The pinned joints can be found in ``SoftBody``'s ``Attachments`` property, choose the ``BoneAttachment`` as the ``SpatialAttachment`` for each pinned joints, the pinned joints are now attached to the neck.
The pinned joints can be found in ``SoftBody3D``'s ``Attachments`` property, choose the ``BoneAttachment`` as the ``SpatialAttachment`` for each pinned joints, the pinned joints are now attached to the neck.
.. image:: img/softbody_cloak_pinned_attach.png
Last step is to avoid clipping by adding the Kinematic Body `Player` to ``Parent Collision Ignore`` of the ``SoftBody``.
Last step is to avoid clipping by adding the Kinematic Body `Player` to ``Parent Collision Ignore`` of the ``SoftBody3D``.
.. image:: img/softbody_cloak_ignore.png
@@ -67,3 +67,21 @@ Play the scene and the cloak should simulate correctly.
.. image:: img/softbody_cloak_finish.png
This covers the basic settings of softbody, experiment with the parameters to achieve the effect you are aiming for when making your game.
Using Imported Meshes
~~~~~~~~~~~~~~~~~~~~~
The **Save to File** option in the Advanced Import Settings dialog allows you
to save a mesh to a standalone resource file that you can then attach to
``SoftBody3D`` nodes.
You may also want to disable LOD generation or change the LOD generation options
when importing a mesh for use with ``SoftBody3D``. The default import settings
will produce an LOD that merges adjacent faces that are nearly flat with
respect to each other, even at very close render distances. This works well for
static meshes, but is often undesirable for use with ``SoftBody3D`` if you want
these faces to be able to bend and move with respect to each other, instead of
being rendered as a single plane.
See :ref:`doc_importing_3d_scenes_import_configuration` and :ref:`doc_mesh_lod`
for more details.

2
tutorials/physics/using_character_body_2d.rst
View File

@@ -508,7 +508,9 @@ Here's the code for the player body:
// Handle jump.
if (Input.IsActionJustPressed("jump") && IsOnFloor())
{
velocity.Y = _jumpSpeed;
}
// Get the input direction.
float direction = Input.GetAxis("ui_left", "ui_right");

Some files were not shown because too many files have changed in this diff Show More