diff --git a/.mailmap b/.mailmap index 3ad8821532d..5f4dd94676e 100644 --- a/.mailmap +++ b/.mailmap @@ -1,3 +1,4 @@ +31 <31eee384@gmail.com> <331300+31@users.noreply.github.com> Andreas Haas Andrew Conrad Andrii Doroshenko @@ -6,11 +7,16 @@ Chris Bradfield clayjohn clayjohn corrigentia <20541985+corrigentia@users.noreply.github.com> +DeeJayLSP +DeeJayLSP <60024671+DeeJayLSP@users.noreply.github.com> Frido Frido <43795127+mega-bit@users.noreply.github.com> +Hana - Piralein <48352564+Piralein@users.noreply.github.com> +hpnrep6 <57055412+hpnrep6@users.noreply.github.com> Hugo Locurcio Hugo Locurcio Ignacio Etcheverry +jsjtxietian Julian Murgia Kelly Thomas Leon Krause @@ -19,12 +25,18 @@ Max Hilbrunner Max Hilbrunner Michael Alexsander Nathan Lovato +Patrick Exner +Patrick Exner Paul Joannon <437025+paulloz@users.noreply.github.com> +Poommetee Ketson Rémi Verschelde -skyace65 -skyace65 +skyace65 +skyace65 +skyace65 +TheYellowArchitect TwistedTwigleg Will Nations -Yuri Roubinsky -Yuri Sizov +Yuri Rubinsky +Yuri Sizov +Yuri Sizov <11782833+YuriSizov@users.noreply.github.com> ZX-WT diff --git a/AUTHORS.md b/AUTHORS.md index 8a87aeb6f6c..6743ea6a9a0 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -14,23 +14,32 @@ name is available. (in alphabetical order, with over 10 commits excluding merges) + 31 Aaron Franke (aaronfranke) + Adam Scott (adamscott) Andrew Conrad (her001) Andrii Doroshenko (Xrayez) Arman (puchik) + AThousandShips Bastiaan Olij (BastiaanOlij) bitbutter + bruvzg Camille Mohr-Daurat (pouleyKetchoupp) Chris Bradfield (cbscribe) Clay John (clayjohn) corrigentia + Danil Alexeev (dalexeev) + Douglas Leão (DeeJayLSP) Fabio Alessandrelli (Faless) FeralBytes + Fredia Huya-Kouadio (m4gr3d) Frido (mega-bit) George Marques (vnen) Gerrit Großkopf (Grosskopf) Griatch + Hana - Piralein (Piralein) Haoyu Qiu (timothyqiu) + hpnrep6 Hugo Locurcio (Calinou) Ignacio Roldán Etcheverry (neikeq) Jérôme Gully (Nutriz) @@ -38,16 +47,24 @@ name is available. Julian Murgia (StraToN) Kelly Thomas (KellyThomas) Leon Krause (leonkrause) + Marcel Admiraal (madmiraal) + Markus Sauermann (Sauermann) Matthew (skyace65) Max Hilbrunner (mhilbrunner) Michael Alexsander (YeldhamDev) + Nathalie Galla (MurderVeggie) Nathan Lovato (NathanLovato) + Patrick Exner (FlameLizard) Paul Joannon (paulloz) - Poommetee Ketson (Naryosha) + Poommetee Ketson (Noshyaar) + Raul Santos (raulsntos) Rémi Verschelde (akien-mga) + smix8 + TheYellowArchitect Tomasz Chabora (KoBeWi) TwistedTwigleg Will Nations (willnationsdev) - Yuri Roubinsky (Chaosus) - Yuri Sizov (pycbouh) + Yuri Rubinsky (Chaosus) + Yuri Sizov (YuriSizov) ZX-WT + 谢天 (jsjtxietian) diff --git a/README.md b/README.md index 5e2da59c413..2ef3c81d9bb 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,17 @@ They are meant to be parsed with the [Sphinx](https://www.sphinx-doc.org/) docum ## Download for offline use -To browse the documentation offline, you can -[download an HTML copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-master.zip) -for offline reading (updated every Monday). Extract the ZIP archive then open -the top-level `index.html` in a web browser. - -For mobile devices or e-readers, you can also -[download an ePub copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-master.zip) -for offline reading (updated every Monday). Extract the ZIP archive then open -the `GodotEngine.epub` file in an e-book reader application. +To browse the documentation offline, you can download an HTML copy (updated every Monday): +[stable](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-stable.zip), +[latest](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-master.zip), +[3.6](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-3.6.zip). Extract +the ZIP archive then open the top-level `index.html` in a web browser. + +For mobile devices or e-readers, you can also download an ePub copy (updated every Monday): +[stable](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-stable.zip), +[latest](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-master.zip), +[3.6](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-3.6.zip). Extract +the ZIP archive then open the `GodotEngine.epub` file in an e-book reader application. ## Theming diff --git a/_static/css/custom.css b/_static/css/custom.css index 8654cd14d6f..67efe0257d3 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -711,6 +711,7 @@ footer { .wy-body-for-nav { position: relative; background-color: var(--content-wrap-background-color); + overflow: visible; } @media only screen and (min-width: 769px) { diff --git a/_tools/redirects/redirects.csv b/_tools/redirects/redirects.csv index 09a214bfd19..5ffff280792 100644 --- a/_tools/redirects/redirects.csv +++ b/_tools/redirects/redirects.csv @@ -30,6 +30,7 @@ source,destination /contributing/development/core_and_modules/introduction_to_godot_development.html,/contributing/development/core_and_modules/index.html /contributing/doc_and_l10n_guidelines.html,/community/contributing/doc_and_l10n_guidelines.html /contributing/updating_the_class_reference.html,/community/contributing/updating_the_class_reference.html +/contributing/ways_to_contribute.html,/contributing/how_to_contribute.html /development/compiling/compiling_for_android.html,/contributing/development/compiling/compiling_for_android.html /development/compiling/compiling_for_ios.html,/contributing/development/compiling/compiling_for_ios.html /development/compiling/compiling_for_linuxbsd.html,/contributing/development/compiling/compiling_for_linuxbsd.html diff --git a/about/faq.rst b/about/faq.rst index 79ddcbfd35c..33f627a1c5f 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -11,7 +11,7 @@ Frequently asked questions What can I do with Godot? How much does it cost? What are the license terms? ---------------------------------------------------------------------------- -Godot is `Free and open source Software `_ +Godot is `Free and open source Software `_ available under the `OSI-approved `_ MIT license. This means it is free as in "free speech" as well as in "free beer." diff --git a/about/list_of_features.rst b/about/list_of_features.rst index 91c14e7e816..1fa78622871 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -22,7 +22,7 @@ Platforms **Can run both the editor and exported projects:** -- Windows (x86, 64-bit and 32-bit). +- Windows (x86 and ARM, 64-bit and 32-bit). - macOS (x86 and ARM, 64-bit only). - Linux (x86 and ARM, 64-bit and 32-bit). diff --git a/about/system_requirements.rst b/about/system_requirements.rst index 73a8ecc6cde..528e1056c3e 100644 --- a/about/system_requirements.rst +++ b/about/system_requirements.rst @@ -23,9 +23,9 @@ Desktop or laptop PC - Minimum .. which can run up to macOS 10.13. +----------------------+-----------------------------------------------------------------------------------------+ -| **CPU** | - **Windows:** x86_32 CPU with SSE2 instructions, or any x86_64 CPU | +| **CPU** | - **Windows:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv8 CPU | | | | -| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300* | +| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Snapdragon X Elite* | | | | | | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | | | | @@ -112,40 +112,40 @@ Godot editor on a simple 2D or 3D project: Desktop or laptop PC - Recommended ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -+----------------------+-----------------------------------------------------------------------------------------+ -| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more | -| | | -| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600* | -| | | -| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | -| | | -| | - *Example: Intel Core i5-8500, Apple M1* | -| | | -| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU | -| | | -| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* | -+----------------------+-----------------------------------------------------------------------------------------+ -| **GPU** | - **Forward+ rendering method:** Dedicated graphics with full Vulkan 1.2 support | -| | | -| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | -| | | -| | - **Mobile rendering method:** Dedicated graphics with full Vulkan 1.2 support | -| | | -| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | -| | | -| | - **Compatibility rendering method:** Dedicated graphics with full OpenGL 4.6 support | -| | | -| | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* | -+----------------------+-----------------------------------------------------------------------------------------+ -| **RAM** | - **Native editor:** 8 GB | -| | - **Web editor:** 12 GB | -+----------------------+-----------------------------------------------------------------------------------------+ -| **Storage** | 1.5 GB (used for the executable, project files, all export templates and cache) | -+----------------------+-----------------------------------------------------------------------------------------+ -| **Operating system** | - **Native editor:** Windows 10, macOS 10.15, | -| | Linux distribution released after 2020 | -| | - **Web editor:** Latest version of Firefox, Chrome, Edge, Safari, Opera | -+----------------------+-----------------------------------------------------------------------------------------+ ++----------------------+---------------------------------------------------------------------------------------------+ +| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more, ARMv8 CPU| +| | | +| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Snapdragon X Elite* | +| | | +| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | +| | | +| | - *Example: Intel Core i5-8500, Apple M1* | +| | | +| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU | +| | | +| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* | ++----------------------+---------------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ rendering method:** Dedicated graphics with full Vulkan 1.2 support | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Mobile rendering method:** Dedicated graphics with full Vulkan 1.2 support | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Compatibility rendering method:** Dedicated graphics with full OpenGL 4.6 support | +| | | +| | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* | ++----------------------+---------------------------------------------------------------------------------------------+ +| **RAM** | - **Native editor:** 8 GB | +| | - **Web editor:** 12 GB | ++----------------------+---------------------------------------------------------------------------------------------+ +| **Storage** | 1.5 GB (used for the executable, project files, all export templates and cache) | ++----------------------+---------------------------------------------------------------------------------------------+ +| **Operating system** | - **Native editor:** Windows 10, macOS 10.15, | +| | Linux distribution released after 2020 | +| | - **Web editor:** Latest version of Firefox, Chrome, Edge, Safari, Opera | ++----------------------+---------------------------------------------------------------------------------------------+ Mobile device (smartphone/tablet) - Recommended ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -208,9 +208,9 @@ Desktop or laptop PC - Minimum .. which can run up to macOS 10.13. +----------------------+-----------------------------------------------------------------------------------------+ -| **CPU** | - **Windows:** x86_32 CPU with SSE2 instructions, or any x86_64 CPU | +| **CPU** | - **Windows:** x86_32 CPU with SSE2 instructions, any x86_64 CPU, ARMv8 CPU | | | | -| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300* | +| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Snapdragon X Elite* | | | | | | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | | | | @@ -295,40 +295,40 @@ simple 2D or 3D project exported with Godot: Desktop or laptop PC - Recommended ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -+----------------------+-----------------------------------------------------------------------------------------+ -| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more | -| | | -| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600* | -| | | -| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | -| | | -| | - *Example: Intel Core i5-8500, Apple M1* | -| | | -| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU | -| | | -| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* | -+----------------------+-----------------------------------------------------------------------------------------+ -| **GPU** | - **Forward+ rendering method:** Dedicated graphics with full Vulkan 1.2 support | -| | | -| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | -| | | -| | - **Mobile rendering method:** Dedicated graphics with full Vulkan 1.2 support | -| | | -| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | -| | | -| | - **Compatibility rendering method:** Dedicated graphics with full OpenGL 4.6 support | -| | | -| | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* | -+----------------------+-----------------------------------------------------------------------------------------+ -| **RAM** | - **For native exports:** 4 GB | -| | - **For web exports:** 8 GB | -+----------------------+-----------------------------------------------------------------------------------------+ -| **Storage** | 150 MB (used for the executable, project files and cache) | -+----------------------+-----------------------------------------------------------------------------------------+ -| **Operating system** | - **For native exports:** Windows 10, macOS 10.15, | -| | Linux distribution released after 2020 | -| | - **For web exports:** Latest version of Firefox, Chrome, Edge, Safari, Opera | -+----------------------+-----------------------------------------------------------------------------------------+ ++----------------------+---------------------------------------------------------------------------------------------+ +| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more, ARMv8 CPU| +| | | +| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Snapdragon X Elite* | +| | | +| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | +| | | +| | - *Example: Intel Core i5-8500, Apple M1* | +| | | +| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU | +| | | +| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* | ++----------------------+---------------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ rendering method:** Dedicated graphics with full Vulkan 1.2 support | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Mobile rendering method:** Dedicated graphics with full Vulkan 1.2 support | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Compatibility rendering method:** Dedicated graphics with full OpenGL 4.6 support | +| | | +| | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* | ++----------------------+---------------------------------------------------------------------------------------------+ +| **RAM** | - **For native exports:** 4 GB | +| | - **For web exports:** 8 GB | ++----------------------+---------------------------------------------------------------------------------------------+ +| **Storage** | 150 MB (used for the executable, project files and cache) | ++----------------------+---------------------------------------------------------------------------------------------+ +| **Operating system** | - **For native exports:** Windows 10, macOS 10.15, | +| | Linux distribution released after 2020 | +| | - **For web exports:** Latest version of Firefox, Chrome, Edge, Safari, Opera | ++----------------------+---------------------------------------------------------------------------------------------+ Mobile device (smartphone/tablet) - Recommended ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index a1308bea25e..2e072c6768f 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -3878,7 +3878,7 @@ The property is not stored, and does not display in the editor. This is the defa :ref:`PropertyUsageFlags` **PROPERTY_USAGE_STORAGE** = ``2`` -The property is serialized and saved in the scene file (default). +The property is serialized and saved in the scene file (default for exported properties). .. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR: @@ -3886,7 +3886,7 @@ The property is serialized and saved in the scene file (default). :ref:`PropertyUsageFlags` **PROPERTY_USAGE_EDITOR** = ``4`` -The property is shown in the :ref:`EditorInspector` (default). +The property is shown in the :ref:`EditorInspector` (default for exported properties). .. _class_@GlobalScope_constant_PROPERTY_USAGE_INTERNAL: diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst index 9a6fc2a5519..4c35ba984c8 100644 --- a/classes/class_aabb.rst +++ b/classes/class_aabb.rst @@ -441,7 +441,7 @@ For an example, see :ref:`get_longest_axis`. :ref:`Vector3` **get_shortest_axis**\ (\ ) |const| :ref:`🔗` -Returns the shortest normaalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`). +Returns the shortest normalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`). .. tabs:: diff --git a/classes/class_animation.rst b/classes/class_animation.rst index 4d37c7df846..c977ca1a26e 100644 --- a/classes/class_animation.rst +++ b/classes/class_animation.rst @@ -1347,7 +1347,7 @@ Sets the value of an existing key. |void| **track_set_path**\ (\ track_idx\: :ref:`int`, path\: :ref:`NodePath`\ ) :ref:`🔗` -Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the parent node of the node that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by ``":"``. +Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the :ref:`AnimationMixer.root_node` that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by ``":"``. For example, ``"character/skeleton:ankle"`` or ``"character/mesh:transform/local"``. diff --git a/classes/class_animationmixer.rst b/classes/class_animationmixer.rst index f452889138d..d970b77d9b7 100644 --- a/classes/class_animationmixer.rst +++ b/classes/class_animationmixer.rst @@ -25,6 +25,13 @@ Base class for :ref:`AnimationPlayer` and :ref:`Animation After instantiating the playback information data within the extended class, the blending is processed by the **AnimationMixer**. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Migrating Animations from Godot 4.0 to 4.3 `__ + .. rst-class:: classref-reftable-group Properties @@ -454,9 +461,9 @@ This makes it more convenient to preview and edit animations in the editor, as c - |void| **set_root_motion_track**\ (\ value\: :ref:`NodePath`\ ) - :ref:`NodePath` **get_root_motion_track**\ (\ ) -The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. To specify a track that controls properties or bones, append its name after the path, separated by ``":"``. For example, ``"character/skeleton:ankle"`` or ``"character/mesh:transform/local"``. +The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. The :ref:`root_motion_track` uses the same format as :ref:`Animation.track_set_path`, but note that a bone must be specified. -If the track has type :ref:`Animation.TYPE_POSITION_3D`, :ref:`Animation.TYPE_ROTATION_3D` or :ref:`Animation.TYPE_SCALE_3D` the transformation will be canceled visually, and the animation will appear to stay in place. See also :ref:`get_root_motion_position`, :ref:`get_root_motion_rotation`, :ref:`get_root_motion_scale` and :ref:`RootMotionView`. +If the track has type :ref:`Animation.TYPE_POSITION_3D`, :ref:`Animation.TYPE_ROTATION_3D`, or :ref:`Animation.TYPE_SCALE_3D` the transformation will be canceled visually, and the animation will appear to stay in place. See also :ref:`get_root_motion_position`, :ref:`get_root_motion_rotation`, :ref:`get_root_motion_scale`, and :ref:`RootMotionView`. .. rst-class:: classref-item-separator @@ -504,6 +511,18 @@ A virtual function for processing after getting a key during playback. Adds ``library`` to the animation player, under the key ``name``. +AnimationMixer has a global library by default with an empty string as key. For adding an animation to the global library: + + +.. tabs:: + + .. code-tab:: gdscript + + var global_library = mixer.get_animation_library("") + global_library.add_animation("animation_name", animation_resource) + + + .. rst-class:: classref-item-separator ---- @@ -653,7 +672,7 @@ The most basic example is applying position to :ref:`CharacterBody3D`, you can apply the root motion position more correctly to account for the rotation of the node. +By using this in combination with :ref:`get_root_motion_rotation_accumulator`, you can apply the root motion position more correctly to account for the rotation of the node. .. tabs:: @@ -763,10 +782,10 @@ For example, if an animation with only one key ``Quaternion(0, 0, 0, 1)`` is pla func _process(delta): if Input.is_action_just_pressed("animate"): state_machine.travel("Animate") - var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_Quaternion_accumulator() + var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_rotation_accumulator() var difference: Quaternion = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator - transform.basis *= difference + transform.basis *= Basis(difference) diff --git a/classes/class_animationnodeanimation.rst b/classes/class_animationnodeanimation.rst index 734212e8862..d7b220ae231 100644 --- a/classes/class_animationnodeanimation.rst +++ b/classes/class_animationnodeanimation.rst @@ -126,6 +126,8 @@ Animation to use as an output. It is one of the animations provided by :ref:`Ani If :ref:`use_custom_timeline` is ``true``, override the loop settings of the original :ref:`Animation` resource with the value. +\ **Note:** If the :ref:`Animation.loop_mode` isn't set to looping, the :ref:`Animation.track_set_interpolation_loop_wrap` option will not be respected. If you cannot get the expected behavior, consider duplicating the :ref:`Animation` resource and changing the loop settings. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_animationplayer.rst b/classes/class_animationplayer.rst index ffa39105dba..b11956e6de9 100644 --- a/classes/class_animationplayer.rst +++ b/classes/class_animationplayer.rst @@ -661,7 +661,7 @@ If ``duration`` is a negative value, the duration is set to the interval between |void| **queue**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` -Queues an animation for playback once the current one is done. +Queues an animation for playback once the current animation and all previously queued animations are done. \ **Note:** If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow. diff --git a/classes/class_array.rst b/classes/class_array.rst index 450bbd9761c..f7a93b7a2a0 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -17,7 +17,7 @@ A built-in data structure that holds a sequence of elements. Description ----------- -An array data structure that can contain a sequence of elements of any type. Elements are accessed by a numerical index starting at 0. Negative indices are used to count from the back (-1 is the last element, -2 is the second to last, etc.). +An array data structure that can contain a sequence of elements of any :ref:`Variant` type. Elements are accessed by a numerical index starting at 0. Negative indices are used to count from the back (-1 is the last element, -2 is the second to last, etc.). \ **Example:**\ @@ -26,45 +26,29 @@ An array data structure that can contain a sequence of elements of any type. Ele .. code-tab:: gdscript - var array = ["One", 2, 3, "Four"] - print(array[0]) # One. - print(array[2]) # 3. - print(array[-1]) # Four. - array[2] = "Three" - print(array[-2]) # Three. - - .. code-tab:: csharp - - var array = new Godot.Collections.Array{"One", 2, 3, "Four"}; - GD.Print(array[0]); // One. - GD.Print(array[2]); // 3. - GD.Print(array[array.Count - 1]); // Four. - array[2] = "Three"; - GD.Print(array[array.Count - 2]); // Three. - - - -Arrays can be concatenated using the ``+`` operator: - - -.. tabs:: - - .. code-tab:: gdscript - - var array1 = ["One", 2] - var array2 = [3, "Four"] - print(array1 + array2) # ["One", 2, 3, "Four"] + var array = ["First", 2, 3, "Last"] + print(array[0]) # Prints "First" + print(array[2]) # Prints 3 + print(array[-1]) # Prints "Last" + + array[1] = "Second" + print(array[1]) # Prints "Second" + print(array[-3]) # Prints "Second" .. code-tab:: csharp - // Array concatenation is not possible with C# arrays, but is with Godot.Collections.Array. - var array1 = new Godot.Collections.Array{"One", 2}; - var array2 = new Godot.Collections.Array{3, "Four"}; - GD.Print(array1 + array2); // Prints [One, 2, 3, Four] + var array = new Godot.Collections.Array{"First", 2, 3, "Last"}; + GD.Print(array[0]); // Prints "First" + GD.Print(array[2]); // Prints 3 + GD.Print(array[array.Count - 1]); // Prints "Last" + + array[2] = "Second"; + GD.Print(array[1]); // Prints "Second" + GD.Print(array[array.Count - 3]); // Prints "Second" -\ **Note:** Arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use :ref:`duplicate`. +\ **Note:** Arrays are always passed by **reference**. To get a copy of an array that can be modified independently of the original array, use :ref:`duplicate`. \ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. @@ -263,37 +247,41 @@ Constructs an empty **Array**. :ref:`Array` **Array**\ (\ base\: :ref:`Array`, type\: :ref:`int`, class_name\: :ref:`StringName`, script\: :ref:`Variant`\ ) -Creates a typed array from the ``base`` array. All arguments are required. +Creates a typed array from the ``base`` array. A typed array can only contain elements of the given type, or that inherit from the given class, as described by this constructor's parameters: -- ``type`` is the built-in type as a :ref:`Variant.Type` constant, for example :ref:`@GlobalScope.TYPE_INT`. +- ``type`` is the built-in :ref:`Variant` type, as one the :ref:`Variant.Type` constants. -- ``class_name`` is the **native** class name, for example :ref:`Node`. If ``type`` is not :ref:`@GlobalScope.TYPE_OBJECT`, must be an empty string. +- ``class_name`` is the built-in class name (see :ref:`Object.get_class`). -- ``script`` is the associated script. Must be a :ref:`Script` instance or ``null``. +- ``script`` is the associated script. It must be a :ref:`Script` instance or ``null``. -Examples: +If ``type`` is not :ref:`@GlobalScope.TYPE_OBJECT`, ``class_name`` must be an empty :ref:`StringName` and ``script`` must be ``null``. :: - class_name MyNode + class_name Sword extends Node - class MyClass: + class Stats: pass func _ready(): - var a = Array([], TYPE_INT, &"", null) # Array[int] - var b = Array([], TYPE_OBJECT, &"Node", null) # Array[Node] - var c = Array([], TYPE_OBJECT, &"Node", MyNode) # Array[MyNode] - var d = Array([], TYPE_OBJECT, &"RefCounted", MyClass) # Array[MyClass] + var a = Array([], TYPE_INT, "", null) # Array[int] + var b = Array([], TYPE_OBJECT, "Node", null) # Array[Node] + var c = Array([], TYPE_OBJECT, "Node", Sword) # Array[Sword] + var d = Array([], TYPE_OBJECT, "RefCounted", Stats) # Array[Stats] + +The ``base`` array's elements are converted when necessary. If this is not possible or ``base`` is already typed, this constructor fails and returns an empty **Array**. -\ **Note:** This constructor can be useful if you want to create a typed array on the fly, but you are not required to use it. In GDScript you can use a temporary variable with the static type you need and then pass it: +In GDScript, this constructor is usually not necessary, as it is possible to create a typed array through static typing: :: - func _ready(): - var a: Array[int] = [] - some_func(a) + var numbers: Array[float] = [] + var children: Array[Node] = [$Node, $Sprite2D, $RigidBody3D] + + var integers: Array[int] = [0.2, 4.5, -2.0] + print(integers) # Prints [0, 4, -2] .. rst-class:: classref-item-separator @@ -420,22 +408,50 @@ Method Descriptions :ref:`bool` **all**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *all* elements in the array. If the :ref:`Callable` returns ``false`` for one array element or more, this method returns ``false``. +Calls the given :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *all* elements in the array. If the :ref:`Callable` returns ``false`` for one array element or more, this method returns ``false``. -The callable's method should take one :ref:`Variant` parameter (the current array element) and return a boolean value. +The ``method`` should take one :ref:`Variant` parameter (the current array element) and return a :ref:`bool`. -:: +.. tabs:: + + .. code-tab:: gdscript + + func greater_than_5(number): + return number > 5 + func _ready(): - print([6, 10, 6].all(greater_than_5)) # Prints True (3/3 elements evaluate to `true`). - print([4, 10, 4].all(greater_than_5)) # Prints False (1/3 elements evaluate to `true`). - print([4, 4, 4].all(greater_than_5)) # Prints False (0/3 elements evaluate to `true`). - print([].all(greater_than_5)) # Prints True (0/0 elements evaluate to `true`). + print([6, 10, 6].all(greater_than_5)) # Prints true (3/3 elements evaluate to true). + print([4, 10, 4].all(greater_than_5)) # Prints false (1/3 elements evaluate to true). + print([4, 4, 4].all(greater_than_5)) # Prints false (0/3 elements evaluate to true). + print([].all(greater_than_5)) # Prints true (0/0 elements evaluate to true). - print([6, 10, 6].all(func(number): return number > 5)) # Prints True. Same as the first line above, but using lambda function. + # Same as the first line above, but using a lambda function. + print([6, 10, 6].all(func(element): return element > 5)) # Prints true + + .. code-tab:: csharp + + private static bool GreaterThan5(int number) + { + return number > 5; + } - func greater_than_5(number): - return number > 5 + public override void _Ready() + { + // Prints true (3/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(GreaterThan5)); + // Prints false (1/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 10, 4 }.All(GreaterThan5)); + // Prints false (0/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 4, 4 }.All(GreaterThan5)); + // Prints true (0/0 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { }.All(GreaterThan5)); + + // Same as the first line above, but using a lambda function. + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(element => element > 5)); // Prints true + } + + See also :ref:`any`, :ref:`filter`, :ref:`map` and :ref:`reduce`. @@ -453,22 +469,23 @@ See also :ref:`any`, :ref:`filter` **any**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *one or more* elements in the array. If the :ref:`Callable` returns ``false`` for all elements in the array, this method returns ``false``. +Calls the given :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *one or more* elements in the array. If the :ref:`Callable` returns ``false`` for all elements in the array, this method returns ``false``. -The callable's method should take one :ref:`Variant` parameter (the current array element) and return a boolean value. +The ``method`` should take one :ref:`Variant` parameter (the current array element) and return a :ref:`bool`. :: - func _ready(): - print([6, 10, 6].any(greater_than_5)) # Prints True (3 elements evaluate to `true`). - print([4, 10, 4].any(greater_than_5)) # Prints True (1 elements evaluate to `true`). - print([4, 4, 4].any(greater_than_5)) # Prints False (0 elements evaluate to `true`). - print([].any(greater_than_5)) # Prints False (0 elements evaluate to `true`). - - print([6, 10, 6].any(func(number): return number > 5)) # Prints True. Same as the first line above, but using lambda function. - func greater_than_5(number): return number > 5 + + func _ready(): + print([6, 10, 6].any(greater_than_5)) # Prints true (3 elements evaluate to true). + print([4, 10, 4].any(greater_than_5)) # Prints true (1 elements evaluate to true). + print([4, 4, 4].any(greater_than_5)) # Prints false (0 elements evaluate to true). + print([].any(greater_than_5)) # Prints false (0 elements evaluate to true). + + # Same as the first line above, but using a lambda function. + print([6, 10, 6].any(func(number): return number > 5)) # Prints true See also :ref:`all`, :ref:`filter`, :ref:`map` and :ref:`reduce`. @@ -486,7 +503,7 @@ See also :ref:`all`, :ref:`filter`\ ) :ref:`🔗` -Appends an element at the end of the array (alias of :ref:`push_back`). +Appends ``value`` at the end of the array (alias of :ref:`push_back`). .. rst-class:: classref-item-separator @@ -498,14 +515,14 @@ Appends an element at the end of the array (alias of :ref:`push_back`\ ) :ref:`🔗` -Appends another array at the end of this array. +Appends another ``array`` at the end of this array. :: - var array1 = [1, 2, 3] - var array2 = [4, 5, 6] - array1.append_array(array2) - print(array1) # Prints [1, 2, 3, 4, 5, 6]. + var numbers = [1, 2, 3] + var extra = [4, 5, 6] + numbers.append_array(extra) + print(nums) # Prints [1, 2, 3, 4, 5, 6] .. rst-class:: classref-item-separator @@ -529,9 +546,9 @@ Assigns elements of another ``array`` into the array. Resizes the array to match :ref:`Variant` **back**\ (\ ) |const| :ref:`🔗` -Returns the last element of the array. Prints an error and returns ``null`` if the array is empty. +Returns the last element of the array. If the array is empty, fails and returns ``null``. See also :ref:`front`. -\ **Note:** Calling this function is not the same as writing ``array[-1]``. If the array is empty, accessing by index will pause project execution when running from the editor. +\ **Note:** Unlike with the ``[]`` operator (``array[-1]``), an error is generated without stopping project execution. .. rst-class:: classref-item-separator @@ -543,15 +560,23 @@ Returns the last element of the array. Prints an error and returns ``null`` if t :ref:`int` **bsearch**\ (\ value\: :ref:`Variant`, before\: :ref:`bool` = true\ ) |const| :ref:`🔗` -Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array. +Returns the index of ``value`` in the sorted array. If it cannot be found, returns where ``value`` should be inserted to keep the array sorted. The algorithm used is `binary search `__. + +If ``before`` is ``true`` (as by default), the returned index comes before all existing elements equal to ``value`` in the array. :: - var array = ["a", "b", "c", "c", "d", "e"] - print(array.bsearch("c", true)) # Prints 2, at the first matching element. - print(array.bsearch("c", false)) # Prints 4, after the last matching element, pointing to "d". + var numbers = [2, 4, 8, 10] + var idx = numbers.bsearch(7) + + numbers.insert(idx, 7) + print(numbers) # Prints [2, 4, 7, 8, 10] + + var fruits = ["Apple", "Lemon", "Lemon", "Orange"] + print(fruits.bsearch("Lemon", true)) # Prints 1, points at the first "Lemon". + print(fruits.bsearch("Lemon", false)) # Prints 3, points at "Orange". -\ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** Calling :ref:`bsearch` on an *unsorted* array will result in unexpected behavior. Use :ref:`sort` before calling this method. .. rst-class:: classref-item-separator @@ -563,11 +588,34 @@ Finds the index of an existing value (or the insertion index that maintains sort :ref:`int` **bsearch_custom**\ (\ value\: :ref:`Variant`, func\: :ref:`Callable`, before\: :ref:`bool` = true\ ) |const| :ref:`🔗` -Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search and a custom comparison method. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array. The custom method receives two arguments (an element from the array and the value searched for) and must return ``true`` if the first argument is less than the second, and return ``false`` otherwise. +Returns the index of ``value`` in the sorted array. If it cannot be found, returns where ``value`` should be inserted to keep the array sorted (using ``func`` for the comparisons). The algorithm used is `binary search `__. -\ **Note:** The custom method must accept the two arguments in any order, you cannot rely on that the first argument will always be from the array. +Similar to :ref:`sort_custom`, ``func`` is called as many times as necessary, receiving one array element and ``value`` as arguments. The function should return ``true`` if the array element should be *behind* ``value``, otherwise it should return ``false``. -\ **Note:** Calling :ref:`bsearch_custom` on an unsorted array results in unexpected behavior. +If ``before`` is ``true`` (as by default), the returned index comes before all existing elements equal to ``value`` in the array. + +:: + + func sort_by_amount(a, b): + if a[1] < b[1]: + return true + return false + + func _ready(): + var my_items = [["Tomato", 2], ["Kiwi", 5], ["Rice", 9]] + + var apple = ["Apple", 5] + # "Apple" is inserted before "Kiwi". + my_items.insert(my_items.bsearch_custom(apple, sort_by_amount, true), apple) + + var banana = ["Banana", 5] + # "Banana" is inserted after "Kiwi". + my_items.insert(my_items.bsearch_custom(banana, sort_by_amount, false), banana) + + # Prints [["Tomato", 2], ["Apple", 5], ["Kiwi", 5], ["Banana", 5], ["Rice", 9]] + print(my_items) + +\ **Note:** Calling :ref:`bsearch_custom` on an *unsorted* array will result in unexpected behavior. Use :ref:`sort_custom` with ``func`` before calling this method. .. rst-class:: classref-item-separator @@ -579,7 +627,7 @@ Finds the index of an existing value (or the insertion index that maintains sort |void| **clear**\ (\ ) :ref:`🔗` -Clears the array. This is equivalent to using :ref:`resize` with a size of ``0``. +Removes all elements from the array. This is equivalent to using :ref:`resize` with a size of ``0``. .. rst-class:: classref-item-separator @@ -603,9 +651,11 @@ Returns the number of times an element is in the array. :ref:`Array` **duplicate**\ (\ deep\: :ref:`bool` = false\ ) |const| :ref:`🔗` -Returns a copy of the array. +Returns a new copy of the array. -If ``deep`` is ``true``, a deep copy is performed: all nested arrays and dictionaries are duplicated and will not be shared with the original array. If ``false``, a shallow copy is made and references to the original nested arrays and dictionaries are kept, so that modifying a sub-array or dictionary in the copy will also impact those referenced in the source array. Note that any :ref:`Object`-derived elements will be shallow copied regardless of the ``deep`` setting. +By default, a **shallow** copy is returned: all nested **Array** and :ref:`Dictionary` elements are shared with the original array. Modifying them in one array will also affect them in the other. + +If ``deep`` is ``true``, a **deep** copy is returned: all nested arrays and dictionaries are also duplicated (recursively). .. rst-class:: classref-item-separator @@ -617,13 +667,11 @@ If ``deep`` is ``true``, a deep copy is performed: all nested arrays and diction |void| **erase**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` -Removes the first occurrence of a value from the array. If the value does not exist in the array, nothing happens. To remove an element by index, use :ref:`remove_at` instead. - -\ **Note:** This method acts in-place and doesn't return a modified array. +Finds and removes the first occurrence of ``value`` from the array. If ``value`` does not exist in the array, nothing happens. To remove an element by index, use :ref:`remove_at` instead. -\ **Note:** On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed. +\ **Note:** This method shifts every element's index after the removed ``value`` back, which may have a noticeable performance cost, especially on larger arrays. -\ **Note:** Do not erase entries while iterating over the array. +\ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. .. rst-class:: classref-item-separator @@ -635,7 +683,9 @@ Removes the first occurrence of a value from the array. If the value does not ex |void| **fill**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` -Assigns the given value to all elements in the array. This can typically be used together with :ref:`resize` to create an array with a given size and initialized elements: +Assigns the given ``value`` to all elements in the array. + +This method can often be combined with :ref:`resize` to create an array with a given size and initialized elements: .. tabs:: @@ -643,18 +693,20 @@ Assigns the given value to all elements in the array. This can typically be used .. code-tab:: gdscript var array = [] - array.resize(10) - array.fill(0) # Initialize the 10 elements to 0. + array.resize(5) + array.fill(2) + print(array) # Prints [2, 2, 2, 2, 2] .. code-tab:: csharp var array = new Godot.Collections.Array(); - array.Resize(10); - array.Fill(0); // Initialize the 10 elements to 0. + array.Resize(5); + array.Fill(2); + GD.Print(array); // Prints [2, 2, 2, 2, 2] -\ **Note:** If ``value`` is of a reference type (:ref:`Object`-derived, **Array**, :ref:`Dictionary`, etc.) then the array is filled with the references to the same object, i.e. no duplicates are created. +\ **Note:** If ``value`` is a :ref:`Variant` passed by reference (:ref:`Object`-derived, **Array**, :ref:`Dictionary`, etc.), the array will be filled with references to the same ``value``, which are not duplicates. .. rst-class:: classref-item-separator @@ -666,18 +718,20 @@ Assigns the given value to all elements in the array. This can typically be used :ref:`Array` **filter**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` on each element in the array and returns a new array with the elements for which the method returned ``true``. +Calls the given :ref:`Callable` on each element in the array and returns a new, filtered **Array**. -The callable's method should take one :ref:`Variant` parameter (the current array element) and return a boolean value. +The ``method`` receives one of the array elements as an argument, and should return ``true`` to add the element to the filtered array, or ``false`` to exclude it. :: + func is_even(number): + return number % 2 == 0 + func _ready(): - print([1, 2, 3].filter(remove_1)) # Prints [2, 3]. - print([1, 2, 3].filter(func(number): return number != 1)) # Same as above, but using lambda function. + print([1, 4, 5, 8].filter(is_even)) # Prints [4, 8] - func remove_1(number): - return number != 1 + # Same as above, but using a lambda function. + print([1, 4, 5, 8].filter(func(number): return number % 2 == 0)) See also :ref:`any`, :ref:`all`, :ref:`map` and :ref:`reduce`. @@ -691,7 +745,11 @@ See also :ref:`any`, :ref:`all`, :ref:`int` **find**\ (\ what\: :ref:`Variant`, from\: :ref:`int` = 0\ ) |const| :ref:`🔗` -Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +Returns the index of the **first** occurrence of ``what`` in this array, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the end of the array. + +\ **Note:** If you just want to know whether the array contains ``what``, use :ref:`has` (``Contains`` in C#). In GDScript, you may also use the ``in`` operator. + +\ **Note:** For performance reasons, the search is affected by ``what``'s :ref:`Variant.Type`. For example, ``7`` (:ref:`int`) and ``7.0`` (:ref:`float`) are not considered equal for this method. .. rst-class:: classref-item-separator @@ -703,9 +761,9 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt :ref:`Variant` **front**\ (\ ) |const| :ref:`🔗` -Returns the first element of the array. Prints an error and returns ``null`` if the array is empty. +Returns the first element of the array. If the array is empty, fails and returns ``null``. See also :ref:`back`. -\ **Note:** Calling this function is not the same as writing ``array[0]``. If the array is empty, accessing by index will pause project execution when running from the editor. +\ **Note:** Unlike with the ``[]`` operator (``array[0]``), an error is generated without stopping project execution. .. rst-class:: classref-item-separator @@ -717,7 +775,7 @@ Returns the first element of the array. Prints an error and returns ``null`` if :ref:`int` **get_typed_builtin**\ (\ ) |const| :ref:`🔗` -Returns the built-in type of the typed array as a :ref:`Variant.Type` constant. If the array is not typed, returns :ref:`@GlobalScope.TYPE_NIL`. +Returns the built-in :ref:`Variant` type of the typed array as a :ref:`Variant.Type` constant. If the array is not typed, returns :ref:`@GlobalScope.TYPE_NIL`. See also :ref:`is_typed`. .. rst-class:: classref-item-separator @@ -729,7 +787,7 @@ Returns the built-in type of the typed array as a :ref:`Variant.Type` **get_typed_class_name**\ (\ ) |const| :ref:`🔗` -Returns the **native** class name of the typed array if the built-in type is :ref:`@GlobalScope.TYPE_OBJECT`. Otherwise, this method returns an empty string. +Returns the **built-in** class name of the typed array, if the built-in :ref:`Variant` type :ref:`@GlobalScope.TYPE_OBJECT`. Otherwise, returns an empty :ref:`StringName`. See also :ref:`is_typed` and :ref:`Object.get_class`. .. rst-class:: classref-item-separator @@ -741,7 +799,7 @@ Returns the **native** class name of the typed array if the built-in type is :re :ref:`Variant` **get_typed_script**\ (\ ) |const| :ref:`🔗` -Returns the script associated with the typed array. This method returns a :ref:`Script` instance or ``null``. +Returns the :ref:`Script` instance associated with this typed array, or ``null`` if it does not exist. See also :ref:`is_typed`. .. rst-class:: classref-item-separator @@ -753,50 +811,37 @@ Returns the script associated with the typed array. This method returns a :ref:` :ref:`bool` **has**\ (\ value\: :ref:`Variant`\ ) |const| :ref:`🔗` -Returns ``true`` if the array contains the given value. +Returns ``true`` if the array contains the given ``value``. .. tabs:: .. code-tab:: gdscript - print(["inside", 7].has("inside")) # True - print(["inside", 7].has("outside")) # False - print(["inside", 7].has(7)) # True - print(["inside", 7].has("7")) # False + print(["inside", 7].has("inside")) # Prints true + print(["inside", 7].has("outside")) # Prints false + print(["inside", 7].has(7)) # Prints true + print(["inside", 7].has("7")) # Prints false .. code-tab:: csharp var arr = new Godot.Collections.Array { "inside", 7 }; - // has is renamed to Contains - GD.Print(arr.Contains("inside")); // True - GD.Print(arr.Contains("outside")); // False - GD.Print(arr.Contains(7)); // True - GD.Print(arr.Contains("7")); // False - - - -\ **Note:** This is equivalent to using the ``in`` operator as follows: - - -.. tabs:: + // By C# convention, this method is renamed to `Contains`. + GD.Print(arr.Contains("inside")); // Prints true + GD.Print(arr.Contains("outside")); // Prints false + GD.Print(arr.Contains(7)); // Prints true + GD.Print(arr.Contains("7")); // Prints false - .. code-tab:: gdscript - # Will evaluate to `true`. - if 2 in [2, 4, 6, 8]: - print("Contains!") - .. code-tab:: csharp +In GDScript, this is equivalent to the ``in`` operator: - // As there is no "in" keyword in C#, you have to use Contains - var array = new Godot.Collections.Array { 2, 4, 6, 8 }; - if (array.Contains(2)) - { - GD.Print("Contains!"); - } +:: + if 4 in [2, 4, 6, 8]: + print("4 is here!") # Will be printed. +\ **Note:** For performance reasons, the search is affected by the ``value``'s :ref:`Variant.Type`. For example, ``7`` (:ref:`int`) and ``7.0`` (:ref:`float`) are not considered equal for this method. .. rst-class:: classref-item-separator @@ -810,7 +855,7 @@ Returns ``true`` if the array contains the given value. Returns a hashed 32-bit integer value representing the array and its contents. -\ **Note:** **Array**\ s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does *not* imply the arrays are equal, because different arrays can have identical hash values due to hash collisions. +\ **Note:** Arrays with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the countrary, arrays with different hash values are guaranteed to be different. .. rst-class:: classref-item-separator @@ -822,11 +867,11 @@ Returns a hashed 32-bit integer value representing the array and its contents. :ref:`int` **insert**\ (\ position\: :ref:`int`, value\: :ref:`Variant`\ ) :ref:`🔗` -Inserts a new element at a given position in the array. The position must be valid, or at the end of the array (``pos == size()``). Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. +Inserts a new element (``value``) at a given index (``position``) in the array. ``position`` should be between ``0`` and the array's :ref:`size`. -\ **Note:** This method acts in-place and doesn't return a modified array. +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` constants if this method fails. -\ **Note:** On large arrays, this method will be slower if the inserted element is close to the beginning of the array (index 0). This is because all elements placed after the newly inserted element have to be reindexed. +\ **Note:** Every element's index after ``position`` needs to be shifted forward, which may have a noticeable performance cost, especially on larger arrays. .. rst-class:: classref-item-separator @@ -838,7 +883,7 @@ Inserts a new element at a given position in the array. The position must be val :ref:`bool` **is_empty**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the array is empty. +Returns ``true`` if the array is empty (``[]``). See also :ref:`size`. .. rst-class:: classref-item-separator @@ -850,7 +895,9 @@ Returns ``true`` if the array is empty. :ref:`bool` **is_read_only**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the array is read-only. See :ref:`make_read_only`. Arrays are automatically read-only if declared with ``const`` keyword. +Returns ``true`` if the array is read-only. See :ref:`make_read_only`. + +In GDScript, arrays are automatically read-only if declared with the ``const`` keyword. .. rst-class:: classref-item-separator @@ -862,7 +909,7 @@ Returns ``true`` if the array is read-only. See :ref:`make_read_only` **is_same_typed**\ (\ array\: :ref:`Array`\ ) |const| :ref:`🔗` -Returns ``true`` if the array is typed the same as ``array``. +Returns ``true`` if this array is typed the same as the given ``array``. See also :ref:`is_typed`. .. rst-class:: classref-item-separator @@ -874,7 +921,14 @@ Returns ``true`` if the array is typed the same as ``array``. :ref:`bool` **is_typed**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the array is typed. Typed arrays can only store elements of their associated type and provide type safety for the ``[]`` operator. Methods of typed array still return :ref:`Variant`. +Returns ``true`` if the array is typed. Typed arrays can only contain elements of a specific type, as defined by the typed array constructor. The methods of a typed array are still expected to return a generic :ref:`Variant`. + +In GDScript, it is possible to define a typed array with static typing: + +:: + + var numbers: Array[float] = [0.2, 4.2, -2.0] + print(numbers.is_typed()) # Prints true .. rst-class:: classref-item-separator @@ -886,7 +940,9 @@ Returns ``true`` if the array is typed. Typed arrays can only store elements of |void| **make_read_only**\ (\ ) :ref:`🔗` -Makes the array read-only, i.e. disabled modifying of the array's elements. Does not apply to nested content, e.g. content of nested arrays. +Makes the array read-only. The array's elements cannot be overridden with different values, and their order cannot change. Does not apply to nested elements, such as dictionaries. + +In GDScript, arrays are automatically read-only if declared with the ``const`` keyword. .. rst-class:: classref-item-separator @@ -898,18 +954,20 @@ Makes the array read-only, i.e. disabled modifying of the array's elements. Does :ref:`Array` **map**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` for each element in the array and returns a new array filled with values returned by the method. +Calls the given :ref:`Callable` for each element in the array and returns a new array filled with values returned by the ``method``. -The callable's method should take one :ref:`Variant` parameter (the current array element) and can return any :ref:`Variant`. +The ``method`` should take one :ref:`Variant` parameter (the current array element) and can return any :ref:`Variant`. :: + func double(number): + return number * 2 + func _ready(): - print([1, 2, 3].map(negate)) # Prints [-1, -2, -3]. - print([1, 2, 3].map(func(number): return -number)) # Same as above, but using lambda function. + print([1, 2, 3].map(double)) # Prints [2, 4, 6] - func negate(number): - return -number + # Same as above, but using a lambda function. + print([1, 2, 3].map(func(element): return element * 2)) See also :ref:`filter`, :ref:`reduce`, :ref:`any` and :ref:`all`. @@ -923,19 +981,9 @@ See also :ref:`filter`, :ref:`reduce` **max**\ (\ ) |const| :ref:`🔗` -Returns the maximum value contained in the array if all elements are of comparable types. If the elements can't be compared, ``null`` is returned. - -To find the maximum value using a custom comparator, you can use :ref:`reduce`. In this example every array element is checked and the first maximum value is returned: - -:: +Returns the maximum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also :ref:`min`. - func _ready(): - var arr = [Vector2(0, 1), Vector2(2, 0), Vector2(1, 1), Vector2(1, 0), Vector2(0, 2)] - # In this example we compare the lengths. - print(arr.reduce(func(max, val): return val if is_length_greater(val, max) else max)) - - func is_length_greater(a, b): - return a.length() > b.length() +To find the maximum value using a custom comparator, you can use :ref:`reduce`. .. rst-class:: classref-item-separator @@ -947,9 +995,7 @@ To find the maximum value using a custom comparator, you can use :ref:`reduce` **min**\ (\ ) |const| :ref:`🔗` -Returns the minimum value contained in the array if all elements are of comparable types. If the elements can't be compared, ``null`` is returned. - -See also :ref:`max` for an example of using a custom comparator. +Returns the minimum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also :ref:`max`. .. rst-class:: classref-item-separator @@ -961,22 +1007,24 @@ See also :ref:`max` for an example of using a custom com :ref:`Variant` **pick_random**\ (\ ) |const| :ref:`🔗` -Returns a random value from the target array. Prints an error and returns ``null`` if the array is empty. +Returns a random element from the array. Generates an error and returns ``null`` if the array is empty. .. tabs:: .. code-tab:: gdscript - var array: Array[int] = [1, 2, 3, 4] - print(array.pick_random()) # Prints either of the four numbers. + # May print 1, 2, 3.25, or "Hi". + print([1, 2, 3.25, "Hi"].pick_random()) .. code-tab:: csharp - var array = new Godot.Collections.Array { 1, 2, 3, 4 }; - GD.Print(array.PickRandom()); // Prints either of the four numbers. + var array = new Godot.Collections.Array { 1, 2, 3.25f, "Hi" }; + GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi". + +\ **Note:** Like many similar functions in the engine (such as :ref:`@GlobalScope.randi` or :ref:`shuffle`), this method uses a common, global random seed. To get a predictable outcome from this method, see :ref:`@GlobalScope.seed`. .. rst-class:: classref-item-separator @@ -988,9 +1036,9 @@ Returns a random value from the target array. Prints an error and returns ``null :ref:`Variant` **pop_at**\ (\ position\: :ref:`int`\ ) :ref:`🔗` -Removes and returns the element of the array at index ``position``. If negative, ``position`` is considered relative to the end of the array. Leaves the array unchanged and returns ``null`` if the array is empty or if it's accessed out of bounds. An error message is printed when the array is accessed out of bounds, but not when the array is empty. +Removes and returns the element of the array at index ``position``. If negative, ``position`` is considered relative to the end of the array. Returns ``null`` if the array is empty. If ``position`` is out of bounds, an error message is also generated. -\ **Note:** On large arrays, this method can be slower than :ref:`pop_back` as it will reindex the array's elements that are located after the removed element. The larger the array and the lower the index of the removed element, the slower :ref:`pop_at` will be. +\ **Note:** This method shifts every element's index after ``position`` back, which may have a noticeable performance cost, especially on larger arrays. .. rst-class:: classref-item-separator @@ -1002,7 +1050,7 @@ Removes and returns the element of the array at index ``position``. If negative, :ref:`Variant` **pop_back**\ (\ ) :ref:`🔗` -Removes and returns the last element of the array. Returns ``null`` if the array is empty, without printing an error message. See also :ref:`pop_front`. +Removes and returns the last element of the array. Returns ``null`` if the array is empty, without generating an error. See also :ref:`pop_front`. .. rst-class:: classref-item-separator @@ -1014,9 +1062,9 @@ Removes and returns the last element of the array. Returns ``null`` if the array :ref:`Variant` **pop_front**\ (\ ) :ref:`🔗` -Removes and returns the first element of the array. Returns ``null`` if the array is empty, without printing an error message. See also :ref:`pop_back`. +Removes and returns the first element of the array. Returns ``null`` if the array is empty, without generating an error. See also :ref:`pop_back`. -\ **Note:** On large arrays, this method is much slower than :ref:`pop_back` as it will reindex all the array's elements every time it's called. The larger the array, the slower :ref:`pop_front` will be. +\ **Note:** This method shifts every other element's index back, which may have a noticeable performance cost, especially on larger arrays. .. rst-class:: classref-item-separator @@ -1042,7 +1090,7 @@ Appends an element at the end of the array. See also :ref:`push_front`. -\ **Note:** On large arrays, this method is much slower than :ref:`push_back` as it will reindex all the array's elements every time it's called. The larger the array, the slower :ref:`push_front` will be. +\ **Note:** This method shifts every other element's index forward, which may have a noticeable performance cost, especially on larger arrays. .. rst-class:: classref-item-separator @@ -1054,18 +1102,34 @@ Adds an element at the beginning of the array. See also :ref:`push_back` **reduce**\ (\ method\: :ref:`Callable`, accum\: :ref:`Variant` = null\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` for each element in array and accumulates the result in ``accum``. +Calls the given :ref:`Callable` for each element in array, accumulates the result in ``accum``, then returns it. -The callable's method takes two arguments: the current value of ``accum`` and the current array element. If ``accum`` is ``null`` (default value), the iteration will start from the second element, with the first one used as initial value of ``accum``. +The ``method`` takes two arguments: the current value of ``accum`` and the current array element. If ``accum`` is ``null`` (as by default), the iteration will start from the second element, with the first one used as initial value of ``accum``. :: - func _ready(): - print([1, 2, 3].reduce(sum, 10)) # Prints 16. - print([1, 2, 3].reduce(func(accum, number): return accum + number, 10)) # Same as above, but using lambda function. - func sum(accum, number): return accum + number + + func _ready(): + print([1, 2, 3].reduce(sum, 0)) # Prints 6 + print([1, 2, 3].reduce(sum, 10)) # Prints 16 + + # Same as above, but using a lambda function. + print([1, 2, 3].reduce(func(accum, number): return accum + number, 10)) + +If :ref:`max` is not desirable, this method may also be used to implement a custom comparator: + +:: + + func _ready(): + var arr = [Vector2(5, 0), Vector2(3, 4), Vector2(1, 2)] + + var longest_vec = arr.reduce(func(max, vec): return vec if is_length_greater(vec, max) else max) + print(longest_vec) # Prints Vector2(3, 4). + + func is_length_greater(a, b): + return a.length() > b.length() See also :ref:`map`, :ref:`filter`, :ref:`any` and :ref:`all`. @@ -1079,13 +1143,13 @@ See also :ref:`map`, :ref:`filter`\ ) :ref:`🔗` -Removes an element from the array by index. If the index does not exist in the array, nothing happens. To remove an element by searching for its value, use :ref:`erase` instead. +Removes the element from the array at the given index (``position``). If the index is out of bounds, this method fails. -\ **Note:** This method acts in-place and doesn't return a modified array. +If you need to return the removed element, use :ref:`pop_at`. To remove an element by value, use :ref:`erase` instead. -\ **Note:** On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed. +\ **Note:** This method shifts every element's index after ``position`` back, which may have a noticeable performance cost, especially on larger arrays. -\ **Note:** ``position`` cannot be negative. To remove an element relative to the end of the array, use ``arr.remove_at(arr.size() - (i + 1))``. To remove the last element from the array without returning the value, use ``arr.resize(arr.size() - 1)``. +\ **Note:** The ``position`` cannot be negative. To remove an element relative to the end of the array, use ``arr.remove_at(arr.size() - (i + 1))``. To remove the last element from the array, use ``arr.resize(arr.size() - 1)``. .. rst-class:: classref-item-separator @@ -1097,11 +1161,11 @@ Removes an element from the array by index. If the index does not exist in the a :ref:`int` **resize**\ (\ size\: :ref:`int`\ ) :ref:`🔗` -Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are ``null``. Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. +Sets the array's number of elements to ``size``. If ``size`` is smaller than the array's current size, the elements at the end are removed. If ``size`` is greater, new default elements (usually ``null``) are added, depending on the array's type. -Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` constants if this method fails. -\ **Note:** This method acts in-place and doesn't return a modified array. +\ **Note:** Calling this method once and assigning the new values is faster than calling :ref:`append` for every new element. .. rst-class:: classref-item-separator @@ -1113,7 +1177,7 @@ Calling :ref:`resize` once and assigning the new valu |void| **reverse**\ (\ ) :ref:`🔗` -Reverses the order of the elements in the array. +Reverses the order of all elements in the array. .. rst-class:: classref-item-separator @@ -1125,7 +1189,7 @@ Reverses the order of the elements in the array. :ref:`int` **rfind**\ (\ what\: :ref:`Variant`, from\: :ref:`int` = -1\ ) |const| :ref:`🔗` -Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +Returns the index of the **last** occurrence of ``what`` in this array, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the beginning of the array. This method is the reverse of :ref:`find`. .. rst-class:: classref-item-separator @@ -1137,7 +1201,9 @@ Searches the array in reverse order. Optionally, a start search index can be pas |void| **shuffle**\ (\ ) :ref:`🔗` -Shuffles the array such that the items will have a random order. This method uses the global random number generator common to methods such as :ref:`@GlobalScope.randi`. Call :ref:`@GlobalScope.randomize` to ensure that a new seed will be used each time if you want non-reproducible shuffling. +Shuffles all elements of the array in a random order. + +\ **Note:** Like many similar functions in the engine (such as :ref:`@GlobalScope.randi` or :ref:`pick_random`), this method uses a common, global random seed. To get a predictable outcome from this method, see :ref:`@GlobalScope.seed`. .. rst-class:: classref-item-separator @@ -1149,7 +1215,7 @@ Shuffles the array such that the items will have a random order. This method use :ref:`int` **size**\ (\ ) |const| :ref:`🔗` -Returns the number of elements in the array. +Returns the number of elements in the array. Empty arrays (``[]``) always return ``0``. See also :ref:`is_empty`. .. rst-class:: classref-item-separator @@ -1161,17 +1227,24 @@ Returns the number of elements in the array. :ref:`Array` **slice**\ (\ begin\: :ref:`int`, end\: :ref:`int` = 2147483647, step\: :ref:`int` = 1, deep\: :ref:`bool` = false\ ) |const| :ref:`🔗` -Returns the slice of the **Array**, from ``begin`` (inclusive) to ``end`` (exclusive), as a new **Array**. +Returns a new **Array** containing this array's elements, from index ``begin`` (inclusive) to ``end`` (exclusive), every ``step`` elements. -The absolute value of ``begin`` and ``end`` will be clamped to the array size, so the default value for ``end`` makes it slice to the size of the array by default (i.e. ``arr.slice(1)`` is a shorthand for ``arr.slice(1, arr.size())``). +If either ``begin`` or ``end`` are negative, their value is relative to the end of the array. -If either ``begin`` or ``end`` are negative, they will be relative to the end of the array (i.e. ``arr.slice(0, -2)`` is a shorthand for ``arr.slice(0, arr.size() - 2)``). +If ``step`` is negative, this method iterates through the array in reverse, returning a slice ordered backwards. For this to work, ``begin`` must be greater than ``end``. -If specified, ``step`` is the relative index between source elements. It can be negative, then ``begin`` must be higher than ``end``. For example, ``[0, 1, 2, 3, 4, 5].slice(5, 1, -2)`` returns ``[5, 3]``. +If ``deep`` is ``true``, all nested **Array** and :ref:`Dictionary` elements in the slice are duplicated from the original, recursively. See also :ref:`duplicate`). -If ``deep`` is true, each element will be copied by value rather than by reference. +:: -\ **Note:** To include the first element when ``step`` is negative, use ``arr.slice(begin, -arr.size() - 1, step)`` (i.e. ``[0, 1, 2].slice(1, -4, -1)`` returns ``[1, 0]``). + var letters = ["A", "B", "C", "D", "E", "F"] + + print(letters.slice(0, 2)) # Prints ["A", "B"] + print(letters.slice(2, -2)) # Prints ["C", "D"] + print(letters.slice(-2, 6)) # Prints ["E", "F"] + + print(letters.slice(0, 6, 2)) # Prints ["A", "C", "E"] + print(letters.slice(4, 1, -1)) # Prints ["E", "D", "C"] .. rst-class:: classref-item-separator @@ -1183,36 +1256,26 @@ If ``deep`` is true, each element will be copied by value rather than by referen |void| **sort**\ (\ ) :ref:`🔗` -Sorts the array. - -\ **Note:** The sorting algorithm used is not `stable `__. This means that values considered equal may have their order changed when using :ref:`sort`. - -\ **Note:** Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example: +Sorts the array in ascending order. The final order is dependent on the "less than" (``<``) comparison between elements. .. tabs:: .. code-tab:: gdscript - var strings = ["string1", "string2", "string10", "string11"] - strings.sort() - print(strings) # Prints [string1, string10, string11, string2] + var numbers = [10, 5, 2.5, 8] + numbers.sort() + print(numbers) # Prints [2.5, 5, 8, 10] .. code-tab:: csharp - var strings = new Godot.Collections.Array { "string1", "string2", "string10", "string11" }; - strings.Sort(); - GD.Print(strings); // Prints [string1, string10, string11, string2] - + var numbers = new Godot.Collections.Array { 10, 5, 2.5, 8 }; + numbers.Sort(); + GD.Print(numbers); // Prints [2.5, 5, 8, 10] -To perform natural order sorting, you can use :ref:`sort_custom` with :ref:`String.naturalnocasecmp_to` as follows: -:: - - var strings = ["string1", "string2", "string10", "string11"] - strings.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0) - print(strings) # Prints [string1, string2, string10, string11] +\ **Note:** The sorting algorithm used is not `stable `__. This means that equivalent elements (such as ``2`` and ``2.0``) may have their order changed when calling :ref:`sort`. .. rst-class:: classref-item-separator @@ -1224,36 +1287,39 @@ To perform natural order sorting, you can use :ref:`sort_custom`\ ) :ref:`🔗` -Sorts the array using a custom method. The custom method receives two arguments (a pair of elements from the array) and must return either ``true`` or ``false``. For two elements ``a`` and ``b``, if the given method returns ``true``, element ``b`` will be after element ``a`` in the array. - -\ **Note:** The sorting algorithm used is not `stable `__. This means that values considered equal may have their order changed when using :ref:`sort_custom`. +Sorts the array using a custom :ref:`Callable`. -\ **Note:** You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Randomizing the return value will result in unexpected behavior. +\ ``func`` is called as many times as necessary, receiving two array elements as arguments. The function should return ``true`` if the first element should be moved *behind* the second one, otherwise it should return ``false``. - -.. tabs:: - - .. code-tab:: gdscript +:: func sort_ascending(a, b): - if a[0] < b[0]: + if a[1] < b[1]: return true return false func _ready(): - var my_items = [[5, "Potato"], [9, "Rice"], [4, "Tomato"]] + var my_items = [["Tomato", 5], ["Apple", 9], ["Rice", 4]] my_items.sort_custom(sort_ascending) - print(my_items) # Prints [[4, Tomato], [5, Potato], [9, Rice]]. + print(my_items) # Prints [["Rice", 4], ["Tomato", 5], ["Apple", 9]] - # Descending, lambda version. + # Sort descending, using a lambda function. my_items.sort_custom(func(a, b): return a[0] > b[0]) - print(my_items) # Prints [[9, Rice], [5, Potato], [4, Tomato]]. + print(my_items) # Prints [["Apple", 9], ["Tomato", 5], ["Rice", 4]] - .. code-tab:: csharp +It may also be necessary to use this method to sort strings by natural order, with :ref:`String.naturalnocasecmp_to`, as in the following example: - // There is no custom sort support for Godot.Collections.Array +:: + var files = ["newfile1", "newfile2", "newfile10", "newfile11"] + files.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0) + print(files) # Prints ["newfile1", "newfile2", "newfile10", "newfile11"] +\ **Note:** In C#, this method is not supported. + +\ **Note:** The sorting algorithm used is not `stable `__. This means that values considered equal may have their order changed when calling this method. + +\ **Note:** You should not randomize the return value of ``func``, as the heapsort algorithm expects a consistent result. Randomizing the return value will result in unexpected behavior. .. rst-class:: classref-section-separator @@ -1270,7 +1336,7 @@ Operator Descriptions :ref:`bool` **operator !=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` -Compares the left operand **Array** against the ``right`` **Array**. Returns ``true`` if the sizes or contents of the arrays are *not* equal, ``false`` otherwise. +Returns ``true`` if the array's size or its elements are different than ``right``'s. .. rst-class:: classref-item-separator @@ -1282,7 +1348,27 @@ Compares the left operand **Array** against the ``right`` **Array**. Returns ``t :ref:`Array` **operator +**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` -Concatenates two **Array**\ s together, with the ``right`` **Array** being added to the end of the **Array** specified in the left operand. For example, ``[1, 2] + [3, 4]`` results in ``[1, 2, 3, 4]``. +Appends the ``right`` array to the left operand, creating a new **Array**. This is also known as an array concatenation. + + +.. tabs:: + + .. code-tab:: gdscript + + var array1 = ["One", 2] + var array2 = [3, "Four"] + print(array1 + array2) # Prints ["One", 2, 3, "Four"] + + .. code-tab:: csharp + + // Note that concatenation is not possible with C#'s native Array type. + var array1 = new Godot.Collections.Array{"One", 2}; + var array2 = new Godot.Collections.Array{3, "Four"}; + GD.Print(array1 + array2); // Prints ["One", 2, 3, "Four"] + + + +\ **Note:** For existing arrays, :ref:`append_array` is much more efficient than concatenation and assignment with the ``+=`` operator. .. rst-class:: classref-item-separator @@ -1294,7 +1380,9 @@ Concatenates two **Array**\ s together, with the ``right`` **Array** being added :ref:`bool` **operator <**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` -Performs a comparison for each index between the left operand **Array** and the ``right`` **Array**, considering the highest common index of both arrays for this comparison: Returns ``true`` on the first occurrence of an element that is less, or ``false`` if the element is greater. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns ``false`` if the left operand **Array** has fewer elements, otherwise it returns ``true``. +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than ``right``'s, ``false`` if this element is greater. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is less than ``right``'s, otherwise returns ``false``. .. rst-class:: classref-item-separator @@ -1306,7 +1394,9 @@ Performs a comparison for each index between the left operand **Array** and the :ref:`bool` **operator <=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` -Performs a comparison for each index between the left operand **Array** and the ``right`` **Array**, considering the highest common index of both arrays for this comparison: Returns ``true`` on the first occurrence of an element that is less, or ``false`` if the element is greater. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns ``true`` if the left operand **Array** has the same number of elements or fewer, otherwise it returns ``false``. +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than ``right``'s, ``false`` if this element is greater. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is less or equal to ``right``'s, otherwise returns ``false``. .. rst-class:: classref-item-separator @@ -1330,7 +1420,9 @@ Compares the left operand **Array** against the ``right`` **Array**. Returns ``t :ref:`bool` **operator >**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` -Performs a comparison for each index between the left operand **Array** and the ``right`` **Array**, considering the highest common index of both arrays for this comparison: Returns ``true`` on the first occurrence of an element that is greater, or ``false`` if the element is less. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns ``true`` if the ``right`` **Array** has more elements, otherwise it returns ``false``. +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than ``right``'s, ``false`` if this element is less. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is greater than ``right``'s, otherwise returns ``false``. .. rst-class:: classref-item-separator @@ -1342,7 +1434,9 @@ Performs a comparison for each index between the left operand **Array** and the :ref:`bool` **operator >=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` -Performs a comparison for each index between the left operand **Array** and the ``right`` **Array**, considering the highest common index of both arrays for this comparison: Returns ``true`` on the first occurrence of an element that is greater, or ``false`` if the element is less. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns ``true`` if the ``right`` **Array** has more or the same number of elements, otherwise it returns ``false``. +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than ``right``'s, ``false`` if this element is less. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is greater or equal to ``right``'s, otherwise returns ``false``. .. rst-class:: classref-item-separator @@ -1354,7 +1448,7 @@ Performs a comparison for each index between the left operand **Array** and the :ref:`Variant` **operator []**\ (\ index\: :ref:`int`\ ) :ref:`🔗` -Returns a reference to the element of type :ref:`Variant` at the specified location. Arrays start at index 0. ``index`` can be a zero or positive value to start from the beginning, or a negative value to start from the end. Out-of-bounds array access causes a run-time error, which will result in an error being printed and the project execution pausing if run from the editor. +Returns the :ref:`Variant` element at the specified ``index``. Arrays start at index 0. If ``index`` is greater or equal to ``0``, the element is fetched starting from the beginning of the array. If ``index`` is a negative value, the element is fetched starting from the end. Accessing an array out-of-bounds will cause a run-time error, pausing the project execution if run from the editor. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_arraymesh.rst b/classes/class_arraymesh.rst index 629392dde74..a1769807e4f 100644 --- a/classes/class_arraymesh.rst +++ b/classes/class_arraymesh.rst @@ -197,7 +197,9 @@ Overrides the :ref:`AABB` with one defined by user for use with frus - |void| **set_shadow_mesh**\ (\ value\: :ref:`ArrayMesh`\ ) - :ref:`ArrayMesh` **get_shadow_mesh**\ (\ ) -An optional mesh which is used for rendering shadows and can be used for the depth prepass. Can be used to increase performance of shadow rendering by using a mesh that only contains vertex position data (without normals, UVs, colors, etc.). +An optional mesh which can be used for rendering shadows and the depth prepass. Can be used to increase performance by supplying a mesh with fused vertices and only vertex position data (without normals, UVs, colors, etc.). + +\ **Note:** This mesh must have exactly the same vertex positions as the source mesh (including the source mesh's LODs, if present). If vertex positions differ, then the mesh will not draw correctly. .. rst-class:: classref-section-separator diff --git a/classes/class_atlastexture.rst b/classes/class_atlastexture.rst index 42228a2387e..70457128a5c 100644 --- a/classes/class_atlastexture.rst +++ b/classes/class_atlastexture.rst @@ -116,7 +116,7 @@ The margin around the :ref:`region`. Useful - |void| **set_region**\ (\ value\: :ref:`Rect2`\ ) - :ref:`Rect2` **get_region**\ (\ ) -The region used to draw the :ref:`atlas`. +The region used to draw the :ref:`atlas`. If either dimension of the region's size is ``0``, the value from :ref:`atlas` size will be used for that axis instead. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_audioeffectspectrumanalyzer.rst b/classes/class_audioeffectspectrumanalyzer.rst index c2f812bfd36..2a862c5c0f3 100644 --- a/classes/class_audioeffectspectrumanalyzer.rst +++ b/classes/class_audioeffectspectrumanalyzer.rst @@ -21,6 +21,8 @@ Description This audio effect does not affect sound output, but can be used for real-time audio visualizations. +This resource configures an :ref:`AudioEffectSpectrumAnalyzerInstance`, which performs the actual analysis at runtime. An instance can be acquired with :ref:`AudioServer.get_bus_effect_instance`. + See also :ref:`AudioStreamGenerator` for procedurally generating sounds. .. rst-class:: classref-introduction-group diff --git a/classes/class_audioeffectspectrumanalyzerinstance.rst b/classes/class_audioeffectspectrumanalyzerinstance.rst index bd15e48e710..68c533dcf73 100644 --- a/classes/class_audioeffectspectrumanalyzerinstance.rst +++ b/classes/class_audioeffectspectrumanalyzerinstance.rst @@ -12,9 +12,23 @@ AudioEffectSpectrumAnalyzerInstance **Inherits:** :ref:`AudioEffectInstance` **<** :ref:`RefCounted` **<** :ref:`Object` -.. container:: contribute +Queryable instance of an :ref:`AudioEffectSpectrumAnalyzer`. - There is currently no description for this class. Please help us by :ref:`contributing one `! +.. rst-class:: classref-introduction-group + +Description +----------- + +The runtime part of an :ref:`AudioEffectSpectrumAnalyzer`, which can be used to query the magnitude of a frequency range on its host bus. + +An instance of this class can be acquired with :ref:`AudioServer.get_bus_effect_instance`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Audio Spectrum Visualizer Demo `__ .. rst-class:: classref-reftable-group @@ -49,7 +63,7 @@ enum **MagnitudeMode**: :ref:`🔗` **MAGNITUDE_AVERAGE** = ``0`` -Use the average value as magnitude. +Use the average value across the frequency range as magnitude. .. _class_AudioEffectSpectrumAnalyzerInstance_constant_MAGNITUDE_MAX: @@ -57,7 +71,7 @@ Use the average value as magnitude. :ref:`MagnitudeMode` **MAGNITUDE_MAX** = ``1`` -Use the maximum value as magnitude. +Use the maximum value of the frequency range as magnitude. .. rst-class:: classref-section-separator @@ -74,9 +88,9 @@ Method Descriptions :ref:`Vector2` **get_magnitude_for_frequency_range**\ (\ from_hz\: :ref:`float`, to_hz\: :ref:`float`, mode\: :ref:`MagnitudeMode` = 1\ ) |const| :ref:`🔗` -.. container:: contribute +Returns the magnitude of the frequencies from ``from_hz`` to ``to_hz`` in linear energy as a Vector2. The ``x`` component of the return value represents the left stereo channel, and ``y`` represents the right channel. - There is currently no description for this method. Please help us by :ref:`contributing one `! +\ ``mode`` determines how the frequency range will be processed. See :ref:`MagnitudeMode`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_audiostreamplayer.rst b/classes/class_audiostreamplayer.rst index 9f709e104b4..6c7a6c826cd 100644 --- a/classes/class_audiostreamplayer.rst +++ b/classes/class_audiostreamplayer.rst @@ -24,7 +24,7 @@ Description The **AudioStreamPlayer** node plays an audio stream non-positionally. It is ideal for user interfaces, menus, or background music. -To use this node, :ref:`stream` needs to be set to a valid :ref:`AudioStream` resource. Playing more than one sound at the time is also supported, see :ref:`max_polyphony`. +To use this node, :ref:`stream` needs to be set to a valid :ref:`AudioStream` resource. Playing more than one sound at the same time is also supported, see :ref:`max_polyphony`. If you need to play audio at a specific position, use :ref:`AudioStreamPlayer2D` or :ref:`AudioStreamPlayer3D` instead. diff --git a/classes/class_audiostreamsynchronized.rst b/classes/class_audiostreamsynchronized.rst index a83a29f5c6f..914abe5cb97 100644 --- a/classes/class_audiostreamsynchronized.rst +++ b/classes/class_audiostreamsynchronized.rst @@ -66,7 +66,7 @@ Constants **MAX_STREAMS** = ``32`` :ref:`🔗` -Maximum amount of streams that can be synchrohized. +Maximum amount of streams that can be synchronized. .. rst-class:: classref-section-separator diff --git a/classes/class_audiostreamwav.rst b/classes/class_audiostreamwav.rst index 733b5fff25a..fb21bcccfb9 100644 --- a/classes/class_audiostreamwav.rst +++ b/classes/class_audiostreamwav.rst @@ -213,7 +213,7 @@ Audio format. See :ref:`Format` constants for values - |void| **set_loop_begin**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_loop_begin**\ (\ ) -The loop start point (in number of samples, relative to the beginning of the sample). This information will be imported automatically from the WAV file if present. +The loop start point (in number of samples, relative to the beginning of the stream). This information will be imported automatically from the WAV file if present. .. rst-class:: classref-item-separator @@ -230,7 +230,7 @@ The loop start point (in number of samples, relative to the beginning of the sam - |void| **set_loop_end**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_loop_end**\ (\ ) -The loop end point (in number of samples, relative to the beginning of the sample). This information will be imported automatically from the WAV file if present. +The loop end point (in number of samples, relative to the beginning of the stream). This information will be imported automatically from the WAV file if present. .. rst-class:: classref-item-separator diff --git a/classes/class_basis.rst b/classes/class_basis.rst index e699ff6d776..5ad7ebeb811 100644 --- a/classes/class_basis.rst +++ b/classes/class_basis.rst @@ -25,7 +25,7 @@ A **Basis** is **orthogonal** if its axes are perpendicular to each other. A bas For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. -\ **Note:** Godot uses a `right-handed coordinate system `__, which is a common standard. For directions, the convention for built-in types like :ref:`Camera3D` is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the `Importing 3D Scenes <../tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions>`__ tutorial. +\ **Note:** Godot uses a `right-handed coordinate system `__, which is a common standard. For directions, the convention for built-in types like :ref:`Camera3D` is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the `3D asset direction conventions <../tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.html#d-asset-direction-conventions>`__ tutorial. \ **Note:** The basis matrices are exposed as `column-major `__ order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX. diff --git a/classes/class_button.rst b/classes/class_button.rst index 051c8071d05..6d617ac223f 100644 --- a/classes/class_button.rst +++ b/classes/class_button.rst @@ -557,7 +557,7 @@ Icon modulate :ref:`Color` used when the **Button** is being presse :ref:`int` **align_to_largest_stylebox** = ``0`` :ref:`🔗` -This constant acts as a boolean. If ``true``, text and icon are always aligned to the largest stylebox margins, otherwise it's aligned to the current button state stylebox margins. +This constant acts as a boolean. If ``true``, the minimum size of the button and text/icon alignment is always based on the largest stylebox margins, otherwise it's based on the current button state stylebox margins. .. rst-class:: classref-item-separator diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index eb18bdb7958..d5412e78e24 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -735,9 +735,9 @@ If ``true``, this **CanvasItem** is drawn. The node is only visible if all of it - |void| **set_y_sort_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_y_sort_enabled**\ (\ ) -If ``true``, this and child **CanvasItem** nodes with a lower Y position are rendered in front of nodes with a higher Y position. If ``false``, this and child **CanvasItem** nodes are rendered normally in scene tree order. +If ``true``, this and child **CanvasItem** nodes with a higher Y position are rendered in front of nodes with a lower Y position. If ``false``, this and child **CanvasItem** nodes are rendered normally in scene tree order. -With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc) render together on the same Y position as the child node 'B'. This allows you to organize the render order of a scene without changing the scene tree. +With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree. Nodes sort relative to each other only if they are on the same :ref:`z_index`. @@ -1470,6 +1470,8 @@ Returns ``true`` if global transform notifications are communicated to children. Returns ``true`` if the node is present in the :ref:`SceneTree`, its :ref:`visible` property is ``true`` and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see :ref:`_draw`). +Visibility is checked only in parent nodes that inherit from **CanvasItem**, :ref:`CanvasLayer`, and :ref:`Window`. If the parent is of any other type (such as :ref:`Node`, :ref:`AnimationPlayer`, or :ref:`Node3D`), it is assumed to be visible. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_color.rst b/classes/class_color.rst index f91df07a16d..08a71e5faf2 100644 --- a/classes/class_color.rst +++ b/classes/class_color.rst @@ -1771,6 +1771,8 @@ Decodes a **Color** from an RGBE9995 format integer. See :ref:`Image.FORMAT_RGBE Creates a **Color** from the given string, which can be either an HTML color code or a named color (case-insensitive). Returns ``default`` if the color cannot be inferred from the string. +If you want to create a color from String in a constant expression, use the equivalent constructor instead (i.e. ``Color("color string")``). + .. rst-class:: classref-item-separator ---- @@ -1816,6 +1818,8 @@ In GDScript and C#, the :ref:`int` is best visualized with hexadecima +If you want to use hex notation in a constant expression, use the equivalent constructor instead (i.e. ``Color(0xRRGGBBAA)``). + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_compositoreffect.rst b/classes/class_compositoreffect.rst index fc44b84775d..9c644ec5d53 100644 --- a/classes/class_compositoreffect.rst +++ b/classes/class_compositoreffect.rst @@ -21,7 +21,7 @@ This resource allows for creating a custom rendering effect. Description ----------- -This resource defines a custom rendering effect that can be applied to :ref:`Viewport`\ s through the viewports' :ref:`Environment`. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. +This resource defines a custom rendering effect that can be applied to :ref:`Viewport`\ s through the viewports' :ref:`Environment`. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. CompositorEffect is an abstract base class and must be extended to implement specific rendering logic. .. rst-class:: classref-reftable-group diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst index 12dbf7269bf..2b3e7ac3edc 100644 --- a/classes/class_dictionary.rst +++ b/classes/class_dictionary.rst @@ -615,8 +615,6 @@ This method is useful for quickly making dictionaries with default values: # Prints { "fruit": "apple", "vegetable": "potato", "dressing": "vinegar" } print(extra.merged(base, true)) -See also :ref:`merge`. - .. rst-class:: classref-item-separator ---- diff --git a/classes/class_displayserver.rst b/classes/class_displayserver.rst index 069dc41ba27..86ce5173f49 100644 --- a/classes/class_displayserver.rst +++ b/classes/class_displayserver.rst @@ -190,6 +190,8 @@ Methods +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`global_menu_set_popup_callbacks`\ (\ menu_root\: :ref:`String`, open_callback\: :ref:`Callable`, close_callback\: :ref:`Callable`\ ) | +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_additional_outputs`\ (\ ) |const| | + +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_feature`\ (\ feature\: :ref:`Feature`\ ) |const| | +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`help_set_search_callbacks`\ (\ search_callback\: :ref:`Callable`, action_callback\: :ref:`Callable`\ ) | @@ -230,6 +232,8 @@ Methods +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`process_events`\ (\ ) | +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`register_additional_output`\ (\ object\: :ref:`Object`\ ) | + +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`screen_get_dpi`\ (\ screen\: :ref:`int` = -1\ ) |const| | +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Image` | :ref:`screen_get_image`\ (\ screen\: :ref:`int` = -1\ ) |const| | @@ -298,6 +302,8 @@ Methods +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`tts_stop`\ (\ ) | +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`unregister_additional_output`\ (\ object\: :ref:`Object`\ ) | + +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`virtual_keyboard_get_height`\ (\ ) |const| | +-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`virtual_keyboard_hide`\ (\ ) | @@ -1508,6 +1514,8 @@ Returns the user's clipboard as a string if possible. Returns the user's clipboard as an image if possible. +\ **Note:** This method uses the copied pixel data, e.g. from a image editing software or a web browser, not an image file copied from file explorer. + .. rst-class:: classref-item-separator ---- @@ -2875,6 +2883,18 @@ Registers callables to emit when the menu is respectively about to show or close ---- +.. _class_DisplayServer_method_has_additional_outputs: + +.. rst-class:: classref-method + +:ref:`bool` **has_additional_outputs**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if any additional outputs have been registered via :ref:`register_additional_output`. + +.. rst-class:: classref-item-separator + +---- + .. _class_DisplayServer_method_has_feature: .. rst-class:: classref-method @@ -3143,6 +3163,20 @@ Perform window manager processing, including input flushing. See also :ref:`forc ---- +.. _class_DisplayServer_method_register_additional_output: + +.. rst-class:: classref-method + +|void| **register_additional_output**\ (\ object\: :ref:`Object`\ ) :ref:`🔗` + +Registers an :ref:`Object` which represents an additional output that will be rendered too, beyond normal windows. The :ref:`Object` is only used as an identifier, which can be later passed to :ref:`unregister_additional_output`. + +This can be used to prevent Godot from skipping rendering when no normal windows are visible. + +.. rst-class:: classref-item-separator + +---- + .. _class_DisplayServer_method_screen_get_dpi: .. rst-class:: classref-method @@ -3713,6 +3747,18 @@ Stops synthesis in progress and removes all utterances from the queue. ---- +.. _class_DisplayServer_method_unregister_additional_output: + +.. rst-class:: classref-method + +|void| **unregister_additional_output**\ (\ object\: :ref:`Object`\ ) :ref:`🔗` + +Unregisters an :ref:`Object` representing an additional output, that was registered via :ref:`register_additional_output`. + +.. rst-class:: classref-item-separator + +---- + .. _class_DisplayServer_method_virtual_keyboard_get_height: .. rst-class:: classref-method diff --git a/classes/class_editorexportplatformios.rst b/classes/class_editorexportplatformios.rst index 52e39a1acc6..e8473aacae5 100644 --- a/classes/class_editorexportplatformios.rst +++ b/classes/class_editorexportplatformios.rst @@ -983,7 +983,7 @@ Indicates whether your app uses advertising data for tracking. :ref:`bool` **privacy/collected_data/audio_data/collected** :ref:`🔗` -Indicates whether your app collects audio data data. +Indicates whether your app collects audio data. .. rst-class:: classref-item-separator @@ -1007,7 +1007,7 @@ The reasons your app collects audio data. See `Describing data use in privacy ma :ref:`bool` **privacy/collected_data/audio_data/linked_to_user** :ref:`🔗` -Indicates whether your app links audio data data to the user's identity. +Indicates whether your app links audio data to the user's identity. .. rst-class:: classref-item-separator @@ -1019,7 +1019,7 @@ Indicates whether your app links audio data data to the user's identity. :ref:`bool` **privacy/collected_data/audio_data/used_for_tracking** :ref:`🔗` -Indicates whether your app uses audio data data for tracking. +Indicates whether your app uses audio data for tracking. .. rst-class:: classref-item-separator diff --git a/classes/class_editorexportplatformmacos.rst b/classes/class_editorexportplatformmacos.rst index 33dbdf9f98f..3bea82b2380 100644 --- a/classes/class_editorexportplatformmacos.rst +++ b/classes/class_editorexportplatformmacos.rst @@ -1335,7 +1335,7 @@ Indicates whether your app uses advertising data for tracking. :ref:`bool` **privacy/collected_data/audio_data/collected** :ref:`🔗` -Indicates whether your app collects audio data data. +Indicates whether your app collects audio data. .. rst-class:: classref-item-separator @@ -1359,7 +1359,7 @@ The reasons your app collects audio data. See `Describing data use in privacy ma :ref:`bool` **privacy/collected_data/audio_data/linked_to_user** :ref:`🔗` -Indicates whether your app links audio data data to the user's identity. +Indicates whether your app links audio data to the user's identity. .. rst-class:: classref-item-separator @@ -1371,7 +1371,7 @@ Indicates whether your app links audio data data to the user's identity. :ref:`bool` **privacy/collected_data/audio_data/used_for_tracking** :ref:`🔗` -Indicates whether your app uses audio data data for tracking. +Indicates whether your app uses audio data for tracking. .. rst-class:: classref-item-separator diff --git a/classes/class_editorexportplatformwindows.rst b/classes/class_editorexportplatformwindows.rst index d87b04a1227..d9041fcafcf 100644 --- a/classes/class_editorexportplatformwindows.rst +++ b/classes/class_editorexportplatformwindows.rst @@ -187,7 +187,7 @@ If set to ``1``, ANGLE libraries are exported with the exported application. If :ref:`int` **application/export_d3d12** :ref:`🔗` -If set to ``1``, Direct3D 12 runtime (DXIL, Agility SDK, PIX) libraries are exported with the exported application. If set to ``0``, Direct3D 12 libraries are exported only if :ref:`ProjectSettings.rendering/rendering_device/driver` is set to ``"d3d12"``. +If set to ``1``, the Direct3D 12 runtime libraries (Agility SDK, PIX) are exported with the exported application. If set to ``0``, Direct3D 12 libraries are exported only if :ref:`ProjectSettings.rendering/rendering_device/driver` is set to ``"d3d12"``. .. rst-class:: classref-item-separator diff --git a/classes/class_editorexportplugin.rst b/classes/class_editorexportplugin.rst index 9bf24e20d1c..241e572665d 100644 --- a/classes/class_editorexportplugin.rst +++ b/classes/class_editorexportplugin.rst @@ -127,7 +127,7 @@ Method Descriptions Return ``true`` if this plugin will customize resources based on the platform and features used. -When enabled, :ref:`_get_customization_configuration_hash`, :ref:`_customize_resource` and :ref:`_customize_scene` will be called and must be implemented. +When enabled, :ref:`_get_customization_configuration_hash` and :ref:`_customize_resource` will be called and must be implemented. .. rst-class:: classref-item-separator @@ -139,7 +139,9 @@ When enabled, :ref:`_get_customization_configuration_hash` **_begin_customize_scenes**\ (\ platform\: :ref:`EditorExportPlatform`, features\: :ref:`PackedStringArray`\ ) |virtual| |const| :ref:`🔗` -Return true if this plugin will customize scenes based on the platform and features used. +Return ``true`` if this plugin will customize scenes based on the platform and features used. + +When enabled, :ref:`_get_customization_configuration_hash` and :ref:`_customize_scene` will be called and must be implemented. .. rst-class:: classref-item-separator @@ -229,7 +231,7 @@ Virtual method to be overridden by the user. Called when the export is finished. |void| **_export_file**\ (\ path\: :ref:`String`, type\: :ref:`String`, features\: :ref:`PackedStringArray`\ ) |virtual| :ref:`🔗` -Virtual method to be overridden by the user. Called for each exported file, providing arguments that can be used to identify the file. ``path`` is the path of the file, ``type`` is the :ref:`Resource` represented by the file (e.g. :ref:`PackedScene`) and ``features`` is the list of features for the export. +Virtual method to be overridden by the user. Called for each exported file before :ref:`_customize_resource` and :ref:`_customize_scene`. The arguments can be used to identify the file. ``path`` is the path of the file, ``type`` is the :ref:`Resource` represented by the file (e.g. :ref:`PackedScene`), and ``features`` is the list of features for the export. Calling :ref:`skip` inside this callback will make the file not included in the export. @@ -467,6 +469,8 @@ Adds a custom file to be exported. ``path`` is the virtual path that can be used When called inside :ref:`_export_file` and ``remap`` is ``true``, the current file will not be exported, but instead remapped to this custom file. ``remap`` is ignored when called in other places. +\ ``file`` will not be imported, so consider using :ref:`_customize_resource` to remap imported resources. + .. rst-class:: classref-item-separator ---- @@ -607,7 +611,7 @@ Returns the current value of an export option supplied by :ref:`_get_export_opti |void| **skip**\ (\ ) :ref:`🔗` -To be called inside :ref:`_export_file`, :ref:`_customize_resource`, or :ref:`_customize_scene`. Skips the current file, so it's not included in the export. +To be called inside :ref:`_export_file`. Skips the current file, so it's not included in the export. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_editorfilesystem.rst b/classes/class_editorfilesystem.rst index b144a8ac710..88106cc11bb 100644 --- a/classes/class_editorfilesystem.rst +++ b/classes/class_editorfilesystem.rst @@ -84,6 +84,18 @@ Emitted if a resource is reimported. ---- +.. _class_EditorFileSystem_signal_resources_reimporting: + +.. rst-class:: classref-signal + +**resources_reimporting**\ (\ resources\: :ref:`PackedStringArray`\ ) :ref:`🔗` + +Emitted before a resource is reimported. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorFileSystem_signal_resources_reload: .. rst-class:: classref-signal diff --git a/classes/class_editorimportplugin.rst b/classes/class_editorimportplugin.rst index cdebc608398..eea95e10a9b 100644 --- a/classes/class_editorimportplugin.rst +++ b/classes/class_editorimportplugin.rst @@ -120,18 +120,18 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr }; } - public override int _Import(string sourceFile, string savePath, Godot.Collections.Dictionary options, Godot.Collections.Array platformVariants, Godot.Collections.Array genFiles) + public override Error _Import(string sourceFile, string savePath, Godot.Collections.Dictionary options, Godot.Collections.Array platformVariants, Godot.Collections.Array genFiles) { using var file = FileAccess.Open(sourceFile, FileAccess.ModeFlags.Read); if (file.GetError() != Error.Ok) { - return (int)Error.Failed; + return Error.Failed; } var mesh = new ArrayMesh(); // Fill the Mesh with data read in "file", left as an exercise to the reader. string filename = $"{savePath}.{_GetSaveExtension()}"; - return (int)ResourceSaver.Save(mesh, filename); + return ResourceSaver.Save(mesh, filename); } } @@ -388,7 +388,7 @@ This method must be overridden to do the actual importing work. See this class' :ref:`Error` **append_import_external_resource**\ (\ path\: :ref:`String`, custom_options\: :ref:`Dictionary` = {}, custom_importer\: :ref:`String` = "", generator_parameters\: :ref:`Variant` = null\ ) :ref:`🔗` -This function can only be called during the :ref:`_import` callback and it allows manually importing resources from it. This is useful when the imported file generates external resources that require importing (as example, images). Custom parameters for the ".import" file can be passed via the ``custom_options``. Additionally, in cases where multiple importers can handle a file, the ``custom_importer`` ca be specified to force a specific one. This function performs a resource import and returns immediately with a success or error code. ``generator_parameters`` defines optional extra metadata which will be stored as ``generator_parameters`` in the ``remap`` section of the ``.import`` file, for example to store a md5 hash of the source data. +This function can only be called during the :ref:`_import` callback and it allows manually importing resources from it. This is useful when the imported file generates external resources that require importing (as example, images). Custom parameters for the ".import" file can be passed via the ``custom_options``. Additionally, in cases where multiple importers can handle a file, the ``custom_importer`` can be specified to force a specific one. This function performs a resource import and returns immediately with a success or error code. ``generator_parameters`` defines optional extra metadata which will be stored as ``generator_parameters`` in the ``remap`` section of the ``.import`` file, for example to store a md5 hash of the source data. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_editorplugin.rst b/classes/class_editorplugin.rst index cd00a3e7b51..c86d0689e21 100644 --- a/classes/class_editorplugin.rst +++ b/classes/class_editorplugin.rst @@ -586,7 +586,7 @@ Called by the engine when the 3D editor's viewport is updated. Use the ``overlay func _forward_3d_draw_over_viewport(overlay): # Draw a circle at cursor position. - overlay.draw_circle(overlay.get_local_mouse_position(), 64) + overlay.draw_circle(overlay.get_local_mouse_position(), 64, Color.WHITE) func _forward_3d_gui_input(camera, event): if event is InputEventMouseMotion: @@ -1143,7 +1143,7 @@ Optionally, you can specify a shortcut parameter. When pressed, this shortcut wi |void| **add_custom_type**\ (\ type\: :ref:`String`, base\: :ref:`String`, script\: :ref:`Script`, icon\: :ref:`Texture2D`\ ) :ref:`🔗` -Adds a custom type, which will appear in the list of nodes or resources. An icon can be optionally passed. +Adds a custom type, which will appear in the list of nodes or resources. When a given node or resource is selected, the base type will be instantiated (e.g. "Node3D", "Control", "Resource"), then the script will be loaded and set to this object. diff --git a/classes/class_editorsettings.rst b/classes/class_editorsettings.rst index 620979d2e10..0a147646091 100644 --- a/classes/class_editorsettings.rst +++ b/classes/class_editorsettings.rst @@ -187,6 +187,8 @@ Properties +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`editors/animation/autorename_animation_tracks` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`editors/animation/confirm_insert_track` | + +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`editors/animation/default_create_bezier_tracks` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`editors/animation/default_create_reset_tracks` | @@ -305,6 +307,10 @@ Properties +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`filesystem/tools/oidn/oidn_denoise_path` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`input/buffering/agile_event_flushing` | + +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`input/buffering/use_accumulated_input` | + +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`interface/editor/accept_dialog_cancel_ok_buttons` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`interface/editor/automatically_open_screenshots` | @@ -321,8 +327,6 @@ Properties +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`interface/editor/custom_display_scale` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`interface/editor/debug/enable_pseudolocalization` | - +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`interface/editor/display_scale` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`interface/editor/dock_tab_style` | @@ -569,6 +573,8 @@ Properties +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`text_editor/behavior/indent/type` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`text_editor/behavior/navigation/custom_word_separators` | + +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`text_editor/behavior/navigation/drag_and_drop_selection` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`text_editor/behavior/navigation/move_caret_on_right_click` | @@ -581,6 +587,10 @@ Properties +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`text_editor/behavior/navigation/stay_in_script_editor_on_node_selected` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`text_editor/behavior/navigation/use_custom_word_separators` | + +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`text_editor/behavior/navigation/use_default_word_separators` | + +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`text_editor/behavior/navigation/v_scroll_speed` | +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`text_editor/completion/add_node_path_literals` | @@ -1595,6 +1605,20 @@ If ``true``, automatically updates animation tracks' target paths when renaming ---- +.. _class_EditorSettings_property_editors/animation/confirm_insert_track: + +.. rst-class:: classref-property + +:ref:`bool` **editors/animation/confirm_insert_track** :ref:`🔗` + +If ``true``, display a confirmation dialog when adding a new track to an animation by pressing the "key" icon next to a property. Holding Shift will bypass the dialog. + +If ``false``, the behavior is reversed, i.e. the dialog only appears when Shift is held. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorSettings_property_editors/animation/default_create_bezier_tracks: .. rst-class:: classref-property @@ -2341,6 +2365,38 @@ To enable this feature for your specific project, use :ref:`ProjectSettings.rend ---- +.. _class_EditorSettings_property_input/buffering/agile_event_flushing: + +.. rst-class:: classref-property + +:ref:`bool` **input/buffering/agile_event_flushing** :ref:`🔗` + +If ``true``, input events will be flushed just before every idle and physics frame. + +If ``false``, these events will be flushed only once per process frame, between iterations of the engine. + +Enabling this setting can greatly improve input responsiveness, especially in devices that struggle to run at the project's intended frame rate. + +.. rst-class:: classref-item-separator + +---- + +.. _class_EditorSettings_property_input/buffering/use_accumulated_input: + +.. rst-class:: classref-property + +:ref:`bool` **input/buffering/use_accumulated_input** :ref:`🔗` + +If ``true``, similar input events sent by the operating system are accumulated. When input accumulation is enabled, all input events generated during a frame will be merged and emitted when the frame is done rendering. Therefore, this limits the number of input method calls per second to the rendering FPS. + +Input accumulation can be disabled to get slightly more precise/reactive input at the cost of increased CPU usage. + +\ **Note:** Input accumulation is *enabled* by default. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorSettings_property_interface/editor/accept_dialog_cancel_ok_buttons: .. rst-class:: classref-property @@ -2451,20 +2507,6 @@ The custom editor scale factor to use. This can be used for displays with very h ---- -.. _class_EditorSettings_property_interface/editor/debug/enable_pseudolocalization: - -.. rst-class:: classref-property - -:ref:`bool` **interface/editor/debug/enable_pseudolocalization** :ref:`🔗` - -If ``true``, lengthens the editor's localizable strings and replaces their characters with accented variants. This allows spotting non-localizable strings easily, while also ensuring the UI layout doesn't break when strings are made longer (as many languages require strings to be longer). - -This is a debugging feature and should only be enabled when working on the editor itself. - -.. rst-class:: classref-item-separator - ----- - .. _class_EditorSettings_property_interface/editor/display_scale: .. rst-class:: classref-property @@ -2753,6 +2795,8 @@ The default **Auto** value will only enable this if the editor was compiled with \ **Note:** If :ref:`interface/editor/update_continuously` is ``true``, the spinner icon displays in red. +\ **Note:** If the editor was started with the ``--debug-canvas-item-redraw`` :doc:`command line argument <../tutorials/editor/command_line_tutorial>`, the update spinner will *never* display regardless of this setting's value. This is to avoid confusion with what would cause redrawing in real world scenarios. + .. rst-class:: classref-item-separator ---- @@ -2763,7 +2807,9 @@ The default **Auto** value will only enable this if the editor was compiled with :ref:`bool` **interface/editor/single_window_mode** :ref:`🔗` -If ``true``, embed modal windows such as docks inside the main editor window. When single-window mode is enabled, tooltips will also be embedded inside the main editor window, which means they can't be displayed outside of the editor window. +If ``true``, embed modal windows such as docks inside the main editor window. When single-window mode is enabled, tooltips will also be embedded inside the main editor window, which means they can't be displayed outside of the editor window. Single-window mode can be faster as it does not need to create a separate window for every popup and tooltip, which can be a slow operation depending on the operating system and rendering method in use. + +This is equivalent to :ref:`ProjectSettings.display/window/subwindows/embed_subwindows` in the running project, except the setting's value is inverted. \ **Note:** To query whether the editor can use multiple windows in an editor plugin, use :ref:`EditorInterface.is_multi_window_enabled` instead of querying the value of this editor setting. @@ -4045,6 +4091,18 @@ The indentation style to use (tabs or spaces). ---- +.. _class_EditorSettings_property_text_editor/behavior/navigation/custom_word_separators: + +.. rst-class:: classref-property + +:ref:`String` **text_editor/behavior/navigation/custom_word_separators** :ref:`🔗` + +The characters to consider as word delimiters if :ref:`text_editor/behavior/navigation/use_custom_word_separators` is ``true``. This is in addition to default characters if :ref:`text_editor/behavior/navigation/use_default_word_separators` is ``true``. The characters should be defined without separation, for example ``_♥=``. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorSettings_property_text_editor/behavior/navigation/drag_and_drop_selection: .. rst-class:: classref-property @@ -4099,7 +4157,7 @@ If ``true``, allows scrolling past the end of the file. :ref:`bool` **text_editor/behavior/navigation/smooth_scrolling** :ref:`🔗` -If ``true``, allows scrolling in sub-line intervals and enables a smooth scrolling animation when using the mouse wheel to scroll. +If ``true``, enables a smooth scrolling animation when using the mouse wheel to scroll. See :ref:`text_editor/behavior/navigation/v_scroll_speed` for the speed of this animation. \ **Note:** :ref:`text_editor/behavior/navigation/smooth_scrolling` currently behaves poorly in projects where :ref:`ProjectSettings.physics/common/physics_ticks_per_second` has been increased significantly from its default value (``60``). In this case, it is recommended to disable this setting. @@ -4119,13 +4177,37 @@ If ``true``, prevents automatically switching between the Script and 2D/3D scree ---- +.. _class_EditorSettings_property_text_editor/behavior/navigation/use_custom_word_separators: + +.. rst-class:: classref-property + +:ref:`bool` **text_editor/behavior/navigation/use_custom_word_separators** :ref:`🔗` + +If ``true``, uses the characters in :ref:`text_editor/behavior/navigation/custom_word_separators` as word separators for word navigation and operations. This is in addition to the default characters if :ref:`text_editor/behavior/navigation/use_default_word_separators` is also enabled. Word navigation and operations include double-clicking on a word or holding :kbd:`Ctrl` (:kbd:`Cmd` on macOS) while pressing :kbd:`left`, :kbd:`right`, :kbd:`backspace`, or :kbd:`delete`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_EditorSettings_property_text_editor/behavior/navigation/use_default_word_separators: + +.. rst-class:: classref-property + +:ref:`bool` **text_editor/behavior/navigation/use_default_word_separators** :ref:`🔗` + +If ``true``, uses the characters in ```!"#$%&'()*+,-./:;<=>?@[\]^`{|}~``, the Unicode General Punctuation table, and the Unicode CJK Punctuation table as word separators for word navigation and operations. If ``false``, a subset of these characters are used and does not include the characters ``<>$~^=+|``. This is in addition to custom characters if :ref:`text_editor/behavior/navigation/use_custom_word_separators` is also enabled. These characters are used to determine where a word stops. Word navigation and operations include double-clicking on a word or holding :kbd:`Ctrl` (:kbd:`Cmd` on macOS) while pressing :kbd:`left`, :kbd:`right`, :kbd:`backspace`, or :kbd:`delete`. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorSettings_property_text_editor/behavior/navigation/v_scroll_speed: .. rst-class:: classref-property :ref:`int` **text_editor/behavior/navigation/v_scroll_speed** :ref:`🔗` -The number of pixels to scroll with every mouse wheel increment. Higher values make the script scroll by faster when using the mouse wheel. +The speed of scrolling in lines per second when :ref:`text_editor/behavior/navigation/smooth_scrolling` is ``true``. Higher values make the script scroll by faster when using the mouse wheel. \ **Note:** You can hold down :kbd:`Alt` while using the mouse wheel to temporarily scroll 5 times faster. @@ -4199,7 +4281,7 @@ The delay in seconds after which autocompletion suggestions should be displayed :ref:`bool` **text_editor/completion/code_complete_enabled** :ref:`🔗` -If ``true``, code completion will be triggered automatically after :ref:`text_editor/completion/code_complete_delay`. If ``false``, you can still trigger completion manually by pressing :kbd:`Ctrl + Space` (:kbd:`Cmd + Space` on macOS). +If ``true``, code completion will be triggered automatically after :ref:`text_editor/completion/code_complete_delay`. Even if ``false``, code completion can be triggered manually with the ``ui_text_completion_query`` action (by default :kbd:`Ctrl + Space` or :kbd:`Cmd + Space` on macOS). .. rst-class:: classref-item-separator diff --git a/classes/class_editorundoredomanager.rst b/classes/class_editorundoredomanager.rst index a45eb3e1398..19b1042bf1e 100644 --- a/classes/class_editorundoredomanager.rst +++ b/classes/class_editorundoredomanager.rst @@ -60,6 +60,8 @@ Methods +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`create_action`\ (\ name\: :ref:`String`, merge_mode\: :ref:`MergeMode` = 0, custom_context\: :ref:`Object` = null, backward_undo_ops\: :ref:`bool` = false\ ) | +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`force_fixed_history`\ (\ ) | + +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`UndoRedo` | :ref:`get_history_undo_redo`\ (\ id\: :ref:`int`\ ) |const| | +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_object_history_id`\ (\ object\: :ref:`Object`\ ) |const| | @@ -254,6 +256,20 @@ The way undo operation are ordered in actions is dictated by ``backward_undo_ops ---- +.. _class_EditorUndoRedoManager_method_force_fixed_history: + +.. rst-class:: classref-method + +|void| **force_fixed_history**\ (\ ) :ref:`🔗` + +Forces the next operation (e.g. :ref:`add_do_method`) to use the action's history rather than guessing it from the object. This is sometimes needed when a history can't be correctly determined, like for a nested resource that doesn't have a path yet. + +This method should only be used when absolutely necessary, otherwise it might cause invalid history state. For most of complex cases, the ``custom_context`` parameter of :ref:`create_action` is sufficient. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorUndoRedoManager_method_get_history_undo_redo: .. rst-class:: classref-method diff --git a/classes/class_enetconnection.rst b/classes/class_enetconnection.rst index 2186fa03f24..17c90a4f97a 100644 --- a/classes/class_enetconnection.rst +++ b/classes/class_enetconnection.rst @@ -290,7 +290,7 @@ Sets the compression method used for network packets. These have different trade Initiates a connection to a foreign ``address`` using the specified ``port`` and allocating the requested ``channels``. Optional ``data`` can be passed during connection in the form of a 32 bit integer. -\ **Note:** You must call either :ref:`create_host` or :ref:`create_host_bound` before calling this method. +\ **Note:** You must call either :ref:`create_host` or :ref:`create_host_bound` on both ends before calling this method. .. rst-class:: classref-item-separator @@ -302,7 +302,11 @@ Initiates a connection to a foreign ``address`` using the specified ``port`` and :ref:`Error` **create_host**\ (\ max_peers\: :ref:`int` = 32, max_channels\: :ref:`int` = 0, in_bandwidth\: :ref:`int` = 0, out_bandwidth\: :ref:`int` = 0\ ) :ref:`🔗` -Create an ENetHost that will allow up to ``max_peers`` connected peers, each allocating up to ``max_channels`` channels, optionally limiting bandwidth to ``in_bandwidth`` and ``out_bandwidth``. +Creates an ENetHost that allows up to ``max_peers`` connected peers, each allocating up to ``max_channels`` channels, optionally limiting bandwidth to ``in_bandwidth`` and ``out_bandwidth`` (if greater than zero). + +This method binds a random available dynamic UDP port on the host machine at the *unspecified* address. Use :ref:`create_host_bound` to specify the address and port. + +\ **Note:** It is necessary to create a host in both client and server in order to establish a connection. .. rst-class:: classref-item-separator @@ -314,7 +318,9 @@ Create an ENetHost that will allow up to ``max_peers`` connected peers, each all :ref:`Error` **create_host_bound**\ (\ bind_address\: :ref:`String`, bind_port\: :ref:`int`, max_peers\: :ref:`int` = 32, max_channels\: :ref:`int` = 0, in_bandwidth\: :ref:`int` = 0, out_bandwidth\: :ref:`int` = 0\ ) :ref:`🔗` -Create an ENetHost like :ref:`create_host` which is also bound to the given ``bind_address`` and ``bind_port``. +Creates an ENetHost bound to the given ``bind_address`` and ``bind_port`` that allows up to ``max_peers`` connected peers, each allocating up to ``max_channels`` channels, optionally limiting bandwidth to ``in_bandwidth`` and ``out_bandwidth`` (if greater than zero). + +\ **Note:** It is necessary to create a host in both client and server in order to establish a connection. .. rst-class:: classref-item-separator @@ -438,10 +444,12 @@ Configures the DTLS server to automatically drop new connections. :ref:`Array` **service**\ (\ timeout\: :ref:`int` = 0\ ) :ref:`🔗` -Waits for events on the host specified and shuttles packets between the host and its peers. The returned :ref:`Array` will have 4 elements. An :ref:`EventType`, the :ref:`ENetPacketPeer` which generated the event, the event associated data (if any), the event associated channel (if any). If the generated event is :ref:`EVENT_RECEIVE`, the received packet will be queued to the associated :ref:`ENetPacketPeer`. +Waits for events on this connection and shuttles packets between the host and its peers, with the given ``timeout`` (in milliseconds). The returned :ref:`Array` will have 4 elements. An :ref:`EventType`, the :ref:`ENetPacketPeer` which generated the event, the event associated data (if any), the event associated channel (if any). If the generated event is :ref:`EVENT_RECEIVE`, the received packet will be queued to the associated :ref:`ENetPacketPeer`. Call this function regularly to handle connections, disconnections, and to receive new packets. +\ **Note:** This method must be called on both ends involved in the event (sending and receiving hosts). + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_filedialog.rst b/classes/class_filedialog.rst index 29bc9d9638e..b61b1c59457 100644 --- a/classes/class_filedialog.rst +++ b/classes/class_filedialog.rst @@ -279,7 +279,7 @@ Property Descriptions The file system access scope. See :ref:`Access` constants. -\ **Warning:** Currently, in sandboxed environments such as Web builds or sandboxed macOS apps, FileDialog cannot access the host file system. See `godot-proposals#1123 `__. +\ **Warning:** In Web builds, FileDialog cannot access the host file system. In sandboxed Linux and macOS environments, :ref:`use_native_dialog` is automatically used to allow limited access to host file system. .. rst-class:: classref-item-separator @@ -298,6 +298,8 @@ The file system access scope. See :ref:`Access` constant The current working directory of the file dialog. +\ **Note:** For native file dialogs, this property is only treated as a hint and may not be respected by specific OS implementations. + .. rst-class:: classref-item-separator ---- @@ -419,6 +421,8 @@ The number of additional :ref:`OptionButton`\ s and :ref:`Ch If non-empty, the given sub-folder will be "root" of this **FileDialog**, i.e. user won't be able to go to its parent directory. +\ **Note:** This property is ignored by native file dialogs. + .. rst-class:: classref-item-separator ---- @@ -436,6 +440,8 @@ If non-empty, the given sub-folder will be "root" of this **FileDialog**, i.e. u If ``true``, the dialog will show hidden files. +\ **Note:** This property is ignored by native file dialogs on Linux. + .. rst-class:: classref-item-separator ---- @@ -453,7 +459,11 @@ If ``true``, the dialog will show hidden files. If ``true``, :ref:`access` is set to :ref:`ACCESS_FILESYSTEM`, and it is supported by the current :ref:`DisplayServer`, OS native dialog will be used instead of custom one. -\ **Note:** On macOS, sandboxed apps always use native dialogs to access host filesystem. +\ **Note:** On Linux and macOS, sandboxed apps always use native dialogs to access the host file system. + +\ **Note:** On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use :ref:`OS.get_granted_permissions` to get a list of saved bookmarks. + +\ **Note:** Native dialogs are isolated from the base process, file dialog properties can't be modified once the dialog is shown. .. rst-class:: classref-section-separator @@ -590,6 +600,8 @@ Returns the vertical box container of the dialog, custom controls can be added t \ **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` property. +\ **Note:** Changes to this node are ignored by native file dialogs, use :ref:`add_option` to add custom elements to the dialog instead. + .. rst-class:: classref-item-separator ---- @@ -602,6 +614,8 @@ Returns the vertical box container of the dialog, custom controls can be added t Invalidate and update the current dialog content list. +\ **Note:** This method does nothing on native file dialogs. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_font.rst b/classes/class_font.rst index 542dcb1a58d..0db4a8e1fc2 100644 --- a/classes/class_font.rst +++ b/classes/class_font.rst @@ -501,7 +501,7 @@ To print available variation axes of a variable font: :: var fv = FontVariation.new() - fv.set_base_font = load("res://RobotoFlex.ttf") + fv.base_font = load("res://RobotoFlex.ttf") var variation_list = fv.get_supported_variation_list() for tag in variation_list: var name = TextServerManager.get_primary_interface().tag_to_name(tag) diff --git a/classes/class_fontvariation.rst b/classes/class_fontvariation.rst index ea7a927b185..bedd7004382 100644 --- a/classes/class_fontvariation.rst +++ b/classes/class_fontvariation.rst @@ -29,8 +29,8 @@ To use simulated bold font variant: .. code-tab:: gdscript var fv = FontVariation.new() - fv.set_base_font(load("res://BarlowCondensed-Regular.ttf")) - fv.set_variation_embolden(1.2) + fv.base_font = load("res://BarlowCondensed-Regular.ttf") + fv.variation_embolden = 1.2 $Label.add_theme_font_override("font", fv) $Label.add_theme_font_size_override("font_size", 64) diff --git a/classes/class_gltfaccessor.rst b/classes/class_gltfaccessor.rst index c938fd962ea..d3febd05a38 100644 --- a/classes/class_gltfaccessor.rst +++ b/classes/class_gltfaccessor.rst @@ -40,37 +40,108 @@ Properties .. table:: :widths: auto - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`accessor_type` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`buffer_view` | ``-1`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`byte_offset` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`component_type` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`count` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`PackedFloat64Array` | :ref:`max` | ``PackedFloat64Array()`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`PackedFloat64Array` | :ref:`min` | ``PackedFloat64Array()`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`bool` | :ref:`normalized` | ``false`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`sparse_count` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`sparse_indices_buffer_view` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`sparse_indices_byte_offset` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`sparse_indices_component_type` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`sparse_values_buffer_view` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`sparse_values_byte_offset` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ - | :ref:`int` | :ref:`type` | ``0`` | - +-----------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`GLTFAccessorType` | :ref:`accessor_type` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`buffer_view` | ``-1`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`byte_offset` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`component_type` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`count` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`PackedFloat64Array` | :ref:`max` | ``PackedFloat64Array()`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`PackedFloat64Array` | :ref:`min` | ``PackedFloat64Array()`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`bool` | :ref:`normalized` | ``false`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`sparse_count` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`sparse_indices_buffer_view` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`sparse_indices_byte_offset` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`sparse_indices_component_type` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`sparse_values_buffer_view` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`sparse_values_byte_offset` | ``0`` | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`int` | :ref:`type` | | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------+--------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_GLTFAccessor_GLTFAccessorType: + +.. rst-class:: classref-enumeration + +enum **GLTFAccessorType**: :ref:`🔗` + +.. _class_GLTFAccessor_constant_TYPE_SCALAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`GLTFAccessorType` **TYPE_SCALAR** = ``0`` + +Accessor type "SCALAR". For the glTF object model, this can be used to map to a single float, int, or bool value, or a float array. + +.. _class_GLTFAccessor_constant_TYPE_VEC2: + +.. rst-class:: classref-enumeration-constant + +:ref:`GLTFAccessorType` **TYPE_VEC2** = ``1`` + +Accessor type "VEC2". For the glTF object model, this maps to "float2", represented in the glTF JSON as an array of two floats. + +.. _class_GLTFAccessor_constant_TYPE_VEC3: + +.. rst-class:: classref-enumeration-constant + +:ref:`GLTFAccessorType` **TYPE_VEC3** = ``2`` + +Accessor type "VEC3". For the glTF object model, this maps to "float3", represented in the glTF JSON as an array of three floats. + +.. _class_GLTFAccessor_constant_TYPE_VEC4: + +.. rst-class:: classref-enumeration-constant + +:ref:`GLTFAccessorType` **TYPE_VEC4** = ``3`` + +Accessor type "VEC4". For the glTF object model, this maps to "float4", represented in the glTF JSON as an array of four floats. + +.. _class_GLTFAccessor_constant_TYPE_MAT2: + +.. rst-class:: classref-enumeration-constant + +:ref:`GLTFAccessorType` **TYPE_MAT2** = ``4`` + +Accessor type "MAT2". For the glTF object model, this maps to "float2x2", represented in the glTF JSON as an array of four floats. + +.. _class_GLTFAccessor_constant_TYPE_MAT3: + +.. rst-class:: classref-enumeration-constant + +:ref:`GLTFAccessorType` **TYPE_MAT3** = ``5`` + +Accessor type "MAT3". For the glTF object model, this maps to "float3x3", represented in the glTF JSON as an array of nine floats. + +.. _class_GLTFAccessor_constant_TYPE_MAT4: + +.. rst-class:: classref-enumeration-constant + +:ref:`GLTFAccessorType` **TYPE_MAT4** = ``6`` + +Accessor type "MAT4". For the glTF object model, this maps to "float4x4", represented in the glTF JSON as an array of sixteen floats. .. rst-class:: classref-section-separator @@ -85,12 +156,12 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **accessor_type** = ``0`` :ref:`🔗` +:ref:`GLTFAccessorType` **accessor_type** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget -- |void| **set_accessor_type**\ (\ value\: :ref:`int`\ ) -- :ref:`int` **get_accessor_type**\ (\ ) +- |void| **set_accessor_type**\ (\ value\: :ref:`GLTFAccessorType`\ ) +- :ref:`GLTFAccessorType` **get_accessor_type**\ (\ ) The GLTF accessor type as an enum. Possible values are 0 for "SCALAR", 1 for "VEC2", 2 for "VEC3", 3 for "VEC4", 4 for "MAT2", 5 for "MAT3", and 6 for "MAT4". @@ -323,7 +394,7 @@ The offset relative to the start of the bufferView in bytes. .. rst-class:: classref-property -:ref:`int` **type** = ``0`` :ref:`🔗` +:ref:`int` **type** :ref:`🔗` .. rst-class:: classref-property-setget diff --git a/classes/class_graphedit.rst b/classes/class_graphedit.rst index 21dbf9a8fc1..9baee6bee1c 100644 --- a/classes/class_graphedit.rst +++ b/classes/class_graphedit.rst @@ -27,6 +27,8 @@ Description \ **Performance:** It is greatly advised to enable low-processor usage mode (see :ref:`OS.low_processor_usage_mode`) when using GraphEdits. +\ **Note:** Keep in mind that :ref:`Node.get_children` will also return the connection layer node named ``_connection_layer`` due to technical limitations. This behavior may change in future releases. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_hashingcontext.rst b/classes/class_hashingcontext.rst index bf5d5b98ac5..40232dc8460 100644 --- a/classes/class_hashingcontext.rst +++ b/classes/class_hashingcontext.rst @@ -40,8 +40,9 @@ The :ref:`HashType` enum shows the supported hashi # Open the file to hash. var file = FileAccess.open(path, FileAccess.READ) # Update the context after reading each chunk. - while not file.eof_reached(): - ctx.update(file.get_buffer(CHUNK_SIZE)) + while file.get_position() < file.get_length(): + var remaining = file.get_length() - file.get_position() + ctx.update(file.get_buffer(min(remaining, CHUNK_SIZE))) # Get the computed hash. var res = ctx.finish() # Print the result as hex string and array. @@ -64,9 +65,10 @@ The :ref:`HashType` enum shows the supported hashi // Open the file to hash. using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read); // Update the context after reading each chunk. - while (!file.EofReached()) + while (file.GetPosition() < file.GetLength()) { - ctx.Update(file.GetBuffer(ChunkSize)); + int remaining = (int)(file.GetLength() - file.GetPosition()); + ctx.Update(file.GetBuffer(Mathf.Min(remaining, ChunkSize))); } // Get the computed hash. byte[] res = ctx.Finish(); diff --git a/classes/class_inputevent.rst b/classes/class_inputevent.rst index 9084aecf512..a10d7c967d5 100644 --- a/classes/class_inputevent.rst +++ b/classes/class_inputevent.rst @@ -248,7 +248,9 @@ Returns ``true`` if this input event has been canceled. :ref:`bool` **is_echo**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if this input event is an echo event (only for events of type :ref:`InputEventKey`). Any other event type returns ``false``. +Returns ``true`` if this input event is an echo event (only for events of type :ref:`InputEventKey`). An echo event is a repeated key event sent when the user is holding down the key. Any other event type returns ``false``. + +\ **Note:** The rate at which echo events are sent is typically around 20 events per second (after holding down the key for roughly half a second). However, the key repeat delay/speed can be changed by the user or disabled entirely in the operating system settings. To ensure your project works correctly on all configurations, do not assume the user has a specific key repeat configuration in your project's behavior. .. rst-class:: classref-item-separator diff --git a/classes/class_inputeventkey.rst b/classes/class_inputeventkey.rst index b889662fb89..78f83f59bb4 100644 --- a/classes/class_inputeventkey.rst +++ b/classes/class_inputeventkey.rst @@ -100,7 +100,9 @@ Property Descriptions - |void| **set_echo**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_echo**\ (\ ) -If ``true``, the key was already pressed before this event. It means the user is holding the key down. +If ``true``, the key was already pressed before this event. An echo event is a repeated key event sent when the user is holding down the key. + +\ **Note:** The rate at which echo events are sent is typically around 20 events per second (after holding down the key for roughly half a second). However, the key repeat delay/speed can be changed by the user or disabled entirely in the operating system settings. To ensure your project works correctly on all configurations, do not assume the user has a specific key repeat configuration in your project's behavior. .. rst-class:: classref-item-separator diff --git a/classes/class_inputeventshortcut.rst b/classes/class_inputeventshortcut.rst index 8a1170f1f5d..bdebcaf978a 100644 --- a/classes/class_inputeventshortcut.rst +++ b/classes/class_inputeventshortcut.rst @@ -19,7 +19,7 @@ Represents a triggered keyboard :ref:`Shortcut`. Description ----------- -InputEventShortcut is a special event that can be received in :ref:`Node._unhandled_key_input`. It is typically sent by the editor's Command Palette to trigger actions, but can also be sent manually using :ref:`Viewport.push_input`. +InputEventShortcut is a special event that can be received in :ref:`Node._input`, :ref:`Node._shortcut_input`, and :ref:`Node._unhandled_input`. It is typically sent by the editor's Command Palette to trigger actions, but can also be sent manually using :ref:`Viewport.push_input`. .. rst-class:: classref-reftable-group diff --git a/classes/class_json.rst b/classes/class_json.rst index 8276d936dcf..40b167e48e6 100644 --- a/classes/class_json.rst +++ b/classes/class_json.rst @@ -19,7 +19,7 @@ Helper class for creating and parsing JSON data. Description ----------- -The **JSON** enables all data types to be converted to and from a JSON string. This useful for serializing data to save to a file or send over the network. +The **JSON** class enables all data types to be converted to and from a JSON string. This is useful for serializing data, e.g. to save to a file or send over the network. \ :ref:`stringify` is used to convert any data type into a JSON string. @@ -45,7 +45,7 @@ The **JSON** enables all data types to be converted to and from a JSON string. T else: print("JSON Parse Error: ", json.get_error_message(), " in ", json_string, " at line ", json.get_error_line()) -Alternatively, you can parse string using the static :ref:`parse_string` method, but it doesn't allow to handle errors. +Alternatively, you can parse strings using the static :ref:`parse_string` method, but it doesn't handle errors. :: @@ -156,7 +156,7 @@ Returns an empty string if the last call to :ref:`parse :ref:`String` **get_parsed_text**\ (\ ) |const| :ref:`🔗` -Return the text parsed by :ref:`parse` as long as the function is instructed to keep it. +Return the text parsed by :ref:`parse` (requires passing ``keep_text`` to :ref:`parse`). .. rst-class:: classref-item-separator @@ -170,7 +170,7 @@ Return the text parsed by :ref:`parse` as long as the f Attempts to parse the ``json_text`` provided. -Returns an :ref:`Error`. If the parse was successful, it returns :ref:`@GlobalScope.OK` and the result can be retrieved using :ref:`data`. If unsuccessful, use :ref:`get_error_line` and :ref:`get_error_message` for identifying the source of the failure. +Returns an :ref:`Error`. If the parse was successful, it returns :ref:`@GlobalScope.OK` and the result can be retrieved using :ref:`data`. If unsuccessful, use :ref:`get_error_line` and :ref:`get_error_message` to identify the source of the failure. Non-static variant of :ref:`parse_string`, if you want custom error handling. @@ -204,7 +204,7 @@ Converts a :ref:`Variant` var to JSON text and returns the result \ **Note:** If ``full_precision`` is ``true``, when stringifying floats, the unreliable digits are stringified in addition to the reliable digits to guarantee exact decoding. -The ``indent`` parameter controls if and how something is indented, the string used for this parameter will be used where there should be an indent in the output, even spaces like ``" "`` will work. ``\t`` and ``\n`` can also be used for a tab indent, or to make a newline for each indent respectively. +The ``indent`` parameter controls if and how something is indented; its contents will be used where there should be an indent in the output. Even spaces like ``" "`` will work. ``\t`` and ``\n`` can also be used for a tab indent, or to make a newline for each indent respectively. \ **Example output:**\ diff --git a/classes/class_lightmapgi.rst b/classes/class_lightmapgi.rst index 94ffc9b8123..aa78fa38d16 100644 --- a/classes/class_lightmapgi.rst +++ b/classes/class_lightmapgi.rst @@ -273,6 +273,22 @@ The user aborted the lightmap baking operation (typically by clicking the **Canc Lightmap baking failed as the maximum texture size is too small to fit some of the meshes marked for baking. +.. _class_LightmapGI_constant_BAKE_ERROR_LIGHTMAP_TOO_SMALL: + +.. rst-class:: classref-enumeration-constant + +:ref:`BakeError` **BAKE_ERROR_LIGHTMAP_TOO_SMALL** = ``10`` + +Lightmap baking failed as the lightmap is too small. + +.. _class_LightmapGI_constant_BAKE_ERROR_ATLAS_TOO_SMALL: + +.. rst-class:: classref-enumeration-constant + +:ref:`BakeError` **BAKE_ERROR_ATLAS_TOO_SMALL** = ``11`` + +Lightmap baking failed as the lightmap was unable to fit into an atlas. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_mesh.rst b/classes/class_mesh.rst index ced3064f9a2..c75c8c8ab52 100644 --- a/classes/class_mesh.rst +++ b/classes/class_mesh.rst @@ -191,6 +191,8 @@ enum **ArrayType**: :ref:`🔗` :ref:`PackedVector3Array` of vertex normals. +\ **Note:** The array has to consist of normal vectors, otherwise they will be normalized by the engine, potentially causing visual discrepancies. + .. _class_Mesh_constant_ARRAY_TANGENT: .. rst-class:: classref-enumeration-constant diff --git a/classes/class_mobilevrinterface.rst b/classes/class_mobilevrinterface.rst index 14b69591f74..b5bcd4ce413 100644 --- a/classes/class_mobilevrinterface.rst +++ b/classes/class_mobilevrinterface.rst @@ -29,7 +29,7 @@ You can initialize this interface as follows: var interface = XRServer.find_interface("Native mobile") if interface and interface.initialize(): - get_viewport().xr = true + get_viewport().use_xr = true .. rst-class:: classref-reftable-group diff --git a/classes/class_multimesh.rst b/classes/class_multimesh.rst index e212c9e387b..bfef9e8093f 100644 --- a/classes/class_multimesh.rst +++ b/classes/class_multimesh.rst @@ -426,6 +426,8 @@ Returns the :ref:`Transform2D` of a specific instance. Sets the color of a specific instance by *multiplying* the mesh's existing vertex colors. This allows for different color tinting per instance. +\ **Note:** Each component is stored in 32 bits in the Forward+ and Mobile rendering methods, but is packed into 16 bits in the Compatibility rendering method. + For the color to take effect, ensure that :ref:`use_colors` is ``true`` on the **MultiMesh** and :ref:`BaseMaterial3D.vertex_color_use_as_albedo` is ``true`` on the material. If you intend to set an absolute color instead of tinting, make sure the material's albedo color is set to pure white (``Color(1, 1, 1)``). .. rst-class:: classref-item-separator @@ -440,6 +442,8 @@ For the color to take effect, ensure that :ref:`use_colors` type only to contain 4 floating-point numbers. +\ **Note:** Each number is stored in 32 bits in the Forward+ and Mobile rendering methods, but is packed into 16 bits in the Compatibility rendering method. + For the custom data to be used, ensure that :ref:`use_custom_data` is ``true``. This custom instance data has to be manually accessed in your custom shader using ``INSTANCE_CUSTOM``. diff --git a/classes/class_node.rst b/classes/class_node.rst index e6c2af5e0eb..318db3705a8 100644 --- a/classes/class_node.rst +++ b/classes/class_node.rst @@ -971,7 +971,7 @@ Implemented on desktop platforms. Notification received from the OS when a go back request is sent (e.g. pressing the "Back" button on Android). -Implemented only on iOS. +Implemented only on Android. .. _class_Node_constant_NOTIFICATION_WM_SIZE_CHANGED: diff --git a/classes/class_nodepath.rst b/classes/class_nodepath.rst index 842dd3e8a9c..8d2fd23fe07 100644 --- a/classes/class_nodepath.rst +++ b/classes/class_nodepath.rst @@ -44,11 +44,13 @@ Despite their name, node paths may also point to a property: :: - ^"position" # Points to this object's position. - ^"position:x" # Points to this object's position in the x axis. + ^":position" # Points to this object's position. + ^":position:x" # Points to this object's position in the x axis. ^"Camera3D:rotation:y" # Points to the child Camera3D and its y rotation. ^"/root:size:x" # Points to the root Window and its width. +In some situations, it's possible to omit the leading ``:`` when pointing to an object's property. As an example, this is the case with :ref:`Object.set_indexed` and :ref:`Tween.tween_property`, as those methods call :ref:`get_as_property_path` under the hood. However, it's generally recommended to keep the ``:`` prefix. + Node paths cannot check whether they are valid and may point to nodes or properties that do not exist. Their meaning depends entirely on the context in which they're used. You usually do not have to worry about the **NodePath** type, as strings are automatically converted to the type when necessary. There are still times when defining node paths is useful. For example, exported **NodePath** properties allow you to easily select any node within the currently edited scene. They are also automatically updated when moving, renaming or deleting nodes in the scene tree editor. See also :ref:`@GDScript.@export_node_path`. diff --git a/classes/class_object.rst b/classes/class_object.rst index 4910f84f598..9916ba56184 100644 --- a/classes/class_object.rst +++ b/classes/class_object.rst @@ -695,7 +695,7 @@ Override this method to customize existing properties. Every property info goes public override void _ValidateProperty(Godot.Collections.Dictionary property) { - if (property["name"].AsStringName() == PropertyName.Number && IsNumberEditable) + if (property["name"].AsStringName() == PropertyName.Number && !IsNumberEditable) { var usage = property["usage"].As() | PropertyUsageFlags.ReadOnly; property["usage"] = (int)usage; diff --git a/classes/class_openxrinterface.rst b/classes/class_openxrinterface.rst index 56f5cb446cd..66479ab7a6a 100644 --- a/classes/class_openxrinterface.rst +++ b/classes/class_openxrinterface.rst @@ -137,7 +137,7 @@ Informs the user queued a recenter of the player position. Informs the user the HMD refresh rate has changed. -\ **Node:** Only emitted if XR runtime supports the refresh rate extension. +\ **Note:** Only emitted if XR runtime supports the refresh rate extension. .. rst-class:: classref-item-separator diff --git a/classes/class_os.rst b/classes/class_os.rst index 1eca41e0573..b26590dfea6 100644 --- a/classes/class_os.rst +++ b/classes/class_os.rst @@ -829,7 +829,7 @@ Returns the value of the given environment variable, or an empty string if ``var Returns the file path to the current engine executable. -\ **Note:** On macOS, always use :ref:`create_instance` instead of relying on executable path. +\ **Note:** On macOS, if you want to launch another instance of Godot, always use :ref:`create_instance` instead of relying on the executable path. .. rst-class:: classref-item-separator @@ -1057,6 +1057,8 @@ Returns the exit code of a spawned process once it has finished running (see :re Returns ``-1`` if the ``pid`` is not a PID of a spawned child process, the process is still running, or the method is not implemented for the current platform. +\ **Note:** Returns ``-1`` if the ``pid`` is a macOS bundled app process. + \ **Note:** This method is implemented on Android, Linux, macOS and Windows. .. rst-class:: classref-item-separator diff --git a/classes/class_parallax2d.rst b/classes/class_parallax2d.rst index a8d7337406c..98bf826682d 100644 --- a/classes/class_parallax2d.rst +++ b/classes/class_parallax2d.rst @@ -25,6 +25,13 @@ A **Parallax2D** is used to create a parallax effect. It can move at a different \ **Note:** Any changes to this node's position made after it enters the scene tree will be overridden if :ref:`ignore_camera_scroll` is ``false`` or :ref:`screen_offset` is modified. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`2D Parallax <../tutorials/2d/2d_parallax>` + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_physicalbone3d.rst b/classes/class_physicalbone3d.rst index c830b8a7952..2325c9a540b 100644 --- a/classes/class_physicalbone3d.rst +++ b/classes/class_physicalbone3d.rst @@ -24,6 +24,8 @@ Description The **PhysicalBone3D** node is a physics body that can be used to make bones in a :ref:`Skeleton3D` react to physics. +\ **Note:** In order to detect physical bones with raycasts, the :ref:`SkeletonModifier3D.active` property of the parent :ref:`PhysicalBoneSimulator3D` must be ``true`` and the :ref:`Skeleton3D`'s bone must be assigned to **PhysicalBone3D** correctly; it means that :ref:`get_bone_id` should return a valid id (``>= 0``). + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_physicspointqueryparameters2d.rst b/classes/class_physicspointqueryparameters2d.rst index 0127643629b..6544baca2c6 100644 --- a/classes/class_physicspointqueryparameters2d.rst +++ b/classes/class_physicspointqueryparameters2d.rst @@ -135,6 +135,8 @@ The physics layers the query will detect (as a bitmask). By default, all collisi The list of object :ref:`RID`\ s that will be excluded from collisions. Use :ref:`CollisionObject2D.get_rid` to get the :ref:`RID` associated with a :ref:`CollisionObject2D`-derived node. +\ **Note:** The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_physicspointqueryparameters3d.rst b/classes/class_physicspointqueryparameters3d.rst index 2f2765e9c99..321305afa3a 100644 --- a/classes/class_physicspointqueryparameters3d.rst +++ b/classes/class_physicspointqueryparameters3d.rst @@ -114,6 +114,8 @@ The physics layers the query will detect (as a bitmask). By default, all collisi The list of object :ref:`RID`\ s that will be excluded from collisions. Use :ref:`CollisionObject3D.get_rid` to get the :ref:`RID` associated with a :ref:`CollisionObject3D`-derived node. +\ **Note:** The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_physicsrayqueryparameters2d.rst b/classes/class_physicsrayqueryparameters2d.rst index 4daa99ecba0..1a8593ffa2f 100644 --- a/classes/class_physicsrayqueryparameters2d.rst +++ b/classes/class_physicsrayqueryparameters2d.rst @@ -130,6 +130,8 @@ The physics layers the query will detect (as a bitmask). By default, all collisi The list of object :ref:`RID`\ s that will be excluded from collisions. Use :ref:`CollisionObject2D.get_rid` to get the :ref:`RID` associated with a :ref:`CollisionObject2D`-derived node. +\ **Note:** The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_physicsrayqueryparameters3d.rst b/classes/class_physicsrayqueryparameters3d.rst index e53ca2eb15e..990417768e8 100644 --- a/classes/class_physicsrayqueryparameters3d.rst +++ b/classes/class_physicsrayqueryparameters3d.rst @@ -132,6 +132,8 @@ The physics layers the query will detect (as a bitmask). By default, all collisi The list of object :ref:`RID`\ s that will be excluded from collisions. Use :ref:`CollisionObject3D.get_rid` to get the :ref:`RID` associated with a :ref:`CollisionObject3D`-derived node. +\ **Note:** The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_physicsserver2d.rst b/classes/class_physicsserver2d.rst index 8a58d30b956..500395ab270 100644 --- a/classes/class_physicsserver2d.rst +++ b/classes/class_physicsserver2d.rst @@ -208,6 +208,8 @@ Methods +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`body_set_state`\ (\ body\: :ref:`RID`, state\: :ref:`BodyState`, value\: :ref:`Variant`\ ) | +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`body_set_state_sync_callback`\ (\ body\: :ref:`RID`, callable\: :ref:`Callable`\ ) | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`body_test_motion`\ (\ body\: :ref:`RID`, parameters\: :ref:`PhysicsTestMotionParameters2D`, result\: :ref:`PhysicsTestMotionResult2D` = null\ ) | +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`capsule_shape_create`\ (\ ) | @@ -2151,6 +2153,24 @@ Sets the value of a body's state. See :ref:`BodyState`, callable\: :ref:`Callable`\ ) :ref:`🔗` + +Sets the body's state synchronization callback function to ``callable``. Use an empty :ref:`Callable` (``Callable()``) to clear the callback. + +The function ``callable`` will be called every physics frame, assuming that the body was active during the previous physics tick, and can be used to fetch the latest state from the physics server. + +The function ``callable`` must take the following parameters: + +1. ``state``: a :ref:`PhysicsDirectBodyState2D`, used to retrieve the body's state. + +.. rst-class:: classref-item-separator + +---- + .. _class_PhysicsServer2D_method_body_test_motion: .. rst-class:: classref-method diff --git a/classes/class_physicsserver2dextension.rst b/classes/class_physicsserver2dextension.rst index c93a466d3c2..c0bb62666d8 100644 --- a/classes/class_physicsserver2dextension.rst +++ b/classes/class_physicsserver2dextension.rst @@ -1386,7 +1386,7 @@ Overridable version of :ref:`PhysicsServer2D.body_set_state` is called. See also :ref:`_sync`. -Overridable version of :ref:`PhysicsServer2D`'s internal ``body_set_state_sync_callback`` method. +Overridable version of :ref:`PhysicsServer2D.body_set_state_sync_callback`. .. rst-class:: classref-item-separator diff --git a/classes/class_physicsserver3d.rst b/classes/class_physicsserver3d.rst index bb6015042b8..cd8e76c55ed 100644 --- a/classes/class_physicsserver3d.rst +++ b/classes/class_physicsserver3d.rst @@ -206,6 +206,8 @@ Methods +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`body_set_state`\ (\ body\: :ref:`RID`, state\: :ref:`BodyState`, value\: :ref:`Variant`\ ) | +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`body_set_state_sync_callback`\ (\ body\: :ref:`RID`, callable\: :ref:`Callable`\ ) | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`body_test_motion`\ (\ body\: :ref:`RID`, parameters\: :ref:`PhysicsTestMotionParameters3D`, result\: :ref:`PhysicsTestMotionResult3D` = null\ ) | +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`box_shape_create`\ (\ ) | @@ -2887,6 +2889,24 @@ Sets a body state (see :ref:`BodyState` constant ---- +.. _class_PhysicsServer3D_method_body_set_state_sync_callback: + +.. rst-class:: classref-method + +|void| **body_set_state_sync_callback**\ (\ body\: :ref:`RID`, callable\: :ref:`Callable`\ ) :ref:`🔗` + +Sets the body's state synchronization callback function to ``callable``. Use an empty :ref:`Callable` (``Callable()``) to clear the callback. + +The function ``callable`` will be called every physics frame, assuming that the body was active during the previous physics tick, and can be used to fetch the latest state from the physics server. + +The function ``callable`` must take the following parameters: + +1. ``state``: a :ref:`PhysicsDirectBodyState3D`, used to retrieve the body's state. + +.. rst-class:: classref-item-separator + +---- + .. _class_PhysicsServer3D_method_body_test_motion: .. rst-class:: classref-method diff --git a/classes/class_physicsshapequeryparameters2d.rst b/classes/class_physicsshapequeryparameters2d.rst index d374905b937..793282d9723 100644 --- a/classes/class_physicsshapequeryparameters2d.rst +++ b/classes/class_physicsshapequeryparameters2d.rst @@ -122,6 +122,8 @@ The physics layers the query will detect (as a bitmask). By default, all collisi The list of object :ref:`RID`\ s that will be excluded from collisions. Use :ref:`CollisionObject2D.get_rid` to get the :ref:`RID` associated with a :ref:`CollisionObject2D`-derived node. +\ **Note:** The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_physicsshapequeryparameters3d.rst b/classes/class_physicsshapequeryparameters3d.rst index 67ae0a513c6..bc2b871df55 100644 --- a/classes/class_physicsshapequeryparameters3d.rst +++ b/classes/class_physicsshapequeryparameters3d.rst @@ -122,6 +122,8 @@ The physics layers the query will detect (as a bitmask). By default, all collisi The list of object :ref:`RID`\ s that will be excluded from collisions. Use :ref:`CollisionObject3D.get_rid` to get the :ref:`RID` associated with a :ref:`CollisionObject3D`-derived node. +\ **Note:** The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_popupmenu.rst b/classes/class_popupmenu.rst index 07e5d0822ef..d58bc3a5406 100644 --- a/classes/class_popupmenu.rst +++ b/classes/class_popupmenu.rst @@ -148,6 +148,8 @@ Methods +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_item_shortcut_disabled`\ (\ index\: :ref:`int`\ ) |const| | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_native_menu`\ (\ ) |const| | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_system_menu`\ (\ ) |const| | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_item`\ (\ index\: :ref:`int`\ ) | @@ -445,6 +447,8 @@ The number of items currently in the list. If ``true``, :ref:`MenuBar` will use native menu when supported. +\ **Note:** If **PopupMenu** is linked to :ref:`StatusIndicator`, :ref:`MenuBar`, or another **PopupMenu** item it can use native menu regardless of this property, use :ref:`is_native_menu` to check it. + .. rst-class:: classref-item-separator ---- @@ -1076,6 +1080,18 @@ Returns ``true`` if the specified item's shortcut is disabled. ---- +.. _class_PopupMenu_method_is_native_menu: + +.. rst-class:: classref-method + +:ref:`bool` **is_native_menu**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the system native menu is supported and currently used by this **PopupMenu**. + +.. rst-class:: classref-item-separator + +---- + .. _class_PopupMenu_method_is_system_menu: .. rst-class:: classref-method diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index 2c171e352b7..0ff76597b42 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -177,6 +177,8 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debug/gdscript/warnings/assert_always_true` | ``1`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`debug/gdscript/warnings/confusable_capture_reassignment` | ``1`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debug/gdscript/warnings/confusable_identifier` | ``1`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debug/gdscript/warnings/confusable_local_declaration` | ``1`` | @@ -277,6 +279,8 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debug/settings/profiler/max_functions` | ``16384`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`debug/settings/profiler/max_timestamp_query_elements` | ``256`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`debug/settings/stdout/print_fps` | ``false`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`debug/settings/stdout/print_gpu_profile` | ``false`` | @@ -1519,6 +1523,10 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`rendering/rendering_device/driver.windows` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`rendering/rendering_device/fallback_to_d3d12` | ``true`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`rendering/rendering_device/fallback_to_vulkan` | ``true`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`rendering/rendering_device/pipeline_cache/enable` | ``true`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`rendering/rendering_device/pipeline_cache/save_chunk_size_mb` | ``3.0`` | @@ -1820,6 +1828,8 @@ This user directory is used for storing persistent data (``user://`` filesystem) The :ref:`application/config/use_custom_user_dir` setting must be enabled for this to take effect. +\ **Note:** If :ref:`application/config/custom_user_dir_name` contains trailing periods, they will be stripped as folder names ending with a period are not allowed on Windows. + .. rst-class:: classref-item-separator ---- @@ -2080,7 +2090,7 @@ This setting can be overridden using the ``--frame-delay `` command line ar :ref:`bool` **application/run/low_processor_mode** = ``false`` :ref:`🔗` -If ``true``, enables low-processor usage mode. The screen is not redrawn if nothing changes visually. This is meant for writing applications and editors, but is pretty useless (and can hurt performance) in most games. +If ``true``, enables low-processor usage mode. When enabled, the engine takes longer to redraw, but only redraws the screen if necessary. This may lower power consumption, and is intended for editors or mobile applications. For most games, because the screen needs to be redrawn every frame, it is recommended to keep this setting disabled. .. rst-class:: classref-item-separator @@ -2566,6 +2576,18 @@ When set to ``warn`` or ``error``, produces a warning or an error respectively w ---- +.. _class_ProjectSettings_property_debug/gdscript/warnings/confusable_capture_reassignment: + +.. rst-class:: classref-property + +:ref:`int` **debug/gdscript/warnings/confusable_capture_reassignment** = ``1`` :ref:`🔗` + +When set to ``warn`` or ``error``, produces a warning or an error respectively when a local variable captured by a lambda is reassigned, since this does not modify the outer local variable. + +.. rst-class:: classref-item-separator + +---- + .. _class_ProjectSettings_property_debug/gdscript/warnings/confusable_identifier: .. rst-class:: classref-property @@ -3178,6 +3200,18 @@ Maximum number of functions per frame allowed when profiling. ---- +.. _class_ProjectSettings_property_debug/settings/profiler/max_timestamp_query_elements: + +.. rst-class:: classref-property + +:ref:`int` **debug/settings/profiler/max_timestamp_query_elements** = ``256`` :ref:`🔗` + +Maximum number of timestamp query elements allowed per frame for visual profiling. + +.. rst-class:: classref-item-separator + +---- + .. _class_ProjectSettings_property_debug/settings/stdout/print_fps: .. rst-class:: classref-property @@ -4200,9 +4234,9 @@ Defines how the base size is stretched to fit the resolution of the window or sc \ **"disabled"**: No stretching happens. One unit in the scene corresponds to one pixel on the screen. In this mode, :ref:`display/window/stretch/aspect` has no effect. Recommended for non-game applications. -\ **"canvas_items"**: The base size specified in width and height in the project settings is stretched to cover the whole screen (taking :ref:`display/window/stretch/aspect` into account). This means that everything is rendered directly at the target resolution. 3D is unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts. Recommended for most games that don't use a pixel art esthetic, although it is possible to use this stretch mode for pixel art games too (especially in 3D). +\ **"canvas_items"**: The base size specified in width and height in the project settings is stretched to cover the whole screen (taking :ref:`display/window/stretch/aspect` into account). This means that everything is rendered directly at the target resolution. 3D is unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts. Recommended for most games that don't use a pixel art aesthetic, although it is possible to use this stretch mode for pixel art games too (especially in 3D). -\ **"viewport"**: The size of the root :ref:`Viewport` is set precisely to the base size specified in the Project Settings' Display section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking :ref:`display/window/stretch/aspect` into account). Recommended for games that use a pixel art esthetic. +\ **"viewport"**: The size of the root :ref:`Viewport` is set precisely to the base size specified in the Project Settings' Display section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking :ref:`display/window/stretch/aspect` into account). Recommended for games that use a pixel art aesthetic. .. rst-class:: classref-item-separator @@ -4244,7 +4278,11 @@ The policy to use to determine the final scale factor for 2D elements. This affe :ref:`bool` **display/window/subwindows/embed_subwindows** = ``true`` :ref:`🔗` -If ``true`` subwindows are embedded in the main window. +If ``true``, subwindows are embedded in the main window (this is also called single-window mode). Single-window mode can be faster as it does not need to create a separate window for every popup and tooltip, which can be a slow operation depending on the operating system and rendering method in use. + +If ``false``, subwindows are created as separate windows (this is also called multi-window mode). This allows them to be moved outside the main window and use native operating system window decorations. + +This is equivalent to :ref:`EditorSettings.interface/editor/single_window_mode` in the editor, except the setting's value is inverted. .. rst-class:: classref-item-separator @@ -4316,9 +4354,11 @@ Changing this value allows setting up a multi-project scenario where there are m :ref:`bool` **editor/export/convert_text_resources_to_binary** = ``true`` :ref:`🔗` -If ``true``, text resources are converted to a binary format on export. This decreases file sizes and speeds up loading slightly. +If ``true``, text resource (``tres``) and text scene (``tscn``) files are converted to their corresponding binary format on export. This decreases file sizes and speeds up loading slightly. -\ **Note:** If :ref:`editor/export/convert_text_resources_to_binary` is ``true``, :ref:`@GDScript.load` will not be able to return the converted files in an exported project. Some file paths within the exported PCK will also change, such as ``project.godot`` becoming ``project.binary``. If you rely on run-time loading of files present within the PCK, set :ref:`editor/export/convert_text_resources_to_binary` to ``false``. +\ **Note:** Because a resource's file extension may change in an exported project, it is heavily recommended to use :ref:`@GDScript.load` or :ref:`ResourceLoader` instead of :ref:`FileAccess` to load resources dynamically. + +\ **Note:** The project settings file (``project.godot``) will always be converted to binary on export, regardless of this setting. .. rst-class:: classref-item-separator @@ -9638,8 +9678,6 @@ Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of tw Sets the number of MSAA samples to use for 3D rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware, especially integrated graphics due to their limited memory bandwidth. See also :ref:`rendering/scaling_3d/mode` for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. -\ **Note:** MSAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. - .. rst-class:: classref-item-separator ---- @@ -11172,6 +11210,34 @@ Windows override for :ref:`rendering/rendering_device/driver` **rendering/rendering_device/fallback_to_d3d12** = ``true`` :ref:`🔗` + +If ``true``, the forward renderer will fall back to Direct3D 12 if Vulkan is not supported. + +\ **Note:** This setting is implemented only on Windows. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ProjectSettings_property_rendering/rendering_device/fallback_to_vulkan: + +.. rst-class:: classref-property + +:ref:`bool` **rendering/rendering_device/fallback_to_vulkan** = ``true`` :ref:`🔗` + +If ``true``, the forward renderer will fall back to Vulkan if Direct3D 12 is not supported. + +\ **Note:** This setting is implemented only on Windows. + +.. rst-class:: classref-item-separator + +---- + .. _class_ProjectSettings_property_rendering/rendering_device/pipeline_cache/enable: .. rst-class:: classref-property @@ -11797,7 +11863,7 @@ Specify whether OpenXR should be configured for an HMD or a hand held device. If true and foveation is supported, will automatically adjust foveation level based on framerate up to the level set on :ref:`xr/openxr/foveation_level`. -\ **Note:** Only works on compatibility renderer. +\ **Note:** Only works on the Compatibility rendering method. .. rst-class:: classref-item-separator @@ -11811,7 +11877,7 @@ If true and foveation is supported, will automatically adjust foveation level ba Applied foveation level if supported: 0 = off, 1 = low, 2 = medium, 3 = high. -\ **Note:** Only works on compatibility renderer. +\ **Note:** Only works on the Compatibility rendering method. On platforms other than Android, if :ref:`rendering/anti_aliasing/quality/msaa_3d` is enabled, this feature will be disabled. .. rst-class:: classref-item-separator diff --git a/classes/class_renderdataextension.rst b/classes/class_renderdataextension.rst index c90e048a60a..b6981ea11f0 100644 --- a/classes/class_renderdataextension.rst +++ b/classes/class_renderdataextension.rst @@ -54,7 +54,7 @@ Method Descriptions :ref:`RID` **_get_camera_attributes**\ (\ ) |virtual| |const| :ref:`🔗` -Implement this in GDExtension to return the :ref:`RID` for the implementations camera attributes object. +Implement this in GDExtension to return the :ref:`RID` for the implementation's camera attributes object. .. rst-class:: classref-item-separator @@ -66,9 +66,7 @@ Implement this in GDExtension to return the :ref:`RID` for the implem :ref:`RID` **_get_environment**\ (\ ) |virtual| |const| :ref:`🔗` -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Implement this in GDExtension to return the :ref:`RID` of the implementation's environment object. .. rst-class:: classref-item-separator @@ -80,7 +78,7 @@ Implement this in GDExtension to return the :ref:`RID` for the implem :ref:`RenderSceneBuffers` **_get_render_scene_buffers**\ (\ ) |virtual| |const| :ref:`🔗` -Implement this in GDExtension to return the :ref:`RID` of the implementations environment object. +Implement this in GDExtension to return the implementation's :ref:`RenderSceneBuffers` object. .. rst-class:: classref-item-separator @@ -92,7 +90,7 @@ Implement this in GDExtension to return the :ref:`RID` of the impleme :ref:`RenderSceneData` **_get_render_scene_data**\ (\ ) |virtual| |const| :ref:`🔗` -Implement this in GDExtension to return the implementations :ref:`RenderSceneDataExtension` object. +Implement this in GDExtension to return the implementation's :ref:`RenderSceneDataExtension` object. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_renderingdevice.rst b/classes/class_renderingdevice.rst index bb7434a72d5..d7e988760f8 100644 --- a/classes/class_renderingdevice.rst +++ b/classes/class_renderingdevice.rst @@ -1719,7 +1719,7 @@ VRAM-compressed signed red/green channel data format with normalized value. Valu :ref:`DataFormat` **DATA_FORMAT_BC6H_UFLOAT_BLOCK** = ``142`` -VRAM-compressed unsigned red/green/blue channel data format with the floating-point value stored as-is. The format's precision is 8 bits of red channel and 8 bits of green channel. Using BC6H texture compression (also known as BPTC HDR). +VRAM-compressed unsigned red/green/blue channel data format with the floating-point value stored as-is. The format's precision is between 10 and 13 bits for the red/green/blue channels. Using BC6H texture compression (also known as BPTC HDR). .. _class_RenderingDevice_constant_DATA_FORMAT_BC6H_SFLOAT_BLOCK: @@ -1727,7 +1727,7 @@ VRAM-compressed unsigned red/green/blue channel data format with the floating-po :ref:`DataFormat` **DATA_FORMAT_BC6H_SFLOAT_BLOCK** = ``143`` -VRAM-compressed signed red/green/blue channel data format with the floating-point value stored as-is. The format's precision is between 4 and 7 bits for the red/green/blue channels and between 0 and 8 bits for the alpha channel. Using BC7 texture compression (also known as BPTC HDR). +VRAM-compressed signed red/green/blue channel data format with the floating-point value stored as-is. The format's precision is between 10 and 13 bits for the red/green/blue channels. Using BC6H texture compression (also known as BPTC HDR). .. _class_RenderingDevice_constant_DATA_FORMAT_BC7_UNORM_BLOCK: @@ -1807,7 +1807,7 @@ VRAM-compressed unsigned red/green/blue/alpha channel data format with normalize :ref:`DataFormat` **DATA_FORMAT_EAC_R11_SNORM_BLOCK** = ``153`` -11-bit VRAM-compressed signed red channel data format with normalized value. Values are in the ``[0.0, 1.0]`` range. Using ETC2 texture compression. +11-bit VRAM-compressed signed red channel data format with normalized value. Values are in the ``[-1.0, 1.0]`` range. Using ETC2 texture compression. .. _class_RenderingDevice_constant_DATA_FORMAT_EAC_R11G11_UNORM_BLOCK: @@ -1823,7 +1823,7 @@ VRAM-compressed unsigned red/green/blue/alpha channel data format with normalize :ref:`DataFormat` **DATA_FORMAT_EAC_R11G11_SNORM_BLOCK** = ``155`` -11-bit VRAM-compressed signed red/green channel data format with normalized value. Values are in the ``[0.0, 1.0]`` range. Using ETC2 texture compression. +11-bit VRAM-compressed signed red/green channel data format with normalized value. Values are in the ``[-1.0, 1.0]`` range. Using ETC2 texture compression. .. _class_RenderingDevice_constant_DATA_FORMAT_ASTC_4x4_UNORM_BLOCK: diff --git a/classes/class_renderscenebuffersrd.rst b/classes/class_renderscenebuffersrd.rst index 44cf432275c..7989b651241 100644 --- a/classes/class_renderscenebuffersrd.rst +++ b/classes/class_renderscenebuffersrd.rst @@ -35,49 +35,61 @@ Methods .. table:: :widths: auto - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`clear_context`\ (\ context\: :ref:`StringName`\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`create_texture`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, data_format\: :ref:`DataFormat`, usage_bits\: :ref:`int`, texture_samples\: :ref:`TextureSamples`, size\: :ref:`Vector2i`, layers\: :ref:`int`, mipmaps\: :ref:`int`, unique\: :ref:`bool`\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`create_texture_from_format`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, format\: :ref:`RDTextureFormat`, view\: :ref:`RDTextureView`, unique\: :ref:`bool`\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`create_texture_view`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, view_name\: :ref:`StringName`, view\: :ref:`RDTextureView`\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_color_layer`\ (\ layer\: :ref:`int`, msaa\: :ref:`bool` = false\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_color_texture`\ (\ msaa\: :ref:`bool` = false\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_depth_layer`\ (\ layer\: :ref:`int`, msaa\: :ref:`bool` = false\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_depth_texture`\ (\ msaa\: :ref:`bool` = false\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2i` | :ref:`get_internal_size`\ (\ ) |const| | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`ViewportMSAA` | :ref:`get_msaa_3d`\ (\ ) |const| | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_render_target`\ (\ ) |const| | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_texture`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RDTextureFormat` | :ref:`get_texture_format`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_texture_slice`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, layer\: :ref:`int`, mipmap\: :ref:`int`, layers\: :ref:`int`, mipmaps\: :ref:`int`\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2i` | :ref:`get_texture_slice_size`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, mipmap\: :ref:`int`\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_texture_slice_view`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, layer\: :ref:`int`, mipmap\: :ref:`int`, layers\: :ref:`int`, mipmaps\: :ref:`int`, view\: :ref:`RDTextureView`\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`get_use_taa`\ (\ ) |const| | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_velocity_layer`\ (\ layer\: :ref:`int`, msaa\: :ref:`bool` = false\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_velocity_texture`\ (\ msaa\: :ref:`bool` = false\ ) | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_view_count`\ (\ ) |const| | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`has_texture`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | - +--------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_context`\ (\ context\: :ref:`StringName`\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`create_texture`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, data_format\: :ref:`DataFormat`, usage_bits\: :ref:`int`, texture_samples\: :ref:`TextureSamples`, size\: :ref:`Vector2i`, layers\: :ref:`int`, mipmaps\: :ref:`int`, unique\: :ref:`bool`\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`create_texture_from_format`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, format\: :ref:`RDTextureFormat`, view\: :ref:`RDTextureView`, unique\: :ref:`bool`\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`create_texture_view`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, view_name\: :ref:`StringName`, view\: :ref:`RDTextureView`\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_color_layer`\ (\ layer\: :ref:`int`, msaa\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_color_texture`\ (\ msaa\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_depth_layer`\ (\ layer\: :ref:`int`, msaa\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_depth_texture`\ (\ msaa\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_fsr_sharpness`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2i` | :ref:`get_internal_size`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`ViewportMSAA` | :ref:`get_msaa_3d`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_render_target`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`ViewportScaling3DMode` | :ref:`get_scaling_3d_mode`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`ViewportScreenSpaceAA` | :ref:`get_screen_space_aa`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2i` | :ref:`get_target_size`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_texture`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RDTextureFormat` | :ref:`get_texture_format`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`TextureSamples` | :ref:`get_texture_samples`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_texture_slice`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, layer\: :ref:`int`, mipmap\: :ref:`int`, layers\: :ref:`int`, mipmaps\: :ref:`int`\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2i` | :ref:`get_texture_slice_size`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, mipmap\: :ref:`int`\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_texture_slice_view`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`, layer\: :ref:`int`, mipmap\: :ref:`int`, layers\: :ref:`int`, mipmaps\: :ref:`int`, view\: :ref:`RDTextureView`\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_use_debanding`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_use_taa`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_velocity_layer`\ (\ layer\: :ref:`int`, msaa\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_velocity_texture`\ (\ msaa\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_view_count`\ (\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_texture`\ (\ context\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -192,6 +204,18 @@ If ``msaa`` is **true** and MSAA is enabled, this returns the MSAA variant of th ---- +.. _class_RenderSceneBuffersRD_method_get_fsr_sharpness: + +.. rst-class:: classref-method + +:ref:`float` **get_fsr_sharpness**\ (\ ) |const| :ref:`🔗` + +Returns the FSR sharpness value used while rendering the 3D content (if :ref:`get_scaling_3d_mode` is an FSR mode). + +.. rst-class:: classref-item-separator + +---- + .. _class_RenderSceneBuffersRD_method_get_internal_size: .. rst-class:: classref-method @@ -228,6 +252,42 @@ Returns the render target associated with this buffers object. ---- +.. _class_RenderSceneBuffersRD_method_get_scaling_3d_mode: + +.. rst-class:: classref-method + +:ref:`ViewportScaling3DMode` **get_scaling_3d_mode**\ (\ ) |const| :ref:`🔗` + +Returns the scaling mode used for upscaling. + +.. rst-class:: classref-item-separator + +---- + +.. _class_RenderSceneBuffersRD_method_get_screen_space_aa: + +.. rst-class:: classref-method + +:ref:`ViewportScreenSpaceAA` **get_screen_space_aa**\ (\ ) |const| :ref:`🔗` + +Returns the screen-space antialiasing method applied. + +.. rst-class:: classref-item-separator + +---- + +.. _class_RenderSceneBuffersRD_method_get_target_size: + +.. rst-class:: classref-method + +:ref:`Vector2i` **get_target_size**\ (\ ) |const| :ref:`🔗` + +Returns the target size of the render buffer (size after upscaling). + +.. rst-class:: classref-item-separator + +---- + .. _class_RenderSceneBuffersRD_method_get_texture: .. rst-class:: classref-method @@ -252,6 +312,18 @@ Returns the texture format information with which a cached texture was created. ---- +.. _class_RenderSceneBuffersRD_method_get_texture_samples: + +.. rst-class:: classref-method + +:ref:`TextureSamples` **get_texture_samples**\ (\ ) |const| :ref:`🔗` + +Returns the number of MSAA samples used. + +.. rst-class:: classref-item-separator + +---- + .. _class_RenderSceneBuffersRD_method_get_texture_slice: .. rst-class:: classref-method @@ -288,6 +360,18 @@ Returns a specific view of a slice (layer or mipmap) for a cached texture. ---- +.. _class_RenderSceneBuffersRD_method_get_use_debanding: + +.. rst-class:: classref-method + +:ref:`bool` **get_use_debanding**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if debanding is enabled. + +.. rst-class:: classref-item-separator + +---- + .. _class_RenderSceneBuffersRD_method_get_use_taa: .. rst-class:: classref-method diff --git a/classes/class_resource.rst b/classes/class_resource.rst index 14f3dd0285e..830345729a1 100644 --- a/classes/class_resource.rst +++ b/classes/class_resource.rst @@ -254,9 +254,15 @@ Override this method to customize the newly duplicated resource created from :re Duplicates this resource, returning a new resource with its ``export``\ ed or :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` properties copied from the original. -If ``subresources`` is ``false``, a shallow copy is returned; nested resources within subresources are not duplicated and are shared from the original resource. If ``subresources`` is ``true``, a deep copy is returned; nested subresources will be duplicated and are not shared. +If ``subresources`` is ``false``, a shallow copy is returned; nested resources within subresources are not duplicated and are shared with the original resource (with one exception; see below). If ``subresources`` is ``true``, a deep copy is returned; nested subresources will be duplicated and are not shared (with two exceptions; see below). -Subresource properties with the :ref:`@GlobalScope.PROPERTY_USAGE_ALWAYS_DUPLICATE` flag are always duplicated even with ``subresources`` set to ``false``, and properties with the :ref:`@GlobalScope.PROPERTY_USAGE_NEVER_DUPLICATE` flag are never duplicated even with ``subresources`` set to ``true``. +\ ``subresources`` is usually respected, with the following exceptions: + +- Subresource properties with the :ref:`@GlobalScope.PROPERTY_USAGE_ALWAYS_DUPLICATE` flag are always duplicated. + +- Subresource properties with the :ref:`@GlobalScope.PROPERTY_USAGE_NEVER_DUPLICATE` flag are never duplicated. + +- Subresources inside :ref:`Array` and :ref:`Dictionary` properties are never duplicated. \ **Note:** For custom resources, this method will fail if :ref:`Object._init` has been defined with required parameters. diff --git a/classes/class_resourceimportertexture.rst b/classes/class_resourceimportertexture.rst index 5be053430fd..37acc7b5219 100644 --- a/classes/class_resourceimportertexture.rst +++ b/classes/class_resourceimportertexture.rst @@ -329,9 +329,9 @@ More information about normal maps (including a coordinate order table for popul An alternative to fixing darkened borders with :ref:`process/fix_alpha_border` is to use premultiplied alpha. By enabling this option, the texture will be converted to this format. A premultiplied alpha texture requires specific materials to be displayed correctly: -- In 2D, a :ref:`CanvasItemMaterial` will need to be created and configured to use the :ref:`CanvasItemMaterial.BLEND_MODE_PREMULT_ALPHA` blend mode on :ref:`CanvasItem`\ s that use this texture. +- In 2D, a :ref:`CanvasItemMaterial` will need to be created and configured to use the :ref:`CanvasItemMaterial.BLEND_MODE_PREMULT_ALPHA` blend mode on :ref:`CanvasItem`\ s that use this texture. In custom ``@canvas_item`` shaders, ``render_mode blend_premul_alpha;`` should be used. -- In 3D, there is no support for premultiplied alpha blend mode yet, so this option is only suited for 2D. +- In 3D, a :ref:`BaseMaterial3D` will need to be created and configured to use the :ref:`BaseMaterial3D.BLEND_MODE_PREMULT_ALPHA` blend mode on materials that use this texture. In custom ``spatial`` shaders, ``render_mode blend_premul_alpha;`` should be used. .. rst-class:: classref-item-separator diff --git a/classes/class_resourceimporterwav.rst b/classes/class_resourceimporterwav.rst index 1c71c45d83d..6cbf8292c99 100644 --- a/classes/class_resourceimporterwav.rst +++ b/classes/class_resourceimporterwav.rst @@ -91,7 +91,7 @@ The compression mode to use on import. :ref:`int` **edit/loop_begin** = ``0`` :ref:`🔗` -The begin loop point to use when :ref:`edit/loop_mode` is **Forward**, **Ping-Pong** or **Backward**. This is set in seconds after the beginning of the audio file. +The begin loop point to use when :ref:`edit/loop_mode` is **Forward**, **Ping-Pong**, or **Backward**. This is set in samples after the beginning of the audio file. .. rst-class:: classref-item-separator @@ -103,7 +103,7 @@ The begin loop point to use when :ref:`edit/loop_mode` **edit/loop_end** = ``-1`` :ref:`🔗` -The end loop point to use when :ref:`edit/loop_mode` is **Forward**, **Ping-Pong** or **Backward**. This is set in seconds after the beginning of the audio file. A value of ``-1`` uses the end of the audio file as the end loop point. +The end loop point to use when :ref:`edit/loop_mode` is **Forward**, **Ping-Pong**, or **Backward**. This is set in samples after the beginning of the audio file. A value of ``-1`` uses the end of the audio file as the end loop point. .. rst-class:: classref-item-separator diff --git a/classes/class_resourceloader.rst b/classes/class_resourceloader.rst index 46543e6f4ca..845ce3d19e0 100644 --- a/classes/class_resourceloader.rst +++ b/classes/class_resourceloader.rst @@ -294,7 +294,7 @@ GDScript has a simplified :ref:`@GDScript.load` bui Returns the resource loaded by :ref:`load_threaded_request`. -If this is called before the loading thread is done (i.e. :ref:`load_threaded_get_status` is not :ref:`THREAD_LOAD_LOADED`), the calling thread will be blocked until the resource has finished loading. +If this is called before the loading thread is done (i.e. :ref:`load_threaded_get_status` is not :ref:`THREAD_LOAD_LOADED`), the calling thread will be blocked until the resource has finished loading. However, it's recommended to use :ref:`load_threaded_get_status` to known when the load has actually completed. .. rst-class:: classref-item-separator @@ -310,6 +310,8 @@ Returns the status of a threaded loading operation started with :ref:`load_threa An array variable can optionally be passed via ``progress``, and will return a one-element array containing the percentage of completion of the threaded loading. +\ **Note:** The recommended way of using this method is to call it during different frames (e.g., in :ref:`Node._process`, instead of a loop). + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_scenetree.rst b/classes/class_scenetree.rst index 82e2d63d69c..3b3562a856e 100644 --- a/classes/class_scenetree.rst +++ b/classes/class_scenetree.rst @@ -730,7 +730,7 @@ Returns ``true`` if a node added to the given group ``name`` exists in the tree. |void| **notify_group**\ (\ group\: :ref:`StringName`, notification\: :ref:`int`\ ) :ref:`🔗` -Calls :ref:`Object.notification` with the given ``notification`` to all nodes inside this tree added to the ``group``. See also :ref:`call_group` and :ref:`set_group`. +Calls :ref:`Object.notification` with the given ``notification`` to all nodes inside this tree added to the ``group``. See also :doc:`Godot notifications <../tutorials/best_practices/godot_notifications>` and :ref:`call_group` and :ref:`set_group`. \ **Note:** This method acts immediately on all selected nodes at once, which may cause stuttering in some performance-intensive situations. diff --git a/classes/class_script.rst b/classes/class_script.rst index e65cc33bc26..ddb6b6145ea 100644 --- a/classes/class_script.rst +++ b/classes/class_script.rst @@ -266,6 +266,8 @@ Returns ``true`` if the script, or a base class, defines a signal with the given Returns ``true`` if the script contains non-empty source code. +\ **Note:** If a script does not have source code, this does not mean that it is invalid or unusable. For example, a :ref:`GDScript` that was exported with binary tokenization has no source code, but still behaves as expected and could be instantiated. This can be checked with :ref:`can_instantiate`. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_scripteditorbase.rst b/classes/class_scripteditorbase.rst index 5dcd5fc9175..062c0e7e01f 100644 --- a/classes/class_scripteditorbase.rst +++ b/classes/class_scripteditorbase.rst @@ -144,7 +144,7 @@ Emitted when the user contextual goto and the item is in the same script. .. rst-class:: classref-signal -**request_save_previous_state**\ (\ line\: :ref:`int`\ ) :ref:`🔗` +**request_save_previous_state**\ (\ state\: :ref:`Dictionary`\ ) :ref:`🔗` Emitted when the user changes current script or moves caret by 10 or more columns within the same script. diff --git a/classes/class_skeleton3d.rst b/classes/class_skeleton3d.rst index 9616f8efb98..bd90a50ffac 100644 --- a/classes/class_skeleton3d.rst +++ b/classes/class_skeleton3d.rst @@ -40,6 +40,8 @@ Properties .. table:: :widths: auto + +---------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`animate_physical_bones` | ``true`` | +---------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+-----------+ | :ref:`ModifierCallbackModeProcess` | :ref:`modifier_callback_mode_process` | ``1`` | +---------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+-----------+ @@ -71,8 +73,6 @@ Methods +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`force_update_bone_child_transform`\ (\ bone_idx\: :ref:`int`\ ) | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`get_animate_physical_bones`\ (\ ) |const| | - +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedInt32Array` | :ref:`get_bone_children`\ (\ bone_idx\: :ref:`int`\ ) |const| | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_bone_count`\ (\ ) |const| | @@ -123,8 +123,6 @@ Methods +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`reset_bone_poses`\ (\ ) | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_animate_physical_bones`\ (\ enabled\: :ref:`bool`\ ) | - +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_bone_enabled`\ (\ bone_idx\: :ref:`int`, enabled\: :ref:`bool` = true\ ) | +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_bone_global_pose`\ (\ bone_idx\: :ref:`int`, pose\: :ref:`Transform3D`\ ) | @@ -276,6 +274,27 @@ Notification received when this skeleton's pose needs to be updated. In that cas Property Descriptions --------------------- +.. _class_Skeleton3D_property_animate_physical_bones: + +.. rst-class:: classref-property + +:ref:`bool` **animate_physical_bones** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_animate_physical_bones**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_animate_physical_bones**\ (\ ) + +**Deprecated:** This property may be changed or removed in future versions. + +If you follow the recommended workflow and explicitly have :ref:`PhysicalBoneSimulator3D` as a child of **Skeleton3D**, you can control whether it is affected by raycasting without running :ref:`physical_bones_start_simulation`, by its :ref:`SkeletonModifier3D.active`. + +However, for old (deprecated) configurations, **Skeleton3D** has an internal virtual :ref:`PhysicalBoneSimulator3D` for compatibility. This property controls the internal virtual :ref:`PhysicalBoneSimulator3D`'s :ref:`SkeletonModifier3D.active`. + +.. rst-class:: classref-item-separator + +---- + .. _class_Skeleton3D_property_modifier_callback_mode_process: .. rst-class:: classref-property @@ -426,18 +445,6 @@ Force updates the bone transform for the bone at ``bone_idx`` and all of its chi ---- -.. _class_Skeleton3D_method_get_animate_physical_bones: - -.. rst-class:: classref-method - -:ref:`bool` **get_animate_physical_bones**\ (\ ) |const| :ref:`🔗` - -**Deprecated:** This method may be changed or removed in future versions. - -.. rst-class:: classref-item-separator - ----- - .. _class_Skeleton3D_method_get_bone_children: .. rst-class:: classref-method @@ -768,18 +775,6 @@ Sets all bone poses to rests. ---- -.. _class_Skeleton3D_method_set_animate_physical_bones: - -.. rst-class:: classref-method - -|void| **set_animate_physical_bones**\ (\ enabled\: :ref:`bool`\ ) :ref:`🔗` - -**Deprecated:** This method may be changed or removed in future versions. - -.. rst-class:: classref-item-separator - ----- - .. _class_Skeleton3D_method_set_bone_enabled: .. rst-class:: classref-method diff --git a/classes/class_skeletonmodifier3d.rst b/classes/class_skeletonmodifier3d.rst index 401d766dee5..c00c09b431f 100644 --- a/classes/class_skeletonmodifier3d.rst +++ b/classes/class_skeletonmodifier3d.rst @@ -25,7 +25,14 @@ Description If there is :ref:`AnimationMixer`, modification always performs after playback process of the :ref:`AnimationMixer`. -This node should be used to implement custom IK solvers, constraints, or skeleton physics +This node should be used to implement custom IK solvers, constraints, or skeleton physics. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Design of the Skeleton Modifier 3D `__ .. rst-class:: classref-reftable-group diff --git a/classes/class_textedit.rst b/classes/class_textedit.rst index a5913b3b3b0..f71171de46c 100644 --- a/classes/class_textedit.rst +++ b/classes/class_textedit.rst @@ -59,6 +59,8 @@ Properties +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`context_menu_enabled` | ``true`` | +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`custom_word_separators` | ``""`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`deselect_on_focus_loss_enabled` | ``true`` | +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`drag_and_drop_selection_enabled` | ``true`` | @@ -117,6 +119,10 @@ Properties +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`TextDirection` | :ref:`text_direction` | ``0`` | +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`use_custom_word_separators` | ``false`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`use_default_word_separators` | ``true`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`virtual_keyboard_enabled` | ``true`` | +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`LineWrappingMode` | :ref:`wrap_mode` | ``0`` | @@ -1234,6 +1240,23 @@ If ``true``, a right-click displays the context menu. ---- +.. _class_TextEdit_property_custom_word_separators: + +.. rst-class:: classref-property + +:ref:`String` **custom_word_separators** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_custom_word_separators**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_custom_word_separators**\ (\ ) + +The characters to consider as word delimiters if :ref:`use_custom_word_separators` is ``true``. The characters should be defined without separation, for example ``#_!``. + +.. rst-class:: classref-item-separator + +---- + .. _class_TextEdit_property_deselect_on_focus_loss_enabled: .. rst-class:: classref-property @@ -1697,6 +1720,40 @@ Base text writing direction. ---- +.. _class_TextEdit_property_use_custom_word_separators: + +.. rst-class:: classref-property + +:ref:`bool` **use_custom_word_separators** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_custom_word_separators**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_custom_word_separators_enabled**\ (\ ) + +If ``false``, using :kbd:`Ctrl + Left` or :kbd:`Ctrl + Right` (:kbd:`Cmd + Left` or :kbd:`Cmd + Right` on macOS) bindings will use the behavior of :ref:`use_default_word_separators`. If ``true``, it will also stop the caret if a character within :ref:`custom_word_separators` is detected. Useful for subword moving. This behavior also will be applied to the behavior of text selection. + +.. rst-class:: classref-item-separator + +---- + +.. _class_TextEdit_property_use_default_word_separators: + +.. rst-class:: classref-property + +:ref:`bool` **use_default_word_separators** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_default_word_separators**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_default_word_separators_enabled**\ (\ ) + +If ``false``, using :kbd:`Ctrl + Left` or :kbd:`Ctrl + Right` (:kbd:`Cmd + Left` or :kbd:`Cmd + Right` on macOS) bindings will stop moving caret only if a space or punctuation is detected. If ``true``, it will also stop the caret if a character is part of ``!"#$%&'()*+,-./:;<=>?@[\]^`{|}~``, the Unicode General Punctuation table, or the Unicode CJK Punctuation table. Useful for subword moving. This behavior also will be applied to the behavior of text selection. + +.. rst-class:: classref-item-separator + +---- + .. _class_TextEdit_property_virtual_keyboard_enabled: .. rst-class:: classref-property diff --git a/classes/class_textparagraph.rst b/classes/class_textparagraph.rst index 2309a3997fd..f9d6088f07b 100644 --- a/classes/class_textparagraph.rst +++ b/classes/class_textparagraph.rst @@ -593,7 +593,7 @@ Returns TextServer line buffer RID. :ref:`Vector2` **get_line_size**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` -Returns size of the bounding box of the line of text. +Returns size of the bounding box of the line of text. Returned size is rounded up. .. rst-class:: classref-item-separator diff --git a/classes/class_textserver.rst b/classes/class_textserver.rst index 5c820c8c863..655d54c9d71 100644 --- a/classes/class_textserver.rst +++ b/classes/class_textserver.rst @@ -4164,8 +4164,9 @@ When ``chars_per_line`` is greater than zero, line break boundaries are returned :: var ts = TextServerManager.get_primary_interface() - print(ts.string_get_word_breaks("Godot Engine")) # Prints [0, 5, 6, 12] - print(ts.string_get_word_breaks("Godot Engine", "en", 5)) # Prints [0, 5, 6, 11, 11, 12] + print(ts.string_get_word_breaks("The Godot Engine, 4")) # Prints [0, 3, 4, 9, 10, 16, 18, 19], which corresponds to the following substrings: "The", "Godot", "Engine", "4" + print(ts.string_get_word_breaks("The Godot Engine, 4", "en", 5)) # Prints [0, 3, 4, 9, 10, 15, 15, 19], which corresponds to the following substrings: "The", "Godot", "Engin", "e, 4" + print(ts.string_get_word_breaks("The Godot Engine, 4", "en", 10)) # Prints [0, 9, 10, 19], which corresponds to the following substrings: "The Godot", "Engine, 4" .. rst-class:: classref-item-separator diff --git a/classes/class_tilemap.rst b/classes/class_tilemap.rst index bc63e741979..878c1b28d0b 100644 --- a/classes/class_tilemap.rst +++ b/classes/class_tilemap.rst @@ -13,7 +13,7 @@ TileMap ======= -**Deprecated:** Use multiple :ref:`TileMapLayer` nodes instead. +**Deprecated:** Use multiple :ref:`TileMapLayer` nodes instead. To convert a TileMap to a set of TileMapLayer nodes, open the TileMap bottom panel with the node selected, click the toolbox icon in the top-right corner and choose 'Extract TileMap layers as individual TileMapLayer nodes'. **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` diff --git a/classes/class_tilesetscenescollectionsource.rst b/classes/class_tilesetscenescollectionsource.rst index 797902b7a01..f3942c6b91d 100644 --- a/classes/class_tilesetscenescollectionsource.rst +++ b/classes/class_tilesetscenescollectionsource.rst @@ -23,6 +23,39 @@ When placed on a :ref:`TileMap`, tiles from **TileSetScenesCollec Scenes are instantiated as children of the :ref:`TileMap` when it enters the tree. If you add/remove a scene tile in the :ref:`TileMap` that is already inside the tree, the :ref:`TileMap` 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` will always return ``1``. Use :ref:`get_scene_tiles_count` to get a number of scenes in a **TileSetScenesCollectionSource**. + +Use this code if you want to find the scene path at a given tile in :ref:`TileMapLayer`: + + +.. tabs:: + + .. code-tab:: gdscript + + var source_id = tile_map_layer.get_cell_source_id(Vector2i(x, y)) + if source_id > -1: + var scene_source = tile_map_layer.tile_set.get_source(source_id) + if scene_source is TileSetScenesCollectionSource: + var alt_id = tile_map_layer.get_cell_alternative_tile(Vector2i(x, y)) + # The assigned PackedScene. + var scene = scene_source.get_scene_tile_scene(alt_id) + + .. code-tab:: csharp + + int sourceId = tileMapLayer.GetCellSourceId(new Vector2I(x, y)); + if (sourceId > -1) + { + TileSetSource source = tileMapLayer.TileSet.GetSource(sourceId); + if (source is TileSetScenesCollectionSource sceneSource) + { + int altId = tileMapLayer.GetCellAlternativeTile(new Vector2I(x, y)); + // The assigned PackedScene. + PackedScene scene = sceneSource.GetSceneTileScene(altId); + } + } + + + .. rst-class:: classref-reftable-group Methods diff --git a/classes/class_transform2d.rst b/classes/class_transform2d.rst index ccf25f0fbbe..476b1c5c006 100644 --- a/classes/class_transform2d.rst +++ b/classes/class_transform2d.rst @@ -17,10 +17,14 @@ A 2×3 matrix representing a 2D transformation. Description ----------- -A 2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of three :ref:`Vector2` values: :ref:`x`, :ref:`y`, and the :ref:`origin`. +The **Transform2D** built-in :ref:`Variant` type is a 2×3 `matrix `__ representing a transformation in 2D space. It contains three :ref:`Vector2` values: :ref:`x`, :ref:`y`, and :ref:`origin`. Together, they can represent translation, rotation, scale, and skew. + +The :ref:`x` and :ref:`y` axes form a 2×2 matrix, known as the transform's **basis**. The length of each axis (:ref:`Vector2.length`) influences the transform's scale, while the direction of all axes influence the rotation. Usually, both axes are perpendicular to one another. However, when you rotate one axis individually, the transform becomes skewed. Applying a skewed transform to a 2D sprite will make the sprite appear distorted. For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. +\ **Note:** Unlike :ref:`Transform3D`, there is no 2D equivalent to the :ref:`Basis` type. All mentions of "basis" refer to the :ref:`x` and :ref:`y` components of **Transform2D**. + .. note:: There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. @@ -173,7 +177,24 @@ Constants **IDENTITY** = ``Transform2D(1, 0, 0, 1, 0, 0)`` :ref:`🔗` -The identity **Transform2D** with no translation, rotation or scaling applied. When applied to other data structures, :ref:`IDENTITY` performs no transformation. +The identity **Transform2D**. A transform with no translation, no rotation, and its scale being ``1``. When multiplied by another :ref:`Variant` such as :ref:`Rect2` or another **Transform2D**, no transformation occurs. This means that: + +- The :ref:`x` points right (:ref:`Vector2.RIGHT`); + +- The :ref:`y` points up (:ref:`Vector2.UP`). + +:: + + var transform = Transform2D.IDENTITY + print("| X | Y | Origin") + print("| %s | %s | %s" % [transform.x.x, transform.y.x, transform.origin.x]) + print("| %s | %s | %s" % [transform.x.y, transform.y.y, transform.origin.y]) + # Prints: + # | X | Y | Origin + # | 1 | 0 | 0 + # | 0 | 1 | 0 + +This is identical to creating :ref:`Transform2D` without any parameters. This constant can be used to make your code clearer, and for consistency with C#. .. _class_Transform2D_constant_FLIP_X: @@ -181,7 +202,9 @@ The identity **Transform2D** with no translation, rotation or scaling applied. W **FLIP_X** = ``Transform2D(-1, 0, 0, 1, 0, 0)`` :ref:`🔗` -The **Transform2D** that will flip something along the X axis. +When any transform is multiplied by :ref:`FLIP_X`, it negates all components of the :ref:`x` axis (the X column). + +When :ref:`FLIP_X` is multiplied by any basis, it negates the :ref:`Vector2.x` component of all axes (the X row). .. _class_Transform2D_constant_FLIP_Y: @@ -189,7 +212,9 @@ The **Transform2D** that will flip something along the X axis. **FLIP_Y** = ``Transform2D(1, 0, 0, -1, 0, 0)`` :ref:`🔗` -The **Transform2D** that will flip something along the Y axis. +When any transform is multiplied by :ref:`FLIP_Y`, it negates all components of the :ref:`y` axis (the Y column). + +When :ref:`FLIP_Y` is multiplied by any basis, it negates the :ref:`Vector2.y` component of all axes (the Y row). .. rst-class:: classref-section-separator @@ -206,7 +231,7 @@ Property Descriptions :ref:`Vector2` **origin** = ``Vector2(0, 0)`` :ref:`🔗` -The origin vector (column 2, the third column). Equivalent to array index ``2``. The origin vector represents translation. +The translation offset of this transform, and the column ``2`` of the matrix. In 2D space, this can be seen as the position. .. rst-class:: classref-item-separator @@ -218,7 +243,9 @@ The origin vector (column 2, the third column). Equivalent to array index ``2``. :ref:`Vector2` **x** = ``Vector2(1, 0)`` :ref:`🔗` -The basis matrix's X vector (column 0). Equivalent to array index ``0``. +The transform basis's X axis, and the column ``0`` of the matrix. Combined with :ref:`y`, this represents the transform's rotation, scale, and skew. + +On the identity transform, this vector points right (:ref:`Vector2.RIGHT`). .. rst-class:: classref-item-separator @@ -230,7 +257,9 @@ The basis matrix's X vector (column 0). Equivalent to array index ``0``. :ref:`Vector2` **y** = ``Vector2(0, 1)`` :ref:`🔗` -The basis matrix's Y vector (column 1). Equivalent to array index ``1``. +The transform basis's Y axis, and the column ``1`` of the matrix. Combined with :ref:`x`, this represents the transform's rotation, scale, and skew. + +On the identity transform, this vector points up (:ref:`Vector2.UP`). .. rst-class:: classref-section-separator @@ -247,7 +276,7 @@ Constructor Descriptions :ref:`Transform2D` **Transform2D**\ (\ ) :ref:`🔗` -Constructs a default-initialized **Transform2D** set to :ref:`IDENTITY`. +Constructs a **Transform2D** identical to :ref:`IDENTITY`. .. rst-class:: classref-item-separator @@ -267,7 +296,7 @@ Constructs a **Transform2D** as a copy of the given **Transform2D**. :ref:`Transform2D` **Transform2D**\ (\ rotation\: :ref:`float`, position\: :ref:`Vector2`\ ) -Constructs the transform from a given angle (in radians) and position. +Constructs a **Transform2D** from a given angle (in radians) and position. .. rst-class:: classref-item-separator @@ -277,7 +306,7 @@ Constructs the transform from a given angle (in radians) and position. :ref:`Transform2D` **Transform2D**\ (\ rotation\: :ref:`float`, scale\: :ref:`Vector2`, skew\: :ref:`float`, position\: :ref:`Vector2`\ ) -Constructs the transform from a given angle (in radians), scale, skew (in radians) and position. +Constructs a **Transform2D** from a given angle (in radians), scale, skew (in radians), and position. .. rst-class:: classref-item-separator @@ -287,7 +316,7 @@ Constructs the transform from a given angle (in radians), scale, skew (in radian :ref:`Transform2D` **Transform2D**\ (\ x_axis\: :ref:`Vector2`, y_axis\: :ref:`Vector2`, origin\: :ref:`Vector2`\ ) -Constructs the transform from 3 :ref:`Vector2` values representing :ref:`x`, :ref:`y`, and the :ref:`origin` (the three column vectors). +Constructs a **Transform2D** from 3 :ref:`Vector2` values representing :ref:`x`, :ref:`y`, and the :ref:`origin` (the three matrix columns). .. rst-class:: classref-section-separator @@ -304,7 +333,9 @@ Method Descriptions :ref:`Transform2D` **affine_inverse**\ (\ ) |const| :ref:`🔗` -Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant). +Returns the inverted version of this transform. Unlike :ref:`inverse`, this method works with almost any basis, including non-uniform ones, but is slower. See also :ref:`inverse`. + +\ **Note:** For this method to return correctly, the transform's basis needs to have a determinant that is not exactly ``0`` (see :ref:`determinant`). .. rst-class:: classref-item-separator @@ -316,9 +347,7 @@ Returns the inverse of the transform, under the assumption that the basis is inv :ref:`Vector2` **basis_xform**\ (\ v\: :ref:`Vector2`\ ) |const| :ref:`🔗` -Returns a vector transformed (multiplied) by the basis matrix. - -This method does not account for translation (the :ref:`origin` vector). +Returns a copy of the ``v`` vector, transformed (multiplied) by the transform basis's matrix. Unlike the multiplication operator (``*``), this method ignores the :ref:`origin`. .. rst-class:: classref-item-separator @@ -330,13 +359,9 @@ This method does not account for translation (the :ref:`origin` **basis_xform_inv**\ (\ v\: :ref:`Vector2`\ ) |const| :ref:`🔗` -Returns a vector transformed (multiplied) by the inverse basis matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). - -This method does not account for translation (the :ref:`origin` vector). +Returns a copy of the ``v`` vector, transformed (multiplied) by the inverse transform basis's matrix (see :ref:`inverse`). This method ignores the :ref:`origin`. -\ ``transform.basis_xform_inv(vector)`` is equivalent to ``transform.inverse().basis_xform(vector)``. See :ref:`inverse`. - -For non-orthonormal transforms (e.g. with scaling) ``transform.affine_inverse().basis_xform(vector)`` can be used instead. See :ref:`affine_inverse`. +\ **Note:** This method assumes that this transform's basis is *orthonormal* (see :ref:`orthonormalized`). If the basis is not orthonormal, ``transform.affine_inverse().basis_xform(vector)`` should be used instead (see :ref:`affine_inverse`). .. rst-class:: classref-item-separator @@ -348,9 +373,13 @@ For non-orthonormal transforms (e.g. with scaling) ``transform.affine_inverse(). :ref:`float` **determinant**\ (\ ) |const| :ref:`🔗` -Returns the determinant of the basis matrix. If the basis is uniformly scaled, then its determinant equals the square of the scale factor. +Returns the `determinant `__ of this transform basis's matrix. For advanced math, this number can be used to determine a few attributes: + +- If the determinant is exactly ``0``, the basis is not invertible (see :ref:`inverse`). -A negative determinant means the basis was flipped, so one part of the scale is negative. A zero determinant means the basis isn't invertible, and is usually considered invalid. +- If the determinant is a negative number, the basis represents a negative scale. + +\ **Note:** If the basis's scale is the same for every axis, its determinant is always that scale by the power of 2. .. rst-class:: classref-item-separator @@ -362,7 +391,7 @@ A negative determinant means the basis was flipped, so one part of the scale is :ref:`Vector2` **get_origin**\ (\ ) |const| :ref:`🔗` -Returns the transform's origin (translation). +Returns this transform's translation. Equivalent to :ref:`origin`. .. rst-class:: classref-item-separator @@ -374,7 +403,7 @@ Returns the transform's origin (translation). :ref:`float` **get_rotation**\ (\ ) |const| :ref:`🔗` -Returns the transform's rotation (in radians). +Returns this transform's rotation (in radians). This is equivalent to :ref:`x`'s angle (see :ref:`Vector2.angle`). .. rst-class:: classref-item-separator @@ -386,7 +415,38 @@ Returns the transform's rotation (in radians). :ref:`Vector2` **get_scale**\ (\ ) |const| :ref:`🔗` -Returns the scale. +Returns the length of both :ref:`x` and :ref:`y`, as a :ref:`Vector2`. If this transform's basis is not skewed, this value is the scaling factor. It is not affected by rotation. + + +.. tabs:: + + .. code-tab:: gdscript + + var my_transform = Transform2D( + Vector2(2, 0), + Vector2(0, 4), + Vector2(0, 0) + ) + # Rotating the Transform2D in any way preserves its scale. + my_transform = my_transform.rotated(TAU / 2) + + print(my_transform.get_scale()) # Prints (2, 4). + + .. code-tab:: csharp + + var myTransform = new Transform2D( + Vector3(2.0f, 0.0f), + Vector3(0.0f, 4.0f), + Vector3(0.0f, 0.0f) + ); + // Rotating the Transform2D in any way preserves its scale. + myTransform = myTransform.Rotated(Mathf.Tau / 2.0f); + + GD.Print(myTransform.GetScale()); // Prints (2, 4, 8). + + + +\ **Note:** If the value returned by :ref:`determinant` is negative, the scale is also negative. .. rst-class:: classref-item-separator @@ -398,7 +458,7 @@ Returns the scale. :ref:`float` **get_skew**\ (\ ) |const| :ref:`🔗` -Returns the transform's skew (in radians). +Returns this transform's skew (in radians). .. rst-class:: classref-item-separator @@ -410,7 +470,9 @@ Returns the transform's skew (in radians). :ref:`Transform2D` **interpolate_with**\ (\ xform\: :ref:`Transform2D`, weight\: :ref:`float`\ ) |const| :ref:`🔗` -Returns a transform interpolated between this transform and another by a given ``weight`` (on the range of 0.0 to 1.0). +Returns the result of the linear interpolation between this transform and ``xform`` by the given ``weight``. + +The ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). Values outside this range are allowed and can be used to perform *extrapolation* instead. .. rst-class:: classref-item-separator @@ -422,7 +484,9 @@ Returns a transform interpolated between this transform and another by a given ` :ref:`Transform2D` **inverse**\ (\ ) |const| :ref:`🔗` -Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use :ref:`affine_inverse` for non-orthonormal transforms (e.g. with scaling). +Returns the `inverted version of this transform `__. + +\ **Note:** For this method to return correctly, the transform's basis needs to be *orthonormal* (see :ref:`orthonormalized`). That means, the basis should only represent a rotation. If it does not, use :ref:`affine_inverse` instead. .. rst-class:: classref-item-separator @@ -434,7 +498,7 @@ Returns the inverse of the transform, under the assumption that the transformati :ref:`bool` **is_conformal**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the transform's basis is conformal, meaning it preserves angles and distance ratios, and may only be composed of rotation and uniform scale. Returns ``false`` if the transform's basis has non-uniform scale or shear/skew. This can be used to validate if the transform is non-distorted, which is important for physics and other use cases. +Returns ``true`` if this transform's basis is conformal. A conformal basis is both *orthogonal* (the axes are perpendicular to each other) and *uniform* (the axes share the same length). This method can be especially useful during physics calculations. .. rst-class:: classref-item-separator @@ -470,9 +534,7 @@ Returns ``true`` if this transform is finite, by calling :ref:`@GlobalScope.is_f :ref:`Transform2D` **looking_at**\ (\ target\: :ref:`Vector2` = Vector2(0, 0)\ ) |const| :ref:`🔗` -Returns a copy of the transform rotated such that the rotated X-axis points towards the ``target`` position. - -Operations take place in global space. +Returns a copy of the transform rotated such that the rotated X-axis points towards the ``target`` position, in global space. .. rst-class:: classref-item-separator @@ -484,7 +546,7 @@ Operations take place in global space. :ref:`Transform2D` **orthonormalized**\ (\ ) |const| :ref:`🔗` -Returns the transform with the basis orthogonal (90 degrees), and normalized axis vectors (scale of 1 or -1). +Returns a copy of this transform with its basis orthonormalized. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1``), which also means it can only represent rotation. .. rst-class:: classref-item-separator @@ -597,7 +659,7 @@ Operator Descriptions :ref:`bool` **operator !=**\ (\ right\: :ref:`Transform2D`\ ) :ref:`🔗` -Returns ``true`` if the transforms are not equal. +Returns ``true`` if the components of both transforms are not equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. @@ -611,7 +673,9 @@ Returns ``true`` if the transforms are not equal. :ref:`PackedVector2Array` **operator ***\ (\ right\: :ref:`PackedVector2Array`\ ) :ref:`🔗` -Transforms (multiplies) each element of the :ref:`Vector2` array by the given **Transform2D** matrix. +Transforms (multiplies) every :ref:`Vector2` element of the given :ref:`PackedVector2Array` by this transformation matrix. + +On larger arrays, this operation is much faster than transforming each :ref:`Vector2` individually. .. rst-class:: classref-item-separator @@ -623,7 +687,7 @@ Transforms (multiplies) each element of the :ref:`Vector2` array :ref:`Rect2` **operator ***\ (\ right\: :ref:`Rect2`\ ) :ref:`🔗` -Transforms (multiplies) the :ref:`Rect2` by the given **Transform2D** matrix. +Transforms (multiplies) the :ref:`Rect2` by this transformation matrix. .. rst-class:: classref-item-separator @@ -635,7 +699,17 @@ Transforms (multiplies) the :ref:`Rect2` by the given **Transform2D :ref:`Transform2D` **operator ***\ (\ right\: :ref:`Transform2D`\ ) :ref:`🔗` -Composes these two transformation matrices by multiplying them together. This has the effect of transforming the second transform (the child) by the first transform (the parent). +Transforms (multiplies) this transform by the ``right`` transform. + +This is the operation performed between parent and child :ref:`CanvasItem` nodes. + +\ **Note:** If you need to only modify one attribute of this transform, consider using one of the following methods, instead: + +- For translation, see :ref:`translated` or :ref:`translated_local`. + +- For rotation, see :ref:`rotated` or :ref:`rotated_local`. + +- For scale, see :ref:`scaled` or :ref:`scaled_local`. .. rst-class:: classref-item-separator @@ -647,7 +721,7 @@ Composes these two transformation matrices by multiplying them together. This ha :ref:`Vector2` **operator ***\ (\ right\: :ref:`Vector2`\ ) :ref:`🔗` -Transforms (multiplies) the :ref:`Vector2` by the given **Transform2D** matrix. +Transforms (multiplies) the :ref:`Vector2` by this transformation matrix. .. rst-class:: classref-item-separator @@ -659,7 +733,7 @@ Transforms (multiplies) the :ref:`Vector2` by the given **Transfo :ref:`Transform2D` **operator ***\ (\ right\: :ref:`float`\ ) :ref:`🔗` -This operator multiplies all components of the **Transform2D**, including the :ref:`origin` vector, which scales it uniformly. +Multiplies all components of the **Transform2D** by the given :ref:`float`, including the :ref:`origin`. This affects the transform's scale uniformly. .. rst-class:: classref-item-separator @@ -671,7 +745,7 @@ This operator multiplies all components of the **Transform2D**, including the :r :ref:`Transform2D` **operator ***\ (\ right\: :ref:`int`\ ) :ref:`🔗` -This operator multiplies all components of the **Transform2D**, including the :ref:`origin` vector, which scales it uniformly. +Multiplies all components of the **Transform2D** by the given :ref:`int`, including the :ref:`origin`. This affects the transform's scale uniformly. .. rst-class:: classref-item-separator @@ -683,7 +757,7 @@ This operator multiplies all components of the **Transform2D**, including the :r :ref:`Transform2D` **operator /**\ (\ right\: :ref:`float`\ ) :ref:`🔗` -This operator divides all components of the **Transform2D**, including the :ref:`origin` vector, which inversely scales it uniformly. +Divides all components of the **Transform2D** by the given :ref:`float`, including the :ref:`origin`. This affects the transform's scale uniformly. .. rst-class:: classref-item-separator @@ -695,7 +769,7 @@ This operator divides all components of the **Transform2D**, including the :ref: :ref:`Transform2D` **operator /**\ (\ right\: :ref:`int`\ ) :ref:`🔗` -This operator divides all components of the **Transform2D**, including the :ref:`origin` vector, which inversely scales it uniformly. +Divides all components of the **Transform2D** by the given :ref:`int`, including the :ref:`origin`. This affects the transform's scale uniformly. .. rst-class:: classref-item-separator @@ -707,7 +781,7 @@ This operator divides all components of the **Transform2D**, including the :ref: :ref:`bool` **operator ==**\ (\ right\: :ref:`Transform2D`\ ) :ref:`🔗` -Returns ``true`` if the transforms are exactly equal. +Returns ``true`` if the components of both transforms are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. @@ -721,7 +795,7 @@ Returns ``true`` if the transforms are exactly equal. :ref:`Vector2` **operator []**\ (\ index\: :ref:`int`\ ) :ref:`🔗` -Access transform components using their index. ``t[0]`` is equivalent to ``t.x``, ``t[1]`` is equivalent to ``t.y``, and ``t[2]`` is equivalent to ``t.origin``. +Accesses each axis (column) of this transform by their index. Index ``0`` is the same as :ref:`x`, index ``1`` is the same as :ref:`y`, and index ``2`` is the same as :ref:`origin`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_transform3d.rst b/classes/class_transform3d.rst index d5b7f62265d..5c02673f09e 100644 --- a/classes/class_transform3d.rst +++ b/classes/class_transform3d.rst @@ -21,7 +21,7 @@ The **Transform3D** built-in :ref:`Variant` type is a 3×4 matrix For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. -\ **Note:** Godot uses a `right-handed coordinate system `__, which is a common standard. For directions, the convention for built-in types like :ref:`Camera3D` is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the `Importing 3D Scenes <../tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions>`__ tutorial. +\ **Note:** Godot uses a `right-handed coordinate system `__, which is a common standard. For directions, the convention for built-in types like :ref:`Camera3D` is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the `3D asset direction conventions <../tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.html#d-asset-direction-conventions>`__ tutorial. .. note:: diff --git a/classes/class_visibleonscreennotifier2d.rst b/classes/class_visibleonscreennotifier2d.rst index 37e3e0554ab..b789caf2362 100644 --- a/classes/class_visibleonscreennotifier2d.rst +++ b/classes/class_visibleonscreennotifier2d.rst @@ -21,7 +21,7 @@ A rectangular region of 2D space that detects whether it is visible on screen. Description ----------- -:ref:`VisibleOnScreenEnabler2D` represents a rectangular region of 2D space. When any part of this region becomes visible on screen or in a viewport, it will emit a :ref:`screen_entered` signal, and likewise it will emit a :ref:`screen_exited` signal when no part of it remains visible. +**VisibleOnScreenNotifier2D** represents a rectangular region of 2D space. When any part of this region becomes visible on screen or in a viewport, it will emit a :ref:`screen_entered` signal, and likewise it will emit a :ref:`screen_exited` signal when no part of it remains visible. If you want a node to be enabled automatically when this region is visible on screen, use :ref:`VisibleOnScreenEnabler2D`. diff --git a/classes/class_visibleonscreennotifier3d.rst b/classes/class_visibleonscreennotifier3d.rst index d201ffa6166..ded7a0e147a 100644 --- a/classes/class_visibleonscreennotifier3d.rst +++ b/classes/class_visibleonscreennotifier3d.rst @@ -21,7 +21,7 @@ A box-shaped region of 3D space that detects whether it is visible on screen. Description ----------- -:ref:`VisibleOnScreenEnabler3D` represents a box-shaped region of 3D space. When any part of this region becomes visible on screen or in a :ref:`Camera3D`'s view, it will emit a :ref:`screen_entered` signal, and likewise it will emit a :ref:`screen_exited` signal when no part of it remains visible. +**VisibleOnScreenNotifier3D** represents a box-shaped region of 3D space. When any part of this region becomes visible on screen or in a :ref:`Camera3D`'s view, it will emit a :ref:`screen_entered` signal, and likewise it will emit a :ref:`screen_exited` signal when no part of it remains visible. If you want a node to be enabled automatically when this region is visible on screen, use :ref:`VisibleOnScreenEnabler3D`. diff --git a/classes/class_websocketpeer.rst b/classes/class_websocketpeer.rst index c7d7d73de46..b2104534c39 100644 --- a/classes/class_websocketpeer.rst +++ b/classes/class_websocketpeer.rst @@ -482,7 +482,7 @@ Sends the given ``message`` using WebSocket text mode. Prefer this method over : |void| **set_no_delay**\ (\ enabled\: :ref:`bool`\ ) :ref:`🔗` -Disable Nagle's algorithm on the underling TCP socket (default). See :ref:`StreamPeerTCP.set_no_delay` for more information. +Disable Nagle's algorithm on the underlying TCP socket (default). See :ref:`StreamPeerTCP.set_no_delay` for more information. \ **Note:** Not available in the Web export. diff --git a/classes/class_webxrinterface.rst b/classes/class_webxrinterface.rst index e99fd78f484..de4deb8f978 100644 --- a/classes/class_webxrinterface.rst +++ b/classes/class_webxrinterface.rst @@ -75,9 +75,10 @@ Here's the minimum code required to start an immersive VR session: # supported. webxr_interface.requested_reference_space_types = 'bounded-floor, local-floor, local' # In order to use 'local-floor' or 'bounded-floor' we must also - # mark the features as required or optional. + # mark the features as required or optional. By including 'hand-tracking' + # as an optional feature, it will be enabled if supported. webxr_interface.required_features = 'local-floor' - webxr_interface.optional_features = 'bounded-floor' + webxr_interface.optional_features = 'bounded-floor, hand-tracking' # This will return false if we're unable to even request the session, # however, it can still fail asynchronously later in the process, so we @@ -94,7 +95,10 @@ Here's the minimum code required to start an immersive VR session: # This will be the reference space type you ultimately got, out of the # types that you requested above. This is useful if you want the game to # work a little differently in 'bounded-floor' versus 'local-floor'. - print ("Reference space type: " + webxr_interface.reference_space_type) + print("Reference space type: ", webxr_interface.reference_space_type) + # This will be the list of features that were successfully enabled + # (except on browsers that don't support this property). + print("Enabled features: ", webxr_interface.enabled_features) func _webxr_session_ended(): $Button.visible = true @@ -419,7 +423,9 @@ Property Descriptions A comma-separated list of features that were successfully enabled by :ref:`XRInterface.initialize` when setting up the WebXR session. -This may include features requested by setting :ref:`required_features` and :ref:`optional_features`. +This may include features requested by setting :ref:`required_features` and :ref:`optional_features`, and will only be available after :ref:`session_started` has been emitted. + +\ **Note:** This may not be support by all web browsers, in which case it will be an empty string. .. rst-class:: classref-item-separator @@ -442,7 +448,7 @@ If a user's browser or device doesn't support one of the given features, initial This doesn't have any effect on the interface when already initialized. -Possible values come from `WebXR's XRReferenceSpaceType `__. If you want to use a particular reference space type, it must be listed in either :ref:`required_features` or :ref:`optional_features`. +Possible values come from `WebXR's XRReferenceSpaceType `__, or include other features like ``"hand-tracking"`` to enable hand tracking. .. rst-class:: classref-item-separator @@ -506,7 +512,7 @@ If a user's browser or device doesn't support one of the given features, initial This doesn't have any effect on the interface when already initialized. -Possible values come from `WebXR's XRReferenceSpaceType `__. If you want to use a particular reference space type, it must be listed in either :ref:`required_features` or :ref:`optional_features`. +Possible values come from `WebXR's XRReferenceSpaceType `__, or include other features like ``"hand-tracking"`` to enable hand tracking. .. rst-class:: classref-item-separator diff --git a/classes/class_window.rst b/classes/class_window.rst index bf0a89c2cf9..004a0b70cf9 100644 --- a/classes/class_window.rst +++ b/classes/class_window.rst @@ -2137,6 +2137,12 @@ Causes the window to grab focus, allowing it to receive user input. Shows the **Window** and makes it transient (see :ref:`transient`). If ``rect`` is provided, it will be set as the **Window**'s size. Fails if called on the main window. +If :ref:`ProjectSettings.display/window/subwindows/embed_subwindows` is ``true`` (single-window mode), ``rect``'s coordinates are global and relative to the main window's top-left corner (excluding window decorations). If ``rect``'s position coordinates are negative, the window will be located outside the main window and may not be visible as a result. + +If :ref:`ProjectSettings.display/window/subwindows/embed_subwindows` is ``false`` (multi-window mode), ``rect``'s coordinates are global and relative to the top-left corner of the leftmost screen. If ``rect``'s position coordinates are negative, the window will be placed at the top-left corner of the screen. + +\ **Note:** ``rect`` must be in global coordinates if specified. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_xrinterface.rst b/classes/class_xrinterface.rst index ce3e8e907a7..6b0dcdc5a70 100644 --- a/classes/class_xrinterface.rst +++ b/classes/class_xrinterface.rst @@ -704,6 +704,14 @@ Triggers a haptic pulse on a device associated with this interface. \ ``tracker_name`` is optional and can be used to direct the pulse to a specific device provided that device is bound to this haptic. +\ ``frequency`` is the frequency of the pulse, set to ``0.0`` to have the system use a default frequency. + +\ ``amplitude`` is the amplitude of the pulse between ``0.0`` and ``1.0``. + +\ ``duration_sec`` is the duration of the pulse in seconds. + +\ ``delay_sec`` is a delay in seconds before the pulse is given. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_xrnode3d.rst b/classes/class_xrnode3d.rst index 675e6db7b89..e6a0642610b 100644 --- a/classes/class_xrnode3d.rst +++ b/classes/class_xrnode3d.rst @@ -196,6 +196,14 @@ Triggers a haptic pulse on a device associated with this interface. \ ``action_name`` is the name of the action for this pulse. +\ ``frequency`` is the frequency of the pulse, set to ``0.0`` to have the system use a default frequency. + +\ ``amplitude`` is the amplitude of the pulse between ``0.0`` and ``1.0``. + +\ ``duration_sec`` is the duration of the pulse in seconds. + +\ ``delay_sec`` is a delay in seconds before the pulse is given. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/community/asset_library/what_is_assetlib.rst b/community/asset_library/what_is_assetlib.rst index 7d42a957c3f..890b9841fb1 100644 --- a/community/asset_library/what_is_assetlib.rst +++ b/community/asset_library/what_is_assetlib.rst @@ -31,10 +31,10 @@ Types of assets Be aware that there are, broadly, two different types of assets you can post. * Assets labeled as "Templates", "Projects", or "Demos" appear under - the "Asset Library Projects" tab in the Godot Project Manager. These assets are + the "Asset Library" tab in the Godot Project Manager. These assets are standalone Godot projects that can run by themselves. -* Other assets show up inside of the Godot editor under the "AssetLib" +* Other assets show up inside of the Godot editor under the "Asset Library" main screen tab, next to "2D", "3D", and "Script". These assets are meant to be downloaded and placed into an existing Godot project. diff --git a/community/tutorials.rst b/community/tutorials.rst index a52e43b371c..118e8853769 100644 --- a/community/tutorials.rst +++ b/community/tutorials.rst @@ -43,7 +43,7 @@ Video tutorials Text tutorials -------------- -- `FinepointCGI website by Mitch `__ +- `FinePointCGI website by Mitch `__ - `GDScript website by Andrew Wilkes `__ - `Godot Recipes by KidsCanCode `__ - `Godot Tutorials by SomethingLikeGames `__ @@ -62,4 +62,3 @@ Resources - `awesome-godot: A curated list of free/libre plugins, scripts and add-ons `_ - `Godot Asset Library `_ - `Godot Shaders: A community-driven shader library `_ -- `Zeef Godot Engine: A curated directory of resources by Andre Schmitz `_ diff --git a/contributing/development/compiling/compiling_for_android.rst b/contributing/development/compiling/compiling_for_android.rst index dc67cf3ad2d..c7f50ade78a 100644 --- a/contributing/development/compiling/compiling_for_android.rst +++ b/contributing/development/compiling/compiling_for_android.rst @@ -38,7 +38,7 @@ For compiling under Windows, Linux or macOS, the following is required: - Gradle (will be downloaded and installed automatically if missing). - JDK 17 (either OpenJDK or Oracle JDK). - - You can download a build from `ojdkbuild `_. + - You can download a build from `Adoptium `_. .. seealso:: To get the Godot source code for compiling, see :ref:`doc_getting_source`. @@ -90,10 +90,11 @@ Setting up the buildsystem Building the export templates ----------------------------- -Godot needs two export templates for Android: the optimized "release" -template (``android_release.apk``) and the debug template (``android_debug.apk``). +Godot needs three export templates for Android: the optimized "release" +template (``android_release.apk``), the debug template (``android_debug.apk``), +and the Gradle build template (``android_source.zip``). As Google requires all APKs to include ARMv8 (64-bit) libraries since August 2019, -the commands below build an APK containing both ARMv7 and ARMv8 libraries. +the commands below build templates containing both ARMv7 and ARMv8 libraries. Compiling the standard export templates is done by calling SCons from the Godot root directory with the following arguments: @@ -105,14 +106,6 @@ root directory with the following arguments: scons platform=android target=template_release arch=arm32 scons platform=android target=template_release arch=arm64 generate_apk=yes -.. note:: - - If you are changing the list of architectures you're building, remember to add - ``generate_apk=yes`` to the *last* architecture you're building, so that an APK - file is generated after the build. - -The resulting APK will be located at ``bin/android_release.apk``. - - Debug template (used when exporting with **Debugging Enabled** checked) :: @@ -120,7 +113,25 @@ The resulting APK will be located at ``bin/android_release.apk``. scons platform=android target=template_debug arch=arm32 scons platform=android target=template_debug arch=arm64 generate_apk=yes -The resulting APK will be located at ``bin/android_debug.apk``. +- (**Optional**) Dev template (used when troubleshooting) + +:: + + scons platform=android target=template_debug arch=arm32 dev_build=yes + scons platform=android target=template_debug arch=arm64 dev_build=yes generate_apk=yes + +The resulting templates will be located under the ``bin`` directory: + +- ``bin/android_release.apk`` for the release template +- ``bin/android_debug.apk`` for the debug template +- ``bin/android_dev.apk`` for the dev template +- ``bin/android_source.zip`` for the Gradle build template + +.. note:: + + - If you are changing the list of architectures you're building, remember to add ``generate_apk=yes`` to the *last* architecture you're building, so that the template files are generated after the build. + + - To include debug symbols in the generated templates, add the ``debug_symbols=yes`` parameter to the SCons command. .. seealso:: @@ -142,10 +153,10 @@ example, for the release template: scons platform=android target=template_release arch=x86_32 scons platform=android target=template_release arch=x86_64 generate_apk=yes -This will create a fat binary that works on all platforms. -The final APK size of exported projects will depend on the platforms you choose +This will create template binaries that works on all platforms. +The final binary size of exported projects will depend on the platforms you choose to support when exporting; in other words, unused platforms will be removed from -the APK. +the binary. Cleaning the generated export templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -164,19 +175,18 @@ You can use the following commands to remove the generated export templates: Using the export templates -------------------------- -Godot needs release and debug APKs that were compiled against the same +Godot needs release and debug binaries that were compiled against the same version/commit as the editor. If you are using official binaries for the editor, make sure to install the matching export templates, or build your own from the same version. -When exporting your game, Godot opens the APK, changes a few things inside and -adds your files. +When exporting your game, Godot uses the templates as a base, and updates their content as needed. Installing the templates ~~~~~~~~~~~~~~~~~~~~~~~~ The newly-compiled templates (``android_debug.apk`` -and ``android_release.apk``) must be copied to Godot's templates folder +, ``android_release.apk``, and ``android_source.zip``) must be copied to Godot's templates folder with their respective names. The templates folder can be located in: - Windows: ``%APPDATA%\Godot\export_templates\\`` @@ -191,7 +201,7 @@ next to your export templates. .. TODO: Move these paths to a common reference page However, if you are writing your custom modules or custom C++ code, you -might instead want to configure your APKs as custom export templates +might instead want to configure your template binaries as custom export templates here: .. image:: img/andtemplates.png @@ -214,16 +224,20 @@ root directory with the following arguments: scons platform=android arch=x86_32 production=yes target=editor scons platform=android arch=x86_64 production=yes target=editor generate_apk=yes -You can skip certain architectures depending on your target device to speed up -compilation. Remember to add ``generate_apk=yes`` to the *last* architecture -you're building, so that an APK file is generated after the build. +- You can add the ``dev_build=yes`` parameter to generate a dev build of the Godot editor. -The resulting APK will be located at ``bin/android_editor_builds/android_editor-release.apk``. +- You can add the ``debug_symbols=yes`` parameter to include the debug symbols in the generated build. -Removing the Editor templates ------------------------------ +- You can skip certain architectures depending on your target device to speed up compilation. + +Remember to add ``generate_apk=yes`` to the *last* architecture you're building, so that binaries are generated after the build. + +The resulting binaries will be located under ``bin/android_editor_builds/``. + +Removing the Editor binaries +---------------------------- -You can use the following commands to remove the generated editor templates: +You can use the following commands to remove the generated editor binaries: :: @@ -233,8 +247,8 @@ You can use the following commands to remove the generated editor templates: # On Linux and macOS ./gradlew clean -Installing the Godot editor ---------------------------- +Installing the Godot editor APK +------------------------------- With an Android device with Developer Options enabled, connect the Android device to your computer via its charging cable to a USB/USB-C port. Open up a Terminal/Command Prompt and run the following commands from the root directory with the following arguments: diff --git a/contributing/development/compiling/compiling_for_linuxbsd.rst b/contributing/development/compiling/compiling_for_linuxbsd.rst index c348cc6d7e4..942b5dff642 100644 --- a/contributing/development/compiling/compiling_for_linuxbsd.rst +++ b/contributing/development/compiling/compiling_for_linuxbsd.rst @@ -437,16 +437,53 @@ you may not be able to use system libraries for everything due to bugs in the system library packages (or in the build system, as this feature is less tested). -To compile Godot with system libraries, install these dependencies *on top* of the ones +To compile Godot with system libraries, install these dependencies **on top** of the ones listed in the :ref:`doc_compiling_for_linuxbsd_oneliners`: -+------------------+-----------------------------------------------------------------------------------------------------------+ -| **Fedora** | :: | -| | | -| | sudo dnf install embree3-devel enet-devel glslang-devel graphite2-devel harfbuzz-devel libicu-devel \ | -| | libsquish-devel libtheora-devel libvorbis-devel libwebp-devel libzstd-devel mbedtls-devel \ | -| | miniupnpc-devel | -+------------------+-----------------------------------------------------------------------------------------------------------+ +.. tabs:: + + .. tab:: Debian/Ubuntu + + :: + + sudo apt-get update + sudo apt-get install -y \ + libembree-dev \ + libenet-dev \ + libfreetype-dev \ + libpng-dev \ + zlib1g-dev \ + libgraphite2-dev \ + libharfbuzz-dev \ + libogg-dev \ + libtheora-dev \ + libvorbis-dev \ + libwebp-dev \ + libmbedtls-dev \ + libminiupnpc-dev \ + libpcre2-dev \ + libzstd-dev \ + libsquish-dev \ + libicu-dev + + .. tab:: Fedora + + :: + + sudo dnf install -y \ + embree3-devel \ + enet-devel \ + glslang-devel \ + graphite2-devel \ + harfbuzz-devel \ + libicu-devel \ + libsquish-devel \ + libtheora-devel \ + libvorbis-devel \ + libwebp-devel \ + libzstd-devel \ + mbedtls-devel \ + miniupnpc-devel After installing all required packages, use the following command to build Godot: @@ -457,6 +494,10 @@ After installing all required packages, use the following command to build Godot scons platform=linuxbsd builtin_embree=no builtin_enet=no builtin_freetype=no builtin_graphite=no builtin_harfbuzz=no builtin_libogg=no builtin_libpng=no builtin_libtheora=no builtin_libvorbis=no builtin_libwebp=no builtin_mbedtls=no builtin_miniupnpc=no builtin_pcre2=no builtin_zlib=no builtin_zstd=no +On Debian stable, you will need to remove `builtin_embree=no` as the system-provided +Embree version is too old to work with Godot's latest `master` branch +(which requires Embree 4). + You can view a list of all built-in libraries that have system alternatives by running ``scons -h``, then looking for options starting with ``builtin_``. diff --git a/contributing/development/compiling/compiling_for_web.rst b/contributing/development/compiling/compiling_for_web.rst index 7e4863a877a..89e1a1e916c 100644 --- a/contributing/development/compiling/compiling_for_web.rst +++ b/contributing/development/compiling/compiling_for_web.rst @@ -51,6 +51,12 @@ enabled. Since ``eval()`` calls can be a security concern, the scons platform=web target=template_release javascript_eval=no scons platform=web target=template_debug javascript_eval=no +By default, WebWorker threads support is enabled. To disable it and only use a single thread, +the ``threads`` option can be used to build the web template without threads support:: + + scons platform=web target=template_release threads=no + scons platform=web target=template_debug threads=no + The engine will now be compiled to WebAssembly by Emscripten. Once finished, the resulting file will be placed in the ``bin`` subdirectory. Its name is ``godot.web.template_release.wasm32.zip`` for release or ``godot.web.template_debug.wasm32.zip`` diff --git a/contributing/development/compiling/compiling_for_windows.rst b/contributing/development/compiling/compiling_for_windows.rst index d3ce579b3aa..adea4528c71 100644 --- a/contributing/development/compiling/compiling_for_windows.rst +++ b/contributing/development/compiling/compiling_for_windows.rst @@ -20,9 +20,14 @@ For compiling under Windows, the following is required: **Make sure to enable C++ in the list of workflows to install.** If you've already installed Visual Studio without C++ support, run the installer again; it should present you a **Modify** button. + Supports ``x86_64``, ``x86_32``, and ``arm64``. - `MinGW-w64 `_ with GCC can be used as an alternative to Visual Studio. Be sure to install/configure it to use the ``posix`` thread model. **Important:** When using MinGW to compile the ``master`` branch, you need GCC 9 or later. + Supports ``x86_64`` and ``x86_32`` only. +- `MinGW-LLVM `_ with clang can be used as + an alternative to Visual Studio and MinGW-w64. + Supports ``x86_64``, ``x86_32``, and ``arm64``. - `Python 3.6+ `_. **Make sure to enable the option to add Python to the ``PATH`` in the installer.** - `SCons 3.1.2+ `_ build system. Using the @@ -106,9 +111,10 @@ Selecting a compiler SCons will automatically find and use an existing Visual Studio installation. If you do not have Visual Studio installed, it will attempt to use MinGW instead. If you already have Visual Studio installed and want to -use MinGW, pass ``use_mingw=yes`` to the SCons command line. Note that MSVC +use MinGW-w64, pass ``use_mingw=yes`` to the SCons command line. Note that MSVC builds cannot be performed from the MSYS2 or MinGW shells. Use either -``cmd.exe`` or PowerShell instead. +``cmd.exe`` or PowerShell instead. If you are using MinGW-LLVM, pass both +``use_mingw=yes`` and ``use_llvm=yes`` to the SCons command line. .. tip:: @@ -140,8 +146,8 @@ the engine source code (using ``cd``) and type: If all goes well, the resulting binary executable will be placed in ``C:\godot\bin\`` with the name ``godot.windows.editor.x86_32.exe`` or ``godot.windows.editor.x86_64.exe``. By default, SCons will build a binary matching -your CPU architecture, but this can be overridden using ``arch=x86_64`` or -``arch=x86_32``. +your CPU architecture, but this can be overridden using ``arch=x86_64``, +``arch=x86_32``, or ``arch=arm64``. This executable file contains the whole engine and runs without any dependencies. Running it will bring up the Project Manager. @@ -151,10 +157,10 @@ dependencies. Running it will bring up the Project Manager. SCons option ``production=yes``. This enables additional compiler optimizations and link-time optimization. - LTO takes some time to run and requires about 7 GB of available RAM - while compiling. If you're running out of memory with the above option, - use ``production=yes lto=none`` or ``production=yes lto=thin`` for a - lightweight but less effective form of LTO. + LTO takes some time to run and requires up to 30 GB of available RAM + while compiling (depending on toolchain). If you're running out of memory + with the above option, use ``production=yes lto=none`` or ``production=yes lto=thin`` + (LLVM only) for a lightweight but less effective form of LTO. .. note:: If you want to use separate editor settings for your own Godot builds and official releases, you can enable @@ -167,12 +173,8 @@ Compiling with support for Direct3D 12 By default, builds of Godot do not contain support for the Direct3D 12 graphics API. -To compile Godot with Direct3D 12 support you need at least the following: +To compile Godot with Direct3D 12 support you need at least the following item: -- `The DirectX Shader Compiler `_. - The zip folder will be named "dxc\_" followed by the date of release. Download - it anywhere, unzip it and remember the path to the unzipped folder, you will - need it below. - `godot-nir-static library `_. We compile the Mesa libraries you will need into a static library. Download it anywhere, unzip it and remember the path to the unzipped folder, you will @@ -191,11 +193,18 @@ To compile Godot with Direct3D 12 support you need at least the following: ./update_mesa.sh scons - If you are building with MinGW, add ``use_mingw=yes`` to the ``scons`` + If you are building with MinGW-w64, add ``use_mingw=yes`` to the ``scons`` command, you can also specify build architecture using ``arch={architecture}``. + If you are building with MinGW-LLVM, add both ``use_mingw=yes`` and + ``use_llvm=yes`` to the ``scons`` command. + + If you are building with MinGW and the binaries are not located in + the ``PATH``, add ``mingw_prefix="/path/to/mingw"`` to the ``scons`` + command. - Mesa static library should be built using the same compiler you are - using for building Godot. + Mesa static library should be built using the same compiler and the + same CRT (if you are building with MinGW) you are using for building + Godot. Optionally, you can compile with the following for additional features: @@ -232,23 +241,13 @@ look for the additional libraries: .. code-block:: doscon - C:\godot> scons platform=windows d3d12=yes dxc_path=<...> mesa_libs=<...> + C:\godot> scons platform=windows d3d12=yes mesa_libs=<...> Or, with all options enabled: .. code-block:: doscon - C:\godot> scons platform=windows d3d12=yes dxc_path=<...> mesa_libs=<...> agility_sdk_path=<...> pix_path=<...> - -.. note:: The build process will copy ``dxil.dll`` from the ``bin//`` - directory in the DXC folder to the Godot binary directory and the - appropriate ``bin/`` file in the Godot binary directory. - Direct3D 12-enabled Godot packages for distribution to end users must - include the ``dxil.dll`` (and relevant folders if using multi-arch), - both for the editor and games. At runtime, the renderer will try to - load the DLL from the arch-specific folders, and will fall back to the - same directory as the Godot executable if the appropriate arch isn't - found. + C:\godot> scons platform=windows d3d12=yes mesa_libs=<...> agility_sdk_path=<...> pix_path=<...> .. note:: For the Agility SDK's DLLs you have to explicitly choose the kind of workflow. Single-arch is the default (DLLs copied to ``bin/``). If you @@ -285,13 +284,22 @@ To compile Godot with statically linked ANGLE: directory and navigate to it. 2. Run the following command:: + git submodule update --init + ./update_angle.sh scons If you are buildng with MinGW, add ``use_mingw=yes`` to the command, you can also specify build architecture using ``arch={architecture}``. + If you are building with MinGW-LLVM, add both ``use_mingw=yes`` and + ``use_llvm=yes`` to the ``scons`` command. - ANGLE static library should be built using the same compiler you are - using for building Godot. + If you are building with MinGW and the binaries are not located in + the ``PATH``, add ``mingw_prefix="/path/to/mingw"`` to the ``scons`` + command. + + ANGLE static library should be built using the same compiler and the + same CRT (if you are building with MinGW) you are using for building + Godot. Development in Visual Studio ---------------------------- @@ -317,9 +325,10 @@ Cross-compiling for Windows from other operating systems -------------------------------------------------------- If you are a Linux or macOS user, you need to install -`MinGW-w64 `__, which typically comes in 32-bit -and 64-bit variants. The package names may differ based on your distribution, -here are some known ones: +`MinGW-w64 `__, which typically comes in 32-bit +and 64-bit variants, or `MinGW-LLVM `_, +which comes as a single archive for all target architectures. +The package names may differ based on your distribution, here are some known ones: +----------------+--------------------------------------------------------------+ | **Arch Linux** | :: | @@ -348,9 +357,15 @@ here are some known ones: Before attempting the compilation, SCons will check for the following binaries in your ``PATH`` environment variable:: + # for MinGW-w64 i686-w64-mingw32-gcc x86_64-w64-mingw32-gcc + # for MinGW-LLVM + aarch64-w64-mingw32-clang + i686-w64-mingw32-clang + x86_64-w64-mingw32-clang + If the binaries are not located in the ``PATH`` (e.g. ``/usr/bin``), you can define the following environment variable to give a hint to the build system:: @@ -368,10 +383,11 @@ differ based on your system):: ${MINGW_PREFIX}/bin/x86_64-w64-mingw32-gcc --version # x86_64-w64-mingw32-gcc (GCC) 13.2.0 +.. note:: If you are building with MinGW-LLVM, add ``use_llvm=yes`` to the ``scons`` command. .. note:: When cross-compiling for Windows using MinGW-w64, keep in mind only - ``x86_64`` and ``x86_32`` architectures are supported. Be sure to - specify the right ``arch=`` option when invoking SCons if building - from a different architecture. + ``x86_64`` and ``x86_32`` architectures are supported. MinGW-LLVM supports + ``arm64`` as well. Be sure to specify the right ``arch=`` option when + invoking SCons if building from a different architecture. Troubleshooting ~~~~~~~~~~~~~~~ @@ -407,6 +423,8 @@ with the following flags: C:\godot> scons platform=windows target=template_release arch=x86_32 C:\godot> scons platform=windows target=template_debug arch=x86_64 C:\godot> scons platform=windows target=template_release arch=x86_64 + C:\godot> scons platform=windows target=template_debug arch=arm64 + C:\godot> scons platform=windows target=template_release arch=arm64 If you plan on replacing the standard export templates, copy these to the following location, replacing ```` with the version identifier @@ -422,16 +440,22 @@ With the following names:: windows_debug_x86_32.exe windows_debug_x86_64_console.exe windows_debug_x86_64.exe + windows_debug_arm64_console.exe + windows_debug_arm64.exe windows_release_x86_32_console.exe windows_release_x86_32.exe windows_release_x86_64_console.exe windows_release_x86_64.exe + windows_release_arm64_console.exe + windows_release_arm64.exe However, if you are using custom modules or custom engine code, you may instead want to configure your binaries as custom export templates here: -.. image:: img/wintemplates.png +.. 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 diff --git a/contributing/development/compiling/cross-compiling_for_ios_on_linux.rst b/contributing/development/compiling/cross-compiling_for_ios_on_linux.rst index 08be816bde8..0d0b13df0c3 100644 --- a/contributing/development/compiling/cross-compiling_for_ios_on_linux.rst +++ b/contributing/development/compiling/cross-compiling_for_ios_on_linux.rst @@ -24,94 +24,61 @@ described here and cross-compiling the binary. Requirements ------------ -- `XCode with the iOS SDK `__ - (a dmg image, for newer versions a **xip** file is going to be downloaded.) +- `XCode with the iOS SDK `__ + (you must be logged into an Apple ID to download Xcode). - `Clang >= 3.5 `__ for your development machine installed and in the ``PATH``. It has to be version >= 3.5 to target ``arm64`` architecture. -- `Fuse `__ for mounting and unmounting - the dmg image. -- `darling-dmg `__, which - needs to be built from source. The procedure for that is explained - below. - - - For newer versions you should download `xar `__ - and `pbzx `__. - - For building darling-dmg, you'll need the development packages of - the following libraries: fuse, icu, openssl, zlib, bzip2. - - For building xar and pbzx you may want to follow - `this guide `__. +- `xar `__ and `pbzx `__ + (required to extract the ``.xip`` archive Xcode comes in). + + - For building xar and pbzx, you may want to follow + `this guide `__. - `cctools-port `__ for the needed build tools. The procedure for building is quite peculiar and is described below. - - This also has some extra dependencies: automake, autogen, libtool. + - This also has some extra dependencies: automake, autogen, libtool. Configuring the environment --------------------------- -darling-dmg -~~~~~~~~~~~ - -Clone the repository on your machine: - -:: - - $ git clone https://github.com/darlinghq/darling-dmg.git - -Build it: - -:: - - $ cd darling-dmg - $ mkdir build - $ cd build - $ cmake .. -DCMAKE_BUILD_TYPE=Release - $ make -j 4 # The number is the amount of cores your processor has, for faster build - $ cd ../.. - Preparing the SDK ~~~~~~~~~~~~~~~~~ -Mount the XCode image: +Extract the Xcode ``.xip`` file you downloaded from Apple's developer website: :: - $ mkdir xcode - $ ./darling-dmg/build/darling-dmg /path/to/Xcode_7.1.1.dmg xcode - [...] - Everything looks OK, disk mounted - - -For newer versions you should extract the **xip** file: - -:: + mkdir xcode + xar -xf /path/to/Xcode_X.x.xip -C xcode + pbzx -n Content | cpio -i - $ mkdir xcode - $ xar -xf /path/to/Xcode_X.x.xip -C xcode - $ pbzx -n Content | cpio -i [...] ######### Blocks -Note that for the commands below, you may need to replace the version (`X.x`) with whatever iOS SDK version you're using. +Note that for the commands below, you will need to replace the version (``x.x``) +with whatever iOS SDK version you're using. If you don't know your iPhone SDK +version, you can see the JSON file inside of +``Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs``. Extract the iOS SDK: :: - $ # If you don't know your iPhone SDK version you can see the json file inside of Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs - $ mkdir -p iPhoneSDK/iPhoneOSX.x.sdk - $ cp -r xcode/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/* iPhoneSDK/iPhoneOSX.x.sdk - $ cp -r xcode/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/* iPhoneSDK/iPhoneOSX.x.sdk/usr/include/c++ - $ fusermount -u xcode # unmount the image + export IOS_SDK_VERSION="x.x" + mkdir -p iPhoneSDK/iPhoneOS${IOS_SDK_VERSION}.sdk + cp -r xcode/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/* iPhoneSDK/iPhoneOS${IOS_SDK_VERSION}.sdk + cp -r xcode/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/* iPhoneSDK/iPhoneOS${IOS_SDK_VERSION}.sdk/usr/include/c++ + fusermount -u xcode -Pack the SDK: +Pack the SDK so that cctools can use it: :: - $ cd iPhoneSDK - $ tar -cf - * | xz -9 -c - > iPhoneOSX.x.sdk.tar.xz + cd iPhoneSDK + tar -cf - * | xz -9 -c - > iPhoneOS${IOS_SDK_VERSION}.sdk.tar.xz Toolchain ~~~~~~~~~ @@ -120,9 +87,9 @@ Build cctools: :: - $ git clone https://github.com/tpoechtrager/cctools-port.git - $ cd cctools-port/usage_examples/ios_toolchain - $ ./build.sh /path/iPhoneOSX.x.sdk.tar.xz arm64 + git clone https://github.com/tpoechtrager/cctools-port.git + cd cctools-port/usage_examples/ios_toolchain + ./build.sh /path/iPhoneOS${IOS_SDK_VERSION}.sdk.tar.xz arm64 Copy the tools to a nicer place. Note that the SCons scripts for building will look under ``usr/bin`` inside the directory you provide @@ -131,11 +98,11 @@ to the following commands: :: - $ mkdir -p /home/user/iostoolchain/usr - $ cp -r target/bin /home/user/iostoolchain/usr/ + mkdir -p "$HOME/iostoolchain/usr" + cp -r target/bin "$HOME/iostoolchain/usr/" Now you should have the iOS toolchain binaries in -``/home/user/iostoolchain/usr/bin``. +``$HOME/iostoolchain/usr/bin``. Compiling Godot for iPhone -------------------------- @@ -150,11 +117,11 @@ environment variable defined to anything. :: - $ export OSXCROSS_IOS=anything + export OSXCROSS_IOS="anything" Now you can compile for iPhone using SCons like the standard Godot way, with some additional arguments to provide the correct paths: :: - $ scons -j 4 platform=ios arch=arm64 target=template_release IOS_SDK_PATH="/path/to/iPhoneSDK" IOS_TOOLCHAIN_PATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-" + scons platform=ios arch=arm64 target=template_release IOS_SDK_PATH="/path/to/iPhoneSDK" IOS_TOOLCHAIN_PATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-" diff --git a/contributing/development/compiling/img/wintemplates.png b/contributing/development/compiling/img/wintemplates.png deleted file mode 100644 index 56157c0dc0f..00000000000 Binary files a/contributing/development/compiling/img/wintemplates.png and /dev/null differ diff --git a/contributing/development/compiling/img/wintemplates.webp b/contributing/development/compiling/img/wintemplates.webp new file mode 100644 index 00000000000..db99b07c5cf Binary files /dev/null and b/contributing/development/compiling/img/wintemplates.webp differ diff --git a/contributing/development/compiling/introduction_to_the_buildsystem.rst b/contributing/development/compiling/introduction_to_the_buildsystem.rst index e19ed0ba4c3..2b01c0f8a59 100644 --- a/contributing/development/compiling/introduction_to_the_buildsystem.rst +++ b/contributing/development/compiling/introduction_to_the_buildsystem.rst @@ -446,10 +446,14 @@ platform: windows_debug_x86_32.exe windows_debug_x86_64_console.exe windows_debug_x86_64.exe + windows_debug_arm64_console.exe + windows_debug_arm64.exe windows_release_x86_32_console.exe windows_release_x86_32.exe windows_release_x86_64_console.exe windows_release_x86_64.exe + windows_release_arm64_console.exe + windows_release_arm64.exe To create those yourself, follow the instructions detailed for each platform in this same tutorial section. Each platform explains how to diff --git a/contributing/development/core_and_modules/unit_testing.rst b/contributing/development/core_and_modules/unit_testing.rst index b6de4085ff7..ebf2d2c008b 100644 --- a/contributing/development/core_and_modules/unit_testing.rst +++ b/contributing/development/core_and_modules/unit_testing.rst @@ -152,6 +152,26 @@ common test data for each test, or writing parameterized tests. Godot supports writing tests per C++ module. For instructions on how to write module tests, refer to :ref:`doc_custom_module_unit_tests`. +Subcases +~~~~~~~~ + +In situations where you have a common setup for several test cases with only slight variations, subcases can be very helpful. Here's an example: + +.. code-block:: cpp + + TEST_CASE("[SceneTree][Node] Testing node operations with a very simple scene tree") { + // ... common setup (e.g. creating a scene tree with a few nodes) + SUBCASE("Move node to specific index") { + // ... setup and checks for moving a node + } + SUBCASE("Remove node at specific index") { + // ... setup and checks for removing a node + } + } + +Each ``SUBCASE`` causes the ``TEST_CASE`` to be executed from the beginning. +Subcases can be nested to an arbitrary depth, but it is advised to limit nesting to no more than one level deep. + Assertions ~~~~~~~~~~ @@ -240,6 +260,25 @@ the engine, for instance: "Invalid HTML notation should result in a Color with the default values."); } +Special tags in test case names +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These tags can be added to the test case name to modify or extend the test environment: + ++-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| **Tag** | **Description** | ++-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[SceneTree]`` | Required for test cases that rely on a scene tree with MessageQueue to be available. It also enables a mock rendering server and :ref:`ThemeDB`. | ++-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[Editor]`` | Like ``[SceneTree]``, but with additional editor-related infrastructure available, such as :ref:`EditorSettings`. | ++-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[Audio]`` | Initializes the :ref:`AudioServer` using a mock audio driver. | ++-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[Navigation]`` | Creates the default 2D/3D navigation servers and makes them available for testing. | ++-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +You can use them together to combine multiple test environment extensions. + Test tools ---------- diff --git a/contributing/development/file_formats/tscn.rst b/contributing/development/file_formats/tscn.rst index f2137ae725b..2bf92943719 100644 --- a/contributing/development/file_formats/tscn.rst +++ b/contributing/development/file_formats/tscn.rst @@ -193,7 +193,7 @@ For example, the ``skeleton`` property in the MeshInstance3D node called Skeleton3D ~~~~~~~~~~ -The :ref:`class_Skeleton3D` node inherits the Node3D node, but may alsohave a +The :ref:`class_Skeleton3D` node inherits the Node3D node, but may also have a list of bones described in key-value pairs in the format ``bones// = value``. The bone attributes consist of: diff --git a/contributing/documentation/docs_image_guidelines.rst b/contributing/documentation/docs_image_guidelines.rst index 7ada5455a79..1e32ea765a9 100644 --- a/contributing/documentation/docs_image_guidelines.rst +++ b/contributing/documentation/docs_image_guidelines.rst @@ -67,7 +67,7 @@ have cropping built in it's not always easy to get something precise. And while Krita is designed as a painting program the cropping tool gives you pixel precision by default. Of course, feel free to use a different program you are familiar with. -If you've never used Krita before download it from the `official Krita website `_, +If you've never used Krita before download it from the `official Krita website `_, on Linux you may also be able to download it from your distributions repository, flathub is also an option. Once it's installed on your computer open Krita then open the image you want to crop. This button on the left panel is the crop tool. diff --git a/contributing/how_to_contribute.rst b/contributing/how_to_contribute.rst new file mode 100644 index 00000000000..fd8c61f3083 --- /dev/null +++ b/contributing/how_to_contribute.rst @@ -0,0 +1,110 @@ +.. _doc_ways_to_contribute: + +How to contribute +================= + +The Godot Engine is free and open-source. Like any community-driven project, we rely on volunteer contributions. +On this page we want to showcase the various ways you as users can participate - to help you find the right starting place with the skillset you have. +Because contrary to popular opinion, we need more than just programmers on the project! + + +Fundraising +----------- + +- **Donate** + + We created the non-profit `Godot Foundation `_ to be able to support the Godot Engine in both matters of finance and administration. + In practice, this means the Foundation hires people to work part-time or full-time on the project. + These jobs include engine development as well as related tasks like code reviews, production management, community & marketing efforts, and more. + + With as little as 5 EUR per month, you can help us keep going strong. + Currently, we are intending to hire more core developers, as to cover more ground with full-time specialists that supplement and guide volunteer work. + + `Join the Development Fund `_ + +- **Donation Drives** + Think about your followers on social media, or other communities you are active in. + Use that reach to remind your social environment that even small contributions can make a difference, especially when done by a great number of people at the same time. + + Are you a content creator? Consider adding a link to the `Godot Development Fund `_ to your descriptions. + If you do live streams, perhaps think about organizing a stream with donation incentives. + +.. - **Buy Official Merch** + +- **Publish Godot Games.** + You heard right, simply publishing a game #MadeWithGodot can positively impact the well-being of this project. + Your personal success elevates the engine to a viable alternative for other developers, growing the community further. + Additionally, it opens the doors for us to approach industry contacts about possible cooperations. + + +Technical contributions +----------------------- + +- **Report bugs & other issues** + As active users of the engine, you are better equipped to identify bugs and other issues than anyone else. + To let us know about your findings, fill out this `bug report form `_ on our GitHub. + Make sure to include as much information as possible to ensure these issues can easily be reproduced by others. + + If you are interested in helping keep our bug tracker organized, you can even join the `bugsquad `_! + +- **Test Development Versions** + While it is recommended to use the stable releases for your projects, you can help us test dev releases, betas, and release candidates + by opening a copy of your project in them and checking what problems this introduces or maybe even solves. + Make sure to have a backup ready, since this can produce irreversible changes. + + Find recent `development versions `_ directly on our download page, or linked in their own blog posts. + +- **Contribute Engine Code (mainly C++)** + The engine development is mainly coordinated on our `Contributor RocketChat `_, + so if you are serious about making PRs you should join us there! + + Read more about the **technical submission process**: :ref:`doc_first_steps` + + For each subject area of the engine, there is a corresponding team to coordinate the work. + Join the linked chat to get more eyes on your related PR, learn about open todos, or partake in meetings. + For some areas, specialists might even be encouraged to step up as maintainer! + `List of teams `_ + +- **Review Code Contributions** + All pull requests need to be thoroughly reviewed before they can be merged into the master branch. + Help us get a headstart by participating in the code review process. + + To get started, chose any `open pull request `_ and reference our **style guide**: :ref:`doc_pr_review_guidelines` + +- **Write Plugins (GDScript, C#, & more)** + Community addons are not directly included in the core engine download or repository, yet they provide essential quality of life upgrades for your fellow game developers. + Upload your plugins to the `Godot Asset Library `_ to make them available to others. + .. update to talk about Asset Store later + +- **Demo projects (GDScript, C#, and making Assets)** + We provide new users with `demo projects `_ so they can quickly test new features or get familiar with the engine in the first place. + At industry events, we might even exhibit these demo projects to showcase what Godot can do! + Help improve existing projects or supply your own to be added to the pool, and join the `demo channel `_ in the Contributor RocketChat to talk about it. + +- **Documentation** + The documentation is one of the most essential parts of any tech project, yet the need to document new features and substantial changes often gets overlooked. + Join the `documentation team `_ to improve the Godot Engine with your technical writing skills. + +- **Translations (spoken languages other than English)** + Are you interested in making the Godot Engine more accessible to non-English speakers? + Contribute to our `community-translations `_. + +Community support +----------------- + +- **Call for Moderators** + With a community of our size, we need people to step up as volunteer moderators in all kinds of places. + These teams are organized by the Godot Foundation, but would not function without the dedication of active community members like you. + + Have a look around your favorite community platform and you might come across open application calls. + +- **Answer tech-support questions** + With many new people discovering the Godot Engine recently, the need for peer-to-peer tech-support has never been greater. + Be it on the `Forum `_, our `subreddit `_, or on `Discord `_, you can always brighten someone's day by helping them get their personal projects back on track. + +- **Create tutorials & more** + How did you get started with the Godot Engine? + Chances are you looked for learning materials outside of what the documentation provides. + Without content creators covering the game development process, there would not be this big of a community today. + Therefore it seemed only right to mention them in a page about important contributions to the project. + diff --git a/contributing/ways_to_contribute.rst b/contributing/workflow/first_steps.rst similarity index 69% rename from contributing/ways_to_contribute.rst rename to contributing/workflow/first_steps.rst index 13943009bc0..ef9c77d54e5 100644 --- a/contributing/ways_to_contribute.rst +++ b/contributing/workflow/first_steps.rst @@ -1,54 +1,4 @@ -.. _doc_ways_to_contribute: - -Ways to contribute -================== - -Godot Engine is a non-profit, community-driven free and open source project. -Almost all (but our lead dev Juan, more on that below) developers are working -*pro bono* on their free time, out of personal interest and for the love of -creating a libre engine of exceptional quality. - -This means that to thrive, Godot needs as many users as possible to get -involved by contributing to the engine. There are many ways to contribute to -such a big project, making it possible for everybody to bring something -positive to the engine, regardless of their skill set: - -- **Be part of the community.** The best way to contribute to Godot and help - it become ever better is simply to use the engine and promote it by - word-of-mouth, in the credits or splash screen of your games, blog posts, tutorials, - videos, demos, gamedev or free software events, support on the Q&A, forums, - Contributors Chat, Discord, etc. Participate! - Being a user and advocate helps spread the word about our great engine, - which has no marketing budget and can therefore only rely on its community - to become more mainstream. - -- **Make games.** It's no secret that, to convince new users and especially the - industry at large that Godot is a relevant market player, we need great games - made with Godot. We know that the engine has a lot of potential, both for 2D - and 3D games, but given its young age we still lack big releases that will - draw attention to Godot. So keep working on your awesome projects, each new - game increases our credibility on the gamedev market! - -- **Get involved in the engine's development.** This can be by contributing - code via pull requests, testing the development snapshots or directly the - git *master* branch, report bugs or suggest enhancements on the issue - tracker, improve the official documentation (both the class reference and - tutorials) and its translations. - The following sections will cover each of those "direct" ways - of contributing to the engine. - -- **Donate.** Godot is a non-profit project, but it can still benefit from - user donations for many things. Apart from usual expenses such as hosting - costs or promotional material on events, we also use donation money to - acquire hardware when necessary (e.g. we used donation money to buy a - MacBook Pro to implement Retina/HiDPI support and various other - macOS-related features). - Most importantly, we also used donation money to hire core developers so they - can work full-time on the engine. Even with a low - monthly wage, we need a steady donation income to continue doing this, which - has been very beneficial to the project so far. So if you want to donate - some money to the project, check `our website `_ - for details. +.. _doc_first_steps: Contributing code ----------------- diff --git a/contributing/workflow/index.rst b/contributing/workflow/index.rst index 0c6e451e6d9..039f9adb06b 100644 --- a/contributing/workflow/index.rst +++ b/contributing/workflow/index.rst @@ -14,6 +14,7 @@ approach the project. :maxdepth: 1 :name: toc-contributing-workflow + first_steps bisecting_regressions bug_triage_guidelines pr_workflow diff --git a/getting_started/first_2d_game/06.heads_up_display.rst b/getting_started/first_2d_game/06.heads_up_display.rst index abda7b816a6..f02f3ae7258 100644 --- a/getting_started/first_2d_game/06.heads_up_display.rst +++ b/getting_started/first_2d_game/06.heads_up_display.rst @@ -273,8 +273,7 @@ with the changing score: ``_ready()`` if you haven't already, otherwise your game will start automatically. -Now you're ready to play! Click the "Play the Project" button. You will be asked -to select a main scene, so choose ``main.tscn``. +Now you're ready to play! Click the "Play the Project" button. Removing old creeps ~~~~~~~~~~~~~~~~~~~ diff --git a/getting_started/first_3d_game/01.game_setup.rst b/getting_started/first_3d_game/01.game_setup.rst index 594435409db..2ebc78d3164 100644 --- a/getting_started/first_3d_game/01.game_setup.rst +++ b/getting_started/first_3d_game/01.game_setup.rst @@ -27,6 +27,11 @@ Click *Import & Edit* to open the project in the editor. .. image:: img/01.game_setup/03.import_and_edit.webp +A window notifying you that the project was generated by an older Godot version may appear. +Click *Convert Full Project* to convert the project to your current Godot version. + +.. image:: img/01.game_setup/import_project_to_4.x_prompt.webp + The start project contains an icon and two folders: ``art/`` and ``fonts/``. There, you will find the art assets and music we'll use in the game. @@ -41,11 +46,11 @@ Setting up the playable area We're going to create our main scene with a plain :ref:`Node ` as its root. In the *Scene* dock, click the *Add Child Node* button represented by a "+" icon in the top-left and double-click on *Node*. Name the node ``Main``. An alternate method to rename the node is to right-click on *Node* and choose *Rename* (or :kbd:`F2`). Alternatively, to add -a node to the scene, you can press :kbd:`Ctrl + a` (or :kbd:`Cmd + a` on macOS). +a node to the scene, you can press :kbd:`Ctrl + A` (:kbd:`Cmd + A` on macOS). .. image:: img/01.game_setup/05.main_node.png -Save the scene as ``main.tscn`` by pressing :kbd:`Ctrl + s` (:kbd:`Cmd + s` on macOS). +Save the scene as ``main.tscn`` by pressing :kbd:`Ctrl + S` (:kbd:`Cmd + S` on macOS). We'll start by adding a floor that'll prevent the characters from falling. To create static colliders like the floor, walls, or ceilings, you can use :ref:`StaticBody3D ` nodes. They require :ref:`CollisionShape3D ` child nodes to @@ -74,8 +79,8 @@ reliable to block even fast-moving objects. A box's wireframe appears in the viewport with three orange dots. You can click and drag these to edit the shape's extents interactively. We can also precisely set the size in the inspector. Click on the :ref:`BoxShape3D ` to expand the resource. -Set its *Size* to ``60`` on the X axis, ``2`` for the Y axis, and ``60`` for -the Z axis. +Set its *Size* to ``60`` on the X-axis, ``2`` for the Y-axis, and ``60`` for +the Z-axis. .. image:: img/01.game_setup/09.box_size.webp @@ -98,9 +103,14 @@ resource and set its *Size* to ``60``, ``2``, and ``60``. You should see a wide grey slab that covers the grid and blue and red axes in the viewport. -We're going to move the ground down so we can see the floor grid. Select the -``Ground`` node, hold the :kbd:`Ctrl` key down to turn on grid snapping, -and click and drag down on the Y axis. It's the green arrow in the move gizmo. +We're going to move the ground down so we can see the floor grid. To do this, the grid snapping feature can be used. +Grid snapping can be activated 2 ways in the 3D editor. +The first is by pressing the *Use Snap* button (or pressing the :kbd:`Y` key). +The second is by selecting a node, dragging a handle on the gizmo **then** holding :kbd:`Ctrl` while still clicking to enable snapping as long as :kbd:`Ctrl` is held. + +.. image:: img/01.game_setup/use_snap.webp + +Start by setting snapping with your preferred method. Then move the ``Ground`` node using the Y-axis (the green arrow on the gizmo). .. image:: img/01.game_setup/move_gizmo_y_axis.webp @@ -133,7 +143,7 @@ node and add a child node :ref:`DirectionalLight3D `. We need to move and rotate the :ref:`DirectionalLight3D ` node. Move it up by clicking and dragging on the manipulator's green arrow -and click and drag on the red arc to rotate it around the X axis, until the +and click and drag on the red arc to rotate it around the X-axis, until the ground is lit. In the *Inspector*, turn on *Shadow -> Enabled* by clicking the checkbox. diff --git a/getting_started/first_3d_game/03.player_movement_code.rst b/getting_started/first_3d_game/03.player_movement_code.rst index 6f4a0d02451..29d0989b181 100644 --- a/getting_started/first_3d_game/03.player_movement_code.rst +++ b/getting_started/first_3d_game/03.player_movement_code.rst @@ -246,7 +246,7 @@ smooth it out for you. It uses the *velocity* value native to the :ref:`Characte And that's all the code you need to move the character on the floor. -Here is the complete ``Player.gd`` code for reference. +Here is the complete ``player.gd`` code for reference. .. tabs:: .. code-tab:: gdscript GDScript diff --git a/getting_started/first_3d_game/04.mob_scene.rst b/getting_started/first_3d_game/04.mob_scene.rst index a96f71d3490..5cc089a9d22 100644 --- a/getting_started/first_3d_game/04.mob_scene.rst +++ b/getting_started/first_3d_game/04.mob_scene.rst @@ -252,7 +252,7 @@ method. This function destroys the instance it's called on. Our monster is ready to enter the game! In the next part, you will spawn monsters in the game level. -Here is the complete ``Mob.gd`` script for reference. +Here is the complete ``mob.gd`` script for reference. .. tabs:: .. code-tab:: gdscript GDScript diff --git a/getting_started/first_3d_game/06.jump_and_squash.rst b/getting_started/first_3d_game/06.jump_and_squash.rst index 9a451c9ccf4..cc2d6c07bc7 100644 --- a/getting_started/first_3d_game/06.jump_and_squash.rst +++ b/getting_started/first_3d_game/06.jump_and_squash.rst @@ -318,7 +318,7 @@ such as counting the score multiple times for one kill. We are calling one undefined function, ``mob.squash()``, so we have to add it to the Mob class. -Open the script ``Mob.gd`` by double-clicking on it in the *FileSystem* dock. At +Open the script ``mob.gd`` by double-clicking on it in the *FileSystem* dock. At the top of the script, we want to define a new signal named ``squashed``. And at the bottom, you can add the squash function, where we emit the signal and destroy the mob. diff --git a/getting_started/first_3d_game/07.killing_player.rst b/getting_started/first_3d_game/07.killing_player.rst index d1fd101b8ec..74b22d246b1 100644 --- a/getting_started/first_3d_game/07.killing_player.rst +++ b/getting_started/first_3d_game/07.killing_player.rst @@ -213,7 +213,7 @@ Starting with ``main.gd``. } } -Next is ``Mob.gd``. +Next is ``mob.gd``. .. tabs:: .. code-tab:: gdscript GDScript @@ -308,7 +308,7 @@ Next is ``Mob.gd``. } } -Finally, the longest script, ``Player.gd``: +Finally, the longest script, ``player.gd``: .. tabs:: .. code-tab:: gdscript GDScript diff --git a/getting_started/first_3d_game/08.score_and_replay.rst b/getting_started/first_3d_game/08.score_and_replay.rst index 0037e6447cb..7c97ddfec3f 100644 --- a/getting_started/first_3d_game/08.score_and_replay.rst +++ b/getting_started/first_3d_game/08.score_and_replay.rst @@ -131,7 +131,7 @@ line: This line means that when the mob emits the ``squashed`` signal, the ``ScoreLabel`` node will receive it and call the function ``_on_mob_squashed()``. -Head back to the ``ScoreLabel.gd`` script to define the ``_on_mob_squashed()`` +Head back to the ``score_label.gd`` script to define the ``_on_mob_squashed()`` callback function. There, we increment the score and update the displayed text. @@ -321,18 +321,18 @@ game. |image17| -Save the scene as ``MusicPlayer.tscn``. +Save the scene as ``music_player.tscn``. We have to register it as an autoload. Head to the *Project -> Project Settings…* menu and click on the *Autoload* tab. In the *Path* field, you want to enter the path to your scene. Click the folder -icon to open the file browser and double-click on ``MusicPlayer.tscn``. Then, +icon to open the file browser and double-click on ``music_player.tscn``. Then, click the *Add* button on the right to register the node. |image18| -``MusicPlayer.tscn`` now loads into any scene you open or play. +``music_player.tscn`` now loads into any scene you open or play. So if you run the game now, the music will play automatically in any scene. Before we wrap up this lesson, here's a quick look at how it works under the diff --git a/getting_started/first_3d_game/09.adding_animations.rst b/getting_started/first_3d_game/09.adding_animations.rst index 6f3b602ba59..38ae7f8aa02 100644 --- a/getting_started/first_3d_game/09.adding_animations.rst +++ b/getting_started/first_3d_game/09.adding_animations.rst @@ -298,8 +298,8 @@ And with that, you finished coding your first complete 3D game. **Congratulations**! In the next part, we'll quickly recap what you learned and give you some links -to keep learning more. But for now, here are the complete ``Player.gd`` and -``Mob.gd`` so you can check your code against them. +to keep learning more. But for now, here are the complete ``player.gd`` and +``mob.gd`` so you can check your code against them. Here's the *Player* script. diff --git a/getting_started/first_3d_game/img/01.game_setup/import_project_to_4.x_prompt.webp b/getting_started/first_3d_game/img/01.game_setup/import_project_to_4.x_prompt.webp new file mode 100644 index 00000000000..a38e0652d09 Binary files /dev/null and b/getting_started/first_3d_game/img/01.game_setup/import_project_to_4.x_prompt.webp differ diff --git a/getting_started/first_3d_game/img/01.game_setup/use_snap.webp b/getting_started/first_3d_game/img/01.game_setup/use_snap.webp new file mode 100644 index 00000000000..008fcdadba3 Binary files /dev/null and b/getting_started/first_3d_game/img/01.game_setup/use_snap.webp differ diff --git a/getting_started/introduction/first_look_at_the_editor.rst b/getting_started/introduction/first_look_at_the_editor.rst index e7db0b99272..c74b81311a2 100644 --- a/getting_started/introduction/first_look_at_the_editor.rst +++ b/getting_started/introduction/first_look_at_the_editor.rst @@ -6,104 +6,122 @@ .. _doc_intro_to_the_editor_interface: -First look at Godot's editor -============================ +First look at Godot's interface +=============================== This page will give you a brief overview of Godot's interface. We're going to look at the different main screens and docks to help you situate yourself. .. seealso:: For a comprehensive breakdown of the editor's interface and how to - use it, see the :ref:`Editor manual `. + use it, see the :ref:`Editor manual `. The Project Manager ------------------- When you launch Godot, the first window you see is the Project Manager. In the -default tab **Local Projects**, you can manage existing projects, import or create new +default tab **Projects**, you can manage existing projects, import or create new ones, and more. .. image:: img/editor_intro_project_manager.webp -At the top of the window, there is another tab named "Asset Library Projects". The first -time you go to this tab you'll see a "Go Online" button. For privacy reasons the Godot +At the top of the window, there is another tab named **Asset Library**. The first +time you go to this tab you'll see a "Go Online" button. For privacy reasons, the Godot project manager does not access the internet by default. To change this click -the "Go Online button", if you want to change your network mode back to "offline" you -can do so from the project manager settings. - -Once your network mode is set to "online" you can search for demo projects in the open -source asset library, which includes many projects developed by the community. +the "Go Online" button. You can change this option later in the settings. -.. seealso:: To learn the Project Manager's ins and outs, read - :ref:`doc_project_manager`. +Once your network mode is set to "online", you can search for demo projects in the open +source asset library, which includes many projects developed by the community: .. image:: img/editor_intro_project_templates.webp -You can also change the editor's language by going into the settings menu. +The Project Manager's settings can be opened using the **Settings** menu: .. image:: img/editor_intro_settings.webp -From here use the language drop down menu to select your language. By default, it is in -English (EN). +From here, you can change the editor's language (default is the system language), interface theme, display +scale, network mode, and also the directory naming convention. + +.. seealso:: To learn the Project Manager's ins and outs, read + :ref:`doc_project_manager`. -.. image:: img/editor_intro_language.webp First look at Godot's editor ---------------------------- When you open a new or an existing project, the editor's interface appears. -Let's look at its main areas. +Let's look at its main areas: .. image:: img/editor_intro_editor_empty.webp -By default, it features **menus**, **main screens**, and playtest buttons along -the window's top edge. +By default, along the window's top edge, it features **main menu** on the left, **workspace** switching +buttons in the center (active workspace is highlighted), and **playtest** buttons on the right: .. image:: img/editor_intro_top_menus.webp -In the center is the **viewport** with its **toolbar** at the top, where you'll -find tools to move, scale, or lock the scene's nodes. +Just below the workspace buttons, the opened :ref:`scenes ` +as tabs are seen. The plus (+) button right next to the tabs will add a new scene to the project. +With the button on the far right, distraction-free mode can be toggled, which maximizes or restores +the **viewport**'s size by hiding **docks** in the interface: -.. image:: img/editor_intro_3d_viewport.webp +.. image:: img/editor_intro_scene_selector.webp -On either side of the viewport sit the **docks**. And at the bottom of the -window lies the **bottom panel**. +In the center, below the scene selector is the **viewport** with its **toolbar** at the top, where you'll +find different tools to move, scale, or lock the scene's nodes (currently the 3D workspace is active): + +.. image:: img/editor_intro_3d_viewport.webp -The toolbar changes based on the context and selected node. Here is the 2D toolbar. +This toolbar changes based on the context and selected node. Here is the 2D toolbar: .. image:: img/editor_intro_toolbar_2d.webp -Below is the 3D one. +Below is the 3D one: .. image:: img/editor_intro_toolbar_3d.webp +.. seealso:: To learn more on workspaces, read :ref:`doc_intro_to_the_editor_interface_four_screens`. + +.. seealso:: To learn more on the 3D viewport and 3D in general, read :ref:`doc_introduction_to_3d`. + +On either side of the viewport sit the **docks**. And at the bottom of the +window lies the **bottom panel**. + Let's look at the docks. The **FileSystem** dock lists your project files, including -scripts, images, audio samples, and more. +scripts, images, audio samples, and more: .. image:: img/editor_intro_filesystem_dock.webp -The **Scene** dock lists the active scene's nodes. +The **Scene** dock lists the active scene's nodes: .. image:: img/editor_intro_scene_dock.webp -The **Inspector** allows you to edit the properties of a selected node. +The **Inspector** allows you to edit the properties of a selected node: .. image:: img/editor_intro_inspector_dock.webp +.. seealso:: To read more on inspector, see :ref:`doc_editor_inspector_dock`. + +.. seealso:: Docks can be customized. Read more on :ref:`doc_customizing_editor_moving_docks`. + The **bottom panel**, situated below the viewport, is the host for the debug console, the animation editor, the audio mixer, and more. They can take precious -space, that's why they're folded by default. +space, that's why they're folded by default: .. image:: img/editor_intro_bottom_panels.webp -When you click on one, it expands vertically. Below, you can see the animation editor opened. +When you click on one, it expands vertically. Below, you can see the animation editor opened: .. image:: img/editor_intro_bottom_panel_animation.webp +Bottom panels can also be shown or hidden using the shortcuts defined in +**Editor Settings > Shortcuts**, under the **Bottom Panels** category. + +.. _doc_intro_to_the_editor_interface_four_screens: + The four main screens --------------------- There are four main screen buttons centered at the top of the editor: -2D, 3D, Script, and AssetLib. +2D, 3D, Script, and Asset Library. You'll use the **2D screen** for all types of games. In addition to 2D games, the 2D screen is where you'll build your interfaces. @@ -115,11 +133,6 @@ In the **3D screen**, you can work with meshes, lights, and design levels for .. image:: img/editor_intro_workspace_3d.webp -Notice the perspective button under the toolbar. Clicking on it opens a list of -options related to the 3D view. - -.. image:: img/editor_intro_3d_viewport_perspective.webp - .. note:: Read :ref:`doc_introduction_to_3d` for more detail about the **3D main screen**. @@ -128,7 +141,7 @@ auto-completion, and built-in code reference. .. image:: img/editor_intro_workspace_script.webp -Finally, the **AssetLib** is a library of free and open source add-ons, scripts, +Finally, the **Asset Library** is a library of free and open source add-ons, scripts, and assets to use in your projects. .. image:: img/editor_intro_workspace_assetlib.webp @@ -144,13 +157,13 @@ Godot comes with a built-in class reference. You can search for information about a class, method, property, constant, or signal by any one of the following methods: -* Pressing :kbd:`F1` (or :kbd:`Opt + Space` on macOS, or :kbd:`fn + F1` for laptops with a :kbd:`fn` key) anywhere in the editor. +* Pressing :kbd:`F1` (or :kbd:`Opt + Space` on macOS, or :kbd:`Fn + F1` for laptops + with a :kbd:`Fn` key) anywhere in the editor. * Clicking the "Search Help" button in the top-right of the Script main screen. * Clicking on the Help menu and Search Help. -* Clicking while pressing the :kbd:`Ctrl` key on a class name, function name, +* :kbd:`Ctrl + Click` (:kbd:`Cmd + Click` on macOS) on a class name, function name, or built-in variable in the script editor. - .. image:: img/editor_intro_search_help_button.webp When you do any of these, a window pops up. Type to search for any item. You can @@ -161,3 +174,11 @@ also use it to browse available objects and methods. Double-click on an item to open the corresponding page in the script main screen. .. image:: img/editor_intro_help_class_animated_sprite.webp + +Alternatively, + +* Clicking while pressing the :kbd:`Ctrl` key on a class name, function name, + or built-in variable in the script editor. +* Right-clicking on nodes and choosing **Open Documentation** or choosing **Lookup Symbol** + for elements in script editor will directly open their documentation. + diff --git a/getting_started/introduction/godot_design_philosophy.rst b/getting_started/introduction/godot_design_philosophy.rst index df307079ad2..a6aff397ef5 100644 --- a/getting_started/introduction/godot_design_philosophy.rst +++ b/getting_started/introduction/godot_design_philosophy.rst @@ -17,7 +17,7 @@ your project, you need to try it out for yourself and understand its design and limitations. Please watch -`Godot explained in 5 minutes `_ +`Godot explained in 7 minutes `_ if you're looking for an overview of the engine's features. Object-oriented design and composition diff --git a/getting_started/introduction/img/editor_intro_3d_viewport.webp b/getting_started/introduction/img/editor_intro_3d_viewport.webp index d0f517b835c..7e5e0bdfd15 100644 Binary files a/getting_started/introduction/img/editor_intro_3d_viewport.webp and b/getting_started/introduction/img/editor_intro_3d_viewport.webp differ diff --git a/getting_started/introduction/img/editor_intro_3d_viewport_perspective.webp b/getting_started/introduction/img/editor_intro_3d_viewport_perspective.webp deleted file mode 100644 index 9c6113309e0..00000000000 Binary files a/getting_started/introduction/img/editor_intro_3d_viewport_perspective.webp and /dev/null differ diff --git a/getting_started/introduction/img/editor_intro_language.webp b/getting_started/introduction/img/editor_intro_language.webp deleted file mode 100644 index 0a80a704fb6..00000000000 Binary files a/getting_started/introduction/img/editor_intro_language.webp and /dev/null differ diff --git a/getting_started/introduction/img/editor_intro_scene_selector.webp b/getting_started/introduction/img/editor_intro_scene_selector.webp new file mode 100644 index 00000000000..4f867dc74d3 Binary files /dev/null and b/getting_started/introduction/img/editor_intro_scene_selector.webp differ diff --git a/getting_started/introduction/key_concepts_overview.rst b/getting_started/introduction/key_concepts_overview.rst index d91ef2e110e..24e525ddc27 100644 --- a/getting_started/introduction/key_concepts_overview.rst +++ b/getting_started/introduction/key_concepts_overview.rst @@ -16,6 +16,8 @@ These are the four concepts you will learn here. We're going to look at them briefly to give you a sense of how the engine works. In the getting started series, you will get to use them in practice. +.. _doc_key_concepts_overview_scenes: + Scenes ------ diff --git a/getting_started/introduction/learning_new_features.rst b/getting_started/introduction/learning_new_features.rst index b6802b6b186..cae20a23b6c 100644 --- a/getting_started/introduction/learning_new_features.rst +++ b/getting_started/introduction/learning_new_features.rst @@ -56,8 +56,8 @@ A class reference's page tells you: `_ GitHub repository to report it. -You can Ctrl-click (Cmd-click on MacOS) any underlined text like the name of a class, property, -method, signal, or constant to jump to it. +You can hold :kbd:`Ctrl` (macOS :kbd:`Cmd`) and then mouseover text like the name of a class, property, +method, signal, or constant to underline it, then :kbd:`Ctrl + Click` (macOS :kbd:`Cmd + Click`) it to jump to it. Learning to think like a programmer ----------------------------------- @@ -121,10 +121,11 @@ information: Also, please don't take a picture with your phone, the low quality and screen reflections can make it hard to understand the image. Your operating system should have a built-in tool to take screenshots with the :kbd:`PrtSc` (Print - Screen) key. + Screen) key (macOS: use :kbd:`Cmd + Shift + 3` for a full screen shot, + `more information here `_). Alternatively, you can use a program like `ShareX `_ - on Windows or `FlameShot `_ on Linux. + on Windows, or `FlameShot `_ on Linux. 5. Sharing a video of your running game can also be really **useful to troubleshoot your game**. You can use programs like `OBS Studio diff --git a/getting_started/step_by_step/img/instancing_ball_scene_open.webp b/getting_started/step_by_step/img/instancing_ball_scene_open.webp new file mode 100644 index 00000000000..3c003a7d5bf Binary files /dev/null and b/getting_started/step_by_step/img/instancing_ball_scene_open.webp differ diff --git a/getting_started/step_by_step/instancing.rst b/getting_started/step_by_step/instancing.rst index 91bfcba84ab..fce49061d1a 100644 --- a/getting_started/step_by_step/instancing.rst +++ b/getting_started/step_by_step/instancing.rst @@ -58,6 +58,9 @@ Finally, click the Import & Edit button. .. image:: img/instancing_import_and_edit_button.webp +A window notifying you that the project was last opened in an older Godot version +may appear, that's not an issue. Click *Ok* to open the project. + The project contains two packed scenes: ``main.tscn``, containing walls against which the ball collides, and ``ball.tscn``. The Main scene should open automatically. If you're seeing an empty 3D scene instead of the main scene, click the 2D button at the top of the screen. @@ -114,8 +117,12 @@ There is more to instances. With this feature, you can: .. note:: Changing a property on an instance always overrides values from the corresponding packed scene. -Let's try this. Open ``ball.tscn`` and select the Ball node. In the Inspector on -the right, click on the PhysicsMaterial property to expand it. +Let's try this. Double-click ``ball.tscn`` in the FileSystem to open it. + +.. image:: img/instancing_ball_scene_open.webp + +Select the Ball node. In the Inspector on the right, click on the PhysicsMaterial +property to expand it. .. image:: img/instancing_physics_material_expand.webp diff --git a/getting_started/step_by_step/scripting_first_script.rst b/getting_started/step_by_step/scripting_first_script.rst index 66e2129990c..9c2bcc9a880 100644 --- a/getting_started/step_by_step/scripting_first_script.rst +++ b/getting_started/step_by_step/scripting_first_script.rst @@ -101,7 +101,8 @@ the following line of code: .. code-tab:: csharp C# using Godot; - + using System; + public partial class MySprite2D : Sprite2D { } @@ -327,7 +328,8 @@ Here is the complete ``sprite_2d.gd`` file for reference. .. code-tab:: csharp C# using Godot; - + using System; + public partial class MySprite2D : Sprite2D { private int _speed = 400; diff --git a/getting_started/step_by_step/signals.rst b/getting_started/step_by_step/signals.rst index e3086e27346..5a0e512632f 100644 --- a/getting_started/step_by_step/signals.rst +++ b/getting_started/step_by_step/signals.rst @@ -25,9 +25,17 @@ For example, you might have a life bar on the screen that represents the player's health. When the player takes damage or uses a healing potion, you want the bar to reflect the change. To do so, in Godot, you would use signals. -.. note:: As mentioned in the introduction, signals are Godot's version of the - observer pattern. You can learn more about it here: - https://gameprogrammingpatterns.com/observer.html +Like methods (:ref:`class_callable`), signals are a first-class type since Godot +4.0. This means you can pass them around as method arguments directly without +having to pass them as strings, which allows for better autocompletion and is +less error-prone. See the :ref:`class_signal` class reference for a list of +what you can do with the Signal type directly. + +.. seealso:: + + As mentioned in the introduction, signals are Godot's version of the + observer pattern. You can learn more about it in + `Game Programming Patterns `__. We will now use a signal to make our Godot icon from the previous lesson (:ref:`doc_scripting_player_input`) move and stop by pressing a button. @@ -43,8 +51,6 @@ We will now use a signal to make our Godot icon from the previous lesson camelCase (See :ref:`doc_c_sharp_styleguide`). Be careful to type the method names precisely when connecting signals. -.. Example - Scene setup ----------- @@ -139,10 +145,10 @@ methods "_on_node_name_signal_name". Here, it'll be "_on_button_pressed". toggle the mode in the window's bottom-right by clicking the Advanced button. -.. note:: +.. note:: - If you are using an external editor (such as VS Code) this - automatic code generation might not work. In this case you need to to connect + If you are using an external editor (such as VS Code) this + automatic code generation might not work. In this case you need to to connect the signal via code as explained in the next section. Click the Connect button to complete the signal connection and jump to the diff --git a/img/color_constants.png b/img/color_constants.png index 01e7486f296..a3b6f8074ab 100644 Binary files a/img/color_constants.png and b/img/color_constants.png differ diff --git a/index.rst b/index.rst index be996cba034..1615a93af51 100644 --- a/index.rst +++ b/index.rst @@ -131,7 +131,7 @@ the ``GodotEngine.epub`` file in an e-book reader application. :caption: Contributing :name: sec-contributing - contributing/ways_to_contribute + contributing/how_to_contribute contributing/workflow/index contributing/development/index contributing/documentation/index diff --git a/tutorials/2d/2d_lights_and_shadows.rst b/tutorials/2d/2d_lights_and_shadows.rst index e7f4d193ae3..848c00d8c4a 100644 --- a/tutorials/2d/2d_lights_and_shadows.rst +++ b/tutorials/2d/2d_lights_and_shadows.rst @@ -38,7 +38,7 @@ There are several nodes involved in a complete 2D lighting setup: - :ref:`PointLight2D ` (for omnidirectional or spot lights) - :ref:`DirectionalLight2D ` (for sunlight or moonlight) - :ref:`LightOccluder2D ` (for light shadow casters) -- Other 2D nodes that receive lighting, such as Sprite2D or TileMap. +- Other 2D nodes that receive lighting, such as Sprite2D or TileMapLayer. :ref:`CanvasModulate ` is used to darken the scene by specifying a color that will act as the base "ambient" color. This is the final @@ -55,7 +55,7 @@ to simulate lighting. :ref:`LightOccluder2Ds ` are used to tell the shader which parts of the scene cast shadows. These occluders can be placed as -independent nodes or can be part of a TileMap node. +independent nodes or can be part of a TileMapLayer node. The shadows appear only on areas covered by the :ref:`PointLight2D ` and their direction is based on the center of the diff --git a/tutorials/2d/2d_parallax.rst b/tutorials/2d/2d_parallax.rst new file mode 100644 index 00000000000..5702a89f1cb --- /dev/null +++ b/tutorials/2d/2d_parallax.rst @@ -0,0 +1,231 @@ +.. doc_2d_parallax: + +2D Parallax +=========== + +Introduction +------------ + +Parallax is an effect used to simulate depth by having textures move at different speeds relative to the camera. Godot +provides the :ref:`Parallax2D` node to achieve this effect. It can still be easy to get tripped +up though, so this page provides in-depth descriptions of some properties and how to fix some common mistakes. + +.. note:: + This page only covers how to use :ref:`Parallax2D`. This node is still experimental, so the + implementation might change in future versions of Godot. However, it is still recommended to use over the + :ref:`ParallaxLayer` and :ref:`ParallaxBackground` nodes. + +Scroll scale +------------ + +The backbone of the parallax effect is the :ref:`scroll_scale ` property. +It works as a scroll-speed multiplier, allowing layers to move at a different speed than the camera for each axis set. +A value of 1 makes the parallax node scroll at the same speed as the camera. If you want your image to look further away +when scrolling, use a value lower than 1, with 0 bringing it to a complete stop. If you want something to appear closer +to the camera, use a value higher than 1, making it scroll faster. + +.. image:: img/2d_parallax_size_viewport.webp + +The scene above is comprised of five layers. Some good :ref:`scroll_scale ` +values might be: + +- ``(0.7, 1)`` - Forest +- ``(0.5, 1)`` - Hills +- ``(0.3, 1)`` - Lower Clouds +- ``(0.2, 1)`` - Higher Clouds +- ``(0.1, 1)`` - Sky + +The video below displays how these values affect scrolling while in-game: + +.. video:: video/2d_parallax_scroll_scale.webm + :alt: A scene with five layers scrolling at different speeds + :autoplay: + :loop: + :muted: + +Infinite repeat +--------------- + +:ref:`Parallax2D` provides a bonus effect that gives textures the illusion of repeating infinitely. +:ref:`repeat_size` tells the node to snap its position forward or back when the +camera scrolls by the set value. This effect is achieved by adding a single repeat to all the child canvas items offset +by the value. While the camera scrolls between the image and its repeat, it invisibly snaps back giving the appearance +of a looping image. + +.. image:: img/2d_parallax_scroll.gif + +Being a delicate effect, it's easy for unfamiliar users to make mistakes with their setup. Let's go over the "how" and +"why" of a few common problems users encounter. + +Poor sizing +~~~~~~~~~~~ + +The infinite repeat effect is easiest to work with when you have an image designed to repeat seamlessly and is the same +size or larger than your viewport **before** setting the :ref:`repeat_size`. If +you aren't able to obtain assets that are designed for this task, there are some other things you can do to better +prepare your image in regards to size. + +Here is an example of a texture that is too small for its viewport: + +.. image:: img/2d_parallax_size_bad.webp + +We can see that the viewport size is 500x300 but the texture is 288x208. If we set the +:ref:`repeat_size` to the size of our image, the infinite repeat effect doesn't +scroll properly because the original texture doesn't cover the viewport. If we set the +:ref:`repeat_size` to the size of the viewport, we have a large gap. What can we +do? + +Make the viewport smaller +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The simplest answer is to make the viewport the same size or smaller than your textures. Click on +``Project -> Project Settings -> Window`` and change the viewport height and width to match your background. + +.. image:: img/2d_parallax_size_viewport.webp + +Scale the Parallax2D +^^^^^^^^^^^^^^^^^^^^ + +If you're not aiming for a pixel-perfect style, or don't mind a little blurriness, you may opt to scale the textures +larger to fit your screen. Set the :ref:`scale` of the :ref:`Parallax2D`, +and all child textures scale with it. + +Scale the child nodes +^^^^^^^^^^^^^^^^^^^^^ + +Similar to scaling the :ref:`Parallax2D`, you can scale your :ref:`Sprite2D` nodes to +be large enough to cover the screen. Keep in mind that some settings like +:ref:`Parallax2D.repeat_size` and +:ref:`Sprite2D.region_rect` do not take scaling into account, so it's necessary to +adjust these values based on the scale. + +.. image:: img/2d_parallax_size_scale.webp + +Repeat the textures +^^^^^^^^^^^^^^^^^^^ + +You can also start off on the right foot by preparing child nodes earlier in the process. If you have a +:ref:`Sprite2D` you'd like to repeat, but is too small, you can do the following to repeat it: + +- set :ref:`texture_repeat` to :ref:`CanvasItem.TEXTURE_REPEAT_ENABLED` +- set :ref:`region_enabled` to ``true`` +- set the :ref:`region_rect` to a multiple of the size of your texture large enough to cover the viewport. + +Below, you can see that repeating the image twice makes it large enough to cover the screen. + +.. image:: img/2d_parallax_size_repeat.webp + +Poor positioning +~~~~~~~~~~~~~~~~ + +It's common to see users mistakenly set all of their textures to be centered at ``(0,0)``: + +.. image:: img/2d_parallax_single_centered.webp + +This creates problems with the infinite repeat effect and should be avoided. The "infinite repeat canvas" starts at +``(0,0)`` and expands down and to the right to the size of the :ref:`repeat_size` +value. + +.. image:: img/2d_parallax_single_expand.webp + +If the textures are centered on the ``(0,0)`` crossing, the infinite repeat canvas is only partly covered, so it +only partly repeats. + +Would increasing ``repeat_times`` fix this? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Increasing :ref:`repeat_times` technically *would* work in some scenarios, but +is a brute force solution and not the problem it is designed to solve (we'll go over this in a bit). A better fix is to +understand how the repeat effect works and set up the parallax textures appropriately to begin with. + +First, check to see if any textures are spilling over onto the negative parts of the canvas. Make sure the textures +used in the parallax nodes fit inside the "infinite repeat canvas" starting at ``(0,0)``. That way, if +:ref:`Parallax2D.repeat_size` is set correctly, it should look something like +this, with one single loop of the image the same size or larger than the viewport: + +.. image:: img/2d_parallax_repeat_good_norect.webp + +If you think of how the image scrolls across the screen, it starts by displaying what's inside the red rectangle +(determined by :ref:`repeat_size`), and when it reaches what's inside the yellow +rectangle it zips the image forward to give the illusion of scrolling forever. + +.. image:: img/2d_parallax_repeat_good.webp + +If you have the image positioned away from the "infinite repeat canvas", when the camera reaches the yellow rectangle, +half of the image is cut off before it jumps forward like in the image below: + +.. image:: img/2d_parallax_repeat_bad.webp + +Scroll offset +------------- + +If your parallax textures are already working correctly, but you prefer it to start at a different point, +:ref:`Parallax2D` comes with a :ref:`scroll_offset` property +used to offset where the infinite repeat canvas starts. As an example, if your image is 288x208, setting +the :ref:`scroll_offset` to ``(-144,0)`` or ``(144,0)`` allows it to begin +halfway across the image. + +Repeat times +------------ + +Ideally, following this guide, your parallax textures are large enough to cover the screen even when zoomed out. +Until now, we have had a perfectly fitting 288x208 texture inside of a 288x208 viewport. However, problems +occur when we zoom out by setting the :ref:`Camera2D.zoom` to ``(0.5, 0.5)``: + +.. image:: img/2d_parallax_zoom_single.webp + +Even though everything is correctly set for the viewport at the default zoom level, zooming out makes it smaller than +the viewport, breaking the infinite repeat effect. This is where +:ref:`repeat_times` can help out. Setting a value of ``3`` (one extra +repeat behind and in front), it is now large enough to accommodate the infinite repeat effect. + +.. image:: img/2d_parallax_zoom_repeat_times.webp + +If these textures were meant to be repeated vertically, we would have specified a ``y`` value for the +:ref:`repeat_size`. The +:ref:`repeat_times` would automatically add a repeat above and below as well. +This is only a horizontal parallax, so it leaves an empty block above and below the image. How do we solve this? We +need to get creative! In this example, we stretch the sky higher, and grass sprite lower. The textures now support the +normal zoom level and zooming out to half size. + +.. image:: img/2d_parallax_zoom_repeat_adjusted.webp + +Split screen +------------ + +Most tutorials for making a split screen game in Godot begin by writing a small script to assign +the :ref:`Viewport.world_2d` of the first SubViewport to the second, so they have a +shared display. Questions often pop up about how to share a parallax effect between both screens. + +The parallax effect fakes a perspective by moving the positions of different textures in relation to the camera. This is +understandably problematic if you have multiple cameras, because your textures can't be in two places at once! + +This is still achievable by cloning the parallax nodes into the second (or third or fourth) +:ref:`SubViewport`. Here's how it looks for a two player game: + +.. image:: img/2d_parallax_splitscreen.webp + +Of course, now both backgrounds show in both SubViewports. What we want is for some nodes to be visible in one viewport +but not another. While technically possible, this is not a feature officially supported by Godot at the moment. There is +currently a proposal to make this much simpler, so please stay tuned. + +As a workaround, you can do the following: + +- Set the first SubViewport's :ref:`canvas_cull_mask` to only layer 1, so it displays all nodes with a :ref:`visibility_layer` of layer 1. +- Set the second SubViewport's :ref:`canvas_cull_mask` to only layer 2, so it displays all nodes with a :ref:`visibility_layer` of layer 2. +- Set the :ref:`visibility_layer` of every node you want to display in both viewports to both layers 1 and 2. +- Set the :ref:`visibility_layer` of the :ref:`Parallax2D` node and all its descendants in the first :ref:`SubViewport` to layer 1. +- Set the :ref:`visibility_layer` of the :ref:`Parallax2D` node and all its descendants in the second :ref:`SubViewport` to layer 2. + +Previewing in the editor +------------------------ + +Prior to 4.3, the recommendation was to place every layer in their own +:ref:`ParallaxBackground`, enable the +:ref:`follow_viewport_enabled` property, and scale the individual +layer. This method has always been tricky to get right, but is still achievable by using a +:ref:`CanvasLayer` instead of a :ref:`ParallaxBackground`. + +.. note:: + Another recommendation is `KoBeWi's "Parallax2D Preview" addon `_. + It provides a few different preview modes and is very handy! diff --git a/tutorials/2d/img/2d_parallax_repeat_bad.webp b/tutorials/2d/img/2d_parallax_repeat_bad.webp new file mode 100644 index 00000000000..5b1625be39e Binary files /dev/null and b/tutorials/2d/img/2d_parallax_repeat_bad.webp differ diff --git a/tutorials/2d/img/2d_parallax_repeat_good.webp b/tutorials/2d/img/2d_parallax_repeat_good.webp new file mode 100644 index 00000000000..9ea89714d1d Binary files /dev/null and b/tutorials/2d/img/2d_parallax_repeat_good.webp differ diff --git a/tutorials/2d/img/2d_parallax_repeat_good_norect.webp b/tutorials/2d/img/2d_parallax_repeat_good_norect.webp new file mode 100644 index 00000000000..65693ba8738 Binary files /dev/null and b/tutorials/2d/img/2d_parallax_repeat_good_norect.webp differ diff --git a/tutorials/2d/img/2d_parallax_scroll.gif b/tutorials/2d/img/2d_parallax_scroll.gif new file mode 100644 index 00000000000..426d4e28526 Binary files /dev/null and b/tutorials/2d/img/2d_parallax_scroll.gif differ diff --git a/tutorials/2d/img/2d_parallax_single_centered.webp b/tutorials/2d/img/2d_parallax_single_centered.webp new file mode 100644 index 00000000000..9c6f8fd8cab Binary files /dev/null and b/tutorials/2d/img/2d_parallax_single_centered.webp differ diff --git a/tutorials/2d/img/2d_parallax_single_expand.webp b/tutorials/2d/img/2d_parallax_single_expand.webp new file mode 100644 index 00000000000..98de5a27edd Binary files /dev/null and b/tutorials/2d/img/2d_parallax_single_expand.webp differ diff --git a/tutorials/2d/img/2d_parallax_size_bad.webp b/tutorials/2d/img/2d_parallax_size_bad.webp new file mode 100644 index 00000000000..8c3b1644836 Binary files /dev/null and b/tutorials/2d/img/2d_parallax_size_bad.webp differ diff --git a/tutorials/2d/img/2d_parallax_size_repeat.webp b/tutorials/2d/img/2d_parallax_size_repeat.webp new file mode 100644 index 00000000000..dde94a1a0af Binary files /dev/null and b/tutorials/2d/img/2d_parallax_size_repeat.webp differ diff --git a/tutorials/2d/img/2d_parallax_size_scale.webp b/tutorials/2d/img/2d_parallax_size_scale.webp new file mode 100644 index 00000000000..3d8912745ca Binary files /dev/null and b/tutorials/2d/img/2d_parallax_size_scale.webp differ diff --git a/tutorials/2d/img/2d_parallax_size_viewport.webp b/tutorials/2d/img/2d_parallax_size_viewport.webp new file mode 100644 index 00000000000..0ad33a04ecb Binary files /dev/null and b/tutorials/2d/img/2d_parallax_size_viewport.webp differ diff --git a/tutorials/2d/img/2d_parallax_splitscreen.webp b/tutorials/2d/img/2d_parallax_splitscreen.webp new file mode 100644 index 00000000000..7544bcf5303 Binary files /dev/null and b/tutorials/2d/img/2d_parallax_splitscreen.webp differ diff --git a/tutorials/2d/img/2d_parallax_zoom_repeat_adjusted.webp b/tutorials/2d/img/2d_parallax_zoom_repeat_adjusted.webp new file mode 100644 index 00000000000..156f230a288 Binary files /dev/null and b/tutorials/2d/img/2d_parallax_zoom_repeat_adjusted.webp differ diff --git a/tutorials/2d/img/2d_parallax_zoom_repeat_times.webp b/tutorials/2d/img/2d_parallax_zoom_repeat_times.webp new file mode 100644 index 00000000000..87a2ae420a2 Binary files /dev/null and b/tutorials/2d/img/2d_parallax_zoom_repeat_times.webp differ diff --git a/tutorials/2d/img/2d_parallax_zoom_single.webp b/tutorials/2d/img/2d_parallax_zoom_single.webp new file mode 100644 index 00000000000..00726a3f083 Binary files /dev/null and b/tutorials/2d/img/2d_parallax_zoom_single.webp differ diff --git a/tutorials/2d/img/using_tilemaps_create_layers.webp b/tutorials/2d/img/using_tilemaps_create_layers.webp deleted file mode 100644 index c56da00886d..00000000000 Binary files a/tutorials/2d/img/using_tilemaps_create_layers.webp and /dev/null differ diff --git a/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp b/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp index 46f3d25904f..33b8bdf77ea 100644 Binary files a/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp and b/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_custom_data_layer.webp b/tutorials/2d/img/using_tilesets_create_custom_data_layer.webp index ffb8126175f..81754b72c13 100644 Binary files a/tutorials/2d/img/using_tilesets_create_custom_data_layer.webp and b/tutorials/2d/img/using_tilesets_create_custom_data_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_navigation_layer.webp b/tutorials/2d/img/using_tilesets_create_navigation_layer.webp index 424cae015d0..f359d57ea26 100644 Binary files a/tutorials/2d/img/using_tilesets_create_navigation_layer.webp and b/tutorials/2d/img/using_tilesets_create_navigation_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_new_tileset.webp b/tutorials/2d/img/using_tilesets_create_new_tileset.webp index a757ded8244..ef325ba1f89 100644 Binary files a/tutorials/2d/img/using_tilesets_create_new_tileset.webp and b/tutorials/2d/img/using_tilesets_create_new_tileset.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_occlusion_layer.webp b/tutorials/2d/img/using_tilesets_create_occlusion_layer.webp index 9840bc544e9..c6d740ad7b9 100644 Binary files a/tutorials/2d/img/using_tilesets_create_occlusion_layer.webp and b/tutorials/2d/img/using_tilesets_create_occlusion_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_physics_layer.webp b/tutorials/2d/img/using_tilesets_create_physics_layer.webp index 9b4175fb43e..f667e48c5d3 100644 Binary files a/tutorials/2d/img/using_tilesets_create_physics_layer.webp and b/tutorials/2d/img/using_tilesets_create_physics_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_terrain_set.webp b/tutorials/2d/img/using_tilesets_create_terrain_set.webp index 3270f0bb1e5..fb99233d9c8 100644 Binary files a/tutorials/2d/img/using_tilesets_create_terrain_set.webp and b/tutorials/2d/img/using_tilesets_create_terrain_set.webp differ diff --git a/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp b/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp index 7da39c8caba..fc854fe87be 100644 Binary files a/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp and b/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp differ diff --git a/tutorials/2d/index.rst b/tutorials/2d/index.rst index 27e67c9c696..d90628551ee 100644 --- a/tutorials/2d/index.rst +++ b/tutorials/2d/index.rst @@ -23,6 +23,7 @@ Rendering particle_systems_2d 2d_antialiasing custom_drawing_in_2d + 2d_parallax Physics and movement -------------------- diff --git a/tutorials/2d/using_tilemaps.rst b/tutorials/2d/using_tilemaps.rst index 0cfba905499..41a0373eb52 100644 --- a/tutorials/2d/using_tilemaps.rst +++ b/tutorials/2d/using_tilemaps.rst @@ -13,7 +13,7 @@ Introduction ------------ A tilemap is a grid of tiles used to create a game's layout. There are several -benefits to using :ref:`TileMap ` nodes to design your levels. +benefits to using :ref:`TileMapLayer ` nodes to design your levels. First, they make it possible to draw the layout by "painting" the tiles onto a grid, which is much faster than placing individual :ref:`Sprite2D ` nodes one by one. Second, they allow for much larger levels because they are @@ -21,15 +21,15 @@ optimized for drawing large numbers of tiles. Finally, you can add collision, occlusion, and navigation shapes to tiles, adding greater functionality to the TileMap. -Specifying the TileSet in the TileMap -------------------------------------- +Specifying the TileSet in the TileMapLayer +------------------------------------------ If you've followed the previous page on :ref:`doc_using_tilesets`, you should -have a TileSet resource that is built-in to the TileMap node. This is good for +have a TileSet resource that is built-in to the TileMapLayer node. This is good for prototyping, but in a real world project, you will generally have multiple levels reusing the same tileset. -The recommended way to reuse the same TileSet in several TileMap nodes is to save +The recommended way to reuse the same TileSet in several TileMapLayer nodes is to save the TileSet to an external resource. To do so, click the dropdown next to the TileSet resource and choose **Save**: @@ -39,48 +39,60 @@ resource and choose **Save**: Saving the built-in TileSet resource to an external resource file -Creating TileMap layers ------------------------ - -As of Godot 4.0, you can place several *layers* in a single TileMap node. For -example, this allows you to distinguish foreground tiles from background tiles -for better organization. You can place one tile per layer at a given location, -which allows you to overlap several tiles together if you have more than one layer. - -By default, a TileMap node automatically has one premade layer. You do not have -to create additional layers if you only need a single layer, but if you wish to -do so now, select the TileMap node and unfold the **Layers** section in the -inspector: - -.. figure:: img/using_tilemaps_create_layers.webp - :align: center - :alt: Creating layers in a TileMap node (example with "background" and "foreground") +Multiple TileMaplayers and settings +----------------------------------- - Creating layers in a TileMap node (example with "background" and "foreground") +When working with tilemaps it's generally advised that you use multiple TileMapLayer +nodes when appropriate. Using multiple layers can be advantageous, for example, +this allows you to distinguish foreground tiles from background tiles for better +organization. You can place one tile per layer at a given location, which allows you +to overlap several tiles together if you have more than one layer. -Each layer has several properties you can adjust: +Each TileMapLayer node has several properties you can adjust: -- **Name:** A human-readable name to display in the TileMap editor. This can be - something like "background", "buildings", "vegetation", etc. - **Enabled:** If ``true``, the layer is visible in the editor and when running the project. -- **Modulate:** The color to use as a multiplier for all tiles on the layer. - This is also multiplied with the per-tile **Modulate** property and the - TileMap node's **Modulate** property. For example, you can use this to darken - background tiles to make foreground tiles stand out more. -- **Y Sort Enabled:** If ``true``, sorts tiles based on their Y position on the - TileMap. This can be used to prevent sorting issues with certain tile setups, - especially with isometric tiles. +- **TileSet** The tileset used by the TileMapLayer node. + +Rendering +^^^^^^^^^ + - **Y Sort Origin:** The vertical offset to use for Y-sorting on each tile (in pixels). - Only effective if **Y Sort Enabled** is ``true``. -- **Z Index:** Controls whether this layer is drawn in front of or behind other - TileMap layers. This value can be positive or negative; the layer with the highest Z - Index is drawn on top of other layers. If several layers have an equal Z Index - property, the layer that is *last* in the list of layers (the one which - appears at the bottom in the list) is drawn on top. + Only effective if **Y Sort Enabled** under CanvasItem settings is ``true``. +- **X Draw Order Reversed** Reverses the order tiles are drawn on the X axis. Requires + that **Y Sort Enabled** under CanvasItem settings is ``true``. +- **Rendering Quadrant Size** A quadrant is a group of tiles drawn together on a single + CanvasItem for optimization purposes. This setting defines the length of a square's + side in the map's coordinate system. The quadrant size does not apply to a Y sorted + TileMapLayer since tiles are grouped by Y position in that case. + +Physics +^^^^^^^ +- **Collision Enabled** Enables or disables collision. +- **Use Kinematic Bodies** When true TileMapLayer collision shapes will be instantiated + as kinematic bodies. +- **Collision Visibility Mode** Whether or not the TileMapLayer's collision shapes are + visible. If set to default, then it depends on the show collision debug settings. + +Navigation +^^^^^^^^^^ + +- **Navigation Enabled** Whether or not navigation regions are enabled. +- **Navigation Visible** Whether or not the TileMapLayer's navigation meshes are + visible. If set to default then it depends on the show navigation debug settings. + +.. tip:: + + TileMap built-in navigation has many practical limitations that result in inferior pathfinding performance and pathfollowing quality. + + After designing the TileMap consider baking it to a more optimized navigation mesh (and disabling the TileMap NavigationLayer) using a :ref:`NavigationRegion2D ` or the :ref:`NavigationServer2D `. See :ref:`doc_navigation_using_navigationmeshes` for additional information. + +.. warning:: + 2D navigation meshes can not be "layered" or stacked on top of each other like visuals or physic shapes. Attempting to stack navigation meshes on the same navigation map will result in merge and logical errors that break the pathfinding. -You can reorder layers by drag-and-dropping the "three horizontal bars" icon on -the left of the entries in the **Layers** section. +You can reorder layers by drag-and-dropping their node in the Scene tab. You can +also switch between which TileMapLayer node you're working on by using the buttons +in the top right corner of the TileMap editor. .. note:: @@ -91,7 +103,7 @@ the left of the entries in the **Layers** section. Opening the TileMap editor -------------------------- -Select the TileMap node, then open the TileMap panel at the bottom +Select the TileMapLayer node, then open the TileMap panel at the bottom of the editor: .. figure:: img/using_tilemaps_open_tilemap_editor.webp @@ -386,7 +398,7 @@ Rectangle or Bucket Fill painting modes. .. note:: Despite being edited in the TileMap editor, patterns are stored in the - TileSet resource. This allows reusing patterns in different TileMap nodes + TileSet resource. This allows reusing patterns in different TileMapLayer nodes after loading a TileSet resource saved to an external file. Handling tile connections automatically using terrains @@ -400,7 +412,7 @@ set for the TileSet yet. There are 3 kinds of painting modes available for terrain connections: - **Connect**, where tiles are connected to surrounding tiles on the same - TileMap layer. + TileMapLayer. - **Path**, where tiles are connected to tiles painted in the same stroke (until the mouse button is released). - Tile-specific overrides to resolve conflicts or handle situations not covered @@ -454,5 +466,5 @@ the new tile's appearance. .. note:: - Missing tile placeholders may not be visible until you select the TileMap + Missing tile placeholders may not be visible until you select the TileMapLayer node and open the TileMap editor. diff --git a/tutorials/2d/using_tilesets.rst b/tutorials/2d/using_tilesets.rst index 843fc5af51c..8dbc0e39272 100644 --- a/tutorials/2d/using_tilesets.rst +++ b/tutorials/2d/using_tilesets.rst @@ -7,16 +7,16 @@ Introduction ------------ A tilemap is a grid of tiles used to create a game's layout. There are several -benefits to using :ref:`TileMap ` nodes to design your levels. -First, they let you draw a layout by "painting" tiles onto a grid, +benefits to using :ref:`TileMapLayer ` nodes to design your +levels. First, they let you draw a layout by "painting" tiles onto a grid, which is much faster than placing individual :ref:`Sprite2D ` nodes one by one. Second, they allow for larger levels because they are optimized for drawing large numbers of tiles. Finally, they allow you to add greater functionality to your tiles with collision, occlusion, and navigation shapes. -To use tilemaps, you will need to create a TileSet first. A TileSet is a -collection of tiles that can be placed in a TileMap node. After creating a +To use TileMapLayer nodes, you will need to create a TileSet first. A TileSet is a +collection of tiles that can be placed in a TileMapLayer node. After creating a TileSet, you will be able to place them :ref:`using the TileMap editor `. @@ -43,13 +43,13 @@ We'll use this particular *tilesheet* from the set: Tilesheet with 64×64 tiles. Credit: `Kenney `__ -Create a new **TileMap** node, then select it and create a new TileSet resource in the inspector: +Create a new **TileMapLayer** node, then select it and create a new TileSet resource in the inspector: .. figure:: img/using_tilesets_create_new_tileset.webp :align: center - :alt: Creating a new TileSet resource within the TileMap node + :alt: Creating a new TileSet resource within the TileMapLayer node - Creating a new TileSet resource within the TileMap node + Creating a new TileSet resource within the TileMapLayer node After creating the TileSet resource, click the value to unfold it in the inspector. The default tile shape is Square, but you can also choose Isometric, @@ -70,7 +70,7 @@ Set the tile size to 64×64 in the inspector to match the example tilesheet: If relying on automatic tiles creation (like we're about to do here), you must set the tile size **before** creating the *atlas*. The atlas will -determine which tiles from the tilesheet can be added to a TileMap node +determine which tiles from the tilesheet can be added to a TileMapLayer node (as not every part of the image may be a valid tile). Open the **TileSet** panel at the bottom of the editor, then click and drag the @@ -135,7 +135,7 @@ The following properties can be adjusted on the atlas: Increasing this can be useful if the tilesheet image you're using contains guides (such as outlines between every tile). - **Texture Region Size:** The size of each tile on the atlas in pixels. In most - cases, this should match the tile size defined in the TileMap property + cases, this should match the tile size defined in the TileMapLayer property (although this is not strictly necessary). - **Use Texture Padding:** If checked, adds a 1-pixel transparent edge around each tile to prevent texture bleeding when filtering is enabled. @@ -174,7 +174,7 @@ sounds), particle effects, and more. For this example, we'll create a scene containing a CPUParticles2D root node. Save this scene to a scene file (separate from the scene containing the -TileMap), then switch to the scene containing the TileMap node. Open the TileSet +TileMapLayer), then switch to the scene containing the TileMapLayer node. Open the TileSet editor, and create a new **Scenes Collection** in the left column: .. figure:: img/using_tilesets_creating_scene_collection.webp @@ -258,7 +258,7 @@ Adding collision, navigation and occlusion to the TileSet --------------------------------------------------------- We've now successfully created a basic TileSet. We could start using in the -TileMap node now, but it currently lacks any form of collision detection. +TileMapLayer node now, but it currently lacks any form of collision detection. This means the player and other objects could walk straight through the floor or walls. @@ -272,31 +272,31 @@ This requires defining occluder polygons for "solid" tiles on the TileSet. To be able to define collision, navigation and occlusion shapes for each tile, you will need to create a physics, navigation or occlusion layer for the TileSet -resource first. To do so, select the TileMap node, click the TileSet property +resource first. To do so, select the TileMapLayer node, click the TileSet property value in the inspector to edit it then unfold **Physics Layers** and choose **Add Element**: .. figure:: img/using_tilesets_create_physics_layer.webp :align: center - :alt: Creating a physics layer in the TileSet resource inspector (within the TileMap node) + :alt: Creating a physics layer in the TileSet resource inspector (within the TileMapLayer node) - Creating a physics layer in the TileSet resource inspector (within the TileMap node) + Creating a physics layer in the TileSet resource inspector (within the TileMapLayer node) If you also need navigation support, now is a good time to create a navigation layer: .. figure:: img/using_tilesets_create_navigation_layer.webp :align: center - :alt: Creating a navigation layer in the TileSet resource inspector (within the TileMap node) + :alt: Creating a navigation layer in the TileSet resource inspector (within the TileMapLayer node) - Creating a navigation layer in the TileSet resource inspector (within the TileMap node) + Creating a navigation layer in the TileSet resource inspector (within the TileMapLayer node) If you need support for light polygon occluders, now is a good time to create an occlusion layer: .. figure:: img/using_tilesets_create_occlusion_layer.webp :align: center - :alt: Creating an occlusion layer in the TileSet resource inspector (within the TileMap node) + :alt: Creating an occlusion layer in the TileSet resource inspector (within the TileMapLayer node) - Creating an occlusion layer in the TileSet resource inspector (within the TileMap node) + Creating an occlusion layer in the TileSet resource inspector (within the TileMapLayer node) .. note:: @@ -381,9 +381,9 @@ the custom data for the alternative tile only. .. figure:: img/using_tilesets_create_custom_data_layer.webp :align: center - :alt: Creating a custom data layer in the TileSet resource inspector (within the TileMap node) + :alt: Creating a custom data layer in the TileSet resource inspector (within the TileMapLayer node) - Creating a custom data layer in the TileSet resource inspector (within the TileMap node) + Creating a custom data layer in the TileSet resource inspector (within the TileMapLayer node) .. figure:: img/using_tilesets_custom_data_layers_example.webp :align: center @@ -451,13 +451,13 @@ terrains are matched to each other in a terrain set. Godot 3.x: 2×2, 3×3 or 3×3 minimal. This is also similar to what the `Tiled `__ editor features. -Select the TileMap node, go to the inspector and create a new terrain set within the TileSet *resource*: +Select the TileMapLayer node, go to the inspector and create a new terrain set within the TileSet *resource*: .. figure:: img/using_tilesets_create_terrain_set.webp :align: center - :alt: Creating a terrain set in the TileSet resource inspector (within the TileMap node) + :alt: Creating a terrain set in the TileSet resource inspector (within the TileMapLayer node) - Creating a terrain set in the TileSet resource inspector (within the TileMap node) + Creating a terrain set in the TileSet resource inspector (within the TileMapLayer node) After creating a terrain set, you **must** create one or more terrains *within* the terrain set: @@ -643,7 +643,7 @@ properties is different compared to base tiles: coordinate (in pixels). This allows using layers as if they were on different height for top-down games. Adjusting this can help alleviate issues with sorting certain tiles. Only effective if **Y Sort Enabled** is ``true`` on - the TileMap layer the tile is placed on. + the TileMapLayer node under **CanvasItem > Ordering** You can create an additional alternative tile variant by clicking the large "+" icon next to the alternative tile. This is equivalent to selecting the base tile diff --git a/tutorials/2d/video/2d_parallax_scroll_scale.webm b/tutorials/2d/video/2d_parallax_scroll_scale.webm new file mode 100644 index 00000000000..960065b9602 Binary files /dev/null and b/tutorials/2d/video/2d_parallax_scroll_scale.webm differ diff --git a/tutorials/3d/3d_antialiasing.rst b/tutorials/3d/3d_antialiasing.rst index a5e606ce5f4..24582b28241 100644 --- a/tutorials/3d/3d_antialiasing.rst +++ b/tutorials/3d/3d_antialiasing.rst @@ -116,7 +116,7 @@ AMD FidelityFX Super Resolution 2.2 (FSR2) ------------------------------------------ Since Godot 4.2, there is built-in support for -`AMD FidelityFX Super Resolution `__ +`AMD FidelityFX Super Resolution `__ 2.2. This is an :ref:`upscaling method ` compatible with all recent GPUs from any vendor. FSR2 is normally designed to improve performance by lowering the internal 3D rendering resolution, diff --git a/tutorials/3d/global_illumination/using_lightmap_gi.rst b/tutorials/3d/global_illumination/using_lightmap_gi.rst index 37a88c05ae3..e25b4624f3c 100644 --- a/tutorials/3d/global_illumination/using_lightmap_gi.rst +++ b/tutorials/3d/global_illumination/using_lightmap_gi.rst @@ -60,9 +60,6 @@ Visual comparison but lower quality visuals. Notice the blurrier sun shadow in the top-right corner. -Visual comparison ------------------ - Here are some comparisons of how LightmapGI vs. VoxelGI look. Notice that lightmaps are more accurate, but also suffer from the fact that lighting is on an unwrapped texture, so transitions and resolution may not @@ -77,6 +74,12 @@ large open worlds without any need for baking. Setting up ---------- +.. warning:: + + Baking lightmaps in the Android and web editors is not supported due to + graphics API limitations on those devices. On Android and web platforms, + only *rendering* lightmaps that were baked on a desktop PC is supported. + First of all, before the lightmapper can do anything, the objects to be baked need a UV2 layer and a texture size. A UV2 layer is a set of secondary texture coordinates that ensures any face in the object has its own place in the UV map. Faces must diff --git a/tutorials/3d/img/3d_toolbar.webp b/tutorials/3d/img/3d_toolbar.webp new file mode 100644 index 00000000000..b3d24bd9ebc Binary files /dev/null and b/tutorials/3d/img/3d_toolbar.webp differ diff --git a/tutorials/3d/img/godot-tps-demo.webp b/tutorials/3d/img/godot-tps-demo.webp new file mode 100644 index 00000000000..26a2f58acd7 Binary files /dev/null and b/tutorials/3d/img/godot-tps-demo.webp differ diff --git a/tutorials/3d/img/tuto_3d4.webp b/tutorials/3d/img/tuto_3d4.webp index f3ab669ef22..d8385347f76 100644 Binary files a/tutorials/3d/img/tuto_3d4.webp and b/tutorials/3d/img/tuto_3d4.webp differ diff --git a/tutorials/3d/img/tuto_3d9.webp b/tutorials/3d/img/tuto_3d9.webp new file mode 100644 index 00000000000..2a33719dadf Binary files /dev/null and b/tutorials/3d/img/tuto_3d9.webp differ diff --git a/tutorials/3d/img/tuto_3d_gizmo.webp b/tutorials/3d/img/tuto_3d_gizmo.webp new file mode 100644 index 00000000000..8993064ef2a Binary files /dev/null and b/tutorials/3d/img/tuto_3d_gizmo.webp differ diff --git a/tutorials/3d/img/tuto_3d_updated_view_menu.webp b/tutorials/3d/img/tuto_3d_updated_view_menu.webp new file mode 100644 index 00000000000..dcbc3825bb9 Binary files /dev/null and b/tutorials/3d/img/tuto_3d_updated_view_menu.webp differ diff --git a/tutorials/3d/introduction_to_3d.rst b/tutorials/3d/introduction_to_3d.rst index a314805dbaf..674e5f5e24f 100644 --- a/tutorials/3d/introduction_to_3d.rst +++ b/tutorials/3d/introduction_to_3d.rst @@ -11,116 +11,135 @@ are present in both 2D and 3D versions. In fact, it is worth checking the 3D platformer tutorial, or the 3D kinematic character tutorials, which are almost identical to their 2D counterparts. +.. figure:: img/godot-tps-demo.webp + :align: center + :alt: An example 3D game demo created using Godot + + Godot Third Person Shooter (TPS) Demo, available on the + `Github repository `__ or the + :ref:`Asset Library `. + In 3D, math is a little more complex than in 2D, so also checking the :ref:`doc_vector_math` entry in the wiki (which was especially created for game developers, not mathematicians or engineers) will help pave the way for you to develop 3D games efficiently. -Node3D node -~~~~~~~~~~~ - -:ref:`Node2D ` is the base node for 2D. -:ref:`Control ` is the base node for everything GUI. -Following this reasoning, the 3D engine uses the :ref:`Node3D ` -node for everything 3D. - -.. image:: img/tuto_3d1.webp - -Node3Ds have a local transform, which is relative to the parent -node (as long as the parent node is also of **or inherits from** the type -Node3D). This transform can be accessed as a 3×4 -:ref:`Transform3D `, or as 3 :ref:`Vector3 ` -members representing location, Euler rotation (X, Y and Z angles) and -scale. - -.. image:: img/tuto_3d2.webp - -3D content -~~~~~~~~~~ - -Unlike 2D, where loading image content and drawing is straightforward, 3D is a -little more difficult. The content needs to be created with special 3D tools -(also called Digital Content Creation tools, or DCCs) and exported to an -exchange file format to be imported in Godot. This is required since 3D formats -are not as standardized as images. - -Manually authored models (using 3D modeling software) ------------------------------------------------------ - -.. FIXME: Needs update to properly description Godot 3.x workflow - (used to reference a non existing doc_importing_3d_meshes importer). - -There are two pipelines to import 3D models in Godot. The first and most common -one is by :ref:`doc_importing_3d_scenes`, which allows you to import entire -scenes (exactly as they look in the 3D modeling software), including animation, -skeletal rigs, blend shapes, etc. - -The second pipeline is by importing simple .OBJ files as mesh resources, -which can be then put inside a :ref:`MeshInstance3D ` -node for display. - -Generated geometry ------------------- +3D workspace +~~~~~~~~~~~~ -It is possible to create custom geometry by using the -:ref:`ArrayMesh ` resource directly. Simply create your arrays -and use the :ref:`ArrayMesh.add_surface_from_arrays() ` -function. A helper class is also available, :ref:`SurfaceTool `, -which provides a more straightforward API and helpers for indexing, -generating normals, tangents, etc. +Editing 3D scenes is done in the 3D workspace. This workspace can be selected +manually, but it will be automatically selected when a Node3D node is +selected. -In any case, this method is meant for generating static geometry (models -that will not be updated often), as creating vertex arrays and -submitting them to the 3D API has a significant performance cost. +.. image:: img/tuto_3d3.webp -Immediate geometry ------------------- +Similar to 2D, the tabs below the workspace selector are used to change between +currently opened scenes or create a new one using the plus (+) button. The left and +right docks should be familiar from :ref:`editor introduction `. + +Below the scene selector, the main toolbar is visible, and beneath the main toolbar +is the 3D viewport. + +Main toolbar +------------ + +Some buttons in the main toolbar are the same as those in the 2D workspace. A brief explanation +is given with the shortcut if the mouse cursor is hovered over a button for one second. +Some buttons may have additional functionality if another keypress is performed. A recap +of main functionality of each button with its default shortcut is provided below from +left to right: + +.. image:: img/3d_toolbar.webp + +- **Select Mode** (:kbd:`Q`): Allows selection of nodes in the viewport. Left clicking + on a node to select one. Left clicking and dragging a rectangle selects all + nodes within the rectangle's boundaries, once released. + Holding :kbd:`Shift` while selecting adds more nodes to the selection. + Clicking on a selected node while holding :kbd:`Shift` deselects the node. + In this mode, you can use the gizmos to perform movement or rotation. +- **Move Mode** (:kbd:`W`): Enables move (or translate) mode for the selected nodes. + See :ref:`doc_introduction_to_3d_space_and_manipulation` for more details. +- **Rotate Mode** (:kbd:`E`): Enables rotation mode for the selected nodes. See + :ref:`doc_introduction_to_3d_space_and_manipulation` for more details. +- **Scale Mode** (:kbd:`R`): Enables scaling and displays scaling gizmos in different + axes for the selected nodes. See :ref:`doc_introduction_to_3d_space_and_manipulation` + for more details. + +- **Show the list of selectable nodes at the clicked position**: As the description suggests, + this provides a list of selectable nodes at the clicked position as a context menu, + if there is more than one node in the clicked area. +- **Lock** (:kbd:`Ctrl + L`) the selected nodes, preventing selection and movement in the viewport. + Clicking the button again (or using :kbd:`Ctrl + Shift + L`) unlocks the selected nodes. + Locked nodes can only be selected in the scene tree. + They can easily be identified with a padlock next to their node names in the scene tree. + Clicking on this padlock also unlocks the nodes. +- **Group selected nodes** (:kbd:`Ctrl + G`). This allows selection of the root node if + any of the children are selected. + Using :kbd:`Ctrl + G` ungroups them. Additionally, clicking the ungroup button in + the scene tree performs the same action. +- **Use Local Space** (:kbd:`T`): If enabled, gizmos of a node are drawn using the current node's + rotation angle instead of the :ref:`global viewport axes `. +- **Use Snap** (:kbd:`Y`): If enabled, movement, and rotation snap to grid. Snapping can also + temporarily be activated using :kbd:`Ctrl` while performing the action. + The settings for changing snap options are explained below. +- **Project Camera Override**: This action temporarily replaces the active camera in the level + (e.g., the camera following the player) with the camera in the editor's viewport, allowing you + to move freely and inspect the level's different parts, while game is running. +- **Toggle preview sunlight**: If no DirectionalLight3D exist in the scene, a preview + of sunlight can be used as a light source. See + :ref:`doc_introduction_to_3d_preview_environment_light` for more details. +- **Toggle preview environment**: If no WorldEnvironment exists in the scene, a preview of the + environment can be used as a placeholder. See + :ref:`doc_introduction_to_3d_preview_environment_light` for more details. +- **Edit Sun and Environment Settings (three dots)**: Opens the menu to configure preview + sunlight and environment settings. See :ref:`doc_introduction_to_3d_preview_environment_light` + for more details. + +- **Transform menu**: It has three options: + + - *Snap Object to Floor*: Snaps an object to a solid floor. + - *Transform Dialog*: Opens a dialog to adjust transform parameters (translate, rotate, scale, + and transform) manually. + - *Snap Settings*: Allows you to change transform, rotate snap (in degrees), and scale snap + (in percent) settings. + +- **View menu**: Controls the view options and enables additional viewports: -If, instead, you need to generate simple geometry that will be updated often, -Godot provides a special :ref:`ImmediateMesh ` resource -that can be used in a :ref:`MeshInstance3D ` node. -This provides an OpenGL 1.x-style immediate-mode API to create points, lines, -triangles, etc. +.. image:: img/tuto_3d6.webp -2D in 3D --------- +In this menu, you can also show/hide grids, which are set to 1x1 meter by default, +and the origin, where the blue, green, and red axis lines intersect. +Moreover, specific types of gizmos can be toggled in this menu. -While Godot packs a powerful 2D engine, many types of games use 2D in a -3D environment. By using a fixed camera (either orthogonal or -perspective) that does not rotate, nodes such as -:ref:`Sprite3D ` and -:ref:`AnimatedSprite3D ` -can be used to create 2D games that take advantage of mixing with 3D -backgrounds, more realistic parallax, lighting/shadow effects, etc. +.. image:: img/tuto_3d6_2.webp -The disadvantage is, of course, that added complexity and reduced -performance in comparison to plain 2D, as well as the lack of reference -of working in pixels. +An open eye means that the gizmo is visible, a closed eye means it is hidden. +A half-open eye means that it is also visible through opaque surfaces. -Environment -~~~~~~~~~~~ +Clicking on *Settings* in this view menu opens a window to change the +*Vertical Field of View (VFOV)* parameter +(in degrees), *Z-Near*, and *Z-Far* values. -Besides editing a scene, it is often common to edit the environment. -Godot provides a :ref:`WorldEnvironment ` -node that allows changing the background color, mode (as in, put a -skybox), and applying several types of built-in post-processing effects. -Environments can also be overridden in the Camera. +Next to the View menu, additional buttons may be visible. In the toolbar image +at the beginning of this chapter, an additional *Mesh* button appears because a +MeshInstance3D is selected. This menu provides some quick actions or tools to +work on a specific node or selection. -3D viewport -~~~~~~~~~~~ +View menu of viewport +--------------------- -Editing 3D scenes is done in the 3D tab. This tab can be selected -manually, but it will be automatically enabled when a Node3D node is -selected. +Below the *Select* tool, in the 3D viewport, clicking on the three dots opens the +**View menu** for the viewport. +Hiding all shown gizmos in the editor's 3D view can also be performed through +this menu: -.. image:: img/tuto_3d3.webp +.. image:: img/tuto_3d6_1.webp -Default 3D scene navigation controls are similar to Blender (aiming to -have some sort of consistency in the free software pipeline..), but -options are included to customize mouse buttons and behavior to be -similar to other tools in the Editor Settings: +This menu also displays the current view type and enables quick adjustment of the +viewport's viewing angle. Additionally, it offers options to modify the appearance of +nodes within the viewport. -.. image:: img/tuto_3d4.webp +.. _doc_introduction_to_3d_coordinate_system: Coordinate system ----------------- @@ -154,10 +173,14 @@ See this chart for comparison with other 3D software: Image by `Freya Holmér `__ + +.. _doc_introduction_to_3d_space_and_manipulation: + Space and manipulation gizmos ----------------------------- -Moving objects in the 3D view is done through the manipulator gizmos. +Moving, rotating, and scaling objects in the 3D view is done through the +manipulator gizmos. Each axis is represented by a color: Red, Green, Blue represent X, Y, Z respectively. This convention applies to the grid and other gizmos too (and also to the shader language, ordering of components for @@ -167,10 +190,67 @@ Vector3, Color, etc.). Some useful keybindings: -- To snap placement or rotation, press :kbd:`Ctrl` while moving, scaling +- To snap placement or rotation, press :kbd:`Ctrl` while moving, scaling, or rotating. - To center the view on the selected object, press :kbd:`F`. +In the viewport, the arrows can be clicked and held to move the object on an axis. +The arcs can be clicked and held to rotate the object. +To lock one axis and move the object freely in the other two axes, the colored rectangles +can be clicked, held, and dragged. + +If the transform mode is changed from *Select Mode* to *Scale Mode*, the arrows will be +replaced by cubes, which can be dragged to scale an object as if the object is being moved. + +Navigating the 3D environment +----------------------------- + +In 3D environments, it is often important to adjust the viewpoint or angle +from which you are viewing the scene. +In Godot, navigating the 3D environment in the viewport (or spatial editor) +can be done in multiple ways. + +The default 3D scene navigation controls are similar to Blender (aiming to +have some sort of consistency in the free software pipeline), but +options are included to customize mouse buttons and behavior to be +similar to other tools in the Editor Settings. To change the controls +to Maya or Modo controls, you can navigate to **Editor Settings > Editors > 3D**. +Then, under *Navigation*, search for *Navigation Scheme*. + +.. image:: img/tuto_3d4.webp + +Using the default settings, the following shortcuts control how one can +navigate in the viewport: + +Pressing the middle mouse button and dragging the mouse allows you to orbit around +the center of what is on the screen. + +It is also possible to left-click and hold the manipulator gizmo located +on the top right of the viewport to orbit around the center: + +.. image:: img/tuto_3d_gizmo.webp + +Left-clicking on one of the colored circles will set the view to the chosen +orthogonal and the viewport's view menu will be updated accordingly. + +.. image:: img/tuto_3d_updated_view_menu.webp + +If the *Perspective* view is enabled on the viewport (can be seen on the viewport's View menu, +not the View menu on the main toolbar), holding down the right mouse button on the viewport +or pressing :kbd:`Shift + F` switches to "free-look" mode. +In this mode you can move the mouse to look around, use the :kbd:`W` :kbd:`A` +:kbd:`S` :kbd:`D` keys to fly around the view, :kbd:`E` to go up, and :kbd:`Q` to +go down. To disable this mode, release the right mouse button or press +:kbd:`Shift + F` again. + +In the free-look mode, you can temporarily increase the flying +speed using :kbd:`Shift` or decrease it using :kbd:`Alt`. To change and keep the +speed modifier use :kbd:`mouse wheel up` or :kbd:`mouse wheel down`, to increase or +decrease it, respectively. + +In orthogonal mode, holding the right mouse button will pan the view instead. +Use :kbd:`Keypad 5` to toggle between perspective and orthogonal view. + Using Blender-style transform shortcuts --------------------------------------- @@ -201,22 +281,104 @@ To use Blender-style transform shortcuts in Godot, go to the Editor Settings' - Finally, unbind **Scale Mode** so that its shortcut won't conflict with **Begin Rotate Transformation**. -View menu ---------- +.. tip:: More shortcuts can be found on the + :ref:`doc_default_key_mapping_shortcuts_spatial_editor` page. -The view options are controlled by the "View" menu in the viewport's toolbar. +Node3D node +~~~~~~~~~~~ -.. image:: img/tuto_3d6.webp +:ref:`Node2D ` is the base node for 2D. +:ref:`Control ` is the base node for everything GUI. +Following this reasoning, the 3D engine uses the :ref:`Node3D ` +node for everything 3D. -You can hide the gizmos in the 3D view of the editor through this menu: +.. image:: img/tuto_3d1.webp -.. image:: img/tuto_3d6_1.webp +Node3Ds have a local transform, which is relative to the parent +node (as long as the parent node is also of **or inherits from** the type +Node3D). This transform can be accessed as a 3×4 +:ref:`Transform3D `, or as 3 :ref:`Vector3 ` +members representing location, Euler rotation (X, Y and Z angles) and +scale. -To hide a specific type of gizmos, you can toggle them off in the "View" menu. +.. image:: img/tuto_3d2.webp -.. image:: img/tuto_3d6_2.webp +3D content +~~~~~~~~~~ + +Unlike 2D, where loading image content and drawing is straightforward, 3D is a +little more difficult. The content needs to be created with special 3D tools +(also called Digital Content Creation tools, or DCCs) and exported to an +exchange file format to be imported in Godot. This is required since 3D formats +are not as standardized as images. + +Manually authored models (using 3D modeling software) +----------------------------------------------------- + +.. FIXME: Needs update to properly description Godot 3.x workflow + (used to reference a non existing doc_importing_3d_meshes importer). + +It is possible to import 3D models in Godot created in external tools. +Depending on the format, you can import entire scenes (exactly as they look in +the 3D modeling software), including animation, skeletal rigs, blend shapes, or +as simple resources. + +.. seealso:: See :ref:`doc_importing_3d_scenes` for more on importing. + +Generated geometry +------------------ + +It is possible to create custom geometry by using the +:ref:`ArrayMesh ` resource directly. Simply create your arrays +and use the :ref:`ArrayMesh.add_surface_from_arrays() ` +function. A helper class is also available, :ref:`SurfaceTool `, +which provides a more straightforward API and helpers for indexing, +generating normals, tangents, etc. + +In any case, this method is meant for generating static geometry (models +that will not be updated often), as creating vertex arrays and +submitting them to the 3D API has a significant performance cost. + +.. note:: To learn about prototyping inside Godot or using external tools, see + :ref:`doc_csg_tools`. + + +Immediate geometry +------------------ + +If, instead, you need to generate simple geometry that will be updated often, +Godot provides a special :ref:`ImmediateMesh ` resource +that can be used in a :ref:`MeshInstance3D ` node. +This provides an OpenGL 1.x-style immediate-mode API to create points, lines, +triangles, etc. + +2D in 3D +-------- + +While Godot packs a powerful 2D engine, many types of games use 2D in a +3D environment. By using a fixed camera (either orthogonal or +perspective) that does not rotate, nodes such as +:ref:`Sprite3D ` and +:ref:`AnimatedSprite3D ` +can be used to create 2D games that take advantage of mixing with 3D +backgrounds, more realistic parallax, lighting/shadow effects, etc. + +The disadvantage is, of course, that added complexity and reduced +performance in comparison to plain 2D, as well as the lack of reference +of working in pixels. + +Environment +~~~~~~~~~~~ + +Besides editing a scene, it is often common to edit the environment. +Godot provides a :ref:`WorldEnvironment ` +node that allows changing the background color, mode (as in, put a +skybox), and applying several types of built-in post-processing effects. +Environments can also be overridden in the Camera. + +.. _doc_introduction_to_3d_preview_environment_light: -preview environment and light +Preview environment and light ----------------------------- By default, any 3D scene that doesn't have a :ref:`WorldEnvironment ` @@ -228,12 +390,17 @@ in the editor. If you run the scene or export the project they will not affect the scene. The preview light and environment can be turned on or off from the top menu -by clicking on their respective icon, and the 3 dots dropdown menu next to -those icons can be used to adjust the properties of the preview environment -and light. +by clicking on their respective icon. .. image:: img/tuto_3d8.webp + +The three dots dropdown menu next to those icons can be used to adjust the properties +of the preview environment and light if they are enabled. + +.. image:: img/tuto_3d9.webp + + The same preview sun and environment is used for every scene in the same project, So only make adjustments that would apply to all of the scenes you will need a preview light and environment for. diff --git a/tutorials/3d/standard_material_3d.rst b/tutorials/3d/standard_material_3d.rst index dbd5892c63a..b9eeb8acdbd 100644 --- a/tutorials/3d/standard_material_3d.rst +++ b/tutorials/3d/standard_material_3d.rst @@ -455,12 +455,13 @@ AO map. It is recommended to bake ambient occlusion whenever possible. Height ------ - -Setting a depth map on a material produces a ray-marched search to emulate the -proper displacement of cavities along the view direction. This is not real -added geometry, but an illusion of depth. It may not work for complex objects, -but it produces a realistic depth effect for textures. For best results, -*Depth* should be used together with normal mapping. +Setting a height map on a material produces a ray-marched search to emulate the +proper displacement of cavities along the view direction. This only creates an +illusion of depth, and does not add real geometry — for a height map shape used +for physics collision (such as terrain), see :ref:`class_HeightMapShape3D`. It +may not work for complex objects, but it produces a realistic depth effect for +textures. For best results, *Height* should be used together with normal +mapping. .. image:: img/spatial_material20.png diff --git a/tutorials/assets_pipeline/img/cubemap_template_1x6.webp b/tutorials/assets_pipeline/img/cubemap_template_1x6.webp new file mode 100644 index 00000000000..fa5a3715f47 Binary files /dev/null and b/tutorials/assets_pipeline/img/cubemap_template_1x6.webp differ diff --git a/tutorials/assets_pipeline/img/cubemap_template_2x3.webp b/tutorials/assets_pipeline/img/cubemap_template_2x3.webp new file mode 100644 index 00000000000..97d1d64a4e6 Binary files /dev/null and b/tutorials/assets_pipeline/img/cubemap_template_2x3.webp differ diff --git a/tutorials/assets_pipeline/img/cubemap_template_3x2.webp b/tutorials/assets_pipeline/img/cubemap_template_3x2.webp new file mode 100644 index 00000000000..df11341baae Binary files /dev/null and b/tutorials/assets_pipeline/img/cubemap_template_3x2.webp differ diff --git a/tutorials/assets_pipeline/img/cubemap_template_6x1.webp b/tutorials/assets_pipeline/img/cubemap_template_6x1.webp new file mode 100644 index 00000000000..7f1be2d77f5 Binary files /dev/null and b/tutorials/assets_pipeline/img/cubemap_template_6x1.webp differ diff --git a/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.rst b/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.rst index e4eac5ccef9..21cc09de021 100644 --- a/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.rst +++ b/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.rst @@ -39,10 +39,12 @@ Exporting textures separately While textures can be exported with a model in certain file formats, such as glTF 2.0, you can also export them separately. Godot uses PBR (physically based rendering) for its materials, so if a texturing program can export PBR -textures they can work in Godot. This includes the `Substance suite `__, +textures, they can work in Godot. This includes the `Substance suite `__, `ArmorPaint (open source) `__, and `Material Maker (open source) `__. -.. note:: For more information on Godot's materials, see :ref:`doc_standard_material_3d`. +.. seealso:: + + For more information on Godot's materials, see :ref:`doc_standard_material_3d`. Exporting considerations ------------------------ diff --git a/tutorials/assets_pipeline/importing_images.rst b/tutorials/assets_pipeline/importing_images.rst index 34934d7b0ca..292e37d60da 100644 --- a/tutorials/assets_pipeline/importing_images.rst +++ b/tutorials/assets_pipeline/importing_images.rst @@ -97,12 +97,21 @@ It is possible to choose other types of imported resources in the Import dock: texture applied onto a 3D surface. Texture3D is similar to a texture array, but with interpolation between layers. Texture3D is typically used for :ref:`class_FogMaterial` density maps in :ref:`volumetric fog - `, :ref:`class_Environment` 3D LUT color correction and - custom shaders. + `, :ref:`particle attractor ` + vector fields, :ref:`class_Environment` 3D LUT color correction, and custom shaders. - **TextureAtlas:** Import the image as an *atlas* of different textures. Can be used to reduce memory usage for animated 2D sprites. Only supported in 2D due to missing support in built-in 3D shaders. +For **Cubemap**, the expected image order is X+, X-, Y+, Y-, Z+, Z- +(in Godot's coordinate system, so Y+ is "up" and Z- is "forward"). +Here are templates you can use for cubemap images (right-click > **Save Link As…**): + +- :download:`2×3 cubemap template (default layout option) ` +- :download:`3×2 cubemap template ` +- :download:`1×6 cubemap template ` +- :download:`6×1 cubemap template ` + Detect 3D ^^^^^^^^^ diff --git a/tutorials/audio/audio_streams.rst b/tutorials/audio/audio_streams.rst index b831fa14ec2..05fdcb8e84c 100644 --- a/tutorials/audio/audio_streams.rst +++ b/tutorials/audio/audio_streams.rst @@ -20,23 +20,32 @@ many places, but is most commonly loaded from the filesystem. Audio files can be loaded as AudioStreams and placed inside an AudioStreamPlayer. You can find information on supported formats and differences in :ref:`doc_importing_audio_samples`. -There are other types of AudioStreams, such as AudioStreamRandomPitch. -This one makes a random adjustment to the sound's pitch every time it's -played back. This can be helpful for adding variation to sounds that are -played back often. +There are other types of AudioStreams, such as :ref:`AudioStreamRandomizer`. +This one picks a different audio stream from a list of streams each time it's played +back, and applies random pitch and volume shifting. This can be helpful for adding +variation to sounds that are played back often. AudioStreamPlayer ----------------- -.. image:: img/audio_stream_player.png +.. image:: img/audio_stream_player.webp This is the standard, non-positional stream player. It can play to any bus. In 5.1 sound setups, it can send audio to stereo mix or front speakers. +Playback Type is an experimental setting, and could change in future versions +of Godot. It exists so Web exports use Web Audio-API based samples instead of +streaming all sounds to the browser, unlike most platforms. This prevents the +audio from being garbled in single-threaded Web exports. By default, only the +Web platform will use samples. Changing this setting is not recommended, unless +you have an explicit reason to. You can change the default playback type +for the web and other platforms in the project settings under **Audio > General** +(advanced settings must be turned on to see the setting). + AudioStreamPlayer2D ------------------- -.. image:: img/audio_stream_2d.png +.. image:: img/audio_stream_2d.webp This is a variant of AudioStreamPlayer, but emits sound in a 2D positional environment. When close to the left of the screen, the panning will go left. @@ -49,20 +58,20 @@ When close to the right side, it will go right. different reverb or sound qualities to handle action happening in a particular parts of your game world. -.. image:: img/audio_stream_2d_area.png +.. image:: img/audio_stream_2d_area.webp AudioStreamPlayer3D ------------------- -.. image:: img/audio_stream_3d.png +.. image:: img/audio_stream_3d.webp This is a variant of AudioStreamPlayer, but emits sound in a 3D positional environment. Depending on the location of the player relative to the screen, it can position sound in stereo, 5.1 or 7.1 depending on the chosen audio setup. -Similar to AudioStreamPlayer2D, an Area can divert the sound to an audio bus. +Similar to AudioStreamPlayer2D, an Area3D can divert the sound to an audio bus. -.. image:: img/audio_stream_3d_area.png +.. image:: img/audio_stream_3d_area.webp Unlike for 2D, the 3D version of AudioStreamPlayer has a few more advanced options: @@ -71,20 +80,20 @@ Unlike for 2D, the 3D version of AudioStreamPlayer has a few more advanced optio Reverb buses ~~~~~~~~~~~~ -Godot allows for 3D audio streams that enter a specific Area node to send dry +Godot allows for 3D audio streams that enter a specific Area3D node to send dry and wet audio to separate buses. This is useful when you have several reverb configurations for different types of rooms. This is done by enabling this type -of reverb in the **Reverb Bus** section of the Area's properties: +of reverb in the **Reverb Bus** section of the Area3D's properties: -.. image:: img/audio_stream_reverb_bus.png +.. image:: img/audio_stream_reverb_bus.webp -At the same time, a special bus layout is created where each area receives the -reverb info from each area. A Reverb effect needs to be created and configured +At the same time, a special bus layout is created where each Area3D receives the +reverb info from each Area3D. A Reverb effect needs to be created and configured in each reverb bus to complete the setup for the desired effect: -.. image:: img/audio_stream_reverb_bus2.png +.. image:: img/audio_stream_reverb_bus2.webp -The Area's **Reverb Bus** section also has a parameter named **Uniformity**. +The Area3D's **Reverb Bus** section also has a parameter named **Uniformity**. Some types of rooms bounce sounds more than others (like a warehouse), so reverberation can be heard almost uniformly across the room even though the source may be far away. Playing around with this parameter can simulate @@ -98,7 +107,7 @@ perceived as an increase or decrease in the pitch of the emitted sound. Godot can track velocity changes in the AudioStreamPlayer3D and Camera nodes. Both nodes have this property, which must be enabled manually: -.. image:: img/audio_stream_doppler.png +.. image:: img/audio_stream_doppler.webp Enable it by setting it depending on how objects will be moved: use **Idle** for objects moved using ``_process``, or **Physics** diff --git a/tutorials/audio/img/audio_stream_2d.png b/tutorials/audio/img/audio_stream_2d.png deleted file mode 100644 index 23f899fbe62..00000000000 Binary files a/tutorials/audio/img/audio_stream_2d.png and /dev/null differ diff --git a/tutorials/audio/img/audio_stream_2d.webp b/tutorials/audio/img/audio_stream_2d.webp new file mode 100644 index 00000000000..c992e521944 Binary files /dev/null and b/tutorials/audio/img/audio_stream_2d.webp differ diff --git a/tutorials/audio/img/audio_stream_2d_area.png b/tutorials/audio/img/audio_stream_2d_area.png deleted file mode 100644 index 4f46a72f6f5..00000000000 Binary files a/tutorials/audio/img/audio_stream_2d_area.png and /dev/null differ diff --git a/tutorials/audio/img/audio_stream_2d_area.webp b/tutorials/audio/img/audio_stream_2d_area.webp new file mode 100644 index 00000000000..e15378f9d76 Binary files /dev/null and b/tutorials/audio/img/audio_stream_2d_area.webp differ diff --git a/tutorials/audio/img/audio_stream_3d.png b/tutorials/audio/img/audio_stream_3d.png deleted file mode 100644 index 200b87435d9..00000000000 Binary files a/tutorials/audio/img/audio_stream_3d.png and /dev/null differ diff --git a/tutorials/audio/img/audio_stream_3d.webp b/tutorials/audio/img/audio_stream_3d.webp new file mode 100644 index 00000000000..f2ad40bfb43 Binary files /dev/null and b/tutorials/audio/img/audio_stream_3d.webp differ diff --git a/tutorials/audio/img/audio_stream_3d_area.png b/tutorials/audio/img/audio_stream_3d_area.png deleted file mode 100644 index 86f8b951669..00000000000 Binary files a/tutorials/audio/img/audio_stream_3d_area.png and /dev/null differ diff --git a/tutorials/audio/img/audio_stream_3d_area.webp b/tutorials/audio/img/audio_stream_3d_area.webp new file mode 100644 index 00000000000..3f6e9dbda9c Binary files /dev/null and b/tutorials/audio/img/audio_stream_3d_area.webp differ diff --git a/tutorials/audio/img/audio_stream_doppler.png b/tutorials/audio/img/audio_stream_doppler.png deleted file mode 100644 index 4c7bf2bd7bb..00000000000 Binary files a/tutorials/audio/img/audio_stream_doppler.png and /dev/null differ diff --git a/tutorials/audio/img/audio_stream_doppler.webp b/tutorials/audio/img/audio_stream_doppler.webp new file mode 100644 index 00000000000..f540dc11044 Binary files /dev/null and b/tutorials/audio/img/audio_stream_doppler.webp differ diff --git a/tutorials/audio/img/audio_stream_player.png b/tutorials/audio/img/audio_stream_player.png deleted file mode 100644 index b70011e8aff..00000000000 Binary files a/tutorials/audio/img/audio_stream_player.png and /dev/null differ diff --git a/tutorials/audio/img/audio_stream_player.webp b/tutorials/audio/img/audio_stream_player.webp new file mode 100644 index 00000000000..855471b543f Binary files /dev/null and b/tutorials/audio/img/audio_stream_player.webp differ diff --git a/tutorials/audio/img/audio_stream_reverb_bus.png b/tutorials/audio/img/audio_stream_reverb_bus.png deleted file mode 100644 index d7eb794201d..00000000000 Binary files a/tutorials/audio/img/audio_stream_reverb_bus.png and /dev/null differ diff --git a/tutorials/audio/img/audio_stream_reverb_bus.webp b/tutorials/audio/img/audio_stream_reverb_bus.webp new file mode 100644 index 00000000000..4fc921662d7 Binary files /dev/null and b/tutorials/audio/img/audio_stream_reverb_bus.webp differ diff --git a/tutorials/audio/img/audio_stream_reverb_bus2.png b/tutorials/audio/img/audio_stream_reverb_bus2.png deleted file mode 100644 index 726104adb5f..00000000000 Binary files a/tutorials/audio/img/audio_stream_reverb_bus2.png and /dev/null differ diff --git a/tutorials/audio/img/audio_stream_reverb_bus2.webp b/tutorials/audio/img/audio_stream_reverb_bus2.webp new file mode 100644 index 00000000000..265ed211a24 Binary files /dev/null and b/tutorials/audio/img/audio_stream_reverb_bus2.webp differ diff --git a/tutorials/best_practices/autoloads_versus_internal_nodes.rst b/tutorials/best_practices/autoloads_versus_internal_nodes.rst index 48664a26a59..2f8b10a92a9 100644 --- a/tutorials/best_practices/autoloads_versus_internal_nodes.rst +++ b/tutorials/best_practices/autoloads_versus_internal_nodes.rst @@ -87,7 +87,7 @@ limitation of static functions is that they can't reference member variables, non-static functions or ``self``. Since Godot 4.1, GDScript also supports ``static`` variables using ``static var``. -This means you can now share a variables across instances of a class without +This means you can now share variables across instances of a class without having to create a separate autoload. Still, autoloaded nodes can simplify your code for systems with a wide scope. If diff --git a/tutorials/best_practices/data_preferences.rst b/tutorials/best_practices/data_preferences.rst index 2595fd7ba72..7bd718267c0 100644 --- a/tutorials/best_practices/data_preferences.rst +++ b/tutorials/best_practices/data_preferences.rst @@ -240,7 +240,7 @@ tree structures. class_name TreeNode var _parent: TreeNode = null - var _children: = [] setget + var _children := [] func _notification(p_what): match p_what: @@ -283,7 +283,7 @@ Enumerations: int vs. string Most languages offer an enumeration type option. GDScript is no different, but unlike most other languages, it allows one to use either integers or strings for -the enum values (the latter only when using the ``export`` keyword in GDScript). +the enum values (the latter only when using the ``@export_enum`` annotation in GDScript). The question then arises, "which should one use?" The short answer is, "whichever you are more comfortable with." This @@ -329,7 +329,7 @@ the other :ref:`Node ` objects discussed here. One might create a :ref:`Sprite2D ` node that uses AnimatedTexture as its texture. Or (something the others can't do) one could add AnimatedTextures as tiles in a :ref:`TileSet ` and integrate it with a -:ref:`TileMap ` for many auto-animating backgrounds that +:ref:`TileMapLayer ` for many auto-animating backgrounds that all render in a single batched draw call. The AnimatedSprite2D node, in combination with the diff --git a/tutorials/best_practices/logic_preferences.rst b/tutorials/best_practices/logic_preferences.rst index 2f61ebcd417..6f5901fd28c 100644 --- a/tutorials/best_practices/logic_preferences.rst +++ b/tutorials/best_practices/logic_preferences.rst @@ -119,7 +119,7 @@ consider: in exceptional cases, one may wish not to do this: 1. If the 'imported' class is liable to change, then it should be a property - instead, initialized either using an ``export`` or a ``load()`` (and + instead, initialized either using an ``@export`` or a ``load()`` (and perhaps not even initialized until later). 2. If the script requires a great many dependencies, and one does not wish diff --git a/tutorials/best_practices/scene_organization.rst b/tutorials/best_practices/scene_organization.rst index d05771fb4d9..c03914f9a18 100644 --- a/tutorials/best_practices/scene_organization.rst +++ b/tutorials/best_practices/scene_organization.rst @@ -4,7 +4,7 @@ Scene organization ================== This article covers topics related to the effective organization of -scene content. Which nodes should one use? Where should one place them? +scene content. Which nodes should you use? Where should you place them? How should they interact? How to build relationships effectively @@ -21,10 +21,9 @@ possible. Re-using the scene in multiple places creates issues because the node paths do not find their targets and signal connections established in the editor break. -To fix these problems, one must instantiate the sub-scenes without them -requiring details about their environment. One needs to be able to trust -that the sub-scene will create itself without being picky about how one uses -it. +To fix these problems, you must instantiate the sub-scenes without them +requiring details about their environment. You need to be able to trust +that the sub-scene will create itself without being picky about how it's used. One of the biggest things to consider in OOP is maintaining focused, singular-purpose classes with @@ -35,8 +34,8 @@ maintainability) and improves their reusability. These OOP best practices have *several* implications for best practices in scene structure and script usage. -**If at all possible, one should design scenes to have no dependencies.** -That is, one should create scenes that keep everything they need within +**If at all possible, you should design scenes to have no dependencies.** +That is, you should create scenes that keep everything they need within themselves. If a scene must interact with an external context, experienced developers @@ -46,7 +45,7 @@ This technique involves having a high-level API provide the dependencies of the low-level API. Why do this? Because classes which rely on their external environment can inadvertently trigger bugs and unexpected behavior. -To do this, one must expose data and then rely on a parent context to +To do this, you must expose data and then rely on a parent context to initialize it: 1. Connect to a signal. Extremely safe, but should be used only to "respond" to @@ -148,14 +147,14 @@ initialize it: GetNode(TargetPath); // Use parent-defined NodePath. These options hide the points of access from the child node. This in turn -keeps the child **loosely coupled** to its environment. One can reuse it +keeps the child **loosely coupled** to its environment. You can reuse it in another context without any extra changes to its API. .. note:: Although the examples above illustrate parent-child relationships, the same principles apply towards all object relations. Nodes which - are siblings should only be aware of their hierarchies while an ancestor + are siblings should only be aware of their own hierarchies while an ancestor mediates their communications and references. .. tabs:: @@ -201,21 +200,21 @@ in another context without any extra changes to its API. } The same principles also apply to non-Node objects that maintain dependencies - on other objects. Whichever object actually owns the objects should manage + on other objects. Whichever object owns the other objects should manage the relationships between them. .. warning:: - One should favor keeping data in-house (internal to a scene) though as + You should favor keeping data in-house (internal to a scene), though, as placing a dependency on an external context, even a loosely coupled one, still means that the node will expect something in its environment to be true. The project's design philosophies should prevent this from happening. If not, the code's inherent liabilities will force developers to use documentation to keep track of object relations on a microscopic scale; this is otherwise known as development hell. Writing code that relies on external - documentation for one to use it safely is error-prone by default. + documentation to use it safely is error-prone by default. - To avoid creating and maintaining such documentation, one converts the + To avoid creating and maintaining such documentation, you convert the dependent node ("child" above) into a tool script that implements ``_get_configuration_warnings()``. Returning a non-empty PackedStringArray from it will make the Scene dock generate a @@ -234,7 +233,7 @@ in another context without any extra changes to its API. So, why does all this complex switcheroo work? Well, because scenes operate best when they operate alone. If unable to work alone, then working with others anonymously (with minimal hard dependencies, i.e. loose coupling) -is the next best thing. Inevitably, changes may need to be made to a class and +is the next best thing. Inevitably, changes may need to be made to a class, and if these changes cause it to interact with other scenes in unforeseen ways, then things will start to break down. The whole point of all this indirection is to avoid ending up in a situation where changing one class results in @@ -251,44 +250,43 @@ by *all* OOP principles. Examples include... Choosing a node tree structure ------------------------------ -So, a developer starts work on a game only to stop at the vast possibilities -before them. They might know what they want to do, what systems they want to -have, but *where* to put them all? Well, how one goes about making their game -is always up to them. One can construct node trees in countless ways. -But, for those who are unsure, this helpful guide can give them a sample of -a decent structure to start with. +You might start to work on a game but get overwhelmed by the vast possibilities +before you. You might know what you want to do, what systems you want to +have, but *where* do you put them all? How you go about making your game +is always up to you. You can construct node trees in countless ways. +If you are unsure, this guide can give you a sample of a decent structure to +start with. -A game should always have a sort of "entry point"; somewhere the developer can -definitively track where things begin so that they can follow the logic as it -continues elsewhere. This place also serves as a bird's eye view of all of the -other data and logic in the program. For traditional applications, this would -be the "main" function. In this case, it would be a Main node. +A game should always have an "entry point"; somewhere you can definitively +track where things begin so that you can follow the logic as it continues +elsewhere. It also serves as a bird's eye view of all other data and logic +in the program. For traditional applications, this is normally a "main" +function. In Godot, it's a Main node. - Node "Main" (main.gd) -The ``main.gd`` script would then serve as the primary controller of one's -game. +The ``main.gd`` script will serve as the primary controller of your game. -Then one has their actual in-game "World" (a 2D or 3D one). This can be a child -of Main. In addition, one will need a primary GUI for their game that manages +Then you have an in-game "World" (a 2D or 3D one). This can be a child +of Main. In addition, you will need a primary GUI for your game that manages the various menus and widgets the project needs. - Node "Main" (main.gd) - Node2D/Node3D "World" (game_world.gd) - Control "GUI" (gui.gd) -When changing levels, one can then swap out the children of the "World" node. -:ref:`Changing scenes manually ` gives users full -control over how their game world transitions. +When changing levels, you can then swap out the children of the "World" node. +:ref:`Changing scenes manually ` gives you full +control over how your game world transitions. -The next step is to consider what gameplay systems one's project requires. -If one has a system that... +The next step is to consider what gameplay systems your project requires. +If you have a system that... 1. tracks all of its data internally 2. should be globally accessible 3. should exist in isolation -... then one should create an :ref:`autoload 'singleton' node `. +... then you should create an :ref:`autoload 'singleton' node `. .. note:: @@ -298,27 +296,24 @@ If one has a system that... to swap out the main scene's content. This structure more or less keeps the "World" as the main game node. - Any GUI would need to also be a - singleton; be a transitory part of the "World"; or be manually added as a - direct child of the root. Otherwise, the GUI nodes would also delete - themselves during scene transitions. + Any GUI would also need to be either a singleton, a transitory part of the + "World", or manually added as a direct child of the root. Otherwise, the + GUI nodes would also delete themselves during scene transitions. -If one has systems that modify other systems' data, one should define those as -their own scripts or scenes rather than autoloads. For more information on the -reasons, please see the -:ref:`Autoloads versus regular nodes ` -documentation. +If you have systems that modify other systems' data, you should define those as +their own scripts or scenes, rather than autoloads. For more information, see +:ref:`Autoloads versus regular nodes `. -Each subsystem within one's game should have its own section within the -SceneTree. One should use parent-child relationships only in cases where nodes +Each subsystem within your game should have its own section within the +SceneTree. You should use parent-child relationships only in cases where nodes are effectively elements of their parents. Does removing the parent reasonably -mean that one should also remove the children? If not, then it should have its +mean that the children should also be removed? If not, then it should have its own place in the hierarchy as a sibling or some other relation. .. note:: - In some cases, one needs these separated nodes to *also* position themselves - relative to each other. One can use the + In some cases, you need these separated nodes to *also* position themselves + relative to each other. You can use the :ref:`RemoteTransform ` / :ref:`RemoteTransform2D ` nodes for this purpose. They will allow a target node to conditionally inherit selected transform @@ -326,50 +321,51 @@ own place in the hierarchy as a sibling or some other relation. :ref:`NodePath `, use one of the following: 1. A reliable third party, likely a parent node, to mediate the assignment. - 2. A group, to easily pull a reference to the desired node (assuming there + 2. A group, to pull a reference to the desired node (assuming there will only ever be one of the targets). - When should one do this? Well, this is subjective. The dilemma arises when - one must micro-manage when a node must move around the SceneTree to preserve + When you should do this is subjective. The dilemma arises when you must + micro-manage when a node must move around the SceneTree to preserve itself. For example... - Add a "player" node to a "room". - - Need to change rooms, so one must delete the current room. - - Before the room can be deleted, one must preserve and/or move the player. + - Need to change rooms, so you must delete the current room. + - Before the room can be deleted, you must preserve and/or move the player. - Is memory a concern? + If memory is not a concern, you can... - - If not, one can just create the two rooms, move the player - and delete the old one. No problem. + - Create the new room. + - Move the player to the new room. + - Delete the old room. - If so, one will need to... + If memory is a concern, instead you will need to... - Move the player somewhere else in the tree. - Delete the room. - Instantiate and add the new room. - - Re-add the player. + - Re-add the player to the new room. - The issue is that the player here is a "special case"; one where the + The issue is that the player here is a "special case" where the developers must *know* that they need to handle the player this way for the - project. As such, the only way to reliably share this information as a team - is to *document* it. Keeping implementation details in documentation however - is dangerous. It's a maintenance burden, strains code readability, and bloats - the intellectual content of a project unnecessarily. + project. The only way to reliably share this information as a team + is to *document* it. Keeping implementation details in documentation is + dangerous. It's a maintenance burden, strains code readability, and + unnecessarily bloats the intellectual content of a project. - In a more complex game with larger assets, it can be a better idea to simply - keep the player somewhere else in the SceneTree entirely. This results in: + In a more complex game with larger assets, it can be a better idea to keep + the player somewhere else in the SceneTree entirely. This results in: 1. More consistency. 2. No "special cases" that must be documented and maintained somewhere. 3. No opportunity for errors to occur because these details are not accounted for. - In contrast, if one ever needs to have a child node that does *not* inherit - the transform of their parent, one has the following options: + In contrast, if you ever need a child node that does *not* inherit + the transform of its parent, you have the following options: 1. The **declarative** solution: place a :ref:`Node ` in between - them. As nodes with no transform, Nodes will not pass along such - information to their children. + them. Since it doesn't have a transform, they won't pass this information + to its children. 2. The **imperative** solution: Use the ``top_level`` property for the :ref:`CanvasItem ` or :ref:`Node3D ` node. This will make @@ -380,9 +376,9 @@ own place in the hierarchy as a sibling or some other relation. If building a networked game, keep in mind which nodes and gameplay systems are relevant to all players versus those just pertinent to the authoritative server. For example, users do not all need to have a copy of every players' - "PlayerController" logic. Instead, they need only their own. As such, keeping - these in a separate branch from the "world" can help simplify the management - of game connections and the like. + "PlayerController" logic - they only need their own. Keeping them in a + separate branch from the "world" can help simplify the management of game + connections and the like. The key to scene organization is to consider the SceneTree in relational terms rather than spatial terms. Are the nodes dependent on their parent's existence? @@ -392,5 +388,5 @@ that parent (and likely part of that parent's scene if they aren't already). Does this mean nodes themselves are components? Not at all. Godot's node trees form an aggregation relationship, not one of composition. -But while one still has the flexibility to move nodes around, it is still best +But while you still have the flexibility to move nodes around, it is still best when such moves are unnecessary by default. diff --git a/tutorials/editor/command_line_tutorial.rst b/tutorials/editor/command_line_tutorial.rst index 4a0e6ff14b6..f240b54bfaf 100644 --- a/tutorials/editor/command_line_tutorial.rst +++ b/tutorials/editor/command_line_tutorial.rst @@ -245,6 +245,9 @@ available in the ``PATH``: .. code-tab:: sh Windows + # Add "Extras" bucket + scoop bucket add extras + # Standard editor: scoop install godot diff --git a/tutorials/editor/customizing_editor.rst b/tutorials/editor/customizing_editor.rst index fa844fd7855..a0d8d0fd0b2 100644 --- a/tutorials/editor/customizing_editor.rst +++ b/tutorials/editor/customizing_editor.rst @@ -7,6 +7,8 @@ Godot's interface lives in a single window by default. Since Godot 4.0, you can split several elements to separate windows to better make use of multi-monitor setups. +.. _doc_customizing_editor_moving_docks: + Moving and resizing docks ------------------------- diff --git a/tutorials/editor/default_key_mapping.rst b/tutorials/editor/default_key_mapping.rst index 70640c85899..f5f2a9ea448 100644 --- a/tutorials/editor/default_key_mapping.rst +++ b/tutorials/editor/default_key_mapping.rst @@ -140,6 +140,8 @@ General Editor Actions | Clear Pose | :kbd:`Shift + K` | :kbd:`Shift + K` | ``canvas_item_editor/anim_clear_pose`` | +------------------------------+-------------------------+------------------------+--------------------------------------------------------+ +.. _doc_default_key_mapping_shortcuts_spatial_editor: + 3D / Spatial Editor ------------------- @@ -218,83 +220,85 @@ General Editor Actions Text Editor ----------- -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Action name | Windows, Linux | macOS | Editor setting | -+===========================+==========================+============================+=================================================+ -| Cut | :kbd:`Ctrl + X` | :kbd:`Cmd + X` | ``script_text_editor/cut`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Copy | :kbd:`Ctrl + C` | :kbd:`Cmd + C` | ``script_text_editor/copy`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Paste | :kbd:`Ctrl + V` | :kbd:`Cmd + V` | ``script_text_editor/paste`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Select All | :kbd:`Ctrl + A` | :kbd:`Cmd + A` | ``script_text_editor/select_all`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Find | :kbd:`Ctrl + F` | :kbd:`Cmd + F` | ``script_text_editor/find`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Find Next | :kbd:`F3` | :kbd:`Cmd + G` | ``script_text_editor/find_next`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Find Previous | :kbd:`Shift + F3` | :kbd:`Cmd + Shift + G` | ``script_text_editor/find_previous`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Find in Files | :kbd:`Ctrl + Shift + F` | :kbd:`Cmd + Shift + F` | ``script_text_editor/find_in_files`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Replace | :kbd:`Ctrl + R` | :kbd:`Opt + Cmd + F` | ``script_text_editor/replace`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Replace in Files | :kbd:`Ctrl + Shift + R` | :kbd:`Cmd + Shift + R` | ``script_text_editor/replace_in_files`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Undo | :kbd:`Ctrl + Z` | :kbd:`Cmd + Z` | ``script_text_editor/undo`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Redo | :kbd:`Ctrl + Y` | :kbd:`Cmd + Y` | ``script_text_editor/redo`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Move Up | :kbd:`Alt + Up Arrow` | :kbd:`Opt + Up Arrow` | ``script_text_editor/move_up`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Move Down | :kbd:`Alt + Down Arrow` | :kbd:`Opt + Down Arrow` | ``script_text_editor/move_down`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Delete Line | :kbd:`Ctrl + Shift + K` | :kbd:`Cmd + Shift + K` | ``script_text_editor/delete_line`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Toggle Comment | :kbd:`Ctrl + K` | :kbd:`Cmd + K` | ``script_text_editor/toggle_comment`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Fold/Unfold Line | :kbd:`Alt + F` | :kbd:`Ctrl + Cmd + F` | ``script_text_editor/toggle_fold_line`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Duplicate Selection | :kbd:`Ctrl + Shift + D` | :kbd:`Cmd + Shift + C` | ``script_text_editor/duplicate_selection`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Complete Symbol | :kbd:`Ctrl + Space` | :kbd:`Ctrl + Space` | ``script_text_editor/complete_symbol`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Evaluate Selection | :kbd:`Ctrl + Shift + E` | :kbd:`Cmd + Shift + E` | ``script_text_editor/evaluate_selection`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Trim Trailing Whitespace | :kbd:`Ctrl + Alt + T` | :kbd:`Opt + Cmd + T` | ``script_text_editor/trim_trailing_whitespace`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Uppercase | :kbd:`Shift + F4` | :kbd:`Shift + F4` | ``script_text_editor/convert_to_uppercase`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Lowercase | :kbd:`Shift + F5` | :kbd:`Shift + F5` | ``script_text_editor/convert_to_lowercase`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Capitalize | :kbd:`Shift + F6` | :kbd:`Shift + F6` | ``script_text_editor/capitalize`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Convert Indent to Spaces | :kbd:`Ctrl + Shift + Y` | :kbd:`Cmd + Shift + Y` | ``script_text_editor/convert_indent_to_spaces`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Convert Indent to Tabs | :kbd:`Ctrl + Shift + I` | :kbd:`Cmd + Shift + I` | ``script_text_editor/convert_indent_to_tabs`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Auto Indent | :kbd:`Ctrl + I` | :kbd:`Cmd + I` | ``script_text_editor/auto_indent`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Toggle Bookmark | :kbd:`Ctrl + Alt + B` | :kbd:`Opt + Cmd + B` | ``script_text_editor/toggle_bookmark`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Go to Next Bookmark | :kbd:`Ctrl + B` | :kbd:`Cmd + B` | ``script_text_editor/goto_next_bookmark`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Go to Previous Bookmark | :kbd:`Ctrl + Shift + B` | :kbd:`Cmd + Shift + B` | ``script_text_editor/goto_previous_bookmark`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Go to Function | :kbd:`Ctrl + Alt + F` | :kbd:`Ctrl + Cmd + J` | ``script_text_editor/goto_function`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Go to Line | :kbd:`Ctrl + L` | :kbd:`Cmd + L` | ``script_text_editor/goto_line`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Toggle Breakpoint | :kbd:`F9` | :kbd:`Cmd + Shift + B` | ``script_text_editor/toggle_breakpoint`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Remove All Breakpoints | :kbd:`Ctrl + Shift + F9` | :kbd:`Cmd + Shift + F9` | ``script_text_editor/remove_all_breakpoints`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Go to Next Breakpoint | :kbd:`Ctrl + .` | :kbd:`Cmd + .` | ``script_text_editor/goto_next_breakpoint`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Go to Previous Breakpoint | :kbd:`Ctrl + ,` | :kbd:`Cmd + ,` | ``script_text_editor/goto_previous_breakpoint`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ -| Contextual Help | :kbd:`Alt + F1` | :kbd:`Opt + Shift + Space` | ``script_text_editor/contextual_help`` | -+---------------------------+--------------------------+----------------------------+-------------------------------------------------+ ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Action name | Windows, Linux | macOS | Editor setting | ++===========================+=================================+==================================+=================================================+ +| Cut | :kbd:`Ctrl + X` | :kbd:`Cmd + X` | ``script_text_editor/cut`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Copy | :kbd:`Ctrl + C` | :kbd:`Cmd + C` | ``script_text_editor/copy`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Paste | :kbd:`Ctrl + V` | :kbd:`Cmd + V` | ``script_text_editor/paste`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Select All | :kbd:`Ctrl + A` | :kbd:`Cmd + A` | ``script_text_editor/select_all`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Find | :kbd:`Ctrl + F` | :kbd:`Cmd + F` | ``script_text_editor/find`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Find Next | :kbd:`F3` | :kbd:`Cmd + G` | ``script_text_editor/find_next`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Find Previous | :kbd:`Shift + F3` | :kbd:`Cmd + Shift + G` | ``script_text_editor/find_previous`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Find in Files | :kbd:`Ctrl + Shift + F` | :kbd:`Cmd + Shift + F` | ``script_text_editor/find_in_files`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Replace | :kbd:`Ctrl + R` | :kbd:`Opt + Cmd + F` | ``script_text_editor/replace`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Replace in Files | :kbd:`Ctrl + Shift + R` | :kbd:`Cmd + Shift + R` | ``script_text_editor/replace_in_files`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Undo | :kbd:`Ctrl + Z` | :kbd:`Cmd + Z` | ``script_text_editor/undo`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Redo | :kbd:`Ctrl + Y` | :kbd:`Cmd + Y` | ``script_text_editor/redo`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Move Up | :kbd:`Alt + Up Arrow` | :kbd:`Opt + Up Arrow` | ``script_text_editor/move_up`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Move Down | :kbd:`Alt + Down Arrow` | :kbd:`Opt + Down Arrow` | ``script_text_editor/move_down`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Delete Line | :kbd:`Ctrl + Shift + K` | :kbd:`Cmd + Shift + K` | ``script_text_editor/delete_line`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Toggle Comment | :kbd:`Ctrl + K` | :kbd:`Cmd + K` | ``script_text_editor/toggle_comment`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Fold/Unfold Line | :kbd:`Alt + F` | :kbd:`Ctrl + Cmd + F` | ``script_text_editor/toggle_fold_line`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Duplicate Lines | :kbd:`Ctrl + Alt + Down Arrow` | :kbd:`Cmd + Shift + Down Arrow` | ``script_text_editor/duplicate_lines`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Duplicate Selection | :kbd:`Ctrl + Shift + D` | :kbd:`Cmd + Shift + C` | ``script_text_editor/duplicate_selection`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Complete Symbol | :kbd:`Ctrl + Space` | :kbd:`Ctrl + Space` | ``script_text_editor/complete_symbol`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Evaluate Selection | :kbd:`Ctrl + Shift + E` | :kbd:`Cmd + Shift + E` | ``script_text_editor/evaluate_selection`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Trim Trailing Whitespace | :kbd:`Ctrl + Alt + T` | :kbd:`Opt + Cmd + T` | ``script_text_editor/trim_trailing_whitespace`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Uppercase | :kbd:`Shift + F4` | :kbd:`Shift + F4` | ``script_text_editor/convert_to_uppercase`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Lowercase | :kbd:`Shift + F5` | :kbd:`Shift + F5` | ``script_text_editor/convert_to_lowercase`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Capitalize | :kbd:`Shift + F6` | :kbd:`Shift + F6` | ``script_text_editor/capitalize`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Convert Indent to Spaces | :kbd:`Ctrl + Shift + Y` | :kbd:`Cmd + Shift + Y` | ``script_text_editor/convert_indent_to_spaces`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Convert Indent to Tabs | :kbd:`Ctrl + Shift + I` | :kbd:`Cmd + Shift + I` | ``script_text_editor/convert_indent_to_tabs`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Auto Indent | :kbd:`Ctrl + I` | :kbd:`Cmd + I` | ``script_text_editor/auto_indent`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Toggle Bookmark | :kbd:`Ctrl + Alt + B` | :kbd:`Opt + Cmd + B` | ``script_text_editor/toggle_bookmark`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Go to Next Bookmark | :kbd:`Ctrl + B` | :kbd:`Cmd + B` | ``script_text_editor/goto_next_bookmark`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Go to Previous Bookmark | :kbd:`Ctrl + Shift + B` | :kbd:`Cmd + Shift + B` | ``script_text_editor/goto_previous_bookmark`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Go to Function | :kbd:`Ctrl + Alt + F` | :kbd:`Ctrl + Cmd + J` | ``script_text_editor/goto_function`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Go to Line | :kbd:`Ctrl + L` | :kbd:`Cmd + L` | ``script_text_editor/goto_line`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Toggle Breakpoint | :kbd:`F9` | :kbd:`Cmd + Shift + B` | ``script_text_editor/toggle_breakpoint`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Remove All Breakpoints | :kbd:`Ctrl + Shift + F9` | :kbd:`Cmd + Shift + F9` | ``script_text_editor/remove_all_breakpoints`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Go to Next Breakpoint | :kbd:`Ctrl + .` | :kbd:`Cmd + .` | ``script_text_editor/goto_next_breakpoint`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Go to Previous Breakpoint | :kbd:`Ctrl + ,` | :kbd:`Cmd + ,` | ``script_text_editor/goto_previous_breakpoint`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ +| Contextual Help | :kbd:`Alt + F1` | :kbd:`Opt + Shift + Space` | ``script_text_editor/contextual_help`` | ++---------------------------+---------------------------------+----------------------------------+-------------------------------------------------+ Script Editor ------------- diff --git a/tutorials/editor/img/editor_ui_intro_project_manager_05.webp b/tutorials/editor/img/editor_ui_intro_project_manager_05.webp index d5879b143eb..c1d020ea07b 100644 Binary files a/tutorials/editor/img/editor_ui_intro_project_manager_05.webp and b/tutorials/editor/img/editor_ui_intro_project_manager_05.webp differ diff --git a/tutorials/editor/img/editor_ui_intro_project_manager_08.webp b/tutorials/editor/img/editor_ui_intro_project_manager_08.webp index 5472566973b..d2b1260d10b 100644 Binary files a/tutorials/editor/img/editor_ui_intro_project_manager_08.webp and b/tutorials/editor/img/editor_ui_intro_project_manager_08.webp differ diff --git a/tutorials/editor/img/editor_ui_intro_project_manager_10.webp b/tutorials/editor/img/editor_ui_intro_project_manager_10.webp index 0a80a704fb6..1702b588b84 100644 Binary files a/tutorials/editor/img/editor_ui_intro_project_manager_10.webp and b/tutorials/editor/img/editor_ui_intro_project_manager_10.webp differ diff --git a/tutorials/editor/index.rst b/tutorials/editor/index.rst index 9e2345ca0d0..07974f9b7bd 100644 --- a/tutorials/editor/index.rst +++ b/tutorials/editor/index.rst @@ -1,6 +1,8 @@ :allow_comments: False :article_outdated: True +.. _doc_editor_introduction: + Editor introduction =================== diff --git a/tutorials/editor/project_manager.rst b/tutorials/editor/project_manager.rst index 45eaab2aebc..7e559759470 100644 --- a/tutorials/editor/project_manager.rst +++ b/tutorials/editor/project_manager.rst @@ -4,16 +4,24 @@ Using the Project Manager ========================= When you launch Godot, the first window you see is the Project Manager. It lets -you create, remove, import, or play game projects. +you create, remove, import, or play game projects: .. image:: img/editor_ui_intro_project_manager_01.webp -To change the editors language click on the "Settings" Button in the top right -corner. +To change the editors language click on the **Settings** Button in the top right +corner: .. image:: img/editor_ui_intro_project_manager_02.webp -Then on the settings page seelct the language you want from the dropdown menu. +In Project Manager Settings, you can change the interface **language** from the language +dropdown menu, which is the system default language by default. + +You can also change the **theme** of the editor, the **display scale** for different interface +element sizes, and the availability of online functionality using **network mode**. +If network mode is online, Godot will also check and inform you about new versions of Godot. + +The **directory naming convention** can also be changed to replace spaces according to the chosen format +when creating folders automatically. .. image:: img/editor_ui_intro_project_manager_10.webp @@ -24,24 +32,42 @@ Creating and importing projects To create a new project: -1. Click the **New** button on the top-left of the window. +1. Click the **Create** button on the top-left of the window. 2. Give the project a name, choose an empty folder on your computer to save the - files, and select a rendering backend. -3. Click the **Create & Edit** button to create the project folder and open it in the editor. + files. Alternatively, you can enable **Create Folder** option to automatically create + a new sub-folder with the project name, following the directory naming convention + set in the settings. An empty folder will show a green tick on the right. +3. Select one of the rendering backends (this can also be changed later). +4. Click the **Create & Edit** button to create the project folder and open it in the editor. .. image:: img/editor_ui_intro_project_manager_04.webp +.. note:: You can optionally choose a version control system. Currently, only + `git `__ is supported and it needs the Godot Git Plugin to be installed, + either manually or using the :ref:`Asset Library `. To learn more about the Godot Git Plugin, see its `wiki `__. + Using the file browser ~~~~~~~~~~~~~~~~~~~~~~ -Click the **Browse** button to open Godot's file browser and pick a location or type -the folder's path in the Project Path field. +Click the **Browse** button to open Godot's file browser. +You can pick a location or type the folder's path in the **Path** field, after choosing a drive. -.. image:: img/editor_ui_intro_project_manager_05.webp +Left of the path field on the top row contains arrows to navigate backward and forward through the last +visited locations. +The up arrow navigates to parent folder. +On the right side of the path field, there are buttons to refresh the current folder's contents, +favorite/unfavorite the current folder, and show/hide hidden folders. + +Next, the buttons to switch the display type of the folders and files between grid view and list view +are seen. + +The last button on the right will create a new folder. -When you see the green tick on the right, it means the engine detects an empty -folder. You can also click the **Create Folder** button to create an empty -folder based on your project's name. +Favorited folders will be displayed on the left side under the **Favorites** section. You can sort the +favorites using the up and down buttons in this section. +Last chosen folders will be listed under the **Recent** list. + +.. image:: img/editor_ui_intro_project_manager_05.webp Opening and importing projects ------------------------------ @@ -57,22 +83,26 @@ edit it. .. image:: img/editor_ui_intro_project_manager_08.webp +Alternatively, it is possible to choose a zip file to be automatically extracted by Godot. + When the folder path is correct, you'll see a green checkmark. .. image:: img/editor_ui_intro_project_manager_09.webp +.. _doc_project_manager_downloading_demos: + Downloading demos and templates ------------------------------- -From the **Asset Library Projects** tab you can download open source project -templates and demos from the :ref:`Asset Library ` to help +From the **Asset Library** tab you can download open source project +templates and demos from the :ref:`Asset Library ` to help you get started faster. The first time you open this tab you'll notice that it's asking you to go online. For privacy reasons the project manager, and Godot editor, can't access the internet -by default. To enable accessing the internet click the "Go Online" button. This will +by default. To enable accessing the internet click the **Go Online** button. This will also allow project manager to notify you about updates. If you wish to turn this off -in the future go into project manager settings and change "Network Mode" to "Offline" +in the future go into project manager settings and change **Network Mode** to "Offline" Now that Godot is connected to the internet you can download a demo or template, to do this: @@ -89,7 +119,7 @@ Managing projects with tags For users with a lot of projects on one PC it can be a lot to keep track of. To aid in this Godot allows you to create project tags. To add a tag to a project click on the -project in the project manager, then click on the "Manage Tags" button +project in the project manager, then click on the **Manage Tags** button .. image:: img/editor_ui_intro_project_manager_11.webp @@ -97,10 +127,17 @@ This will open up the manage project tags window. To add a tag click the plus bu .. image:: img/editor_ui_intro_project_manager_12.webp -type out the tag name, and click "ok". Your project will now have a tag added to it. -These tags can be used for any other project in your project manager. In addition tags -will stay with projects. So if you tag your project, send it to another machine and -import it into the project manager you will see the tags you created. +Type out the tag name, and click **OK**. Your project will now have a tag added to it. +These tags can be used for any other project in your project manager. + +To show projects with a specific tag only, you can click on the tags or write ``tag:`` +and type the tag you would like to search for in the filter bar. To limit the results +using multiple tags, you can click on another tag or add ``tag:`` after +a space and type another tag in the filter bar. + +In addition, tags will stay with projects. So if you tag your project, send it to +another machine, and import it into the project manager you will see the tags +you created. To remove a tag from your project manager it must be removed from all the projects it's used by. Once that's done close the project manager, open it up again, and the tag should diff --git a/tutorials/editor/using_the_android_editor.rst b/tutorials/editor/using_the_android_editor.rst index 04b8804ffb1..a8848f37d90 100644 --- a/tutorials/editor/using_the_android_editor.rst +++ b/tutorials/editor/using_the_android_editor.rst @@ -9,7 +9,7 @@ that can be used to work on new or existing projects on Android devices. .. note:: - The Android editor is in beta testing stage, while we continue to refine the experience, + The Android editor is in early access, while we continue to refine the experience, and bring it up to parity with the Desktop version of the editor. See :ref:`doc_using_the_android_editor_limitations` below. Android devices support @@ -41,7 +41,6 @@ Here are the known limitations and issues of the Android editor: - No support for building and exporting an Android APK binary. As a workaround, you can generate and export a `Godot PCK or ZIP file `__ - No support for building and exporting binaries for other platforms -- Performance and stability issues when using the *Vulkan Mobile* renderer for a project - UX not optimized for Android phones form-factor - `Android Go devices `__ lacks the *All files access* permission required for device read/write access. diff --git a/tutorials/export/exporting_for_android.rst b/tutorials/export/exporting_for_android.rst index 6ca4e3b10d7..2ba96076477 100644 --- a/tutorials/export/exporting_for_android.rst +++ b/tutorials/export/exporting_for_android.rst @@ -28,15 +28,18 @@ Download the Android SDK Download and install the Android SDK. -- You can install the Android SDK using `Android Studio Hedgehog (version 2023.1.1) or later `__. +- You can install the Android SDK using `Android Studio Iguana (version 2023.2.1) or later `__. - Run it once to complete the SDK setup using these `instructions `__. - - Ensure that the `required packages `__ are installed as well. + - Ensure that the `required packages `__ are installed as well. - Android SDK Platform-Tools version 34.0.0 or later - Android SDK Build-Tools version 34.0.0 - Android SDK Platform 34 - Android SDK Command-line Tools (latest) + + - Ensure that the `NDK and CMake are installed and configured `__. + - CMake version 3.10.2.4988404 - NDK version r23c (23.2.8568313) diff --git a/tutorials/export/feature_tags.rst b/tutorials/export/feature_tags.rst index b0183252315..9ce3dfd8ed3 100644 --- a/tutorials/export/feature_tags.rst +++ b/tutorials/export/feature_tags.rst @@ -125,15 +125,14 @@ Here is a list of most feature tags in Godot. Keep in mind they are **case-sensi .. warning:: - With the exception of texture compression and ``movie`` feature tags, - default feature tags are **immutable**. This means that they will *not* - change depending on run-time conditions. For example, - ``OS.has_feature("mobile")`` will return ``false`` when running a project - exported to HTML5 on a mobile device. - - To check whether a project exported to HTML5 is running on a mobile device, - :ref:`call JavaScript code ` that reads the browser's - user agent. + With the exception of texture compression, ``web_`` and + ``movie`` feature tags, default feature tags are **immutable**. + This means that they will *not* change depending on run-time conditions. + For example, ``OS.has_feature("mobile")`` will return ``false`` + when running a project exported to Web on a mobile device. + + To check whether a project exported to Web is running on a mobile device, + use ``OS.has_feature("web_android") or OS.has_feature("web_ios")``. Custom features --------------- diff --git a/tutorials/i18n/internationalizing_games.rst b/tutorials/i18n/internationalizing_games.rst index 24518a05324..18cc299cdc3 100644 --- a/tutorials/i18n/internationalizing_games.rst +++ b/tutorials/i18n/internationalizing_games.rst @@ -6,9 +6,7 @@ Internationalizing games Introduction ------------ -Sería excelente que el mundo hablara solo un idioma (It would be great if the -world spoke only one language). Unfortunately for -us developers, that is not the case. While indie or niche games usually +While indie or niche games usually do not need localization, games targeting a more massive market often require localization. Godot offers many tools to make this process more straightforward, so this tutorial is more like a collection of diff --git a/tutorials/inputs/inputevent.rst b/tutorials/inputs/inputevent.rst index 25fa9c0b596..8f49916ffeb 100644 --- a/tutorials/inputs/inputevent.rst +++ b/tutorials/inputs/inputevent.rst @@ -234,8 +234,8 @@ The Input singleton has a method for this: var ev = new InputEventAction(); // Set as ui_left, pressed. - ev.SetAction("ui_left"); - ev.SetPressed(true); + ev.Action = "ui_left"; + ev.Pressed = true; // Feedback. Input.ParseInputEvent(ev); diff --git a/tutorials/migrating/index.rst b/tutorials/migrating/index.rst index 01653803f0f..90291dc2136 100644 --- a/tutorials/migrating/index.rst +++ b/tutorials/migrating/index.rst @@ -22,3 +22,4 @@ path. upgrading_to_godot_4 upgrading_to_godot_4.1 upgrading_to_godot_4.2 + upgrading_to_godot_4.3 diff --git a/tutorials/migrating/upgrading_to_godot_4.3.rst b/tutorials/migrating/upgrading_to_godot_4.3.rst new file mode 100644 index 00000000000..fb1cbb46e72 --- /dev/null +++ b/tutorials/migrating/upgrading_to_godot_4.3.rst @@ -0,0 +1,379 @@ +.. _doc_upgrading_to_godot_4.3: + +Upgrading from Godot 4.2 to Godot 4.3 +===================================== + +For most games and apps made with 4.2 it should be relatively safe to migrate to 4.3. +This page intends to cover everything you need to pay attention to when migrating +your project. + +Breaking changes +---------------- + +If you are migrating from 4.2 to 4.3, the breaking changes listed here might +affect you. Changes are grouped by areas/systems. + +This article indicates whether each breaking change affects GDScript and whether +the C# breaking change is *binary compatible* or *source compatible*: + +- **Binary compatible** - Existing binaries will load and execute successfully without + recompilation, and the run-time behavior won't change. +- **Source compatible** - Source code will compile successfully without changes when + upgrading Godot. + +GDExtension +^^^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**GDExtension** +Method ``close_library`` removed |❌| |❌| |❌| `GH-88418`_ +Method ``initialize_library`` removed |❌| |❌| |❌| `GH-88418`_ +Method ``open_library`` removed |❌| |❌| |❌| `GH-88418`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Since it was basically impossible to use these methods in any useful way, these methods have been removed. Use ``GDExtensionManager::load_extension`` and ``GDExtensionManager::unload_extension`` instead to correctly load and unload a GDExtension. + +Animation +^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**Animation** +Method ``position_track_interpolate`` adds a new ``backward`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-86629`_ +Method ``rotation_track_interpolate`` adds a new ``backward`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-86629`_ +Method ``scale_track_interpolate`` adds a new ``backward`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-86629`_ +Method ``blend_shape_track_interpolate`` adds a new ``backward`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-86629`_ +Method ``value_track_interpolate`` adds a new ``backward`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-86629`_ +Method ``track_find_key`` adds a new ``limit`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-86661`_ +Method ``track_find_key`` adds a new ``backward`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-92861`_ +**AnimationMixer** +Method ``_post_process_key_value`` changes ``object`` parameter type from ``Object`` to ``uint64`` |✔️| |❌| |❌| `GH-86687`_ +**Skeleton3D** +Method ``add_bone`` changes return type from ``void`` to ``int32`` |✔️| |❌| |✔️| `GH-88791`_ +Signal ``bone_pose_changed`` replaced by ``skeleton_updated`` |❌| |❌| |❌| `GH-90575`_ +**BoneAttachment3D** +Method ``on_bone_pose_update`` replaced by ``on_skeleton_update`` |✔️| |✔️ with compat| |✔️ with compat| `GH-90575`_ +======================================================================================================================== =================== ==================== ==================== =========== + +GUI nodes +^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**AcceptDialog** +Method ``register_text_enter`` changes parameter ``line_edit`` type from ``Control`` to ``LineEdit`` |✔️| |✔️ with compat| |✔️ with compat| `GH-89419`_ +Method ``remove_button`` changes parameter ``button`` type from ``Control`` to ``Button`` |✔️| |✔️ with compat| |✔️ with compat| `GH-89419`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Physics +^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**PhysicsShapeQueryParameters3D** +Property ``motion`` changes type from ``Vector2`` to ``Vector3`` |❌| |❌| |❌| `GH-85393`_ +======================================================================================================================== =================== ==================== ==================== =========== + +.. note:: + + In C#, the enum ``PhysicsServer3D.G6DofJointAxisFlag`` breaks compatibility because of the way the bindings generator + detects the enum prefix. New members were added in `GH-89851`_ to the enum that caused the enum members to be renamed. + +Rendering +^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**RenderingDevice** +Enum field ``FinalAction.FINAL_ACTION_CONTINUE`` changes value from ``2`` to ``0`` |✔️| |❌| |❌| `GH-84976`_ +Enum field ``InitialAction.INITIAL_ACTION_CLEAR`` changes value from ``0`` to ``1`` |✔️| |❌| |❌| `GH-84976`_ +Enum field ``InitialAction.INITIAL_ACTION_CLEAR_REGION_CONTINUE`` changes value from ``2`` to ``1`` |✔️| |❌| |❌| `GH-84976`_ +Enum field ``InitialAction.INITIAL_ACTION_CONTINUE`` changes value from ``5`` to ``0`` |✔️| |❌| |❌| `GH-84976`_ +Enum field ``InitialAction.INITIAL_ACTION_DROP`` changes value from ``4`` to ``2`` |✔️| |❌| |❌| `GH-84976`_ +Enum field ``InitialAction.INITIAL_ACTION_KEEP`` changes value from ``3`` to ``0`` |✔️| |❌| |❌| `GH-84976`_ +Method ``buffer_clear`` removes ``post_barrier`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``buffer_update`` removes ``post_barrier`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``compute_list_begin`` removes ``allow_draw_overlap`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``compute_list_end`` removes ``post_barrier`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``draw_list_begin`` removes ``storage_textures`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``draw_list_end`` removes ``post_barrier`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``texture_clear`` removes ``post_barrier`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``texture_copy`` removes ``post_barrier`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``texture_resolve_multisample`` removes ``post_barrier`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +Method ``texture_update`` removes ``post_barrier`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-84976`_ +**RenderingServer** +Method ``environment_set_fog`` adds a new ``fog_mode`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-84792`_ +**RenderSceneBuffersRD** +Method ``get_color_layer`` adds a new ``msaa`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-80214`_ +Method ``get_depth_layer`` adds a new ``msaa`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-80214`_ +Method ``get_velocity_layer`` adds a new ``msaa`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-80214`_ +Method ``get_color_texture`` adds a new ``msaa`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-80214`_ +Method ``get_depth_texture`` adds a new ``msaa`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-80214`_ +Method ``get_velocity_texture`` adds a new ``msaa`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-80214`_ +======================================================================================================================== =================== ==================== ==================== =========== + +.. note:: + + While the values of the enum fields in ``RenderingDevice.InitialAction`` and ``RenderingDevice.FinalAction`` changed, + the only method that consumed them (``draw_list_begin``) added a compatibility method which supports the old values. + So in practice it doesn't break compatibility. + +.. note:: + + In C#, the enum ``RenderingDevice.DriverResource`` breaks compatibility because of the way the bindings generator + detects the enum prefix. New members were added in `GH-83452`_ to the enum that caused the enum members to be + renamed. + +Text +^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**Font** +Method ``find_variation`` adds a new ``baseline_offset`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-87668`_ +**RichTextLabel** +Method ``push_meta`` adds a new ``underline_mode`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-89024`_ +**TextServer** +Method ``shaped_text_get_word_breaks`` adds a new optional ``skip_grapheme_flags`` parameter |✔️| |✔️ with compat| |✔️| `GH-90732`_ +**TextServerExtension** +Method ``_shaped_text_get_word_breaks`` adds a new ``skip_grapheme_flags`` parameter |❌| |❌| |❌| `GH-90732`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Audio +^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**AudioStreamPlaybackPolyphonic** +Method ``play_stream`` adds new ``playback_type``, and ``bus`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-91382`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Navigation +^^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**AStar2D** +Method ``get_id_path`` adds new ``allow_partial_path`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-88047`_ +Method ``get_point_path`` adds new ``allow_partial_path`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-88047`_ +**AStar3D** +Method ``get_id_path`` adds new ``allow_partial_path`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-88047`_ +Method ``get_point_path`` adds new ``allow_partial_path`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-88047`_ +**AStarGrid2D** +Method ``get_id_path`` adds new ``allow_partial_path`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-88047`_ +Method ``get_point_path`` adds new ``allow_partial_path`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-88047`_ +**NavigationRegion2D** +Property ``avoidance_layers`` removed |❌| |❌| |❌| `GH-90747`_ +Property ``constrain_avoidance`` removed |❌| |❌| |❌| `GH-90747`_ +Method ``get_avoidance_layer_value`` removed |❌| |❌| |❌| `GH-90747`_ +Method ``set_avoidance_layer_value`` removed |❌| |❌| |❌| `GH-90747`_ +======================================================================================================================== =================== ==================== ==================== =========== + +.. note:: + + The constrain avoidance feature in ``NavigationRegion2D`` was experimental and has been discontinued with no + replacement. + +TileMap +^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**TileData** +Method ``get_navigation_polygon`` adds new ``flip_h``, ``flip_v``, and ``transpose`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-84660`_ +Method ``get_occluder`` adds new ``flip_h``, ``flip_v``, and ``transpose`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-84660`_ +======================================================================================================================== =================== ==================== ==================== =========== + +XR +^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**WebXRInterface** +Method ``get_input_source_tracker`` changes return type from ``XRPositionalTracker`` to ``XRControllerTracker`` |✔️| |❌| |✔️| `GH-90645`_ +**XRServer** +Method ``get_tracker`` changes return type from ``XRPositionalTracker`` to ``XRTracker`` |✔️| |❌| |❌| `GH-90645`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Editor plugins +^^^^^^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**EditorInspectorPlugin** +Method ``add_property_editor`` adds a new ``label`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-92322`_ +**EditorPlugin** +Method ``add_control_to_bottom_panel`` adds a new ``shortcut`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-88081`_ +Method ``add_control_to_dock`` adds a new ``shortcut`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-88081`_ +**EditorSceneFormatImporterFBX** +Type renamed to ``EditorSceneFormatImporterFBX2GLTF`` |❌| |❌| |❌| `GH-81746`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Behavior changes +---------------- + +In 4.3 some behavior changes have been introduced, which might require you to adjust your project. + +Core +^^^^ + +.. note:: + + Binary serialization was modified to fix some issues with the serialization of scripted Objects and typed Arrays (`GH-78219`_). + This breaks compat with script encoding/decoding. + +.. note:: + + ``PackedByteArray`` is now able to use a more compact base64 encoding for storage. But the trade-off is that it breaks + compatibility, meaning that older versions of Godot may not be able to open resources saved by 4.3 (`GH-89186`_). + + To maximize compatibility, this new storage format will only be enabled for resources and scenes that contain large + PackedByteArrays for now. Support for this new format will also be added in patch updates for older versions of Godot. + Once all supported Godot versions are able to read the new format, we will gradually retire the compatibility measures + and have all resources and scenes use the new storage format. + +.. note:: + + In C#, the ``Transform3D.InterpolateWith`` implementation was fixed to use the right order of operations, applying the rotation before the scale (`GH-89843`_). + +.. note:: + + In C#, the ``Aabb.GetSupport`` implementation was fixed to properly return the support vector (`GH-88919`_). + +.. note:: + + In C#, the Variant types' ``ToString`` implementation now defaults to using the ``InvariantCulture`` (`GH-89547`_) + which means ``Vector2(1.2, 3.4)`` is formatted using ``.`` as the decimal separator independently of the language + of the operating system that the program is running on. + +Animation +^^^^^^^^^ + +.. note:: + + ``AnimationMixer`` replaced its Capture mode with a new Capture feature that works much better than the old one, + this replaces the existing cache (`GH-86715`_). + +.. note:: + + ``AnimationNode`` has a reworked process for retrieving the semantic time info. This ensures that time-related + behavior works as expected, but changes the blending behavior. Implementors of the ``_process`` virtual method + should also note that this method is now deprecated and will be replaced by a new one in the future (`GH-87171`_). + +More information about the changes to Animation can be found in the +`Migrating Animations from Godot 4.0 to 4.3 `__ +article. + +GUI nodes +^^^^^^^^^ + +.. note:: + + The default font outline color was changed from white to black (`GH-54641`_). + +.. note:: + + The ``auto_translate`` property is deprecated in favor of the ``auto_translate_mode`` property which is now in ``Node`` (`GH-87530`_). + The default value for ``auto_translate_mode`` is ``AUTO_TRANSLATE_INHERIT``, which means nodes inherit the ``auto_translate_mode`` value + from their parent. This means, existing nodes with the ``auto_translate`` property set to ``true`` may no longer be translated if they + are children of a node with the ``auto_translate`` property set to ``false``. + +Multiplayer +^^^^^^^^^^^ + +.. note:: + + The ``SceneMultiplayer`` caching protocol was changed to send the received ID instead of the Node path when sending a node removal confirmation packet (`GH-90027`_). + + This is a breaking change for the high-level multiplayer protocol making it incompatible with previous Godot versions. + Upgrade both your server and client versions to Godot 4.3 to handle this change gracefully. + + Note that high-level multiplayer facilities are only ever meant to be compatible with server and client using the same Godot version. It is recommended to implement some kind of version checking. + +Rendering +^^^^^^^^^ + +.. note:: + + Decals now convert the modulate color from an sRGB color to a linear color, like all other inputs, to ensure proper + blending (`GH-89849`_). Existing projects that were using the decal's modulate property will notice a change in + their visuals. + +.. note:: + + The reverse Z depth buffer technique is now implemented. This may break compatibility for some shaders. + Read the `Introducing Reverse Z (AKA I'm sorry for breaking your shader) `__ + article for more information and guidance on how to fix common scenarios. + +TileMap +^^^^^^^ + +.. note:: + + ``TileMap`` layers were moved to individual nodes (`GH-87379`_ and `GH-89179`_). + +Android +^^^^^^^ + +.. note:: + + Android permissions are no longer requested automatically because it goes against the recommended best practices (`GH-87080`_). + Use the ``request_permission`` method in ``OS`` and the ``on_request_permissions_result`` signal on ``MainLoop`` to request + permissions and wait for the user response. + +.. |❌| replace:: :abbr:`❌ (This API breaks compatibility.)` +.. |✔️| replace:: :abbr:`✔️ (This API does not break compatibility.)` +.. |✔️ with compat| replace:: :abbr:`✔️ (This API does not break compatibility. A compatibility method was added.)` + +.. _GH-54641: https://github.com/godotengine/godot/pull/54641 +.. _GH-78219: https://github.com/godotengine/godot/pull/78219 +.. _GH-80214: https://github.com/godotengine/godot/pull/80214 +.. _GH-81746: https://github.com/godotengine/godot/pull/81746 +.. _GH-83452: https://github.com/godotengine/godot/pull/83452 +.. _GH-84660: https://github.com/godotengine/godot/pull/84660 +.. _GH-84792: https://github.com/godotengine/godot/pull/84792 +.. _GH-84976: https://github.com/godotengine/godot/pull/84976 +.. _GH-85393: https://github.com/godotengine/godot/pull/85393 +.. _GH-86629: https://github.com/godotengine/godot/pull/86629 +.. _GH-86661: https://github.com/godotengine/godot/pull/86661 +.. _GH-86687: https://github.com/godotengine/godot/pull/86687 +.. _GH-86715: https://github.com/godotengine/godot/pull/86715 +.. _GH-87080: https://github.com/godotengine/godot/pull/87080 +.. _GH-87171: https://github.com/godotengine/godot/pull/87171 +.. _GH-87379: https://github.com/godotengine/godot/pull/87379 +.. _GH-87530: https://github.com/godotengine/godot/pull/87530 +.. _GH-87668: https://github.com/godotengine/godot/pull/87668 +.. _GH-87888: https://github.com/godotengine/godot/pull/87888 +.. _GH-88047: https://github.com/godotengine/godot/pull/88047 +.. _GH-88081: https://github.com/godotengine/godot/pull/88081 +.. _GH-88418: https://github.com/godotengine/godot/pull/88418 +.. _GH-88791: https://github.com/godotengine/godot/pull/88791 +.. _GH-88919: https://github.com/godotengine/godot/pull/88919 +.. _GH-89024: https://github.com/godotengine/godot/pull/89024 +.. _GH-89179: https://github.com/godotengine/godot/pull/89179 +.. _GH-89186: https://github.com/godotengine/godot/pull/89186 +.. _GH-89419: https://github.com/godotengine/godot/pull/89419 +.. _GH-89547: https://github.com/godotengine/godot/pull/89547 +.. _GH-89843: https://github.com/godotengine/godot/pull/89843 +.. _GH-89849: https://github.com/godotengine/godot/pull/89849 +.. _GH-89851: https://github.com/godotengine/godot/pull/89851 +.. _GH-90027: https://github.com/godotengine/godot/pull/90027 +.. _GH-90575: https://github.com/godotengine/godot/pull/90575 +.. _GH-90645: https://github.com/godotengine/godot/pull/90645 +.. _GH-90732: https://github.com/godotengine/godot/pull/90732 +.. _GH-90747: https://github.com/godotengine/godot/pull/90747 +.. _GH-91382: https://github.com/godotengine/godot/pull/91382 +.. _GH-92322: https://github.com/godotengine/godot/pull/92322 +.. _GH-92861: https://github.com/godotengine/godot/pull/92861 diff --git a/tutorials/migrating/upgrading_to_godot_4.rst b/tutorials/migrating/upgrading_to_godot_4.rst index f4930420067..a5bb987f3d2 100644 --- a/tutorials/migrating/upgrading_to_godot_4.rst +++ b/tutorials/migrating/upgrading_to_godot_4.rst @@ -437,6 +437,7 @@ table to find its new name. - Shortcut's ``is_valid()`` is now ``has_valid_event()``. - TileMap's ``world_to_map()`` is now ``local_to_map()``. - TileMap's ``map_to_world()`` is now ``map_to_local()``. +- Transform2D's ``xform()`` is ``mat * vec`` and ``xform_inv()`` is ``vec * mat``. **Properties** diff --git a/tutorials/navigation/img/nav_obstacle_bake.webp b/tutorials/navigation/img/nav_obstacle_bake.webp new file mode 100644 index 00000000000..820343da8c9 Binary files /dev/null and b/tutorials/navigation/img/nav_obstacle_bake.webp differ diff --git a/tutorials/navigation/navigation_using_navigationagents.rst b/tutorials/navigation/navigation_using_navigationagents.rst index 80f41d47bb9..b22be476db4 100644 --- a/tutorials/navigation/navigation_using_navigationagents.rst +++ b/tutorials/navigation/navigation_using_navigationagents.rst @@ -28,6 +28,7 @@ The result of the pathfinding can be influenced with the following properties. - The ``pathfinding_algorithm`` controls how the pathfinding travels through the navigation mesh polygons in the path search. - The ``path_postprocessing`` sets if or how the raw path corridor found by the pathfinding is altered before it is returned. - The ``path_metadata_flags`` enable the collection of additional path point meta data returned by the path. +- The ``simplify_path`` and ``simplify_epsilon`` properties can be used to remove less critical points from the path. .. warning:: @@ -141,144 +142,240 @@ to toggle avoidance. The following code snippets can be used to toggle avoidance on agents, create or delete avoidance callbacks or switch avoidance modes. .. tabs:: - .. code-tab:: gdscript GDScript + .. code-tab:: gdscript 2D GDScript extends NavigationAgent2D - var agent: RID = get_rid() - # Enable avoidance - NavigationServer2D.agent_set_avoidance_enabled(agent, true) - # Create avoidance callback - NavigationServer2D.agent_set_avoidance_callback(agent, Callable(self, "_avoidance_done")) + func _ready() -> void: + var agent: RID = get_rid() + # Enable avoidance + NavigationServer2D.agent_set_avoidance_enabled(agent, true) + # Create avoidance callback + NavigationServer2D.agent_set_avoidance_callback(agent, Callable(self, "_avoidance_done")) - # Disable avoidance - NavigationServer2D.agent_set_avoidance_enabled(agent, false) - # Delete avoidance callback - NavigationServer2D.agent_set_avoidance_callback(agent, Callable()) + # Disable avoidance + NavigationServer2D.agent_set_avoidance_enabled(agent, false) + # Delete avoidance callback + NavigationServer2D.agent_set_avoidance_callback(agent, Callable()) -.. tabs:: - .. code-tab:: gdscript GDScript + .. code-tab:: gdscript 3D GDScript extends NavigationAgent3D - var agent: RID = get_rid() - # Enable avoidance - NavigationServer3D.agent_set_avoidance_enabled(agent, true) - # Create avoidance callback - NavigationServer3D.agent_set_avoidance_callback(agent, Callable(self, "_avoidance_done")) - # Switch to 3D avoidance - NavigationServer3D.agent_set_use_3d_avoidance(agent, true) - - # Disable avoidance - NavigationServer3D.agent_set_avoidance_enabled(agent, false) - # Delete avoidance callback - NavigationServer3D.agent_set_avoidance_callback(agent, Callable()) - # Switch to 2D avoidance - NavigationServer3D.agent_set_use_3d_avoidance(agent, false) + func _ready() -> void: + var agent: RID = get_rid() + # Enable avoidance + NavigationServer3D.agent_set_avoidance_enabled(agent, true) + # Create avoidance callback + NavigationServer3D.agent_set_avoidance_callback(agent, Callable(self, "_avoidance_done")) + # Switch to 3D avoidance + NavigationServer3D.agent_set_use_3d_avoidance(agent, true) + + # Disable avoidance + NavigationServer3D.agent_set_avoidance_enabled(agent, false) + # Delete avoidance callback + NavigationServer3D.agent_set_avoidance_callback(agent, Callable()) + # Switch to 2D avoidance + NavigationServer3D.agent_set_use_3d_avoidance(agent, false) + NavigationAgent Script Templates -------------------------------- The following sections provides script templates for nodes commonly used with NavigationAgents. -Actor as Node3D -~~~~~~~~~~~~~~~ +.. tabs:: -This script adds basic navigation movement to a :ref:`Node3D ` with a :ref:`NavigationAgent3D ` child node. + .. tab:: 2D GDScript -.. tabs:: - .. code-tab:: gdscript GDScript + .. tabs:: - extends Node3D + .. code-tab:: gdscript Node2D - @export var movement_speed: float = 4.0 - @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D") - var movement_delta: float + extends Node2D - func _ready() -> void: - navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) + @export var movement_speed: float = 4.0 + @onready var navigation_agent: NavigationAgent2D = get_node("NavigationAgent2D") + var movement_delta: float - func set_movement_target(movement_target: Vector3): - navigation_agent.set_target_position(movement_target) + func _ready() -> void: + navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) - func _physics_process(delta): - if navigation_agent.is_navigation_finished(): - return + func set_movement_target(movement_target: Vector2): + navigation_agent.set_target_position(movement_target) - 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 - if navigation_agent.avoidance_enabled: - navigation_agent.velocity = new_velocity - else: - _on_velocity_computed(new_velocity) + func _physics_process(delta): + # Do not query when the map has never synchronized and is empty. + if NavigationServer2D.map_get_iteration_id(navigation_agent.get_navigation_map()) == 0: + return + if navigation_agent.is_navigation_finished(): + return - func _on_velocity_computed(safe_velocity: Vector3) -> void: - global_position = global_position.move_toward(global_position + safe_velocity, movement_delta) + movement_delta = movement_speed * delta + var next_path_position: Vector2 = navigation_agent.get_next_path_position() + var new_velocity: Vector2 = global_position.direction_to(next_path_position) * movement_delta + if navigation_agent.avoidance_enabled: + navigation_agent.set_velocity(new_velocity) + else: + _on_velocity_computed(new_velocity) -Actor as CharacterBody3D -~~~~~~~~~~~~~~~~~~~~~~~~ + func _on_velocity_computed(safe_velocity: Vector2) -> void: + global_position = global_position.move_toward(global_position + safe_velocity, movement_delta) -This script adds basic navigation movement to a :ref:`CharacterBody3D ` with a :ref:`NavigationAgent3D ` child node. + .. code-tab:: gdscript CharacterBody2D -.. tabs:: - .. code-tab:: gdscript GDScript + extends CharacterBody2D - extends CharacterBody3D + @export var movement_speed: float = 4.0 + @onready var navigation_agent: NavigationAgent2D = get_node("NavigationAgent2D") - @export var movement_speed: float = 4.0 - @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D") + func _ready() -> void: + navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) - func _ready() -> void: - navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) + func set_movement_target(movement_target: Vector2): + navigation_agent.set_target_position(movement_target) - func set_movement_target(movement_target: Vector3): - navigation_agent.set_target_position(movement_target) + func _physics_process(delta): + # Do not query when the map has never synchronized and is empty. + if NavigationServer2D.map_get_iteration_id(navigation_agent.get_navigation_map()) == 0: + return + if navigation_agent.is_navigation_finished(): + return - func _physics_process(delta): - if navigation_agent.is_navigation_finished(): - return + var next_path_position: Vector2 = navigation_agent.get_next_path_position() + var new_velocity: Vector2 = 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) - var next_path_position: Vector3 = navigation_agent.get_next_path_position() - var new_velocity: Vector3 = global_position.direction_to(next_path_position) * movement_speed - if navigation_agent.avoidance_enabled: - navigation_agent.velocity = new_velocity - else: - _on_velocity_computed(new_velocity) + func _on_velocity_computed(safe_velocity: Vector2): + velocity = safe_velocity + move_and_slide() - func _on_velocity_computed(safe_velocity: Vector3): - velocity = safe_velocity - move_and_slide() + .. code-tab:: gdscript RigidBody2D -Actor as RigidBody3D -~~~~~~~~~~~~~~~~~~~~ + extends RigidBody2D -This script adds basic navigation movement to a :ref:`RigidBody3D ` with a :ref:`NavigationAgent3D ` child node. + @export var movement_speed: float = 4.0 + @onready var navigation_agent: NavigationAgent2D = get_node("NavigationAgent2D") -.. tabs:: - .. code-tab:: gdscript GDScript + func _ready() -> void: + navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) - extends RigidBody3D + func set_movement_target(movement_target: Vector2): + navigation_agent.set_target_position(movement_target) - @export var movement_speed: float = 4.0 - @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D") + func _physics_process(delta): + # Do not query when the map has never synchronized and is empty. + if NavigationServer2D.map_get_iteration_id(navigation_agent.get_navigation_map()) == 0: + return + if navigation_agent.is_navigation_finished(): + return - func _ready() -> void: - navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) + var next_path_position: Vector2 = navigation_agent.get_next_path_position() + var new_velocity: Vector2 = 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: Vector2): + linear_velocity = safe_velocity + + .. tab:: 3D GDScript + + .. tabs:: + + .. code-tab:: gdscript Node3D + + extends Node3D + + @export var movement_speed: float = 4.0 + @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D") + var movement_delta: float + + func _ready() -> void: + navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) + + func set_movement_target(movement_target: Vector3): + navigation_agent.set_target_position(movement_target) + + func _physics_process(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 + 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) + + .. code-tab:: gdscript CharacterBody3D + + extends CharacterBody3D + + @export var movement_speed: float = 4.0 + @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D") + + func _ready() -> void: + navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) + + func set_movement_target(movement_target: Vector3): + navigation_agent.set_target_position(movement_target) + + func _physics_process(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 + + var next_path_position: Vector3 = navigation_agent.get_next_path_position() + 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): + velocity = safe_velocity + move_and_slide() + + .. code-tab:: gdscript RigidBody3D + + extends RigidBody3D + + @export var movement_speed: float = 4.0 + @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D") + + func _ready() -> void: + navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed)) - func set_movement_target(movement_target: Vector3): - navigation_agent.set_target_position(movement_target) + func set_movement_target(movement_target: Vector3): + navigation_agent.set_target_position(movement_target) - func _physics_process(delta): - if navigation_agent.is_navigation_finished(): - return + func _physics_process(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 - var next_path_position: Vector3 = navigation_agent.get_next_path_position() - var new_velocity: Vector3 = global_position.direction_to(next_path_position) * movement_speed - if navigation_agent.avoidance_enabled: - navigation_agent.velocity = new_velocity - else: - _on_velocity_computed(new_velocity) + var next_path_position: Vector3 = navigation_agent.get_next_path_position() + 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): - linear_velocity = safe_velocity + func _on_velocity_computed(safe_velocity: Vector3): + linear_velocity = safe_velocity diff --git a/tutorials/navigation/navigation_using_navigationlayers.rst b/tutorials/navigation/navigation_using_navigationlayers.rst index 2b08d11c871..e945b55f532 100644 --- a/tutorials/navigation/navigation_using_navigationlayers.rst +++ b/tutorials/navigation/navigation_using_navigationlayers.rst @@ -3,15 +3,13 @@ Using NavigationLayers ====================== -NavigationLayers are an optional feature to further control which navigation meshes are considered in a path query and which regions can be connected. +NavigationLayers are an optional feature to further control which navigation meshes are considered in a path query. They work similar to how physics layers control collision between collision objects or how visual layers control what is rendered to the Viewport. NavigationLayers can be named in the **ProjectSettings** the same as physics layers or visual layers. .. image:: img/navigationlayers_naming.png -If two regions have not a single compatible layer they will not be merged by the NavigationServer. See :ref:`doc_navigation_connecting_navmesh` for more information on merging navigation meshes. - If a region has not a single compatible navigation layer with the ``navigation_layers`` parameter of a path query this regions navigation mesh will be skipped in pathfinding. See :ref:`doc_navigation_using_navigationpaths` for more information on querying the NavigationServer for paths. @@ -96,5 +94,4 @@ trigger large scale updates on the NavigationServer. Changing the navigation layers of NavigationAgent nodes will have an immediate effect on the next path query. Changing the navigation layers of -regions will have an immediate effect on the region but any new region -connect or disconnect will only be in effect after the next physics frame. +regions will have an effect after the next NavigationServer sync. diff --git a/tutorials/navigation/navigation_using_navigationlinks.rst b/tutorials/navigation/navigation_using_navigationlinks.rst index 31cbf5abd27..0192e23e818 100644 --- a/tutorials/navigation/navigation_using_navigationlinks.rst +++ b/tutorials/navigation/navigation_using_navigationlinks.rst @@ -16,7 +16,7 @@ interacting with gameplay objects e.g. ladders, jump pads or teleports. :ref:`NavigationLink3D` respectively. Different NavigationRegions can connect their navigation meshes without the need for a NavigationLink -as long as they are within navigation map ``edge_connection_margin`` and have compatible ``navigation_layers``. +as long as they have overlapping edges or edges that are within navigation map ``edge_connection_margin``. As soon as the distance becomes too large, building valid connections becomes a problem - a problem that NavigationLinks can solve. See :ref:`doc_navigation_using_navigationregions` to learn more about the use of navigation regions. diff --git a/tutorials/navigation/navigation_using_navigationmeshes.rst b/tutorials/navigation/navigation_using_navigationmeshes.rst index 44cf163eb9e..ec435f4d82c 100644 --- a/tutorials/navigation/navigation_using_navigationmeshes.rst +++ b/tutorials/navigation/navigation_using_navigationmeshes.rst @@ -209,6 +209,13 @@ Baking navigation mesh chunks for large worlds Building and updating individual navigation mesh chunks at runtime. +.. seealso:: + + You can see the navigation mesh chunk baking in action in the + `Navigation Mesh Chunks 2D `__ + and `Navigation Mesh Chunks 3D `__ + demo projects. + To avoid misaligned edges between different region chunks the navigation meshes have two important properties for the navigation mesh baking process. The baking bound and the border size. Together they can be used to ensure perfectly aligned edges between region chunks. @@ -255,6 +262,10 @@ parts so that only the intended chunk size is left. The baking bounds need to be large enough to include a reasonable amount of source geometry from all the neighboring chunks. +.. warning:: + + In 3D the functionality of the border size is limited to the xz-axis. + Navigation mesh baking common problems -------------------------------------- @@ -284,6 +295,14 @@ There are some common user problems and important caveats to consider when creat Remove the geometry that is on the ground inside the other geometry. If that is not possible, add smaller "dummy" geometry inside with as few triangles as possible so the cells are occupied with something. + A :ref:`NavigationObstacle3D` shape set to bake with navigation mesh can be used to discard geometry as well. + +.. figure:: img/nav_mesh_obstacles_discard.webp + :align: center + :alt: NavigationObstacle3D unwanted geometry discard + + A NavigationObstacle3D shape can be used to discard unwanted navigation mesh parts. + Navigation mesh script templates -------------------------------- diff --git a/tutorials/networking/high_level_multiplayer.rst b/tutorials/networking/high_level_multiplayer.rst index b04dc2293b3..45e7e8557d7 100644 --- a/tutorials/networking/high_level_multiplayer.rst +++ b/tutorials/networking/high_level_multiplayer.rst @@ -201,10 +201,11 @@ must have the same name. When using ``add_child()`` for nodes which are expected scripts and the server scripts, **even functions that are currently not in use**. The signature of the RPC includes the ``@rpc()`` declaration, the function, return type, - AND the nodepath. If an RPC resides in a script attached to ``/root/Main/Node1``, then it + **and** the NodePath. If an RPC resides in a script attached to ``/root/Main/Node1``, then it must reside in precisely the same path and node on both the client script and the server - script. Function arguments (example: ``func sendstuff():`` and ``func sendstuff(arg1, arg2):`` - **will pass** signature matching). + script. Function arguments are not checked for matching between the server and client code + (example: ``func sendstuff():`` and ``func sendstuff(arg1, arg2):`` **will pass** signature + matching). If these conditions are not met (if all RPCs do not pass signature matching), the script may print an error or cause unwanted behavior. The error message may be unrelated to the RPC function you are diff --git a/tutorials/platform/android/android_plugin.rst b/tutorials/platform/android/android_plugin.rst index ff810a7b6e5..0674ebdad42 100644 --- a/tutorials/platform/android/android_plugin.rst +++ b/tutorials/platform/android/android_plugin.rst @@ -363,7 +363,7 @@ developers / users intend to run the Godot Editor. Not doing so may prevent deve users from writing code that accesses the plugin from within the Godot Editor. This may involve creating dummy plugins for the host OS just so the API is published to the -editor. You can use the [godot-cpp-template](https://github.com/godotengine/godot-cpp-template) +editor. You can use the `godot-cpp-template `__ github template for reference on how to do so. Godot crashes upon load diff --git a/tutorials/platform/consoles.rst b/tutorials/platform/consoles.rst index 373d276a750..02a6e476c2f 100644 --- a/tutorials/platform/consoles.rst +++ b/tutorials/platform/consoles.rst @@ -81,7 +81,7 @@ Following is the list of providers: Switch porting and publishing of Godot games. - `Seaven Studio `_ offers Switch, Xbox One, Xbox Series, PlayStation 4 & PlayStation 5 porting of Godot games. - +- `Sickhead Games `_ offers console porting to Nintendo Switch, PlayStation 4, PlayStation 5, Xbox One, and Xbox Series X/S for Godot games. If your company offers porting, or porting *and* publishing services for Godot games, feel free to diff --git a/tutorials/plugins/editor/3d_gizmos.rst b/tutorials/plugins/editor/3d_gizmos.rst index fabeac6d387..a62620ba209 100644 --- a/tutorials/plugins/editor/3d_gizmos.rst +++ b/tutorials/plugins/editor/3d_gizmos.rst @@ -34,7 +34,7 @@ This would be a basic setup: extends EditorNode3DGizmoPlugin - func get_name(): + func _get_gizmo_name(): return "CustomNode" diff --git a/tutorials/rendering/jitter_stutter.rst b/tutorials/rendering/jitter_stutter.rst index dca284ba615..0f1f10dd188 100644 --- a/tutorials/rendering/jitter_stutter.rst +++ b/tutorials/rendering/jitter_stutter.rst @@ -34,7 +34,6 @@ Finally, a game exhibiting *stutter* will appear smooth, but appear to *stop* or .. image:: img/motion_stutter.gif - Jitter ------ @@ -92,6 +91,11 @@ games, will usually not exhibit this problem anyway). For fullscreen, Windows gives special priority to the game so stutter is no longer visible and very rare. This is how most games are played. +When using a mouse with a polling rate of 1,000 Hz or more, consider using a +fully up-to-date Windows 11 installation which comes with fixes related to high +CPU utilization with high polling rate mice. These fixes are not available in +Windows 10 and older versions. + .. tip:: Games should use the **Exclusive Fullscreen** window mode, as opposed to @@ -151,7 +155,20 @@ Project configuration On platforms that support disabling V-Sync, input lag can be made less noticeable by disabling V-Sync in the project settings. This will however cause -tearing to appear, especially on monitors with low refresh rates. +tearing to appear, especially on monitors with low refresh rates. It's suggested +to make V-Sync available as an option for players to toggle. + +When using the Forward+ or Mobile rendering methods, another way to reduce +visual latency when V-Sync is enabled is to use double-buffered V-Sync instead +of the default triple-buffered V-Sync. Since Godot 4.3, this can be achieved by +reducing the **Display > Window > V-Sync > Swapchain Image Count** project +setting to ``2``. The downside of using double buffering is that framerate will +be less stable if the display refresh rate can't be reached due to a CPU or GPU +bottleneck. For instance, on a 60 Hz display, if the framerate would normally +drop to 55 FPS during gameplay with triple buffering, it will have to drop down +to 30 FPS momentarily with double buffering (and then go back to 60 FPS when +possible). As a result, double-buffered V-Sync is only recommended if you can +*consistently* reach the display refresh rate on the target hardware. Increasing the number of physics iterations per second can also reduce physics-induced input latency. This is especially noticeable when using physics @@ -181,6 +198,13 @@ every input, rather than accumulating inputs and waiting for a frame to be rendered. Disabling input accumulation will increase CPU usage, so it should be done with caution. +.. tip:: + + On any Godot project, you can use the ``--disable-vsync`` + :ref:`command line argument ` to forcibly disable V-Sync. + Since Godot 4.2, ``--max-fps `` can also be used to set a FPS limit + (``0`` is unlimited). These arguments can be used at the same time. + Hardware/OS-specific ^^^^^^^^^^^^^^^^^^^^ diff --git a/tutorials/scripting/c_sharp/c_sharp_basics.rst b/tutorials/scripting/c_sharp/c_sharp_basics.rst index fe430b11631..e406f69d925 100644 --- a/tutorials/scripting/c_sharp/c_sharp_basics.rst +++ b/tutorials/scripting/c_sharp/c_sharp_basics.rst @@ -328,7 +328,7 @@ objects, e.g. when trying to change the X coordinate of a ``Node2D``: public partial class MyNode2D : Node2D { - public override _Ready() + public override void _Ready() { Position.X = 100.0f; // CS1612: Cannot modify the return value of 'Node2D.Position' because diff --git a/tutorials/scripting/c_sharp/c_sharp_global_classes.rst b/tutorials/scripting/c_sharp/c_sharp_global_classes.rst index 9983dcab266..8336c4347c0 100644 --- a/tutorials/scripting/c_sharp/c_sharp_global_classes.rst +++ b/tutorials/scripting/c_sharp/c_sharp_global_classes.rst @@ -80,3 +80,12 @@ will let you create and load instances of this type easily. .. image:: img/globalclasses_exportedproperty1.webp .. image:: img/globalclasses_exportedproperty2.webp + +.. warning:: + + The Godot editor will hide these custom classes with names that beging with the prefix + "Editor" in the 'Create New Node' or 'Create New Scene' dialog windows. The classes + are available for instantiation at runtime via their class names, but are + automatically hidden by the editor windows along with the built-in editor nodes used + by the Godot editor. + diff --git a/tutorials/scripting/change_scenes_manually.rst b/tutorials/scripting/change_scenes_manually.rst index 4c14f5a149d..300636b5b04 100644 --- a/tutorials/scripting/change_scenes_manually.rst +++ b/tutorials/scripting/change_scenes_manually.rst @@ -3,11 +3,11 @@ Change scenes manually ====================== -Sometimes it helps to have more control over how one swaps scenes around. +Sometimes it helps to have more control over how you swap scenes around. A :ref:`Viewport `'s child nodes will render to the image -it generates, this holds true even for nodes outside -of the "current" scene. Autoloads fall into this category, but so do -scenes which one instances and adds to the tree at runtime: +it generates. This holds true even for nodes outside of the "current" +scene. Autoloads fall into this category, and also scenes which you +instantiate and add to the tree at runtime: .. tabs:: .. code-tab:: gdscript GDScript @@ -36,16 +36,16 @@ scenes which one instances and adds to the tree at runtime: } To complete the cycle and swap out the new scene with the old one, -developers have a choice to make. Many strategies exist for removing a scene +you have a choice to make. Many strategies exist for removing a scene from view of the :ref:`Viewport `. The tradeoffs involve -balancing operation speed and memory consumption as well as balancing data +balancing operation speed and memory consumption, as well as balancing data access and integrity. -1. **We can delete the existing scene.** +1. **Delete the existing scene.** :ref:`SceneTree.change_scene_to_file() ` and :ref:`SceneTree.change_scene_to_packed() ` - will delete the current scene immediately. Developers can also delete the - main scene though. Assuming the root node's name is "Main", one could do + will delete the current scene immediately. You can also delete the + main scene. Assuming the root node's name is "Main", you could do ``get_node("/root/Main").free()`` to delete the whole scene. - Unloads memory. @@ -65,60 +65,60 @@ access and integrity. - Processing stops. - - Pro: No nodes means no process, physics process, or input + - Pro: No nodes means no processing, physics processing, or input handling. The CPU is available to work on the new scene's contents. - Con: Those nodes' processing and input handling no longer operate. Not a problem if using the updated data is unnecessary. -2. **We can hide the existing scene.** By changing the visibility or collision - detection of the nodes, we can hide the entire node sub-tree from the +2. **Hide the existing scene.** By changing the visibility or collision + detection of the nodes, you can hide the entire node sub-tree from the player's perspective. - Memory still exists. - - Pro: One can still access the data if need be. + - Pro: You can still access the data if needed. - Pro: There's no need to move any more nodes around to save data. - - Con: More data is being kept in memory which will become a problem + - Con: More data is being kept in memory, which will be become a problem on memory-sensitive platforms like web or mobile. - Processing continues. - Pro: Data continues to receive processing updates, so the scene will - keep updated any data within it that relies on delta time or frame - data. + keep any data within it that relies on delta time or frame data + updated. - Pro: Nodes are still members of groups (since groups belong to the :ref:`SceneTree `). - Con: The CPU's attention is now divided between both scenes. Too much - load could result in low frame rates. One should be sure to test - performance as they go to ensure the target platform can support the - load they are giving it. + load could result in low frame rates. You should be sure to test + performance as you go to ensure the target platform can support the + load from this approach. -3. **We can remove the existing scene from the tree.** Assign a variable +3. **Remove the existing scene from the tree.** Assign a variable to the existing scene's root node. Then use :ref:`Node.remove_child(Node) ` to detach the entire scene from the tree. - - Memory still exists (similar pros/cons as with hiding it from view). + - Memory still exists (similar pros/cons as hiding it from view). - - Processing stops (similar pros/cons as with deleting it completely). + - Processing stops (similar pros/cons as deleting it completely). - Pro: This variation of "hiding" it is much easier to show/hide. Rather - than potentially keeping track of multiple changes to the scene, one - must only call the one method add/remove_child pair of methods. It is - similar to disabling game objects in other engines. + than potentially keeping track of multiple changes to the scene, you + only need to call the add/remove_child methods. This is similar to + disabling game objects in other engines. - Con: Unlike with hiding it from view only, the data contained within the scene will become stale if it relies on delta time, input, groups, or other data that is derived from :ref:`SceneTree ` access. -There are also cases where one may wish to have many scenes present at the same -time. Perhaps one is adding their own singleton at runtime, or preserving +There are also cases where you may wish to have many scenes present at the same +time, such as adding your own singleton at runtime, or preserving a scene's data between scene changes (adding the scene to the root node). .. tabs:: @@ -130,11 +130,11 @@ a scene's data between scene changes (adding the scene to the root node). GetTree().Root.AddChild(scene); -Perhaps instead they wish to display multiple scenes at the same time using -:ref:`SubViewportContainers `. This is optimal in -cases where the intent is to render different content in different parts of the -screen. Minimaps and split-screen multiplayer are good examples. +Another case may be displaying multiple scenes at the same time using +:ref:`SubViewportContainers `. This is optimal for +rendering different content in different parts of the screen (e.g. minimaps, +split-screen multiplayer). -Each option will have cases where it is best appropriate, so one must -examine the effects of each and determine what path best fits -their unique situation. +Each option will have cases where it is best appropriate, so you must examine +the effects of each approach, and determine what path best fits your unique +situation. diff --git a/tutorials/scripting/evaluating_expressions.rst b/tutorials/scripting/evaluating_expressions.rst index 57989353507..4f29b907421 100644 --- a/tutorials/scripting/evaluating_expressions.rst +++ b/tutorials/scripting/evaluating_expressions.rst @@ -44,7 +44,8 @@ The following operators are available: | Division (``/``) | Performs and integer division if both operands are integers. | | | If at least one of them is a floating-point number, returns a floating-point value. | +------------------------+-------------------------------------------------------------------------------------+ -| Modulo (``%``) | Returns the remainder of an integer division. | +| Remainder (``%``) | Returns the remainder of an integer division (modulo). | +| | The result will always have the sign of the dividend. | +------------------------+-------------------------------------------------------------------------------------+ Spaces around operators are optional. Also, keep in mind the usual diff --git a/tutorials/scripting/gdextension/gdextension_cpp_example.rst b/tutorials/scripting/gdextension/gdextension_cpp_example.rst index 51f329c4c2b..f89754b77bc 100644 --- a/tutorials/scripting/gdextension/gdextension_cpp_example.rst +++ b/tutorials/scripting/gdextension/gdextension_cpp_example.rst @@ -365,6 +365,7 @@ loaded for each platform and the entry function for the module. It is called ``g entry_symbol = "example_library_init" compatibility_minimum = "4.1" + reloadable = true [libraries] @@ -388,6 +389,8 @@ loaded for each platform and the entry function for the module. It is called ``g This file contains a ``configuration`` section that controls the entry function of the module. You should also set the minimum compatible Godot version with ``compatability_minimum``, which prevents older version of Godot from trying to load your extension. +The ``reloadable`` flag enables automatic reloading of your extension by the editor every time you recompile it, +without needing to restart the editor. This only works if you compile your extension in debug mode (default). The ``libraries`` section is the important bit: it tells Godot the location of the dynamic library in the project's filesystem for each supported platform. It will diff --git a/tutorials/scripting/gdextension/gdextension_docs_system.rst b/tutorials/scripting/gdextension/gdextension_docs_system.rst new file mode 100644 index 00000000000..0a5f09338ca --- /dev/null +++ b/tutorials/scripting/gdextension/gdextension_docs_system.rst @@ -0,0 +1,172 @@ +.. _doc_gdextension_docs_system: + +GDExtension documentation system +================================ + +.. note:: + + Adding documentation for GDExtensions is only possible for Godot 4.3 and later. The support can be integrated into your project + regardless because the snippet will check if you use the appropriate godot-cpp version. + If you set the ``compatability_minimum`` to 4.2 and you load a project with the extension through a 4.2 editor, the + documentation page for that class will be empty. The extension itself will still work. + +The GDExtension documentation system works in a similar manner to the built-in engine documentation. It uses a series of +XML files (one per class) to document the exposed constructors, properties, methods, constants, signals, and theme items of each class. + +.. note:: + + We are assuming you are using the project files explained in the :ref:`GDExtension C++ Example ` + with the following structure: + + gdextension_cpp_example/ # GDExtension directory + | + +--demo/ # game example/demo to test the extension + | | + | +--main.tscn + | | + | +--bin/ + | | + | +--gdexample.gdextension + | + +--godot-cpp/ # C++ bindings + | + +--src/ # source code of the extension we are building + | | + | +--register_types.cpp + | +--register_types.h + | +--gdexample.cpp + | +--gdexample.h + +Inside the Godot demo project directory of your GDExtension directory, run the following terminal command: + +.. code-block:: none + + # Replace "godot" with the full path to a Godot editor binary + # if Godot is not installed in your `PATH`. + godot --doctool ../ --gdextension-docs + +This command calls upon the Godot editor binary to generate documentation via the ``--doctool`` +and ``--gdextension-docs`` commands. The ``../`` addition is to let Godot know where the GDExtension +SConstruct file is located. By calling this command, Godot generates a ``doc_classes`` directory inside the +project directory in which it generates XML files for the GDExtension classes. Those files +can then be edited to add information about member variables, methods, signals, and more. + +To add the now edited documentation to the GDExtension and let the editor load it, +you need to add the following lines to your SConstruct file: + +.. code-block:: py + + if env["target"] in ["editor", "template_debug"]: + try: + doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml")) + sources.append(doc_data) + except AttributeError: + print("Not including class reference as we're targeting a pre-4.3 baseline.") + +The if-statement checks if we are compiling the GDExtension library with the ``editor`` and ``template_debug`` +flags. SCons then tries to load all the XML files inside the ``doc_classes`` directory and appends them +to the ``sources`` variable which already includes all the source files of your extension. If it fails +it means we are currently trying to compile the library when the ``godot_cpp`` is set to a version before 4.3. + +After loading the extension in a 4.3 Godot editor or later and open the documentation of your extension class +either by :kbd:`Ctrl + Click` in the script editor or the Editor help dialog you will see something like this: + +.. image:: img/gdextension_docs_generation.webp + +Documentation styling +--------------------- + +To style specific parts of text you can use BBCode tags similarly to how they can be used in :ref:`RichTextLabels `. +You can set text as bold, italic, underlined, colored, codeblocks etc. by embedding them in tags like this: + +.. code-block:: none + + [b]this text will be shown as bold[/b] + +Currently they supported tags for the GDExtension documentation system are: + +.. list-table:: + :class: wrap-normal + :width: 100% + :widths: 60 40 + + * - Tag + - Example + + * - | **b** + | Makes ``{text}`` use the bold (or bold italics) font of ``RichTextLabel``. + + - ``[b]{text}[/b]`` + + * - | **i** + | Makes ``{text}`` use the italics (or bold italics) font of ``RichTextLabel``. + + - ``[i]{text}[/i]`` + + * - | **u** + | Makes ``{text}`` underlined. + + - ``[u]{text}[/u]`` + + * - | **s** + | Makes ``{text}`` strikethrough. + + - ``[s]{text}[/s]`` + + * - | **kbd** + | Makes ``{text}`` use the mono font and styles the text color and background like a shortcut. + + - ``[code]{text}[/code]`` + + * - | **code** + | Makes inline ``{text}`` use the mono font and styles the text color and background like code. + + - ``[code]{text}[/code]`` + + * - | **codeblocks** + | Makes multiline ``{text}`` use the mono font and styles the text color and background like code. + | The addition of the ``[gdscript]`` tag highlights the GDScript specific syntax. + + - | ``[codeblocks]`` + | ``[gdscript]`` + | ``{text}`` + | ``[/gdscript]`` + | ``[/codeblocks]`` + + * - | **center** + | Makes ``{text}`` horizontally centered. + | Same as ``[p align=center]``. + + - ``[center]{text}[/center]`` + + * - | **url** + | Creates a hyperlink (underlined and clickable text). Can contain optional + ``{text}`` or display ``{link}`` as is. + | **Must be handled with the "meta_clicked" signal to have an effect,** see :ref:`doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. + + - | ``[url]{link}[/url]`` + | ``[url={link}]{text}[/url]`` + + * - | **img** + | Inserts an image from the ``{path}`` (can be any valid :ref:`class_Texture2D` resource). + | If ``{width}`` is provided, the image will try to fit that width maintaining + the aspect ratio. + | If both ``{width}`` and ``{height}`` are provided, the image will be scaled + to that size. + | Add ``%`` to the end of ``{width}`` or ``{height}`` value to specify it as percentages of the control width instead of pixels. + | If ``{valign}`` configuration is provided, the image will try to align to the + surrounding text, see :ref:`doc_bbcode_in_richtextlabel_image_and_table_alignment`. + | Supports configuration options, see :ref:`doc_bbcode_in_richtextlabel_image_options`. + + - | ``[img]{path}[/img]`` + | ``[img={width}]{path}[/img]`` + | ``[img={width}x{height}]{path}[/img]`` + | ``[img={valign}]{path}[/img]`` + | ``[img {options}]{path}[/img]`` + + * - | **color** + | Changes the color of ``{text}``. Color must be provided by a common name (see + :ref:`doc_bbcode_in_richtextlabel_named_colors`) or using the HEX format (e.g. + ``#ff00ff``, see :ref:`doc_bbcode_in_richtextlabel_hex_colors`). + + - ``[color={code/name}]{text}[/color]`` diff --git a/tutorials/scripting/gdextension/gdextension_file.rst b/tutorials/scripting/gdextension/gdextension_file.rst index ec76b1862a5..68e05611b44 100644 --- a/tutorials/scripting/gdextension/gdextension_file.rst +++ b/tutorials/scripting/gdextension/gdextension_file.rst @@ -1,4 +1,4 @@ -.. _doc_gdextension_file_sections: +.. _doc_gdextension_file: The .gdextension file ===================== @@ -129,7 +129,7 @@ Icons section ------------- By default, Godot uses the Node icon in the scene dock for GDExtension nodes. A custom icon can be -set set by reference to its name and resource path of an SVG file. +set by reference to its name and resource path of an SVG file. For example: @@ -141,3 +141,45 @@ For example: The path should point to a 16 by 16 pixel SVG image. Read the guide for :ref:`creating icons ` for more information. + +Dependencies section +-------------------- + +In this section you set the paths of the GDExtension dependencies. This is used internally to export the dependencies +when exporting your game executable. You are able to set which dependency is loaded depending on the feature flags +of the exported executable. In addition, you are able to set an optional subdirectory to move your dependencies into. +If no path is supplied Godot will move the libraries into the same directory as your game executable. + +.. warning:: + In MacOS it is necessary to have shared libraries inside a folder called ``Frameworks`` with a directory structure + like this: ``Game.app/Contents/Frameworks``. + +.. code-block:: none + + [dependencies] + + macos.debug = { + "res://bin/libdependency.macos.template_debug.framework" : "Contents/Frameworks" + } + macos.release = { + "res://bin/libdependency.macos.template_release.framework" : "Contents/Frameworks" + } + windows.debug = { + "res://bin/libdependency.windows.template_debug.x86_64.dll" : "", + "res://bin/libdependency.windows.template_debug.x86_32.dll" : "" + } + windows.release = { + "res://bin/libdependency.windows.template_release.x86_64.dll" : "", + "res://bin/libdependency.windows.template_release.x86_32.dll" : "" + } + linux.debug = { + "res://bin/libdependency.linux.template_debug.x86_64.so" : "", + "res://bin/libdependency.linux.template_debug.arm64.so" : "", + "res://bin/libdependency.linux.template_debug.rv64.so" : "" + } + linux.release = { + "res://bin/libdependency.linux.template_release.x86_64.so" : "", + "res://bin/libdependency.linux.template_release.arm64.so" : "", + "res://bin/libdependency.linux.template_release.rv64.so" : "" + } + diff --git a/tutorials/scripting/gdextension/img/gdextension_docs_generation.webp b/tutorials/scripting/gdextension/img/gdextension_docs_generation.webp new file mode 100644 index 00000000000..88642bdbb03 Binary files /dev/null and b/tutorials/scripting/gdextension/img/gdextension_docs_generation.webp differ diff --git a/tutorials/scripting/gdextension/index.rst b/tutorials/scripting/gdextension/index.rst index 04b27a6e804..952145334da 100644 --- a/tutorials/scripting/gdextension/index.rst +++ b/tutorials/scripting/gdextension/index.rst @@ -10,3 +10,4 @@ GDExtension what_is_gdextension gdextension_cpp_example gdextension_file + gdextension_docs_system diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index 465a5cebae6..0f1451799d4 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -1034,11 +1034,14 @@ Member variables are initialized in the following order: (``0`` for ``int``, ``false`` for ``bool``, etc.). 2. The specified values are assigned in the order of the variables in the script, from top to bottom. - - *(Only for ``Node``-derived classes)* If the ``@onready`` annotation is applied to a variable, its initialization is deferred to step 5. + + - (Only for ``Node``-derived classes) If the ``@onready`` annotation is applied to a variable, + its initialization is deferred to step 5. + 3. If defined, the ``_init()`` method is called. 4. When instantiating scenes and resources, the exported values are assigned. -5. *(Only for ``Node``-derived classes)* ``@onready`` variables are initialized. -6. *(Only for ``Node``-derived classes)* If defined, the ``_ready()`` method is called. +5. (Only for ``Node``-derived classes) ``@onready`` variables are initialized. +6. (Only for ``Node``-derived classes) If defined, the ``_ready()`` method is called. .. warning:: @@ -1350,8 +1353,8 @@ return early with the ``return`` keyword, but they can't return any value. Referencing functions ^^^^^^^^^^^^^^^^^^^^^ -Functions are first-class items in terms of the :ref:`Callable ` object. Referencing a -function by name without calling it will automatically generate the proper +Functions are first-class values in terms of the :ref:`Callable ` object. +Referencing a function by name without calling it will automatically generate the proper callable. This can be used to pass functions as arguments. :: @@ -1368,43 +1371,86 @@ callable. This can be used to pass functions as arguments. func _ready() -> void: var my_array = [1, 2, 3] var plus_one = map(my_array, add1) - print(plus_one) # Prints [2, 3, 4]. + print(plus_one) # Prints `[2, 3, 4]`. + +.. note:: -.. note:: Callables **must** be called with the ``call`` method. You cannot use - the ``()`` operator directly. This behavior is implemented to avoid - performance issues on direct function calls. + Callables **must** be called with the :ref:`call() ` method. + You cannot use the ``()`` operator directly. This behavior is implemented to avoid + performance issues on direct function calls. Lambda functions ^^^^^^^^^^^^^^^^ -Lambda functions allow you to declare functions that do not belong to a class. Instead a :ref:`Callable ` object is created and assigned to a variable directly. -This can be useful to create Callables to pass around without polluting the class scope. +Lambda functions allow you to declare functions that do not belong to a class. Instead, a +:ref:`Callable ` object is created and assigned to a variable directly. +This can be useful to create callables to pass around without polluting the class scope. :: - var lambda = func(x): print(x) - lambda.call(42) # Prints "42" + var lambda = func (x): + print(x) + +To call the created lambda you can use the :ref:`call() ` method:: -Lambda functions can be named for debugging purposes:: + lambda.call(42) # Prints `42`. + +Lambda functions can be named for debugging purposes (the name is displayed in the Debugger):: var lambda = func my_lambda(x): print(x) -Note that if you want to return a value from a lambda, an explicit ``return`` +You can specify type hints for lambda functions in the same way as for regular ones:: + + var lambda := func (x: int) -> void: + print(x) + +Note that if you want to return a value from a lambda function, an explicit ``return`` is required (you can't omit ``return``):: - var lambda = func(x): return x ** 2 + var lambda = func (x): return x ** 2 print(lambda.call(2)) # Prints `4`. -Lambda functions capture the local environment. Local variables are passed by value, so they won't be updated in the lambda if changed in the local function:: +Lambda functions capture the local environment:: var x = 42 - var my_lambda = func(): print(x) - my_lambda.call() # Prints "42" - x = "Hello" - my_lambda.call() # Prints "42" + var lambda = func (): + print(x) # Prints `42`. + lambda.call() + +.. warning:: -.. note:: The values of the outer scope behave like constants. Therefore, if you declare an array or dictionary, it can still be modified afterwards. + Local variables are captured by value once, when the lambda is created. + So they won't be updated in the lambda if reassigned in the outer function:: + + var x = 42 + var lambda = func (): print(x) + lambda.call() # Prints `42`. + x = "Hello" + lambda.call() # Prints `42`. + + Also, a lambda cannot reassign an outer local variable. After exiting the lambda, + the variable will be unchanged, because the lambda capture implicitly shadows it:: + + var x = 42 + var lambda = func (): + print(x) # Prints `42`. + x = "Hello" # Produces the `CONFUSABLE_CAPTURE_REASSIGNMENT` warning. + print(x) # Prints `Hello`. + lambda.call() + print(x) # Prints `42`. + + However, if you use pass-by-reference data types (arrays, dictionaries, and objects), + then the content changes are shared until you reassign the variable:: + + var a = [] + var lambda = func (): + a.append(1) + print(a) # Prints `[1]`. + a = [2] # Produces the `CONFUSABLE_CAPTURE_REASSIGNMENT` warning. + print(a) # Prints `[2]`. + lambda.call() + print(a) # Prints `[1]`. Static functions ^^^^^^^^^^^^^^^^ @@ -1415,7 +1461,7 @@ A static function has access to static variables. Also static functions are usef static func sum2(a, b): return a + b -Lambdas cannot be declared static. +Lambda functions cannot be declared static. See also `Static variables`_ and `Static constructor`_. @@ -1542,6 +1588,10 @@ in the loop variable. for x in [5, 7, 11]: statement # Loop iterates 3 times with 'x' as 5, then 7 and finally 11. + var names = ["John", "Marta", "Samantha", "Jimmy"] + for name: String in names: # Typed loop variable. + print(name) # Prints name's content. + var dict = {"a": 0, "b": 1, "c": 2} for i in dict: print(dict[i]) # Prints 0, then 1, then 2. @@ -1838,6 +1888,14 @@ If you want to use ``extends`` too, you can keep both on the same line:: and this includes arrays and dictionaries. This is in the spirit of thread safety, since scripts can be initialized in separate threads without the user knowing. +.. warning:: + + The Godot editor will hide these custom classes with names that beging with the prefix + "Editor" in the 'Create New Node' or 'Create New Scene' dialog windows. The classes + are available for instantiation at runtime via their class names, but are + automatically hidden by the editor windows along with the built-in editor nodes used + by the Godot editor. + Inheritance ^^^^^^^^^^^ @@ -2061,7 +2119,7 @@ Example:: .. note:: - Unlike ``setget`` in previous Godot versions, the properties setter and getter are **always** called (except as noted below), + Unlike ``setget`` in previous Godot versions, ``set`` and ``get`` methods are **always** called (except as noted below), even when accessed inside the same class (with or without prefixing with ``self.``). This makes the behavior consistent. If you need direct access to the value, use another variable for direct access and make the property code use that name. diff --git a/tutorials/scripting/gdscript/gdscript_styleguide.rst b/tutorials/scripting/gdscript/gdscript_styleguide.rst index a3ebacc633e..b069c790987 100644 --- a/tutorials/scripting/gdscript/gdscript_styleguide.rst +++ b/tutorials/scripting/gdscript/gdscript_styleguide.rst @@ -707,7 +707,7 @@ are constants: FIRE, } -Write enums with each item on its own line. This allows adding documentation comments abve each item +Write enums with each item on its own line. This allows adding documentation comments above each item more easily, and also makes for cleaner diffs in version control when items are added or removed. **Good**: @@ -843,7 +843,7 @@ variables, in that order. .. note:: - The GDScript compiler evaluates onready variables right before the ``_ready`` + GDScript evaluates ``@onready`` variables right before the ``_ready`` callback. You can use that to cache node dependencies, that is to say, to get child nodes in the scene that your class relies on. This is what the example above shows. diff --git a/tutorials/scripting/singletons_autoload.rst b/tutorials/scripting/singletons_autoload.rst index 8fb76e64c2c..851c1a2a7c6 100644 --- a/tutorials/scripting/singletons_autoload.rst +++ b/tutorials/scripting/singletons_autoload.rst @@ -60,8 +60,8 @@ You can create an Autoload to load a scene or a script that inherits from .. image:: img/singleton.webp -To autoload a scene or script, select **Project > Project Settings** from the -menu and switch to the **Autoload** tab. +To autoload a scene or script, start from the menu and navigate to +**Project > Project Settings > Globals > Autoload**. .. image:: img/autoload_tab.webp @@ -132,6 +132,9 @@ To begin, download the template from here: `singleton_autoload_starter.zip `_ and open it in Godot. +A window notifying you that the project was last opened in an older Godot version +may appear, that's not an issue. Click *Ok* to open the project. + The project contains two scenes: ``scene_1.tscn`` and ``scene_2.tscn``. Each scene contains a label displaying the scene name and a button with its ``pressed()`` signal connected. When you run the project, it starts in @@ -145,8 +148,9 @@ Make sure it inherits from ``Node``: .. image:: img/autoload_script.webp -The next step is to add this script to the autoLoad list. Open -**Project > Project Settings** from the menu, switch to the **Autoload** tab and +The next step is to add this script to the autoLoad list. +Starting from the menu, open +**Project > Project Settings > Globals > Autoload** and select the script by clicking the browse button or typing its path: ``res://global.gd``. Press **Add** to add it to the autoload list: diff --git a/tutorials/shaders/advanced_postprocessing.rst b/tutorials/shaders/advanced_postprocessing.rst index 1461cabaab6..e06b97e148a 100644 --- a/tutorials/shaders/advanced_postprocessing.rst +++ b/tutorials/shaders/advanced_postprocessing.rst @@ -46,6 +46,8 @@ and sets the vertex position in clip space directly. .. code-block:: glsl shader_type spatial; + // Prevent the quad from being affected by lighting and fog. This also improves performance. + render_mode unshaded, disable_fog; void vertex() { POSITION = vec4(VERTEX.xy, 1.0, 1.0); diff --git a/tutorials/shaders/img/shader_material_create_mesh.png b/tutorials/shaders/img/shader_material_create_mesh.png deleted file mode 100644 index 12aba76e1f4..00000000000 Binary files a/tutorials/shaders/img/shader_material_create_mesh.png and /dev/null differ diff --git a/tutorials/shaders/img/shader_material_create_mesh.webp b/tutorials/shaders/img/shader_material_create_mesh.webp new file mode 100644 index 00000000000..1b6a55cc990 Binary files /dev/null and b/tutorials/shaders/img/shader_material_create_mesh.webp differ diff --git a/tutorials/shaders/img/visual_shader_create.webp b/tutorials/shaders/img/visual_shader_create.webp index 64ed1a69c58..e11f9f215ed 100644 Binary files a/tutorials/shaders/img/visual_shader_create.webp and b/tutorials/shaders/img/visual_shader_create.webp differ diff --git a/tutorials/shaders/img/visual_shader_create2.webp b/tutorials/shaders/img/visual_shader_create2.webp index 02a5a55ce51..48410d1894d 100644 Binary files a/tutorials/shaders/img/visual_shader_create2.webp and b/tutorials/shaders/img/visual_shader_create2.webp differ diff --git a/tutorials/shaders/img/visual_shader_editor2.png b/tutorials/shaders/img/visual_shader_editor2.png deleted file mode 100644 index f648049acfa..00000000000 Binary files a/tutorials/shaders/img/visual_shader_editor2.png and /dev/null differ diff --git a/tutorials/shaders/img/visual_shader_editor2.webp b/tutorials/shaders/img/visual_shader_editor2.webp new file mode 100644 index 00000000000..607a77281fc Binary files /dev/null and b/tutorials/shaders/img/visual_shader_editor2.webp differ diff --git a/tutorials/shaders/img/vs_boolean.webp b/tutorials/shaders/img/vs_boolean.webp index b87ed5d9c7d..0fc207e178f 100644 Binary files a/tutorials/shaders/img/vs_boolean.webp and b/tutorials/shaders/img/vs_boolean.webp differ diff --git a/tutorials/shaders/img/vs_expression.gif b/tutorials/shaders/img/vs_expression.gif deleted file mode 100644 index 8a95e1e905d..00000000000 Binary files a/tutorials/shaders/img/vs_expression.gif and /dev/null differ diff --git a/tutorials/shaders/img/vs_fresnel.png b/tutorials/shaders/img/vs_fresnel.png deleted file mode 100644 index aa132e56f54..00000000000 Binary files a/tutorials/shaders/img/vs_fresnel.png and /dev/null differ diff --git a/tutorials/shaders/img/vs_fresnel.webp b/tutorials/shaders/img/vs_fresnel.webp new file mode 100644 index 00000000000..f3b581e62d3 Binary files /dev/null and b/tutorials/shaders/img/vs_fresnel.webp differ diff --git a/tutorials/shaders/img/vs_node.webp b/tutorials/shaders/img/vs_node.webp index 5ec24b67141..f430180e2ae 100644 Binary files a/tutorials/shaders/img/vs_node.webp and b/tutorials/shaders/img/vs_node.webp differ diff --git a/tutorials/shaders/img/vs_popup.png b/tutorials/shaders/img/vs_popup.png deleted file mode 100644 index 356d2b61d8f..00000000000 Binary files a/tutorials/shaders/img/vs_popup.png and /dev/null differ diff --git a/tutorials/shaders/img/vs_popup.webp b/tutorials/shaders/img/vs_popup.webp new file mode 100644 index 00000000000..b14fbee5862 Binary files /dev/null and b/tutorials/shaders/img/vs_popup.webp differ diff --git a/tutorials/shaders/img/vs_reroute.webp b/tutorials/shaders/img/vs_reroute.webp new file mode 100644 index 00000000000..dbad681b5b0 Binary files /dev/null and b/tutorials/shaders/img/vs_reroute.webp differ diff --git a/tutorials/shaders/img/vs_reroute_handle.webp b/tutorials/shaders/img/vs_reroute_handle.webp new file mode 100644 index 00000000000..baa4ce5606c Binary files /dev/null and b/tutorials/shaders/img/vs_reroute_handle.webp differ diff --git a/tutorials/shaders/img/vs_sampler.webp b/tutorials/shaders/img/vs_sampler.webp index ddf528e9aa7..d2705032b05 100644 Binary files a/tutorials/shaders/img/vs_sampler.webp and b/tutorials/shaders/img/vs_sampler.webp differ diff --git a/tutorials/shaders/img/vs_scalar.webp b/tutorials/shaders/img/vs_scalar.webp index d078d75028a..b8bb219780b 100644 Binary files a/tutorials/shaders/img/vs_scalar.webp and b/tutorials/shaders/img/vs_scalar.webp differ diff --git a/tutorials/shaders/img/vs_switch.png b/tutorials/shaders/img/vs_switch.png deleted file mode 100644 index 04cc8edfa38..00000000000 Binary files a/tutorials/shaders/img/vs_switch.png and /dev/null differ diff --git a/tutorials/shaders/img/vs_switch.webp b/tutorials/shaders/img/vs_switch.webp new file mode 100644 index 00000000000..ec2e1b4ac1f Binary files /dev/null and b/tutorials/shaders/img/vs_switch.webp differ diff --git a/tutorials/shaders/img/vs_transform.webp b/tutorials/shaders/img/vs_transform.webp index 7c71d8b01b1..c61b10f1bf1 100644 Binary files a/tutorials/shaders/img/vs_transform.webp and b/tutorials/shaders/img/vs_transform.webp differ diff --git a/tutorials/shaders/img/vs_vector.webp b/tutorials/shaders/img/vs_vector.webp index 8c2788c3b05..7a1a813499e 100644 Binary files a/tutorials/shaders/img/vs_vector.webp and b/tutorials/shaders/img/vs_vector.webp differ diff --git a/tutorials/shaders/shader_reference/canvas_item_shader.rst b/tutorials/shaders/shader_reference/canvas_item_shader.rst index 3aa5c5d6127..8a9f081e9fe 100644 --- a/tutorials/shaders/shader_reference/canvas_item_shader.rst +++ b/tutorials/shaders/shader_reference/canvas_item_shader.rst @@ -50,24 +50,26 @@ Global built-ins Global built-ins are available everywhere, including custom functions. -+-------------------+----------------------------------------------------------------------------------------+ -| Built-in | Description | -+===================+========================================================================================+ -| in float **TIME** | Global time since the engine has started, in seconds (always positive). | -| | It's subject to the rollover setting (which is 3,600 seconds by default). | -| | It's not affected by :ref:`time_scale` | -| | or pausing, but you can define a global shader uniform to add a "scaled" | -| | ``TIME`` variable if desired. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **PI** | A ``PI`` constant (``3.141592``). | -| | A ration of circle's circumference to its diameter and amount of radians in half turn. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **TAU** | A ``TAU`` constant (``6.283185``). | -| | An equivalent of ``PI * 2`` and amount of radians in full turn. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **E** | An ``E`` constant (``2.718281``). | -| | Euler's number and a base of the natural logarithm. | -+-------------------+----------------------------------------------------------------------------------------+ ++-------------------+-----------------------------------------------------------------------------------------+ +| Built-in | Description | ++===================+=========================================================================================+ +| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600 | +| | seconds (which can be changed with the | +| | :ref:`rollover`| +| | setting). It's not affected by :ref:`time_scale` or | +| | pausing. If you need a ``TIME`` variable that can be scaled or paused, add your own | +| | :ref:`global shader uniform` and update it each | +| | frame. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **PI** | A ``PI`` constant (``3.141592``). | +| | A ration of circle's circumference to its diameter and amount of radians in half turn. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **TAU** | A ``TAU`` constant (``6.283185``). | +| | An equivalent of ``PI * 2`` and amount of radians in full turn. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **E** | An ``E`` constant (``2.718281``). | +| | Euler's number and a base of the natural logarithm. | ++-------------------+-----------------------------------------------------------------------------------------+ Vertex built-ins ^^^^^^^^^^^^^^^^ @@ -132,9 +134,9 @@ is usually: +--------------------------------+----------------------------------------------------+ | inout float **POINT_SIZE** | Point size for point drawing. | +--------------------------------+----------------------------------------------------+ -| in vec4 **CUSTOM0** | | +| in vec4 **CUSTOM0** | Custom value from vertex primitive. | +--------------------------------+----------------------------------------------------+ -| in vec4 **CUSTOM1** | | +| in vec4 **CUSTOM1** | Custom value from vertex primitive. | +--------------------------------+----------------------------------------------------+ Fragment built-ins diff --git a/tutorials/shaders/shader_reference/fog_shader.rst b/tutorials/shaders/shader_reference/fog_shader.rst index 677db5be5d2..b673c7395ca 100644 --- a/tutorials/shaders/shader_reference/fog_shader.rst +++ b/tutorials/shaders/shader_reference/fog_shader.rst @@ -35,7 +35,13 @@ Global built-ins are available everywhere, including in custom functions. +---------------------------------+-----------------------------------------------------------------------------------------+ | Built-in | Description | +=================================+=========================================================================================+ -| in float **TIME** | Global time, in seconds. | +| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600 | +| | seconds (which can be changed with the | +| | :ref:`rollover`| +| | setting). It's not affected by :ref:`time_scale` or | +| | pausing. If you need a ``TIME`` variable that can be scaled or paused, add your own | +| | :ref:`global shader uniform` and update it each | +| | frame. | +---------------------------------+-----------------------------------------------------------------------------------------+ | in float **PI** | A ``PI`` constant (``3.141592``). | | | A ratio of a circle's circumference to its diameter and amount of radians in half turn. | diff --git a/tutorials/shaders/shader_reference/particle_shader.rst b/tutorials/shaders/shader_reference/particle_shader.rst index 177eee4204d..7e67138d525 100644 --- a/tutorials/shaders/shader_reference/particle_shader.rst +++ b/tutorials/shaders/shader_reference/particle_shader.rst @@ -55,19 +55,25 @@ Global built-ins Global built-ins are available everywhere, including custom functions. -+-------------------+----------------------------------------------------------------------------------------+ -| Built-in | Description | -+===================+========================================================================================+ -| in float **TIME** | Global time, in seconds. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **PI** | A ``PI`` constant (``3.141592``). | -| | A ration of circle's circumference to its diameter and amount of radians in half turn. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **TAU** | A ``TAU`` constant (``6.283185``). | -| | An equivalent of ``PI * 2`` and amount of radians in full turn. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **E** | An ``E`` constant (``2.718281``). Euler's number and a base of the natural logarithm. | -+-------------------+----------------------------------------------------------------------------------------+ ++-------------------+-----------------------------------------------------------------------------------------+ +| Built-in | Description | ++===================+=========================================================================================+ +| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600 | +| | seconds (which can be changed with the | +| | :ref:`rollover`| +| | setting). It's not affected by :ref:`time_scale` or | +| | pausing. If you need a ``TIME`` variable that can be scaled or paused, add your own | +| | :ref:`global shader uniform` and update it each | +| | frame. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **PI** | A ``PI`` constant (``3.141592``). | +| | A ration of circle's circumference to its diameter and amount of radians in half turn. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **TAU** | A ``TAU`` constant (``6.283185``). | +| | An equivalent of ``PI * 2`` and amount of radians in full turn. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **E** | An ``E`` constant (``2.718281``). Euler's number and a base of the natural logarithm. | ++-------------------+-----------------------------------------------------------------------------------------+ Start and Process built-ins ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 08ff01b34f7..db74e561809 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -83,6 +83,7 @@ Most GLSL ES 3.0 datatypes are supported: | **samplerCube** | Sampler type for binding Cubemaps, which are read as float. | +----------------------+---------------------------------------------------------------------------------+ | **samplerCubeArray** | Sampler type for binding Cubemap arrays, which are read as float. | +| | Only supported in Forward+ and Mobile, not Compatibility. | +----------------------+---------------------------------------------------------------------------------+ Comments @@ -927,9 +928,10 @@ table of the corresponding types: +----------------------+-------------------------+------------------------------------------------------------+ | **usampler3D** | **Texture3D** | | +----------------------+-------------------------+------------------------------------------------------------+ -| **samplerCube** | **Cubemap** | | +| **samplerCube** | **Cubemap** | See :ref:`doc_importing_images_changing_import_type` for | +| | | instructions on importing cubemaps for use in Godot. | +----------------------+-------------------------+------------------------------------------------------------+ -| **samplerCubeArray** | **CubemapArray** | | +| **samplerCubeArray** | **CubemapArray** | Only supported in Forward+ and Mobile, not Compatibility. | +----------------------+-------------------------+------------------------------------------------------------+ .. note:: Be careful when setting shader uniforms from GDScript, no error will @@ -966,6 +968,8 @@ The syntax also supports subgroups (it's not mandatory to declare the base group group_uniforms MyGroup.MySubgroup; +.. _doc_shading_language_global_uniforms: + Global uniforms ~~~~~~~~~~~~~~~ diff --git a/tutorials/shaders/shader_reference/sky_shader.rst b/tutorials/shaders/shader_reference/sky_shader.rst index 08a9424fc57..dd03498211c 100644 --- a/tutorials/shaders/shader_reference/sky_shader.rst +++ b/tutorials/shaders/shader_reference/sky_shader.rst @@ -154,7 +154,13 @@ There are 4 ``LIGHTX`` lights, accessed as ``LIGHT0``, ``LIGHT1``, ``LIGHT2``, a +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | Built-in | Description | +=================================+==========================================================================================================================+ -| in float **TIME** | Global time, in seconds. | +| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600 | +| | seconds (which can be changed with the | +| | :ref:`rollover` | +| | setting). It's not affected by :ref:`time_scale` or | +| | pausing. If you need a ``TIME`` variable that can be scaled or paused, add your own | +| | :ref:`global shader uniform` and update it each | +| | frame. | +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | in vec3 **POSITION** | Camera position in world space | +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+ diff --git a/tutorials/shaders/shader_reference/spatial_shader.rst b/tutorials/shaders/shader_reference/spatial_shader.rst index 3430f60f9f8..4e14ad78aae 100644 --- a/tutorials/shaders/shader_reference/spatial_shader.rst +++ b/tutorials/shaders/shader_reference/spatial_shader.rst @@ -96,19 +96,25 @@ Global built-ins Global built-ins are available everywhere, including custom functions. -+-------------------+----------------------------------------------------------------------------------------+ -| Built-in | Description | -+===================+========================================================================================+ -| in float **TIME** | Global time, in seconds. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **PI** | A ``PI`` constant (``3.141592``). | -| | A ration of circle's circumference to its diameter and amount of radians in half turn. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **TAU** | A ``TAU`` constant (``6.283185``). | -| | An equivalent of ``PI * 2`` and amount of radians in full turn. | -+-------------------+----------------------------------------------------------------------------------------+ -| in float **E** | An ``E`` constant (``2.718281``). Euler's number and a base of the natural logarithm. | -+-------------------+----------------------------------------------------------------------------------------+ ++-------------------+-----------------------------------------------------------------------------------------+ +| Built-in | Description | ++===================+=========================================================================================+ +| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600 | +| | seconds (which can be changed with the | +| | :ref:`rollover`| +| | setting). It's not affected by :ref:`time_scale` or | +| | pausing. If you need a ``TIME`` variable that can be scaled or paused, add your own | +| | :ref:`global shader uniform` and update it each | +| | frame. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **PI** | A ``PI`` constant (``3.141592``). | +| | A ration of circle's circumference to its diameter and amount of radians in half turn. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **TAU** | A ``TAU`` constant (``6.283185``). | +| | An equivalent of ``PI * 2`` and amount of radians in full turn. | ++-------------------+-----------------------------------------------------------------------------------------+ +| in float **E** | An ``E`` constant (``2.718281``). Euler's number and a base of the natural logarithm. | ++-------------------+-----------------------------------------------------------------------------------------+ Vertex built-ins ^^^^^^^^^^^^^^^^ @@ -230,19 +236,26 @@ shader, this value can be used as desired. +----------------------------------------+--------------------------------------------------------+ | in vec4 **BONE_WEIGHTS** | | +----------------------------------------+--------------------------------------------------------+ -| in vec4 **CUSTOM0** | | +| in vec4 **CUSTOM0** | Custom value from vertex primitive. When using extra | +| | UVs, ``xy`` is UV3 and ``zw`` is UV4. | +----------------------------------------+--------------------------------------------------------+ -| in vec4 **CUSTOM1** | | +| in vec4 **CUSTOM1** | Custom value from vertex primitive. When using extra | +| | UVs, ``xy`` is UV5 and ``zw`` is UV6. | +----------------------------------------+--------------------------------------------------------+ -| in vec4 **CUSTOM2** | | +| in vec4 **CUSTOM2** | Custom value from vertex primitive. When using extra | +| | UVs, ``xy`` is UV7 and ``zw`` is UV8. | +----------------------------------------+--------------------------------------------------------+ -| in vec4 **CUSTOM3** | | +| in vec4 **CUSTOM3** | Custom value from vertex primitive. | +----------------------------------------+--------------------------------------------------------+ .. note:: ``MODELVIEW_MATRIX`` combines both the ``MODEL_MATRIX`` and ``VIEW_MATRIX`` and is better suited when floating point issues may arise. For example, if the object is very far away from the world origin, you may run into floating point issues when using the separated ``MODEL_MATRIX`` and ``VIEW_MATRIX``. +.. note:: + + ``INV_VIEW_MATRIX`` is the matrix used for rendering the object in that pass, not like ``MAIN_CAM_INV_VIEW_MATRIX``, which is the matrix of the camera in the scene. In the shadow pass, ``INV_VIEW_MATRIX``'s view is based on the camera that is located at the position of the light. + Fragment built-ins ^^^^^^^^^^^^^^^^^^ diff --git a/tutorials/shaders/visual_shaders.rst b/tutorials/shaders/visual_shaders.rst index 276d778809d..de3f172621c 100644 --- a/tutorials/shaders/visual_shaders.rst +++ b/tutorials/shaders/visual_shaders.rst @@ -22,21 +22,23 @@ Creating a VisualShader VisualShaders can be created in any :ref:`class_ShaderMaterial`. To begin using VisualShaders, create a new ``ShaderMaterial`` in an object of your choice. -.. image:: img/shader_material_create_mesh.png +.. image:: img/shader_material_create_mesh.webp -Then assign a :ref:`class_VisualShader` resource to the ``Shader`` property. +Then assign a :ref:`class_Shader` resource to the ``Shader`` property. .. image:: img/visual_shader_create.webp Click on the new ``Shader`` resource and the Create Shader dialog will -open automatically. Change the Type option to VisualShader in the dropdown. +open automatically. Change the Type option to :ref:`class_VisualShader` +in the dropdown, then give it a name. .. image:: img/visual_shader_create2.webp -The layout of the Visual Shader Editor comprises two parts: +Click on the visual shader you just created to open the Shader Editor. +The layout of the Shader Editor comprises two parts: the upper toolbar and the graph itself. -.. image:: img/visual_shader_editor2.png +.. image:: img/visual_shader_editor2.webp From left to right in the toolbar: @@ -46,6 +48,12 @@ From left to right in the toolbar: script shaders, it defines what built-in nodes will be available. - The following buttons and number input control the zooming level, grid snapping and distance between grid lines (in pixels). +- The toggle controls if the graph minimap in the bottom right of the editor + is visible or not. +- The automatically arrange selected nodes button will try to organize any + nodes you have selected as efficiently and cleanly as possible. +- The Manage Varyings button opens a dropdown that lets you add or remove a + varying. - The last icon shows the generated shader code corresponding to your graph. .. note:: @@ -68,7 +76,7 @@ create your shader. To add a new node, click on the ``Add Node`` button on the upper left corner or right click on any empty location in the graph, and a menu will pop up. -.. image:: img/vs_popup.png +.. image:: img/vs_popup.webp This popup has the following properties: @@ -117,7 +125,7 @@ These ports are colored to differentiate type of port: - Description - Example * - Scalar - - Cyan + - Gray - Scalar is a single value. - |scalar| * - Vector @@ -125,15 +133,15 @@ These ports are colored to differentiate type of port: - Vector is a set of values. - |vector| * - Boolean - - Blue + - Green - On or off, true or false. - |boolean| * - Transform - - Orange + - Pink - A matrix, usually used to transform vertices. - |transform| * - Sampler - - Yellow + - Orange - A texture sampler. It can be used to sample textures. - |sampler| @@ -160,14 +168,28 @@ parsing or compilation errors will be printed to the Output tab. The outputs are initialized to their zero value by default. The node is located under the Special tab and can be used in all shader modes. -.. image:: img/vs_expression.gif - The possibilities of this node are almost limitless – you can write complex procedures, and use all the power of text-based shaders, such as loops, the ``discard`` keyword, extended types, etc. For example: .. image:: img/vs_expression2.png +Reroute node +++++++++++++ + +The ``Reroute`` node is used purely for organizational purposes. In a complicated +shader with many nodes you may find that the paths between nodes can make +things hard to read. Reroute, as its name suggests, allows you to adjust the path +between nodes to make things easier to read. You can even have multiple reroute +nodes for a single path, which can be used to make right angles. + +.. image:: img/vs_reroute.webp + +To move a reroute node move your mouse cursor above it, and grab the handle that +appears. + +.. image:: img/vs_reroute_handle.webp + Fresnel node ++++++++++++ @@ -176,7 +198,7 @@ a scalar which is the saturated dot product between them. Additionally, you can setup the inversion and the power of equation. The ``Fresnel`` node is great for adding a rim-like lighting effect to objects. -.. image:: img/vs_fresnel.png +.. image:: img/vs_fresnel.webp Boolean node ++++++++++++ @@ -205,4 +227,4 @@ The ``Switch`` node returns a vector if the boolean condition is ``true`` or ``false``. ``Boolean`` was introduced above. If you convert a vector to a true boolean, all components of the vector should be above zero. -.. image:: img/vs_switch.png +.. image:: img/vs_switch.webp diff --git a/tutorials/shaders/your_first_shader/your_first_2d_shader.rst b/tutorials/shaders/your_first_shader/your_first_2d_shader.rst index 2d5f5c29285..ff84bbde227 100644 --- a/tutorials/shaders/your_first_shader/your_first_2d_shader.rst +++ b/tutorials/shaders/your_first_shader/your_first_2d_shader.rst @@ -33,7 +33,7 @@ material, the material must be attached to each object. All objects derived from a :ref:`CanvasItem ` have a material property. This includes all :ref:`GUI elements `, :ref:`Sprite2Ds -`, :ref:`TileMaps `, :ref:`MeshInstance2Ds +`, :ref:`TileMapLayers `, :ref:`MeshInstance2Ds ` etc. They also have an option to inherit their parent's material. This can be useful if you have a large number of nodes that you want to use the same material. diff --git a/tutorials/troubleshooting.rst b/tutorials/troubleshooting.rst index 186c7c65106..0cc7a44a8ef 100644 --- a/tutorials/troubleshooting.rst +++ b/tutorials/troubleshooting.rst @@ -81,6 +81,13 @@ output). You can work this around by changing the debug port used by the project in the Editor Settings (**Network > Debug > Remote Port**). The default is ``6007``; try another value that is greater than ``1024``, such as ``7007``. +On Windows, when loading the project for the first time after the PC is turned on, +Windows Defender will cause the filesystem cache validation on project startup +to take significantly longer. This is especially noticable in projects with a +large number of files. Consinder adding the project folder to the list of exclusions +by going to Virus & threat protection > Virus & threat protection settings > +Add or remove exclusions. + The Godot editor appears frozen after clicking the system console ----------------------------------------------------------------- @@ -130,6 +137,12 @@ seen on Windows, as Linux does not have support for ShadowPlay. To disable this overlay, press :kbd:`Alt + Z` (default shortcut for the NVIDIA overlay) and disable **Settings > HUD Layout > Status Indicator** in the NVIDIA overlay. +Alternatively, you can install the `new NVIDIA app +` which replaces GeForce +Experience and does not suffer from this issue. Unlike GeForce Experience, the +NVIDIA app draws the replay indicator in the corner of the screen as opposed to +the corner of each window. + The editor or project appears overly sharp or blurry ---------------------------------------------------- diff --git a/tutorials/ui/bbcode_in_richtextlabel.rst b/tutorials/ui/bbcode_in_richtextlabel.rst index 5250e33524f..55fa0ba3cee 100644 --- a/tutorials/ui/bbcode_in_richtextlabel.rst +++ b/tutorials/ui/bbcode_in_richtextlabel.rst @@ -223,6 +223,12 @@ The following script will result in the same visual output as using Reference --------- +.. seealso:: + + *Some* of these BBCode tags can be used in tooltips for ``@export`` script + variables as well as in the XML source of the class reference. For more + information, see :ref:`Class reference BBCode `. + .. list-table:: :class: wrap-normal :width: 100% diff --git a/tutorials/ui/gui_using_fonts.rst b/tutorials/ui/gui_using_fonts.rst index 970c3d2ab65..5da7ea2a249 100644 --- a/tutorials/ui/gui_using_fonts.rst +++ b/tutorials/ui/gui_using_fonts.rst @@ -555,10 +555,33 @@ For example, here's the `Inter V `__ font with a .. tip:: - While variable font axis names and scales aren't standardized, some common - conventions are usually followed by font designers. For instance, the - *weight* axis typically uses ``400`` as the "regular" font weight and - ``700`` as the "bold" font weight. + While variable font axis names and scales aren't standardized, + some common conventions are usually followed by font designers. + The *weight* axis is standardized in OpenType to work as follows: + + +------------+--------------------------------+ + | Axis value | Effective font weight | + +============+================================+ + | ``100`` | Thin (Hairline) | + +------------+--------------------------------+ + | ``200`` | Extra Light (Ultra Light) | + +------------+--------------------------------+ + | ``300`` | Light | + +------------+--------------------------------+ + | ``400`` | **Regular (Normal)** | + +------------+--------------------------------+ + | ``500`` | Medium | + +------------+--------------------------------+ + | ``600`` | Semi-Bold (Demi-Bold) | + +------------+--------------------------------+ + | ``700`` | **Bold** | + +------------+--------------------------------+ + | ``800`` | Extra Bold (Ultra Bold) | + +------------+--------------------------------+ + | ``900`` | Black (Heavy) | + +------------+--------------------------------+ + | ``950`` | Extra Black (Ultra Black) | + +------------+--------------------------------+ You can save the FontVariation to a ``.tres`` resource file to reuse it in other places: diff --git a/tutorials/xr/a_better_xr_start_script.rst b/tutorials/xr/a_better_xr_start_script.rst index 4d9b10385e9..cc97a695111 100644 --- a/tutorials/xr/a_better_xr_start_script.rst +++ b/tutorials/xr/a_better_xr_start_script.rst @@ -331,7 +331,7 @@ If you haven't, you can connect a method to the signal that performs additional xr_is_focussed = false # pause our game - process_mode = Node.PROCESS_MODE_DISABLED + get_tree().paused = true emit_signal("focus_lost") @@ -355,7 +355,7 @@ If you haven't, you can connect a method to the signal that performs additional _xrIsFocused = false; // Pause our game - ProcessMode = ProcessModeEnum.Disabled; + GetTree().Paused = true; EmitSignal(SignalName.FocusLost); } @@ -395,7 +395,7 @@ While handling our signal we will update the focusses state, unpause our node an xr_is_focussed = true # unpause our game - process_mode = Node.PROCESS_MODE_INHERIT + get_tree().paused = false emit_signal("focus_gained") @@ -414,7 +414,7 @@ While handling our signal we will update the focusses state, unpause our node an _xrIsFocused = true; // Un-pause our game - ProcessMode = ProcessModeEnum.Inherit; + GetTree().Paused = false; EmitSignal(SignalName.FocusGained); } diff --git a/tutorials/xr/img/openxr_enable_hand_tracking_meta.webp b/tutorials/xr/img/openxr_enable_hand_tracking_meta.webp new file mode 100644 index 00000000000..1d1860a1f11 Binary files /dev/null and b/tutorials/xr/img/openxr_enable_hand_tracking_meta.webp differ diff --git a/tutorials/xr/img/openxr_hand_interaction_profile.webp b/tutorials/xr/img/openxr_hand_interaction_profile.webp new file mode 100644 index 00000000000..14f471c2c66 Binary files /dev/null and b/tutorials/xr/img/openxr_hand_interaction_profile.webp differ diff --git a/tutorials/xr/img/openxr_hand_skeleton.webp b/tutorials/xr/img/openxr_hand_skeleton.webp deleted file mode 100644 index 22fb395d689..00000000000 Binary files a/tutorials/xr/img/openxr_hand_skeleton.webp and /dev/null differ diff --git a/tutorials/xr/img/openxr_hand_tracking_nodes.webp b/tutorials/xr/img/openxr_hand_tracking_nodes.webp new file mode 100644 index 00000000000..3d76d57200c Binary files /dev/null and b/tutorials/xr/img/openxr_hand_tracking_nodes.webp differ diff --git a/tutorials/xr/img/openxr_htc_hand_interaction_profile.webp b/tutorials/xr/img/openxr_htc_hand_interaction_profile.webp new file mode 100644 index 00000000000..ff96cccdac2 Binary files /dev/null and b/tutorials/xr/img/openxr_htc_hand_interaction_profile.webp differ diff --git a/tutorials/xr/img/openxr_msft_hand_interaction_profile.webp b/tutorials/xr/img/openxr_msft_hand_interaction_profile.webp new file mode 100644 index 00000000000..e674d3b8137 Binary files /dev/null and b/tutorials/xr/img/openxr_msft_hand_interaction_profile.webp differ diff --git a/tutorials/xr/img/openxr_simple_controller_hand.webp b/tutorials/xr/img/openxr_simple_controller_hand.webp new file mode 100644 index 00000000000..c9b1c7bcf30 Binary files /dev/null and b/tutorials/xr/img/openxr_simple_controller_hand.webp differ diff --git a/tutorials/xr/img/xr_enable_handtracking.webp b/tutorials/xr/img/xr_enable_handtracking.webp index 6ea76a3cdd9..afe8bcfcdb6 100644 Binary files a/tutorials/xr/img/xr_enable_handtracking.webp and b/tutorials/xr/img/xr_enable_handtracking.webp differ diff --git a/tutorials/xr/index.rst b/tutorials/xr/index.rst index 72367a410d0..39d6420d9f9 100644 --- a/tutorials/xr/index.rst +++ b/tutorials/xr/index.rst @@ -31,6 +31,7 @@ Advanced topics xr_room_scale openxr_composition_layers openxr_hand_tracking + openxr_body_tracking Godot XR Tools -------------- diff --git a/tutorials/xr/openxr_body_tracking.rst b/tutorials/xr/openxr_body_tracking.rst new file mode 100644 index 00000000000..6a40bf81ced --- /dev/null +++ b/tutorials/xr/openxr_body_tracking.rst @@ -0,0 +1,38 @@ +.. _doc_openxr_body_tracking: + +OpenXR body tracking +==================== + +Support for full body tracking in OpenXR is only just becoming available for a select few platforms. +As support solidifies information will be added to this page. + +HTC Tracker support +------------------- + +An option that has been available for some time is doing full body tracking using HTC trackers. +These are currently supported through SteamVR and on HTC Elite XR headsets. +They are exposed through the action map system. + +These trackers are identified by their roles which are assigned to them when configured. +Simply add :ref:`XRController3D ` nodes as children to +the :ref:`XROrigin3D ` node and assign one of the following trackers: + +.. list-table:: HTC trackers + :widths: 100 + :header-rows: 0 + + * - /user/vive_tracker_htcx/role/handheld_object + * - /user/vive_tracker_htcx/role/left_foot + * - /user/vive_tracker_htcx/role/right_foot + * - /user/vive_tracker_htcx/role/left_shoulder + * - /user/vive_tracker_htcx/role/right_shoulder + * - /user/vive_tracker_htcx/role/left_elbow + * - /user/vive_tracker_htcx/role/right_elbow + * - /user/vive_tracker_htcx/role/left_knee + * - /user/vive_tracker_htcx/role/right_knee + * - /user/vive_tracker_htcx/role/waist + * - /user/vive_tracker_htcx/role/chest + * - /user/vive_tracker_htcx/role/camera + * - /user/vive_tracker_htcx/role/keyboard + +You can now use these as targets for IK modifiers on a full body avatar. diff --git a/tutorials/xr/openxr_hand_tracking.rst b/tutorials/xr/openxr_hand_tracking.rst index e974b6b49f3..9f0da10f5db 100644 --- a/tutorials/xr/openxr_hand_tracking.rst +++ b/tutorials/xr/openxr_hand_tracking.rst @@ -1,201 +1,355 @@ .. _doc_openxr_hand_tracking: -The OpenXR hand tracking -======================== - -Hand tracking is the process by which the position and orientation of the players hands are tracked, -including the orientation of the players fingers. -We can identify 3 categories of this: - -One, hand tracking through external sensors such as cameras. -This is what Hololens, Quest, UltraLeap and similar devices do. -This often results in very accurate tracking of all fingers of the players hands. - -Two, hand tracking through VR gloves. -This method is still mostly experimental but is likely to gain popularity soon. -Gloves often have good finger tracking capabilities but their real selling point is the ability to restrict movement. -This allows the sensation of touch. -Gloves are often also recognised as controllers and often will have additional controls such as buttons embedded. - -Three, inferred hand tracking. -This has been the de facto approach since the early days of VR. -As we know the player is holding a controller and we know the position of this controller, -we can infer where to render the players hand. -Fingers can be positioned based on the controls the player is interacting with. -Many modern VR controllers have additional sensors to help determine finger positions on the controller. +OpenXR hand tracking +==================== + +Introduction +------------ .. note:: - Traditionally inferred hand tracking has been the responsibility of the game. - However the principles behind the action map have somewhat limited the viable options here. - Valve is currently the only XR Runtime that has implemented inferred hand tracking as part of the hand tracking extension. - There is an expectation that other XR Runtimes will follow this example in the near future. - - Until then we recommend that if your game depends on inferred hand tracking, - to use the hand assets that are part of Godot XR Tools. - -Tracking through interaction profiles -------------------------------------- - -Tracking the location and state of controllers are performed through interaction profiles. -Bindings can be set within the :ref:`action map `. - -However it is important to realise that in OpenXR controllers are bound to paths indicating the usage of these controllers. -I.e. the controller held in the players left hand is bound to ``/user/hand/left`` -while the controller in the players right hand is bound to ``/user/hand/right``. -And while not yet supported outside of the HTC tracker extension, -it is likely OpenXR will be extended with paths such as ``/user/foot/left`` and ``/user/foot/right`` at some point. - -.. warning:: - - This paradigm therefore begs the question what happens to a controller that is not being held by a user. - There is no answer to this question yet, this is still being debated and the specification may change in the near future. - The behavior is thus undefined and can be different for different platforms. - - The most common is that the controller will remain bound regardless of whether the player is actually holding the controller. - - However there are runtimes, such as the Quest, that can unbind a controller when it is not being held by the user. - - This may become the norm in the future and the expectation is that the action map system will be enhanced accordingly. - -The hand tracking extension ---------------------------- - -OpenXR has an extension that exposes hand tracking functionality. -This extension allows a game to request the hand skeleton with all bone positions for each hand. - -.. figure:: img/openxr_hand_skeleton.webp - :align: center - - Copyright (c) 2017-2022, The Khronos Group Inc. SPDX-License-Identifier: CC-BY-4.0 - -The above image shows the joints that have to be provided by each XR runtime that implements this extension. - -Currently Godot exposes this functionality through the :ref:`OpenXRHand ` node. -This is a helper node that will retrieve the hand tracking data from OpenXR and apply it to a skeleton in Godot. -You select either the left or right hand through the ``hand`` property on this node. - -The hand asset itself has to be provided by the developer and is thus separate from the OpenXRHand node. -You set the ``hand_skeleton`` on the OpenXRHand node to the skeleton it needs to apply the tracking data to. - -If supported by the XR runtime you can also set the ``motion_range`` property to limit how far the hand can close. - -The skeleton for this asset has to have the following bones: - -.. list-table:: OpenXR hand skeleton - :widths: 50 50 - :header-rows: 1 - - * - Left hand - - Right hand - * - Palm_L - - Palm_R - * - Wrist_L - - Wrist_R - * - Thumb_Metacarpal_L - - Thumb_Metacarpal_R - * - Thumb_Proximal_L - - Thumb_Proximal_R - * - Thumb_Distal_L - - Thumb_Distal_R - * - Thumb_Tip_L - - Thumb_Tip_R - * - Index_Metacarpal_L - - Index_Metacarpal_R - * - Index_Proximal_L - - Index_Proximal_R - * - Index_Intermediate_L - - Index_Intermediate_R - * - Index_Distal_L - - Index_Distal_R - * - Index_Tip_L - - Index_Tip_R - * - Middle_Metacarpal_L - - Middle_Metacarpal_R - * - Middle_Proximal_L - - Middle_Proximal_R - * - Middle_Intermediate_L - - Middle_Intermediate_R - * - Middle_Distal_L - - Middle_Distal_R - * - Middle_Tip_L - - Middle_Tip_R - * - Ring_Metacarpal_L - - Ring_Metacarpal_R - * - Ring_Proximal_L - - Ring_Proximal_R - * - Ring_Intermediate_L - - Ring_Intermediate_R - * - Ring_Distal_L - - Ring_Distal_R - * - Ring_Tip_L - - Ring_Tip_R - * - Little_Metacarpal_L - - Little_Metacarpal_R - * - Little_Proximal_L - - Little_Proximal_R - * - Little_Intermediate_L - - Little_Intermediate_R - * - Little_Distal_L - - Little_Distal_R - * - Little_Tip_L - - Little_Tip_R - -.. warning:: - - The skeleton data returned from different XR runtimes are often not compatible which poses a problem for cross platform development. - - For instance both Microsoft and Meta runtimes base the skeleton on the actual hands of the player. - These skeletons will thus conform to the size of the players hand. - - Contrast that to Valve where a fixed skeleton is used if inferred hand tracking is applied. - - We are still gathering experience on how best to deal with these differences in the platforms. - -When exporting to Meta Quest you need to enable the following setting: + This page focuses specifically on the feature set exposed through OpenXR. + Parts of the functionality presented here also applies to WebXR and can by provided + by other XR interfaces. + +When discussing hand tracking it is important to know that there are differences of opinion as to where lines are drawn. +The practical result of this is that there are differences in implementation between the different OpenXR runtimes. +You may find yourself in a place where chosen hardware doesn't support a piece of the puzzle or does things differently +enough from the other platforms that you need to do extra work. + +That said, recent improvements to the OpenXR specification are closing these gaps and as platforms implement +these improvements we are getting closer to a future where we have either full portability between platforms +or at least a clear way to detect the capabilities of a platform. + +When we look at the early days of VR the focus of the major platforms was on tracked controller based input. +Here we are tracking a physical device that also has buttons for further input. +From the tracking data we can infer the location of the player's hands but no further information is known, +traditionally it was left up to the game to implement a mechanism to display the player's hand and animate +the fingers based on further input from the controller, be it due to buttons being pressed or through proximity +sensors. +Often fingers are also placed based on context, what the user is holding, and what action a user is performing. + +More recently optical hand tracking has become a popular solution, where cameras track the user's hands +and full tracking data for the hand and finger positions becomes available. +Many vendors saw this as completely separate from controller tracking and introduced independent APIs to +access hand and finger positions and orientation data. +When handling input, it was up to the game developer to implement a gesture detection mechanism. + +This split also exists in OpenXR, where controller tracking is handled primarily by the action map system, +while optical hand tracking is primarily handled by the hand tracking API extension. + +However, the world is not that black and white and we're seeing a number of scenarios +where we cross the line: + + * Devices that fit in both categories, such as tracked gloves + and controllers such as the Index controller that also perform finger tracking. + * XR Runtimes that implement inferred hand tracking from controller data as a means + to solve proper finger placement for multiple controllers. + * XR applications that wish to seamlessly switch between controller and hand tracking + offering the same user experience regardless of approach used. + +OpenXR is answering this call by introducing further extensions that lets us query the capabilities of +the XR runtime/hardware or that add further functionality across this divide. +The problem that currently does remain is that there are gaps in adopting these extensions, +with some platforms thus not reporting capabilities to their full extent. +As such you may need to test for the features available on specific hardware +and adjust your approach accordingly. + +Demo project +------------ + +The information presented on this page was used to create a demo project that can be found +`here `_. + + +The Hand Tracking API +--------------------- + +As mentioned in our introduction, the hand tracking API is primarily used with optical hand tracking +and on many platforms only works when the user is not holding a controller. +Some platforms support controller inferred hand tracking meaning that you will get hand tracking data +even if the user is holding a controller. +This includes SteamVR, Meta Quest (currently native only but Meta link support is likely coming), +and hopefully soon others as well. + +The hand tracking implementation in Godot has been standardized around the Godot Humanoid Skeleton +and works both in OpenXR and WebXR. The instructions below will thus work in both environments. + +In order to use the hand tracking API with OpenXR you first need to enable it. +This can be done in the project settings: .. image:: img/xr_enable_handtracking.webp -Body tracking -------------- +For some standalone XR devices you also need to configure the hand tracking extension in export settings, +for instance for Meta Quest: + +.. image:: img/openxr_enable_hand_tracking_meta.webp + +Now you need to add 3 components into your scene for each hand: + + * A tracked node to position the hand. + * A properly skinned hand mesh with skeleton. + * A skeleton modifier that applies finger tracking data to the skeleton. + +.. image:: img/openxr_hand_tracking_nodes.webp + +Hand tracking node +^^^^^^^^^^^^^^^^^^ + +The hand tracking system uses separate hand trackers to track the position of the player's hands +within our tracking space. + +This information has been separated out for the following use cases: + + * Tracking happens in the local space of the :ref:`XROrigin3D ` node. + This node must be a child of the `XROrigin3D` node in order to be correctly placed. + * This node can be used as an IK target when an upper body mesh with arms is used instead + of separate hand meshes. + * Actual placement of the hands may be loosely bound to the tracking in scenarios such as + avatar creation UIs, fake mirrors, or similar situations + resulting in the hand mesh and finger tracking being localized elsewhere. + +We'll concentrate on the first use case only. + +For this you need to add an :ref:`XRNode3D ` node to your ``XROrigin3D`` node. + + * On this node the ``tracker`` should be set to ``/user/hand_tracker/left`` or ``/user/hand_tracker/right`` + for the left or right hand respectively. + * The ``pose`` should remain set to ``default``, no other option will work here. + * The checkbox ``Show When Tracked`` will automatically hide this node if no tracking data is available, + or make this node visible if tracking data is available. + +Rigged hand mesh +^^^^^^^^^^^^^^^^ + +In order to display our hand we need a hand mesh that is properly rigged and skinned. +For this Godot uses the hand bone structure as defined for the :ref:`Godot Humanoid ` +but optionally supporting an extra tip bone for each finger. + +The `OpenXR hand tracking demo `_ +contains example GLTF files of properly rigged hands. + +We will be using those here and add them as a child to our ``XRNode3D`` node. +We also need to enable editable children to gain access to our :ref:`Skeleton3D ` node. + +The hand skeleton modifier +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Finally we need to add a :ref:`XRHandModifier3D ` node as a child to our ``Skeleton3D`` node. +This node will obtain the finger tracking data from OpenXR and apply it the hand model. + +You need to set the ``Hand Tracker`` property to either ``/user/hand_tracker/left`` or ``/user/hand_tracker/right`` +depending on whether we are apply the tracking data of respectively the left or right hand. + +You can also set the ``Bone Update`` mode on this node. + + * ``Full`` applies the hand tracking data fully. + This does mean that the skeleton positioning will potentially reflect the size of the actual hand of the user. + This can lead to scrunching effect if meshes aren't weighted properly to account for this. + Make sure you test your game with players of all sizes when optical hand tracking is used! + * ``Rotation Only`` will only apply rotation to the bones of the hands and keep the bone length as is. + In this mode the size of the hand mesh doesn't change. + +With this added, when we run the project we should see the hand correctly displayed if hand tracking is supported. + +The hand tracking data source +----------------------------- + +This is an OpenXR extension that provides information about the source of the hand tracking data. +At this moment only a few runtimes implement it but if it is available, Godot will activate it. + +If this extension is not supported and thus unknown is returned, you can make the following assumptions: + + * If you are using SteamVR (including Steam link), only controller based hand tracking is supported. + * For any other runtime, if hand tracking is supported, only optical hand tracking is supported + (Note, Meta Link currently fall into this category). + * In all other cases, no hand tracking is supported at all. + +You can access this information through code: -At the time of writing, OpenXR does not support body tracking as part of the core spec. -We are expecting this to change in the near future as more and more body tracking solutions are hitting the market. +.. code-block:: gdscript -For now the only option available here is through HTC trackers. -There is an extension that becomes available if HTC trackers are supported by the XR runtime. -These are fully exposed through the action map system. + var hand_tracker : XRHandTracker = XRServer.get_tracker('/user/hand_tracker/left') + if hand_tracker: + if hand_tracker.has_tracking_data: + if hand_tracker.hand_tracking_source == XRHandTracker.HAND_TRACKING_SOURCE_UNKNOWN: + print("Hand tracking source unknown") + elif hand_tracker.hand_tracking_source == XRHandTracker.HAND_TRACKING_SOURCE_UNOBSTRUCTED: + print("Hand tracking source is optical hand tracking") + elif hand_tracker.hand_tracking_source == XRHandTracker.HAND_TRACKING_SOURCE_CONTROLLER: + print("Hand tracking data is inferred from controller data") + else: + print("Unknown hand tracking source ", hand_tracker.hand_tracking_source) + else: + print("Hand is currently not being tracked") + else: + print("No hand tracker registered") -Godot has full support for these and you can setup the trackers in the action map. -Each tracker is assigned a usage within the SteamVR interface. +This example simply logs the state for the left hand. + +If in this example no hand tracker is returned by ``get_tracker``, +this means the hand tracking API is not supported on the XR runtime at all. + +If there is a tracker but `has_tracking_data` is false, the user's hand is currently not being tracked. +This is likely caused by one of the following reasons: + + * The player's hand is not visible by any of the tracking cameras on the headset + * The player is currently using a controller and the headset only supports optical hand tracking + * The controller is turned off and only controller hand tracking is supported. + +Handling user input +------------------- + +Reacting to actions performed by the user is handled through :ref:`doc_xr_action_map` +if controllers are used. +In the action map you can map various inputs like the trigger or joystick on the controller +to an action. This can then drive logic in your game. + +When hand tracking is used we originally had no such inputs, +inputs are driven by gestures made by the user such as making a fist to grab +or pinching the thumb and index finger together to select something. +It was up to the game developer to implement this. + +Recognizing that there is an increasing demand for applications that can switch seamlessly +between controller and hand tracking and the need some form of basic input capability, +a number of extensions were added to the specification that provide some basic gesture recognition +and can be used with the action map. + +The hand interaction profile +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `hand interaction profile extension `_ +is a new core extension which supports pinch, grasp, and poke gestures and related poses. +There is still limited support for this extension but it should become available in more +runtimes in the near future. + +.. image:: img/openxr_hand_interaction_profile.webp + +The pinch gesture is triggered by pinching your thumb and index finger together. +This is often used as a select gesture for menu systems, similar to using your controller +to point at an object and press the trigger to select and is thus often mapped as such. + + * The ``pinch pose`` is a pose positioned in the middle between the tip of the thumb and + the tip of the index finger and oriented such that a ray cast can be used to identify a target. + * The ``pinch`` float input is a value between 0.0 (the tip of the thumb and index finger are apart) + and 1.0 (the tip of the thumb and index finger are touching). + * The ``pinch ready`` input is true when the tips of the fingers are (close to) touching. + +The grasp gesture is triggered by making a fist and is often used to pick items up, +similar to engaging the squeeze input on controllers. + + * The ``grasp`` float input is a value between 0.0 (open hand) and 1.0 (fist). + * The ``grasp ready`` input is true when the user made a fist. + +The poke gesture is triggered by extending your index finger, this one is a bit +of an exception as the pose at the tip of your index finger is often used to poke +an interactable object. The ``poke pose`` is a pose positioned on the tip of the index finger. + +Finally the ``aim activate (ready)`` input is defined as an input that is 1.0/true +when the index finger is extended and pointing at a target that can be activated. +How runtimes interpret this, is not clear. + +With this setup the normal ``left_hand`` and ``right_hand`` trackers are used and you can +thus seamlessly switch between controller and hand tracking input. + +.. note:: + + You need to enable the hand interaction profile extension in the OpenXR project settings. + +Microsoft hand interaction profile +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `Microsoft hand interaction profile extension `_ +was introduced by Microsoft and loosely mimics the simple controller profile. +Meta has also added support for this extension but only on their native OpenXR client, +it is currently not available over Meta Link. + +.. image:: img/openxr_msft_hand_interaction_profile.webp + +Pinch support is exposed through the ``select`` input, the value of which +is 0.0 when the tip of the thumb and index finger are apart +and 1.0 when they are together. + +Note that in this profile the ``aim pose`` is redefined as a pose between thumb +and index finger, oriented so a ray cast can be used to identify a target. + +Grasp support is exposed through the ``squeeze`` input, the value of which +is 0.0 when the hand is open, and 1.0 when a fist is made. + +With this setup the normal ``left_hand`` and ``right_hand`` trackers are used and you can +thus seamlessly switch between controller and hand tracking input. + +HTC hand interaction profile +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `HTC hand interaction profile extension `_ +was introduced by HTC and is defined similarly to the Microsoft extension. +It is only supported by HTC for the Focus 3 and Elite XR headsets. + +.. image:: img/openxr_htc_hand_interaction_profile.webp + +See the Microsoft hand interaction profile for the gesture support. + +The defining difference is that this extension introduces two new trackers, +``/user/hand_htc/left`` and ``/user/hand_htc/right``. +This means that extra logic needs to be implemented to switch between the default trackers +and the HTC specific trackers when the user puts down, or picks up, their controller. + +Simple controller profile +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The simple controller profile is a standard core profile defined as a fallback profile +when a controller is used for which no profile exists. + +There are a number of OpenXR runtimes that will mimic controllers through +the simple controller profile when hand tracking is used. + +Unfortunately there is no sound way to determine whether an unknown controller is used +or whether hand tracking is emulating a controller through this profile. + +.. image:: img/openxr_simple_controller_hand.webp + +XR runtimes are free to define how the simple controller profile operates, +so there is also no certainty to how this profile is mapped to gestures. + +The most common mapping seems to be that ``select click`` is true +when the tip of the thumb and index fingers are touching while the +user's palm is facing away from the user. +``menu click`` will be true when tip of the thumb and index fingers +are touching while the user's palm is facing towards the user. + +With this setup the normal ``left_hand`` and ``right_hand`` trackers are used and you can +thus seamlessly switch between controller and hand tracking input. + +.. note:: -These are exposed through the following trackers: + As some of these interaction profiles have overlap it is important to know + that you can add each profile to your action map and the XR runtime will choose + the best fitting profile. -.. list-table:: HTC trackers - :widths: 100 - :header-rows: 0 + For instance, a Meta Quest supports both the Microsoft hand interaction profile + and simple controller profile. + If both are specified the Microsoft hand interaction profile will take precedence + and will be used. - * - /user/vive_tracker_htcx/role/handheld_object - * - /user/vive_tracker_htcx/role/left_foot - * - /user/vive_tracker_htcx/role/right_foot - * - /user/vive_tracker_htcx/role/left_shoulder - * - /user/vive_tracker_htcx/role/right_shoulder - * - /user/vive_tracker_htcx/role/left_elbow - * - /user/vive_tracker_htcx/role/right_elbow - * - /user/vive_tracker_htcx/role/left_knee - * - /user/vive_tracker_htcx/role/right_knee - * - /user/vive_tracker_htcx/role/waist - * - /user/vive_tracker_htcx/role/chest - * - /user/vive_tracker_htcx/role/camera - * - /user/vive_tracker_htcx/role/keyboard + The expectation is that once Meta supports the core hand interaction profile + extension, that profile will take precedence over both Microsoft + and simple controller profiles. +Gesture based input +^^^^^^^^^^^^^^^^^^^ -Some final words ----------------- +If the platform doesn't support any interaction profiles when hand tracking is used, +or if you're building an application where you need more complicated gesture support +you're going to need to build your own gesture recognition system. -Hand tracking is an area that is still under active development and we are expecting improvements in the near future. +You can obtain the full hand tracking data through the :ref:`XRHandTracker ` +resource for each hand. You can obtain the hand tracker by calling ``XRServer.get_tracker`` +and using either ``/user/hand_tracker/left`` or ``/user/hand_tracker/left`` as the tracker. +This resource provides access to all the joint information for the given hand. -The underlying principle that we're hoping will eventuate is that the action map will be used to handle interactions, -while the hand tracking extension will primarily be a means for visualising the players hand. -The hope here is that improvements to the OpenXR specification will ensure better portability between platforms. +Detailing out a full gesture recognition algorithm goes beyond the scope of this manual +however there are a number of community projects you can look at: + * `Julian Todd's Auto hands library `_ + * `Malcolm Nixons Hand Pose Detector `_