diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 37a2e10d175..2fadf9a9424 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -9,5 +9,7 @@ updates: schedule: interval: "daily" ignore: - # ReadTheDocs is staying on v1. + # We need to decide on when we upgrade Sphinx manually, + # as historically, this has been proven to often imply larger changes + # (RTD compat, upgrading extensions, other dependencies, our content, etc.). - dependency-name: "sphinx" diff --git a/.github/workflows/build_offline_docs.yml b/.github/workflows/build_offline_docs.yml index b5df48b671e..7c6aba060b1 100644 --- a/.github/workflows/build_offline_docs.yml +++ b/.github/workflows/build_offline_docs.yml @@ -11,20 +11,38 @@ jobs: # Don't run scheduled runs on forks unless the CI_OFFLINE_DOCS_CRON variable is set to 'true'. # Manual runs can still be triggered as normal. if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_OFFLINE_DOCS_CRON == 'true' }} - runs-on: ubuntu-22.04 + runs-on: ubuntu-24.04 + timeout-minutes: 180 strategy: matrix: branch: - master - stable + permissions: + contents: write steps: - uses: actions/checkout@v4 with: ref: ${{ matrix.branch }} + - name: Get Python version + id: pythonv + run: | + echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT + + - name: Restore cached virtualenv + uses: actions/cache/restore@v4 + with: + key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }} + path: .venv + - name: Install dependencies run: | - sudo pip3 install -r requirements.txt + python -m venv .venv + source .venv/bin/activate + python -m pip install -r requirements.txt + echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH + echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV sudo apt update sudo apt install parallel libwebp7 @@ -32,6 +50,12 @@ jobs: run: | python migrate.py . _migrated + - name: Save virtualenv cache + uses: actions/cache/save@v4 + with: + key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }} + path: .venv + - name: Sphinx - Build HTML run: make SPHINXOPTS='--color -j 4' SPHINXSOURCEDIR='./_migrated' html diff --git a/.github/workflows/cherrypick.yml b/.github/workflows/cherrypick.yml new file mode 100644 index 00000000000..0be1fc39925 --- /dev/null +++ b/.github/workflows/cherrypick.yml @@ -0,0 +1,75 @@ +name: Create Cherrypick PR + +on: + pull_request: + types: + - closed + branches: + # TODO: Extract this to an env variable? + - 'master' + +env: + # TODO: Add a way to handle multiple potential cherrypick targets. + TARGET_BRANCH: '4.3' + USERNAME: 'Godot Organization' + EMAIL: 'noreply@godotengine.org' + +jobs: + Create-cherrypick-PR: + # The cherrypick label is hardcoded because `contains()` doesn't seem to be able to use an environment variable as a second argument. + if: ${{ github.event.pull_request.merged == true && contains( github.event.pull_request.labels.*.name, 'cherrypick:4.3' ) }} + runs-on: ubuntu-24.04 + timeout-minutes: 10 + env: + # "Ternary" hack featured in the official docs. + # When using "Squash and merge", the commit hash is the last merge commit of the pull request merge branch. + # When using "Merge", the commit hash is the last commit to the head branch of the pull request. + # This is mildly error-prone, since in theory we could merge multiple commits without squashing. + # We are relying on human review of the generated PRs to catch that. + COMMIT_HASH: ${{ github.event.pull_request.commits > 1 && github.sha || github.event.pull_request.head.sha }} + PR_NUMBER: ${{ github.event.number }} + + permissions: + contents: write + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + ref: ${{ env.TARGET_BRANCH }} + + - name: Cherrypick Commit + id: cherrypick_commit + continue-on-error: true + # TODO: Maybe only fetch some branches? + run: | + git config user.name "${{ env.USERNAME }}" + git config user.email "${{ env.EMAIL }}" + git fetch + git cherry-pick -m 1 ${{ env.COMMIT_HASH }} + + - name: Create Pull Request + if: steps.cherrypick_commit.outcome == 'success' + uses: peter-evans/create-pull-request@v7 + with: + commit-message: 'Cherrypick to ${{ env.TARGET_BRANCH }}' + branch: 'cherrypick-${{ env.PR_NUMBER }}-${{ env.TARGET_BRANCH }}' + delete-branch: true + + # Configure the commit author. + author: '${{ env.USERNAME }} <${{ env.EMAIL }}>' + committer: '${{ env.USERNAME }} <${{ env.EMAIL }}>' + + # Configure the pull request. + title: 'Cherrypick ${{ env.PR_NUMBER }} to ${{ env.TARGET_BRANCH }}' + body: 'Cherrypick #${{ env.PR_NUMBER }} to ${{ env.TARGET_BRANCH }}.' + # TODO: Only add the bug or enhancement label, depending on which the original PR uses. + labels: 'bug,enhancement' + + - name: Handle failure + if: steps.cherrypick_commit.outcome == 'failure' + run: | + echo "Can't automatically cherrypick. Potential causes:" + echo "- PR has multiple commits. Did you squash and merge?" + echo "- Cherrypick did not apply cleanly and can't be auto-merged." diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 178a651f94a..1d6d0d58d87 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,12 +5,13 @@ on: pull_request: concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref_name }} cancel-in-progress: true jobs: build: - runs-on: ubuntu-22.04 + runs-on: ubuntu-24.04 + timeout-minutes: 120 steps: - name: Checkout uses: actions/checkout@v4 @@ -18,8 +19,30 @@ jobs: - name: Style checks via pre-commit uses: pre-commit/action@v3.0.1 + - name: Get Python version + id: pythonv + run: | + echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT + + - name: Restore cached virtualenv + uses: actions/cache/restore@v4 + with: + key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }} + path: .venv + - name: Install dependencies - run: sudo pip3 install -r requirements.txt + run: | + python -m venv .venv + source .venv/bin/activate + python -m pip install -r requirements.txt + echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH + echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV + + - name: Save virtualenv cache + uses: actions/cache/save@v4 + with: + key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }} + path: .venv - name: Migrate to Redot run: | @@ -27,4 +50,6 @@ jobs: # Use dummy builder to improve performance as we don't need the generated HTML in this workflow. - name: Sphinx build - run: make SPHINXOPTS='--color -W -j 4' SPHINXSOURCEDIR='./_migrated' dummy + run: | + source .venv/bin/activate + make SPHINXOPTS='--color -W -j 4' SPHINXSOURCEDIR='./_migrated' dummy diff --git a/.github/workflows/sync_class_ref.yml b/.github/workflows/sync_class_ref.yml index d946f41dcd1..4407c8006de 100644 --- a/.github/workflows/sync_class_ref.yml +++ b/.github/workflows/sync_class_ref.yml @@ -3,14 +3,15 @@ name: Sync Class Reference on: workflow_dispatch: # Scheduled updates only run on the default/master branch. + # Other branches need to be run manually (usually after a new release for that branch). schedule: - # Run it at night (European time) every Saturday. - # The offset is there to try and avoid the high load times. + # Run it at (European) night time every Saturday. + # The offset is there to try and avoid high load times. - cron: '15 3 * * 6' # Make sure jobs cannot overlap. concurrency: - group: classref-sync-ci-master + group: classref-sync-ci-${{ github.ref_name }} cancel-in-progress: true jobs: @@ -19,13 +20,14 @@ jobs: # Manual runs can still be triggered as normal. if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_SYNC_CLASS_REF_CRON == 'true' }} name: Update class reference files based on the engine revision - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + timeout-minutes: 10 env: engine_rev: 'master' permissions: contents: write pull-requests: write - + steps: - name: Checkout the documentation repository uses: actions/checkout@v4 diff --git a/_extensions/gdscript.py b/_extensions/gdscript.py index ac10552fd18..76aeb5316c8 100644 --- a/_extensions/gdscript.py +++ b/_extensions/gdscript.py @@ -428,6 +428,8 @@ def innerstring_rules(ttype): "@static_unload", "@tool", "@warning_ignore", + "@warning_ignore_restore", + "@warning_ignore_start", ), prefix=r"(? + {%- if (theme_prev_next_buttons_location == 'bottom' or theme_prev_next_buttons_location == 'both') and (next or prev) %} + + {%- endif %}

User-contributed notes

diff --git a/about/complying_with_licenses.rst b/about/complying_with_licenses.rst index 57b3b0bb9be..4646f982093 100644 --- a/about/complying_with_licenses.rst +++ b/about/complying_with_licenses.rst @@ -84,39 +84,39 @@ how the text has to be included, but here are the most common approaches (you only need to implement one of them, not all). Credits screen -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ Include the above license text somewhere in the credits screen. It can be at the bottom after showing the rest of the credits. Most large studios use this approach with open source licenses. Licenses screen -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ Some games have a special menu (often in the settings) to display licenses. This menu is typically accessed with a button called **Third-party Licenses** or **Open Source Licenses**. Output log -^^^^^^^^^^ +~~~~~~~~~~ Printing the license text using the :ref:`print() ` function may be enough on platforms where a global output log is readable. This is the case on desktop platforms, Android and HTML5 (but not iOS). Accompanying file -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ If the game is distributed on desktop platforms, a file containing the license text can be added to the software that is installed to the user PC. Printed manual -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ If the game includes a printed manual, the license text can be included there. Link to the license -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ The Godot Engine developers consider that a link to ``godotengine.org/license`` in your game documentation or credits would be an acceptable way to satisfy diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst index 2534763bbf0..8d7c0bafe7e 100644 --- a/about/docs_changelog.rst +++ b/about/docs_changelog.rst @@ -17,32 +17,32 @@ New pages since version 4.3 --------------------------- 2D -^^ +~~ - :ref:`doc_introduction_to_2d` 3D -^^ +~~ - :ref:`doc_spring_arm` Debug -^^^^^ +~~~~~ - :ref:`doc_output_panel` Editor -^^^^^^ +~~~~~~ - :ref:`doc_using_the_xr_editor` Performance -^^^^^^^^^^^ +~~~~~~~~~~~ - :ref:`doc_pipeline_compilations` Physics -^^^^^^^ +~~~~~~~ - :ref:`doc_physics_interpolation` - :ref:`doc_physics_interpolation_quick_start_guide` @@ -52,12 +52,12 @@ Physics - :ref:`doc_2d_and_3d_physics_interpolation` Rendering -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_renderers` Shaders -^^^^^^^ +~~~~~~~ - :ref:`doc_shader_functions` @@ -65,39 +65,39 @@ New pages since version 4.2 --------------------------- About -^^^^^ +~~~~~ - :ref:`doc_system_requirements` 2D -^^ +~~ - :ref:`doc_2d_parallax` Contributing -^^^^^^^^^^^^ +~~~~~~~~~~~~ - :ref:`doc_handling_compatibility_breakages` - :ref:`doc_ways_to_contribute` GDExtension -^^^^^^^^^^^ +~~~~~~~~~~~ - :ref:`doc_gdextension_file` - :ref:`doc_gdextension_docs_system` Migrating -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_upgrading_to_godot_4.3` Rendering -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_compositor` XR -^^ +~~ - :ref:`doc_a_better_xr_start_script` - :ref:`doc_openxr_passthrough` @@ -111,27 +111,27 @@ New pages since version 4.1 --------------------------- C# -^^ +~~ - :ref:`doc_c_sharp_diagnostics` Development -^^^^^^^^^^^ +~~~~~~~~~~~ - :ref:`doc_2d_coordinate_systems` Migrating -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_upgrading_to_godot_4.2` I/O -^^^ +~~~ - :ref:`doc_runtime_loading_and_saving` Platform-specific -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ - :ref:`doc_android_library` @@ -139,17 +139,17 @@ New pages since version 4.0 --------------------------- Development -^^^^^^^^^^^ +~~~~~~~~~~~ - :ref:`doc_internal_rendering_architecture` - :ref:`doc_using_sanitizers` Migrating -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_upgrading_to_godot_4.1` Physics -^^^^^^^ +~~~~~~~ - :ref:`doc_troubleshooting_physics_issues` diff --git a/about/faq.rst b/about/faq.rst index d1e630413c4..8f6ff66cbfd 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -256,7 +256,7 @@ This will automatically perform the required steps for desktop integration. Alternatively, you can manually perform the steps that an installer would do for you: Windows -^^^^^^^ +~~~~~~~ - Move the Godot executable to a stable location (i.e. outside of your Downloads folder), so you don't accidentally move it and break the shortcut in the future. @@ -267,14 +267,14 @@ Windows **Pin to Task Bar**. macOS -^^^^^ +~~~~~ Drag the extracted Godot application to ``/Applications/Godot.app``, then drag it to the Dock if desired. Spotlight will be able to find Godot as long as it's in ``/Applications`` or ``~/Applications``. Linux -^^^^^ +~~~~~ - Move the Godot binary to a stable location (i.e. outside of your Downloads folder), so you don't accidentally move it and break the shortcut in the future. diff --git a/about/system_requirements.rst b/about/system_requirements.rst index 9cb6f993818..673840dc173 100644 --- a/about/system_requirements.rst +++ b/about/system_requirements.rst @@ -16,7 +16,7 @@ These are the **minimum** specifications required to run the Godot editor and wo on a simple 2D or 3D project: Desktop or laptop PC - Minimum -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. When adjusting specifications, make sure to only mention hardware that can run the required OS version. .. For example, the x86 CPU requirement for macOS is set after the MacBook Air 11" (late 2010 model), @@ -72,7 +72,7 @@ Desktop or laptop PC - Minimum renderer when running Godot on a Windows version older than 10. Mobile device (smartphone/tablet) - Minimum -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------+-----------------------------------------------------------------------------------------+ | **CPU** | - **Android:** SoC with any 32-bit or 64-bit ARM or x86 CPU | @@ -109,7 +109,7 @@ These are the **recommended** specifications to get a smooth experience with the Godot editor on a simple 2D or 3D project: Desktop or laptop PC - Recommended -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------+---------------------------------------------------------------------------------------------+ | **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more, ARMv8 CPU| @@ -147,7 +147,7 @@ Desktop or laptop PC - Recommended +----------------------+---------------------------------------------------------------------------------------------+ Mobile device (smartphone/tablet) - Recommended -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------+-----------------------------------------------------------------------------------------+ | **CPU** | - **Android:** SoC with 64-bit ARM or x86 CPU, with 3 "performance" cores or more | @@ -200,7 +200,7 @@ These are the **minimum** specifications required to run a simple 2D or 3D project exported with Godot: Desktop or laptop PC - Minimum -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. When adjusting specifications, make sure to only mention hardware that can run the required OS version. .. For example, the x86 CPU requirement for macOS is set after the MacBook Air 11" (late 2010 model), @@ -259,7 +259,7 @@ Desktop or laptop PC - Minimum renderer when running Godot on a Windows version older than 10. Mobile device (smartphone/tablet) - Minimum -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------+-----------------------------------------------------------------------------------------+ | **CPU** | - **Android:** SoC with any 32-bit or 64-bit ARM or x86 CPU | @@ -301,7 +301,7 @@ These are the **recommended** specifications to get a smooth experience with a 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 | @@ -341,7 +341,7 @@ Desktop or laptop PC - Recommended +----------------------+----------------------------------------------------------------------------------------------+ Mobile device (smartphone/tablet) - Recommended -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------+-----------------------------------------------------------------------------------------+ | **CPU** | - **Android:** SoC with 64-bit ARM or x86 CPU, with 3 "performance" cores or more | diff --git a/community/tutorials.rst b/community/tutorials.rst index 18d61d28899..934ce4e632f 100644 --- a/community/tutorials.rst +++ b/community/tutorials.rst @@ -22,25 +22,20 @@ Some tutorials mentioned below cover more advanced subjects, e.g. on 3D or shade Video tutorials --------------- -For video tutorials we recommend looking on `YouTube `_. There's many great -channels covering a wide array of subjects. +For video tutorials we recommend looking on `YouTube `_. +There are many great channels covering a wide array of subjects. Text tutorials -------------- - `FinePointCGI website by Mitch `__ +- `Catlike Coding by Jasper Flick `__ - `GDScript website by Andrew Wilkes `__ - `Godot Recipes by KidsCanCode `__ - `Godot Tutorials by SomethingLikeGames `__ - `Game Dev Artisan website `__ - `Night Quest Games Blog `__ -Devlogs -------- - -- `bitbrain `_ -- `DevDuck (2D) `_ - Resources --------- diff --git a/conf.py b/conf.py index 6419c27592c..bf04422a3ad 100644 --- a/conf.py +++ b/conf.py @@ -140,7 +140,7 @@ is_i18n = tags.has("i18n") # noqa: F821 print("Build language: {}, i18n tag: {}".format(language, is_i18n)) -exclude_patterns = ["_build"] +exclude_patterns = [".*", "**/.*", "_build", "_tools"] # fmt: off # These imports should *not* be moved to the start of the file, diff --git a/contributing/development/compiling/compiling_for_linuxbsd.rst b/contributing/development/compiling/compiling_for_linuxbsd.rst index 0cadc515541..a4582241efd 100644 --- a/contributing/development/compiling/compiling_for_linuxbsd.rst +++ b/contributing/development/compiling/compiling_for_linuxbsd.rst @@ -39,7 +39,7 @@ required: .. _doc_compiling_for_linuxbsd_oneliners: Distro-specific one-liners -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -403,12 +403,6 @@ To cross-compile Godot for RISC-V devices, we need to setup the following items: If in doubt, `use this version `__, and download ``riscv64-glibc-ubuntu-18.04-nightly-2021.12.22-nightly.tar.gz``. Extract it somewhere and remember its path. -- Clang. RISC-V GCC has - `bugs with its atomic operations `__ - which prevent it from compiling Godot correctly. Any version of Clang from 16.0.0 upwards - will suffice. Download it from the package manager of your distro, and make sure that - it *can* compile to RISC-V. You can verify by executing this command ``clang -print-targets``, - make sure you see ``riscv64`` on the list of targets. - `mold `__. This fast linker, is the only one that correctly links the resulting binary. Download it, extract it, and make sure to add its ``bin`` folder to your PATH. Run @@ -431,10 +425,27 @@ Go to the root of the source code, and execute the following build command: :: + PATH="$RISCV_TOOLCHAIN_PATH/bin:$PATH" \ scons arch=rv64 use_llvm=yes linker=mold lto=none target=editor \ ccflags="--sysroot=$RISCV_TOOLCHAIN_PATH/sysroot --gcc-toolchain=$RISCV_TOOLCHAIN_PATH -target riscv64-unknown-linux-gnu" \ linkflags="--sysroot=$RISCV_TOOLCHAIN_PATH/sysroot --gcc-toolchain=$RISCV_TOOLCHAIN_PATH -target riscv64-unknown-linux-gnu" +.. note:: + + RISC-V GCC has `bugs with its atomic operations `__ + which prevent it from compiling Godot correctly. That's why Clang is used instead. Make sure that + it *can* compile to RISC-V. You can verify by executing this command ``clang -print-targets``, + make sure you see ``riscv64`` on the list of targets. + +.. warning:: The code above includes adding ``$RISCV_TOOLCHAIN_PATH/bin`` to the PATH, + but only for the following ``scons`` command. Since riscv-gnu-toolchain uses + its own Clang located in the ``bin`` folder, adding ``$RISCV_TOOLCHAIN_PATH/bin`` + to your user's PATH environment variable may block you from accessing another + version of Clang if one is installed. For this reason it's not recommended to make + adding the bin folder permanent. You can also omit the ``PATH="$RISCV_TOOLCHAIN_PATH/bin:$PATH"`` line + if you want to use scons with self-installed version of Clang, but it may have + compatibility issues with riscv-gnu-toolchain. + The command is similar in nature, but with some key changes. ``ccflags`` and ``linkflags`` append additional flags to the build. ``--sysroot`` points to a folder simulating a Linux system, it contains all the headers, libraries, @@ -565,7 +576,7 @@ listed in the :ref:`doc_compiling_for_linuxbsd_oneliners`: :: sudo dnf install -y \ - embree3-devel \ + embree-devel \ enet-devel \ glslang-devel \ graphite2-devel \ diff --git a/contributing/development/compiling/compiling_for_macos.rst b/contributing/development/compiling/compiling_for_macos.rst index 5d02b0f10ef..778d6795c08 100644 --- a/contributing/development/compiling/compiling_for_macos.rst +++ b/contributing/development/compiling/compiling_for_macos.rst @@ -21,6 +21,8 @@ For compiling under macOS, the following is required: (or the more lightweight Command Line Tools for Xcode). - `Vulkan SDK `_ for MoltenVK (macOS doesn't support Vulkan out of the box). + The latest Vulkan SDK version can be installed quickly by running + ``misc/scripts/install_vulkan_sdk_macos.sh`` within the Godot source repository. .. note:: If you have `Homebrew `_ installed, you can easily install SCons using the following command:: diff --git a/contributing/development/compiling/compiling_for_windows.rst b/contributing/development/compiling/compiling_for_windows.rst index 982d300cccc..60ee8be3d6b 100644 --- a/contributing/development/compiling/compiling_for_windows.rst +++ b/contributing/development/compiling/compiling_for_windows.rst @@ -148,7 +148,7 @@ the engine source code (using ``cd``) and type: .. 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``. + 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. @@ -182,7 +182,15 @@ Compiling with support for Direct3D 12 By default, builds of Godot do not contain support for the Direct3D 12 graphics API. -To compile Godot with Direct3D 12 support you need at least the following item: +You can install the required dependencies by running +``python misc/scripts/install_d3d12_sdk_windows.py`` +in the Godot source repository. After running this script, add the ``d3d12=yes`` +SCons option to enable Direct3D 12 support. This will use the default paths for +the various dependencies, which match the ones used in the script. + +You can find the detailed steps below if you wish to set up dependencies +manually, but the above script handles everything for you (including the +optional PIX and Agility SDK components). - `godot-nir-static library `_. We compile the Mesa libraries you will need into a static library. Download it diff --git a/contributing/development/compiling/compiling_with_dotnet.rst b/contributing/development/compiling/compiling_with_dotnet.rst index d0cf39a11e5..d2e6c7ae810 100644 --- a/contributing/development/compiling/compiling_with_dotnet.rst +++ b/contributing/development/compiling/compiling_with_dotnet.rst @@ -83,7 +83,7 @@ More details about this directory in :ref:`Data directory`. Build Platform -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ Provide the ``--godot-platform=`` argument to control for which platform specific the libraries are built. Omit this argument to build for the @@ -93,7 +93,7 @@ This currently only controls the inclusion of the support for Visual Studio as an external editor, the libraries are otherwise identical. NuGet packages -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ The API assemblies, source generators, and custom MSBuild project SDK are distributed as NuGet packages. This is all transparent to the user, but it can @@ -130,7 +130,7 @@ cache. It's recommended to always use this option when building the C# solutions during development to avoid mistakes. Building without depending on deprecated features (NO_DEPRECATED) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When building Godot without deprecated classes and functions, i.e. the ``deprecated=no`` argument for scons, the managed libraries must also be built without dependencies to deprecated code. @@ -140,7 +140,7 @@ This is done by passing the ``--no-deprecated`` argument: ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local --no-deprecated Double Precision Support (REAL_T_IS_DOUBLE) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When building Godot with double precision support, i.e. the ``precision=double`` argument for scons, the managed libraries must be adjusted to match by passing @@ -154,7 +154,7 @@ Examples -------- Example (Windows) -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ :: @@ -171,7 +171,7 @@ Example (Windows) Example (Linux, \*BSD) -^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~ :: @@ -196,7 +196,7 @@ enabled. It contains important files for the correct functioning of Godot. It must be distributed together with the Godot executable. Editor -^^^^^^ +~~~~~~ The name of the data directory for the Godot editor will always be ``GodotSharp``. This directory contains an ``Api`` subdirectory with the Godot @@ -208,7 +208,7 @@ directory may be placed in the ``.app/Contents/Resources/`` directory inside the bundle. Export templates -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ The data directory for exported projects is generated by the editor during the export. It is named ``data__``, where ```` is the diff --git a/contributing/development/compiling/optimizing_for_size.rst b/contributing/development/compiling/optimizing_for_size.rst index 278f98d4951..2cabcac11e4 100644 --- a/contributing/development/compiling/optimizing_for_size.rst +++ b/contributing/development/compiling/optimizing_for_size.rst @@ -271,7 +271,7 @@ Optimizing the distribution of your project ------------------------------------------- Desktop -^^^^^^^ +~~~~~~~ .. note:: @@ -303,7 +303,7 @@ command: 7z a -mx9 my_project.zip folder_containing_executable_and_pck Web -^^^ +~~~ Enabling gzip or Brotli compression for all file types from the web export (especially the ``.wasm`` and ``.pck``) can reduce the download size diff --git a/contributing/development/core_and_modules/custom_platform_ports.rst b/contributing/development/core_and_modules/custom_platform_ports.rst index fd5ece4a7ff..5c601b1d978 100644 --- a/contributing/development/core_and_modules/custom_platform_ports.rst +++ b/contributing/development/core_and_modules/custom_platform_ports.rst @@ -63,7 +63,7 @@ knowledge of the platform's SDKs. Depending on what features you need, the amount of work needed varies: Required features of a platform port -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At the very least, a platform port must have methods from the :ref:`class_OS` singleton implemented to be buildable and usable for headless operation. @@ -109,7 +109,7 @@ All methods should be implemented within ``detect.py`` as follows: options depending on SCons options chosen. Optional features of a platform port -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In practice, headless operation doesn't suffice if you want to see anything on screen and handle input devices. You may also want audio output for most diff --git a/contributing/development/core_and_modules/internal_rendering_architecture.rst b/contributing/development/core_and_modules/internal_rendering_architecture.rst index 6d12b5e5d42..0ab0a1bbbba 100644 --- a/contributing/development/core_and_modules/internal_rendering_architecture.rst +++ b/contributing/development/core_and_modules/internal_rendering_architecture.rst @@ -20,11 +20,11 @@ ask in the ``#rendering`` channel of the recommended to go through an OpenGL tutorial such as `LearnOpenGL `__. - Modern low-level APIs (Vulkan/Direct3D 12) require intermediate + Modern low-level APIs (Vulkan/Direct3D 12/Metal) require intermediate knowledge of higher-level APIs (OpenGL/Direct3D 11) to be used effectively. Thankfully, contributors rarely need to work directly with low-level APIs. Godot's renderers are built entirely on OpenGL and - RenderingDevice, which is our abstraction over Vulkan/Direct3D 12. + RenderingDevice, which is our abstraction over Vulkan/Direct3D 12/Metal. .. _doc_internal_rendering_architecture_methods: @@ -32,7 +32,7 @@ Rendering methods ----------------- Forward+ -^^^^^^^^ +~~~~~~~~ This is a forward renderer that uses a *clustered* approach to lighting. @@ -45,7 +45,7 @@ This approach can greatly speed up rendering performance on desktop hardware, but is substantially less efficient on mobile. Mobile -^^^^^^ +~~~~~~ This is a forward renderer that uses a traditional single-pass approach to lighting. Internally, it is called **Forward Mobile**. @@ -104,12 +104,12 @@ post-processing effects are also not available. .. _doc_internal_rendering_architecture_compatibility: Compatibility -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ .. note:: 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 rendering method is not available when using Vulkan, Direct3D 12, or Metal. 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, @@ -139,7 +139,7 @@ rendering features (even less so compared to Mobile). Most post-processing effects are not available. Why not deferred rendering? -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Forward rendering generally provides a better tradeoff for performance versus flexibility, especially when a clustered approach to lighting is used. While @@ -161,7 +161,7 @@ Rendering drivers Godot 4 supports the following graphics APIs: Vulkan -^^^^^^ +~~~~~~ This is the main driver in Godot 4, with most of the development focus going towards this driver. @@ -185,7 +185,7 @@ Vulkan driver. - `drivers/d3d12/d3d12_context.cpp `__ Direct3D 12 -^^^^^^^^^^^ +~~~~~~~~~~~ Like Vulkan, the Direct3D 12 driver targets modern platforms only. It is designed to target both Windows and Xbox (whereas Vulkan can't be used directly on Xbox). @@ -206,25 +206,28 @@ See the `pull request that introduced Direct3D 12 support `__, -as macOS and iOS do not support Vulkan natively. -This is done automatically when specifying the Vulkan driver in the Project Settings. +Godot provides a native Metal driver that works on all Apple Silicon hardware +(macOS ARM). Compared to using the MoltenVK translation layer, this is +significantly faster, particularly in CPU-bound scenarios. -MoltenVK makes driver maintenance easy at the cost of some performance overhead. -Also, MoltenVK has several limitations that a native Metal driver implementation -wouldn't have. Both the clustered and mobile -:ref:`doc_internal_rendering_architecture_methods` can be used with a Metal -backend via MoltenVK. +Both the Forward+ and Mobile :ref:`doc_internal_rendering_architecture_methods` can be +used with Metal. + +:ref:`doc_internal_rendering_architecture_core_shaders` are shared with the +Vulkan renderer. Shaders are transpiled from GLSL to :abbr:`MSL (Metal Shading Language)` +using SPIRV-Cross. -.. UPDATE: Planned feature. When the native Metal driver is implemented, update this. +Godot also supports Metal rendering via `MoltenVK `__, +which is used as a fallback when native Metal support is not available (e.g. on x86 macOS). -A native Metal driver is planned in the future for better performance and -compatibility. +**This driver is still experimental and only available in Godot 4.4 and later.** +See the `pull request that introduced Metal support `__ +for more information. OpenGL -^^^^^^ +~~~~~~ This driver uses OpenGL ES 3.0 and targets legacy and low-end devices that don't support Vulkan. OpenGL 3.3 Core Profile is used on desktop platforms to run this @@ -246,17 +249,17 @@ Many advanced features are not supported with this driver, as it targets low-end devices first and foremost. Summary of rendering drivers/methods -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following rendering API + rendering method combinations are currently possible: -- Vulkan + Forward+ -- Vulkan + Mobile +- Vulkan + Forward+ (optionally through MoltenVK on macOS and iOS) +- Vulkan + Mobile (optionally through MoltenVK on macOS and iOS) - Direct3D 12 + Forward+ - Direct3D 12 + Mobile -- Metal + Forward+ (via MoltenVK) -- Metal + Mobile (via MoltenVK) -- OpenGL + Compatibility +- Metal + Forward+ +- Metal + Mobile +- OpenGL + Compatibility (optionally through ANGLE on Windows and macOS) Each combination has its own limitations and performance characteristics. Make sure to test your changes on all rendering methods if possible before opening a @@ -273,10 +276,10 @@ To make the complexity of modern low-level graphics APIs more manageable, Godot uses its own abstraction called RenderingDevice. This means that when writing code for modern rendering methods, you don't -actually use the Vulkan or Direct3D 12 APIs directly. While this is still +actually use the Vulkan, Direct3D 12, or Metal APIs directly. While this is still lower-level than an API like OpenGL, this makes working on the renderer easier, as RenderingDevice will abstract many API-specific quirks for you. The -RenderingDevice presents a similar level of abstraction as Metal or WebGPU. +RenderingDevice presents a similar level of abstraction as WebGPU. **Vulkan RenderingDevice implementation:** @@ -286,6 +289,10 @@ RenderingDevice presents a similar level of abstraction as Metal or WebGPU. - `drivers/d3d12/rendering_device_driver_d3d12.cpp `__ +**Metal RenderingDevice implementation:** + +- `drivers/metal/rendering_device_driver_metal.mm `__ + Core rendering classes architecture ----------------------------------- @@ -447,14 +454,14 @@ used to calculate particle collisions in 2D. ----------------------- Batching and instancing -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ 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. Light, decal and reflection probe rendering -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -497,7 +504,7 @@ Clustering is also used for reflection probes and decal rendering in the Forward+ renderer. Shadow mapping -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ Both Forward+ and Mobile methods use :abbr:`PCF (Percentage Closer Filtering)` to filter shadow maps and create a @@ -517,7 +524,7 @@ The Compatibility renderer supports shadow mapping for DirectionalLight3D, OmniLight3D, and SpotLight3D lights. Temporal antialiasing -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -549,7 +556,7 @@ RenderingDevice abstraction as opposed to using AMD's reference code directly. - `thirdparty/amd-fsr2/ `__ Global illumination -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ .. note:: @@ -600,7 +607,7 @@ This would allow baking lightmaps while using the Compatibility renderer. - `modules/lightmapper_rd/lm_blendseams.glsl `__ Depth of field -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ .. note:: @@ -629,7 +636,7 @@ when temporal antialiasing is enabled. - `servers/rendering/renderer_rd/shaders/effects/bokeh_dof_raster.glsl `__ Screen-space effects (SSAO, SSIL, SSR, SSS) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -678,7 +685,7 @@ SSR is always performed at half resolution to improve performance. - `servers/rendering/renderer_rd/shaders/effects/subsurface_scattering.glsl `__ Sky rendering -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ .. seealso:: @@ -705,7 +712,7 @@ article. **Sky rendering GLSL shader:** Volumetric fog -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ .. note:: @@ -740,10 +747,11 @@ article. - `servers/rendering/renderer_rd/shaders/environment/volumetric_fog_process.glsl `__ Occlusion culling -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ While modern GPUs can handle drawing a lot of triangles, the number of draw -calls in complex scenes can still be a bottleneck (even with Vulkan and Direct3D 12). +calls in complex scenes can still be a bottleneck (even with Vulkan, Direct3D 12, +and Metal). Godot 4 supports occlusion culling to reduce overdraw (when the depth prepass is disabled) and reduce vertex throughput. @@ -782,7 +790,7 @@ RendererSceneOcclusionCull. - `servers/rendering/renderer_scene_occlusion_cull.cpp `__ Visibility range (LOD) -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~ Godot supports manually authored hierarchical level of detail (HLOD), with distances specified by the user in the inspector. @@ -796,7 +804,7 @@ same mesh with different LODs (to allow for split screen rendering to look corre - `servers/rendering/renderer_scene_cull.cpp `__ Automatic mesh LOD -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ The ImporterMesh class is used for the 3D mesh import workflow in the editor. Its ``generate_lods()`` function handles generating using the diff --git a/contributing/development/cpp_usage_guidelines.rst b/contributing/development/cpp_usage_guidelines.rst index cccc6930329..0ba32784882 100644 --- a/contributing/development/cpp_usage_guidelines.rst +++ b/contributing/development/cpp_usage_guidelines.rst @@ -46,7 +46,7 @@ use of modern C++ features conservative. Their use needs to serve a real purpose, such as improving code readability or performance. Standard Template Library -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ We don't allow using the `STL `__ as Godot provides its own data types (among other things). @@ -67,7 +67,7 @@ This means that pull requests should **not** use ``std::string``, and Array. Therefore, List should be avoided in new code unless necessary. ``auto`` keyword -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ Please don't use the ``auto`` keyword for type inference. While it can avoid repetition, it can also lead to confusing code: @@ -88,14 +88,14 @@ We chose to forbid ``auto`` instead of allowing it on a case-by-case basis to avoid having to decide on difficult edge cases. Thank you for your understanding. Lambdas -^^^^^^^ +~~~~~~~ Lambdas should be used conservatively when they make code effectively faster or simpler, and do not impede readability. Please ask before using lambdas in a pull request. ``#pragma once`` directive -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ To follow the existing style, please use standard ``#ifdef``-based include guards instead of ``#pragma once`` in new files. diff --git a/contributing/development/debugging/using_cpp_profilers.rst b/contributing/development/debugging/using_cpp_profilers.rst index 72e2cf78106..df51becbbe1 100644 --- a/contributing/development/debugging/using_cpp_profilers.rst +++ b/contributing/development/debugging/using_cpp_profilers.rst @@ -59,7 +59,7 @@ Profiler-specific instructions ------------------------------ VerySleepy -^^^^^^^^^^ +~~~~~~~~~~ - Start the Godot editor or your project first. If you start the Project Manager, make sure to edit or run a project first. @@ -81,7 +81,7 @@ VerySleepy .. image:: img/cpp_profiler_verysleepy_results_filtered.png HotSpot -^^^^^^^ +~~~~~~~ - Open HotSpot. Click **Record Data**: @@ -128,7 +128,7 @@ HotSpot This process attachment-based workflow is similar to the one used by VerySleepy. Xcode Instruments -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ - Open Xcode. Select **Open Developer Tool** - **Instruments** from the **Xcode** app menu: - Double-click on **Time Profiler** in the **Instruments** window: diff --git a/contributing/development/debugging/using_sanitizers.rst b/contributing/development/debugging/using_sanitizers.rst index a19755212e9..7d6f4c32874 100644 --- a/contributing/development/debugging/using_sanitizers.rst +++ b/contributing/development/debugging/using_sanitizers.rst @@ -197,7 +197,7 @@ Platform-specific sanitizers ---------------------------- Web -^^^ +~~~ When :ref:`compiling for the Web `, there are 2 additional sanitizer SCons options available: diff --git a/contributing/documentation/building_the_manual.rst b/contributing/documentation/building_the_manual.rst index a3752d14ecf..60a338e12d6 100644 --- a/contributing/documentation/building_the_manual.rst +++ b/contributing/documentation/building_the_manual.rst @@ -134,7 +134,7 @@ Hints for performance --------------------- RAM usage -^^^^^^^^^ +~~~~~~~~~ Building the documentation requires at least 8 GB of RAM to run without disk swapping, which slows it down. @@ -160,7 +160,7 @@ threads, ``-j auto`` (which corresponds to ``-j 32`` here) can require 20+ GB of RAM for Sphinx alone. Specifying a list of files -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ You can specify a list of files to build, which can greatly speed up compilation: diff --git a/contributing/documentation/docs_image_guidelines.rst b/contributing/documentation/docs_image_guidelines.rst index ff48bd4c8ac..7be6c25c780 100644 --- a/contributing/documentation/docs_image_guidelines.rst +++ b/contributing/documentation/docs_image_guidelines.rst @@ -11,7 +11,7 @@ Images ------ Capturing an image -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ To take a picture of something in Godot, a screen capture tool can be used. @@ -37,7 +37,7 @@ resolution screen the screenshot should be scaled down. There are instructions on how to do this later on this page. Format conversion -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ The current format for images in Godot's documentation is WebP (``.webp``). While some Linux programs will support saving screenshots in this format, macOS @@ -60,7 +60,7 @@ it may have the ability to open an image then save it as a WebP file. a 256-color palette with 1-bit transparency. Cropping -^^^^^^^^ +~~~~~~~~ For a screenshot of a 2D or 3D scene in the editor, the above steps will be enough. But for most UI images some extra work should be done, specifically cropping to @@ -95,7 +95,7 @@ Krita and can be adjusted. Click on the image with your cropping tool still sele and the controls will return. Scaling down an image -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ As explained earlier on this page, all images taken on a screen that is a higher resolution than 1080p should be scaled down. To do this in Krita click on **Image** on the top bar, and @@ -107,7 +107,7 @@ sure the **Constrain Proportions** box at the bottom of the menu is checked so y to change 1 value. Saving as WebP in Krita -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ To save an image as webp if it isn't already one, Go to **File > Save As**. Select **webp** from the **Save as type:** dropdown, then choose wherever you want to save it. After clicking **Save** a menu @@ -120,7 +120,7 @@ If it's still over 300KB change to lossy compression and slowly increase the com size is bigger. Outlines, arrows and text -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ Sometimes an image needs something extra to properly direct the readers attention, or make something clear. Outlines and arrows can be used @@ -145,7 +145,7 @@ be used if appropriate. For example, if yellow blends into the image, or if ther multiple outlines in multiple colors. Adding an image to a documentation page -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once you've finished working on your image, it can be added to the documentation. All images are stored in folders named ``img`` next to the page they are used in. @@ -164,7 +164,7 @@ Videos ------ Capturing a video -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ To record a video of something in Godot, a screen capture tool can be used. Operating systems generally don't come with tools that are flexible enough @@ -188,7 +188,7 @@ use a resolution of 1280×720. recording on a slow device), but it's less flexible. Compressing the captured video -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The recommendation is to record your video in the highest quality possible (without dropping frames due to excessive CPU/GPU utilization), then re-encode diff --git a/contributing/documentation/docs_writing_guidelines.rst b/contributing/documentation/docs_writing_guidelines.rst index 9206c156e8d..88552f4196e 100644 --- a/contributing/documentation/docs_writing_guidelines.rst +++ b/contributing/documentation/docs_writing_guidelines.rst @@ -665,7 +665,50 @@ as long as the lines don't exceed 100 characters. .. code:: json - "editor.rulers": [80,100], + "editor.rulers": [80,100], + +Section header syntax +~~~~~~~~~~~~~~~~~~~~~ + +Use the following syntax for section headers: + +.. code-block:: + + Page title + ========== + + Renders as h1. + Every page has this. + + Section header + -------------- + + Renders as h2. + Usually appears in sidebar. Many pages only need one level of nested headers. + + Sub-section header + ~~~~~~~~~~~~~~~~~~ + + Renders as h3. + Appears in sidebar in some pages, depending on how deeply nested the page is. + + Sub-sub-section header + ^^^^^^^^^^^^^^^^^^^^^^ + + Renders as h4. + Usually won't appear in the sidebar. + +Currently, there are no cases of deeper header nesting than this. Avoid +introducing any deeper nesting. + +Note that headers have no inherent meaning. In reStructuredText, headers are +parsed based on the order that they initially appear within a page. Make sure +that if you use an ``h3`` section header (``~~~``), you include an ``h2`` +sub-section header (``---``) first. + +See the `Sphinx documentation `__ +and the `reStructuredText documentation `__ +for more information. When to refer to a specific Godot version ----------------------------------------- diff --git a/contributing/workflow/bisecting_regressions.rst b/contributing/workflow/bisecting_regressions.rst index 6e58e410e35..53a1c723fcb 100644 --- a/contributing/workflow/bisecting_regressions.rst +++ b/contributing/workflow/bisecting_regressions.rst @@ -77,7 +77,7 @@ reproduce the bug. another contributor can continue bisecting from there. Determine the commit hashes -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ To start bisecting, you must first determine the commit hashes (identifiers) of the "bad" and "good" build. "bad" refers to the build that exhibits the bug, @@ -138,7 +138,7 @@ instead of a commit hash. Note that unlike tagged releases or snapshot commit hashes, ``master`` is a perpetually moving target. Build the engine -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ :ref:`Get Godot's source code using Git `. Once this is done, in the terminal window, use ``cd`` to reach the Godot repository @@ -159,7 +159,7 @@ Compile Godot. This assumes you've set up a build environment: scons Run the engine -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ Run the binary located in the ``bin/`` folder and try to reproduce the bug. diff --git a/contributing/workflow/pr_review_guidelines.rst b/contributing/workflow/pr_review_guidelines.rst index 66281dcc1a9..9bdf7146509 100644 --- a/contributing/workflow/pr_review_guidelines.rst +++ b/contributing/workflow/pr_review_guidelines.rst @@ -70,7 +70,7 @@ do to conduct a substantive code review of a pull request. code only and have not tested the changes locally. 1. Confirm that the problem exists -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PRs need to solve problems and problems need to be documented. Make sure that the pull request links and closes (or at least addresses) a bug or a proposal. @@ -83,7 +83,7 @@ the PR to explain the problem that the PR aims to solve in more detail. helps contributors in the future understand why the code is the way it is. 2. Test the PR and look for regressions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While strict code review and CI help to ensure that all pull requests work as intended, mistakes happen and sometimes contributors push code that creates a @@ -99,7 +99,7 @@ the code, look for suspicious changes in other parts of the engine. Sometimes during rebasing changes slip through that contributors are not aware of. 3. Do a code review -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ Code reviews are usually done by people who are already experienced in a given area. They may be able to provide ideas to make code faster, more organized, or @@ -137,7 +137,7 @@ Here are some things to think about and look out for as you review the code: problem. 4. Iterate with the contributor and improve the PR -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Maintainers should provide feedback and suggestions for improvement if they spot things in the code that they would like changed. Preferably, suggestions should @@ -194,7 +194,7 @@ Other teams may already be tagged for review, so you can also wait or ask for their assistance. 5. Approve the pull request -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ After reviewing the code, if you think that the code is ready to be merged into the engine, then go ahead and "approve" it. Make sure to also comment and @@ -270,7 +270,7 @@ As a contributor you can help move a pull request forward by doing some of these steps yourself. 1. Get feedback from the right people/teams -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Production team members should ensure that the right people look at a pull request before it is merged. In some cases this may require multiple people to @@ -301,7 +301,7 @@ Godot organization left a review without having the relevant expertise. `_. 2. Get feedback from the community -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If a pull request is having trouble attracting reviewers, you may need to reach out more broadly to ask for help reviewing. Consider asking: @@ -311,7 +311,7 @@ out more broadly to ask for help reviewing. Consider asking: * a more experienced maintainer from another area if they could provide feedback. 3. Git checklist -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ * **Make sure that the PR comes in one commit.** @@ -358,7 +358,7 @@ out more broadly to ask for help reviewing. Consider asking: page in the main Godot repository. 4. GitHub checklist -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ * **Validate the target branch of the PR.** @@ -413,7 +413,7 @@ out more broadly to ask for help reviewing. Consider asking: milestone for the closed issue. 5. Merge the pull request -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ If it is appropriate for you to be merging a pull request (i.e. you are on the production team or you are the team leader for that area), you are confident diff --git a/contributing/workflow/testing_pull_requests.rst b/contributing/workflow/testing_pull_requests.rst index 7f96ff6bd41..75ce55be8e4 100644 --- a/contributing/workflow/testing_pull_requests.rst +++ b/contributing/workflow/testing_pull_requests.rst @@ -27,7 +27,7 @@ depending on whether you have a GitHub account or not. instead. If you have a GitHub account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Open the pull request page. Click the **Checks** tab near the top of the page: @@ -50,7 +50,7 @@ If you have a GitHub account On macOS, see :ref:`doc_running_on_macos` for instructions on bypassing Gatekeeper. If you don't have a GitHub account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you don't have a GitHub account and can't sign up for one, you can use the third-party `nightly.link `__ service @@ -91,7 +91,7 @@ This approach may be needed for pull requests that were last updated more than by Godot's GitHub Actions setup. Downloading a zipped pull request branch -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Open the pull request page. Click the *fork*'s branch name near the top of the page: @@ -106,7 +106,7 @@ Downloading a zipped pull request branch for your operating system. Checking out a pull request branch with git -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Alternatively, you can checkout the pull request directly with git: diff --git a/getting_started/first_2d_game/01.project_setup.rst b/getting_started/first_2d_game/01.project_setup.rst index 50ca655c182..7269ae14da3 100644 --- a/getting_started/first_2d_game/01.project_setup.rst +++ b/getting_started/first_2d_game/01.project_setup.rst @@ -41,7 +41,8 @@ Your project folder should look like this. This game is designed for portrait mode, so we need to adjust the size of the game window. Click on *Project -> Project Settings* to open the project settings window, in the left column open the *Display -> Window* tab. There, set -"Viewport Width" to ``480`` and "Viewport Height" to ``720``. +"Viewport Width" to ``480`` and "Viewport Height" to ``720``. You can see the +"Project" menu on the upper left corner. .. image:: img/setting-project-width-and-height.webp @@ -51,7 +52,7 @@ This ensures that the game scales consistently on different sized screens. .. image:: img/setting-stretch-mode.webp Organizing the project -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- In this project, we will make 3 independent scenes: ``Player``, ``Mob``, and ``HUD``, which we will combine into the game's ``Main`` scene. diff --git a/getting_started/first_2d_game/02.player_scene.rst b/getting_started/first_2d_game/02.player_scene.rst index adad2005486..eb979810af6 100644 --- a/getting_started/first_2d_game/02.player_scene.rst +++ b/getting_started/first_2d_game/02.player_scene.rst @@ -11,24 +11,24 @@ creating a separate Player scene is that we can test it separately, even before we've created other parts of the game. Node structure -~~~~~~~~~~~~~~ +-------------- To begin, we need to choose a root node for the player object. As a general rule, a scene's root node should reflect the object's desired functionality - -what the object *is*. Click the "Other Node" button and add an :ref:`Area2D -` node to the scene. +what the object *is*. In the upper-left corner, in the "Scene" tab, click the +"Other Node" button and add an :ref:`Area2D ` node to the scene. .. image:: img/add_node.webp -When you add the ``Area2D`` node, Godot will display the following **warning icon** +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. +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. @@ -44,8 +44,8 @@ node is clicked in 2D and 3D view." .. image:: img/lock_children.webp -Save the scene. Click Scene -> Save, or press :kbd:`Ctrl + S` on Windows/Linux -or :kbd:`Cmd + S` on macOS. +Save the scene as ``player.tscn``. Click **Scene > Save**, or press :kbd:`Ctrl + S` +on Windows/Linux or :kbd:`Cmd + S` on macOS. .. note:: For this project, we will be following the Godot naming conventions. @@ -60,7 +60,7 @@ or :kbd:`Cmd + S` on macOS. Sprite animation -~~~~~~~~~~~~~~~~ +---------------- Click on the ``Player`` node and add (:kbd:`Ctrl + A` on Windows/Linux or :kbd:`Cmd + A` on macOS) a child node :ref:`AnimatedSprite2D @@ -68,8 +68,8 @@ Click on the ``Player`` node and add (:kbd:`Ctrl + A` on Windows/Linux or appearance and animations for our player. Notice that there is a warning symbol next to the node. An ``AnimatedSprite2D`` requires a :ref:`SpriteFrames ` resource, which is a list of the animations it can -display. To create one, find the ``Sprite Frames`` property under the ``Animation`` tab in the Inspector and click -"[empty]" -> "New SpriteFrames": +display. Make sure ``AnimatedSprite2D`` is selected and then find the ``Sprite Frames`` property under +the ``Animation`` section in the Inspector and click "[empty]" -> "New SpriteFrames": .. image:: img/new_spriteframes.webp @@ -110,7 +110,7 @@ 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 +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. diff --git a/getting_started/first_2d_game/03.coding_the_player.rst b/getting_started/first_2d_game/03.coding_the_player.rst index 1b88aa4be82..8f461308234 100644 --- a/getting_started/first_2d_game/03.coding_the_player.rst +++ b/getting_started/first_2d_game/03.coding_the_player.rst @@ -260,7 +260,7 @@ the player around the screen in all directions. the name you see in the scene tree. Choosing animations -~~~~~~~~~~~~~~~~~~~ +------------------- Now that the player can move, we need to change which animation the AnimatedSprite2D is playing based on its direction. We have the "walk" animation, @@ -341,7 +341,7 @@ When you're sure the movement is working correctly, add this line to Hide(); Preparing for collisions -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ We want ``Player`` to detect when it's hit by an enemy, but we haven't made any enemies yet! That's OK, because we're going to use Godot's *signal* diff --git a/getting_started/first_2d_game/04.creating_the_enemy.rst b/getting_started/first_2d_game/04.creating_the_enemy.rst index 72355e85d34..859879da7ec 100644 --- a/getting_started/first_2d_game/04.creating_the_enemy.rst +++ b/getting_started/first_2d_game/04.creating_the_enemy.rst @@ -11,7 +11,7 @@ We'll create a ``Mob`` scene, which we can then *instance* to create any number of independent mobs in the game. Node setup -~~~~~~~~~~ +---------- Click Scene -> New Scene from the top menu and add the following nodes: @@ -60,7 +60,7 @@ to ``90`` (under "Transform" in the Inspector). Save the scene. Enemy script -~~~~~~~~~~~~ +------------ Add a script to the ``Mob`` like this: diff --git a/getting_started/first_2d_game/05.the_main_game_scene.rst b/getting_started/first_2d_game/05.the_main_game_scene.rst index ae4f2e775ee..ff4c922b2ab 100644 --- a/getting_started/first_2d_game/05.the_main_game_scene.rst +++ b/getting_started/first_2d_game/05.the_main_game_scene.rst @@ -35,7 +35,7 @@ In addition, set the ``One Shot`` property of ``StartTimer`` to "On" and set ``Position`` of the ``StartPosition`` node to ``(240, 450)``. Spawning mobs -~~~~~~~~~~~~~ +------------- The Main node will be spawning new mobs, and we want them to appear at a random location on the edge of the screen. Add a :ref:`Path2D ` node @@ -70,7 +70,7 @@ Your scene should look like this: .. image:: img/main_scene_nodes.webp Main script -~~~~~~~~~~~ +----------- Add a script to ``Main``. At the top of the script, we use ``@export var mob_scene: PackedScene`` to allow us to choose the Mob scene we want @@ -257,7 +257,7 @@ Note that a new instance must be added to the scene using ``add_child()``. convert between the two. Testing the scene -~~~~~~~~~~~~~~~~~ +----------------- Let's test the scene to make sure everything is working. Add this ``new_game`` call to ``_ready()``: diff --git a/getting_started/first_2d_game/06.heads_up_display.rst b/getting_started/first_2d_game/06.heads_up_display.rst index 78556702250..97775cbcbb4 100644 --- a/getting_started/first_2d_game/06.heads_up_display.rst +++ b/getting_started/first_2d_game/06.heads_up_display.rst @@ -56,14 +56,14 @@ use "Anchor Presets". .. image:: img/ui_anchor.webp ScoreLabel -~~~~~~~~~~ +---------- 1. Add the text ``0``. 2. Set the "Horizontal Alignment" and "Vertical Alignment" to ``Center``. 3. Choose the "Anchor Preset" ``Center Top``. Message -~~~~~~~~~~~~ +------- 1. Add the text ``Dodge the Creeps!``. 2. Set the "Horizontal Alignment" and "Vertical Alignment" to ``Center``. @@ -72,7 +72,7 @@ Message 5. Choose the "Anchor Preset" ``Center``. StartButton -~~~~~~~~~~~ +----------- 1. Add the text ``Start``. 2. Under "Control - Layout/Transform", set "Size X" to ``200`` and "Size Y" to ``100`` @@ -213,7 +213,7 @@ signal of ``MessageTimer`` to the ``HUD`` node, and add the following code to th } Connecting HUD to Main -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- Now that we're done creating the ``HUD`` scene, go back to ``Main``. Instance the ``HUD`` scene in ``Main`` like you did the ``Player`` scene. The scene tree @@ -276,7 +276,7 @@ with the changing score: Now you're ready to play! Click the "Play the Project" button. Removing old creeps -~~~~~~~~~~~~~~~~~~~ +------------------- If you play until "Game Over" and then start a new game right away, the creeps from the previous game may still be on the screen. It would be better if they diff --git a/getting_started/first_2d_game/07.finishing-up.rst b/getting_started/first_2d_game/07.finishing-up.rst index 4fb29d4f776..19e2757b685 100644 --- a/getting_started/first_2d_game/07.finishing-up.rst +++ b/getting_started/first_2d_game/07.finishing-up.rst @@ -9,7 +9,7 @@ remaining steps to add a bit more "juice" to improve the game experience. Feel free to expand the gameplay with your own ideas. Background -~~~~~~~~~~ +---------- The default gray background is not very appealing, so let's change its color. One way to do this is to use a :ref:`ColorRect ` node. Make it @@ -21,7 +21,7 @@ You could also add a background image, if you have one, by using a :ref:`TextureRect ` node instead. Sound effects -~~~~~~~~~~~~~ +------------- Sound and music can be the single most effective way to add appeal to the game experience. In your game's **art** folder, you have two sound files: "House In a @@ -73,7 +73,7 @@ Finally, add ``$DeathSound.play()`` in the ``game_over()`` function. Keyboard shortcut -~~~~~~~~~~~~~~~~~ +----------------- Since the game is played with keyboard controls, it would be convenient if we could also start the game by pressing a key on the keyboard. We can do this with @@ -123,7 +123,7 @@ And when you're ready, you can move on to :ref:`doc_your_first_3d_game` to learn to create a complete 3D game from scratch, in Godot. Sharing the finished game with others -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------- If you want people to try out your game without having to install Godot, you'll need to export the project for each operating system you want the game to be diff --git a/getting_started/step_by_step/instancing.rst b/getting_started/step_by_step/instancing.rst index f766a32155e..0c3f828b078 100644 --- a/getting_started/step_by_step/instancing.rst +++ b/getting_started/step_by_step/instancing.rst @@ -186,7 +186,7 @@ For example, you could break down a shooter game like so: You can come up with a diagram like this for almost any type of game. Each rectangle represents an entity that's visible in the game from the player's -perspective. The arrows tell you which scene owns which. +perspective. The arrows point towards the insantiator of each scene. Once you have a diagram, we recommend creating a scene for each element listed in it to develop your game. You'll use instancing, either by code or directly in diff --git a/migrate.py b/migrate.py index 805bae087ce..a05843f87c2 100644 --- a/migrate.py +++ b/migrate.py @@ -39,7 +39,6 @@ import shutil import sys import codecs -from distutils.dir_util import copy_tree defaultInputDirectory = '.' defaultOutputDirectory = '_migrated' diff --git a/requirements.txt b/requirements.txt index 5c668ceef18..cc8a9fed83c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,7 +3,7 @@ # https://github.com/readthedocs/readthedocs.org/blob/master/requirements/docs.txt # Base dependencies -pygments==2.18.0 +pygments==2.19.1 # Sphinx base and RTD theme. sphinx==8.1.3 @@ -21,4 +21,4 @@ sphinx-notfound-page==1.0.4 sphinxext-opengraph==0.9.1 # `.. video::` directive support to embed videos in documentation pages. -sphinxcontrib-video==0.3.1 +sphinxcontrib-video==0.3.2 diff --git a/tutorials/2d/2d_lights_and_shadows.rst b/tutorials/2d/2d_lights_and_shadows.rst index 848c00d8c4a..a5d01409412 100644 --- a/tutorials/2d/2d_lights_and_shadows.rst +++ b/tutorials/2d/2d_lights_and_shadows.rst @@ -200,7 +200,7 @@ LightOccluder2D nodes have 2 properties: There are two ways to create light occluders: Automatically generating a light occluder -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Occluders can be created automatically from Sprite2D nodes by selecting the node, clicking the **Sprite2D** menu at the top of the 2D editor then choosing @@ -213,7 +213,7 @@ edges), adjust **Grow (pixels)** and **Shrink (pixels)**, then click **Update Preview**. Repeat this operation until you get satisfactory results. Manually drawing a light occluder -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a LightOccluder2D node, then select the node and click the "+" button at the top of the 2D editor. When asked to create a polygon resource, answer @@ -256,7 +256,7 @@ The following properties can be adjusted on 2D lights that have shadows enabled: Soft shadows with streaking artifacts due to Filter Smooth being too high (PCF5, Filter Smooth 4) Occluder draw order -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ **LightOccluder2Ds follows the usual 2D drawing order.** This is important for 2D lighting, as this is how you control whether the occluder should occlude the diff --git a/tutorials/2d/custom_drawing_in_2d.rst b/tutorials/2d/custom_drawing_in_2d.rst index 466ad8a26ff..ea831ad5e6b 100644 --- a/tutorials/2d/custom_drawing_in_2d.rst +++ b/tutorials/2d/custom_drawing_in_2d.rst @@ -259,7 +259,7 @@ You will have to code a function to perform this and draw it yourself. to adjust the project to a higher resolution (a 2 or 4 scale tends to work well). Drawing a custom polygon shape -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While there is a dedicated node to draw custom polygons ( :ref:`Polygon2D `), we will use in this case exclusively lower @@ -377,7 +377,7 @@ like this: // We are going to paint with this color. Color godotBlue = new Color("478cbf"); // We pass the array of Vector2 to draw the shape. - DrawPolygon(_head, new Color[]{ godotBlue }); + DrawPolygon(_head, [godotBlue]); } When running it you should see something like this: @@ -394,7 +394,7 @@ Polygons will always **connect its last defined point to its first one** in order to have a closed shape. Drawing connected lines -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ Drawing a sequence of connected lines that don't close down to form a polygon is very similar to the previous method. We will use a connected set of lines to @@ -474,7 +474,7 @@ draw the line, like this: Color white = Colors.White; Color godotBlue = new Color("478cbf"); - DrawPolygon(_head, new Color[]{ godotBlue }); + DrawPolygon(_head, [godotBlue]); // We draw the while line on top of the previous shape. DrawPolyline(_mouth, white, _mouthWidth); @@ -499,7 +499,7 @@ code or a predefined color name. Check the class :ref:`Color ` for constants and ways to define Colors. Drawing circles -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ To create the eyes, we are going to add 4 additional calls to draw the eye shapes, in different sizes, colors and positions. @@ -535,7 +535,7 @@ its radius, and the third is its color: Color godotBlue = new Color("478cbf"); Color grey = new Color("414042"); - DrawPolygon(_head, new Color[]{ godotBlue }); + DrawPolygon(_head, [godotBlue]); DrawPolyline(_mouth, white, _mouthWidth); // Four circles for the 2 eyes: 2 white, 2 grey. @@ -555,7 +555,7 @@ arbitrary angles), you can use the method :ref:`draw_arc `. Drawing lines -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ To draw the final shape (the nose) we will use a line to approximate it. @@ -589,7 +589,7 @@ like this: Color godotBlue = new Color("478cbf"); Color grey = new Color("414042"); - DrawPolygon(_head, new Color[]{ godotBlue }); + DrawPolygon(_head, [godotBlue]); DrawPolyline(_mouth, white, _mouthWidth); DrawCircle(new Vector2(42.479f, 65.4825f), 9.3905f, white); DrawCircle(new Vector2(85.524f, 65.4825f), 9.3905f, white); @@ -610,7 +610,7 @@ you may get additional performance by drawing all of them in a single call, usin the :ref:`draw_multiline ` method. 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 @@ -652,7 +652,7 @@ to do it, like this: Color godotBlue = new Color("478cbf"); Color grey = new Color("414042"); - DrawPolygon(_head, new Color[]{ godotBlue }); + DrawPolygon(_head, [godotBlue]); DrawPolyline(_mouth, white, _mouthWidth); DrawCircle(new Vector2(42.479f, 65.4825f), 9.3905f, white); DrawCircle(new Vector2(85.524f, 65.4825f), 9.3905f, white); @@ -680,7 +680,7 @@ can be found on the :ref:`CanvasItem ` class reference. .. _doc_draw_show_drawing_while_editing_example: Show the drawing while editing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While the code so far is able to draw the logo on a running window, it will not show up on the ``2D view`` on the editor. In certain cases you would @@ -710,7 +710,7 @@ to refresh the current node in the ``2D`` view the first time you add or remove the ``@tool`` annotation. Animation -^^^^^^^^^ +~~~~~~~~~ If we wanted to make the custom shape change at runtime, we could modify the methods called or its arguments at execution time, or apply a transform. @@ -870,7 +870,7 @@ will see how to draw a dynamic line whose coordinates are not known beforehand, and are affected by the user's input. Drawing a straight line between 2 points -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Let's assume we want to draw a straight line between 2 points, the first one will be fixed on the upper left corner ``(0, 0)`` and the second will be defined @@ -943,7 +943,7 @@ It should look like this when run: .. image:: img/draw_line_between_2_points.webp Drawing an arc between 2 points -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The above example works, but we may want to join those 2 points with a different shape or function, other than a straight line. diff --git a/tutorials/2d/introduction_to_2d.rst b/tutorials/2d/introduction_to_2d.rst index 1a73f2197d4..c5a4d33aa1b 100644 --- a/tutorials/2d/introduction_to_2d.rst +++ b/tutorials/2d/introduction_to_2d.rst @@ -20,7 +20,7 @@ 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. @@ -47,7 +47,7 @@ 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. @@ -182,7 +182,7 @@ 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. @@ -206,7 +206,7 @@ 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: @@ -298,7 +298,7 @@ Viewport has a **View** menu which provides several options to change the look o 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 diff --git a/tutorials/2d/using_tilemaps.rst b/tutorials/2d/using_tilemaps.rst index 06f4eac2fea..c5fa6cdcf20 100644 --- a/tutorials/2d/using_tilemaps.rst +++ b/tutorials/2d/using_tilemaps.rst @@ -55,7 +55,7 @@ Each TileMapLayer node has several properties you can adjust: - **TileSet** The tileset used by the TileMapLayer node. Rendering -^^^^^^^^^ +~~~~~~~~~ - **Y Sort Origin:** The vertical offset to use for Y-sorting on each tile (in pixels). Only effective if **Y Sort Enabled** under CanvasItem settings is ``true``. @@ -67,7 +67,7 @@ Rendering TileMapLayer since tiles are grouped by Y position in that case. Physics -^^^^^^^ +~~~~~~~ - **Collision Enabled** Enables or disables collision. - **Use Kinematic Bodies** When true TileMapLayer collision shapes will be instantiated as kinematic bodies. @@ -75,7 +75,7 @@ Physics visible. If set to default, then it depends on the show collision debug settings. Navigation -^^^^^^^^^^ +~~~~~~~~~~ - **Navigation Enabled** Whether or not navigation regions are enabled. - **Navigation Visible** Whether or not the TileMapLayer's navigation meshes are @@ -91,7 +91,7 @@ Navigation 2D navigation meshes can not be "layered" or stacked on top of each other like visuals or physic shapes. Attempting to stack navigation meshes on the same navigation map will result in merge and logical errors that break the pathfinding. Reordering layers -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ You can reorder layers by drag-and-dropping their node in the Scene tab. You can also switch between which TileMapLayer node you're working on by using the buttons @@ -195,7 +195,7 @@ the 2D editor, **not** the TileMap panel itself. From left to right, the painting modes and tools you can choose are: Selection -^^^^^^^^^ +~~~~~~~~~ Select tiles by clicking a single tile, or by holding down the left mouse button to select multiple with a rectangle in the 2D editor. Note that empty space cannot be @@ -221,7 +221,7 @@ then performing a selection. Right-click or press :kbd:`Escape` to cancel pasting. Paint -^^^^^ +~~~~~ The standard Paint mode allows you to place tiles by clicking or holding down the left mouse button. @@ -250,7 +250,7 @@ the left mouse button. This is identical to using the Picker tool described below. Line -^^^^ +~~~~ After selecting Line Paint mode, you can draw in a line that is always 1 tile thick (no matter its orientation). @@ -270,7 +270,7 @@ You can toggle this mode temporarily while in Paint or Eraser mode by holding Using the line tool after selecting two tiles to draw platforms diagonally Rectangle -^^^^^^^^^ +~~~~~~~~~ After selecting Rectangle Paint mode, you can draw in an axis-aligned rectangle. @@ -285,7 +285,7 @@ You can toggle this mode temporarily while in Paint or Eraser mode by holding :kbd:`Ctrl` and :kbd:`Shift` then drawing. Bucket Fill -^^^^^^^^^^^ +~~~~~~~~~~~ After selecting Bucket Fill mode, you can choose whether painting should be limited to contiguous areas only by toggling the **Contiguous** checkbox that @@ -313,7 +313,7 @@ you can place them in a repeating pattern within the filled area. Using the Bucket Fill tool Picker -^^^^^^ +~~~~~~ After selecting Picker mode, you can pick existing tiles in the 2D editor by holding :kbd:`Ctrl` then clicking on a tile. This will switch the currently @@ -325,7 +325,7 @@ You can toggle this mode temporarily while in Paint mode by holding :kbd:`Ctrl` then clicking or dragging the mouse. Eraser -^^^^^^ +~~~~~~ This mode is combined with any other painting mode (Paint, Line, Rectangle, Bucket Fill). When eraser mode is enabled, tiles will be replaced by empty tiles diff --git a/tutorials/2d/using_tilesets.rst b/tutorials/2d/using_tilesets.rst index 054676916c8..6ad3f302722 100644 --- a/tutorials/2d/using_tilesets.rst +++ b/tutorials/2d/using_tilesets.rst @@ -31,7 +31,7 @@ Creating a new TileSet .. _doc_creating_tilesets_using_tilesheet: Using a tilesheet -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ This demonstration will use the following tiles taken from `Kenney's "Abstract Platformer" pack `__. @@ -155,7 +155,7 @@ three vertical dots menu button at the top of the TileSet editor and choose Recreating tiles automatically after changing atlas properties Using a collection of scenes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since Godot 4.0, you can place actual *scenes* as tiles. This allows you to use any collection of nodes as a tile. For example, you could use scene tiles to @@ -522,7 +522,7 @@ There are two ways to assign properties to multiple tiles at once. Depending on your use cases, one method may be faster than the other: Using multiple tile selection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you wish to configure various properties on several tiles at once, choose the **Select** mode at the top of the TileSet editor: @@ -550,7 +550,7 @@ property's value on all tiles in the atlas after editing a property: .. _doc_using_tilemaps_using_tile_property_painting: Using tile property painting -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you wish to apply a single property to several tiles at once, you can use the *property painting* mode for this purpose. diff --git a/tutorials/3d/3d_text.rst b/tutorials/3d/3d_text.rst index 99e8902d3cd..2782da496b8 100644 --- a/tutorials/3d/3d_text.rst +++ b/tutorials/3d/3d_text.rst @@ -36,7 +36,7 @@ remains customizable and uses the same font subresource as Control nodes rendering). Advantages -^^^^^^^^^^ +~~~~~~~~~~ - Label3D is faster to generate than TextMesh. While both use a caching mechanism to only render new glyphs once, Label3D will still be faster to @@ -52,7 +52,7 @@ Advantages See :ref:`doc_gui_using_fonts` for guidelines on configuring font imports. Limitations -^^^^^^^^^^^ +~~~~~~~~~~~ By default, Label3D has limited interaction with a 3D environment. It can be occluded by geometry and lit by light sources if the **Shaded** flag is enabled. @@ -94,7 +94,7 @@ the texture below as a reference for the generated mesh's UV map: .. image:: img/text_mesh_textured.png Advantages -^^^^^^^^^^ +~~~~~~~~~~ TextMesh has a few advantages over Label3D: @@ -103,7 +103,7 @@ TextMesh has a few advantages over Label3D: - TextMesh can use custom shaders, unlike Label3D. Limitations -^^^^^^^^^^^ +~~~~~~~~~~~ There are some limitations to TextMesh: @@ -133,7 +133,7 @@ See the `3D waypoints ` node extrude along a Polygon drawn Custom meshes ~~~~~~~~~~~~~ -Any mesh can be used for :ref:`CSGMesh3D `; the mesh can be -modeled in other software and imported into Godot. Multiple materials are -supported. There are some restrictions for geometry: - -- it must be closed, -- it must not self-intersect, -- it must not contain internal faces, -- every edge must connect to only two other faces. +Custom meshes can be used for :ref:`CSGMesh3D ` as long as the +mesh is *manifold*. The mesh can be modeled in other software and imported into +Godot. Multiple materials are supported. + +For a mesh to be used as a CSG mesh, it is required to: + +- be closed +- have each edge connect to only two faces +- have volume + +And it is recommended to avoid: + +- negative volume +- self-intersection +- interior faces + +Godot uses the `manifold `__ library to +implement CSG meshes. The technical definition of "manifold" used by Godot is +the following, adapted from that library's `definition of "manifold" +`__: + + Every edge of every triangle must contain the same two vertices (by index) as + exactly one other triangle edge, and the start and end vertices must switch + places between these two edges. The triangle vertices must appear in clockwise + order when viewed from the outside of the Godot Engine manifold mesh. .. image:: img/csg_custom_mesh.png diff --git a/tutorials/3d/environment_and_post_processing.rst b/tutorials/3d/environment_and_post_processing.rst index c48a2a3b4f6..d044b301d79 100644 --- a/tutorials/3d/environment_and_post_processing.rst +++ b/tutorials/3d/environment_and_post_processing.rst @@ -26,7 +26,7 @@ but you can enable it by using it in one of the following locations, in order of priority: Camera3D node (high priority) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An Environment can be set to a Camera3D node. It will have priority over any other setting. @@ -37,7 +37,7 @@ This is mostly useful when you want to override an existing environment, but in general it's a better idea to use the option below. WorldEnvironment node (medium priority, recommended) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The WorldEnvironment node can be added to any scene, but only one can exist per active scene tree. Adding more than one will result in a warning. @@ -49,7 +49,7 @@ Any Environment added has higher priority than the default Environment which makes it quite useful. Preview environment and sun (low priority) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -130,7 +130,7 @@ The following is a detailed description of all environment options and how they are intended to be used. Background -^^^^^^^^^^ +~~~~~~~~~~ The Background section contains settings on how to fill the background (parts of the screen where objects were not drawn). The background not only serves the @@ -160,7 +160,7 @@ There are several background modes available: "hall of mirrors" visual glitch if the sky is visible at any time. Sky materials -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ When using the **Sky** background mode (or the ambient/reflected light mode is set to **Sky**), a Sky subresource becomes available to edit in the Environment @@ -201,7 +201,7 @@ If you need a custom sky material (e.g. for procedural clouds), you can create a custom :ref:`sky shader `. Ambient light -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ Ambient light (as defined here) is a type of light that affects every piece of geometry with the same intensity. It is global and independent of lights that @@ -255,7 +255,7 @@ Using one of the methods described above will replace constant ambient lighting with ambient lighting from the probes. Reflected light -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ Reflected light (also called specular light) is the other of the two components of image-based lighting. @@ -271,7 +271,7 @@ Reflected light can be set to one of 3 modes: behaves identically to **Background**. Fog -^^^ +~~~ .. note:: @@ -308,7 +308,7 @@ In practice, it makes light stand out more across the fog. for guidance on reducing banding. Volumetric Fog -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ Volumetric fog provides a realistic fog effect to the scene, with fog color being affected by the lights that traverse the fog. @@ -318,7 +318,7 @@ being affected by the lights that traverse the fog. See :ref:`doc_volumetric_fog` for documentation on setting up volumetric fog. Tonemap -^^^^^^^ +~~~~~~~ Tonemap selects the tonemapping curve that will be applied to the scene, from a list of standard curves used in the film and game industries. Tonemapping operators @@ -369,7 +369,7 @@ The Environment resource supports many popular mid- and post-processing effects. distracting changes during gameplay. Screen-Space Reflections (SSR) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* @@ -411,7 +411,7 @@ This also applies to shaders that use ``hint_screen_texture`` or ``hint_depth_te uniforms. Screen-Space Ambient Occlusion (SSAO) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* @@ -485,7 +485,7 @@ parameters: .. _doc_environment_and_post_processing_ssil: Screen-Space Indirect Lighting (SSIL) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* @@ -531,7 +531,7 @@ Tweaking :abbr:`SSIL (Screen-Space Indirect Lighting)` is possible with several .. image:: img/environment_ssil.webp Signed Distance Field Global Illumination (SDFGI) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* @@ -550,7 +550,7 @@ illumination for off-screen elements (unlike :abbr:`SSIL (Screen-Space Indirect .. _doc_environment_and_post_processing_glow: Glow -^^^^ +~~~~ .. note:: @@ -641,7 +641,7 @@ There are 2 main use cases for a glow map texture: .. _doc_environment_and_post_processing_using_glow_in_2d: Using glow in 2D -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ There are 2 ways to use glow in 2D: @@ -689,7 +689,7 @@ There are 2 ways to use glow in 2D: .. _doc_environment_and_post_processing_using_glow_to_blur_the_screen: Using glow to blur the screen -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Glow can be used to blur the whole viewport, which is useful for background blur when a menu is open. Only 3D rendering will be affected unless the environment's @@ -715,7 +715,7 @@ To use glow as a blurring solution: Example of using glow to blur the 2D rendering in the menu's background Adjustments -^^^^^^^^^^^ +~~~~~~~~~~~ At the end of processing, Godot offers the possibility to do some standard image adjustments. @@ -797,7 +797,7 @@ Camera attribute options ------------------------ Depth of Field / Far Blur -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ This effect simulates focal distance on cameras. It blurs objects behind a given range. It has an initial **Distance** with a **Transition** region @@ -810,7 +810,7 @@ the depth of field quality in the advanced project settings may be needed to avoid artifacts. Depth of Field / Near Blur -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ This effect simulates focal distance on cameras. It blurs objects close to the camera (acts in the opposite direction as far blur). @@ -834,13 +834,13 @@ given object, or create a so-called distance, focal length, and aperture. Exposure -^^^^^^^^ +~~~~~~~~ This multiplies the overall scene brightness visible from the camera. Higher values result in a visually brighter scene. Auto Exposure -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ *This feature is only available when using the Forward+ renderer, not Mobile or Compatibility.* diff --git a/tutorials/3d/global_illumination/img/lightmap_gi_shadowmask.webp b/tutorials/3d/global_illumination/img/lightmap_gi_shadowmask.webp new file mode 100644 index 00000000000..82f5cac947f Binary files /dev/null and b/tutorials/3d/global_illumination/img/lightmap_gi_shadowmask.webp differ diff --git a/tutorials/3d/global_illumination/introduction_to_global_illumination.rst b/tutorials/3d/global_illumination/introduction_to_global_illumination.rst index d5b3b0b139f..0e0c0d9e611 100644 --- a/tutorials/3d/global_illumination/introduction_to_global_illumination.rst +++ b/tutorials/3d/global_illumination/introduction_to_global_illumination.rst @@ -24,7 +24,7 @@ being reflected back onto the rest of the scene. Global illumination is composed of several key concepts: Indirect diffuse lighting -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ This is the lighting that does not change depending on the camera's angle. There are two main sources of indirect diffuse lighting: @@ -64,7 +64,7 @@ it when targeting low-end hardware. limitations documentation for ways to reduce this effect. Specular lighting -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ Specular lighting is also referred to as *reflections*. This is the lighting that changes in intensity depending on the camera's angle. @@ -112,7 +112,7 @@ there are several criteria to keep in mind: Here's a comparison of all the global illumination techniques available in Godot: Performance -^^^^^^^^^^^ +~~~~~~~~~~~ In order of performance from fastest to slowest: @@ -158,7 +158,7 @@ In order of performance from fastest to slowest: **Not available** *when using the Mobile or Compatibility renderers.* Visuals -^^^^^^^ +~~~~~~~ For comparison, here's a 3D scene with no global illumination options used: @@ -242,7 +242,7 @@ Here's how Godot's various global illumination techniques compare: ReflectionProbe in action (without any other GI technique). Notice the reflective sphere. Real-time ability -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ - **VoxelGI:** |good| Fully real-time. @@ -290,7 +290,7 @@ Real-time ability This makes ReflectionProbes viable for procedurally generated levels. User work needed -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ - **VoxelGI:** One or more VoxelGI nodes need to be created and baked. @@ -325,7 +325,7 @@ User work needed .. |bad| image:: img/score_bad.webp Summary -^^^^^^^ +~~~~~~~ If you are unsure about which GI technique to use: @@ -349,7 +349,7 @@ If you are unsure about which GI technique to use: .. _doc_introduction_to_global_illumination_gi_mode_recommendations: Which global illumination mode should I use on meshes and lights? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Regardless of which global illumination technique you use, there is no universally "better" global illumination mode. Still, here are some diff --git a/tutorials/3d/global_illumination/using_lightmap_gi.rst b/tutorials/3d/global_illumination/using_lightmap_gi.rst index 68a4c004106..9a24f166b56 100644 --- a/tutorials/3d/global_illumination/using_lightmap_gi.rst +++ b/tutorials/3d/global_illumination/using_lightmap_gi.rst @@ -95,7 +95,7 @@ not share pixels in the texture. There are a few ways to ensure your object has a unique UV2 layer and texture size: Unwrap on scene import (recommended) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In most scenarios, this is the best approach to use. The only downside is that, on large models, unwrapping can take a while on import. Nonetheless, Godot will @@ -137,7 +137,7 @@ their UV2 maps properly generated. and engine versions. Unwrap from within Godot -^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~ .. warning:: @@ -154,7 +154,7 @@ This will generate a second set of UV2 coordinates which can be used for baking. It will also set the texture size automatically. Unwrap from your 3D modeling software -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The last option is to do it from your favorite 3D app. This approach is generally **not recommended**, but it's explained so that you know it exists. @@ -177,7 +177,7 @@ to work quickly. You will mostly need to use seams or other techniques to create better unwrapping. Generating UV2 for primitive meshes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -203,7 +203,7 @@ lightmap texture, which varies depending on the mesh's size properties and the 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 `. @@ -222,7 +222,7 @@ This can be used to bake lightmaps on a CSG node by following these steps: again. Checking UV2 -^^^^^^^^^^^^ +~~~~~~~~~~~~ In the **Mesh** menu mentioned before, the UV2 texture coordinates can be visualized. If something is failing, double-check that the meshes have these UV2 coordinates: @@ -244,7 +244,7 @@ inconsistent lightmap texel scaling, make sure to respect the rule about mesh scaling mentioned before. Setting up meshes -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ For a **MeshInstance3D** node to take part in the baking process, it needs to have its bake mode set to **Static**. Meshes that have their bake mode set to **Disabled** @@ -255,7 +255,7 @@ or **Dynamic** will be ignored by the lightmapper. When auto-generating lightmaps on scene import, this is enabled automatically. Setting up lights -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ Lights are baked with indirect light only by default. This means that shadowmapping and lighting are still dynamic and affect moving objects, but light bounces from @@ -269,7 +269,7 @@ can be controlled from the **Bake Mode** menu in lights: The modes are: Disabled -^^^^^^^^ +~~~~~~~~ The light is ignored when baking lightmaps. This is the mode to use for dynamic lighting effects such as explosions and weapon effects. @@ -281,7 +281,7 @@ lighting effects such as explosions and weapon effects. disabling its **Visible** property. Dynamic -^^^^^^^ +~~~~~~~ This is the default mode, and is a compromise between performance and real-time friendliness. Only indirect lighting will be baked. Direct light and shadows are @@ -291,8 +291,13 @@ This mode allows performing *subtle* changes to a light's color, energy and position while still looking fairly correct. For example, you can use this to create flickering static torches that have their indirect light baked. +Depending on the value of **Shadowmask Mode**, it is possible to still get +distant baked shadows for DirectionalLight3D. This allows shadows up close to be +real-time and show dynamic objects, while allowing static objects in the +distance to still cast shadows. + Static -^^^^^^ +~~~~~~ Both indirect and direct lighting will be baked. Since static surfaces can skip lighting and shadow computations entirely, this mode provides the best @@ -343,7 +348,7 @@ method and quality selected. set to a high enough value. Tweaks -^^^^^^ +~~~~~~ - **Quality:** Four bake quality modes are provided: Low, Medium, High, and Ultra. Higher quality takes more time, but result in a better-looking lightmap @@ -364,6 +369,12 @@ Tweaks especially with fully baked lights (since they also have direct light baked). The downside is that directional lightmaps are slightly more expensive to render. They also require more time to bake and result in larger file sizes. +- **Shadowmask Mode:** If set to a mode other than **None**, the first DirectionalLight3D + in the scene with the **Dynamic** global illumination mode will have its static shadows + baked to a separate texture called a *shadowmask*. This can be used to allow distant + static objects to cast shadows onto other static objects regardless of the distance + from the camera. See the :ref:`section on shadowmasking ` + for further details. - **Interior:** If enabled, environment lighting will not be sourced. Use this for purely indoor scenes to avoid light leaks. - **Use Texture for Bounces:** If enabled, a texture with the lighting @@ -397,6 +408,74 @@ Tweaks - **Gen Probes > Subdiv:** See :ref:`doc_using_lightmap_gi_dynamic_objects`. - **Data > Light Data:** See :ref:`doc_using_lightmap_gi_data`. +.. _doc_using_lightmap_gi_shadowmask: + +Using shadowmasking for distant directional shadows +--------------------------------------------------- + +When using a DirectionalLight3D, the maximum distance at which it can draw +real-time shadows is limited by its **Shadow Max Distance** property. This can +be an issue in large scenes, as distant objects won't appear to have any shadows +from the DirectionalLight3D. While this can be resolved by using the **Static** +global illumination mode on the DirectionalLight3D, this has several downsides: + +- Since both direct and indirect light are baked, there is no way for dynamic + objects to cast shadows onto static surfaces in a realistic manner. Godot skips + shadow sampling entirely in this case to avoid "double lighting" artifacts. +- Static shadows up close lack in detail, as they only rely on the lightmap texture + and not on real-time shadow cascades. + +We can avoid these downsides while still benefiting from distant shadows by +using *shadowmasking*. While dynamic objects won't receive shadows from the +shadowmask, it still greatly improves visuals since most scenes are primarily +comprised of static objects. + +Since the lightmap texture alone doesn't contain shadow information, we can bake +this shadow information to a separate texture called a *shadowmask*. + +Shadowmasking only affects the first DirectionalLight3D in the scene (determined +by tree order) that has the **Dynamic** global illumination mode. It is not +possible to use shadowmasking with the **Static** global illumination mode, as +this mode skips shadow sampling on static objects entirely. This is because the +Static global illumination mode bakes both direct and indirect light. + +Three shadowmasking modes are available: + +- **None (default):** Don't bake a shadowmask texture. Directional shadows will + not be visible outside the range specified by the DirectionalLight3D's + **Shadow Max Distance** property. +- **Replace:** Bakes a shadowmask texture, and uses it to draw directional + shadows when outside the range specified by the DirectionalLight3D's **Shadow + Max Distance** property. Shadows within this range remain fully real-time. + This option generally makes the most sense for most scenes, as it can deal + well with static objects that exhibit subtle motion (e.g. foliage shadows). +- **Overlay:** Bakes a shadowmask texture, and uses it to draw directional + shadows regardless of the distance from the camera. Shadows within the range + of the DirectionalLight3D's **Shadow Max Distance** property will be overlaid + with real-time shadows. This can make the transition between real-time and + baked shadows less jarring, at the cost of a "smearing" effect present on + static object shadows depending on lightmap texel density. Also, this mode + can't deal as well with static objects that exhibit subtle motion (such as + foliage), as the baked shadows can't be animated over time. Still, for scenes + where the camera moves quickly, this may be a better choice than **Replace**. + +Here's a visual comparison of the shadowmask modes with a scene where the +**Shadow Max Distance** was set very low for comparison purposes. The blue boxes +are dynamic objects, while the rest of the scene is a static object. There is +only a single DirectionalLight3D in the scene with the Dynamic global +illumination mode: + +.. figure:: img/lightmap_gi_shadowmask.webp + :align: center + :alt: Comparison between shadowmask modes + + Comparison between shadowmask modes + +.. note:: + + It is possible to switch between the **Replace** and **Overlay** shadowmask + modes without having to bake lightmaps again. + Balancing bake times with quality --------------------------------- @@ -433,7 +512,7 @@ noise and softens them while attempting to best preserve detail. Godot offers two denoising algorithms: JNLM (Non-Local Means with Joint Filtering) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JNLM is the default denoising method and is included in Godot. It uses a simple but efficient denoising algorithm known as *non-local means*. JNLM runs on the @@ -451,7 +530,7 @@ removing noise, at the cost of suppressing shadow detail for static shadows. Comparison between JNLM denoiser strength values. Higher values can reduce detail. OIDN (Open Image Denoise) -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ Unlike JNLM, OIDN uses a machine learning approach to denoising lightmaps. It features a model specifically trained to remove noise from lightmaps while diff --git a/tutorials/3d/img/spatial_material1.png b/tutorials/3d/img/spatial_material1.png deleted file mode 100644 index 678bd0d3304..00000000000 Binary files a/tutorials/3d/img/spatial_material1.png and /dev/null differ diff --git a/tutorials/3d/img/spatial_material1.webp b/tutorials/3d/img/spatial_material1.webp new file mode 100644 index 00000000000..cbd19f48b25 Binary files /dev/null and b/tutorials/3d/img/spatial_material1.webp differ diff --git a/tutorials/3d/img/spatial_material4.png b/tutorials/3d/img/spatial_material4.png deleted file mode 100644 index 1141fcfb5e5..00000000000 Binary files a/tutorials/3d/img/spatial_material4.png and /dev/null differ diff --git a/tutorials/3d/img/spatial_material4.webp b/tutorials/3d/img/spatial_material4.webp new file mode 100644 index 00000000000..f0ec827754a Binary files /dev/null and b/tutorials/3d/img/spatial_material4.webp differ diff --git a/tutorials/3d/img/spatial_material9.png b/tutorials/3d/img/spatial_material9.png deleted file mode 100644 index ff27d3aaffb..00000000000 Binary files a/tutorials/3d/img/spatial_material9.png and /dev/null differ diff --git a/tutorials/3d/img/spatial_material9.webp b/tutorials/3d/img/spatial_material9.webp new file mode 100644 index 00000000000..60c3d014a14 Binary files /dev/null and b/tutorials/3d/img/spatial_material9.webp differ diff --git a/tutorials/3d/introduction_to_3d.rst b/tutorials/3d/introduction_to_3d.rst index d32f8d620bc..5d81b660649 100644 --- a/tutorials/3d/introduction_to_3d.rst +++ b/tutorials/3d/introduction_to_3d.rst @@ -24,7 +24,7 @@ relevant math written for game developers, not mathemeticians or engineers, check out :ref:`doc_vector_math` and :ref:`doc_using_transforms`. 3D workspace -~~~~~~~~~~~~ +------------ Editing 3D scenes is done in the 3D workspace. This workspace can be selected manually, but it will be automatically selected when a Node3D node is @@ -40,7 +40,7 @@ Below the scene selector, the main toolbar is visible, and beneath the main tool is the 3D viewport. Main toolbar ------------- +~~~~~~~~~~~~ Some buttons in the main toolbar are the same as those in the 2D workspace. A brief explanation is given with the shortcut if the mouse cursor is hovered over a button for one second. @@ -125,7 +125,7 @@ MeshInstance3D is selected. This menu provides some quick actions or tools to work on a specific node or selection. View menu of viewport ---------------------- +~~~~~~~~~~~~~~~~~~~~~ Below the *Select* tool, in the 3D viewport, clicking on the three dots opens the **View menu** for the viewport. @@ -141,7 +141,7 @@ nodes within the viewport. .. _doc_introduction_to_3d_coordinate_system: Coordinate system ------------------ +~~~~~~~~~~~~~~~~~ Godot uses the `metric `__ system for everything in 3D, with 1 unit being equal to 1 meter. @@ -176,7 +176,7 @@ See this chart for comparison with other 3D software: .. _doc_introduction_to_3d_space_and_manipulation: Space and manipulation gizmos ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Moving, rotating, and scaling objects in the 3D view is done through the manipulator gizmos. @@ -202,7 +202,7 @@ If the transform mode is changed from *Select Mode* to *Scale Mode*, the arrows replaced by cubes, which can be dragged to scale an object as if the object is being moved. Navigating the 3D environment ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In 3D environments, it is often important to adjust the viewpoint or angle from which you are viewing the scene. @@ -251,7 +251,7 @@ In orthogonal mode, holding the right mouse button will pan the view instead. Use :kbd:`Keypad 5` to toggle between perspective and orthogonal view. Using Blender-style transform shortcuts ---------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since Godot 4.2, you can enable Blender-style shortcuts for translating, rotating and scaling nodes. In Blender, these shortcuts are: @@ -284,7 +284,7 @@ To use Blender-style transform shortcuts in Godot, go to the Editor Settings' :ref:`doc_default_key_mapping_shortcuts_spatial_editor` page. Node3D node -~~~~~~~~~~~ +----------- :ref:`Node2D ` is the base node for 2D. :ref:`Control ` is the base node for everything GUI. @@ -303,7 +303,7 @@ scale. .. image:: img/tuto_3d2.webp 3D content -~~~~~~~~~~ +---------- Unlike 2D, where loading image content and drawing is straightforward, 3D is a little more difficult. The content needs to be created with special 3D tools @@ -312,7 +312,7 @@ exchange file format to be imported in Godot. This is required since 3D formats are not as standardized as images. Manually authored models (using 3D modeling software) ------------------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. FIXME: Needs update to properly description Godot 3.x workflow (used to reference a non existing doc_importing_3d_meshes importer). @@ -325,7 +325,7 @@ as simple resources. .. seealso:: See :ref:`doc_importing_3d_scenes` for more on importing. Generated geometry ------------------- +~~~~~~~~~~~~~~~~~~ It is possible to create custom geometry by using the :ref:`ArrayMesh ` resource directly. Simply create your arrays @@ -343,7 +343,7 @@ submitting them to the 3D API has a significant performance cost. Immediate geometry ------------------- +~~~~~~~~~~~~~~~~~~ If, instead, you need to generate simple geometry that will be updated often, Godot provides a special :ref:`ImmediateMesh ` resource @@ -352,7 +352,7 @@ This provides an OpenGL 1.x-style immediate-mode API to create points, lines, triangles, etc. 2D in 3D --------- +~~~~~~~~ While Godot packs a powerful 2D engine, many types of games use 2D in a 3D environment. By using a fixed camera (either orthogonal or @@ -367,7 +367,7 @@ performance in comparison to plain 2D, as well as the lack of reference of working in pixels. Environment -~~~~~~~~~~~ +----------- Besides editing a scene, it is often common to edit the environment. Godot provides a :ref:`WorldEnvironment ` @@ -378,7 +378,7 @@ Environments can also be overridden in the Camera. .. _doc_introduction_to_3d_preview_environment_light: Preview environment and light ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, any 3D scene that doesn't have a :ref:`WorldEnvironment ` node, or a :ref:`DirectionalLight3D `, will have @@ -405,7 +405,7 @@ So only make adjustments that would apply to all of the scenes you will need a p light and environment for. Cameras -------- +~~~~~~~ No matter how many objects are placed in the 3D space, nothing will be displayed unless a :ref:`Camera3D ` is @@ -435,7 +435,7 @@ each viewport: tree-order will take its place. Lights ------- +~~~~~~ The background environment emits some ambient light which appears on surfaces. Still, without any light sources placed in the scene, the scene will appear diff --git a/tutorials/3d/lights_and_shadows.rst b/tutorials/3d/lights_and_shadows.rst index b7653a90299..1f291d57bb2 100644 --- a/tutorials/3d/lights_and_shadows.rst +++ b/tutorials/3d/lights_and_shadows.rst @@ -130,7 +130,7 @@ There is a list of generic shadow parameters, each also has a specific function: .. image:: img/lights_and_shadows_blur.webp Tweaking shadow bias -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ Below is an image of what tweaking bias looks like. Default values work for most cases, but in general, it depends on the size and complexity of geometry. @@ -201,7 +201,7 @@ recommendations in :ref:`doc_lights_and_shadows_pcss_recommendations` if setting this value above ``0.0`` on lights with shadows enabled. Directional shadow mapping -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ To compute shadow maps, the scene is rendered (only depth) from an orthogonal point of view that covers the whole scene (or up to the max distance). There is, @@ -290,7 +290,7 @@ expensive, so check the recommendations in .. image:: img/lights_and_shadows_pcss.webp Omni shadow mapping -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ Omni light shadow mapping is relatively straightforward. The main issue that needs to be considered is the algorithm used to render it. @@ -343,7 +343,7 @@ and add two extra parameters: - **Angle Attenuation:** The cone attenuation, which helps soften the cone borders. Spot shadow mapping -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ Spots feature the same parameters as omni lights for shadow mapping. Rendering spot shadow maps is significantly faster compared to omni lights, as only one @@ -439,7 +439,7 @@ Positional (omni/spot) shadow quality settings can be changed at runtime on the root :ref:`class_Viewport`. Shadow map size -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ High shadow resolutions result in sharper shadows, but at a significant performance cost. It should also be noted that *sharper shadows are not always @@ -454,7 +454,7 @@ fewer shadows. This will allow each shadow to be rendered at a higher resolution .. _doc_lights_and_shadows_shadow_filter_mode: Shadow filter mode -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ Several shadow map quality settings can be chosen here. The default **Soft Low** is a good balance between performance and quality for scenes with detailed @@ -474,7 +474,7 @@ make use of the increased sample count. .. image:: img/lights_and_shadows_filter_quality.webp 16-bits versus 32-bit -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ By default, Godot uses 16-bit depth textures for shadow map rendering. This is recommended in most cases as it performs better without a noticeable difference @@ -486,7 +486,7 @@ enabled. However, the difference is often barely visible, yet this can have a significant performance cost. Light/shadow distance fade -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ OmniLight3D and SpotLight3D offer several properties to hide distant lights. This can improve performance significantly in large scenes with dozens of lights @@ -509,7 +509,7 @@ or more. .. _doc_lights_and_shadows_pcss_recommendations: PCSS recommendations -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ Percentage-closer soft shadows (PCSS) provide a more realistic shadow mapping appearance, with the penumbra size varying depending on the distance between the @@ -529,7 +529,7 @@ To avoid performance issues, it's recommended to: ``light_size`` property to ``0.0`` in a script. Projector filter mode -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ The way projectors are rendered also has an impact on performance. The **Rendering > Textures > Light Projectors > Filter** advanced project setting diff --git a/tutorials/3d/occlusion_culling.rst b/tutorials/3d/occlusion_culling.rst index 18ca6f0effd..9f10fe79b61 100644 --- a/tutorials/3d/occlusion_culling.rst +++ b/tutorials/3d/occlusion_culling.rst @@ -115,7 +115,7 @@ There are two ways to set up occluders in a scene: .. _doc_occlusion_culling_baking: Automatically baking occluders (recommended) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -156,7 +156,7 @@ on the **VisualInstance3D > Layers** property, uncheck layer 1 then check layer following the above process. Manually placing occluders -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ This approach is more suited for specialized use cases, such as creating occlusion for MultiMeshInstance3D setups or CSG nodes (due to the aforementioned limitation). @@ -217,7 +217,7 @@ Performance considerations -------------------------- Design your levels to take advantage of occlusion culling -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **This is the most important guideline.** A good level design is not just about what the gameplay demands; it should also be built with occlusion in mind. @@ -230,7 +230,7 @@ when possible. This provides the greatest culling opportunities compared to any other terrain shape. Avoid moving OccluderInstance3D nodes during gameplay -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This includes moving the parents of OccluderInstance3D nodes, as this will cause the nodes themselves to move in global space, therefore requiring the :abbr:`BVH @@ -250,7 +250,7 @@ If you absolutely have to move an OccluderInstance3D node during gameplay, use a primitive Occluder3D shape for it instead of a complex baked shape. Use the simplest possible occluder shapes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you notice low performance or stuttering in complex 3D scenes, it may mean that the CPU is overloaded as a result of rendering detailed occluders. @@ -272,7 +272,7 @@ Troubleshooting --------------- My occludee isn't being culled when it should be -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **On the occluder side:** @@ -302,7 +302,7 @@ the occluder shapes for the occludee to be hidden. .. _doc_occlusion_culling_troubleshooting_false_negative: My occludee is being culled when it shouldn't be -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The most likely cause for this is that objects that were included in the occluder bake have been moved after baking occluders. For instance, this can diff --git a/tutorials/3d/physical_light_and_camera_units.rst b/tutorials/3d/physical_light_and_camera_units.rst index a41f0a50a99..861151c5a27 100644 --- a/tutorials/3d/physical_light_and_camera_units.rst +++ b/tutorials/3d/physical_light_and_camera_units.rst @@ -13,7 +13,7 @@ tradeoffs that aren't worth it for many games. As Godot favors ease of use by default, physical light units are disabled by default. Advantages of physical units -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you aim for photorealism in your project, using real world units as a basis can help make things easier to adjust. References for real world materials, @@ -24,7 +24,7 @@ Using real world units in Godot can also be useful when porting a scene from other 3D software that uses physical light units (such as Blender). Disadvantages of physical units -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The biggest disadvantage of using physical light units is you will have to pay close attention to the dynamic range in use at a given time. You can run into @@ -68,13 +68,13 @@ this performance impact, depth of field quality can be decreased in the advanced Project Settings. Enable the project setting -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ Open the Project Settings, enable the **Advanced** toggle then enable **Rendering > Lights And Shadows > Use Physical Light Units**. Restart the editor. Configure the camera -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ .. warning:: @@ -136,7 +136,7 @@ for a description of CameraAttributesPhysical properties that are also available **not** using physical light units. Configure the environment -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ .. warning:: @@ -160,7 +160,7 @@ the :ref:`class_Environment` resource: is set, this energy is multiplied by the intensity. Configure the light nodes -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ After enabling physical light units, 2 new properties become available in Light3D nodes: diff --git a/tutorials/3d/procedural_geometry/arraymesh.rst b/tutorials/3d/procedural_geometry/arraymesh.rst index cf20a5d2009..ed4848e3d40 100644 --- a/tutorials/3d/procedural_geometry/arraymesh.rst +++ b/tutorials/3d/procedural_geometry/arraymesh.rst @@ -94,7 +94,7 @@ Under ``_ready()``, create a new Array. .. code-tab:: csharp C# - var surfaceArray = new Godot.Collections.Array(); + Godot.Collections.Array surfaceArray = []; This will be the array that we keep our surface information in - it will hold all the arrays of data that the surface needs. Godot will expect it to be of @@ -108,7 +108,7 @@ size ``Mesh.ARRAY_MAX``, so resize it accordingly. .. code-tab:: csharp C# - var surfaceArray = new Godot.Collections.Array(); + Godot.Collections.Array surfaceArray = []; surfaceArray.Resize((int)Mesh.ArrayType.Max); Next create the arrays for each data type you will use. @@ -123,10 +123,10 @@ Next create the arrays for each data type you will use. .. code-tab:: csharp C# - var verts = new List(); - var uvs = new List(); - var normals = new List(); - var indices = new List(); + List verts = []; + List uvs = []; + List normals = []; + List indices = []; Once you have filled your data arrays with your geometry you can create a mesh by adding each array to ``surface_array`` and then committing to the mesh. @@ -196,14 +196,14 @@ Put together, the full code looks like: { public override void _Ready() { - var surfaceArray = new Godot.Collections.Array(); + Godot.Collections.Array surfaceArray = []; surfaceArray.Resize((int)Mesh.ArrayType.Max); // C# arrays cannot be resized or expanded, so use Lists to create geometry. - var verts = new List(); - var uvs = new List(); - var normals = new List(); - var indices = new List(); + List verts = []; + List uvs = []; + List normals = []; + List indices = []; /*********************************** * Insert code here to generate mesh. diff --git a/tutorials/3d/procedural_geometry/index.rst b/tutorials/3d/procedural_geometry/index.rst index 470e97ebef0..d736687576f 100644 --- a/tutorials/3d/procedural_geometry/index.rst +++ b/tutorials/3d/procedural_geometry/index.rst @@ -61,13 +61,13 @@ hidden from the user in the :ref:`RenderingServer `, but manually by passing in an array containing the surface information. Surfaces -^^^^^^^^ +~~~~~~~~ Each surface has its own material. Alternatively, you can override the material for all surfaces in the Mesh when you use a MeshInstance3D using the :ref:`material_override ` property. Surface array -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ The surface array is an array of length ``ArrayMesh.ARRAY_MAX``. Each position in the array is filled with a sub-array containing per-vertex information. For example, the array located at @@ -89,7 +89,7 @@ Godot provides different ways of accessing and working with geometry. More infor be provided in the following tutorials. ArrayMesh -^^^^^^^^^ +~~~~~~~~~ The ArrayMesh resource extends Mesh to add a few different quality of life functions and, most importantly, the ability to construct a Mesh surface through scripting. @@ -97,7 +97,7 @@ importantly, the ability to construct a Mesh surface through scripting. For more information about the ArrayMesh, please see the :ref:`ArrayMesh tutorial `. MeshDataTool -^^^^^^^^^^^^ +~~~~~~~~~~~~ The MeshDataTool is a resource that converts Mesh data into arrays of vertices, faces, and edges that can be modified at runtime. @@ -105,14 +105,14 @@ be modified at runtime. For more information about the MeshDataTool, please see the :ref:`MeshDataTool tutorial `. SurfaceTool -^^^^^^^^^^^ +~~~~~~~~~~~ The SurfaceTool allows the creation of Meshes using an OpenGL 1.x immediate mode style interface. For more information about the SurfaceTool, please see the :ref:`SurfaceTool tutorial `. ImmediateMesh -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ ImmediateMesh is a mesh that uses an immediate mode style interface (like SurfaceTool) to draw objects. The difference between ImmediateMesh and the diff --git a/tutorials/3d/resolution_scaling.rst b/tutorials/3d/resolution_scaling.rst index a34281cd9c1..758830583e2 100644 --- a/tutorials/3d/resolution_scaling.rst +++ b/tutorials/3d/resolution_scaling.rst @@ -41,7 +41,7 @@ In the advanced Project Settings' **Rendering > Scaling 3D** section, you can find several options for 3D resolution scaling: Scaling mode -^^^^^^^^^^^^ +~~~~~~~~~~~~ - **Bilinear:** Standard bilinear filtering (default). - **FSR 1.0:** `AMD FidelityFX Super Resolution 1.0 `__. @@ -86,7 +86,7 @@ MSAA is enabled. However, FSR2 doesn't benefit much from enabling MSAA since it already performs temporal antialiasing. Rendering scale -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ The **Rendering > Scaling 3D > Scale** setting adjusts the resolution scale. ``1.0`` represents the full resolution scale, with the 3D rendering resolution @@ -181,7 +181,7 @@ in each table. +--------------------------+-------------------------+-------------------------------+ FSR Sharpness -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ When using the FSR1 or FSR2 scaling modes, the sharpness can be controlled using the **Rendering > Scaling 3D > FSR Sharpness** advanced project setting. @@ -211,7 +211,7 @@ to oversharpening. .. _doc_resolution_scaling_mipmap_bias: Mipmap bias -^^^^^^^^^^^ +~~~~~~~~~~~ Godot automatically uses a negative texture mipmap bias when the 3D resolution scale is set below ``1.0``. This allows for better preservation of texture @@ -261,7 +261,7 @@ Troubleshooting --------------- Performance does not increase much when decreasing resolution scale -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If performance doesn't increase much when decreasing resolution scale to a value like ``0.5``, it likely means the performance bottleneck is elsewhere in your diff --git a/tutorials/3d/standard_material_3d.rst b/tutorials/3d/standard_material_3d.rst index 3bcc36f4007..37f53cb7817 100644 --- a/tutorials/3d/standard_material_3d.rst +++ b/tutorials/3d/standard_material_3d.rst @@ -36,7 +36,7 @@ BaseMaterial 3D settings StandardMaterial3D has many settings that determine the look of a material. All of these are under the BaseMaterial3D category -.. image:: img/spatial_material1.png +.. image:: img/spatial_material1.webp ORM materials are almost exactly the same with one difference. Instead of separate settings and textures for occlusion, roughness, and metallic, there is a single ORM texture. The different @@ -328,7 +328,7 @@ Vertex Color This setting allows choosing what is done by default to vertex colors that come from your 3D modeling application. By default, they are ignored. -.. image:: img/spatial_material4.png +.. image:: img/spatial_material4.webp Use as Albedo ~~~~~~~~~~~~~ @@ -647,7 +647,7 @@ faces the camera: * **Particle Billboard:** Most suited for particle systems, because it allows specifying :ref:`flipbook animation `. -.. image:: img/spatial_material9.png +.. image:: img/spatial_material9.webp The **Particles Anim** section is only visible when the billboard mode is **Particle Billboard**. diff --git a/tutorials/3d/using_decals.rst b/tutorials/3d/using_decals.rst index 776cd7e5c7f..f7e7b98fe7c 100644 --- a/tutorials/3d/using_decals.rst +++ b/tutorials/3d/using_decals.rst @@ -38,7 +38,7 @@ Use cases --------- Static decoration -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ Sometimes, the fastest way to add texture detail to a scene is to use decals. This is especially the case for organic detail, such as patches of dirt or sand @@ -58,7 +58,7 @@ footprints or wet puddles. Dirt added on top of level geometry using decals Dynamic gameplay elements -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ Decals can represent temporary or persistent gameplay effects such as bullet impacts and explosion scorches. @@ -67,7 +67,7 @@ Using an AnimationPlayer node or a script, decals can be made to fade over time (and then be removed using ``queue_free()``) to improve performance. Blob shadows -^^^^^^^^^^^^ +~~~~~~~~~~~~ Blob shadows are frequently used in mobile projects (or to follow a retro art style), as real-time lighting tends to be too expensive on low-end mobile @@ -96,7 +96,7 @@ Quick start guide ----------------- Creating decals in the editor -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Create a Decal node in the 3D editor. 2. In the inspector, expand the **Textures** section and load a texture in @@ -121,7 +121,7 @@ Decal node properties culling opportunities, therefore improving performance. Textures -^^^^^^^^ +~~~~~~~~ - **Albedo:** The albedo (diffuse/color) map to use for the decal. In most situations, this is the texture you want to set first. If using a normal @@ -141,7 +141,7 @@ Textures **Albedo**, this texture will appear to glow in the dark. Parameters -^^^^^^^^^^ +~~~~~~~~~~ - **Emission Energy:** The brightness of the emission texture. - **Modulate:** Multiplies the color of the albedo and emission textures. Use @@ -160,7 +160,7 @@ Parameters added normal angle computations. Vertical Fade -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ - **Upper Fade:** The curve over which the decal will fade as the surface gets further from the center of the :abbr:`AABB (Axis-Aligned Bounding Box)` @@ -170,7 +170,7 @@ Vertical Fade from the decal's projection angle). Only positive values are valid. Distance Fade -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ - **Enabled:** Controls whether distance fade (a form of :abbr:`LOD (Level of Detail)`) is enabled. The decal will fade out over **Begin + Length**, after which it @@ -184,7 +184,7 @@ Distance Fade more suited when the camera moves fast. Cull Mask -^^^^^^^^^ +~~~~~~~~~ - **Cull Mask:** Specifies which VisualInstance3D layers this decal will project on. By default, decals affect all layers. This is used so you can specify which diff --git a/tutorials/3d/using_multi_mesh_instance.rst b/tutorials/3d/using_multi_mesh_instance.rst index 8941ce0f8c8..ee14aeeea18 100644 --- a/tutorials/3d/using_multi_mesh_instance.rst +++ b/tutorials/3d/using_multi_mesh_instance.rst @@ -3,10 +3,10 @@ .. _doc_using_multi_mesh_instance: Using MultiMeshInstance3D -------------------------- +========================= Introduction -~~~~~~~~~~~~ +------------ In a normal scenario, you would use a :ref:`MeshInstance3D ` node to display a 3D mesh like a human model for the main character, but in some @@ -22,7 +22,7 @@ MeshInstance over a surface of a specific mesh. An example would be having a tree mesh populate a landscape mesh with trees of random scales and orientations. Setting up the nodes -~~~~~~~~~~~~~~~~~~~~ +-------------------- The basic setup requires three nodes: the MultiMeshInstance3D node and two MeshInstance3D nodes. @@ -50,48 +50,48 @@ Click it and select *Populate surface* in the dropdown menu. A new window titled .. image:: img/multimesh_settings.png MultiMesh settings -~~~~~~~~~~~~~~~~~~ +------------------ Below are descriptions of the options. Target Surface -++++++++++++++ +~~~~~~~~~~~~~~ The mesh used as the target surface on which to place copies of your source mesh. Source Mesh -+++++++++++ +~~~~~~~~~~~ The mesh you want duplicated on the target surface. Mesh Up Axis -++++++++++++ +~~~~~~~~~~~~ The axis used as the up axis of the source mesh. Random Rotation -+++++++++++++++ +~~~~~~~~~~~~~~~ Randomizing the rotation around the up axis of the source mesh. Random Tilt -+++++++++++ +~~~~~~~~~~~ Randomizing the overall rotation of the source mesh. Random Scale -++++++++++++ +~~~~~~~~~~~~ Randomizing the scale of the source mesh. Scale -+++++ +~~~~~ The scale of the source mesh that will be placed over the target surface. Amount -++++++ +~~~~~~ The amount of mesh instances placed over the target surface. diff --git a/tutorials/3d/variable_rate_shading.rst b/tutorials/3d/variable_rate_shading.rst index 116e9ca281e..a5c44ad1702 100644 --- a/tutorials/3d/variable_rate_shading.rst +++ b/tutorials/3d/variable_rate_shading.rst @@ -111,7 +111,7 @@ For custom viewports, the VRS mode and texture must be set manually to the :ref:`command line argument `. Creating a VRS density map -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ If using the **Texture** VRS mode, you *must* set a texture to be used as a density map. Otherwise, no effect will be visible. @@ -187,7 +187,7 @@ aspect ratio in your project (such as 16:9). low, or textures will appear grainy. Performance comparison -^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~ To give an idea of how much VRS can improve performance in theory, here's a performance comparison with the textured example scene shown at the top of this diff --git a/tutorials/3d/visibility_ranges.rst b/tutorials/3d/visibility_ranges.rst index 0c882bd1adf..935aa2f15a5 100644 --- a/tutorials/3d/visibility_ranges.rst +++ b/tutorials/3d/visibility_ranges.rst @@ -97,7 +97,7 @@ the following properties in the GeometryInstance3D's **Visibility Range** sectio .. _doc_visibility_ranges_fade_mode: Fade mode -^^^^^^^^^ +~~~~~~~~~ .. note:: @@ -132,7 +132,7 @@ choose from: .. _doc_visibility_ranges_visibility_parent: Visibility parent -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ The **Visibility Parent** property makes it easier to set up :abbr:`HLOD (Hierarchical Level of Detail)`. It allows automatically hiding @@ -194,7 +194,7 @@ Configuration tips ------------------ Use simpler materials at a distance to improve performance -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ One way to further improve performance is to use simpler materials for distant LOD meshes. While using LOD meshes will reduce the number of vertices that need @@ -223,7 +223,7 @@ expensive material features such as: - Proximity Fade Use dithering for LOD transitions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Godot currently only supports alpha-based fading for visibility ranges. You can however use dithering instead by using several different materials for different diff --git a/tutorials/3d/volumetric_fog.rst b/tutorials/3d/volumetric_fog.rst index 1f021e184e5..4834519f77f 100644 --- a/tutorials/3d/volumetric_fog.rst +++ b/tutorials/3d/volumetric_fog.rst @@ -224,7 +224,7 @@ the following properties in FogMaterial: :ref:`changing its import type in the Import dock `. Using 3D noise density textures -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since Godot 4.1, there is a NoiseTexture3D resource that can be used to procedurally generate 3D noise. This is well-suited to FogMaterial density diff --git a/tutorials/animation/animation_tree.rst b/tutorials/animation/animation_tree.rst index bd9fb8d00e7..b7140e3e18d 100644 --- a/tutorials/animation/animation_tree.rst +++ b/tutorials/animation/animation_tree.rst @@ -70,7 +70,7 @@ This will simply play back the animation. Make sure that the ``AnimationTree`` i Following is a short description of available nodes: Blend2 / Blend3 -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ These nodes will blend between two or three inputs by a user-specified blend value: @@ -84,7 +84,7 @@ This is very useful for layering animations on top of each other. .. image:: img/animtree6.png OneShot -^^^^^^^ +~~~~~~~ This node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters. @@ -122,7 +122,7 @@ After setting the request and changing the animation playback, the one-shot node animationTree.Get("parameters/OneShot/active"); TimeSeek -^^^^^^^^ +~~~~~~~~ This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an ``Animation`` from the start or a certain playback position inside the ``AnimationNodeBlendTree``. @@ -150,12 +150,12 @@ After setting the time and changing the animation playback, the seek node automa animationTree.Set("parameters/TimeSeek/seek_request", 12.0); TimeScale -^^^^^^^^^ +~~~~~~~~~ Allows scaling the speed of the animation (or reverse it) connected to the `in` input via the `scale` parameter. Setting the `scale` to 0 will pause the animation. Transition -^^^^^^^^^^ +~~~~~~~~~~ Very simple state machine (when you don't want to cope with a ``StateMachine`` node). Animations can be connected to the outputs and transition times can be specified. After setting the request and changing the animation playback, the transition node automatically clears the request on the next process frame by setting its ``transition_request`` value to an empty string (``""``). @@ -190,7 +190,7 @@ After setting the request and changing the animation playback, the transition no animationTree.Get("parameters/Transition/current_index"); BlendSpace2D -^^^^^^^^^^^^ +~~~~~~~~~~~~ ``BlendSpace2D`` is a node to do advanced blending in two dimensions. Points are added to a two-dimensional space and then a position can be controlled to determine blending: @@ -214,12 +214,12 @@ This mode can be changed in the *Blend* menu: .. image:: img/animtree10.png BlendSpace1D -^^^^^^^^^^^^ +~~~~~~~~~~~~ This is similar to 2D blend spaces, but in one dimension (so triangles are not needed). StateMachine -^^^^^^^^^^^^ +~~~~~~~~~~~~ This node acts as a state machine with root nodes as states. Root nodes can be created and connected via lines. States are connected via *Transitions*, which are connections with special properties. Transitions are uni-directional, but two can be used to connect in both directions. diff --git a/tutorials/animation/creating_movies.rst b/tutorials/animation/creating_movies.rst index f7f5178b978..25d58f529e3 100644 --- a/tutorials/animation/creating_movies.rst +++ b/tutorials/animation/creating_movies.rst @@ -110,7 +110,7 @@ Once you've configured and enabled Movie Maker mode, it will be automatically us when running the project from the editor. Command line usage -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ Movie Maker can also be enabled from the :ref:`command line `: @@ -157,7 +157,7 @@ Godot has 2 built-in :ref:`MovieWriters `, and more can be implemented by extensions: AVI (recommended) -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ AVI container with MJPEG for video and uncompressed audio. Features lossy video compression, resulting in medium file sizes and fast encoding. The lossy @@ -173,7 +173,7 @@ To use AVI, specify a path to an ``.avi`` file to be created in the **Editor > Movie Writer > Movie File** project setting. PNG -^^^ +~~~ PNG image sequence for video and WAV for audio. Features lossless video compression, at the cost of large file sizes and slow encoding. This is designed @@ -193,7 +193,7 @@ To use PNG, specify a ``.png`` file to be created in the file will have the same name as the ``.png`` file (minus the extension). Custom -^^^^^^ +~~~~~~ If you need to encode directly to a different format or pipe a stream through third-party software, you can extend the MovieWriter class to create your own @@ -371,7 +371,7 @@ Some common post-processing steps are listed below. .. _doc_creating_movies_converting_avi: Converting AVI video to MP4 -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ While some platforms such as YouTube support uploading the AVI file directly, many others will require a conversion step beforehand. `HandBrake `__ @@ -398,7 +398,7 @@ cost of a worse size/quality ratio. .. _doc_creating_movies_converting_image_sequence: Converting PNG image sequence + WAV audio to a video -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you chose to record a PNG image sequence with a WAV file beside it, you need to convert it to a video before you can use it elsewhere. @@ -428,7 +428,7 @@ storing transparency, so you can use WebM/VP9 as an alternative: .. _doc_creating_movies_motion_blur: Cutting video -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ You can trim parts of the video you don't want to keep after the video is recorded. For example, to discard everything before 12.1 seconds and keep @@ -442,7 +442,7 @@ Cutting videos can also be done with the GUI tool `LosslessCut `__. Resizing video -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ The following command resizes a video to be 1080 pixels tall (1080p), while preserving its existing aspect ratio: @@ -455,7 +455,7 @@ while preserving its existing aspect ratio: .. _doc_creating_movies_reducing_framerate: Reducing framerate -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ The following command changes a video's framerate to 30 FPS, dropping some of the original frames if there are more in the input video: @@ -465,7 +465,7 @@ the original frames if there are more in the input video: ffmpeg -i input.avi -r 30 -crf 15 output.mp4 Generating accumulation motion blur with FFmpeg -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Godot does not have built-in support for motion blur, but it can still be created in recorded videos. diff --git a/tutorials/animation/img/animation_animation_player_tree.png b/tutorials/animation/img/animation_animation_player_tree.png deleted file mode 100644 index e5fe9e50fa1..00000000000 Binary files a/tutorials/animation/img/animation_animation_player_tree.png and /dev/null differ diff --git a/tutorials/animation/img/animation_animation_player_tree.webp b/tutorials/animation/img/animation_animation_player_tree.webp new file mode 100644 index 00000000000..ad419457264 Binary files /dev/null and b/tutorials/animation/img/animation_animation_player_tree.webp differ diff --git a/tutorials/animation/img/animation_convenience_buttons.png b/tutorials/animation/img/animation_convenience_buttons.png deleted file mode 100644 index aadef466c5f..00000000000 Binary files a/tutorials/animation/img/animation_convenience_buttons.png and /dev/null differ diff --git a/tutorials/animation/img/animation_convenience_buttons.webp b/tutorials/animation/img/animation_convenience_buttons.webp new file mode 100644 index 00000000000..777f2f1a433 Binary files /dev/null and b/tutorials/animation/img/animation_convenience_buttons.webp differ diff --git a/tutorials/animation/img/animation_illustration.png b/tutorials/animation/img/animation_illustration.png deleted file mode 100644 index 84b4567a647..00000000000 Binary files a/tutorials/animation/img/animation_illustration.png and /dev/null differ diff --git a/tutorials/animation/img/animation_illustration.webp b/tutorials/animation/img/animation_illustration.webp new file mode 100644 index 00000000000..42ecbc76ee9 Binary files /dev/null and b/tutorials/animation/img/animation_illustration.webp differ diff --git a/tutorials/animation/img/animation_keyframes.png b/tutorials/animation/img/animation_keyframes.png deleted file mode 100644 index c33eeb8026b..00000000000 Binary files a/tutorials/animation/img/animation_keyframes.png and /dev/null differ diff --git a/tutorials/animation/img/animation_keyframes.webp b/tutorials/animation/img/animation_keyframes.webp new file mode 100644 index 00000000000..d60e2442c17 Binary files /dev/null and b/tutorials/animation/img/animation_keyframes.webp differ diff --git a/tutorials/animation/img/animation_loop.png b/tutorials/animation/img/animation_loop.png deleted file mode 100644 index b6f9a246236..00000000000 Binary files a/tutorials/animation/img/animation_loop.png and /dev/null differ diff --git a/tutorials/animation/img/animation_loop.webp b/tutorials/animation/img/animation_loop.webp new file mode 100644 index 00000000000..ebb63b0f59c Binary files /dev/null and b/tutorials/animation/img/animation_loop.webp differ diff --git a/tutorials/animation/img/animation_normal_track.png b/tutorials/animation/img/animation_normal_track.png deleted file mode 100644 index a6ceb36cea4..00000000000 Binary files a/tutorials/animation/img/animation_normal_track.png and /dev/null differ diff --git a/tutorials/animation/img/animation_normal_track.webp b/tutorials/animation/img/animation_normal_track.webp new file mode 100644 index 00000000000..fea3d71efb2 Binary files /dev/null and b/tutorials/animation/img/animation_normal_track.webp differ diff --git a/tutorials/animation/img/animation_set_length.png b/tutorials/animation/img/animation_set_length.png deleted file mode 100644 index 71a6d253e1c..00000000000 Binary files a/tutorials/animation/img/animation_set_length.png and /dev/null differ diff --git a/tutorials/animation/img/animation_set_length.webp b/tutorials/animation/img/animation_set_length.webp new file mode 100644 index 00000000000..9682e866c3b Binary files /dev/null and b/tutorials/animation/img/animation_set_length.webp differ diff --git a/tutorials/animation/img/animation_simple.gif b/tutorials/animation/img/animation_simple.gif index 787432dca96..f5948739772 100644 Binary files a/tutorials/animation/img/animation_simple.gif and b/tutorials/animation/img/animation_simple.gif differ diff --git a/tutorials/animation/img/animation_timeline.png b/tutorials/animation/img/animation_timeline.png deleted file mode 100644 index 74e48c166ea..00000000000 Binary files a/tutorials/animation/img/animation_timeline.png and /dev/null differ diff --git a/tutorials/animation/img/animation_timeline.webp b/tutorials/animation/img/animation_timeline.webp new file mode 100644 index 00000000000..20c3688592d Binary files /dev/null and b/tutorials/animation/img/animation_timeline.webp differ diff --git a/tutorials/animation/img/animation_track.webp b/tutorials/animation/img/animation_track.webp index d0bc08c8c8c..63b49377f60 100644 Binary files a/tutorials/animation/img/animation_track.webp and b/tutorials/animation/img/animation_track.webp differ diff --git a/tutorials/animation/img/animation_track_settings.webp b/tutorials/animation/img/animation_track_settings.webp index ae0b5cc187a..e913e4b723c 100644 Binary files a/tutorials/animation/img/animation_track_settings.webp and b/tutorials/animation/img/animation_track_settings.webp differ diff --git a/tutorials/animation/img/autoplay_on_load.webp b/tutorials/animation/img/autoplay_on_load.webp index 684b445db9e..00ebbb06cf5 100644 Binary files a/tutorials/animation/img/autoplay_on_load.webp and b/tutorials/animation/img/autoplay_on_load.webp differ diff --git a/tutorials/animation/introduction.rst b/tutorials/animation/introduction.rst index dc8b0e7acdb..ca72c26db7a 100644 --- a/tutorials/animation/introduction.rst +++ b/tutorials/animation/introduction.rst @@ -61,7 +61,7 @@ A keyframe defines the value of a property at a point in time. Diamond shapes represent keyframes in the timeline. A line between two keyframes indicates that the value doesn't change between them. -.. figure:: img/animation_keyframes.png +.. figure:: img/animation_keyframes.webp :alt: Keyframes in Godot Keyframes in Godot @@ -70,7 +70,7 @@ You set values of a node's properties and create animation keyframes for them. When the animation runs, the engine will interpolate the values between the keyframes, resulting in them gradually changing over time. -.. figure:: img/animation_illustration.png +.. figure:: img/animation_illustration.webp :alt: Two keyframes are all it takes to obtain a smooth motion Two keyframes are all it takes to obtain a smooth motion @@ -78,7 +78,7 @@ keyframes, resulting in them gradually changing over time. The timeline defines how long the animation will take. You can insert keyframes at various points, and change their timing. -.. figure:: img/animation_timeline.png +.. figure:: img/animation_timeline.webp :alt: The timeline in the animation panel The timeline in the animation panel @@ -89,7 +89,7 @@ a node and its affected property. For example, the position track in the illustration refers to the ``position`` property of the Sprite2D node. -.. figure:: img/animation_normal_track.png +.. figure:: img/animation_normal_track.webp :alt: Example of Normal animation tracks Example of Normal animation tracks @@ -110,7 +110,7 @@ Scene setup For this tutorial, we'll create a Sprite node with an AnimationPlayer as its child. We will animate the sprite to move between two points on the screen. -.. figure:: img/animation_animation_player_tree.png +.. figure:: img/animation_animation_player_tree.webp :alt: Our scene setup Our scene setup @@ -163,7 +163,7 @@ Adding a track To add a new track for our sprite, select it and take a look at the toolbar: -.. figure:: img/animation_convenience_buttons.png +.. figure:: img/animation_convenience_buttons.webp :alt: Convenience buttons Convenience buttons @@ -195,7 +195,7 @@ default, the animation is set to last only one second, so change the animation length to 2 in the controls on the right side of the animation panel's timeline header. -.. figure:: img/animation_set_length.png +.. figure:: img/animation_set_length.webp :alt: Animation length Animation length @@ -241,7 +241,7 @@ This means we can extend the animation length to four seconds now, and Godot will also calculate the frames from the last keyframe to the first, moving our sprite back and forth. -.. figure:: img/animation_loop.png +.. figure:: img/animation_loop.webp :alt: Animation loop Animation loop diff --git a/tutorials/animation/playing_videos.rst b/tutorials/animation/playing_videos.rst index d2ec01b50dc..6cd0bca9f1c 100644 --- a/tutorials/animation/playing_videos.rst +++ b/tutorials/animation/playing_videos.rst @@ -45,7 +45,7 @@ Setting up VideoStreamPlayer desired. Handling resizing and different aspect ratios -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default in Godot 4.0, the VideoStreamPlayer will automatically be resized to match the video's resolution. You can make it follow usual :ref:`class_Control` sizing @@ -85,7 +85,7 @@ to fit the whole screen while avoiding distortion. aspect ratios in your project. Displaying a video on a 3D surface -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using a VideoStreamPlayer node as a child of a :ref:`class_SubViewport` node, it's possible to display any 2D node on a 3D surface. For example, this can be @@ -117,7 +117,7 @@ See :ref:`doc_viewports` and the for more information on setting this up. Looping a video -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ For looping a video, the **Loop** property can be enabled. This will seamlessly restart the video when it reaches its end. @@ -196,7 +196,7 @@ below with almost any input video format (AVI, MOV, WebM, …). at the ``configuration:`` line in the command output. Balancing quality and file size -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The **video quality** level (``-q:v``) must be between ``1`` and ``10``. Quality ``6`` is a good compromise between quality and file size. If encoding at a high @@ -218,7 +218,7 @@ for a table listing Ogg Vorbis audio quality presets and their respective variable bitrates. FFmpeg: Convert while preserving original video resolution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following command converts the video while keeping its original resolution. The video and audio's bitrate will be variable to maximize quality while saving @@ -230,7 +230,7 @@ static scenes). ffmpeg -i input.mp4 -q:v 6 -q:a 6 output.ogv FFmpeg: Resize the video then convert it -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following command resizes a video to be 720 pixels tall (720p), while preserving its existing aspect ratio. This helps decrease the file size @@ -253,14 +253,14 @@ Chroma key, commonly known as the "green screen" or "blue screen" effect, allows We will achieve the chroma key effect by writing a custom shader in GDScript and using a `VideoStreamPlayer` node to display the video content. Scene Setup -^^^^^^^^^^^ +~~~~~~~~~~~ Ensure that the scene contains a `VideoStreamPlayer` node to play the video and a `Control` node to hold the UI elements for controlling the chroma key effect. .. image:: img/chroma_key_scene.webp Writing the Custom Shader -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ To implement the chroma key effect, follow these steps: @@ -307,7 +307,7 @@ The code above represents a simple demonstration of the Chroma Key shader, and users can customize it according to their specific requirements. UI Controls -^^^^^^^^^^^ +~~~~~~~~~~~ To allow users to manipulate the chroma key effect in real-time, we created sliders in the `Control` node. The `Control` node's script contains the following functions: @@ -375,7 +375,7 @@ also make sure that the range of the sliders are appropriate, our settings are : .. image:: img/slider_range.webp Signal Handling -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ Connect the appropriate signal from the UI elements to the `Control` node's script. you created in the `Control` node's script to control the chroma key effect. diff --git a/tutorials/assets_pipeline/img/import_csv.png b/tutorials/assets_pipeline/img/import_csv.png deleted file mode 100644 index d1336c587d4..00000000000 Binary files a/tutorials/assets_pipeline/img/import_csv.png and /dev/null differ diff --git a/tutorials/assets_pipeline/img/import_csv.webp b/tutorials/assets_pipeline/img/import_csv.webp new file mode 100644 index 00000000000..ce802d94525 Binary files /dev/null and b/tutorials/assets_pipeline/img/import_csv.webp differ diff --git a/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst index 8d7a2be0a45..845b60ccedc 100644 --- a/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst +++ b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst @@ -52,7 +52,7 @@ you'll need to use the Advanced Import Settings dialog, import hints, or possibl .. _doc_importing_3d_scenes_using_the_import_dock: Using the Import dock -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ The following options can be adjusted in the Import dock after selecting a 3D scene in the FileSystem dock: @@ -173,7 +173,7 @@ exported from other tools such as Maya. imported scene, with and without VRAM compression respectively. Using the Advanced Import Settings dialog -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The first tab you'll see is the **Scene** tab. The options available in the panel on the right are identical to the Import dock, but you have access to a 3D @@ -316,7 +316,7 @@ use an external material instead of the material that is included in the original 3D scene file; see the section below. Extracting materials to separate files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While Godot can import materials authored in 3D modeling software, the default configuration may not be suitable for your needs. For example: @@ -374,7 +374,7 @@ material, enabling **Save to File**, then specifying the save path using the .. _doc_importing_3d_scenes_import_script: Using import scripts for automation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A special script to process the whole scene after import can be provided. This is great for post-processing, changing materials, doing funny stuff with @@ -413,7 +413,7 @@ finally be used **must** be returned (even if the scene can be entirely differen To use your script, locate the script in the import tab's "Path" option under the "Import Script" category. Using animation libraries -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ As of Godot 4.0, you can choose to import **only** animations from a glTF file and nothing else. This is used in some asset pipelines to distribute animations @@ -440,7 +440,7 @@ Library act the same as when using the Scene import mode. See :ref:`doc_importing_3d_scenes_using_the_import_dock` for more information. Filter script -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ It is possible to specify a filter script in a special syntax to decide which tracks from which animations should be kept. @@ -492,21 +492,21 @@ would be retained. Any track filter lines that do not begin with a ``+`` or ``-`` are ignored. Storage -^^^^^^^ +~~~~~~~ By default, animations are saved as built-in. It is possible to save them to a file instead. This allows adding custom tracks to the animations and keeping them after a reimport. Optimizer -^^^^^^^^^ +~~~~~~~~~ When animations are imported, an optimizer is run, which reduces the size of the animation considerably. In general, this should always be turned on unless you suspect that an animation might be broken due to it being enabled. Clips -^^^^^ +~~~~~ It is possible to specify multiple animations from a single timeline as clips. For this to work, the model must have only one animation that is named diff --git a/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.rst b/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.rst index 5190bd9f1e7..a5a9f4999b4 100644 --- a/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.rst +++ b/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.rst @@ -21,7 +21,7 @@ will detect suffixes in object names and will perform actions automatically. **case-insensitive**. Remove nodes (-noimp) -^^^^^^^^^^^^^^^^^^^^^ +--------------------- Objects that have the ``-noimp`` suffix will be removed at import-time no matter what their type is. They will not appear in the imported scene. @@ -30,7 +30,7 @@ This is equivalent to enabling **Skip Import** for a node in the Advanced Import Settings dialog. Create collisions (-col, -convcol, -colonly, -convcolonly) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------------------------------- The option ``-col`` will work only for Mesh objects. If it is detected, a child static collision node will be added, using the same geometry as the mesh. This @@ -93,7 +93,7 @@ reliability. shapes. Create Occluder (-occ, -occonly) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------- If a mesh is imported with the ``-occ`` suffix an :ref:`class_occluder3D` node will be created based on the geometry of the mesh, it does not replace the mesh. @@ -101,30 +101,30 @@ A mesh node with the ``-occonly`` suffix will be converted to an :ref:`class_occluder3D` on import. Create navigation (-navmesh) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- A mesh node with the ``-navmesh`` suffix will be converted to a navigation mesh. The original Mesh object will be removed at import-time. Create a VehicleBody (-vehicle) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------- A mesh node with the ``-vehicle`` suffix will be imported as a child to a :ref:`class_VehicleBody3D` node. Create a VehicleWheel (-wheel) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------ A mesh node with the ``-wheel`` suffix will be imported as a child to a :ref:`class_VehicleWheel3D` node. Rigid Body (-rigid) -^^^^^^^^^^^^^^^^^^^ +------------------- A mesh node with the ``-rigid`` suffix will be imported as a :ref:`class_RigidBody3D`. Animation loop (-loop, -cycle) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------ Animation clips in the source 3D file that start or end with the token ``loop`` or ``cycle`` will be imported as a Godot :ref:`class_Animation` with the loop flag set. diff --git a/tutorials/assets_pipeline/importing_audio_samples.rst b/tutorials/assets_pipeline/importing_audio_samples.rst index 5470cb4ee90..42b5f56edde 100644 --- a/tutorials/assets_pipeline/importing_audio_samples.rst +++ b/tutorials/assets_pipeline/importing_audio_samples.rst @@ -181,7 +181,7 @@ Import options (Ogg Vorbis and MP3) ----------------------------------- Loop -^^^^ +~~~~ If enabled, the audio will begin playing at the beginning after playback ends by reaching the end of the audio. @@ -193,7 +193,7 @@ reaching the end of the audio. playing indefinitely. Loop Offset -^^^^^^^^^^^ +~~~~~~~~~~~ The loop offset determines where audio will start to loop after playback reaches the end of the audio. This can be used to only loop a part of the audio file, @@ -208,7 +208,7 @@ A more convenient editor for **Loop Offset** is provided in the dialog, as it lets you preview your changes without having to reimport the audio. BPM -^^^ +~~~ The Beats Per Minute of the audio track. This should match the BPM measure that was used to compose the track. This is only relevant for music that wishes to @@ -220,7 +220,7 @@ A more convenient editor for **BPM** is provided in the dialog, as it lets you preview your changes without having to reimport the audio. Beat Count -^^^^^^^^^^ +~~~~~~~~~~ The beat count of the audio track. This is only relevant for music that wishes to make use of interactive music functionality, not sound @@ -231,7 +231,7 @@ A more convenient editor for **Beat Count** is provided in the dialog, as it lets you preview your changes without having to reimport the audio. Bar Beats -^^^^^^^^^ +~~~~~~~~~ The number of bars within a single beat in the audio track. This is only relevant for music that wishes to make use of interactive music functionality @@ -273,7 +273,7 @@ Best practices -------------- Use appropriate quality settings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While keeping pristine-quality audio sources is important if you're performing editing, using the same quality in the exported project is not necessary. For @@ -299,7 +299,7 @@ sample rate and number of channels for your audio: very high-pitched). This is because most human voices never go past 11 kHz. Use real-time audio effects to reduce file size -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Godot has an :ref:`extensive bus system ` with built-in effects. This saves SFX artists the need to add reverb to the sound effects, diff --git a/tutorials/assets_pipeline/importing_images.rst b/tutorials/assets_pipeline/importing_images.rst index 938fabae512..2570688cc0d 100644 --- a/tutorials/assets_pipeline/importing_images.rst +++ b/tutorials/assets_pipeline/importing_images.rst @@ -65,7 +65,7 @@ image in the FileSystem dock: .. _doc_importing_images_changing_import_type: Changing import type -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ It is possible to choose other types of imported resources in the Import dock: @@ -113,7 +113,7 @@ Here are templates you can use for cubemap images (right-click > **Save Link As - :download:`6×1 cubemap template ` Detect 3D -^^^^^^^^^ +~~~~~~~~~ The default import options (no mipmaps and **Lossless** compression) are suited for 2D, but are not ideal for most 3D projects. **Detect 3D** makes Godot aware @@ -152,7 +152,7 @@ Import options .. _doc_importing_images_compress_mode: Compress > Mode -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ Images are one of the largest assets in a game. To handle them efficiently, they need to be compressed. Godot offers several compression methods, depending on @@ -256,7 +256,7 @@ FileSystem dock, then looking at the Inspector: Previewing a texture in the Inspector. Credit: `Red Brick 03 - Poly Haven `__ Compress > High Quality -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -279,7 +279,7 @@ BPTC and ASTC support VRAM compression for HDR textures, but S3TC and ETC2 do not (see **HDR Compression** below). Compress > HDR Compression -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -299,7 +299,7 @@ If set to **Always**, will force VRAM compression even for HDR textures with an alpha channel. To perform this, the alpha channel is discarded on import. Compress > Normal Map -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ When using a texture as normal map, only the red and green channels are required. Given regular texture compression algorithms produce artifacts that @@ -337,7 +337,7 @@ using the same amount of memory as a standard RGBA VRAM-compressed texture: `here `__. Compress > Channel Pack -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ If set to **sRGB Friendly** (default), prevents the RG color format from being used as it does not support sRGB color. @@ -355,7 +355,7 @@ or **Basis Universal** compression modes. .. _doc_importing_images_mipmaps: Mipmaps > Generate -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ If enabled, smaller versions of the texture are generated on import. For example, a 64×64 texture will generate 6 mipmaps (32×32, 16×16, 8×8, 4×4, 2×2, @@ -375,7 +375,7 @@ camera never zooms out significantly, there won't be a benefit to enabling mipmaps but memory usage will increase. Mipmaps > Limit -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ .. UPDATE: Not implemented. When Mipmaps > Limit is implemented, remove this .. warning and remove this comment. @@ -389,13 +389,13 @@ can be generated. This can be decreased if you don't want textures to become too low-resolution at extreme distances, at the cost of some graininess. Roughness > Mode -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ The color channel to consider as a roughness map in this texture. Only effective if **Roughness > Src Normal** is not empty. Roughness > Src Normal -^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~ The path to the texture to consider as a normal map for roughness filtering on import. Specifying this can help decrease specular aliasing slightly in 3D. @@ -403,7 +403,7 @@ import. Specifying this can help decrease specular aliasing slightly in 3D. Roughness filtering on import is only used in 3D rendering, not 2D. Process > Fix Alpha Border -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ This puts pixels of the same surrounding color in transition from transparent to opaque areas. For textures displayed with bilinear filtering, this helps @@ -415,7 +415,7 @@ It's recommended to leave this enabled (as it is by default), unless this causes issues for a particular image. Process > Premult Alpha -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ An alternative to fixing darkened borders with **Fix Alpha Border** is to use premultiplied alpha. By enabling this option, the texture will be converted to @@ -429,7 +429,7 @@ displayed correctly: option is only suited for 2D. Process > Normal Map Invert Y -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Godot requires the normal map to use the X+, Y+ and Z+ coordinates, which is known as an OpenGL-style normal map. If you've imported a material made to be @@ -441,7 +441,7 @@ popular engines) can be found `here `__. Process > HDR as sRGB -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ Some HDR images you can find online may be broken and contain sRGB color data (instead of linear color data). It is advised not to use those files. If you @@ -453,7 +453,7 @@ absolutely have to, enabling this option on will make them look correct. resulting image to look too dark, so leave this disabled if unsure. Process > HDR Clamp Exposure -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Some HDR panorama images you can find online may contain extremely bright pixels, due to being taken from real life sources without any clipping. @@ -466,7 +466,7 @@ clamping formula that does not introduce *visible* clipping – glow will keep working when looking at the background sky. Process > Size Limit -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ If set to a value greater than ``0``, the size of the texture is limited on import to a value smaller than or equal to the value specified here. For @@ -481,7 +481,7 @@ usually can't display textures larger than 4096×4096). .. _doc_importing_images_detect_3d_compress_to: Detect 3D > Compress To -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ This changes the :ref:`doc_importing_images_compress_mode` option that is used when a texture is detected as being used in 3D. @@ -492,7 +492,7 @@ existing compress mode on a texture (if it's detected to be used in 3D), but choosing **VRAM Compressed** or **Basis Universal** will. SVG > Scale -^^^^^^^^^^^ +~~~~~~~~~~~ *This is only available for SVG images.* @@ -504,7 +504,7 @@ also **Editor > Scale With Editor Scale** below. .. _doc_importing_images_editor_import_options: Editor > Scale With Editor Scale -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *This is only available for SVG images.* @@ -513,7 +513,7 @@ This should be enabled for editor plugin icons and custom class icons, but should be left disabled otherwise. Editor > Convert Colors With Editor Theme -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *This is only available for SVG images.* @@ -549,7 +549,7 @@ Best practices -------------- Supporting high-resolution texture sizes in 2D without artifacts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To support :ref:`multiple resolutions ` with crisp visuals at high resolutions, you will need to use high-resolution source images @@ -575,7 +575,7 @@ to make textures sharper (at the cost of some graininess) by setting negative value. Use appropriate texture sizes in 3D -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While there's no "one size fits all" recommendation, here are some general recommendations for choosing texture sizes in 3D: diff --git a/tutorials/assets_pipeline/importing_translations.rst b/tutorials/assets_pipeline/importing_translations.rst index 0a8943bae7a..a6b75ad010e 100644 --- a/tutorials/assets_pipeline/importing_translations.rst +++ b/tutorials/assets_pipeline/importing_translations.rst @@ -111,6 +111,6 @@ Select the ``.csv`` file and access the **Import** dock to define import options. You can toggle the compression of the imported translations, and select the delimiter to use when parsing the CSV file. -.. image:: img/import_csv.png +.. image:: img/import_csv.webp Be sure to click **Reimport** after any change to these options. diff --git a/tutorials/audio/text_to_speech.rst b/tutorials/audio/text_to_speech.rst index 3a504374e99..6e91954c8d5 100644 --- a/tutorials/audio/text_to_speech.rst +++ b/tutorials/audio/text_to_speech.rst @@ -74,7 +74,8 @@ Godot depends on system libraries for text-to-speech functionality. These librar Both Godot users on Linux and end-users on Linux running Godot games need to ensure that their system includes the system libraries for text-to-speech to work. Please consult the table below or your own distribution's documentation to determine what libraries you need to install. Distro-specific one-liners -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +------------------+-----------------------------------------------------------------------------------------------------------+ | **Arch Linux** | :: | | | | diff --git a/tutorials/best_practices/data_preferences.rst b/tutorials/best_practices/data_preferences.rst index 994d3d45e98..01b289e263d 100644 --- a/tutorials/best_practices/data_preferences.rst +++ b/tutorials/best_practices/data_preferences.rst @@ -259,7 +259,7 @@ tree structures. { private TreeNode _parent = null; - private List _children = new(); + private List _children = []; public override void _Notification(int what) { diff --git a/tutorials/best_practices/godot_interfaces.rst b/tutorials/best_practices/godot_interfaces.rst index 0e64a7d0dc2..3a2cf196693 100644 --- a/tutorials/best_practices/godot_interfaces.rst +++ b/tutorials/best_practices/godot_interfaces.rst @@ -112,9 +112,9 @@ access. { if (EnemyScn == null) { - return new string[] { "Must initialize property 'EnemyScn'." }; + return ["Must initialize property 'EnemyScn'."]; } - return Array.Empty(); + return []; } } diff --git a/tutorials/best_practices/godot_notifications.rst b/tutorials/best_practices/godot_notifications.rst index 50363f3a564..aea48284cc0 100644 --- a/tutorials/best_practices/godot_notifications.rst +++ b/tutorials/best_practices/godot_notifications.rst @@ -224,7 +224,7 @@ values will set up according to the following sequence: 1. **Initial value assignment:** the property is assigned its initialization value, or its default value if one is not specified. If a setter exists, it is not used. -2. **``_init()`` assignment:** the property's value is replaced by any assignments +2. ``_init()`` **assignment:** the property's value is replaced by any assignments made in ``_init()``, triggering the setter. 3. **Exported value assignment:** an exported property's value is again replaced by diff --git a/tutorials/best_practices/version_control_systems.rst b/tutorials/best_practices/version_control_systems.rst index 86d3a516a6d..a09ffe9daed 100644 --- a/tutorials/best_practices/version_control_systems.rst +++ b/tutorials/best_practices/version_control_systems.rst @@ -19,7 +19,7 @@ As of July 2023, there is only a Git plugin available, but the community may create additional VCS plugins. Official Git plugin -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ Using Git from inside the editor is supported with an official plugin. You can find the latest releases on diff --git a/tutorials/editor/default_key_mapping.rst b/tutorials/editor/default_key_mapping.rst index 31882525bfa..c104fb49984 100644 --- a/tutorials/editor/default_key_mapping.rst +++ b/tutorials/editor/default_key_mapping.rst @@ -49,7 +49,7 @@ General editor actions +-----------------------+-------------------------------+------------------------------+----------------------------------+ | Open Scene | :kbd:`Ctrl + O` | :kbd:`Cmd + O` | ``editor/open_scene`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ -| Close Scene | :kbd:`Ctrl + Shift + W` | :kbd:`Cmd + Shift + W` | ``editor/close_scene`` | +| Close Scene | :kbd:`Ctrl + Shift + W` | :kbd:`Cmd + W` | ``editor/close_scene`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ | Reopen Closed Scene | :kbd:`Ctrl + Shift + T` | :kbd:`Cmd + Shift + T` | ``editor/reopen_closed_scene`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ diff --git a/tutorials/editor/external_editor.rst b/tutorials/editor/external_editor.rst index 8745f9104b6..31efb1e21dd 100644 --- a/tutorials/editor/external_editor.rst +++ b/tutorials/editor/external_editor.rst @@ -94,7 +94,7 @@ To use these protocols, a Godot instance must be running on your current project Below are some configuration steps for specific editors: Visual Studio Code -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ You need to install the official `Visual Studio Code plugin `_. @@ -121,6 +121,6 @@ For **DAP**, specify the ``debugServer`` property in your ``launch.json`` file: } Emacs -^^^^^ +~~~~~ Check the official instructions to configure `LSP `_, and `DAP `_. diff --git a/tutorials/editor/img/project_settings_advanced.webp b/tutorials/editor/img/project_settings_advanced.webp new file mode 100644 index 00000000000..2c720b0c3f8 Binary files /dev/null and b/tutorials/editor/img/project_settings_advanced.webp differ diff --git a/tutorials/editor/img/project_settings_basic.webp b/tutorials/editor/img/project_settings_basic.webp new file mode 100644 index 00000000000..dbd5c02f6e1 Binary files /dev/null and b/tutorials/editor/img/project_settings_basic.webp differ diff --git a/tutorials/editor/project_settings.rst b/tutorials/editor/project_settings.rst index 03d651e27d7..b03b5fd40c7 100644 --- a/tutorials/editor/project_settings.rst +++ b/tutorials/editor/project_settings.rst @@ -1,16 +1,138 @@ -:article_outdated: True - .. _doc_project_settings: Project Settings ================ -This page explains how to use the Project Settings window. If you would like to access and modify project settings via code, see :ref:`ProjectSettings `. +There are dozens of settings you can change to control a project's execution, +including physics, rendering, and windowing settings. These settings can be +changed from the **Project Settings** window, from code, or by manually editing +the ``project.godot`` file. You can see a full list of settings in the +:ref:`ProjectSettings ` class. + +Internally, Godot stores the settings for a project in a ``project.godot`` file, +a plain text file in INI format. While this is human-readable and version control +friendly, it's not the most convenient to edit. For that reason, the +**Project Settings** window is available to edit these settings. To open the +Project Settings, select **Project > Project Settings** from the main menu. + +.. figure:: img/project_settings_basic.webp + :align: center + + The Project Settings window + +The **Project Settings** window is mainly used to change settings in the +**General** tab. Additionally, there are tabs for the +:ref:`Input Map `, +:ref:`Localization `, +:ref:`Globals `, +:ref:`Plugins `, and +**Import Defaults**. Usage of these other tabs is documented elsewhere. + +Changing project settings +------------------------- + +The **General** tab of the project settings window works much like the inspector. +It displays a list of project settings which you can change, just like inspector +properties. There is a list of categories on the left, which you can use to select +related groups of settings. You can also search for a specific setting with the +**Filter Settings** field. + +Each setting has a default value. Settings can be reset to their default values +by clicking the circular arrow **Reset** button next to each property. + +Changing project settings from code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use :ref:`set_setting() ` to +change a setting's value from code: + +.. tabs:: + .. code-tab:: gdscript GDScript + + ProjectSettings.set_setting("application/run/max_fps", 60) + ProjectSettings.set_setting("display/window/size/mode", DisplayServer.WINDOW_MODE_WINDOWED) + + .. code-tab:: csharp + + ProjectSettings.SetSetting("application/run/max_fps", 60); + ProjectSettings.SetSetting("display/window/size/mode", (int)DisplayServer.WindowMode.Windowed); + +However, many project settings are only read once when the game starts. After +that, changing the setting with ``set_setting()`` will have no effect. Instead, +most settings have a corresponding property or method on a runtime class like +:ref:`Engine ` or :ref:`DisplayServer `: + +.. tabs:: + .. code-tab:: gdscript GDScript + + Engine.max_fps = 60 + DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_WINDOWED) + + .. code-tab:: csharp + + Engine.MaxFps = 60; + DisplayServer.WindowSetMode(DisplayServer.WindowMode.Windowed); + +In general, project settings are duplicated at runtime in the +:ref:`Engine `, :ref:`PhysicsServer2D `, +:ref:`PhysicsServer3D `, +:ref:`RenderingServer `, +:ref:`Viewport `, or :ref:`Window ` classes. In the +:ref:`ProjectSettings ` class reference, settings +links to their equivalent runtime property or method. + +Reading project settings +------------------------ + +You can read project settings with +:ref:`get_setting() ` or +:ref:`get_setting_with_override() `: + +.. tabs:: + .. code-tab:: gdscript GDScript + + var max_fps = ProjectSettings.get_setting("application/run/max_fps") + var window_mode = ProjectSettings.get_setting("display/window/size/mode") + + .. code-tab:: csharp + + int maxFps = (int)ProjectSettings.GetSetting("application/run/max_fps"); + var windowMode = (DisplayServer.WindowMode)(int)ProjectSettings.GetSetting("display/window/size/mode"); + +Since many project settings are only read once at startup, the value in the +project settings may no longer be accurate. In these cases, it's better to read +the value from the runtime equivalent property or method: + +.. tabs:: + .. code-tab:: gdscript GDScript + + var max_fps = Engine.max_fps + var window_mode = DisplayServer.window_get_mode() + + .. code-tab:: csharp + + int maxFps = Engine.MaxFps; + DisplayServer.WindowMode windowMode = DisplayServer.WindowGetMode(); + +Manually editing project.godot +------------------------------ + +You can open the ``project.godot`` file using a text editor and manually +change project settings. Note that if the ``project.godot`` file does not have a +stored value for a particular setting, it is implicitly the default value of +that setting. This means that if you are are manually editing the file, you may +have to write in both the setting name *and* the value. + +In general, it is recommended to use the Project Settings window rather than +manually edit ``project.godot``. -Godot stores the project settings in a project.godot file, a plain text file in INI format. There are dozens of settings you can change to control a project's execution. To simplify this process, Godot provides a project settings dialog, which acts as a front-end to editing a project.godot file. +Advanced project settings +------------------------- -To access that dialog, select Project -> Project Settings. +.. figure:: img/project_settings_advanced.webp + :align: center -Once the window opens, let's select a main scene. Locate the `Application/Run/Main Scene` property and click on it to select 'hello.tscn'. + The advanced project settings -The project settings dialog provides a lot of options that can be saved to a project.godot file and shows their default values. If you change a value, a tick appears to the left of its name. This means that the property will be saved in the project.godot file and remembered. +By default, only some project settings are shown. To see all the project +settings, enable the **Advanced Settings** toggle. diff --git a/tutorials/editor/script_editor.rst b/tutorials/editor/script_editor.rst index a7b37e2aba0..0927ee1392f 100644 --- a/tutorials/editor/script_editor.rst +++ b/tutorials/editor/script_editor.rst @@ -6,7 +6,7 @@ Script Editor .. _doc_script_editor_introduction: Introduction -~~~~~~~~~~~~ +------------ Godot Engine's script editor is a powerful and fully-integrated text editor that not only streamlines the process of writing and debugging code written in @@ -25,7 +25,7 @@ be accessed in several ways as described in the .. _doc_script_editor_features: Features -~~~~~~~~ +-------- Some of the key features of the text editor are listed below: @@ -44,7 +44,7 @@ Some of the key features of the text editor are listed below: .. _doc_script_editor_usage: Usage -~~~~~ +----- If you are using GDScript in your project, the built-in text editor in Godot provides everything you need, serving as a one-stop location to @@ -106,7 +106,7 @@ You can also select a section below to jump to a specific topic: .. _doc_script_editor_script_panel: Script Panel ------------- +~~~~~~~~~~~~ .. |script| image:: img/script_editor_icons/Script.webp .. |scriptcsharp| image:: img/script_editor_icons/ScriptCSharp.webp @@ -165,7 +165,7 @@ behavior as filtering scripts. .. _doc_script_editor_menus: Menus ------ +~~~~~ The text editor's menus lie below the scene switcher and allow you to access a variety of tools and options, such as file management, search and replace, debugging @@ -365,7 +365,7 @@ The **Go To** menu lets you navigate within the code at ease with these options: .. _doc_script_editor_coding_area: Coding area ------------ +~~~~~~~~~~~ .. note:: This section will only cover the basics of the coding area in terms of the user interface. To learn more about scripting in Godot, refer to the :ref:`doc_gdscript` or diff --git a/tutorials/export/exporting_for_android.rst b/tutorials/export/exporting_for_android.rst index 2a95927f4b9..ad4eaddc7cb 100644 --- a/tutorials/export/exporting_for_android.rst +++ b/tutorials/export/exporting_for_android.rst @@ -96,24 +96,21 @@ Providing launcher icons Launcher icons are used by Android launcher apps to represent your application to users. Godot only requires high-resolution icons (for ``xxxhdpi`` density screens) and will automatically generate lower-resolution variants. -There are two types of icons required by Godot: +There are three types of icons: - **Main Icon:** The "classic" icon. This will be used on all Android versions up to Android 8 (Oreo), exclusive. Must be at least 192×192 px. - **Adaptive Icons:** Starting from Android 8 (inclusive), `Adaptive Icons `_ were introduced. Applications will need to include separate background and foreground icons to have a native look. The user's launcher application will control the icon's animation and masking. Must be at least 432×432 px. -- **Themed Icons:** Starting from Android 13 (inclusive), Themed Icons were introduced. Applications will need to include a monochrome icon to enable this feature. The user's launcher application will control the icon's theme. Must be at least 432×432 px. - -.. caution:: It is mandatory to provide a monochrome icon. Failure to do so will result in the default Godot monochrome icon being used. +- **Themed Icons (optional):** Starting from Android 13 (inclusive), Themed Icons were introduced. Applications will need to include a monochrome icon to enable this feature. The user's launcher application will control the icon's theme. Must be at least 432×432 px. .. seealso:: It's important to adhere to some rules when designing adaptive icons. `Google Design has provided a nice article `_ that helps to understand those rules and some of the capabilities of adaptive icons. .. caution:: The most important adaptive icon design rule is to have your icon critical elements inside the safe zone: a centered circle with a diameter of 66dp (264 pixels on ``xxxhdpi``) to avoid being clipped by the launcher. -If you don't provide some of the requested icons, Godot will replace them using a fallback chain, trying the next in line when the current one fails: +If you don't provide the requested icons (except for Monochrome), Godot will replace them using a fallback chain, trying the next in line when the current one fails: - **Main Icon:** Provided main icon -> Project icon -> Default Godot main icon. - **Adaptive Icon Foreground:** Provided foreground icon -> Provided main icon -> Project icon -> Default Godot foreground icon. - **Adaptive Icon Background:** Provided background icon -> Default Godot background icon. -- **Adaptive Icon Monochrome:** Provided monochrome icon -> Default Godot monochrome icon. It's highly recommended to provide all the requested icons with their specified resolutions. This way, your application will look great on all Android devices and versions. diff --git a/tutorials/export/exporting_pcks.rst b/tutorials/export/exporting_pcks.rst index 55867e76a2a..1955d72d069 100644 --- a/tutorials/export/exporting_pcks.rst +++ b/tutorials/export/exporting_pcks.rst @@ -58,7 +58,7 @@ In order to pack all resources of a project into a PCK file open the project and go to Project/Export and click on "Export PCK/Zip". Also make sure to have an export template selected while doing so. -.. image:: img/export_pck.png +.. image:: img/export_pck.webp Another method would be to :ref:`export from the command line `. If the output file ends with a PCK or ZIP file extension, then the export diff --git a/tutorials/export/feature_tags.rst b/tutorials/export/feature_tags.rst index 4f42e1a213c..a31ac6b4c76 100644 --- a/tutorials/export/feature_tags.rst +++ b/tutorials/export/feature_tags.rst @@ -140,7 +140,7 @@ Custom features It is possible to add custom features to a build; use the relevant field in the *export preset* used to generate it: -.. image:: img/feature_tags1.png +.. image:: img/feature_tags1.webp .. note:: @@ -158,11 +158,14 @@ This allows you to better customize any configuration when doing a build. In the following example, a different icon is added for the demo build of the game (which was customized in a special export preset, which, in turn, includes only demo levels). -.. image:: img/feature_tags2.png +.. figure:: img/feature_tags2.webp + :alt: The Project Settings panel -After overriding, a new field is added for this specific configuration: + The desired configuration is selected, which effectively copies its properties to the panel above (1). The "demo_build" feature tag is selected (2). The configuration is added to the project settings (3). -.. image:: img/feature_tags3.png +After overriding, a new field is added for this specific configuration. + +.. image:: img/feature_tags3.webp .. note:: @@ -179,7 +182,7 @@ Default overrides There are already a lot of settings that come with overrides by default; they can be found in many sections of the project settings. -.. image:: img/feature_tags4.png +.. image:: img/feature_tags4.webp Customizing the build --------------------- diff --git a/tutorials/export/img/export_pck.png b/tutorials/export/img/export_pck.png deleted file mode 100644 index 9d63ad744f8..00000000000 Binary files a/tutorials/export/img/export_pck.png and /dev/null differ diff --git a/tutorials/export/img/export_pck.webp b/tutorials/export/img/export_pck.webp new file mode 100644 index 00000000000..61ecce20262 Binary files /dev/null and b/tutorials/export/img/export_pck.webp differ diff --git a/tutorials/export/img/feature_tags1.png b/tutorials/export/img/feature_tags1.png deleted file mode 100644 index 1904cabadf7..00000000000 Binary files a/tutorials/export/img/feature_tags1.png and /dev/null differ diff --git a/tutorials/export/img/feature_tags1.webp b/tutorials/export/img/feature_tags1.webp new file mode 100644 index 00000000000..03ad85bbe6b Binary files /dev/null and b/tutorials/export/img/feature_tags1.webp differ diff --git a/tutorials/export/img/feature_tags2.png b/tutorials/export/img/feature_tags2.png deleted file mode 100644 index 1673b13b2d8..00000000000 Binary files a/tutorials/export/img/feature_tags2.png and /dev/null differ diff --git a/tutorials/export/img/feature_tags2.webp b/tutorials/export/img/feature_tags2.webp new file mode 100644 index 00000000000..5391c88a9fc Binary files /dev/null and b/tutorials/export/img/feature_tags2.webp differ diff --git a/tutorials/export/img/feature_tags3.png b/tutorials/export/img/feature_tags3.png deleted file mode 100644 index a99decdd0d3..00000000000 Binary files a/tutorials/export/img/feature_tags3.png and /dev/null differ diff --git a/tutorials/export/img/feature_tags3.webp b/tutorials/export/img/feature_tags3.webp new file mode 100644 index 00000000000..fba9a5ff2c4 Binary files /dev/null and b/tutorials/export/img/feature_tags3.webp differ diff --git a/tutorials/export/img/feature_tags4.png b/tutorials/export/img/feature_tags4.png deleted file mode 100644 index 85433aa0475..00000000000 Binary files a/tutorials/export/img/feature_tags4.png and /dev/null differ diff --git a/tutorials/export/img/feature_tags4.webp b/tutorials/export/img/feature_tags4.webp new file mode 100644 index 00000000000..59da5d32803 Binary files /dev/null and b/tutorials/export/img/feature_tags4.webp differ diff --git a/tutorials/export/one-click_deploy.rst b/tutorials/export/one-click_deploy.rst index b9cb8a7e4fd..d116a995716 100644 --- a/tutorials/export/one-click_deploy.rst +++ b/tutorials/export/one-click_deploy.rst @@ -102,7 +102,7 @@ Troubleshooting --------------- Android -^^^^^^^ +~~~~~~~ If you can't see the device in the list of devices when running the ``adb devices`` command in a terminal, it will not be visible by Godot either. @@ -123,7 +123,7 @@ To resolve this: .. _doc_one-click_deploy_troubleshooting_web: Web -^^^ +~~~ By default, the web server started by the editor is only accessible from ``localhost``. This means the web server can't be reached by other devices on diff --git a/tutorials/i18n/img/pseudolocalization_settings.webp b/tutorials/i18n/img/pseudolocalization_settings.webp index 095d213ec2d..c48ea3225a2 100644 Binary files a/tutorials/i18n/img/pseudolocalization_settings.webp and b/tutorials/i18n/img/pseudolocalization_settings.webp differ diff --git a/tutorials/i18n/internationalizing_games.rst b/tutorials/i18n/internationalizing_games.rst index 6267ba0e153..f5445d995e1 100644 --- a/tutorials/i18n/internationalizing_games.rst +++ b/tutorials/i18n/internationalizing_games.rst @@ -102,7 +102,7 @@ This will just look up the text in the translations and convert it if found: define the DynamicFont as the Default Font in the theme. Placeholders -^^^^^^^^^^^^ +~~~~~~~~~~~~ To feature placeholders in your translated strings, use :ref:`doc_gdscript_printf` or the equivalent feature in C#. This lets @@ -123,7 +123,7 @@ allow translators to choose the *order* in which placeholders appear: message.text = tr("{character} picked up the {weapon}").format({character = "Ogre", weapon = "Sword"}) Translation contexts -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ If you're using plain English as source strings (rather than message codes ``LIKE_THIS``), you may run into ambiguities when you have to translate the same @@ -150,7 +150,7 @@ identical: GetNode