diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index bbb13b75ab9..23d5ce025f2 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -2,7 +2,7 @@ name: Bug report about: Report incorrect or outdated documentation title: '' -labels: bug +labels: '' assignees: '' --- diff --git a/.github/ISSUE_TEMPLATE/enhancement_request.md b/.github/ISSUE_TEMPLATE/enhancement_request.md index d7c3aed25a6..737b48b9c97 100644 --- a/.github/ISSUE_TEMPLATE/enhancement_request.md +++ b/.github/ISSUE_TEMPLATE/enhancement_request.md @@ -2,7 +2,7 @@ name: Enhancement request about: Suggest new documentation or improving existing documentation title: '' -labels: enhancement +labels: '' assignees: '' --- diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 10512df0a3c..178a651f94a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,19 +15,11 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Install dependencies - run: | - # Install tools used by `_tools/format.sh`. - sudo apt-get -qq update - sudo apt-get -qq install dos2unix recode - sudo pip3 install -r requirements.txt - sudo pip3 install codespell + - name: Style checks via pre-commit + uses: pre-commit/action@v3.0.1 - - name: Linter checks - run: | - bash _tools/format.sh - - codespell -D- -D _tools/codespell-dict.txt -I _tools/codespell-ignore.txt -x _tools/codespell-ignore-lines.txt -S tutorials/i18n/locales.rst {about,community,contributing,getting_started,tutorials}/{*.rst,**/*.rst,**/**/*.rst,**/**/**/*.rst} + - name: Install dependencies + run: sudo pip3 install -r requirements.txt - name: Migrate to Redot run: | diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000000..80693445812 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,17 @@ +default_language_version: + python: python3 + +repos: + - repo: https://github.com/codespell-project/codespell + rev: v2.3.0 + hooks: + - id: codespell + files: ^(about|community|contributing|getting_started|tutorials)/.*\.rst$ + additional_dependencies: [tomli] + + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: fix-byte-order-marker + - id: mixed-line-ending + args: ['--fix=lf'] diff --git a/_static/css/custom.css b/_static/css/custom.css index ceab552b0e7..6cb76af1f10 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -398,6 +398,7 @@ a.btn:hover { /* Style self-links to make them appear only on hover. */ .classref-method > a[href*="-method-"].reference, +.classref-method > a[href*="-func-"].reference, .classref-property > a[href*="-property-"].reference, .classref-signal > a[href*="-signal-"].reference, .classref-annotation > a[href*="-annotation-"].reference, @@ -412,6 +413,7 @@ a.btn:hover { padding-right: 20px; } .classref-method:hover > a[href*="-method-"].reference, +.classref-method:hover > a[href*="-func-"].reference, .classref-property:hover > a[href*="-property-"].reference, .classref-signal:hover > a[href*="-signal-"].reference, .classref-annotation:hover > a[href*="-annotation-"].reference, @@ -810,6 +812,31 @@ html.writer-html5 .rst-content table.docutils th { .wy-table-responsive table.wrap-normal th { white-space: normal; } +/* Turn nowrap on per-column */ +.wy-table-responsive table.nowrap-col1 td:nth-child(1), +.wy-table-responsive table.nowrap-col1 th:nth-child(1) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col2 td:nth-child(2), +.wy-table-responsive table.nowrap-col2 th:nth-child(2) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col3 td:nth-child(3), +.wy-table-responsive table.nowrap-col3 th:nth-child(3) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col4 td:nth-child(4), +.wy-table-responsive table.nowrap-col4 th:nth-child(4) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col5 td:nth-child(5), +.wy-table-responsive table.nowrap-col5 th:nth-child(5) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col6 td:nth-child(6), +.wy-table-responsive table.nowrap-col6 th:nth-child(6) { + white-space: nowrap; +} /* Make sure line blocks don't stretch tables */ .wy-table-responsive table .line-block { @@ -1136,6 +1163,7 @@ kbd.compound > .kbd, .classref-descriptions-group > p.classref-annotation, .classref-descriptions-group > p.classref-themeproperty, .classref-descriptions-group > p.classref-method, +.classref-descriptions-group > div.classref-method.line-block, .classref-descriptions-group > p.classref-constructor, .classref-descriptions-group > p.classref-operator, .classref-descriptions-group > p.classref-constant, diff --git a/_templates/layout.html b/_templates/layout.html index 4974857364d..55131ff3f25 100644 --- a/_templates/layout.html +++ b/_templates/layout.html @@ -34,9 +34,8 @@ {% endif %} - {% if godot_show_article_status and not godot_is_latest %} -
- {% if meta and meta.get('article_outdated') == 'True' %} + {% if godot_show_article_status and not godot_is_latest and meta and meta.get('article_outdated') == 'True' %} +

Work in progress

The content of this page was not yet updated for Godot @@ -44,13 +43,6 @@ and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

- {% else %} -

Up to date

-

- This page is up to date for Godot {{ godot_version }}. - If you still find outdated information, please open an issue. -

- {% endif %}
{% endif %}
diff --git a/_tools/format.sh b/_tools/format.sh deleted file mode 100755 index 1b0e22f0be3..00000000000 --- a/_tools/format.sh +++ /dev/null @@ -1,42 +0,0 @@ -#!/usr/bin/env bash - -set -uo pipefail -IFS=$'\n\t' - -# Loops through all text files tracked by Git. -git grep -zIl '' | -while IFS= read -rd '' f; do - # Exclude csproj and hdr files. - if [[ "$f" == *"csproj" ]]; then - continue - elif [[ "$f" == *"hdr" ]]; then - continue - fi - # Ensures that files are UTF-8 formatted. - recode UTF-8 "$f" 2> /dev/null - # Ensures that files have LF line endings. - dos2unix "$f" 2> /dev/null - # Ensures that files do not contain a BOM. - sed -i '1s/^\xEF\xBB\xBF//' "$f" - # Ensures that files end with newline characters. - tail -c1 < "$f" | read -r _ || echo >> "$f"; -done - -git diff > patch.patch -FILESIZE="$(stat -c%s patch.patch)" -MAXSIZE=5 - -# If no patch has been generated all is OK, clean up, and exit. -if (( FILESIZE < MAXSIZE )); then - printf "Files in this commit comply with the formatting rules.\n" - rm -f patch.patch - exit 0 -fi - -# A patch has been created, notify the user, clean up, and exit. -printf "\n*** The following differences were found between the code " -printf "and the formatting rules:\n\n" -cat patch.patch -printf "\n*** Aborting, please fix your commit(s) with 'git commit --amend' or 'git rebase -i '\n" -rm -f patch.patch -exit 1 diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst index dbe254adc11..2534763bbf0 100644 --- a/about/docs_changelog.rst +++ b/about/docs_changelog.rst @@ -16,11 +16,21 @@ added since version 3.0. New pages since version 4.3 --------------------------- +2D +^^ + +- :ref:`doc_introduction_to_2d` + 3D ^^ - :ref:`doc_spring_arm` +Debug +^^^^^ + +- :ref:`doc_output_panel` + Editor ^^^^^^ @@ -31,11 +41,26 @@ Performance - :ref:`doc_pipeline_compilations` +Physics +^^^^^^^ + +- :ref:`doc_physics_interpolation` +- :ref:`doc_physics_interpolation_quick_start_guide` +- :ref:`doc_physics_interpolation_introduction` +- :ref:`doc_using_physics_interpolation` +- :ref:`doc_advanced_physics_interpolation` +- :ref:`doc_2d_and_3d_physics_interpolation` + Rendering ^^^^^^^^^ - :ref:`doc_renderers` +Shaders +^^^^^^^ + +- :ref:`doc_shader_functions` + New pages since version 4.2 --------------------------- diff --git a/about/faq.rst b/about/faq.rst index 3fe32cd979a..d1e630413c4 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -167,6 +167,38 @@ The main reasons for creating a custom scripting language for Godot were: GDScript was designed to curtail the issues above, and more. +.. _doc_faq_which_programming_language_is_fastest: + +Which programming language is fastest? +-------------------------------------- + +In most games, the *scripting language* itself is not the cause of performance +problems. Instead, performance is slowed by inefficient algorithms (which are +slow in all languages), by GPU performance, or by the common C++ engine code +like physics or navigation. All languages supported by Godot are fast enough for +general-purpose scripting. You should choose a language based on other factors, +like ease-of-use, familiarity, platform support, or language features. + +In general, the performance of C# and GDScript is within the same order of +magnitude, and C++ is faster than both. + +Comparing GDScript performance to C# is tricky, since C# can be faster in some +specific cases. The C# *language* itself tends to be faster than GDScript, which +means that C# can be faster in situations with few calls to Godot engine code. +However, C# can be slower than GDScript when making many Godot API calls, due +to the cost of *marshalling*. C#'s performance can also be brought down by garbage +collection which occurs at random and unpredictable moments. This can result in +stuttering issues in complex projects, and is not exclusive to Godot. + +C++, using :ref:`GDExtension `, will almost always be +faster than either C# or GDScript. However, C++ is less easy to use than C# or +GDScript, and is slower to develop with. + +You can also use multiple languages within a single project, with +:ref:`cross-language scripting `, or by using +GDExtension and scripting languages together. Be aware that doing so comes with +its own complications. + What 3D model formats does Godot support? ----------------------------------------- @@ -290,7 +322,7 @@ While Vulkan and OpenGL remain our primary focus for their open standard and cross-platform benefits, Godot 4.3 introduced experimental support for Direct3D 12. This addition aims to enhance performance and compatibility on platforms where Direct3D 12 is prevalent, such as Windows and Xbox. However, Vulkan and OpenGL -will continue as the default rendering backends on all platforms, including Windows. +will continue as the default rendering drivers on all platforms, including Windows. Why does Godot aim to keep its core feature set small? ------------------------------------------------------ diff --git a/about/list_of_features.rst b/about/list_of_features.rst index d1a16fc0989..7a81ee918f8 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -95,17 +95,18 @@ Editor Rendering --------- -3 rendering *methods* (running over 2 rendering *drivers*) are available: - -- **Forward+**, running over Vulkan 1.0 (with optional Vulkan 1.1 and 1.2 - features). The most advanced graphics backend, suited for desktop platforms - only. Used by default on desktop platforms. -- **Forward Mobile**, running over Vulkan 1.0 (with optional Vulkan 1.1 and 1.2 - features). Less features, but renders simple scenes faster. Suited for mobile - and desktop platforms. Used by default on mobile platforms. -- **Compatibility**, running over OpenGL 3.3 / OpenGL ES 3.0 / WebGL 2.0. The least - advanced graphics backend, suited for low-end desktop and mobile platforms. - Used by default on the web platform. +Godot 4 includes three renderers: + +- **Forward+**. The most advanced renderer, suited for desktop platforms only. + Used by default on desktop platforms. This renderer uses **Vulkan**, **Direct3D 12**, + or **Metal** as the rendering driver, and it uses the **RenderingDevice** backend. +- **Mobile**. Fewer features, but renders simple scenes faster. Suited for mobile + and desktop platforms. Used by default on mobile platforms. This renderer uses + **Vulkan**, **Direct3D 12**, or **Metal** as the rendering driver, and it uses + the **RenderingDevice** backend. +- **Compatibility**, sometimes called **GL Compatibility**. The least advanced + renderer, suited for low-end desktop and mobile platforms. Used by default on + the web platform. This renderer uses **OpenGL** as the rendering driver. See :ref:`doc_renderers` for a detailed comparison of the rendering methods. @@ -188,9 +189,9 @@ See :ref:`doc_renderers` for a detailed comparison of the rendering methods. - HDR rendering with sRGB. - Perspective, orthographic and frustum-offset cameras. -- When using the Forward+ backend, a depth prepass is used to improve +- When using the Forward+ renderer, a depth prepass is used to improve performance in complex scenes by reducing the cost of overdraw. -- :ref:`doc_variable_rate_shading` on supported GPUs in Forward+ and Forward Mobile. +- :ref:`doc_variable_rate_shading` on supported GPUs in Forward+ and Mobile. **Physically-based rendering (built-in material features):** @@ -217,10 +218,10 @@ See :ref:`doc_renderers` for a detailed comparison of the rendering methods. - Specular, indirect light, and volumetric fog energy can be adjusted on a per-light basis. - Adjustable light "size" for fake area lights (will also make shadows blurrier). - Optional distance fade system to fade distant lights and their shadows, improving performance. -- When using the Forward+ backend (default on desktop), lights are +- When using the Forward+ renderer (default on desktop), lights are rendered with clustered forward optimizations to decrease their individual cost. Clustered rendering also lifts any limits on the number of lights that can be used on a mesh. -- When using the Forward Mobile backend, up to 8 omni lights and 8 spot lights can +- When using the Mobile renderer, up to 8 omni lights and 8 spot lights can be displayed per mesh resource. Baked lighting can be used to overcome this limit if needed. @@ -276,10 +277,10 @@ See :ref:`doc_renderers` for a detailed comparison of the rendering methods. Parallax box correction can optionally be enabled. - Screen-space reflections with support for material roughness. - Reflection techniques can be mixed together for greater accuracy or scalability. -- When using the Forward+ backend (default on desktop), reflection probes are +- When using the Forward+ renderer (default on desktop), reflection probes are rendered with clustered forward optimizations to decrease their individual cost. Clustered rendering also lifts any limits on the number of reflection probes that can be used on a mesh. -- When using the Forward Mobile backend, up to 8 reflection probes can be displayed per mesh +- When using the Mobile renderer, up to 8 reflection probes can be displayed per mesh resource. When using the Compatibility renderer, up to 2 reflection probes can be displayed per mesh resource. @@ -294,10 +295,10 @@ See :ref:`doc_renderers` for a detailed comparison of the rendering methods. complex skinned meshes with no performance penalty, even if the decal moves every frame. - Support for nearest, bilinear, trilinear or anisotropic texture filtering (configured globally). - Optional distance fade system to fade distant decals, improving performance. -- When using the Forward+ backend (default on desktop), decals are +- When using the Forward+ renderer (default on desktop), decals are rendered with clustered forward optimizations to decrease their individual cost. Clustered rendering also lifts any limits on the number of decals that can be used on a mesh. -- When using the Forward Mobile backend, up to 8 decals can be displayed per mesh +- When using the Mobile renderer, up to 8 decals can be displayed per mesh resource. **Sky:** @@ -462,14 +463,12 @@ Scripting :ref:`C#: ` - Packaged in a separate binary to keep file sizes and dependencies down. -- Supports .NET 6 and higher. +- Supports .NET 8 and higher. - - Full support for the C# 10.0 syntax and features. + - Full support for the C# 12.0 syntax and features. -- Supports Windows, Linux, and macOS. As of 4.2 experimental support for Android - and iOS is also available (requires a .NET 7.0 project for Android and 8.0 for iOS). +- Supports Windows, Linux, and macOS. Since Godot 4.2, experimental support for Android and iOS is also available. - - On the Android platform only some architectures are supported: ``arm64`` and ``x64``. - On the iOS platform only some architectures are supported: ``arm64``. - The web platform is currently unsupported. To use C# on that platform, consider Godot 3 instead. @@ -489,7 +488,7 @@ Scripting - Use any build system and language features you wish. - Actively developed GDExtension bindings for `D `__, - `Haxe `__, `Swift `__, and `Rust `__ + `Swift `__, and `Rust `__ bindings provided by the community. (Some of these bindings may be experimental and not production-ready). Audio @@ -653,7 +652,7 @@ XR support (AR and VR) - Including support for popular desktop headsets like the Valve Index, WMR headsets, and Quest over Link. -- Support for :ref:`Android based headsets ` using OpenXR through a plugin. +- Support for :ref:`Android-based headsets ` using OpenXR through a plugin. - Including support for popular stand alone headsets like the Meta Quest 1/2/3 and Pro, Pico 4, Magic Leap 2, and Lynx R1. diff --git a/about/release_policy.rst b/about/release_policy.rst index f8fe8427271..4d42e61e9d1 100644 --- a/about/release_policy.rst +++ b/about/release_policy.rst @@ -63,6 +63,8 @@ further developed for maintenance releases in a Git branch of the same name Release support timeline ------------------------ +.. UPDATE: Table changes every minor version. Support policy may change. + Stable branches are supported *at least* until the next stable branch is released and has received its first patch update. In practice, we support stable branches on a *best effort* basis for as long as they have active users @@ -159,6 +161,8 @@ you are happy with how your project currently works. When is the next release out? ----------------------------- +.. UPDATE: Refers to specific current minor versions 3.6 and 3.7. + While Godot contributors aren't working under any deadlines, we strive to publish minor releases relatively frequently. diff --git a/about/system_requirements.rst b/about/system_requirements.rst index f5a96f9b0d9..9cb6f993818 100644 --- a/about/system_requirements.rst +++ b/about/system_requirements.rst @@ -35,15 +35,15 @@ Desktop or laptop PC - Minimum | | | | | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Raspberry Pi 4* | +----------------------+-----------------------------------------------------------------------------------------+ -| **GPU** | - **Forward+ rendering method:** Integrated graphics with full Vulkan 1.0 support | +| **GPU** | - **Forward+ renderer:** Integrated graphics with full Vulkan 1.0 support | | | | | | - *Example: Intel HD Graphics 5500 (Broadwell), AMD Radeon R5 Graphics (Kaveri)* | | | | -| | - **Mobile rendering method:** Integrated graphics with full Vulkan 1.0 support | +| | - **Mobile renderer:** Integrated graphics with full Vulkan 1.0 support | | | | | | - *Example: Intel HD Graphics 5500 (Broadwell), AMD Radeon R5 Graphics (Kaveri)* | | | | -| | - **Compatibility rendering method:** Integrated graphics with full OpenGL 3.3 support | +| | - **Compatibility renderer:** Integrated graphics with full OpenGL 3.3 support | | | | | | - *Example: Intel HD Graphics 2500 (Ivy Bridge), AMD Radeon R5 Graphics (Kaveri)* | +----------------------+-----------------------------------------------------------------------------------------+ @@ -69,7 +69,7 @@ Desktop or laptop PC - Minimum Vulkan drivers for these Windows versions are known to have issues with memory leaks. As a result, it's recommended to stick to the Compatibility - rendering method when running Godot on a Windows version older than 10. + renderer when running Godot on a Windows version older than 10. Mobile device (smartphone/tablet) - Minimum ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -77,28 +77,28 @@ Mobile device (smartphone/tablet) - Minimum +----------------------+-----------------------------------------------------------------------------------------+ | **CPU** | - **Android:** SoC with any 32-bit or 64-bit ARM or x86 CPU | | | | -| | - *Example: Qualcomm Snapdragon 430, Samsung Exynos 5 Octa 5430* | +| | - *Example: Qualcomm Snapdragon 430, Samsung Exynos 5 Octa 5430* | | | | | | - **iOS:** *Cannot run the editor* | +----------------------+-----------------------------------------------------------------------------------------+ -| **GPU** | - **Forward+ rendering method:** SoC featuring GPU with full Vulkan 1.0 support | +| **GPU** | - **Forward+ renderer:** SoC featuring GPU with full Vulkan 1.0 support | | | | | | - *Example: Qualcomm Adreno 505, Mali-G71 MP2* | | | | -| | - **Mobile rendering method:** SoC featuring GPU with full Vulkan 1.0 support | +| | - **Mobile renderer:** SoC featuring GPU with full Vulkan 1.0 support | | | | | | - *Example: Qualcomm Adreno 505, Mali-G71 MP2* | | | | -| | - **Compatibility rendering method:** SoC featuring GPU with full OpenGL ES 3.0 support | +| | - **Compatibility renderer:** SoC featuring GPU with full OpenGL ES 3.0 support | | | | | | - *Example: Qualcomm Adreno 306, Mali-T628 MP6* | +----------------------+-----------------------------------------------------------------------------------------+ | **RAM** | - **Native editor:** 3 GB | | | - **Web editor:** 6 GB | +----------------------+-----------------------------------------------------------------------------------------+ -| **Storage** | 200 MB (used for the executable, project files and cache). | +| **Storage** | 200 MB (used for the executable, project files and cache) | | | Exporting projects requires downloading export templates separately | -| | (1.3 GB after installation). | +| | (1.3 GB after installation) | +----------------------+-----------------------------------------------------------------------------------------+ | **Operating system** | - **Native editor:** Android 6.0 (Compatibility) or Android 9.0 (Forward+/Mobile) | | | - **Web editor:** Firefox 79, Chrome 88, Edge 79, Safari 15.2, Opera 64, | @@ -124,15 +124,15 @@ Desktop or laptop PC - Recommended | | | | | - *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 | +| **GPU** | - **Forward+ renderer:** 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 | +| | - **Mobile renderer:** 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 | +| | - **Compatibility renderer:** Dedicated graphics with full OpenGL 4.6 support | | | | | | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* | +----------------------+---------------------------------------------------------------------------------------------+ @@ -156,15 +156,15 @@ Mobile device (smartphone/tablet) - Recommended | | | | | - **iOS:** *Cannot run the editor* | +----------------------+-----------------------------------------------------------------------------------------+ -| **GPU** | - **Forward+ rendering method:** SoC featuring GPU with full Vulkan 1.2 support | +| **GPU** | - **Forward+ renderer:** SoC featuring GPU with full Vulkan 1.2 support | | | | | | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* | | | | -| | - **Mobile rendering method:** SoC featuring GPU with full Vulkan 1.2 support | +| | - **Mobile renderer:** SoC featuring GPU with full Vulkan 1.2 support | | | | | | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* | | | | -| | - **Compatibility rendering method:** SoC featuring GPU with full OpenGL ES 3.2 support | +| | - **Compatibility renderer:** SoC featuring GPU with full OpenGL ES 3.2 support | | | | | | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* | +----------------------+-----------------------------------------------------------------------------------------+ @@ -186,7 +186,7 @@ Exported Godot project The requirements below are a baseline for a **simple** 2D or 3D project, with basic scripting and few visual flourishes. CPU, GPU, RAM and storage requirements will heavily vary depending on your project's scope, - its rendering method, viewport resolution and graphics settings chosen. + its renderer, viewport resolution and graphics settings chosen. Other programs running on the system while the project is running will also compete for resources, including RAM and video RAM. @@ -209,25 +209,28 @@ Desktop or laptop PC - Minimum +----------------------+-----------------------------------------------------------------------------------------+ | **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, Snapdragon X Elite* | +| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Snapdragon X Elite* | | | | | | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | | | | -| | - *Example: Intel Core 2 Duo SU9400, Apple M1* | +| | - *Example: Intel Core 2 Duo SU9400, Apple M1* | | | | | | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU | | | | -| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Raspberry Pi 4* | +| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Raspberry Pi 4* | +----------------------+-----------------------------------------------------------------------------------------+ -| **GPU** | - **Forward+ rendering method:** Integrated graphics with full Vulkan 1.0 support | +| **GPU** | - **Forward+ renderer:** Integrated graphics with full Vulkan 1.0 support, | +| | Metal 3 support (macOS) or Direct3D 12 (12_0 feature level) support (Windows) | | | | | | - *Example: Intel HD Graphics 5500 (Broadwell), AMD Radeon R5 Graphics (Kaveri)* | | | | -| | - **Mobile rendering method:** Integrated graphics with full Vulkan 1.0 support | +| | - **Mobile renderer:** Integrated graphics with full Vulkan 1.0 support, | +| | Metal 3 support (macOS) or Direct3D 12 (12_0 feature level) support (Windows) | | | | | | - *Example: Intel HD Graphics 5500 (Broadwell), AMD Radeon R5 Graphics (Kaveri)* | | | | -| | - **Compatibility rendering method:** Integrated graphics with full OpenGL 3.3 support | +| | - **Compatibility renderer:** Integrated graphics with full OpenGL 3.3 support | +| | or Direct3D 11 support (Windows). | | | | | | - *Example: Intel HD Graphics 2500 (Ivy Bridge), AMD Radeon R5 Graphics (Kaveri)* | +----------------------+-----------------------------------------------------------------------------------------+ @@ -236,8 +239,10 @@ Desktop or laptop PC - Minimum +----------------------+-----------------------------------------------------------------------------------------+ | **Storage** | 150 MB (used for the executable, project files and cache) | +----------------------+-----------------------------------------------------------------------------------------+ -| **Operating system** | - **For native exports:** Windows 7, macOS 10.13 (Compatibility) or | -| | macOS 10.15 (Forward+/Mobile), Linux distribution released after 2016 | +| **Operating system** | - **For native exports:** Windows 7 (Compatibility and Forward+/Mobile, Vulkan), | +| | Windows 10 (Forward+/Mobile, Direct3D 12), macOS 10.13 (Compatibility), macOS 10.15 | +| | (Forward+/Mobile, Vulkan), macOS 13.0 (Forward+/Mobile, Metal), Linux distribution | +| | released after 2016 | | | - **For web exports:** Firefox 79, Chrome 68, Edge 79, Safari 15.2, Opera 64 | +----------------------+-----------------------------------------------------------------------------------------+ @@ -251,7 +256,7 @@ Desktop or laptop PC - Minimum Vulkan drivers for these Windows versions are known to have issues with memory leaks. As a result, it's recommended to stick to the Compatibility - rendering method when running Godot on a Windows version older than 10. + renderer when running Godot on a Windows version older than 10. Mobile device (smartphone/tablet) - Minimum ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -265,15 +270,19 @@ Mobile device (smartphone/tablet) - Minimum | | | | | - *Example: Apple A7 (iPhone 5S)* | +----------------------+-----------------------------------------------------------------------------------------+ -| **GPU** | - **Forward+ rendering method:** SoC featuring GPU with full Vulkan 1.0 support | +| **GPU** | - **Forward+ renderer:** SoC featuring GPU with full Vulkan 1.0 support, or | +| | Metal 3 support (iOS/iPadOS) | | | | -| | - *Example: Qualcomm Adreno 505, Mali-G71 MP2, Apple A12 (iPhone XR/XS)* | +| | - *Example (Vulkan): Qualcomm Adreno 505, Mali-G71 MP2, Apple A12 (iPhone XR/XS)* | +| | - *Example (Metal): Apple A11 (iPhone 8/X)* | | | | -| | - **Mobile rendering method:** SoC featuring GPU with full Vulkan 1.0 support | +| | - **Mobile renderer:** SoC featuring GPU with full Vulkan 1.0 support, or | +| | Metal 3 support (iOS/iPadOS) | | | | -| | - *Example: Qualcomm Adreno 505, Mali-G71 MP2, Apple A12 (iPhone XR/XS)* | +| | - *Example (Vulkan): Qualcomm Adreno 505, Mali-G71 MP2, Apple A12 (iPhone XR/XS)* | +| | - *Example (Metal): Apple A11 (iPhone 8/X)* | | | | -| | - **Compatibility rendering method:** SoC featuring GPU with full OpenGL ES 3.0 support | +| | - **Compatibility renderer:** SoC featuring GPU with full OpenGL ES 3.0 support | | | | | | - *Example: Qualcomm Adreno 306, Mali-T628 MP6, Apple A7 (iPhone 5S)* | +----------------------+-----------------------------------------------------------------------------------------+ @@ -282,8 +291,8 @@ Mobile device (smartphone/tablet) - Minimum +----------------------+-----------------------------------------------------------------------------------------+ | **Storage** | 150 MB (used for the executable, project files and cache) | +----------------------+-----------------------------------------------------------------------------------------+ -| **Operating system** | - **For native exports:** Android 6.0 (Compatibility) or Android 9.0 (Forward+/Mobile), | -| | iOS 12.0 | +| **Operating system** | - **For native exports:** Android 6.0 (Compatibility), Android 9.0 (Forward+/Mobile), | +| | iOS 12.0 (Forward+/Mobile, Vulkan), iOS 16.0 (Forward+/Mobile, Metal) | | | - **For web exports:** Firefox 79, Chrome 88, Edge 79, Safari 15.2, Opera 64, | | | Samsung Internet 15 | +----------------------+-----------------------------------------------------------------------------------------+ @@ -294,40 +303,42 @@ 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, 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 | -+----------------------+---------------------------------------------------------------------------------------------+ ++----------------------+----------------------------------------------------------------------------------------------+ +| **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+ renderer:** Dedicated graphics with full Vulkan 1.2 support, | +| | Metal 3 support (macOS), or Direct3D 12 (12_0 feature level) support (Windows) | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Mobile renderer:** Dedicated graphics with full Vulkan 1.2 support, | +| | Metal 3 support (macOS), or Direct3D 12 (12_0 feature level) support (Windows) | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Compatibility renderer:** 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 (Forward+/Mobile, Vulkan), macOS 13.0 | +| | (Forward+/Mobile, Metal), Linux distribution released after 2020 | +| | - **For web exports:** Latest version of Firefox, Chrome, Edge, Safari, Opera | ++----------------------+----------------------------------------------------------------------------------------------+ Mobile device (smartphone/tablet) - Recommended ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -341,15 +352,17 @@ Mobile device (smartphone/tablet) - Recommended | | | | | - *Example: Apple A14 (iPhone 12)* | +----------------------+-----------------------------------------------------------------------------------------+ -| **GPU** | - **Forward+ rendering method:** SoC featuring GPU with full Vulkan 1.2 support | +| **GPU** | - **Forward+ renderer:** SoC featuring GPU with full Vulkan 1.2 support, or | +| | Metal 3 support (iOS/iPadOS) | | | | | | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple A14 (iPhone 12)* | | | | -| | - **Mobile rendering method:** SoC featuring GPU with full Vulkan 1.2 support | +| | - **Mobile renderer:** SoC featuring GPU with full Vulkan 1.2 support, or | +| | Metal 3 support (iOS/iPadOS) | | | | | | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple A14 (iPhone 12)* | | | | -| | - **Compatibility rendering method:** SoC featuring GPU with full OpenGL ES 3.2 support | +| | - **Compatibility renderer:** SoC featuring GPU with full OpenGL ES 3.2 support | | | | | | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple A14 (iPhone 12)* | +----------------------+-----------------------------------------------------------------------------------------+ @@ -358,7 +371,8 @@ Mobile device (smartphone/tablet) - Recommended +----------------------+-----------------------------------------------------------------------------------------+ | **Storage** | 150 MB (used for the executable, project files and cache) | +----------------------+-----------------------------------------------------------------------------------------+ -| **Operating system** | - **For native exports:** Android 9.0 or iOS 14.1 | +| **Operating system** | - **For native exports:** Android 9.0, iOS 14.1 (Forward+/Mobile, Vulkan), iOS 16.0 | +| | (Forward+/Mobile, Metal) | | | - **For web exports:** Latest version of Firefox, Chrome, Edge, Safari, Opera, | | | Samsung Internet | +----------------------+-----------------------------------------------------------------------------------------+ diff --git a/community/tutorials.rst b/community/tutorials.rst index 8a8467a43b6..18d61d28899 100644 --- a/community/tutorials.rst +++ b/community/tutorials.rst @@ -3,7 +3,10 @@ Tutorials and resources ======================= -This is a list of third-party tutorials and resources created by the Godot community. For resources, remember that there is the official `Godot Asset Library `_ full of official and community resources too! Also, have a look at this `huge list over at Reddit `_. +This is a list of third-party tutorials and resources created by the Godot +community. For resources, remember that there is the official +`Godot Asset Library `_ full of +official and community resources too! Think there is something missing here? Feel free to submit a `Pull Request `_ as always. diff --git a/conf.py b/conf.py index a37de5554e6..6419c27592c 100644 --- a/conf.py +++ b/conf.py @@ -179,7 +179,7 @@ html_title = supported_languages[language] % ( "(" + version + ")" ) -# VCS options: https://docs.readthedocs.io/en/latest/vcs.html#github +# Edit on GitHub options: https://docs.readthedocs.io/en/latest/guides/edit-source-links-sphinx.html html_context = { "display_github": not is_i18n, # Integrate GitHub "github_user": "godotengine", # Username diff --git a/contributing/development/best_practices_for_engine_contributors.rst b/contributing/development/best_practices_for_engine_contributors.rst index b0dd1de5608..66206b3a7aa 100644 --- a/contributing/development/best_practices_for_engine_contributors.rst +++ b/contributing/development/best_practices_for_engine_contributors.rst @@ -179,7 +179,7 @@ they'll need to do* in the future? .. image:: img/best_practices6.png The answer to this question is that, to ensure users still can do what they want -to do, we need to give them access to a *low level API* that they can use to +to do, we need to give them access to a *low-level API* that they can use to achieve what they want, even if it's more work for them because it means reimplementing some logic that already exists. @@ -219,7 +219,7 @@ is always the advised one. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Not every problem has a simple solution and, many times, the right choice is to -use a third party library to solve the problem. +use a third-party library to solve the problem. As Godot requires to be shipped in a large amount of platforms, we can't link libraries dynamically. Instead, we bundle them in our source tree. diff --git a/contributing/development/compiling/compiling_for_linuxbsd.rst b/contributing/development/compiling/compiling_for_linuxbsd.rst index 425702fa04a..0cadc515541 100644 --- a/contributing/development/compiling/compiling_for_linuxbsd.rst +++ b/contributing/development/compiling/compiling_for_linuxbsd.rst @@ -196,6 +196,28 @@ Distro-specific one-liners scons \ llvm + .. tab:: openKylin + + :: + + sudo apt update + sudo apt install -y \ + python3-pip \ + build-essential \ + pkg-config \ + libx11-dev \ + libxcursor-dev \ + libxinerama-dev \ + libgl1-mesa-dev \ + libglu1-mesa-dev \ + libasound2-dev \ + libpulse-dev \ + libudev-dev \ + libxi-dev \ + libxrandr-dev \ + libwayland-dev + sudo pip install scons + .. tab:: openSUSE :: @@ -248,6 +270,12 @@ Start a terminal, go to the root dir of the engine source code and type: ``linuxbsd``. If you are looking to compile Godot 3.x, make sure to use the `3.x branch of this documentation `__. +.. tip:: + If you are compiling Godot to make changes or contribute to the engine, + you may want to use the SCons options ``dev_build=yes`` or ``dev_mode=yes``. + See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases` + for more info. + If all goes well, the resulting binary executable will be placed in the "bin" subdirectory. This executable file contains the whole engine and runs without any dependencies. Executing it will bring up the Project @@ -573,34 +601,3 @@ running ``scons -h``, then looking for options starting with ``builtin_``. across Linux distributions anymore. Do not use this approach for creating binaries you intend to distribute to others, unless you're creating a package for a Linux distribution. - -Using Pyston for faster development ------------------------------------ - -You can use `Pyston `__ to run SCons. Pyston is a JIT-enabled -implementation of the Python language (which SCons is written in). It is currently -only compatible with Linux. Pyston can speed up incremental builds significantly, -often by a factor between 1.5× and 2×. Pyston can be combined with Clang and LLD -to get even faster builds. - -- Download the `latest portable Pyston release `__. -- Extract the portable ``.tar.gz`` to a set location, such as ``$HOME/.local/opt/pyston/`` (create folders as needed). -- Use ``cd`` to reach the extracted Pyston folder from a terminal, - then run ``./pyston -m pip install scons`` to install SCons within Pyston. -- To make SCons via Pyston easier to run, create a symbolic link of its wrapper - script to a location in your ``PATH`` environment variable:: - - ln -s ~/.local/opt/pyston/bin/scons ~/.local/bin/pyston-scons - -- Instead of running ``scons ``, run ``pyston-scons `` - to compile Godot. - -If you can't run ``pyston-scons`` after creating the symbolic link, -make sure ``$HOME/.local/bin/`` is part of your user's ``PATH`` environment variable. - -.. note:: - - Alternatively, you can run ``python -m pip install pyston_lite_autoload`` - then run SCons as usual. This will automatically load a subset of Pyston's - optimizations in any Python program you run. However, this won't bring as - much of a performance improvement compared to installing "full" Pyston. diff --git a/contributing/development/compiling/compiling_for_macos.rst b/contributing/development/compiling/compiling_for_macos.rst index b8cf889e3fc..5d02b0f10ef 100644 --- a/contributing/development/compiling/compiling_for_macos.rst +++ b/contributing/development/compiling/compiling_for_macos.rst @@ -59,6 +59,12 @@ To support both architectures in a single "Universal 2" binary, run the above tw lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal +.. tip:: + If you are compiling Godot to make changes or contribute to the engine, + you may want to use the SCons options ``dev_build=yes`` or ``dev_mode=yes``. + See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases` + for more info. + If all goes well, the resulting binary executable will be placed in the ``bin/`` subdirectory. This executable file contains the whole engine and runs without any dependencies. Executing it will bring up the Project @@ -160,22 +166,6 @@ template from the official Godot distribution:: zip -r9 macos.zip macos_template.app -Using Pyston for faster development ------------------------------------ - -You can use `Pyston `__ to run SCons. Pyston is a -JIT-enabled implementation of the Python language (which SCons is written in). -Its "full" version is currently only compatible with Linux, but Pyston-lite is -also compatible with macOS (both x86 and ARM). Pyston can speed up incremental -builds significantly, often by a factor between 1.5× and 2×. Pyston can be -combined with alternative linkers such as LLD or Mold to get even faster builds. - -To install Pyston-lite, run ``python -m pip install pyston_lite_autoload`` then -run SCons as usual. This will automatically load a subset of Pyston's -optimizations in any Python program you run. However, this won't bring as much -of a performance improvement compared to installing "full" Pyston (which -currently can't be done on macOS). - Cross-compiling for macOS from Linux ------------------------------------ diff --git a/contributing/development/compiling/compiling_for_web.rst b/contributing/development/compiling/compiling_for_web.rst index 2db64081bbd..099248dbb30 100644 --- a/contributing/development/compiling/compiling_for_web.rst +++ b/contributing/development/compiling/compiling_for_web.rst @@ -121,7 +121,7 @@ server requirements. python platform/web/serve.py This will serve the contents of the ``bin/`` folder and open the default web - browser automatically. In the page that opens, access ``godot.tools.html`` + browser automatically. In the page that opens, access ``godot.editor.html`` and you should be able to test the web editor this way. Note that for production use cases, this Python-based web server should not diff --git a/contributing/development/compiling/compiling_for_windows.rst b/contributing/development/compiling/compiling_for_windows.rst index 93f355fa5d6..982d300cccc 100644 --- a/contributing/development/compiling/compiling_for_windows.rst +++ b/contributing/development/compiling/compiling_for_windows.rst @@ -146,6 +146,12 @@ the engine source code (using ``cd``) and type: .. note:: When compiling with multiple CPU threads, SCons may warn about pywin32 being missing. You can safely ignore this warning. +.. tip:: + If you are compiling Godot to make changes or contribute to the engine, + you may want to use the SCons options ``dev_build=yes`` or ``dev_mode=yes``. + See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases` + for more info. + 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 diff --git a/contributing/development/compiling/introduction_to_the_buildsystem.rst b/contributing/development/compiling/introduction_to_the_buildsystem.rst index fe229fbd960..df09ed4553f 100644 --- a/contributing/development/compiling/introduction_to_the_buildsystem.rst +++ b/contributing/development/compiling/introduction_to_the_buildsystem.rst @@ -139,6 +139,8 @@ run projects but does not include the editor or the Project Manager. scons platform= target=editor/template_debug/template_release +.. _doc_introduction_to_the_buildsystem_development_and_production_aliases: + Development and production aliases ---------------------------------- diff --git a/contributing/development/configuring_an_ide/code_blocks.rst b/contributing/development/configuring_an_ide/code_blocks.rst index 1689d342266..6d0fe1997d6 100644 --- a/contributing/development/configuring_an_ide/code_blocks.rst +++ b/contributing/development/configuring_an_ide/code_blocks.rst @@ -3,7 +3,7 @@ Code::Blocks ============ -`Code::Blocks `_ is a free, open source, cross platform IDE. +`Code::Blocks `_ is a free, open-source, cross-platform IDE. Creating a new project ---------------------- diff --git a/contributing/development/configuring_an_ide/visual_studio_code.rst b/contributing/development/configuring_an_ide/visual_studio_code.rst index 5141e4b1036..7874cdc2641 100644 --- a/contributing/development/configuring_an_ide/visual_studio_code.rst +++ b/contributing/development/configuring_an_ide/visual_studio_code.rst @@ -70,7 +70,7 @@ To run and debug the project you need to create a new configuration in the ``lau .. figure:: img/vscode_1_create_launch.json.png :align: center -- Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected, +- Select **C++ (GDB/LLDB)**. There may be another platform-specific option here. If selected, adjust the configuration example provided accordingly. - Within the ``launch.json`` file find the ``"configurations"`` array and add a new section to it: diff --git a/contributing/development/core_and_modules/2d_coordinate_systems.rst b/contributing/development/core_and_modules/2d_coordinate_systems.rst index d9d4b044b13..0f0f1459f3a 100644 --- a/contributing/development/core_and_modules/2d_coordinate_systems.rst +++ b/contributing/development/core_and_modules/2d_coordinate_systems.rst @@ -104,7 +104,7 @@ effects of each of them. *Viewport's* :ref:`canvas transform ` and the *CanvasLayer's* :ref:`follow viewport scale ` and can be used, if :ref:`enabled `, to - achieve a pseudo 3D effect. It affects the same child nodes as the *CanvasLayer transform*. + achieve a pseudo-3D effect. It affects the same child nodes as the *CanvasLayer transform*. - **Viewport canvas transform** The :ref:`canvas transform ` affects all diff --git a/contributing/development/core_and_modules/core_types.rst b/contributing/development/core_and_modules/core_types.rst index 59d9bf14115..4d5d1554435 100644 --- a/contributing/development/core_and_modules/core_types.rst +++ b/contributing/development/core_and_modules/core_types.rst @@ -103,36 +103,12 @@ which are equivalent to new, delete, new[] and delete[]. memnew/memdelete also use a little C++ magic and notify Objects right after they are created, and right before they are deleted. -For dynamic memory, the PoolVector<> template is provided. PoolVector is a -standard vector class, and is very similar to vector in the C++ standard library. -To create a PoolVector buffer, use this: - -.. code-block:: cpp - - PoolVector data; - -PoolVector can be accessed using the [] operator and a few helpers exist for this: - -.. code-block:: cpp - - PoolVector::Read r = data.read() - int someint = r[4] - -.. code-block:: cpp - - PoolVector::Write w = data.write() - w[4] = 22; - -These operations allow fast read/write from PoolVectors and keep it -locked until they go out of scope. However, PoolVectors should be used -for small, dynamic memory operations, as read() and write() are too slow for a -large amount of accesses. +For dynamic memory, use Vector<>. References: ~~~~~~~~~~~ - `core/os/memory.h `__ -- `core/pool_vector.h `__ Containers ---------- diff --git a/contributing/development/core_and_modules/custom_platform_ports.rst b/contributing/development/core_and_modules/custom_platform_ports.rst index aa917051306..fd5ece4a7ff 100644 --- a/contributing/development/core_and_modules/custom_platform_ports.rst +++ b/contributing/development/core_and_modules/custom_platform_ports.rst @@ -51,7 +51,7 @@ The official platform ports can be used as a reference when creating a custom pl While platform code is usually self-contained, there are exceptions to this rule. For instance, audio drivers that are shared across several platforms and -rendering backends are located in the +rendering drivers are located in the `drivers/ folder `__ of the Godot source code. @@ -184,7 +184,7 @@ clone's ``platform/`` folder, then run ``scons platform=``. No other steps necessary for building, unless third-party platform-specific dependencies need to be installed first. -However, when a custom rendering backend is needed, another folder must be added +However, when a custom rendering driver is needed, another folder must be added in ``drivers/``. In this case, the platform port can be distributed as a fork of the Godot repository, or as a collection of several folders that can be added over a Godot Git repository clone. diff --git a/contributing/development/core_and_modules/custom_resource_format_loaders.rst b/contributing/development/core_and_modules/custom_resource_format_loaders.rst index add1a045ad7..4a40cf05688 100644 --- a/contributing/development/core_and_modules/custom_resource_format_loaders.rst +++ b/contributing/development/core_and_modules/custom_resource_format_loaders.rst @@ -263,7 +263,7 @@ calls into ``std::istream``. .. code-block:: cpp - #include "core/os/file_access.h" + #include "core/io/file_access.h" #include #include @@ -298,7 +298,7 @@ References - `istream `_ - `streambuf `_ -- `core/io/file_access.h `_ +- `core/io/file_access.h `_ Registering the new file format ------------------------------- diff --git a/contributing/development/core_and_modules/internal_rendering_architecture.rst b/contributing/development/core_and_modules/internal_rendering_architecture.rst index 8cd9905335a..6d12b5e5d42 100644 --- a/contributing/development/core_and_modules/internal_rendering_architecture.rst +++ b/contributing/development/core_and_modules/internal_rendering_architecture.rst @@ -44,10 +44,11 @@ affect that pixel. This approach can greatly speed up rendering performance on desktop hardware, but is substantially less efficient on mobile. -Forward Mobile -^^^^^^^^^^^^^^ +Mobile +^^^^^^ This is a forward renderer that uses a traditional single-pass approach to lighting. +Internally, it is called **Forward Mobile**. Intended for mobile platforms, but can also run on desktop platforms. This rendering method is optimized to perform well on mobile GPUs. Mobile GPUs have a @@ -92,7 +93,7 @@ features result in a notable performance penalty. On desktop platforms, the use of sub-passes won't have any impact on performance. However, this rendering method can still perform better than -Clustered Forward in simple scenes thanks to its lower complexity and lower +Forward+ in simple scenes thanks to its lower complexity and lower bandwidth usage. This is especially noticeable on low-end GPUs, integrated graphics or in VR applications. @@ -110,11 +111,11 @@ Compatibility This is the only rendering method available when using the OpenGL driver. This rendering method is not available when using Vulkan or Direct3D 12. -This is a traditional (non-clustered) forward renderer. It's intended for old -GPUs that don't have Vulkan support, but still works very efficiently on newer -hardware. Specifically, it is optimized for older and lower-end mobile devices -However, many optimizations carry over making it a good choice for older and -lower-end desktop as well. +This is a traditional (non-clustered) forward renderer. Internally, it is called +**GL Compatibility**. It's intended for old GPUs that don't have Vulkan support, +but still works very efficiently on newer hardware. Specifically, it is optimized +for older and lower-end mobile devices. However, many optimizations carry over +making it a good choice for older and lower-end desktop as well. Like the Mobile renderer, the Compatibility renderer uses an R10G10B10A2 UNORM texture for 3D rendering. Unlike the mobile renderer, colors are tonemapped and @@ -134,7 +135,7 @@ looks and needs to be kept in mind when designing scenes for the Compatibility renderer. Given its low-end focus, this rendering method does not provide high-end -rendering features (even less so compared to Forward Mobile). Most +rendering features (even less so compared to Mobile). Most post-processing effects are not available. Why not deferred rendering? @@ -217,6 +218,8 @@ wouldn't have. Both the clustered and mobile :ref:`doc_internal_rendering_architecture_methods` can be used with a Metal backend via MoltenVK. +.. UPDATE: Planned feature. When the native Metal driver is implemented, update this. + A native Metal driver is planned in the future for better performance and compatibility. @@ -228,8 +231,8 @@ support Vulkan. OpenGL 3.3 Core Profile is used on desktop platforms to run this driver, as most graphics drivers on desktop don't support OpenGL ES. WebGL 2.0 is used for web exports. -It is possible to use the use of OpenGL ES 3.0 directly on desktop platforms -using the ``--rendering-driver opengl3_es`` command line argument, although this +It is possible to use OpenGL ES 3.0 directly on desktop platforms +by passing the ``--rendering-driver opengl3_es`` command line argument, although this will only work on graphics drivers that feature native OpenGL ES support (such as Mesa). @@ -248,11 +251,11 @@ Summary of rendering drivers/methods The following rendering API + rendering method combinations are currently possible: - Vulkan + Forward+ -- Vulkan + Forward Mobile +- Vulkan + Mobile - Direct3D 12 + Forward+ -- Direct3D 12 + Forward Mobile +- Direct3D 12 + Mobile - Metal + Forward+ (via MoltenVK) -- Metal + Forward Mobile (via MoltenVK) +- Metal + Mobile (via MoltenVK) - OpenGL + Compatibility Each combination has its own limitations and performance characteristics. Make @@ -350,14 +353,14 @@ this. **Core GLSL material shaders:** - Forward+: `servers/rendering/renderer_rd/shaders/forward_clustered/scene_forward_clustered.glsl `__ -- Forward Mobile: `servers/rendering/renderer_rd/shaders/forward_mobile/scene_forward_mobile.glsl `__ +- Mobile: `servers/rendering/renderer_rd/shaders/forward_mobile/scene_forward_mobile.glsl `__ - Compatibility: `drivers/gles3/shaders/scene.glsl `__ **Material shader generation:** - `scene/resources/material.cpp `__ -**Other GLSL shaders for Forward+ and Forward Mobile rendering methods:** +**Other GLSL shaders for Forward+ and Mobile rendering methods:** - `servers/rendering/renderer_rd/shaders/ `__ - `modules/lightmapper_rd/ `__ @@ -371,9 +374,9 @@ this. .. note:: - The following is only applicable in the Forward+ and Forward Mobile + The following is only applicable in the Forward+ and Mobile rendering methods, not in Compatibility. Multiple Viewports can be used to - emulate this when using the Compatibility backend, or to perform 2D + emulate this when using the Compatibility renderer, or to perform 2D resolution scaling. 2D and 3D are rendered to separate buffers, as 2D rendering in Godot is performed @@ -395,6 +398,9 @@ allows maximizing the performance of bilinear 3D scaling. The ``configure()`` function in RenderSceneBuffersRD reallocates the 2D/3D buffers when the resolution or scaling changes. +.. UPDATE: Planned feature. When dynamic resolution scaling is supported, +.. update this paragraph. + Dynamic resolution scaling isn't supported yet, but is planned in a future Godot release. @@ -413,10 +419,13 @@ release. 2D light rendering is performed in a single pass to allow for better performance with large amounts of lights. +.. UPDATE: Planned feature. When Forward+ and Mobile feature 2D batching, +.. update this. + The Forward+ and Mobile rendering methods don't feature 2D batching yet, but it's planned for a future release. -The Compatibility backend features 2D batching to improve performance, which is +The Compatibility renderer features 2D batching to improve performance, which is especially noticeable with lots of text on screen. MSAA can be enabled in 2D to provide "automatic" line and polygon antialiasing, @@ -440,7 +449,7 @@ used to calculate particle collisions in 2D. Batching and instancing ^^^^^^^^^^^^^^^^^^^^^^^ -In the Forward+ backend, Vulkan instancing is used to group rendering +In the Forward+ renderer, Vulkan instancing is used to group rendering of identical objects for performance. This is not as fast as static mesh merging, but it still allows instances to be culled individually. @@ -449,10 +458,9 @@ Light, decal and reflection probe rendering .. note:: - Reflection probe and decal rendering are currently not available in the - Compatibility backend. + Decal rendering is currently not available in the Compatibility renderer. -As its name implies, the Forward+ backend uses clustered lighting. This +The Forward+ renderer uses clustered lighting. This allows using as many lights as you want; performance largely depends on screen coverage. Shadow-less lights can be almost free if they don't occupy much space on screen. @@ -461,12 +469,12 @@ All rendering methods also support rendering up to 8 directional lights at the same time (albeit with lower shadow quality when more than one light has shadows enabled). -The Forward Mobile backend uses a single-pass lighting approach, with a +The Mobile renderer uses a single-pass lighting approach, with a limitation of 8 OmniLights + 8 SpotLights affecting each Mesh *resource* (plus a limitation of 256 OmniLights + 256 SpotLights in the camera view). These limits are hardcoded and can't be adjusted in the project settings. -The Compatibility backend uses a hybrid single-pass + multi-pass lighting +The Compatibility renderer uses a hybrid single-pass + multi-pass lighting approach. Lights without shadows are rendered in a single pass. Lights with shadows are rendered in multiple passes. This is required for performance reasons on mobile devices. As a result, performance does not scale well with @@ -476,6 +484,9 @@ apart so that each object is only touched by 1 or 2 shadowed lights at a time. The maximum number of lights visible at once can be adjusted in the project settings. +.. UPDATE: Planned feature. When static and dynamic shadow rendering are +.. separated, update this paragraph. + In all 3 methods, lights without shadows are much cheaper than lights with shadows. To improve performance, lights are only updated when the light is modified or when objects in its radius are modified. Godot currently doesn't @@ -483,34 +494,34 @@ separate static shadow rendering from dynamic shadow rendering, but this is planned in a future release. Clustering is also used for reflection probes and decal rendering in the -Forward+ backend. +Forward+ renderer. Shadow mapping ^^^^^^^^^^^^^^ -Both Forward+ and Forward Mobile methods use +Both Forward+ and Mobile methods use :abbr:`PCF (Percentage Closer Filtering)` to filter shadow maps and create a soft penumbra. Instead of using a fixed PCF pattern, these methods use a vogel disk pattern which allows for changing the number of samples and smoothly changing the quality. Godot also supports percentage-closer soft shadows (PCSS) for more realistic -shadow penumbra rendering. PCSS shadows are limited to the Forward+ -backend as they're too demanding to be usable in the Forward Mobile backend. +shadow penumbra rendering. PCSS shadows are limited to the Forward+ renderer +as they're too demanding to be usable in the Mobile renderer. PCSS also uses a vogel-disk shaped kernel. Additionally, both shadow-mapping techniques rotate the kernel on a per-pixel basis to help soften under-sampling artifacts. -The Compatibility backend doesn't support shadow mapping for any light types yet. +The Compatibility renderer supports shadow mapping for DirectionalLight3D, +OmniLight3D, and SpotLight3D lights. Temporal antialiasing ^^^^^^^^^^^^^^^^^^^^^ .. note:: - Only available in the Forward+ backend, not the Forward Mobile or - Compatibility methods. + Only available in the Forward+ renderer, not the Mobile or Compatibility renderers. Godot uses a custom TAA implementation based on the old TAA implementation from `Spartan Engine `__. @@ -542,13 +553,12 @@ Global illumination .. note:: - VoxelGI and SDFGI are only available in the Forward+ backend, not the - Forward Mobile or Compatibility methods. + VoxelGI and SDFGI are only available in the Forward+ renderer, not the + Mobile or Compatibility renderers. - LightmapGI *baking* is only available in the Forward+ and Forward Mobile - methods, and can only be performed within the editor (not in an exported - project). LightmapGI *rendering* will eventually be supported by the - Compatibility backend. + LightmapGI *baking* is only available in the Forward+ and Mobile renderers, + and can only be performed within the editor (not in an exported + project). LightmapGI *rendering* is supported by the Compatibility renderer. Godot supports voxel-based GI (VoxelGI), signed distance field GI (SDFGI) and lightmap baking and rendering (LightmapGI). These techniques can be used @@ -558,7 +568,7 @@ Lightmap baking happens on the GPU using Vulkan compute shaders. The GPU-based lightmapper is implemented in the LightmapperRD class, which inherits from the Lightmapper class. This allows for implementing additional lightmappers, paving the way for a future port of the CPU-based lightmapper present in Godot 3.x. -This would allow baking lightmaps while using the Compatibility backend. +This would allow baking lightmaps while using the Compatibility renderer. **Core GI C++ code:** @@ -594,14 +604,13 @@ Depth of field .. note:: - Only available in the Forward+ and Forward Mobile methods, not the - Compatibility backend. + Only available in the Forward+ and Mobile renderers, not the + Compatibility renderer. -The Forward+ and Forward Mobile methods use different approaches to -DOF rendering, with different visual results. This is done to best -match the performance characteristics of the target hardware. In Clustered -Forward, DOF is performed using a compute shader. In Forward Mobile, DOF is -performed using a fragment shader (raster). +The Forward+ and Mobile renderers use different approaches to DOF rendering, with +different visual results. This is done to best match the performance characteristics +of the target hardware. In Forward+, DOF is performed using a compute shader. In +Mobile, DOF is performed using a fragment shader (raster). Box, hexagon and circle bokeh shapes are available (from fastest to slowest). Depth of field can optionally be jittered every frame to improve its appearance @@ -615,7 +624,7 @@ when temporal antialiasing is enabled. - `servers/rendering/renderer_rd/shaders/effects/bokeh_dof.glsl `__ -**Depth of field GLSL shader (raster - used for Forward Mobile):** +**Depth of field GLSL shader (raster - used for Mobile):** - `servers/rendering/renderer_rd/shaders/effects/bokeh_dof_raster.glsl `__ @@ -624,10 +633,9 @@ Screen-space effects (SSAO, SSIL, SSR, SSS) .. note:: - Only available in the Forward+ backend, not the Forward Mobile or - Compatibility methods. + Only available in the Forward+ renderer, not the Mobile or Compatibility renderers. -The Forward+ backend supports screen-space ambient occlusion, +The Forward+ renderer supports screen-space ambient occlusion, screen-space indirect lighting, screen-space reflections and subsurface scattering. SSAO uses an implementation derived from Intel's @@ -701,8 +709,7 @@ Volumetric fog .. note:: - Only available in the Forward+ backend, not the Forward Mobile or - Compatibility methods. + Only available in the Forward+ renderer, not the Mobile or Compatibility renderers. .. seealso:: diff --git a/contributing/development/core_and_modules/object_class.rst b/contributing/development/core_and_modules/object_class.rst index e2afbdad761..ffa69908cbf 100644 --- a/contributing/development/core_and_modules/object_class.rst +++ b/contributing/development/core_and_modules/object_class.rst @@ -274,7 +274,7 @@ References: Resources ---------- -:ref:`Resource ` inherits from Reference, so all resources +:ref:`Resource ` inherits from RefCounted, so all resources are reference counted. Resources can optionally contain a path, which reference a file on disk. This can be set with ``resource.set_path(path)``, though this is normally done by the resource loader. No two different diff --git a/contributing/development/debugging/using_sanitizers.rst b/contributing/development/debugging/using_sanitizers.rst index 3c8a8e92002..a19755212e9 100644 --- a/contributing/development/debugging/using_sanitizers.rst +++ b/contributing/development/debugging/using_sanitizers.rst @@ -140,6 +140,40 @@ slower, while also multiplying memory usage by an approximately 8× factor. the address, memory and thread sanitizers are mutually exclusive. This means you can only use one of those sanitizers in a given binary. +.. note:: + + On Linux, if you stumble upon the following error: + + ``FATAL: ThreadSanitizer: unexpected memory mapping`` + + You may need to temporarily lower the Address Space Layout Randomization (ASLR) entropy in your system with: + + .. code:: sh + + sudo sysctl vm.mmap_rnd_bits=28 + + Or preferably disable it entirely with: + + .. code:: sh + + sudo sysctl kernel.randomize_va_space=0 + + And as soon as you are done with the thread sanitizer, increase the ASLR entropy with: + + .. code:: sh + + sudo sysctl vm.mmap_rnd_bits=32 + + Or re-enable ASLR with: + + .. code:: sh + + sudo sysctl kernel.randomize_va_space=2 + + Rebooting your machine will also revert the ASLR state to its default values. + + It's important to revert the changes as soon as possible because lowering the ASLR entropy or disabling ASLR entirely can be a security risk. + Undefined behavior sanitizer (UBSAN) ------------------------------------ diff --git a/contributing/development/handling_compatibility_breakages.rst b/contributing/development/handling_compatibility_breakages.rst index 1ca903843ca..a1ab7cb297e 100644 --- a/contributing/development/handling_compatibility_breakages.rst +++ b/contributing/development/handling_compatibility_breakages.rst @@ -101,7 +101,7 @@ like ``core/math/a_star_grid_2d.compat.inc`` in this case: #endif // DISABLE_DEPRECATED -Unless the change in compatibility is complex, the compatibility method should simply call the modified method directly, +Unless the change in compatibility is complex, the compatibility method should call the modified method directly, instead of duplicating that method. Make sure to match the default arguments for that method (in the example above this would be ``false``). This file should always be placed next to the original file, and have ``.compat.inc`` at the end instead of ``.cpp`` or ``.h``. diff --git a/contributing/documentation/docs_image_guidelines.rst b/contributing/documentation/docs_image_guidelines.rst index 02116c05bcd..ff48bd4c8ac 100644 --- a/contributing/documentation/docs_image_guidelines.rst +++ b/contributing/documentation/docs_image_guidelines.rst @@ -53,6 +53,12 @@ compression is fine, even if the file size is bigger. If you already have an image editor such as GIMP, Krita or Photoshop installed it may have the ability to open an image then save it as a WebP file. +.. note:: + + Since WebP supports animations and the documentation can display videos, + GIFs should be avoided. Their compression is inefficient and they only support + a 256-color palette with 1-bit transparency. + Cropping ^^^^^^^^ diff --git a/contributing/documentation/docs_writing_guidelines.rst b/contributing/documentation/docs_writing_guidelines.rst index cab1b797178..9206c156e8d 100644 --- a/contributing/documentation/docs_writing_guidelines.rst +++ b/contributing/documentation/docs_writing_guidelines.rst @@ -507,6 +507,166 @@ examples with the ``:kbd:`` tag left as-is for better visibility: - Press ``:kbd:`Space``` and hold the left mouse button to pan in the 2D editor. - Press ``:kbd:`Shift + Up Arrow``` to move the node upwards by 8 pixels. + +Manual style guidelines +----------------------- + +Follow these formatting and style guidelines when writing the manual. + +Use your best judgement. If you can write more clearly by breaking one of these +guidelines, please do! But remember that the guidelines exist for a reason. + +.. note:: In many cases, the manual does not follow these guidelines. If you are + already making changes to a paragraph or section of the docs, update it to + follow these standards. Avoid making unrelated changes that *only* update style, + since every change will require the paragraph to be re-translated. + +Text styles +~~~~~~~~~~~ + +There are a few styles that the manual uses. + ++---------------------+--------------------------+------------------------------------------------------------------------+ +| Style | RST formatting | Typical usage | ++=====================+==========================+========================================================================+ +| Plaintext | ``text`` | Used for most text. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| *Italics* | ``*text*`` | Used for emphasis. Used for introducing new terms. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| **Bold** | ``**text**`` | Used for emphasis, and for editor UI like menus and windows. | +| | | | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| ``Code`` | `` text `` | Used for variable names, literal values, and code snippets. ``code`` is| +| | | used in many cases where you would use "quoted plaintext" in typical | +| | | English. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| "Quotes" | ``"text"`` | Used for some literal or quoted values. In many cases, another | +| | | style is preferred. | ++---------------------+--------------------------+------------------------------------------------------------------------+ + +Emphasis +~~~~~~~~ + +Use either **bold style** or *italic style* to emphasize words or sentences. +In most cases, either **bold** or *italics* is fine. Use whichever seems best, +or whatever the page already uses. + +Prefer using **bold style** for simple emphasis. + + - Do **not** close the window without saving first. + +Use *italic style* or to emphasize one word in the context of a sentence. + + - You can *add* a node to the scene (but you can't connect one). + - You can add a *node* to the scene (but you can't add a resource). + - You can add a node to the *scene* (but you can't add one to a resource). + +Use *italic style* when introducing new technical terms. **Bold style** +is fine too. + + - Godot uses *nodes* with *scripts* in a *scene tree*. + - Godot uses **nodes** with **scripts** in a **scene tree**. + +Literals +~~~~~~~~ + +Use ``code style`` for literal values. Literals include: + + - Integer or ``int`` literals like ``0``, ``-2``, or ``100`` + - Float literals like ``0.0``, ``0.5``, ``-2.0``, or ``100.0`` + - Vector literals like ``(0.0, 0.0)``, ``(0.5, -0.5, 0.5)``, or ``(1.0, 2.0, 3.0, 4.0)``. + +Classes, properties, and methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Link to classes the first time that you mention them in a page. After the first +mention, use ``code style``. For common classes, like ``Node``, ``Control``, or +``Viewport``, you can also use plaintext. + +Link to class members (properties, methods, enums, and constants) the first time +that you mention them in a page. After the first mention, use ``code style``. If +the class member is very common, like a Node2D's ``position``, you don't have to +link. + +When discussing properties in the context of the inspector, use **bold style** +instead. + +Editor UI +~~~~~~~~~ + +Use **bold style** for editor UI, including window titles, menus, buttons, input +fields, inspector properties, and inspector sections. Use the exact +capitalization that the editor uses. + + - Open the **Editor Settings** window. + - Press the **Confirm** button. + - Change the node's **Transform > Position** property to ``(0, 0)``. + - In the **Project Settings** window, enable the **Advanced Settings** toggle. + +Use **Bold > With > Separators** when describing sequence of menus that the +reader must navigate. Use ``>`` as a separator. You can omit ellipses in menu names. + + - In **Project > Project Settings > Input Map**, add a new input action. + - Select **Scene > Export As... > MeshLibrary...**. + - Select **Scene > Export As > MeshLibrary**. + +.. note:: Sometimes, ``->`` or ``→`` is used as a separator. This is nonstandard. + Replace it with ``>`` if you are already making changes to a section. + +Project settings +~~~~~~~~~~~~~~~~ + +Link to individual project settings. Either include the section and subsection +in the link itself, or include the section and subsection separately from the +link. Since long links are not split into multiple lines when the page is +rendered, prefer splitting the setting name and the section when the link is long. + + - Set the :ref:`Application > Run > Max FPS` setting to ``60``. + - In the project settings under **Application > Run**, set :ref:`Max FPS` to ``60``. + - In **Project Settings > Application > Run**, set :ref:`Max FPS` to ``60``. + +Manually wrapping lines +~~~~~~~~~~~~~~~~~~~~~~~ + +In the manual, lines must be manually wrapped to no more than 80-100 characters +per line. However, links must not be split into multiple lines, and can exceed +100 characters. Tables can also exceed 100 characters. + +When making small changes, you don't need to manually re-wrap the whole paragraph, +as long as the lines don't exceed 100 characters. + +**Bad:** Line length exceeds 100 characters: + +.. code-block:: + + The best thing to do is to wrap lines to under 80 characters per line. Wrapping to around 80-90 characters per line is also fine. + If your lines exceed 100 characters, you definitely need to add a newline! Don't forget to remove trailing whitespace when you do. + +**Good:** Lines are wrapped to 80-90 characters: + +.. code-block:: + + The best thing to do is to wrap lines to under 80 characters per line. Wrapping to + around 80-90 characters per line is also fine. If your lines exceed 100 characters, you + definitely need to add a newline! Don't forget to remove trailing whitespace when you do. + +**Best:** Lines are wrapped to under 80 characters: + +.. code-block:: + + The best thing to do is to wrap lines to under 80 characters per line. Wrapping + to around 80-90 characters per line is also fine. If your lines exceed 100 + characters, you definitely need to add a newline! Don't forget to remove + trailing whitespace when you do. + +.. tip:: In most text editors, you can add a vertical guide or "ruler" at 80 + characters. For example, in Visual Studio Code, you can add the following to + your ``settings.json`` to add rulers at 80 and 100 characters: + + .. code:: json + + "editor.rulers": [80,100], + When to refer to a specific Godot version ----------------------------------------- diff --git a/contributing/documentation/updating_the_class_reference.rst b/contributing/documentation/updating_the_class_reference.rst index a16d4486dc7..77e3b262726 100644 --- a/contributing/documentation/updating_the_class_reference.rst +++ b/contributing/documentation/updating_the_class_reference.rst @@ -11,11 +11,12 @@ methods, properties, and global objects, available for scripting. The class refe is available online, from the documentation sidebar, and in the Godot editor, from the help menu. -As the engine grows and features are added or modified, some parts of the class reference -become obsolete and new descriptions and examples need to be added. While developers are -encouraged to document all of their work in the class reference when submitting a pull request, -we can't expect everyone to be able to write high quality documentation, so there is -always work for contributors like you to polish existing and create missing reference material. +As the engine grows and features are added or modified, some parts of the class +reference become obsolete and new descriptions and examples need to be added. +While developers are required to document their work in the class reference when +submitting a pull request, we can't expect every programmer to be a good +technical writer. There is always work for contributors like you to polish +existing and create missing reference material. The source of the class reference --------------------------------- diff --git a/contributing/how_to_contribute.rst b/contributing/how_to_contribute.rst index dddba3258af..5a3e6ec0456 100644 --- a/contributing/how_to_contribute.rst +++ b/contributing/how_to_contribute.rst @@ -14,7 +14,7 @@ Fundraising - **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. + Additionally, it opens the door for us to approach industry contacts about possible collaborations. Technical contributions diff --git a/contributing/workflow/bug_triage_guidelines.rst b/contributing/workflow/bug_triage_guidelines.rst index ae4a5776b15..d674d963c04 100644 --- a/contributing/workflow/bug_triage_guidelines.rst +++ b/contributing/workflow/bug_triage_guidelines.rst @@ -114,7 +114,7 @@ describe an issue or pull request. - *3D*: relates to 3D-specific issues. Should be coupled with one of the labels below, and should not be coupled with *2D*. - *Animation*: relates to the Animation system, editors and importers. - *Assetlib*: relates to issues with the asset library. -- *Audio*: relates to the audio features (low and high level). +- *Audio*: relates to the audio features (low- and high-level). - *Buildsystem*: relates to building issues, either linked to the SCons buildsystem or to compiler peculiarities. - *Codestyle*: relates to the programming style used within the codebase. @@ -196,6 +196,7 @@ use the following `labels `__: **Content:** - *Images*: Issues and PRs involving outdated or incorrect images in articles. +- *Example code*: Issues and PRs involving writing or updating code examples. - *New page*: Issues and PRs related to creation of new documentation pages for new or undocumented features. - *Organization*: Issues and PRs related to reorganizing the content. - *Proofreading*: Issues and PRs related to proofreading the documentation. diff --git a/getting_started/first_2d_game/02.player_scene.rst b/getting_started/first_2d_game/02.player_scene.rst index 20799618811..adad2005486 100644 --- a/getting_started/first_2d_game/02.player_scene.rst +++ b/getting_started/first_2d_game/02.player_scene.rst @@ -20,8 +20,16 @@ what the object *is*. Click the "Other Node" button and add an :ref:`Area2D .. image:: img/add_node.webp -Godot will display a warning icon next to the node in the scene tree. You can -ignore it for now. We will address it later. +When you add the ``Area2D`` node, Godot will display the following **warning icon** +next to it in the scene tree: + +.. image:: img/no_shape_warning.webp + +This warning tells us that the ``Area2D`` node requires a shape to detect collisions or overlaps. +We can **ignore the warning temporarily** because we will first set up the player's visuals +(using an animated sprite). Once the visuals are ready, we will add a collision shape as a child +node. This will allow us to accurately size and position the shape based on the sprite’s appearance. + With ``Area2D`` we can detect objects that overlap or run into the player. Change the node's name to ``Player`` by double-clicking on it. Now that we've @@ -69,12 +77,16 @@ Click on the ``SpriteFrames`` you just created to open the "SpriteFrames" panel: .. image:: img/spriteframes_panel.webp -On the left is a list of animations. Click the "default" one and rename it to -"walk". Then click the "Add Animation" button to create a second animation named -"up". Find the player images in the "FileSystem" tab - they're in the ``art`` -folder you unzipped earlier. Drag the two images for each animation, named -``playerGrey_walk[1/2]`` and ``playerGrey_walk[2/2]``, into the "Animation Frames" -side of the panel for the corresponding animation: +On the left is a list of animations. Click the ``default`` one and rename it to +``walk``. Then click the **Add Animation** button to create a second animation +named ``up``. + +Find the player images in the FileSystem dock - they're in the ``art`` folder +you unzipped earlier. Drag the two images for each animation, into the +**Animation Frames** side of the panel for the corresponding animation: + +- ``playerGrey_walk1`` and ``playerGrey_walk2`` for the ``walk`` animation +- ``playerGrey_up1`` and ``playerGrey_up2`` for the ``up`` animation .. image:: img/spriteframes_panel2.webp @@ -98,6 +110,9 @@ When you're finished, your ``Player`` scene should look like this: .. image:: img/player_scene_nodes.webp +Once this is done, the warning on the ``Area2D`` node will disappear, as it now has +a shape assigned and can interact with other objects. + Make sure to save the scene again after these changes. In the next part, we'll add a script to the player node to move and animate it. diff --git a/getting_started/first_2d_game/img/no_shape_warning.webp b/getting_started/first_2d_game/img/no_shape_warning.webp new file mode 100644 index 00000000000..5caa74b0778 Binary files /dev/null and b/getting_started/first_2d_game/img/no_shape_warning.webp differ 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 cc2d6c07bc7..9cda6e1bfcb 100644 --- a/getting_started/first_3d_game/06.jump_and_squash.rst +++ b/getting_started/first_3d_game/06.jump_and_squash.rst @@ -241,7 +241,11 @@ With this code, if no collisions occurred on a given frame, the loop won't run. # We get one of the collisions with the player var collision = get_slide_collision(index) - # If the collision is with ground + # If there are duplicate collisions with a mob in a single frame + # the mob will be deleted after the first collision, and a second call to + # get_collider will return null, leading to a null pointer when calling + # collision.get_collider().is_in_group("mob"). + # This block of code prevents processing duplicate collisions. if collision.get_collider() == null: continue diff --git a/getting_started/introduction/first_look_at_the_editor.rst b/getting_started/introduction/first_look_at_the_editor.rst index c74b81311a2..ae01d65eb96 100644 --- a/getting_started/introduction/first_look_at_the_editor.rst +++ b/getting_started/introduction/first_look_at_the_editor.rst @@ -149,6 +149,8 @@ and assets to use in your projects. .. seealso:: You can learn more about the asset library in :ref:`doc_what_is_assetlib`. +.. _doc_intro_to_the_editor_interface_integrated_class_reference: + Integrated class reference -------------------------- @@ -181,4 +183,3 @@ Alternatively, 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/key_concepts_overview.rst b/getting_started/introduction/key_concepts_overview.rst index 24e525ddc27..4ac379bb6be 100644 --- a/getting_started/introduction/key_concepts_overview.rst +++ b/getting_started/introduction/key_concepts_overview.rst @@ -84,8 +84,9 @@ flexibility in how you structure your scenes. more about it here: https://gameprogrammingpatterns.com/observer.html -For example, buttons emit a signal when pressed. You can connect to this signal -to run code in reaction to this event, like starting the game or opening a menu. +For example, buttons emit a signal when pressed. You can connect a piece of code +to this signal which will run in reaction to this event, like starting the game +or opening a menu. Other built-in signals can tell you when two objects collided, when a character or monster entered a given area, and much more. You can also define new signals diff --git a/getting_started/step_by_step/scripting_languages.rst b/getting_started/step_by_step/scripting_languages.rst index bfa72daa09c..a1961b2fbef 100644 --- a/getting_started/step_by_step/scripting_languages.rst +++ b/getting_started/step_by_step/scripting_languages.rst @@ -115,7 +115,7 @@ should be aware of its garbage collector. can download it on the Godot website's `download `_ page. -Since Godot uses .NET 6, in theory, you can use any third-party .NET library or +Since Godot uses .NET 8, in theory, you can use any third-party .NET library or framework in Godot, as well as any Common Language Infrastructure-compliant programming language, such as F#, Boo, or ClojureCLR. However, C# is the only officially supported .NET option. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000000..0797f2a0766 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,8 @@ +[tool.ruff] +line-length = 120 + +[tool.codespell] +dictionary = ["_tools/codespell-dict.txt", "-"] +ignore-words = "_tools/codespell-ignore.txt" +exclude-file = "_tools/codespell-ignore-lines.txt" +skip = "tutorials/i18n/locales.rst" diff --git a/tutorials/2d/2d_parallax.rst b/tutorials/2d/2d_parallax.rst index a5d85a93b19..a1dc370ae04 100644 --- a/tutorials/2d/2d_parallax.rst +++ b/tutorials/2d/2d_parallax.rst @@ -10,6 +10,9 @@ Parallax is an effect used to simulate depth by having textures move at differen 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. +.. UPDATE: Experimental. When Parallax2D is no longer experimental, remove this +.. note and remove this comment. + .. 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 diff --git a/tutorials/2d/2d_transforms.rst b/tutorials/2d/2d_transforms.rst index b8e8ccee8cd..7edbdd53391 100644 --- a/tutorials/2d/2d_transforms.rst +++ b/tutorials/2d/2d_transforms.rst @@ -8,7 +8,7 @@ Introduction This is an overview of the 2D transforms going on for nodes from the moment they draw their content locally to the time they are drawn onto -the screen. This overview discusses very low level details of the engine. +the screen. This overview discusses very low-level details of the engine. The goal of this tutorial is to teach a way for feeding input events to the Input with a position in the correct coordinate system. diff --git a/tutorials/2d/custom_drawing_in_2d.rst b/tutorials/2d/custom_drawing_in_2d.rst index ccb39cff4f8..466ad8a26ff 100644 --- a/tutorials/2d/custom_drawing_in_2d.rst +++ b/tutorials/2d/custom_drawing_in_2d.rst @@ -613,7 +613,7 @@ Drawing text ^^^^^^^^^^^^ While using the :ref:`Label ` Node is the most common way to add -text to your application, the low level `_draw` function includes functionality +text to your application, the low-level `_draw` function includes functionality to add text to your custom Node drawing. We will use it to add the name "GODOT" under the robot head. @@ -844,7 +844,7 @@ It will look somewhat like this when run: Please note that ``_mouth_width`` is a user defined property like any other and it or any other used as a drawing argument can be animated using more -standard and high level methods such as a :ref:`Tween` or an +standard and high-level methods such as a :ref:`Tween` or an :ref:`AnimationPlayer` Node. The only difference is that a ``queue_redraw()`` call is needed to apply those changes so they get shown on screen. diff --git a/tutorials/2d/img/2d_editor_guidelines.webp b/tutorials/2d/img/2d_editor_guidelines.webp new file mode 100644 index 00000000000..26d86067f49 Binary files /dev/null and b/tutorials/2d/img/2d_editor_guidelines.webp differ diff --git a/tutorials/2d/img/2d_editor_viewport.webp b/tutorials/2d/img/2d_editor_viewport.webp new file mode 100644 index 00000000000..6bc63280fee Binary files /dev/null and b/tutorials/2d/img/2d_editor_viewport.webp differ diff --git a/tutorials/2d/img/2d_editor_viewport_with_viewmenu.webp b/tutorials/2d/img/2d_editor_viewport_with_viewmenu.webp new file mode 100644 index 00000000000..4a83707b184 Binary files /dev/null and b/tutorials/2d/img/2d_editor_viewport_with_viewmenu.webp differ diff --git a/tutorials/2d/img/2d_platformer_demo.webp b/tutorials/2d/img/2d_platformer_demo.webp new file mode 100644 index 00000000000..e1dbd886b7a Binary files /dev/null and b/tutorials/2d/img/2d_platformer_demo.webp differ diff --git a/tutorials/2d/img/2d_ruler_with_snap.webp b/tutorials/2d/img/2d_ruler_with_snap.webp new file mode 100644 index 00000000000..dd33e5719c1 Binary files /dev/null and b/tutorials/2d/img/2d_ruler_with_snap.webp differ diff --git a/tutorials/2d/img/2d_snapping_options.webp b/tutorials/2d/img/2d_snapping_options.webp new file mode 100644 index 00000000000..1081a06bfb8 Binary files /dev/null and b/tutorials/2d/img/2d_snapping_options.webp differ diff --git a/tutorials/2d/img/2d_snapping_options_menu.webp b/tutorials/2d/img/2d_snapping_options_menu.webp new file mode 100644 index 00000000000..3c8c29d7bd4 Binary files /dev/null and b/tutorials/2d/img/2d_snapping_options_menu.webp differ diff --git a/tutorials/2d/img/2d_toolbar.webp b/tutorials/2d/img/2d_toolbar.webp new file mode 100644 index 00000000000..6b1c18efc4f Binary files /dev/null and b/tutorials/2d/img/2d_toolbar.webp differ diff --git a/tutorials/2d/img/3d_in_2d_demo_editor.webp b/tutorials/2d/img/3d_in_2d_demo_editor.webp new file mode 100644 index 00000000000..960a79cfb84 Binary files /dev/null and b/tutorials/2d/img/3d_in_2d_demo_editor.webp differ diff --git a/tutorials/2d/index.rst b/tutorials/2d/index.rst index 3966f03f59f..2bc60e0de56 100644 --- a/tutorials/2d/index.rst +++ b/tutorials/2d/index.rst @@ -1,5 +1,14 @@ :allow_comments: False +Godot includes a dedicated 2D renderer and 2D physics engine, as well as +2D-specific features like tilemaps, particles, and animation systems. This +section covers most 2D-specific topics in Godot. + +For 2D topics not covered in this section, see also :ref:`doc_2d_skeletons` and +:ref:`doc_navigation_overview_2d`. For using physics in 2D, see +:ref:`doc_physics_index`. There is also a step-by-step tutorial on creating a 2D +game in :ref:`doc_your_first_2d_game`. + 2D == @@ -7,6 +16,7 @@ :maxdepth: 1 :name: toc-learn-features-2d + introduction_to_2d canvas_layers 2d_transforms diff --git a/tutorials/2d/introduction_to_2d.rst b/tutorials/2d/introduction_to_2d.rst new file mode 100644 index 00000000000..1a73f2197d4 --- /dev/null +++ b/tutorials/2d/introduction_to_2d.rst @@ -0,0 +1,316 @@ +.. _doc_introduction_to_2d: + +Introduction to 2D +================== + +Godot's 2D game development tools include a dedicated 2D rendering engine, physics system, +and features tailored specifically for creating 2D experiences. You can efficiently design +levels with the TileMap system, animate characters with 2D sprite or Cutout animation, +and leverage 2D lighting for dynamic scene illumination. The built-in 2D particle system +allows you to create complex visual effects, and Godot also supports custom shaders to +enhance your graphics. These features, combined with Godot's accessibility and +flexibility, provide a solid foundation for creating engaging 2D games. + +.. figure:: img/2d_platformer_demo.webp + + 2D Platformer Demo available on the Asset Library. + +This page will show you the 2D workspace and how you can get to know it. + +.. tip:: If you would like to get an introduction to 3D, see :ref:`doc_introduction_to_3d`. + +2D workspace +~~~~~~~~~~~~ + +You will use the 2D workspace to work with 2D scenes, design levels, or create user +interfaces. +To switch to the 2D workspace, you can either select a 2D node from the scene tree, +or use the workspace selector located at the top edge of the editor: + +.. image:: img/2d_editor_viewport.webp + +Similar to 3D, you can use the tabs below the workspace selector 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 is the main toolbar, and beneath the main toolbar +is the 2D viewport. + +You can drag and drop compatible nodes from the FileSystem dock to add them to the +viewport as nodes. +Dragging and dropping adds the dragged node as a sibling of the selected node +(if the root node is selected, adds as a child). +Keeping :kbd:`Shift` pressed when dropping adds the node as a child of the selected node. +Holding :kbd:`Alt` when dropping adds the node as a child of the root node. +If :kbd:`Alt + Shift` is held when dropping, the node type can be selected if +applicable. + + +Main toolbar +------------ + +Some buttons in the main toolbar are the same as those in the 3D 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/2d_toolbar.webp + +- **Select Mode** (:kbd:`Q`): Allows selection of nodes in the viewport. Left clicking on a node + in the viewport selects it. + 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 drag the selected node(s) to move, press :kbd:`Ctrl` to switch to the + rotation mode temporarily, or use the red circles to scale it. If multiple nodes are + selected, only movement and rotation are possible. In this mode, rotation and scaling + will not use the snapping options if snapping is enabled. +- **Move Mode** (:kbd:`W`): Enables move (or translate) mode for the selected nodes. See + :ref:`doc_introduction_to_2d_the_viewport` for more details. +- **Rotate Mode** (:kbd:`E`): Enables rotation mode for the selected nodes. See + :ref:`doc_introduction_to_2d_the_viewport` for more details. +- **Scale Mode** (:kbd:`S`): Enables scaling and displays scaling gizmos in both + axes for the selected node(s). See :ref:`doc_introduction_to_2d_the_viewport` for more details. +- **Show list of selectable nodes at position clicked**: 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. +- **Rotation pivot**: Sets the rotation pivot to rotate node(s) around. + An added node has its rotation pivot at ``x: 0``, ``y: 0``, by default, with + exceptions. For example, the default pivot for a :ref:`Sprite2D ` is its + center if the ``centered`` property is set to ``true``. If you would like to change the + rotation pivot of a node, click this button and choose a new location by left clicking. + The node rotates considering this point. If you have multiple nodes selected, this icon + will add a temporary pivot to be used commonly by all selected nodes. Pressing :kbd:`Shift` + and clicking this button will create the pivot at the center of selected nodes. If any of + the snap options are enabled, the pivot will also snap to them it when dragged. +- **Pan Mode** (:kbd:`G`): Allows you to navigate in the viewport without accidentally selecting any nodes. + In other modes, you can also hold :kbd:`Space` and drag with the left mouse button to do the same. +- **Ruler Mode**: After enabling, click on the viewport to display the current global + x and y coordinates. Dragging from a position to another one measures the distance in pixels. + If you drag diagonally, it will draw a triangle and show the separate distances in terms + of x, y, and total distance to the target, including the angles to the axes in degrees. + The :kbd:`R` key activates the ruler. If snapping is enabled, it also displays the + measurements in terms of grid count: + +.. figure:: img/2d_ruler_with_snap.webp + + Using ruler with snapping enabled. + +- **Use Smart Snap**: Toggles smart snapping for move, rotate, and scale modes; and + the rotation pivot. Customize it using the three-dot menu next to the snap tools. +- **Use Grid Snap**: Toggles snapping to grid for move and scale mode, rotation pivot, + and the ruler. Customize it using the three-dot menu next to the snap tools. + +You can customize the grid settings so that move mode, rotate mode, scale mode, ruler, +and rotation pivot uses snapping. +Use the three-dot menu for this: + +.. image:: img/2d_snapping_options_menu.webp + +- **Use Rotation Snap**: Toggles snapping using the configured rotation setting. +- **Use Scale Snap**: Toggles snapping using the configured scaling step setting. +- **Snap Relative**: Toggles the usage of snapping based on the selected node's current + transform values. For example, if the grids are set to 32x32 pixels and if the selected node + is located at ``x: 1, y: 1``, then, enabling this option will temporarily shift the grids by + ``x: 1, y: 1``. +- **Use Pixel Snap**: Toggles the use of subpixels for snapping. If enabled, the position values + will be integers, disabling will enable subpixel movement as decimal values. For the runtime + property, consider checking `Project Settings > Rendering > 2D > Snapping` property for + Node2D nodes, and `Project Settings > GUI > General > Snap Controls to Pixels` for + Control nodes. +- **Smart Snapping**: Provides a set of options to snap to specific positions if they are enabled: + + - Snap to Parent: Snaps to parent's edges. For example, scaling a child control node while + this is enabled will snap to the boundaries of the parent. + - Snap to Node Anchor: Snaps to the node's anchor. For example, if anchors of a control + node is positioned at different positions, enabling this will snap to the sides and + corners of the anchor. + - Snap to Node Sides: Snaps to the node's sides, such as for the rotation pivot or anchor + positioning. + - Snap to Node Center: Snaps to the node's center, such as for the rotation pivot or + anchor positioning. + - Snap to Other Nodes: Snaps to other nodes while moving or scaling. Useful to align nodes + in the editor. + - Snap to Guides: Snaps to custom guides drawn using the horizontal or vertical ruler. More + on the ruler and guides below. + +.. image:: img/2d_snapping_options.webp + +- **Configure Snap**: Opens the window shown above, offering a set of snapping parameters. + + - Grid Offset: Allows you to shift grids with respect to the origin. ``x`` and ``y`` can + be adjusted separately. + - Grid Step: The distance between each grid in pixels. ``x`` and ``y`` can be adjusted separately. + - Primary Line Every: The number of grids in-between to draw infinite lines as indication of + main lines. + - Rotation Offset: Sets the offset to shift rotational snapping. + - Rotation Step: Defines the snapping degree. E.g., 15 means the node will rotate and snap + at multiples of 15 degrees if rotation snap is enabled and the rotate mode is used. + - Scale Step: Determines the scaling increment factor. For example, if it is 0.1, it will + change the scaling at 0.1 steps if scaling snap is enabled and the scaling mode is used. + +- **Lock selected nodes** (:kbd:`Ctrl + L`). Locks 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 by 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. +- **Skeleton Options**: Provides options to work with Skeleton2D and Bone2D. + + - Show Bones: Toggles the visibility of bones for the selected node. + - Make Bone2D Node(s) from Node(s): Converts selected node(s) into Bone2D. + +.. seealso:: To learn more about Skeletons, see :ref:`doc_cutout_animation`. + +- **Project Camera Override**: 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 the game is running. + +- **View** menu: Provides options to control the viewport view. Since its options + depend heavily on the viewport, it is covered in the :ref:`doc_introduction_to_2d_the_viewport` + section. + +Next to the View menu, additional buttons may be visible. In the toolbar image +at the beginning of this chapter, an additional *Sprite2D* button appears because a +Sprite2D is selected. This menu provides some quick actions and tools to +work on a specific node or selection. For example, while drawing a polygon, it +provides buttons to add, modify, or remove points. + + +Coordinate system +----------------- + +In the 2D editor, unlike 3D, there are only two axes: ``x`` and ``y``. Also, the viewing +angle is fixed. + +In the viewport, you will see two lines in two colors going across the screen infinitely: +red for the x-axis, and green for the y-axis. +In Godot, going right and down are positive directions. +Where these two lines intersect is the origin: ``x: 0, y: 0``. + +A root node will have its origin at this position once added. +Switching to the `move` or `scale` modes after selecting a node will display the gizmos at the +node's offset position. +The gizmos will point to the positive directions of the x and y axes. +In the move mode, you can drag the green line to move only in the ``y`` axis. +Similarly, you can hold the red line to move only in the ``x`` axis. + +In the scale mode, the gizmos will have a square shape. You can hold and drag the green and +red squares to scale the nodes in the ``y`` or ``x`` axes. +Dragging in a negative direction flips the node horizontally or vertically. + +.. _doc_introduction_to_2d_the_viewport: + +2D Viewport +----------- + +The viewport will be the area you spend the most time if you plan to design levels or user +interfaces visually: + +.. image:: img/2d_editor_viewport_with_viewmenu.webp + +Middle-clicking and dragging the mouse will pan the view. +The scrollbars on the right or bottom of the viewport also move the view. +Alternatively, the :kbd:`G` or :kbd:`Space` keys can be used. +If you enable `Editor Settings > Editors > Panning > Simple Panning`, you can activate +panning directly with :kbd:`Space` only, without requiring dragging. + +The viewport has buttons on the top-left. +**Center View** centers the selected node(s) in the screen. Useful if you have a large scene +with many nodes, and want to see the node selected in the scene tree. +Next to it are the zoom controls. **-** zooms out, **+** zooms in, and clicking on the number +with percentage defaults to 100%. +Alternatively, you can use middle-mouse scrolling to zoom in (scroll up) and out (scroll down). + +The black bars at the viewport's left and top edges are the **rulers**. You can use them to +orient yourself in the viewport. +By default, the rulers will display the pixel coordinates of the viewport, numbered at +100 pixel steps. Changing the zoom factor will change the shown values. +Enabling `Grid Snap` or changing the snapping options will update the ruler's scaling and +the shown values. + +You can also create multiple custom guides to help you make measurements or align +nodes with them: + +.. image:: img/2d_editor_guidelines.webp + +If you have at least one node in the scene, you can create guides by dragging from the horizontal +or vertical ruler towards the viewport. A purple guide will appear, showing its position, and will +remain there when you release the mouse. You can create both horizontal and vertical guides +simultaneously by dragging from the gray square at the rulers' intersection. Guides can be +repositioned by dragging them back to their respective rulers, and they can be removed by +dragging them all the way back to the ruler. + +You can also enable snapping to the created guides using the `Smart Snap` menu. + +.. note:: If you cannot create a line, or do not see previously created guides, make sure that + they are visible by checking the `View` menu of the viewport. :kbd:`Y` toggles their visibility, + by default. Also, make sure you have at least one node in the scene. + +Depending on the tool chosen in the toolbar, left-clicking will have a primary action in the +viewport. +For example, the `Select Mode` will select the left-clicked node in the viewport. +Sometimes, left-clicking can be combined with a modifier (e.g., :kbd:`Ctrl`, or :kbd:`Shift`) to +perform secondary actions. +For example, keeping :kbd:`Shift` pressed while dragging a node in the Select or Move modes will +try to snap the node in a single axis while moving. + +Right clicking in the viewport provides two options to create a node or instantiate a scene +at the chosen position. +If at least one node is selected, right clicking also provides the option to move the selected +node(s) to this position. + + +Viewport has a **View** menu which provides several options to change the look of the viewport: + +- **Grid**: Allows you to show grids all the time, only when using snapping, or not at all. You + can also toggle them with the provided option. +- **Show Helpers**: Toggles the temporary display of an outline of the node, with the previous + transform properties (position, scaling, or rotation) if a transform operation has been + initiated. For `Control` nodes, it also shows the sizing parameters. Useful to see the deltas. +- **Show Rulers**: Toggles the visibility of horizontal and vertical rulers. See + :ref:`doc_introduction_to_2d_the_viewport` more on rulers. +- **Show Guides**: Toggles the visibility of created guides. See + :ref:`doc_introduction_to_2d_the_viewport` for on how to create them. +- **Show Origin**: Toggles the display of the green and red origin lines drawn at ``x: 0, y: 0``. +- **Show Viewport**: Toggles the visibility of the game's default + viewport, indicated by an indigo-colored rectangle. It is also the default window size on desktop + platforms, which can be changed by going to `Project Settings > Display > Window > Size` and + setting `Viewport Width` and `Viewport Height`. +- **Gizmos**: Toggles the visibility of `Position` (shown with cross icon), `Lock` + (shown with padlock), `Groups` (shown with two squares), and `Transformation` (shown with + green and red lines) indicators. +- **Center Selection**: The same as the **Center View** button inside the viewport. Centers the selected + node(s) in the view. :kbd:`F` is the default shortcut. +- **Frame to Selection**: Similar to `Center Selection`, but also changes the zoom factor to fit the + contents in the screen. :kbd:`Shift + F` is the default shortcut. +- **Clear Guides**: Deletes all guides from the screen. You will need to recreate them if + you plan to use them later. +- **Preview Canvas Scale**: Toggles the preview for scaling of canvas in the editor when the zoom + factor or view of the viewport changes. Useful to see how the controls will look like after scaling + and moving, without running the game. +- **Preview Theme**: Allows to choose from the available themes to change the look of control items + in the editor, without requiring to run the game. + + +Node2D and Control node +~~~~~~~~~~~~~~~~~~~~~~~ + +:ref:`CanvasItem ` is the base node for 2D. :ref:`Node2D ` is the base node +for 2D game objects, and :ref:`Control ` is the base node +for everything GUI. For 3D, Godot uses the :ref:`Node3D ` node. + +3D in 2D +-------- + +It is possible to display 3D scenes in 2D screen. This is achieved by adding a +:ref:`SubViewport ` as a child. +Then, you can drag a 3D scene as a child of the SubViewport: + +.. image:: img/3d_in_2d_demo_editor.webp + +.. seealso:: You can check the demo on: `3D in 2D Viewport demo `__. diff --git a/tutorials/2d/using_tilesets.rst b/tutorials/2d/using_tilesets.rst index b8afbc116b0..054676916c8 100644 --- a/tutorials/2d/using_tilesets.rst +++ b/tutorials/2d/using_tilesets.rst @@ -168,7 +168,7 @@ sounds), particle effects, and more. Scene tiles come with a greater performance overhead compared to atlases, as every scene is instanced individually for every placed tile. - It's recommended to use only scene tiles when necessary. To draw sprites in a + It's recommended to only use scene tiles when necessary. To draw sprites in a tile without any kind of advanced manipulation, :ref:`use atlases instead `. @@ -257,7 +257,7 @@ TileSet resource, choose **Merge (Keep Original Atlases)** instead. Adding collision, navigation and occlusion to the TileSet --------------------------------------------------------- -We've now successfully created a basic TileSet. We could start using in the +We've now successfully created a basic TileSet. We could start using it in the 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. @@ -436,7 +436,7 @@ corners or edges of platforms, floors, etc. While these can be placed manually, this quickly becomes tedious. Handling this situation with procedurally generated levels can also be difficult and require a lot of code. -Godot offers *terrains* to perform this kind of tile connections automatically. +Godot offers *terrains* to perform this kind of tile connection automatically. This allows you to have the "correct" tile variants automatically used. Terrains are grouped into terrain sets. Each terrain set is assigned a mode from diff --git a/tutorials/3d/3d_rendering_limitations.rst b/tutorials/3d/3d_rendering_limitations.rst index a1119965284..091f6defd37 100644 --- a/tutorials/3d/3d_rendering_limitations.rst +++ b/tutorials/3d/3d_rendering_limitations.rst @@ -33,12 +33,12 @@ without affecting the source file. Color banding ------------- -When using the Forward+ or Forward Mobile rendering methods, Godot's 3D engine +When using the Forward+ or Mobile rendering methods, Godot's 3D engine renders internally in HDR. However, the rendering output will be tonemapped to a low dynamic range so it can be displayed on the screen. This can result in visible banding, especially when using untextured materials. For performance -reasons, color precision is also lower when using the Forward Mobile rendering -method compared to Forward+. +reasons, color precision is also lower when using the Mobile rendering method +compared to Forward+. When using the Compatibility rendering method, HDR is not used and the color precision is the lowest of all rendering methods. This also applies to 2D diff --git a/tutorials/3d/csg_tools.rst b/tutorials/3d/csg_tools.rst index 7b1ead30273..2fdb6ec2785 100644 --- a/tutorials/3d/csg_tools.rst +++ b/tutorials/3d/csg_tools.rst @@ -296,8 +296,39 @@ in the **Scale** property will cause the texture to repeat more often. the material onto, click the dropdown arrow next to its material property then choose **Paste**. +.. _doc_csg_tools_converting_to_mesh_instance_3d: + +Converting to MeshInstance3D +---------------------------- + +Since Godot 4.4, you can convert a CSG node and its children to a :ref:`class_MeshInstance3D` node. + +This has several benefits: + +- Bake lightmaps, since UV2 can be generated on a MeshInstance3D. +- Bake occlusion culling, since the occlusion culling bake process only takes MeshInstance3D into account. +- Faster loading times, since the CSG mesh no longer needs to be rebuilt when the scene loads. +- Better performance when updating the node's transform if using the mesh within another CSG node. + +To convert a CSG node to a MeshInstance3D node, select it, then choose +**CSG > Bake Mesh Instance** in the toolbar. The MeshInstance3D node +will be created as a sibling. Note that the CSG node that was used for baking is **not** hidden +automatically, so remember to hide it to prevent its geometry from overlapping with the newly created +MeshInstance3D. + +You can also create a trimesh collision shape using **CSG > Bake Collision Shape**. +The generated :ref:`class_CollisionShape3D` node must be a child of a :ref:`class_StaticBody3D` +or :ref:`class_AnimatableBody3D` node to be effective. + +.. tip:: + + Remember to keep the original CSG node in the scene tree, so that you can + perform changes to the geometry later if needed. To make changes to the + geometry, remove the MeshInstance3D node and make the root CSG node visible + again. + Exporting as glTF ------------------------- +----------------- It can be useful to block out a level using CSG, then export it as a 3d model, to import into 3D modeling software. You can do this by selecting **Scene > Export As... > diff --git a/tutorials/3d/environment_and_post_processing.rst b/tutorials/3d/environment_and_post_processing.rst index 16c5a38d90c..c48a2a3b4f6 100644 --- a/tutorials/3d/environment_and_post_processing.rst +++ b/tutorials/3d/environment_and_post_processing.rst @@ -371,7 +371,7 @@ The Environment resource supports many popular mid- and post-processing effects. Screen-Space Reflections (SSR) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -*This feature is only available when using the Forward+ backend, not +*This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* While Godot supports several sources of reflection data such as @@ -413,7 +413,7 @@ uniforms. Screen-Space Ambient Occlusion (SSAO) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -*This feature is only available when using the Forward+ backend, not +*This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* As mentioned in the **Ambient** section, areas where light from light nodes @@ -487,7 +487,7 @@ parameters: Screen-Space Indirect Lighting (SSIL) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -*This feature is only available when using the Forward+ backend, not +*This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* :abbr:`SSIL (Screen-Space Indirect Lighting)` provides indirect lighting for @@ -533,7 +533,7 @@ Tweaking :abbr:`SSIL (Screen-Space Indirect Lighting)` is possible with several Signed Distance Field Global Illumination (SDFGI) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -*This feature is only available when using the Forward+ backend, not +*This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* Signed distance field global illumination (SDFGI) is a form of real-time global @@ -842,7 +842,7 @@ values result in a visually brighter scene. Auto Exposure ^^^^^^^^^^^^^ -*This feature is only available when using the Forward+ backend, not +*This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* Even though, in most cases, lighting and texturing are heavily artist controlled, diff --git a/tutorials/3d/global_illumination/reflection_probes.rst b/tutorials/3d/global_illumination/reflection_probes.rst index ce8a2068687..fb4a314e1b8 100644 --- a/tutorials/3d/global_illumination/reflection_probes.rst +++ b/tutorials/3d/global_illumination/reflection_probes.rst @@ -5,8 +5,8 @@ Reflection probes .. note:: - Reflection probes are only supported in the Clustered Forward and Forward - Mobile rendering backends, not the Compatibility backend. + Reflection probes are only supported in the Forward+ and Mobile renderers, + not the Compatibility renderer. As stated in the :ref:`doc_standard_material_3d`, objects can show reflected and/or diffuse light. Reflection probes are used as a source of reflected *and* ambient @@ -191,10 +191,10 @@ an omni light, a spot light, a :ref:`decal ` or a :ref:`Max Clustered Elements` in **Project Settings > Rendering > Limits > Cluster Builder**. -When using the Forward Mobile backend, only 8 reflection probes can be applied on each +When using the Mobile renderer, only 8 reflection probes can be applied on each individual Mesh *resource*. If there are more reflection probes affecting a single mesh, not all of them will be rendered on the mesh. -Similarly, when using the Compatibility backend, up to 2 reflection probes can be applied -per mesh. If more than 2 reflection probes affect a single mesh, additional probes will -not be rendered. +Similarly, when using the Compatibility renderer, up to 2 reflection probes can +be applied per mesh. If more than 2 reflection probes affect a single mesh, +additional probes will not be rendered. diff --git a/tutorials/3d/global_illumination/using_lightmap_gi.rst b/tutorials/3d/global_illumination/using_lightmap_gi.rst index c6aaa0816e0..68a4c004106 100644 --- a/tutorials/3d/global_illumination/using_lightmap_gi.rst +++ b/tutorials/3d/global_illumination/using_lightmap_gi.rst @@ -80,6 +80,13 @@ Setting up graphics API limitations on those devices. On Android and web platforms, only *rendering* lightmaps that were baked on a desktop PC is supported. +.. note:: + + The LightmapGI node only bakes nodes that are on the same level as the + LightmapGI node (siblings), or nodes that are children of the + LightmapGI node. This allows you to use several LightmapGI nodes to bake + different parts of the scene, independently from each other. + 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 @@ -195,6 +202,25 @@ lightmap texture, which varies depending on the mesh's size properties and the **UV2 Padding** value. **Lightmap Size Hint** should not be manually changed, as any modifications will be lost when the scene is reloaded. +Generating UV2 for CSG nodes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since Godot 4.4, you can +:ref:`convert a CSG node and its children to a MeshInstance3D `. +This can be used to bake lightmaps on a CSG node by following these steps: + +- Select the root CSG node and choose **CSG > Bake Mesh Instance** at the top of the 3D editor viewport. +- Hide the root CSG node that was just baked (it is not hidden automatically). +- Select the newly created MeshInstance3D node and choose **Mesh > Unwrap UV2 for Lightmap/AO**. +- Bake lightmaps. + +.. tip:: + + Remember to keep the original CSG node in the scene tree, so that you can + perform changes to the geometry later if needed. To make changes to the + geometry, remove the MeshInstance3D node and make the root CSG node visible + again. + Checking UV2 ^^^^^^^^^^^^ diff --git a/tutorials/3d/global_illumination/using_sdfgi.rst b/tutorials/3d/global_illumination/using_sdfgi.rst index f2534373a03..fc446705fdd 100644 --- a/tutorials/3d/global_illumination/using_sdfgi.rst +++ b/tutorials/3d/global_illumination/using_sdfgi.rst @@ -18,8 +18,8 @@ its performance requirements at the cost of quality. .. important:: - SDFGI is only supported when using the Forward Plus rendering backend, - not the Forward Mobile or Compatibility backends. + SDFGI is only supported when using the Forward+ renderer, not the Mobile or + Compatibility renderers. .. seealso:: diff --git a/tutorials/3d/global_illumination/using_voxel_gi.rst b/tutorials/3d/global_illumination/using_voxel_gi.rst index 30be7cdf530..c320efe91b0 100644 --- a/tutorials/3d/global_illumination/using_voxel_gi.rst +++ b/tutorials/3d/global_illumination/using_voxel_gi.rst @@ -9,8 +9,8 @@ it's best used when targeting dedicated graphics cards. .. important:: - VoxelGI is only supported when using the Forward Plus rendering backend, - not the Forward Mobile or Compatibility backends. + VoxelGI is only supported when using the Forward+ renderer, not the Mobile or + Compatibility renderers. .. seealso:: diff --git a/tutorials/3d/img/spatial_material26.png b/tutorials/3d/img/spatial_material26.png deleted file mode 100644 index 10178cead4c..00000000000 Binary files a/tutorials/3d/img/spatial_material26.png and /dev/null differ diff --git a/tutorials/3d/img/standard_material_shading_modes.webp b/tutorials/3d/img/standard_material_shading_modes.webp new file mode 100644 index 00000000000..6e7b803e957 Binary files /dev/null and b/tutorials/3d/img/standard_material_shading_modes.webp differ diff --git a/tutorials/3d/img/standard_material_shading_modes_textured.webp b/tutorials/3d/img/standard_material_shading_modes_textured.webp new file mode 100644 index 00000000000..85a6ec9db47 Binary files /dev/null and b/tutorials/3d/img/standard_material_shading_modes_textured.webp differ diff --git a/tutorials/3d/introduction_to_3d.rst b/tutorials/3d/introduction_to_3d.rst index ba6f2d8e06d..d32f8d620bc 100644 --- a/tutorials/3d/introduction_to_3d.rst +++ b/tutorials/3d/introduction_to_3d.rst @@ -19,10 +19,9 @@ which are almost identical to their 2D counterparts. `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. +In 3D, math is a little more complex than in 2D. For an introduction to the +relevant math written for game developers, not mathemeticians or engineers, +check out :ref:`doc_vector_math` and :ref:`doc_using_transforms`. 3D workspace ~~~~~~~~~~~~ diff --git a/tutorials/3d/lights_and_shadows.rst b/tutorials/3d/lights_and_shadows.rst index 437073a074d..b7653a90299 100644 --- a/tutorials/3d/lights_and_shadows.rst +++ b/tutorials/3d/lights_and_shadows.rst @@ -65,10 +65,9 @@ an omni light, a spot light, a :ref:`decal ` or a :ref:`Max Clustered Elements` in **Project Settings > Rendering > Limits > Cluster Builder**. -When using the Forward Mobile renderer, there is a limitation of 8 OmniLights + -8 SpotLights per mesh resource. There is also a limit of 256 OmniLights + 256 -SpotLights that can be rendered in the current camera view. These limits -currently cannot be changed. +When using the Mobile renderer, there is a limitation of 8 OmniLights + 8 SpotLights +per mesh resource. There is also a limit of 256 OmniLights + 256 SpotLights that +can be rendered in the current camera view. These limits currently cannot be changed. When using the Compatibility renderer, up to 8 OmniLights + 8 SpotLights can be rendered per mesh resource. This limit can be increased in the advanced Project @@ -90,7 +89,7 @@ nodes can help reduce this issue while also improving performance. Splitting your meshes into smaller portions can also help, especially for level geometry (which also improves culling efficiency). -If you need to render more lights than possible in a given rendering backend, +If you need to render more lights than possible in a given renderer, consider using :ref:`baked lightmaps ` with lights' bake mode set to **Static**. This allows lights to be fully baked, which also makes them much faster to render. You can also use emissive materials with any @@ -125,6 +124,8 @@ There is a list of generic shadow parameters, each also has a specific function: moving objects. The downside of increasing shadow blur is that it will make the grainy pattern used for filtering more noticeable. See also :ref:`doc_lights_and_shadows_shadow_filter_mode`. +- **Caster Mask:** Shadows are only cast by objects in these layers. Note that + this mask does not affect which objects shadows are cast *onto*. .. image:: img/lights_and_shadows_blur.webp diff --git a/tutorials/3d/occlusion_culling.rst b/tutorials/3d/occlusion_culling.rst index df1e709a138..18ca6f0effd 100644 --- a/tutorials/3d/occlusion_culling.rst +++ b/tutorials/3d/occlusion_culling.rst @@ -58,16 +58,16 @@ performance gains. .. note:: - When using the Clustered Forward rendering backend, the engine already + When using the Forward+ renderer, the engine already performs a *depth prepass*. This consists in rendering a depth-only version of the scene before rendering the scene's actual materials. This is used to ensure each opaque pixel is only shaded once, reducing the cost of overdraw significantly. - The greatest performance benefits can be observed when using the Forward - Mobile rendering backend, as it does not feature a - depth prepass for performance reasons. As a result, occlusion culling will - actively decrease shading overdraw with that rendering backend. + The greatest performance benefits can be observed when using the Mobile + renderer, as it does not feature a depth prepass for performance reasons. As + a result, occlusion culling will actively decrease shading overdraw with + that renderer. Nonetheless, even when using a depth prepass, there is still a noticeable benefit to occlusion culling in complex 3D scenes. However, in scenes with @@ -79,7 +79,8 @@ How occlusion culling works in Godot .. note:: - *"occluder" refers to the shape blocking the view, while "occludee" refers to the object being hidden.* + "occluder" refers to the shape blocking the view, while "occludee" refers to + the object being hidden. In Godot, occlusion culling works by rasterizing the scene's occluder geometry to a low-resolution buffer on the CPU. This is done using @@ -124,6 +125,10 @@ Automatically baking occluders (recommended) those to be treated as occluders, you have to manually create occluder shapes that (roughly) match their geometry. + Since Godot 4.4, CSG nodes can be taken into account in the baking process if they are + :ref:`converted to a MeshInstance3D ` + before baking occluders. + This restriction does not apply to *occludees*. Any node type that inherits from GeometryInstance3D can be occluded. diff --git a/tutorials/3d/particles/attractors.rst b/tutorials/3d/particles/attractors.rst index 7b4012875da..675a36592ee 100644 --- a/tutorials/3d/particles/attractors.rst +++ b/tutorials/3d/particles/attractors.rst @@ -13,6 +13,9 @@ and :ref:`class_GPUParticlesAttractorVectorField3D`. You can instantiate them at change their properties from gameplay code; you can even animate and combine them for complex attraction effects. +.. UPDATE: Not implemented. When particle attractors are implemented for 2D +.. particle systems, remove this note and remove this comment. + .. note:: Particle attractors are not yet implemented for 2D particle systems. diff --git a/tutorials/3d/spring_arm.rst b/tutorials/3d/spring_arm.rst index d104b08af76..40eee878de4 100644 --- a/tutorials/3d/spring_arm.rst +++ b/tutorials/3d/spring_arm.rst @@ -1,5 +1,3 @@ -:article_outdated: False - .. _doc_spring_arm: Third-person camera with spring arm diff --git a/tutorials/3d/standard_material_3d.rst b/tutorials/3d/standard_material_3d.rst index 5d1a2a619be..3bcc36f4007 100644 --- a/tutorials/3d/standard_material_3d.rst +++ b/tutorials/3d/standard_material_3d.rst @@ -244,31 +244,42 @@ Shading Shading mode ~~~~~~~~~~~~ -Godot has a more or less uniform cost per pixel thanks to the depth pre-pass. -All lighting calculations are made by running the lighting shader on every -pixel. - -As these calculations are costly, performance can be brought down considerably -in some corner cases such as drawing several layers of transparency (which is -common in particle systems). Switching to the **Unshaded** shading mode may help improve -performance in these cases, especially when the camera is close to particles. - -Additionally, on low-end or mobile devices, switching to unshaded rendering -can considerably increase rendering performance. - -.. image:: img/spatial_material26.png - -Keep in mind that when unshaded rendering is enabled, lights will not affect the -material at all. - -.. note:: - - **Per-Vertex** shading is listed as an option in the shading mode property. - However, per-vertex shading is currently unimplemented and will act - identical to per-pixel shading. - - Support for per-vertex shading is planned to be reimplemented in a future - Godot release. +Materials support three shading modes: **Per-Pixel**, **Per-Vertex**, and +**Unshaded**. + +.. figure:: img/standard_material_shading_modes.webp + :align: center + :alt: Three spheres showing the Per-Pixel, Per-Vertex, and Unshaded modes. + +The **Per-Pixel** shading mode calculates lighting for each pixel, and is a good +fit for most use cases. However, in some cases you may want to increase +performance by using another shading mode. + +The **Per-Vertex** shading mode, often called "vertex shading" or "vertex lighting", +instead calculates lighting once for each vertex, and interpolates the result +between each pixel. + +On low-end or mobile devices, using per-vertex lighting can considerably increase +rendering performance. When rendering several layers of transparency, +such as when using particle systems, using per-vertex shading can improve +performance, especially when the camera is close to particles. + +You can also use per-vertex lighting to achieve a retro look. + +.. figure:: img/standard_material_shading_modes_textured.webp + :align: center + :alt: Two cubes with a brick texture, one shaded and one unshaded. + + Texture from `AmbientCG `__ + +The **Unshaded** shading mode does not calculate lighting at all. Instead, the +**Albedo** color is output directly. Lights will not affect the material at all, +and unshaded materials will tend to appear considerably brighter than shaded +materials. + +Rendering unshaded is useful for some specific visual effects. If maximum +performance is needed, it can also be used for particles, or low-end or +mobile devices. Diffuse Mode ~~~~~~~~~~~~ diff --git a/tutorials/3d/using_decals.rst b/tutorials/3d/using_decals.rst index 2309a512337..776cd7e5c7f 100644 --- a/tutorials/3d/using_decals.rst +++ b/tutorials/3d/using_decals.rst @@ -5,10 +5,10 @@ Using decals .. note:: - Decals are only supported in the Clustered Forward and Forward Mobile - rendering backends, not the Compatibility backend. + Decals are only supported in the Forward+ and Mobile renderers, not the + Compatibility renderer. - If using the Compatibility backend, consider using Sprite3D as an alternative + If using the Compatibility renderer, consider using Sprite3D as an alternative for projecting decals onto (mostly) flat surfaces. Decals are projected textures that apply on opaque or transparent surfaces in @@ -267,6 +267,6 @@ an omni light, a spot light, a :ref:`decal ` or a :ref:`Max Clustered Elements` in **Project Settings > Rendering > Limits > Cluster Builder**. -When using the Forward Mobile backend, only 8 decals can be applied on each +When using the Mobile renderer, only 8 decals can be applied on each individual Mesh *resource*. If there are more decals affecting a single mesh, not all of them will be rendered on the mesh. diff --git a/tutorials/3d/using_gridmaps.rst b/tutorials/3d/using_gridmaps.rst index 54dd026aa4f..5636fb163d1 100644 --- a/tutorials/3d/using_gridmaps.rst +++ b/tutorials/3d/using_gridmaps.rst @@ -88,6 +88,29 @@ additional nodes can be added as source geometry just for baking the navmesh. The baked cell size of the NavigationMesh must match the NavigationServer map cell size to properly merge the navigation meshes of different grid cells. +MeshLibrary format +------------------ + +To summarize the specific constraints of the MeshLibrary format, a MeshLibrary +scene has a Node3D as the root node, and several child nodes which will become +MeshLibrary items. Each child of the root node should: + +- Be a :ref:`class_MeshInstance3D`, which will become the MeshLibrary item. Only + this visual mesh will be exported. +- Have a material, in the mesh's material slot, *not* the MeshInstance3D's + material slots. +- Have up to one :ref:`class_StaticBody3D` child, for collision. The + StaticBody3D should have one or more :ref:`class_CollisionShape3D` children. +- Have up to one :ref:`class_NavigationRegion3D` child, for navigation. The + NavigationRegion3D can have one or more additional :ref:`class_MeshInstance3D` + children, which can be baked for navigation, but won't be exported as a visual + mesh. + +Only this specific format is recognized. Other node types placed as children +will not be recognized and exported. GridMap is not a general-purpose system for +placing *nodes* on a grid, but rather a specific, optimized system, designed to +place *meshes* with collisions and navigation. + Exporting the MeshLibrary ------------------------- diff --git a/tutorials/3d/using_transforms.rst b/tutorials/3d/using_transforms.rst index c3e9f113638..1041109ae3e 100644 --- a/tutorials/3d/using_transforms.rst +++ b/tutorials/3d/using_transforms.rst @@ -201,6 +201,8 @@ To rotate relative to object space (the node's own transform), use the following // Rotate around the object's local X axis by 0.1 radians. RotateObjectLocal(new Vector3(1, 0, 0), 0.1f); +The axis should be defined in the local coordinate system of the object. For example, to rotate around the object's local X, Y, or Z axes, use ``Vector3.RIGHT`` for the X-axis, ``Vector3.UP`` for the Y-axis, and ``Vector3.FORWARD`` for the Z-axis. + Precision errors ================ diff --git a/tutorials/3d/variable_rate_shading.rst b/tutorials/3d/variable_rate_shading.rst index 81b902c25cf..116e9ca281e 100644 --- a/tutorials/3d/variable_rate_shading.rst +++ b/tutorials/3d/variable_rate_shading.rst @@ -83,11 +83,12 @@ Using variable rate shading in Godot .. note:: - Both Forward Plus and Forward Mobile rendering methods support variable rate + Both Forward+ and Mobile renderers support variable rate shading. VRS can be used in both pancake (non-XR) and XR display modes. - The Compatibility rendering method does **not** support variable rate - shading. + The Compatibility renderer does **not** support variable rate shading. + For XR, you can use :ref:`foveation level ` + as an alternative. In the advanced Project Settings, the **Rendering > VRS** section offers settings to control variable rate shading on the root viewport: diff --git a/tutorials/3d/volumetric_fog.rst b/tutorials/3d/volumetric_fog.rst index e32acee8344..1f021e184e5 100644 --- a/tutorials/3d/volumetric_fog.rst +++ b/tutorials/3d/volumetric_fog.rst @@ -5,8 +5,8 @@ Volumetric fog and fog volumes .. note:: - Volumetric fog is only supported in the Clustered Forward rendering backend, - not Forward Mobile or Compatibility. + Volumetric fog is only supported in the Forward+ renderer, not the Mobile or + Compatibility renderers. As described in :ref:`doc_environment_and_post_processing`, Godot supports various visual effects including two types of fog: traditional (non-volumetric) @@ -270,7 +270,7 @@ Faking volumetric fog using quads In some cases, it may be better to use specially configured QuadMeshes as an alternative to volumetric fog: -- Quads work with any rendering method, including Forward Mobile and Compatibility. +- Quads work with any rendering method, including Mobile and Compatibility. - Quads do not require temporal reprojection to look smooth, which makes them suited to fast-moving dynamic effects such as lasers. They can also represent small details which volumetric fog cannot do efficiently. diff --git a/tutorials/assets_pipeline/escn_exporter/index.rst b/tutorials/assets_pipeline/escn_exporter/index.rst index f607745ba7e..b9f8a0af7d8 100644 --- a/tutorials/assets_pipeline/escn_exporter/index.rst +++ b/tutorials/assets_pipeline/escn_exporter/index.rst @@ -11,4 +11,3 @@ is not maintained or supported in Godot 4.x. While not officially supported, the partially work for some Godot and Blender versions, particularly before Blender version 4.0. For complete docs on the Blender exporter, see the `previous version of this page `__. - diff --git a/tutorials/assets_pipeline/import_process.rst b/tutorials/assets_pipeline/import_process.rst index f3e23002853..b3b81d8acdc 100644 --- a/tutorials/assets_pipeline/import_process.rst +++ b/tutorials/assets_pipeline/import_process.rst @@ -47,7 +47,7 @@ be discarded. After clicking **Reimport**, the chosen parameters will only be used for this asset and on future reimports. Changing the import parameters of several assets at the same time is also -possible. Simply select all of them together in the resources dock and the +possible. Select all of them together in the FileSystem dock and the exposed parameters will apply to all of them when reimporting. Reimporting multiple assets diff --git a/tutorials/assets_pipeline/importing_images.rst b/tutorials/assets_pipeline/importing_images.rst index 292e37d60da..938fabae512 100644 --- a/tutorials/assets_pipeline/importing_images.rst +++ b/tutorials/assets_pipeline/importing_images.rst @@ -79,8 +79,8 @@ It is possible to choose other types of imported resources in the Import dock: custom shaders. - **CubemapArray:** Import the texture as a collection of 6-sided cubemaps, which can be sampled in custom shaders. This resource type can only be - displayed when using the Forward+ or Forward Mobile rendering methods, not - Compatibility. + displayed when using the Forward+ or Mobile renderers, not the Compatibility + renderer. - **Font Data (Monospace Image Font):** Import the image as a bitmap font where all characters have the same width. See :ref:`doc_gui_using_fonts`. - **Image:** Import the image as-is. This resource type cannot be displayed @@ -261,10 +261,10 @@ Compress > High Quality .. note:: High-quality VRAM texture compression is only supported in the Forward+ and - Forward Mobile rendering methods. + Mobile renderers. - When using the Compatibility rendering method, this option is always - considered disabled. + When using the Compatibility renderer, this option is always considered + disabled. If enabled, uses BPTC compression on desktop platforms and :abbr:`ASTC (Adaptive Scalable Texture Compression)` compression on mobile platforms. When using BPTC, @@ -377,6 +377,9 @@ mipmaps but memory usage will increase. Mipmaps > Limit ^^^^^^^^^^^^^^^ +.. UPDATE: Not implemented. When Mipmaps > Limit is implemented, remove this +.. warning and remove this comment. + .. warning:: **Mipmaps > Limit** is currently not implemented and has no effect when changed. diff --git a/tutorials/audio/audio_streams.rst b/tutorials/audio/audio_streams.rst index a4b9f8537ba..268583c170d 100644 --- a/tutorials/audio/audio_streams.rst +++ b/tutorials/audio/audio_streams.rst @@ -33,6 +33,9 @@ AudioStreamPlayer 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. +.. UPDATE: Experimental. When Playback Type is no longer experimental, update +.. this paragraph. + 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 diff --git a/tutorials/best_practices/logic_preferences.rst b/tutorials/best_practices/logic_preferences.rst index a57abe74206..e3d0431aea5 100644 --- a/tutorials/best_practices/logic_preferences.rst +++ b/tutorials/best_practices/logic_preferences.rst @@ -19,8 +19,10 @@ corresponding values, and that code can be slow! For most cases, this code has no impact on your game's performance, but in heavy use cases such as procedural generation, it can bring your game to a crawl. -For these reasons, it is always a best practice to set the initial values -of a node before adding it to the scene tree. +For these reasons, it is usually best practice to set the initial values +of a node before adding it to the scene tree. There are some exceptions where +values *can't* be set before being added to the scene tree, like setting global +position. Loading vs. preloading ---------------------- diff --git a/tutorials/editor/command_line_tutorial.rst b/tutorials/editor/command_line_tutorial.rst index f240b54bfaf..ab28667d31f 100644 --- a/tutorials/editor/command_line_tutorial.rst +++ b/tutorials/editor/command_line_tutorial.rst @@ -188,7 +188,8 @@ given build type. +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ | Command | Description | +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-s``, ``--script