diff --git a/.github/workflows/build_offline_docs.yml b/.github/workflows/build_offline_docs.yml index 7c6aba060b1..446f9091c72 100644 --- a/.github/workflows/build_offline_docs.yml +++ b/.github/workflows/build_offline_docs.yml @@ -14,6 +14,8 @@ jobs: runs-on: ubuntu-24.04 timeout-minutes: 180 strategy: + max-parallel: 1 + fail-fast: false matrix: branch: - master @@ -44,7 +46,7 @@ jobs: echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV sudo apt update - sudo apt install parallel libwebp7 + sudo apt install parallel libwebp7 imagemagick - name: Migrate to Redot run: | diff --git a/.gitignore b/.gitignore index 710a4e2301d..1bcb31ac48d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,15 +2,30 @@ !redirects.csv .env -env/ -__pycache__ -*.pyc +_build/ *~ .directory .vs/ .vscode/ *.mo +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# Common environment files +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# User created Python virtual environment as described in the docs +godot-docs-venv/ + # Vim temp files *.swo *.swp @@ -44,9 +59,6 @@ logo.h tmp-unused-images tmp-unused-images-history -# User created Python virtual environement as described in the docs -godot-docs-venv/ - # Jetbrains IDE files /.idea/ diff --git a/conf.py b/conf.py index bf04422a3ad..77f87da046b 100644 --- a/conf.py +++ b/conf.py @@ -220,6 +220,8 @@ html_js_files = [ "js/custom.js", + ('https://plausible.godot.foundation/js/script.file-downloads.outbound-links.js', + {'defer': 'defer', 'data-domain': 'godotengine.org'}), ] # Output file base name for HTML help builder diff --git a/contributing/development/compiling/compiling_for_ios.rst b/contributing/development/compiling/compiling_for_ios.rst index 7d5fcbe5929..d9512d1cfa7 100644 --- a/contributing/development/compiling/compiling_for_ios.rst +++ b/contributing/development/compiling/compiling_for_ios.rst @@ -86,3 +86,29 @@ Run To run on a device or simulator, follow these instructions: :ref:`doc_exporting_for_ios`. + +Troubleshooting +--------------- + +Fatal error: 'cstdint' file not found +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you get a compilation error of this form early on, it's likely because +the Xcode command line tools installation needs to be repaired after +a macOS or Xcode update: + +:: + + ./core/typedefs.h:45:10: fatal error: 'cstdint' file not found + 45 | #include + | ^~~~~~~~~ + +Run these two commands to reinstall Xcode command line tools +(enter your administrator password as needed): + +:: + + sudo rm -rf /Library/Developer/CommandLineTools + sudo xcode-select --install + +If it still does not work, try updating Xcode from the Mac App Store and try again. diff --git a/contributing/development/compiling/compiling_for_linuxbsd.rst b/contributing/development/compiling/compiling_for_linuxbsd.rst index a4582241efd..694675de729 100644 --- a/contributing/development/compiling/compiling_for_linuxbsd.rst +++ b/contributing/development/compiling/compiling_for_linuxbsd.rst @@ -608,7 +608,7 @@ running ``scons -h``, then looking for options starting with ``builtin_``. .. warning:: - When using system libraries, the resulting library is **not** portable + When using system libraries, the resulting binary is **not** portable across Linux distributions anymore. Do not use this approach for creating binaries you intend to distribute to others, unless you're creating a package for a Linux distribution. diff --git a/contributing/development/compiling/compiling_for_macos.rst b/contributing/development/compiling/compiling_for_macos.rst index 778d6795c08..9f3af62ff72 100644 --- a/contributing/development/compiling/compiling_for_macos.rst +++ b/contributing/development/compiling/compiling_for_macos.rst @@ -57,10 +57,6 @@ To compile for Apple Silicon (ARM64) powered Macs, use:: scons platform=macos arch=arm64 -To support both architectures in a single "Universal 2" binary, run the above two commands and then use ``lipo`` to bundle them together:: - - lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal - .. 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``. @@ -72,20 +68,39 @@ If all goes well, the resulting binary executable will be placed in the runs without any dependencies. Executing it will bring up the Project Manager. +.. note:: Using a standalone editor executable is not recommended, it should be always packaged into an + ``.app`` bundle to avoid UI activation issues. + .. note:: If you want to use separate editor settings for your own Godot builds and official releases, you can enable :ref:`doc_data_paths_self_contained_mode` by creating a file called ``._sc_`` or ``_sc_`` in the ``bin/`` folder. -To create an ``.app`` bundle like in the official builds, you need to use the -template located in ``misc/dist/macos_tools.app``. Typically, for an optimized +Automatic ``.app`` bundle creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To automatically create an ``.app`` bundle like in the official builds, use the ``generate_bundle=yes`` option on the *last* +SCons command used to build editor:: + + scons platform=macos arch=x86_64 + scons platform=macos arch=arm64 generate_bundle=yes + +Manual ``.app`` bundle creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To support both architectures in a single "Universal 2" binary, +run the above two commands and then use ``lipo`` to bundle them together:: + + lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal + +To create an ``.app`` bundle, you need to use the template located in ``misc/dist/macos_tools.app``. Typically, for an optimized editor binary built with ``dev_build=yes``:: - cp -r misc/dist/macos_tools.app ./Godot.app - mkdir -p Godot.app/Contents/MacOS - cp bin/godot.macos.editor.universal Godot.app/Contents/MacOS/Godot - chmod +x Godot.app/Contents/MacOS/Godot - codesign --force --timestamp --options=runtime --entitlements misc/dist/macos/editor.entitlements -s - Godot.app + cp -r misc/dist/macos_tools.app ./bin/Godot.app + mkdir -p bin/Godot.app/Contents/MacOS + cp bin/godot.macos.editor.universal bin/Godot.app/Contents/MacOS/Godot + chmod +x bin/Godot.app/Contents/MacOS/Godot + codesign --force --timestamp --options=runtime --entitlements misc/dist/macos/editor.entitlements -s - bin/Godot.app .. note:: @@ -95,8 +110,8 @@ editor binary built with ``dev_build=yes``:: You can also choose to link it dynamically by passing ``use_volk=yes`` and including the dynamic library in your ``.app`` bundle:: - mkdir -p Godot.app/Contents/Frameworks - cp /macOS/lib/libMoltenVK.dylib Godot.app/Contents/Frameworks/libMoltenVK.dylib + mkdir -p .app/Contents/Frameworks + cp /macOS/lib/libMoltenVK.dylib .app/Contents/Frameworks/libMoltenVK.dylib Running a headless/server build ------------------------------- @@ -200,3 +215,29 @@ Now you can compile with SCons like you normally would:: If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument:: scons platform=macos osxcross_sdk=darwin15 + +Troubleshooting +--------------- + +Fatal error: 'cstdint' file not found +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you get a compilation error of this form early on, it's likely because +the Xcode command line tools installation needs to be repaired after +a macOS or Xcode update: + +:: + + ./core/typedefs.h:45:10: fatal error: 'cstdint' file not found + 45 | #include + | ^~~~~~~~~ + +Run these two commands to reinstall Xcode command line tools +(enter your administrator password as needed): + +:: + + sudo rm -rf /Library/Developer/CommandLineTools + sudo xcode-select --install + +If it still does not work, try updating Xcode from the Mac App Store and try again. diff --git a/contributing/development/compiling/introduction_to_the_buildsystem.rst b/contributing/development/compiling/introduction_to_the_buildsystem.rst index df09ed4553f..557db6a1d06 100644 --- a/contributing/development/compiling/introduction_to_the_buildsystem.rst +++ b/contributing/development/compiling/introduction_to_the_buildsystem.rst @@ -69,9 +69,10 @@ To list the available target platforms, use ``scons platform=list``:: The following platforms are available: android - javascript + ios linuxbsd - server + macos + web windows Please run SCons again and select a valid platform: platform= @@ -124,20 +125,24 @@ build targets, and which will be explained below. Target ------ -Target controls if the editor is contained and debug flags are used. -All builds are optimized. Each mode means: +The ``target`` option controls if the editor is compiled and debug flags are used. +Optimization levels (``optimize``) and whether each build contains debug symbols +(``debug_symbols``) is controlled separately from the target. Each mode means: -- ``target=editor``: Build with editor, optimized, with debugging code (defines: ``TOOLS_ENABLED``, ``DEBUG_ENABLED``, ``-O2``/``/O2``) -- ``target=template_debug``: Build with C++ debugging symbols (defines: ``DEBUG_ENABLED``, ``-O2``/``/O2``) -- ``target=template_release``: Build without symbols (defines: ``-O3``/``/O2``) +- ``target=editor``: Build an editor binary (defines ``TOOLS_ENABLED`` and ``DEBUG_ENABLED``) +- ``target=template_debug``: Build a debug export template (defines ``DEBUG_ENABLED``) +- ``target=template_release``: Build a release export template The editor is enabled by default in all PC targets (Linux, Windows, macOS), disabled for everything else. Disabling the editor produces a binary that can run projects but does not include the editor or the Project Manager. +The list of :ref:`command line arguments ` +available varies depending on the build type. + :: - scons platform= target=editor/template_debug/template_release + scons platform= target=editor|template_debug|template_release .. _doc_introduction_to_the_buildsystem_development_and_production_aliases: diff --git a/contributing/development/configuring_an_ide/clion.rst b/contributing/development/configuring_an_ide/clion.rst index 2a715f2db56..44cc8d96419 100644 --- a/contributing/development/configuring_an_ide/clion.rst +++ b/contributing/development/configuring_an_ide/clion.rst @@ -81,3 +81,21 @@ You can now build, run, debug, profile, and Valgrind check the Godot editor via :align: center When playing a scene, the Godot editor will spawn a separate process. You can debug this process in CLion by going to **Run > Attach to process...**, typing ``godot``, and selecting the Godot process with the highest **pid** (process ID), which will usually be the running project. + +Ignoring object and library files +----------------------------------- + +After building Godot in CLion, you may see the object and library files showing up in the **Project** view. + +.. figure:: img/clion-object-library-files-in-project-view.webp + :align: center + +You can configure CLion to ignore those files: + +- Open CLion and navigate to **Preferences > Editor > File Types > Ignored Files and Folders** +- Click the **+** button to add ``*.o`` and ``*.a`` to the list. In Windows, you would add ``*.obj`` and ``*.dll``. + +.. figure:: img/clion-ignore-object-library-files.webp + :align: center + +Now, the files should be ignored in the Project view. diff --git a/contributing/development/configuring_an_ide/img/clion-ignore-object-library-files.webp b/contributing/development/configuring_an_ide/img/clion-ignore-object-library-files.webp new file mode 100644 index 00000000000..169b202eac4 Binary files /dev/null and b/contributing/development/configuring_an_ide/img/clion-ignore-object-library-files.webp differ diff --git a/contributing/development/configuring_an_ide/img/clion-object-library-files-in-project-view.webp b/contributing/development/configuring_an_ide/img/clion-object-library-files-in-project-view.webp new file mode 100644 index 00000000000..7a7a9b05c68 Binary files /dev/null and b/contributing/development/configuring_an_ide/img/clion-object-library-files-in-project-view.webp differ diff --git a/contributing/development/core_and_modules/common_engine_methods_and_macros.rst b/contributing/development/core_and_modules/common_engine_methods_and_macros.rst index 7754a40d136..8a47f21c5b8 100644 --- a/contributing/development/core_and_modules/common_engine_methods_and_macros.rst +++ b/contributing/development/core_and_modules/common_engine_methods_and_macros.rst @@ -182,6 +182,8 @@ repetition: It's recommended to use ``GLOBAL_DEF``/``EDITOR_DEF`` only once per setting and use ``GLOBAL_GET``/``EDITOR_GET`` in all other places where it's referenced. +.. _doc_common_engine_methods_and_macros_error_macros: + Error macros ------------ diff --git a/contributing/development/core_and_modules/core_types.rst b/contributing/development/core_and_modules/core_types.rst index 4d5d1554435..bcf7d2d6efa 100644 --- a/contributing/development/core_and_modules/core_types.rst +++ b/contributing/development/core_and_modules/core_types.rst @@ -103,7 +103,30 @@ which are equivalent to new, delete, new[] and delete[]. memnew/memdelete also use a little C++ magic and notify Objects right after they are created, and right before they are deleted. -For dynamic memory, use Vector<>. +For dynamic memory, use one of Godot's sequence types such as ``Vector<>`` +or ``LocalVector<>``. ``Vector<>`` behaves much like an STL ``std::vector<>``, +but is simpler and uses Copy-On-Write (CoW) semantics. CoW copies of +``Vector<>`` can safely access the same data from different threads, but +several threads cannot access the same ``Vector<>`` instance safely. +It can be safely passed via public API if it has a ``Packed`` alias. + +The ``Packed*Array`` :ref:`types ` are aliases +for specific ``Vector<*>`` types (e.g., ``PackedByteArray``, +``PackedInt32Array``) that are accessible via GDScript. Outside of core, +prefer using the ``Packed*Array`` aliases for functions exposed to scripts, +and ``Vector<>`` for other occasions. + +``LocalVector<>`` is much more like ``std::vector`` than ``Vector<>``. +It is non-CoW, with less overhead. It is intended for internal use where +the benefits of CoW are not needed. Note that neither ``LocalVector<>`` +nor ``Vector<>`` are drop-in replacements for each other. They are two +unrelated types with similar interfaces, both using a buffer as their +storage strategy. + +``List<>`` is another Godot sequence type, using a doubly-linked list as +its storage strategy. Prefer ``Vector<>`` (or ``LocalVector<>``) over +``List<>`` unless you're sure you need it, as cache locality and memory +fragmentation tend to be more important with small collections. References: ~~~~~~~~~~~ diff --git a/contributing/development/cpp_usage_guidelines.rst b/contributing/development/cpp_usage_guidelines.rst index 0ba32784882..9f0032a262e 100644 --- a/contributing/development/cpp_usage_guidelines.rst +++ b/contributing/development/cpp_usage_guidelines.rst @@ -100,6 +100,15 @@ pull request. To follow the existing style, please use standard ``#ifdef``-based include guards instead of ``#pragma once`` in new files. +``try``-``catch`` blocks +~~~~~~~~~~~~~~~~~~~~~~~~ + +C++ style exception handling using ``try`` and ``catch`` blocks is forbidden. +This restriction is in place for several reasons, including performance, binary +size and code complexity. +Use :ref:`doc_common_engine_methods_and_macros_error_macros` instead. + + .. seealso:: See :ref:`doc_code_style_guidelines_header_includes` for guidelines on sorting diff --git a/contributing/documentation/building_the_manual.rst b/contributing/documentation/building_the_manual.rst index 60a338e12d6..eb732febcc6 100644 --- a/contributing/documentation/building_the_manual.rst +++ b/contributing/documentation/building_the_manual.rst @@ -162,8 +162,33 @@ RAM for Sphinx alone. Specifying a list of files ~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. warning:: + + This section will not work on Windows, since the repository is using + a simplified ``make.bat`` script instead of the real GNU Make program. + If you would like to get a Linux terminal on your system, consider using + `Windows Subsystem for Linux (WSL) `__. + You can specify a list of files to build, which can greatly speed up compilation: .. code:: sh make html FILELIST='classes/class_node.rst classes/class_resource.rst' + +The list of files can also be provided by the ``git`` command. +This way you can automatically get the names of all files that have changed since +the last commit (``sed`` is used to put them on the same line). + +.. code:: sh + + make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')" + +You can replace ``HEAD`` with ``master`` to return all files changed from the +``master`` branch: + +.. code:: sh + + make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')" + +If any images were modified, the output will contain some warnings about them, +but the build will proceed correctly. diff --git a/contributing/documentation/docs_image_guidelines.rst b/contributing/documentation/docs_image_guidelines.rst index 7be6c25c780..b2537d32869 100644 --- a/contributing/documentation/docs_image_guidelines.rst +++ b/contributing/documentation/docs_image_guidelines.rst @@ -242,6 +242,7 @@ videos should be included with the following code snippet:: :autoplay: :loop: :muted: + :align: default Where ``documentation_video.webp`` would be changed to the name of the video you created. Name your videos in a way that makes their meaning clear, possibly with @@ -249,3 +250,4 @@ a prefix that makes their relationship to a documentation page explicit. The ``:autoplay:``, ``:loop:`` and ``:muted:`` flags should always be specified unless the video needs to play audio. In this case, do not specify *any* of these flags. +The ``:align: default`` flag should always be specified. 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 8f461308234..2548f77ffad 100644 --- a/getting_started/first_2d_game/03.coding_the_player.rst +++ b/getting_started/first_2d_game/03.coding_the_player.rst @@ -399,7 +399,7 @@ Next, add this code to the function: .. tabs:: .. code-tab:: gdscript GDScript - func _on_body_entered(body): + func _on_body_entered(_body): hide() # Player disappears after being hit. hit.emit() # Must be deferred as we can't change physics properties on a physics callback. 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 859879da7ec..af11ba167e7 100644 --- a/getting_started/first_2d_game/04.creating_the_enemy.rst +++ b/getting_started/first_2d_game/04.creating_the_enemy.rst @@ -85,8 +85,8 @@ and randomly choose one of the three animation types: .. code-tab:: gdscript GDScript func _ready(): - var mob_types = $AnimatedSprite2D.sprite_frames.get_animation_names() - $AnimatedSprite2D.play(mob_types[randi() % mob_types.size()]) + var mob_types = Array($AnimatedSprite2D.sprite_frames.get_animation_names()) + $AnimatedSprite2D.animation = mob_types.pick_random() .. code-tab:: csharp @@ -101,9 +101,10 @@ First, we get the list of animation names from the AnimatedSprite2D's ``sprite_f property. This returns an Array containing all three animation names: ``["walk", "swim", "fly"]``. -We then need to pick a random number between ``0`` and ``2`` to select one of -these names from the list (array indices start at ``0``). ``randi() % n`` -selects a random integer between ``0`` and ``n-1``. +In the GDScript code, we use the :ref:`Array.pick_random ` method +to select one of these animation names at random. Meanwhile, in the C# code, we pick a random number +between ``0`` and ``2`` to select one of these names from the list (array indices start at ``0``). The +expression ``GD.Randi() % n`` selects a random integer between ``0`` and ``n-1``. The last piece is to make the mobs delete themselves when they leave the screen. Connect the ``screen_exited()`` signal of the ``VisibleOnScreenNotifier2D`` node @@ -123,6 +124,8 @@ to the ``Mob`` and add this code: QueueFree(); } +``queue_free()`` is a function that essentially 'frees', or deletes, the node at the end of the frame. + This completes the `Mob` scene. With the player and enemies ready, in the next part, we'll bring them together 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 ff4c922b2ab..2087cd474dc 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 @@ -202,12 +202,12 @@ Note that a new instance must be added to the scene using ``add_child()``. var mob_spawn_location = $MobPath/MobSpawnLocation mob_spawn_location.progress_ratio = randf() + # Set the mob's position to the random location. + mob.position = mob_spawn_location.position + # Set the mob's direction perpendicular to the path direction. var direction = mob_spawn_location.rotation + PI / 2 - # Set the mob's position to a random location. - mob.position = mob_spawn_location.position - # Add some randomness to the direction. direction += randf_range(-PI / 4, PI / 4) mob.rotation = direction diff --git a/getting_started/first_3d_game/03.player_movement_code.rst b/getting_started/first_3d_game/03.player_movement_code.rst index 29d0989b181..a1fc2d561f4 100644 --- a/getting_started/first_3d_game/03.player_movement_code.rst +++ b/getting_started/first_3d_game/03.player_movement_code.rst @@ -119,10 +119,9 @@ using the global ``Input`` object, in ``_physics_process()``. } } -Here, we're going to make all calculations using the ``_physics_process()`` -virtual function. Like ``_process()``, it allows you to update the node every -frame, but it's designed specifically for physics-related code like moving a -kinematic or rigid body. +Here, instead of ``_process()``, we're going to make all calculations using the ``_physics_process()`` +virtual function. It's designed specifically for physics-related code like moving a +kinematic or rigid body. It updates the node using fixed time intervals. .. seealso:: diff --git a/getting_started/introduction/first_look_at_the_editor.rst b/getting_started/introduction/first_look_at_the_editor.rst index ae01d65eb96..299eede2103 100644 --- a/getting_started/introduction/first_look_at_the_editor.rst +++ b/getting_started/introduction/first_look_at_the_editor.rst @@ -54,7 +54,8 @@ Let's look at its main areas: .. image:: img/editor_intro_editor_empty.webp By default, along the window's top edge, it features **main menu** on the left, **workspace** switching -buttons in the center (active workspace is highlighted), and **playtest** buttons on the right: +buttons in the center (active workspace is highlighted), and **playtest** buttons and the +**Movie Maker Mode** toggle on the right: .. image:: img/editor_intro_top_menus.webp @@ -78,7 +79,7 @@ Below is the 3D one: .. image:: img/editor_intro_toolbar_3d.webp -.. seealso:: To learn more on workspaces, read :ref:`doc_intro_to_the_editor_interface_four_screens`. +.. seealso:: To learn more on workspaces, read :ref:`doc_intro_to_the_editor_interface_five_screens`. .. seealso:: To learn more on the 3D viewport and 3D in general, read :ref:`doc_introduction_to_3d`. @@ -115,13 +116,13 @@ When you click on one, it expands vertically. Below, you can see the animation e Bottom panels can also be shown or hidden using the shortcuts defined in **Editor Settings > Shortcuts**, under the **Bottom Panels** category. -.. _doc_intro_to_the_editor_interface_four_screens: +.. _doc_intro_to_the_editor_interface_five_screens: -The four main screens +The five main screens --------------------- -There are four main screen buttons centered at the top of the editor: -2D, 3D, Script, and Asset Library. +There are five main screen buttons centered at the top of the editor: +2D, 3D, Script, Game and Asset Library. You'll use the **2D screen** for all types of games. In addition to 2D games, the 2D screen is where you'll build your interfaces. @@ -136,6 +137,13 @@ In the **3D screen**, you can work with meshes, lights, and design levels for .. note:: Read :ref:`doc_introduction_to_3d` for more detail about the **3D main screen**. +The **Game screen** is where your project will appear when running it from +the editor. You can go through your project to test it, and pause it and +adjust it in real time. Note that this is for testing how adjustments would +work, any changes made here are not saved when the game stops running. + +.. image:: img/editor_intro_workspace_game.webp + The **Script screen** is a complete code editor with a debugger, rich auto-completion, and built-in code reference. diff --git a/getting_started/introduction/img/editor_intro_3d_viewport.webp b/getting_started/introduction/img/editor_intro_3d_viewport.webp index 7e5e0bdfd15..6cf92303f70 100644 Binary files a/getting_started/introduction/img/editor_intro_3d_viewport.webp and b/getting_started/introduction/img/editor_intro_3d_viewport.webp differ diff --git a/getting_started/introduction/img/editor_intro_bottom_panel_animation.webp b/getting_started/introduction/img/editor_intro_bottom_panel_animation.webp index 62f51ca70dc..3f6c948ac71 100644 Binary files a/getting_started/introduction/img/editor_intro_bottom_panel_animation.webp and b/getting_started/introduction/img/editor_intro_bottom_panel_animation.webp differ diff --git a/getting_started/introduction/img/editor_intro_editor_empty.webp b/getting_started/introduction/img/editor_intro_editor_empty.webp index 9ed9454cbbf..05b27cd460f 100644 Binary files a/getting_started/introduction/img/editor_intro_editor_empty.webp and b/getting_started/introduction/img/editor_intro_editor_empty.webp differ diff --git a/getting_started/introduction/img/editor_intro_filesystem_dock.webp b/getting_started/introduction/img/editor_intro_filesystem_dock.webp index 671365e1f2d..c3e1cdc27a2 100644 Binary files a/getting_started/introduction/img/editor_intro_filesystem_dock.webp and b/getting_started/introduction/img/editor_intro_filesystem_dock.webp differ diff --git a/getting_started/introduction/img/editor_intro_help_class_animated_sprite.webp b/getting_started/introduction/img/editor_intro_help_class_animated_sprite.webp index 15f69a8a639..9b090049648 100644 Binary files a/getting_started/introduction/img/editor_intro_help_class_animated_sprite.webp and b/getting_started/introduction/img/editor_intro_help_class_animated_sprite.webp differ diff --git a/getting_started/introduction/img/editor_intro_inspector_dock.webp b/getting_started/introduction/img/editor_intro_inspector_dock.webp index cada29002ef..b0919716573 100644 Binary files a/getting_started/introduction/img/editor_intro_inspector_dock.webp and b/getting_started/introduction/img/editor_intro_inspector_dock.webp differ diff --git a/getting_started/introduction/img/editor_intro_project_manager.webp b/getting_started/introduction/img/editor_intro_project_manager.webp index 7a81188b146..0458568f207 100644 Binary files a/getting_started/introduction/img/editor_intro_project_manager.webp and b/getting_started/introduction/img/editor_intro_project_manager.webp differ diff --git a/getting_started/introduction/img/editor_intro_search_help_button.webp b/getting_started/introduction/img/editor_intro_search_help_button.webp index 6058feabd57..393d4b809a6 100644 Binary files a/getting_started/introduction/img/editor_intro_search_help_button.webp and b/getting_started/introduction/img/editor_intro_search_help_button.webp differ diff --git a/getting_started/introduction/img/editor_intro_settings.webp b/getting_started/introduction/img/editor_intro_settings.webp index e30a94a33ff..2bdca60b621 100644 Binary files a/getting_started/introduction/img/editor_intro_settings.webp and b/getting_started/introduction/img/editor_intro_settings.webp differ diff --git a/getting_started/introduction/img/editor_intro_toolbar_2d.webp b/getting_started/introduction/img/editor_intro_toolbar_2d.webp index 481d328dde6..e434e6e5c6d 100644 Binary files a/getting_started/introduction/img/editor_intro_toolbar_2d.webp and b/getting_started/introduction/img/editor_intro_toolbar_2d.webp differ diff --git a/getting_started/introduction/img/editor_intro_toolbar_3d.webp b/getting_started/introduction/img/editor_intro_toolbar_3d.webp index e3ec21974fc..5617e6d2fd8 100644 Binary files a/getting_started/introduction/img/editor_intro_toolbar_3d.webp and b/getting_started/introduction/img/editor_intro_toolbar_3d.webp differ diff --git a/getting_started/introduction/img/editor_intro_top_menus.webp b/getting_started/introduction/img/editor_intro_top_menus.webp index 54c4fbeca90..d97b07672e5 100644 Binary files a/getting_started/introduction/img/editor_intro_top_menus.webp and b/getting_started/introduction/img/editor_intro_top_menus.webp differ diff --git a/getting_started/introduction/img/editor_intro_workspace_2d.webp b/getting_started/introduction/img/editor_intro_workspace_2d.webp index 12eb6785e36..bc7f2e47cc8 100644 Binary files a/getting_started/introduction/img/editor_intro_workspace_2d.webp and b/getting_started/introduction/img/editor_intro_workspace_2d.webp differ diff --git a/getting_started/introduction/img/editor_intro_workspace_3d.webp b/getting_started/introduction/img/editor_intro_workspace_3d.webp index 980fb9d0f2c..4bc67312e47 100644 Binary files a/getting_started/introduction/img/editor_intro_workspace_3d.webp and b/getting_started/introduction/img/editor_intro_workspace_3d.webp differ diff --git a/getting_started/introduction/img/editor_intro_workspace_assetlib.webp b/getting_started/introduction/img/editor_intro_workspace_assetlib.webp index f8f268af3ce..a4cf1c5bdfb 100644 Binary files a/getting_started/introduction/img/editor_intro_workspace_assetlib.webp and b/getting_started/introduction/img/editor_intro_workspace_assetlib.webp differ diff --git a/getting_started/introduction/img/editor_intro_workspace_game.webp b/getting_started/introduction/img/editor_intro_workspace_game.webp new file mode 100644 index 00000000000..4eb719d6361 Binary files /dev/null and b/getting_started/introduction/img/editor_intro_workspace_game.webp differ diff --git a/getting_started/introduction/img/editor_intro_workspace_script.webp b/getting_started/introduction/img/editor_intro_workspace_script.webp index d61a2c8e4f8..345fe234245 100644 Binary files a/getting_started/introduction/img/editor_intro_workspace_script.webp and b/getting_started/introduction/img/editor_intro_workspace_script.webp differ diff --git a/getting_started/step_by_step/img/nodes_and_scenes_01_empty_editor.webp b/getting_started/step_by_step/img/nodes_and_scenes_01_empty_editor.webp index 025129f14d2..e62b052b5a6 100644 Binary files a/getting_started/step_by_step/img/nodes_and_scenes_01_empty_editor.webp and b/getting_started/step_by_step/img/nodes_and_scenes_01_empty_editor.webp differ diff --git a/getting_started/step_by_step/img/nodes_and_scenes_03_create_node_window.webp b/getting_started/step_by_step/img/nodes_and_scenes_03_create_node_window.webp index 91745a39543..42e0489107f 100644 Binary files a/getting_started/step_by_step/img/nodes_and_scenes_03_create_node_window.webp and b/getting_started/step_by_step/img/nodes_and_scenes_03_create_node_window.webp differ diff --git a/getting_started/step_by_step/img/nodes_and_scenes_04_create_label_window.webp b/getting_started/step_by_step/img/nodes_and_scenes_04_create_label_window.webp index 6404736f459..ea817500897 100644 Binary files a/getting_started/step_by_step/img/nodes_and_scenes_04_create_label_window.webp and b/getting_started/step_by_step/img/nodes_and_scenes_04_create_label_window.webp differ diff --git a/getting_started/step_by_step/img/nodes_and_scenes_05_editor_with_label.webp b/getting_started/step_by_step/img/nodes_and_scenes_05_editor_with_label.webp index eee7b82b807..249b1a1af7d 100644 Binary files a/getting_started/step_by_step/img/nodes_and_scenes_05_editor_with_label.webp and b/getting_started/step_by_step/img/nodes_and_scenes_05_editor_with_label.webp differ diff --git a/getting_started/step_by_step/img/nodes_and_scenes_08_hello_world_text.webp b/getting_started/step_by_step/img/nodes_and_scenes_08_hello_world_text.webp index f037cd2c6e2..64f0627f214 100644 Binary files a/getting_started/step_by_step/img/nodes_and_scenes_08_hello_world_text.webp and b/getting_started/step_by_step/img/nodes_and_scenes_08_hello_world_text.webp differ diff --git a/getting_started/step_by_step/img/nodes_and_scenes_10_save_scene_as.webp b/getting_started/step_by_step/img/nodes_and_scenes_10_save_scene_as.webp index 3e5e391be60..ca1cbf84000 100644 Binary files a/getting_started/step_by_step/img/nodes_and_scenes_10_save_scene_as.webp and b/getting_started/step_by_step/img/nodes_and_scenes_10_save_scene_as.webp differ diff --git a/getting_started/step_by_step/img/nodes_and_scenes_11_final_result.webp b/getting_started/step_by_step/img/nodes_and_scenes_11_final_result.webp index 6050f36a54e..7563033fc87 100644 Binary files a/getting_started/step_by_step/img/nodes_and_scenes_11_final_result.webp and b/getting_started/step_by_step/img/nodes_and_scenes_11_final_result.webp differ diff --git a/getting_started/step_by_step/img/nodes_and_scenes_14_select_main_scene.webp b/getting_started/step_by_step/img/nodes_and_scenes_14_select_main_scene.webp index 0fe809e4ae3..e91d1801340 100644 Binary files a/getting_started/step_by_step/img/nodes_and_scenes_14_select_main_scene.webp and b/getting_started/step_by_step/img/nodes_and_scenes_14_select_main_scene.webp differ diff --git a/getting_started/step_by_step/instancing.rst b/getting_started/step_by_step/instancing.rst index 0c3f828b078..14141d78291 100644 --- a/getting_started/step_by_step/instancing.rst +++ b/getting_started/step_by_step/instancing.rst @@ -3,6 +3,15 @@ Creating instances ================== +.. note:: + + This tutorial refers to instancing scenes in the editor. To learn how + to instance scenes from code, see :ref:`doc_nodes_and_scene_instances`. + + Godot's approach to *instancing* described below should not be confused with + hardware instancing that can be used to render large amounts of similar + objects quickly. See :ref:`doc_using_multimesh` instead. + In the previous part, we saw that a scene is a collection of nodes organized in a tree structure, with a single node as its root. You can split your project into any number of scenes. This feature helps you break down and organize your @@ -121,7 +130,7 @@ Let's try this. Double-click ``ball.tscn`` in the FileSystem to open it. .. image:: img/instancing_ball_scene_open.webp -Select the Ball node. In the Inspector on the right, click on the PhysicsMaterial +In the Scene dock on the left, select the Ball node. Then, in the Inspector on the right, click on the PhysicsMaterial property to expand it. .. image:: img/instancing_physics_material_expand.webp diff --git a/requirements.txt b/requirements.txt index cc8a9fed83c..8aa718f59a3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -16,7 +16,7 @@ sphinx-tabs==3.4.7 # Adds a 'copy' button to the right of codeblocks. sphinx-copybutton==0.5.2 # Custom 404 error page (more useful than the default). -sphinx-notfound-page==1.0.4 +sphinx-notfound-page==1.1.0 # Adds Open Graph tags in the HTML `` tag. sphinxext-opengraph==0.9.1 diff --git a/tutorials/2d/2d_parallax.rst b/tutorials/2d/2d_parallax.rst index a1dc370ae04..dd87bce176e 100644 --- a/tutorials/2d/2d_parallax.rst +++ b/tutorials/2d/2d_parallax.rst @@ -10,13 +10,24 @@ Parallax is an effect used to simulate depth by having textures move at differen provides the :ref:`Parallax2D` node to achieve this effect. It can still be easy to get tripped up though, so this page provides in-depth descriptions of some properties and how to fix some common mistakes. -.. UPDATE: Experimental. When Parallax2D is no longer experimental, remove this -.. note and remove this comment. - .. note:: - This page only covers how to use :ref:`Parallax2D`. This node is still experimental, so the - implementation might change in future versions of Godot. However, it is still recommended to use over the - :ref:`ParallaxLayer` and :ref:`ParallaxBackground` nodes. + + This page covers how to use :ref:`Parallax2D`, which is + recommended to use over the :ref:`ParallaxLayer` and + :ref:`ParallaxBackground` nodes. + +Getting started +--------------- + +The parallax node supports adding nodes that render things as children, so you can use one or many nodes to make up each +layer. To begin, place each node or nodes you want to have scroll independently as a child of their own parallax node. +Make sure that the top left of the textures used are at the ``(0, 0)`` crossing, like in the image below. See the section +on :ref:`positioning ` for why this is important. + +.. image:: img/2d_parallax_size_viewport.webp + +The scene above uses one prepared texture for the higher clouds in a :ref:`Sprite2D `, but you could +just as easily use multiple nodes spaced out to compose the layer. Scroll scale ------------ @@ -27,8 +38,6 @@ A value of 1 makes the parallax node scroll at the same speed as the camera. If when scrolling, use a value lower than 1, with 0 bringing it to a complete stop. If you want something to appear closer to the camera, use a value higher than 1, making it scroll faster. -.. image:: img/2d_parallax_size_viewport.webp - The scene above is comprised of five layers. Some good :ref:`scroll_scale ` values might be: @@ -45,6 +54,7 @@ The video below displays how these values affect scrolling while in-game: :autoplay: :loop: :muted: + :align: default Infinite repeat --------------- @@ -121,6 +131,8 @@ Below, you can see that repeating the image twice makes it large enough to cover .. image:: img/2d_parallax_size_repeat.webp +.. _doc_2d_parallax_positioning: + Poor positioning ~~~~~~~~~~~~~~~~ diff --git a/tutorials/2d/2d_sprite_animation.rst b/tutorials/2d/2d_sprite_animation.rst index 912cbffbfec..a508fe1933e 100644 --- a/tutorials/2d/2d_sprite_animation.rst +++ b/tutorials/2d/2d_sprite_animation.rst @@ -104,7 +104,7 @@ released. _animatedSprite = GetNode("AnimatedSprite2D"); } - public override _Process(float _delta) + public override void _Process(double delta) { if (Input.IsActionPressed("ui_right")) { @@ -252,7 +252,7 @@ released. _animationPlayer = GetNode("AnimationPlayer"); } - public override void _Process(float _delta) + public override void _Process(double delta) { if (Input.IsActionPressed("ui_right")) { diff --git a/tutorials/2d/custom_drawing_in_2d.rst b/tutorials/2d/custom_drawing_in_2d.rst index ea831ad5e6b..d6650e4371a 100644 --- a/tutorials/2d/custom_drawing_in_2d.rst +++ b/tutorials/2d/custom_drawing_in_2d.rst @@ -1005,9 +1005,10 @@ Calculating this arc will be more complex than in the case of the line: .. code-tab:: gdscript GDScript func _draw(): - # Calculate the arc parameters. - var center : Vector2 = Vector2((_point2.x - point1.x) / 2, - (_point2.y - point1.y) / 2) + # Average points to get center. + var center : Vector2 = Vector2((_point2.x + point1.x) / 2, + (_point2.y + point1.y) / 2) + # Calculate the rest of the arc parameters. var radius : float = point1.distance_to(_point2) / 2 var start_angle : float = (_point2 - point1).angle() var end_angle : float = (point1 - _point2).angle() @@ -1022,9 +1023,10 @@ Calculating this arc will be more complex than in the case of the line: public override void _Draw() { - // Calculate the arc parameters. - Vector2 center = new Vector2((_point2.X - Point1.X) / 2.0f, - (_point2.Y - Point1.Y) / 2.0f); + // Average points to get center. + Vector2 center = new Vector2((_point2.X + Point1.X) / 2.0f, + (_point2.Y + Point1.Y) / 2.0f); + // Calculate the rest of the arc parameters. float radius = Point1.DistanceTo(_point2) / 2.0f; float startAngle = (_point2 - Point1).Angle(); float endAngle = (Point1 - _point2).Angle(); diff --git a/tutorials/2d/img/2d_editor_viewport.webp b/tutorials/2d/img/2d_editor_viewport.webp index 6bc63280fee..28a57edf8ac 100644 Binary files a/tutorials/2d/img/2d_editor_viewport.webp and b/tutorials/2d/img/2d_editor_viewport.webp differ diff --git a/tutorials/2d/img/2d_editor_viewport_with_viewmenu.webp b/tutorials/2d/img/2d_editor_viewport_with_viewmenu.webp index 4a83707b184..86b45f4a943 100644 Binary files a/tutorials/2d/img/2d_editor_viewport_with_viewmenu.webp and b/tutorials/2d/img/2d_editor_viewport_with_viewmenu.webp differ diff --git a/tutorials/2d/img/2d_parallax_size_viewport.webp b/tutorials/2d/img/2d_parallax_size_viewport.webp index 0ad33a04ecb..1f2b4d068db 100644 Binary files a/tutorials/2d/img/2d_parallax_size_viewport.webp and b/tutorials/2d/img/2d_parallax_size_viewport.webp differ diff --git a/tutorials/2d/img/2d_snapping_options_menu.webp b/tutorials/2d/img/2d_snapping_options_menu.webp index 3c8c29d7bd4..f67bf22110b 100644 Binary files a/tutorials/2d/img/2d_snapping_options_menu.webp and b/tutorials/2d/img/2d_snapping_options_menu.webp differ diff --git a/tutorials/2d/img/2d_toolbar.webp b/tutorials/2d/img/2d_toolbar.webp index 6b1c18efc4f..3a673c09e18 100644 Binary files a/tutorials/2d/img/2d_toolbar.webp and b/tutorials/2d/img/2d_toolbar.webp differ diff --git a/tutorials/2d/img/emission_shapes1.png b/tutorials/2d/img/emission_shapes1.png deleted file mode 100644 index e93b8fcda8b..00000000000 Binary files a/tutorials/2d/img/emission_shapes1.png and /dev/null differ diff --git a/tutorials/2d/img/emission_shapes1.webp b/tutorials/2d/img/emission_shapes1.webp new file mode 100644 index 00000000000..0eade5d58b5 Binary files /dev/null and b/tutorials/2d/img/emission_shapes1.webp differ diff --git a/tutorials/2d/img/emission_shapes2.png b/tutorials/2d/img/emission_shapes2.png deleted file mode 100644 index e6b147b0e49..00000000000 Binary files a/tutorials/2d/img/emission_shapes2.png and /dev/null differ diff --git a/tutorials/2d/img/emission_shapes2.webp b/tutorials/2d/img/emission_shapes2.webp new file mode 100644 index 00000000000..d01adf6f9b1 Binary files /dev/null and b/tutorials/2d/img/emission_shapes2.webp differ diff --git a/tutorials/2d/img/emission_shapes3.png b/tutorials/2d/img/emission_shapes3.png deleted file mode 100644 index f5f8e77d890..00000000000 Binary files a/tutorials/2d/img/emission_shapes3.png and /dev/null differ diff --git a/tutorials/2d/img/emission_shapes3.webp b/tutorials/2d/img/emission_shapes3.webp new file mode 100644 index 00000000000..407b38006c7 Binary files /dev/null and b/tutorials/2d/img/emission_shapes3.webp differ diff --git a/tutorials/2d/img/emission_shapes4.png b/tutorials/2d/img/emission_shapes4.png deleted file mode 100644 index ca657331a7d..00000000000 Binary files a/tutorials/2d/img/emission_shapes4.png and /dev/null differ diff --git a/tutorials/2d/img/emission_shapes4.webp b/tutorials/2d/img/emission_shapes4.webp new file mode 100644 index 00000000000..c66670f0186 Binary files /dev/null and b/tutorials/2d/img/emission_shapes4.webp differ diff --git a/tutorials/2d/img/particle_minmaxcurve.webp b/tutorials/2d/img/particle_minmaxcurve.webp new file mode 100644 index 00000000000..b75307e351c Binary files /dev/null and b/tutorials/2d/img/particle_minmaxcurve.webp differ diff --git a/tutorials/2d/img/particles2.png b/tutorials/2d/img/particles2.png deleted file mode 100644 index 84a6b0ef912..00000000000 Binary files a/tutorials/2d/img/particles2.png and /dev/null differ diff --git a/tutorials/2d/img/particles2.webp b/tutorials/2d/img/particles2.webp new file mode 100644 index 00000000000..8d4e45d84ff Binary files /dev/null and b/tutorials/2d/img/particles2.webp differ diff --git a/tutorials/2d/img/particles_convert.webp b/tutorials/2d/img/particles_convert.webp index bc1385bef8c..82fcb4da23d 100644 Binary files a/tutorials/2d/img/particles_convert.webp and b/tutorials/2d/img/particles_convert.webp differ diff --git a/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp b/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp index 0e362339b61..4a903096712 100644 Binary files a/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp and b/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp differ diff --git a/tutorials/2d/img/particles_material.png b/tutorials/2d/img/particles_material.png deleted file mode 100644 index 860e10d30e3..00000000000 Binary files a/tutorials/2d/img/particles_material.png and /dev/null differ diff --git a/tutorials/2d/img/particles_material.webp b/tutorials/2d/img/particles_material.webp new file mode 100644 index 00000000000..fc99f6d8e17 Binary files /dev/null and b/tutorials/2d/img/particles_material.webp differ diff --git a/tutorials/2d/index.rst b/tutorials/2d/index.rst index 2bc60e0de56..9203c19e5da 100644 --- a/tutorials/2d/index.rst +++ b/tutorials/2d/index.rst @@ -33,6 +33,7 @@ Rendering 2d_meshes 2d_sprite_animation particle_systems_2d + particle_process_material_2d 2d_antialiasing custom_drawing_in_2d 2d_parallax diff --git a/tutorials/2d/introduction_to_2d.rst b/tutorials/2d/introduction_to_2d.rst index c5a4d33aa1b..6b6733d2061 100644 --- a/tutorials/2d/introduction_to_2d.rst +++ b/tutorials/2d/introduction_to_2d.rst @@ -165,10 +165,6 @@ Use the three-dot menu for this: - Make Bone2D Node(s) from Node(s): Converts selected node(s) into Bone2D. .. seealso:: To learn more about Skeletons, see :ref:`doc_cutout_animation`. - -- **Project Camera Override**: Temporarily replaces the active camera in the level - (e.g., the camera following the player) with the camera in the editor's viewport, allowing - you to move freely and inspect the level's different parts, while the game is running. - **View** menu: Provides options to control the viewport view. Since its options depend heavily on the viewport, it is covered in the :ref:`doc_introduction_to_2d_the_viewport` @@ -307,10 +303,8 @@ for everything GUI. For 3D, Godot uses the :ref:`Node3D ` node. 3D in 2D -------- -It is possible to display 3D scenes in 2D screen. This is achieved by adding a -:ref:`SubViewport ` as a child. -Then, you can drag a 3D scene as a child of the SubViewport: +It is possible to display 3D scenes in 2D screen, You can see this in the demo `3D in 2D Viewport `__. .. image:: img/3d_in_2d_demo_editor.webp -.. seealso:: You can check the demo on: `3D in 2D Viewport demo `__. + diff --git a/tutorials/2d/particle_process_material_2d.rst b/tutorials/2d/particle_process_material_2d.rst new file mode 100644 index 00000000000..8e18c39ac7c --- /dev/null +++ b/tutorials/2d/particle_process_material_2d.rst @@ -0,0 +1,286 @@ +.. _doc_particle_process_material_2d: + +ParticleProcessMaterial 2D Usage +================================ + +Process material properties +--------------------------- + +.. figure:: img/particle_minmaxcurve.webp + :alt: ParticleProcessMaterial properties + :align: right + + Min, max, and curve properties + +The properties in this material control how particles behave and change over their lifetime. +A lot of them have ``Min``, ``Max``, and ``Curve`` values that allow you to fine-tune +their behavior. The relationship between these values is this: When a particle is spawned, +the property is set with a random value between ``Min`` and ``Max``. If ``Min`` and ``Max`` are +the same, the value will always be the same for every particle. If the ``Curve`` is also set, +the value of the property will be multiplied by the value of the curve at the current point +in a particle's lifetime. Use the curve to change a property over the particle lifetime. Very +complex behavior can be expressed this way. + +.. note:: + This page covers how to use ParticleProcessMaterial for 2D scenes specifically. + For information on how to use it in a 3D scene see :ref:`doc_process_material_properties`. + +Lifetime Randomness +~~~~~~~~~~~~~~~~~~~ + +The ``Lifetime Randomness`` property controls how much randomness to apply to each particle's +lifetime. A value of ``0`` means there is no randomness at all and all particles live for +the same amount of time, set by the :ref:`Lifetime ` property. A value of ``1`` means +that a particle's lifetime is completely random within the range of [0.0, ``Lifetime``]. + +Particle Flags +-------------- + +Spawn +----- + +Angle +~~~~~ + +Determines the initial angle of the particle (in degrees). This parameter +is mostly useful randomized. + +.. image:: img/paranim11.gif + +Velocity +~~~~~~~~ + +Direction +^^^^^^^^^ + +This is the base direction at which particles emit. The default is +``Vector3(1, 0, 0)`` which makes particles emit to the right. However, +with the default gravity settings, particles will go straight down. + +.. image:: img/direction1.png + +For this property to be noticeable, you need an *initial velocity* greater +than 0. Here, we set the initial velocity to 40. You'll notice that +particles emit toward the right, then go down because of gravity. + +.. image:: img/direction2.png + +Spread +^^^^^^ + +This parameter is the angle in degrees which will be randomly added in +either direction to the base ``Direction``. A spread of ``180`` will emit +in all directions (+/- 180). For spread to do anything the "Initial Velocity" +parameter must be greater than 0. + +.. image:: img/paranim3.gif + +Flatness +^^^^^^^^ + +This property is only useful for 3D particles. + +Initial Velocity +^^^^^^^^^^^^^^^^ + +Initial velocity is the speed at which particles will be emitted (in +pixels/sec). Speed might later be modified by gravity or other +accelerations (as described further below). + +.. image:: img/paranim4.gif + +Animated Velocity +----------------- + +Angular Velocity +~~~~~~~~~~~~~~~~ + +Angular velocity is the speed at which particles rotate around their center +(in degrees/sec). + +.. image:: img/paranim5.gif + +Orbit Velocity +~~~~~~~~~~~~~~ + +Orbit velocity is used to make particles turn around their center. + +.. image:: img/paranim6.gif + +Accelerations +------------- + +Gravity +~~~~~~~ + +The gravity applied to every particle. + +.. image:: img/paranim7.gif + +Linear Acceleration +~~~~~~~~~~~~~~~~~~~ + +The linear acceleration applied to each particle. + +Radial Acceleration +~~~~~~~~~~~~~~~~~~~ + +If this acceleration is positive, particles are accelerated away from +the center. If negative, they are absorbed towards it. + +.. image:: img/paranim8.gif + +Tangential Acceleration +~~~~~~~~~~~~~~~~~~~~~~~ + +This acceleration will use the tangent vector to the center. Combining +with radial acceleration can do nice effects. + +.. image:: img/paranim9.gif + +Damping +~~~~~~~ + +Damping applies friction to the particles, forcing them to stop. It is +especially useful for sparks or explosions, which usually begin with a +high linear velocity and then stop as they fade. + +.. image:: img/paranim10.gif + +Display +------- + +Scale +~~~~~ + +Determines the initial scale of the particles. + +.. image:: img/paranim12.gif + +Color Curves +~~~~~~~~~~~~ + +Color +^^^^^ + +Used to change the color of the particles being emitted. + +Hue Variation +~~~~~~~~~~~~~ + +The ``Variation`` value sets the initial hue variation applied to each +particle. The ``Variation Random`` value controls the hue variation +randomness ratio. + +.. _doc_particle_systems_2d_animation: + +Animation +~~~~~~~~~ + +.. note:: + + Particle flipbook animation is only effective if the CanvasItemMaterial used + on the GPUParticles2D or CPUParticles2D node has been + :ref:`configured accordingly `. + +To set up the particle flipbook for linear playback, set the **Speed Min** and **Speed Max** values to 1: + +.. figure:: img/particles_flipbook_configure_animation_speed.webp + :align: center + :alt: Setting up particle animation for playback during the particle's lifetime + + Setting up particle animation for playback during the particle's lifetime + +By default, looping is disabled. If the particle is done playing before its +lifetime ends, the particle will keep using the flipbook's last frame (which may +be fully transparent depending on how the flipbook texture is designed). If +looping is enabled, the animation will loop back to the first frame and resume +playing. + +Depending on how many images your sprite sheet contains and for how long your +particle is alive, the animation might not look smooth. The relationship between +particle lifetime, animation speed, and number of images in the sprite sheet is +this: + +.. note:: + + At an animation speed of ``1.0``, the animation will reach the last image + in the sequence just as the particle's lifetime ends. + + .. math:: + Animation\ FPS = \frac{Number\ of\ images}{Lifetime} + +If you wish the particle flipbook to be used as a source of random particle +textures for every particle, keep the speed values at 0 and set **Offset Max** +to 1 instead: + +.. figure:: img/particles_flipbook_configure_animation_offset.webp + :align: center + :alt: Setting up particle animation for random offset on emission + + Setting up particle animation for random offset on emission + +Note that the GPUParticles2D node's **Fixed FPS** also affects animation +playback. For smooth animation playback, it's recommended to set it to 0 so that +the particle is simulated on every rendered frame. If this is not an option for +your use case, set **Fixed FPS** to be equal to the effective framerate used by +the flipbook animation (see above for the formula). + +Emission Shapes +--------------- + +ParticleProcessMaterials allow you to set an Emission Mask, which dictates +the area and direction in which particles are emitted. +These can be generated from textures in your project. + +Ensure that a ParticleProcessMaterial is set, and the GPUParticles2D node is selected. +A "Particles" menu should appear in the Toolbar: + +.. image:: img/emission_shapes1.webp + +Open it and select "Load Emission Mask": + +.. image:: img/emission_shapes2.webp + +Then select which texture you want to use as your mask: + +.. image:: img/emission_shapes3.webp + +A dialog box with several settings will appear. + +Emission Mask +~~~~~~~~~~~~~ + +Three types of emission masks can be generated from a texture: + +- Solid Pixels: Particles will spawn from any area of the texture, + excluding transparent areas. + +.. image:: img/emission_mask_solid.gif + +- Border Pixels: Particles will spawn from the outer edges of the texture. + +.. image:: img/emission_mask_border.gif + +- Directed Border Pixels: Similar to Border Pixels, but adds extra + information to the mask to give particles the ability to emit away + from the borders. Note that an ``Initial Velocity`` will need to + be set in order to utilize this. + +.. image:: img/emission_mask_directed_border.gif + +Emission Colors +~~~~~~~~~~~~~~~ + +``Capture from Pixel`` will cause the particles to inherit the color of the mask at their spawn points. + +Once you click "OK", the mask will be generated and set to the +ParticleProcessMaterial, under ``Spawn`` and then ``Position`` + +.. image:: img/emission_shapes4.webp + +All of the values within this section have been automatically generated by the +"Load Emission Mask" menu, so they should generally be left alone. + +.. note:: An image should not be added to ``Point Texture`` or ``Color Texture`` directly. + The "Load Emission Mask" menu should always be used instead. diff --git a/tutorials/2d/particle_systems_2d.rst b/tutorials/2d/particle_systems_2d.rst index e2f815b250c..5e67109c47f 100644 --- a/tutorials/2d/particle_systems_2d.rst +++ b/tutorials/2d/particle_systems_2d.rst @@ -32,12 +32,20 @@ While GPUParticles2D is configured via a :ref:`class_ParticleProcessMaterial` (and optionally with a custom shader), the matching options are provided via node properties in CPUParticles2D (with the exception of the trail settings). -You can convert a GPUParticles2D node into a CPUParticles2D node by clicking on -the node in the inspector, selecting the 2D viewport, and selecting -**GPUParticles2D > Convert to CPUParticles2D** in the viewport toolbar. +Going forward there are no plans to add new features to CPUParticles2D, though +pull requests to add features already in GPUParticles2D will be accepted. For +that reason we recommend using GPUParticles3D unless you have an explicit reason +not to. + +You can convert a CPUParticles2D node into a GPUParticles2D node by clicking on +the node in the scene tree, selecting the 2D workspace, and selecting +**CPUParticles2D > Convert to GPUParticles2D** in the toolbar. .. image:: img/particles_convert.webp +It is also possible to convert a GPUParticles2D node to a CPUParticles2D node, +however there may be issues if you use GPU-only features. + The rest of this tutorial is going to use the GPUParticles2D node. First, add a GPUParticles2D node to your scene. After creating that node you will notice that only a white dot was created, and that there is a warning icon next to your GPUParticles2D node in the scene dock. This @@ -50,7 +58,7 @@ To add a process material to your particles node, go to ``Process Material`` in your inspector panel. Click on the box next to ``Material``, and from the dropdown menu select ``New ParticleProcessMaterial``. -.. image:: img/particles_material.png +.. image:: img/particles_material.webp Your GPUParticles2D node should now be emitting white points downward. @@ -67,7 +75,7 @@ spritesheet for particles. The texture is set via the **Texture** property: -.. image:: img/particles2.png +.. image:: img/particles2.webp .. _doc_particle_systems_2d_using_flipbook: @@ -208,7 +216,16 @@ at 2 frames per second. Note this does not slow down the particle system itself. Fract Delta ~~~~~~~~~~~ -This can be used to turn Fract Delta on or off. +Setting Fract Delta to ``true`` results in fractional delta calculation, +which has a smoother particles display effect. +This increased smoothness stems from higher accuracy. +The difference is more noticeable in systems with high randomness or fast-moving particles. +It helps maintain the visual consistency of the particle system, +making sure that each particle's motion aligns with its actual lifespan. +Without it, particles might appear to jump or move more than they should in a single frame +if they are emitted at a point within the frame. +The greater accuracy has a performance tradeoff, +particularly in systems with a higher amount of particles. Drawing parameters ------------------ @@ -248,240 +265,7 @@ This controls the order in which individual particles are drawn. ``Index`` means particles are drawn according to their emission order (default). ``Lifetime`` means they are drawn in order of remaining lifetime. -ParticleProcessMaterial settings --------------------------------- - -Direction -~~~~~~~~~ - -This is the base direction at which particles emit. The default is -``Vector3(1, 0, 0)`` which makes particles emit to the right. However, -with the default gravity settings, particles will go straight down. - -.. image:: img/direction1.png - -For this property to be noticeable, you need an *initial velocity* greater -than 0. Here, we set the initial velocity to 40. You'll notice that -particles emit toward the right, then go down because of gravity. - -.. image:: img/direction2.png - -Spread -~~~~~~ - -This parameter is the angle in degrees which will be randomly added in -either direction to the base ``Direction``. A spread of ``180`` will emit -in all directions (+/- 180). For spread to do anything the "Initial Velocity" -parameter must be greater than 0. - -.. image:: img/paranim3.gif - -Flatness -~~~~~~~~ - -This property is only useful for 3D particles. - -Gravity -~~~~~~~ - -The gravity applied to every particle. - -.. image:: img/paranim7.gif - -Initial Velocity -~~~~~~~~~~~~~~~~ - -Initial velocity is the speed at which particles will be emitted (in -pixels/sec). Speed might later be modified by gravity or other -accelerations (as described further below). - -.. image:: img/paranim4.gif - -Angular Velocity -~~~~~~~~~~~~~~~~ - -Angular velocity is the initial angular velocity applied to particles. - -Spin Velocity -~~~~~~~~~~~~~ - -Spin velocity is the speed at which particles turn around their center -(in degrees/sec). - -.. image:: img/paranim5.gif - -Orbit Velocity -~~~~~~~~~~~~~~ - -Orbit velocity is used to make particles turn around their center. - -.. image:: img/paranim6.gif - -Linear Acceleration -~~~~~~~~~~~~~~~~~~~ - -The linear acceleration applied to each particle. - -Radial Acceleration -~~~~~~~~~~~~~~~~~~~ - -If this acceleration is positive, particles are accelerated away from -the center. If negative, they are absorbed towards it. - -.. image:: img/paranim8.gif - -Tangential Acceleration -~~~~~~~~~~~~~~~~~~~~~~~ - -This acceleration will use the tangent vector to the center. Combining -with radial acceleration can do nice effects. - -.. image:: img/paranim9.gif - -Damping -~~~~~~~ - -Damping applies friction to the particles, forcing them to stop. It is -especially useful for sparks or explosions, which usually begin with a -high linear velocity and then stop as they fade. - -.. image:: img/paranim10.gif - -Angle -~~~~~ - -Determines the initial angle of the particle (in degrees). This parameter -is mostly useful randomized. - -.. image:: img/paranim11.gif - -Scale -~~~~~ - -Determines the initial scale of the particles. - -.. image:: img/paranim12.gif - -Color -~~~~~ - -Used to change the color of the particles being emitted. - -Hue Variation -~~~~~~~~~~~~~ - -The ``Variation`` value sets the initial hue variation applied to each -particle. The ``Variation Random`` value controls the hue variation -randomness ratio. - -.. _doc_particle_systems_2d_animation: - -Animation -~~~~~~~~~ - -.. note:: - - Particle flipbook animation is only effective if the CanvasItemMaterial used - on the GPUParticles2D or CPUParticles2D node has been - :ref:`configured accordingly `. - -To set up the particle flipbook for linear playback, set the **Speed Min** and **Speed Max** values to 1: - -.. figure:: img/particles_flipbook_configure_animation_speed.webp - :align: center - :alt: Setting up particle animation for playback during the particle's lifetime - - Setting up particle animation for playback during the particle's lifetime - -By default, looping is disabled. If the particle is done playing before its -lifetime ends, the particle will keep using the flipbook's last frame (which may -be fully transparent depending on how the flipbook texture is designed). If -looping is enabled, the animation will loop back to the first frame and resume -playing. - -Depending on how many images your sprite sheet contains and for how long your -particle is alive, the animation might not look smooth. The relationship between -particle lifetime, animation speed, and number of images in the sprite sheet is -this: - -.. note:: - - At an animation speed of ``1.0``, the animation will reach the last image - in the sequence just as the particle's lifetime ends. - - .. math:: - Animation\ FPS = \frac{Number\ of\ images}{Lifetime} - -If you wish the particle flipbook to be used as a source of random particle -textures for every particle, keep the speed values at 0 and set **Offset Max** -to 1 instead: - -.. figure:: img/particles_flipbook_configure_animation_offset.webp - :align: center - :alt: Setting up particle animation for random offset on emission - - Setting up particle animation for random offset on emission - -Note that the GPUParticles2D node's **Fixed FPS** also affects animation -playback. For smooth animation playback, it's recommended to set it to 0 so that -the particle is simulated on every rendered frame. If this is not an option for -your use case, set **Fixed FPS** to be equal to the effective framerate used by -the flipbook animation (see above for the formula). - -Emission Shapes ---------------- - -ParticleProcessMaterials allow you to set an Emission Mask, which dictates -the area and direction in which particles are emitted. -These can be generated from textures in your project. - -Ensure that a ParticleProcessMaterial is set, and the GPUParticles2D node is selected. -A "Particles" menu should appear in the Toolbar: - -.. image:: img/emission_shapes1.png - -Open it and select "Load Emission Mask": - -.. image:: img/emission_shapes2.png - -Then select which texture you want to use as your mask: - -.. image:: img/emission_shapes3.png - -A dialog box with several settings will appear. - -Emission Mask -~~~~~~~~~~~~~ - -Three types of emission masks can be generated from a texture: - -- Solid Pixels: Particles will spawn from any area of the texture, - excluding transparent areas. - -.. image:: img/emission_mask_solid.gif - -- Border Pixels: Particles will spawn from the outer edges of the texture. - -.. image:: img/emission_mask_border.gif - -- Directed Border Pixels: Similar to Border Pixels, but adds extra - information to the mask to give particles the ability to emit away - from the borders. Note that an ``Initial Velocity`` will need to - be set in order to utilize this. - -.. image:: img/emission_mask_directed_border.gif - -Emission Colors -~~~~~~~~~~~~~~~ - -``Capture from Pixel`` will cause the particles to inherit the color of the mask at their spawn points. - -Once you click "OK", the mask will be generated and set to the ParticleProcessMaterial, under the ``Emission Shape`` section: - -.. image:: img/emission_shapes4.png - -All of the values within this section have been automatically generated by the -"Load Emission Mask" menu, so they should generally be left alone. +Particle Process Material Settings +---------------------------------- -.. note:: An image should not be added to ``Point Texture`` or ``Color Texture`` directly. - The "Load Emission Mask" menu should always be used instead. +For information on the settings in the ParticleProcessMaterial see :ref:`this page`. diff --git a/tutorials/3d/csg_tools.rst b/tutorials/3d/csg_tools.rst index 3133c4147ff..278cb5dc7fc 100644 --- a/tutorials/3d/csg_tools.rst +++ b/tutorials/3d/csg_tools.rst @@ -15,9 +15,7 @@ Interior environments can be created by using inverted primitives. .. note:: The CSG nodes in Godot are mainly intended for prototyping. There is no built-in support for UV mapping or editing 3D polygons (though - extruded 2D polygons can be used with the CSGPolygon3D node). In - addition CSG can't reliably create meshes made up of multiple nodes - without holes. + extruded 2D polygons can be used with the CSGPolygon3D node). If you're looking for an easy to use level design tool for a project, you may want to use `FuncGodot `__ @@ -29,6 +27,7 @@ Interior environments can be created by using inverted primitives. :autoplay: :loop: :muted: + :align: default .. seealso:: @@ -119,6 +118,29 @@ the following, adapted from that library's `definition of "manifold" .. image:: img/csg_custom_mesh.png +Making an existing mesh manifold with Blender +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. UPDATE: This relies on a specific Blender addon. If it becomes unsupported, +.. we can remove this section. + +If you have an existing mesh that is not already manifold, you can make it +manifold using Blender. + +In Blender, install and enable the +`3D Print Toolbox `_ +addon. + +Select the mesh you want to make manifold. Open the sidebar by clicking on the arrow: + +.. image:: img/csg_manifold_step_1.webp + +In the **3D Print** tab, under **Clean Up**, click the **Make Manifold** button: + +.. image:: img/csg_manifold_step_2.webp + +The mesh should now be manifold, and can be used as a custom mesh. + CSGCombiner3D ~~~~~~~~~~~~~ diff --git a/tutorials/3d/environment_and_post_processing.rst b/tutorials/3d/environment_and_post_processing.rst index d044b301d79..6de440a3f87 100644 --- a/tutorials/3d/environment_and_post_processing.rst +++ b/tutorials/3d/environment_and_post_processing.rst @@ -226,8 +226,6 @@ There are several types of ambient light to choose from: set to a mode other than **Sky**. If the background mode is already **Sky**, this mode behaves identically to **Background**. -.. image:: img/environment_ambient.webp - When the ambient light mode is set to Sky or Background (and background is set to Sky), it's possible to blend between the ambient color and sky using the **Sky Contribution** property. This value is set to ``1.0`` by default, which @@ -481,6 +479,9 @@ parameters: make the :abbr:`SSAO (Screen-Space Ambient Occlusion)` effect visible in direct light. Values above ``0.0`` are not physically accurate, but some artists prefer this effect. +- **AO Channel Affect** The screen-space ambient occlusion intensity on + materials that have an AO texture defined. Values higher than ``0.0`` will + make the SSAO effect visible in areas darkened by AO textures. .. _doc_environment_and_post_processing_ssil: diff --git a/tutorials/3d/global_illumination/img/lightmap_gi_uvchannel.webp b/tutorials/3d/global_illumination/img/lightmap_gi_uvchannel.webp index f2c6518a504..335eee90088 100644 Binary files a/tutorials/3d/global_illumination/img/lightmap_gi_uvchannel.webp and b/tutorials/3d/global_illumination/img/lightmap_gi_uvchannel.webp differ diff --git a/tutorials/3d/global_illumination/using_lightmap_gi.rst b/tutorials/3d/global_illumination/using_lightmap_gi.rst index 9a24f166b56..74f85b0dd20 100644 --- a/tutorials/3d/global_illumination/using_lightmap_gi.rst +++ b/tutorials/3d/global_illumination/using_lightmap_gi.rst @@ -355,6 +355,11 @@ Tweaks with less noise. The difference is especially noticeable with emissive materials or areas that get little to no direct lighting. Each bake quality mode can be further adjusted in the Project Settings. +- **Supersampling:** This creates the lightmap at a higher resolution and then + downsamples it. This reduces noise and light leaking, and produces better + shadows with small scale details. However, using it will increase bake times and + memory usage during lightmap baking. The **Supersampling Factor** changes the size + the lightmap is rendered at before downsampling. - **Bounces:** The number of bounces to use for indirect lighting. The default value (``3``) is a good compromise between bake times and quality. Higher values will make light bounce around more times before it stops, which makes diff --git a/tutorials/3d/img/3d_toolbar.webp b/tutorials/3d/img/3d_toolbar.webp index b3d24bd9ebc..1596b49a217 100644 Binary files a/tutorials/3d/img/3d_toolbar.webp and b/tutorials/3d/img/3d_toolbar.webp differ diff --git a/tutorials/3d/img/csg_manifold_step_1.webp b/tutorials/3d/img/csg_manifold_step_1.webp new file mode 100644 index 00000000000..c2be3db384a Binary files /dev/null and b/tutorials/3d/img/csg_manifold_step_1.webp differ diff --git a/tutorials/3d/img/csg_manifold_step_2.webp b/tutorials/3d/img/csg_manifold_step_2.webp new file mode 100644 index 00000000000..9f9a6a65ce8 Binary files /dev/null and b/tutorials/3d/img/csg_manifold_step_2.webp differ diff --git a/tutorials/3d/img/environment_adjustments.webp b/tutorials/3d/img/environment_adjustments.webp index d2f7a007aa9..5ae2f43126e 100644 Binary files a/tutorials/3d/img/environment_adjustments.webp and b/tutorials/3d/img/environment_adjustments.webp differ diff --git a/tutorials/3d/img/environment_ambient.webp b/tutorials/3d/img/environment_ambient.webp deleted file mode 100644 index 1fcfcb6947a..00000000000 Binary files a/tutorials/3d/img/environment_ambient.webp and /dev/null differ diff --git a/tutorials/3d/img/environment_background1.webp b/tutorials/3d/img/environment_background1.webp index 0315fec0b60..4d67dac9a13 100644 Binary files a/tutorials/3d/img/environment_background1.webp and b/tutorials/3d/img/environment_background1.webp differ diff --git a/tutorials/3d/img/environment_camera.webp b/tutorials/3d/img/environment_camera.webp index 4834b38a14e..a91a9392651 100644 Binary files a/tutorials/3d/img/environment_camera.webp and b/tutorials/3d/img/environment_camera.webp differ diff --git a/tutorials/3d/img/environment_preview_sun_sky_dialog.webp b/tutorials/3d/img/environment_preview_sun_sky_dialog.webp index 8b6215e57e0..ece93cc5fe3 100644 Binary files a/tutorials/3d/img/environment_preview_sun_sky_dialog.webp and b/tutorials/3d/img/environment_preview_sun_sky_dialog.webp differ diff --git a/tutorials/3d/img/environment_preview_sun_sky_toggle.webp b/tutorials/3d/img/environment_preview_sun_sky_toggle.webp index a995c9927eb..c954254548a 100644 Binary files a/tutorials/3d/img/environment_preview_sun_sky_toggle.webp and b/tutorials/3d/img/environment_preview_sun_sky_toggle.webp differ diff --git a/tutorials/3d/img/environment_ssao_parameters.webp b/tutorials/3d/img/environment_ssao_parameters.webp index a04e2a5258c..b3aa8a698a9 100644 Binary files a/tutorials/3d/img/environment_ssao_parameters.webp and b/tutorials/3d/img/environment_ssao_parameters.webp differ diff --git a/tutorials/3d/img/environment_world.webp b/tutorials/3d/img/environment_world.webp index 24cbdb11c2b..4db1039c7e4 100644 Binary files a/tutorials/3d/img/environment_world.webp and b/tutorials/3d/img/environment_world.webp differ diff --git a/tutorials/3d/img/tuto_3d3.webp b/tutorials/3d/img/tuto_3d3.webp index e7d76e81e8a..53913f1799d 100644 Binary files a/tutorials/3d/img/tuto_3d3.webp and b/tutorials/3d/img/tuto_3d3.webp differ diff --git a/tutorials/3d/img/tuto_3d4.webp b/tutorials/3d/img/tuto_3d4.webp index d8385347f76..159879a6395 100644 Binary files a/tutorials/3d/img/tuto_3d4.webp and b/tutorials/3d/img/tuto_3d4.webp differ diff --git a/tutorials/3d/img/tuto_3d6.webp b/tutorials/3d/img/tuto_3d6.webp index 2046ea509d5..6b84e34fd00 100644 Binary files a/tutorials/3d/img/tuto_3d6.webp and b/tutorials/3d/img/tuto_3d6.webp differ diff --git a/tutorials/3d/img/tuto_3d6_1.webp b/tutorials/3d/img/tuto_3d6_1.webp index 35a3e157c4d..657b5e10364 100644 Binary files a/tutorials/3d/img/tuto_3d6_1.webp and b/tutorials/3d/img/tuto_3d6_1.webp differ diff --git a/tutorials/3d/img/tuto_3d6_2.webp b/tutorials/3d/img/tuto_3d6_2.webp index 88699e90910..c52ae72b09c 100644 Binary files a/tutorials/3d/img/tuto_3d6_2.webp and b/tutorials/3d/img/tuto_3d6_2.webp differ diff --git a/tutorials/3d/img/tuto_3d8.webp b/tutorials/3d/img/tuto_3d8.webp index 06d7ee1404c..9a7eadd63a4 100644 Binary files a/tutorials/3d/img/tuto_3d8.webp and b/tutorials/3d/img/tuto_3d8.webp differ diff --git a/tutorials/3d/img/tuto_3d9.webp b/tutorials/3d/img/tuto_3d9.webp index 2a33719dadf..d4fe0e3d807 100644 Binary files a/tutorials/3d/img/tuto_3d9.webp and b/tutorials/3d/img/tuto_3d9.webp differ diff --git a/tutorials/3d/img/tuto_3d_gizmo.webp b/tutorials/3d/img/tuto_3d_gizmo.webp index 8993064ef2a..da264cfc776 100644 Binary files a/tutorials/3d/img/tuto_3d_gizmo.webp and b/tutorials/3d/img/tuto_3d_gizmo.webp differ diff --git a/tutorials/3d/img/tuto_3d_updated_view_menu.webp b/tutorials/3d/img/tuto_3d_updated_view_menu.webp index dcbc3825bb9..6fc4bcc2151 100644 Binary files a/tutorials/3d/img/tuto_3d_updated_view_menu.webp and b/tutorials/3d/img/tuto_3d_updated_view_menu.webp differ diff --git a/tutorials/3d/introduction_to_3d.rst b/tutorials/3d/introduction_to_3d.rst index 5d81b660649..de9d0e47bc5 100644 --- a/tutorials/3d/introduction_to_3d.rst +++ b/tutorials/3d/introduction_to_3d.rst @@ -63,7 +63,6 @@ left to right: - **Scale Mode** (:kbd:`R`): Enables scaling and displays scaling gizmos in different axes for the selected nodes. See :ref:`doc_introduction_to_3d_space_and_manipulation` for more details. - - **Show the list of selectable nodes at the clicked position**: As the description suggests, this provides a list of selectable nodes at the clicked position as a context menu, if there is more than one node in the clicked area. @@ -76,14 +75,13 @@ left to right: any of the children are selected. Using :kbd:`Ctrl + G` ungroups them. Additionally, clicking the ungroup button in the scene tree performs the same action. +- **Ruler Mode** (:kbd:`M`): When enabled you can click and drag to measure distance in the scene + in meters. - **Use Local Space** (:kbd:`T`): If enabled, gizmos of a node are drawn using the current node's rotation angle instead of the :ref:`global viewport axes `. - **Use Snap** (:kbd:`Y`): If enabled, movement, and rotation snap to grid. Snapping can also temporarily be activated using :kbd:`Ctrl` while performing the action. The settings for changing snap options are explained below. -- **Project Camera Override**: This action temporarily replaces the active camera in the level - (e.g., the camera following the player) with the camera in the editor's viewport, allowing you - to move freely and inspect the level's different parts, while game is running. - **Toggle preview sunlight**: If no DirectionalLight3D exist in the scene, a preview of sunlight can be used as a light source. See :ref:`doc_introduction_to_3d_preview_environment_light` for more details. diff --git a/tutorials/3d/particles/img/particle_minmaxcurve.webp b/tutorials/3d/particles/img/particle_minmaxcurve.webp index c5e6b472291..b75307e351c 100644 Binary files a/tutorials/3d/particles/img/particle_minmaxcurve.webp and b/tutorials/3d/particles/img/particle_minmaxcurve.webp differ diff --git a/tutorials/3d/particles/process_material_properties.rst b/tutorials/3d/particles/process_material_properties.rst index 5b62200117f..4ee3604f296 100644 --- a/tutorials/3d/particles/process_material_properties.rst +++ b/tutorials/3d/particles/process_material_properties.rst @@ -18,6 +18,10 @@ the value of the property will be multiplied by the value of the curve at the cu in a particle's lifetime. Use the curve to change a property over the particle lifetime. Very complex behavior can be expressed this way. +.. note:: + This page covers how to use ParticleProcessMaterial for 3D scenes specifically. + For information on how to use it in a 2D Scene see :ref:`doc_particle_process_material_2d`. + Time ~~~~ diff --git a/tutorials/3d/spring_arm.rst b/tutorials/3d/spring_arm.rst index 40eee878de4..b13167baf2e 100644 --- a/tutorials/3d/spring_arm.rst +++ b/tutorials/3d/spring_arm.rst @@ -121,3 +121,4 @@ Run the game and notice that mouse movement now rotates the camera around the ch :autoplay: :loop: :muted: + :align: default diff --git a/tutorials/animation/animation_track_types.rst b/tutorials/animation/animation_track_types.rst index f6f4e0715aa..5392aa55534 100644 --- a/tutorials/animation/animation_track_types.rst +++ b/tutorials/animation/animation_track_types.rst @@ -157,7 +157,8 @@ diamonds connected to them by a line control curve's shape. .. image:: img/bezier_curves.webp -In the right click panel of the editor, you can select the handle mode: +While a keyframe is selected (not the handle), in the right click panel of the +editor, you can select the handle mode: - Free: Allows you to orient a manipulator in any direction without affecting the other's position. diff --git a/tutorials/animation/img/audio_track.webp b/tutorials/animation/img/audio_track.webp index 36fa3925285..a0b9ba2590d 100644 Binary files a/tutorials/animation/img/audio_track.webp and b/tutorials/animation/img/audio_track.webp differ diff --git a/tutorials/animation/img/bezier_curve_icon.webp b/tutorials/animation/img/bezier_curve_icon.webp index 993ca679e01..0a1e5c3b720 100644 Binary files a/tutorials/animation/img/bezier_curve_icon.webp and b/tutorials/animation/img/bezier_curve_icon.webp differ diff --git a/tutorials/animation/img/bezier_curves.webp b/tutorials/animation/img/bezier_curves.webp index 5b6f2dfa9e2..47c53404869 100644 Binary files a/tutorials/animation/img/bezier_curves.webp and b/tutorials/animation/img/bezier_curves.webp differ diff --git a/tutorials/animation/img/manipulator_modes.webp b/tutorials/animation/img/manipulator_modes.webp index ece9ebb56a7..b67025acecc 100644 Binary files a/tutorials/animation/img/manipulator_modes.webp and b/tutorials/animation/img/manipulator_modes.webp differ diff --git a/tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst b/tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst index 83c478d07e6..d7da97e19a3 100644 --- a/tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst +++ b/tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst @@ -34,17 +34,12 @@ Exporting glTF 2.0 files from Blender (recommended) There are 3 ways to export glTF files from Blender: - As a glTF binary file (``.glb``). -- As a glTF text-based file with embedded binary data (``.gltf`` file) - As a glTF text-based file with separate binary data and textures (``.gltf`` file + ``.bin`` file + textures). -glTF binary files (``.glb``) are the smallest of the three options. They include -the mesh and textures set up in Blender. When brought into Godot the textures -are part of the object's material file. - -glTF embedded files (``.gltf``) function the same way as binary files. They -don't provide extra functionality in Godot, and shouldn't be used since they -have a larger file size. +glTF binary files (``.glb``) are the smaller option. They include the mesh and +textures set up in Blender. When brought into Godot the textures are part of the +object's material file. There are two reasons to use glTF with the textures separate. One is to have the scene description in a text based format and the binary data in a separate @@ -108,9 +103,8 @@ Importing ``.blend`` files directly within Godot This avoids any issues related to packaging, such as different library versions that can cause incompatibilities or sandboxing restrictions. -From Godot 4.0 onwards, the editor can directly import ``.blend`` files by -calling `Blender `__'s glTF export functionality in a -transparent manner. +The editor can directly import ``.blend`` files by calling `Blender `__'s +glTF export functionality in a transparent manner. This allows you to iterate on your 3D scenes faster, as you can save the scene in Blender, alt-tab back to Godot then see your changes immediately. When @@ -121,8 +115,8 @@ To use ``.blend`` import, you must install Blender before opening the Godot editor (if opening a project that already contains ``.blend`` files). If you keep Blender installed at its default location, Godot should be able to detect its path automatically. If this isn't the case, configure the path to the -directory containing the Blender executable in the Editor Settings -(**Filesystem > Import > Blender > Blender 3 Path**). +Blender executable in the Editor Settings +(**Filesystem > Import > Blender > Blender Path**). If you keep ``.blend`` files within your project folder but don't want them to be imported by Godot, disable **Filesystem > Import > Blender > Enabled** in the @@ -154,11 +148,8 @@ Blender has built-in COLLADA support, but it does not work properly for the needs of game engines and shouldn't be used as-is. However, scenes exported with the built-in Collada support may still work for simple scenes without animation. -For complex scenes or scenes that contain animations, Godot provides a -`Blender plugin `_ -that will correctly export COLLADA scenes for use in Godot. This plugin is -not maintained or supported in Godot 4.x, but may still work depending on your -Godot and Blender versions. +For complex scenes or scenes that contain animations it is highly recommend to use +glTF instead. Importing OBJ files in Godot ---------------------------- @@ -179,7 +170,7 @@ There are 2 ways to use OBJ meshes in Godot: Blender 3.4 and later can export RGB vertex colors in OBJ files (this is a nonstandard extension of the OBJ format). Godot is able to import those - vertex colors since Godot 4.0, but they will not be displayed on the + vertex colors, but they will not be displayed on the material unless you enable **Vertex Color > Use As Albedo** on the material. Vertex colors from OBJ meshes keep their original color space once imported diff --git a/tutorials/assets_pipeline/importing_images.rst b/tutorials/assets_pipeline/importing_images.rst index 2570688cc0d..b96615e78b5 100644 --- a/tutorials/assets_pipeline/importing_images.rst +++ b/tutorials/assets_pipeline/importing_images.rst @@ -348,8 +348,10 @@ does not use the blue channel. A third option **Normal Map (RG Channels)** is *only* available in layered textures (:ref:`class_Cubemap`, :ref:`class_CubemapArray`, :ref:`class_Texture2DArray` and :ref:`class_Texture3D`). This forces all layers from the texture to be imported -with the RG color format to reduce memory usage, with only the red and green -channels preserved. This only has an effect on textures with the **VRAM Compressed** +with the RG color format, with only the red and green +channels preserved. :abbr:`RGTC (Red-Green Texture Compression)` compression is able to +preserve its detail much better, while using the same amount of memory as a standard +RGBA VRAM-compressed texture. This only has an effect on textures with the **VRAM Compressed** or **Basis Universal** compression modes. .. _doc_importing_images_mipmaps: @@ -424,9 +426,12 @@ displayed correctly: - In 2D, a :ref:`class_CanvasItemMaterial` will need to be created and configured to use the **Premul Alpha** blend mode on CanvasItems that use this - texture. -- In 3D, there is no support for premultiplied alpha blend mode yet, so this - option is only suited for 2D. + texture. In :ref:`custom canvas item shaders `, + ``render_mode blend_premul_alpha;`` should be used. +- In 3D, a :ref:`class_BaseMaterial3D` will need to be created and configured + to use the **Premul Alpha** blend mode on materials that use this texture. + In :ref:`custom spatial shaders `, + ``render_mode blend_premul_alpha;`` should be used. Process > Normal Map Invert Y ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tutorials/audio/audio_buses.rst b/tutorials/audio/audio_buses.rst index f1aa2c47d92..af07a7c8bf0 100644 --- a/tutorials/audio/audio_buses.rst +++ b/tutorials/audio/audio_buses.rst @@ -51,7 +51,7 @@ Audio buses Audio buses can be found in the bottom panel of the Godot editor: -.. image:: img/audio_buses1.png +.. image:: img/audio_buses1.webp An *audio bus* (also called an *audio channel*) can be considered a place that audio is channeled through on the way to playback through a device's speakers. @@ -67,7 +67,7 @@ the left. The destination bus can be specified for each of the non-master audio buses. Routing always passes audio from buses on the right to buses further to the left. This avoids infinite routing loops. -.. image:: img/audio_buses2.png +.. image:: img/audio_buses2.webp In the above image, the output of *Bus 2* has been routed to the *Master* bus. @@ -77,7 +77,7 @@ Playback of audio through a bus To test passing audio to a bus, create an AudioStreamPlayer node, load an AudioStream and select a target bus for playback: -.. image:: img/audio_buses3.png +.. image:: img/audio_buses3.webp Finally, toggle the **Playing** property to **On** and sound will flow. @@ -112,7 +112,7 @@ There is no need to disable buses manually when not in use. Godot detects that the bus has been silent for a few seconds and disables it (including all effects). -.. figure:: img/audio_buses5.png +.. figure:: img/audio_buses5.webp Disabled buses have a blue VU meter instead of a red-green one. diff --git a/tutorials/audio/img/audio_buses1.png b/tutorials/audio/img/audio_buses1.png deleted file mode 100644 index 33744a3ec56..00000000000 Binary files a/tutorials/audio/img/audio_buses1.png and /dev/null differ diff --git a/tutorials/audio/img/audio_buses1.webp b/tutorials/audio/img/audio_buses1.webp new file mode 100644 index 00000000000..bb0a05dc0b4 Binary files /dev/null and b/tutorials/audio/img/audio_buses1.webp differ diff --git a/tutorials/audio/img/audio_buses2.png b/tutorials/audio/img/audio_buses2.png deleted file mode 100644 index 7c5a5083004..00000000000 Binary files a/tutorials/audio/img/audio_buses2.png and /dev/null differ diff --git a/tutorials/audio/img/audio_buses2.webp b/tutorials/audio/img/audio_buses2.webp new file mode 100644 index 00000000000..036b1767264 Binary files /dev/null and b/tutorials/audio/img/audio_buses2.webp differ diff --git a/tutorials/audio/img/audio_buses3.png b/tutorials/audio/img/audio_buses3.png deleted file mode 100644 index 127cdc68161..00000000000 Binary files a/tutorials/audio/img/audio_buses3.png and /dev/null differ diff --git a/tutorials/audio/img/audio_buses3.webp b/tutorials/audio/img/audio_buses3.webp new file mode 100644 index 00000000000..3dc5861eedd Binary files /dev/null and b/tutorials/audio/img/audio_buses3.webp differ diff --git a/tutorials/audio/img/audio_buses5.png b/tutorials/audio/img/audio_buses5.png deleted file mode 100644 index 61e9ebc0001..00000000000 Binary files a/tutorials/audio/img/audio_buses5.png and /dev/null differ diff --git a/tutorials/audio/img/audio_buses5.webp b/tutorials/audio/img/audio_buses5.webp new file mode 100644 index 00000000000..392ad02759a Binary files /dev/null and b/tutorials/audio/img/audio_buses5.webp differ diff --git a/tutorials/audio/sync_with_audio.rst b/tutorials/audio/sync_with_audio.rst index 9cd090c75d6..1a8c42bb6cc 100644 --- a/tutorials/audio/sync_with_audio.rst +++ b/tutorials/audio/sync_with_audio.rst @@ -72,7 +72,7 @@ Add these two and it's possible to guess almost exactly when sound or music will GetNode("Player").Play(); } - public override void _Process(float _delta) + public override void _Process(double delta) { double time = (Time.GetTicksUsec() - _timeBegin) / 1000000.0d; time = Math.Max(0.0d, time - _timeDelay); @@ -140,7 +140,7 @@ Here is the same code as before using this approach: GetNode("Player").Play(); } - public override void _Process(float _delta) + public override void _Process(double delta) { double time = GetNode("Player").GetPlaybackPosition() + AudioServer.GetTimeSinceLastMix(); // Compensate for output latency. diff --git a/tutorials/editor/default_key_mapping.rst b/tutorials/editor/default_key_mapping.rst index c104fb49984..642373488ee 100644 --- a/tutorials/editor/default_key_mapping.rst +++ b/tutorials/editor/default_key_mapping.rst @@ -31,19 +31,19 @@ General editor actions +-----------------------+-------------------------------+------------------------------+----------------------------------+ | Action name | Windows, Linux | macOS | Editor setting | +=======================+===============================+==============================+==================================+ -| Open 2D Editor | :kbd:`Ctrl + F1` | :kbd:`Opt + 1` | ``editor/editor_2d`` | +| Open 2D Editor | :kbd:`Ctrl + F1` | :kbd:`Cmd + Ctrl + 1` | ``editor/editor_2d`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ -| Open 3D Editor | :kbd:`Ctrl + F2` | :kbd:`Opt + 2` | ``editor/editor_3d`` | +| Open 3D Editor | :kbd:`Ctrl + F2` | :kbd:`Cmd + Ctrl + 2` | ``editor/editor_3d`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ -| Open Script Editor | :kbd:`Ctrl + F3` | :kbd:`Opt + 3` | ``editor/editor_script`` | +| Open Script Editor | :kbd:`Ctrl + F3` | :kbd:`Cmd + Ctrl + 3` | ``editor/editor_script`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ | Search Help | :kbd:`F1` | :kbd:`Opt + Space` | ``editor/editor_help`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ | Distraction Free Mode | :kbd:`Ctrl + Shift + F11` | :kbd:`Cmd + Ctrl + D` | ``editor/distraction_free_mode`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ -| Next tab | :kbd:`Ctrl + Tab` | :kbd:`Cmd + Tab` | ``editor/next_tab`` | +| Next Scene Tab | :kbd:`Ctrl + Tab` | :kbd:`Ctrl + Tab` | ``editor/next_tab`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ -| Previous tab | :kbd:`Ctrl + Shift + Tab` | :kbd:`Cmd + Shift + Tab` | ``editor/prev_tab`` | +| Previous Scene Tab | :kbd:`Ctrl + Shift + Tab` | :kbd:`Ctrl + Shift + Tab` | ``editor/prev_tab`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ | Filter Files | :kbd:`Ctrl + Alt + P` | :kbd:`Opt + Cmd + P` | ``editor/filter_files`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ @@ -59,7 +59,7 @@ General editor actions +-----------------------+-------------------------------+------------------------------+----------------------------------+ | Save All Scenes | :kbd:`Ctrl + Shift + Alt + S` | :kbd:`Cmd + Shift + Opt + S` | ``editor/save_all_scenes`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ -| Quick Open | :kbd:`Shift + Alt + O` | :kbd:`Shift + Opt + O` | ``editor/quick_open`` | +| Quick Open | :kbd:`Shift + Alt + O` | :kbd:`Cmd + Ctrl + O` | ``editor/quick_open`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ | Quick Open Scene | :kbd:`Ctrl + Shift + O` | :kbd:`Cmd + Shift + O` | ``editor/quick_open_scene`` | +-----------------------+-------------------------------+------------------------------+----------------------------------+ diff --git a/tutorials/editor/external_editor.rst b/tutorials/editor/external_editor.rst index 31efb1e21dd..75cb2dbaf44 100644 --- a/tutorials/editor/external_editor.rst +++ b/tutorials/editor/external_editor.rst @@ -56,6 +56,8 @@ Some example **Exec Flags** for various editors include: +---------------------+-----------------------------------------------------+ | Sublime Text | ``{project} {file}:{line}:{column}`` | +---------------------+-----------------------------------------------------+ +| Visual Studio | ``/edit "file"`` | ++---------------------+-----------------------------------------------------+ .. note:: @@ -65,6 +67,9 @@ Some example **Exec Flags** for various editors include: For Emacs, you can call ``emacsclient`` instead of ``emacs`` if you use the server mode. + For Visual Studio, you will have to open the solution file ``.sln`` + manually to get access to the IDE features. Additionally, it will not go to a specific line. + Automatically reloading your changes ------------------------------------ To have the Godot Editor automatically reload any script that has been changed by an external text editor, diff --git a/tutorials/editor/img/editor_ui_intro_project_manager_13.webp b/tutorials/editor/img/editor_ui_intro_project_manager_13.webp new file mode 100644 index 00000000000..f41b5e28ac0 Binary files /dev/null and b/tutorials/editor/img/editor_ui_intro_project_manager_13.webp differ diff --git a/tutorials/editor/project_manager.rst b/tutorials/editor/project_manager.rst index 126522f1170..e7c3413f86f 100644 --- a/tutorials/editor/project_manager.rst +++ b/tutorials/editor/project_manager.rst @@ -144,3 +144,29 @@ you created. To remove a tag from your project manager it must be removed from all the projects it's used by. Once that's done close the project manager, open it up again, and the tag should be gone. + +Recovery Mode +------------- + +If a project is immediately crashing on startup, or crashing frequently during +editing it can be opened in recovery mode, to attempt to make it more stable +while looking for the source of the crashing to fix it. + +Usually a project should open in recovery mode automatically when you re-open it +after a crash. If it doesn't you can manually open recovery mode by selecting the +project in the project manager, to do that select the project from your list of +projects, click the dropdown button next to the edit node, and select ``Edit in +recovery mode``. + +.. image:: img/editor_ui_intro_project_manager_13.webp + +While in recovery mode the following are disabled: + +- Tool scripts +- Editor plugins +- GDExtension addons +- Automatic scene restoring +- Running the project + +It is recommended that you backup your project before editing it in recovery +mode. diff --git a/tutorials/export/changing_application_icon_for_windows.rst b/tutorials/export/changing_application_icon_for_windows.rst index 59f4f3d7955..a15d3c12286 100644 --- a/tutorials/export/changing_application_icon_for_windows.rst +++ b/tutorials/export/changing_application_icon_for_windows.rst @@ -7,10 +7,25 @@ By default, the exported project's icon will be the Godot icon. You will most likely want to change that for your project. There are two types of icons that can be changed on Windows: the file icon and the taskbar icon. -Creating an ICO file --------------------- +Creating a custom ICO file +-------------------------- -Windows does not use formats such as png or jpg for application icons. Instead, +.. note:: + + Since Godot 4.1, Godot can create an ICO file for you based on the icon file + defined in the Windows export preset. This icon file can be in PNG, WebP or + SVG format. If no icon is defined in the Windows export preset, the + :ref:`application/config/icon ` + project setting is used automatically instead. + + This means you no longer need to follow the steps in this section to + manually create an ICO file, unless you wish to have control over the icon + design depending on its displayed size. Note that even if Godot creates the + ICO file for you, you still need to + :ref:`set up rcedit ` + so that the file icon actually changes. + +Windows does not use formats such as PNG or JPEG for application icons. Instead, it uses a Windows-only format called ICO. You can create your application icon in any program but you will have to convert it to an ICO file using a program such as GIMP. @@ -49,15 +64,18 @@ is running. .. image:: img/icon_taskbar_icon.png To change the taskbar icon, go to -**Project → Project Settings → Application → Config → Windows Native Icon**. -Click on the folder icon and select your ICO file. +**Project > Project Settings > Application > Config**, make sure +**Advanced Settings** are enabled to see the setting, then go to +``Windows Native Icon``. Click on the folder icon and select your ICO file. -.. image:: img/icon_project_settings.png +.. image:: img/icon_project_settings.webp This setting only changes the icon for your exported game on Windows. To set the icon for macOS, use ``Macos Native Icon``. And for any other platform, use the ``Icon`` setting. +.. _doc_changing_application_icon_for_windows_changing_the_file_icon: + Changing the file icon ---------------------- @@ -66,13 +84,6 @@ external tools using `godoticon `__. Changing the file icon this way should work for executables containing an embedded PCK. -.. warning:: - - There are `known issues `__ - when changing the application icon in executables that embed a PCK file. - It's recommended to avoid using rcedit for now if you choose to enable the - **Embed Pck** option for your Windows export preset in the Export dialog. - The file icon is the icon of the executable that you click on to start the project. @@ -84,7 +95,7 @@ You can download it `here `_. After downloading, you need to tell Godot the path to the rcedit executable on your computer. -Go to **Editor → Editor Settings → Export → Windows**. +Go to **Editor > Editor Settings > Export > Windows**. Click on the folder icon for the **rcedit** entry. Navigate to and select the rcedit executable. @@ -93,16 +104,16 @@ Navigate to and select the rcedit executable. Linux and macOS users will also need to install `WINE `_ to use rcedit. - On macOS 10.15 (Catalina) or later, make sure to use a 64-bit version of - both WINE and rcedit since 32-bit applications aren't supported anymore. + On macOS, make sure to use a 64-bit version of both WINE and rcedit since + 32-bit applications aren't supported anymore. -.. image:: img/icon_rcedit.png +.. image:: img/icon_rcedit.webp You should now have everything in place to change the file icon. To do that, you will need to specify the icon when exporting. -Go to **Project → Export**. Assuming you have already created +Go to **Project > Export**. Assuming you have already created a Windows Desktop preset, select your icon in ICO format in -the **Application → Icon** field. +the **Application > Icon** field. .. warning:: @@ -114,7 +125,7 @@ the **Application → Icon** field. If you provide invalid metadata in the export preset, the application icon won't change as rcedit will fail to change the executable's metadata. -.. image:: img/icon_export_settings.png +.. image:: img/icon_export_settings.webp .. note:: diff --git a/tutorials/export/exporting_for_android.rst b/tutorials/export/exporting_for_android.rst index ad4eaddc7cb..e8b8edf04e7 100644 --- a/tutorials/export/exporting_for_android.rst +++ b/tutorials/export/exporting_for_android.rst @@ -61,9 +61,9 @@ Download and install the Android SDK. Setting it up in Godot ---------------------- -Enter the Editor Settings screen. This screen contains the editor -settings for the user account in the computer (it's independent of the -project). +Enter the Editor Settings screen (under the Godot tab for macOS, or the Editor tab +for other platforms). This screen contains the editor settings for the user +account in the computer (it's independent of the project). .. image:: img/editorsettings.png diff --git a/tutorials/export/exporting_for_web.rst b/tutorials/export/exporting_for_web.rst index d260a293247..0173e9ebd56 100644 --- a/tutorials/export/exporting_for_web.rst +++ b/tutorials/export/exporting_for_web.rst @@ -17,14 +17,40 @@ in the user's browser. .. attention:: Projects written in C# using Godot 4 currently cannot be exported to the - web. To use C# on web platforms, use Godot 3 instead. + web. See `this blog post `__ + for more information. + + To use C# on web platforms, use Godot 3 instead. .. tip:: Use the browser-integrated developer console, usually opened - with :kbd:`F12` (:kbd:`Cmd + Option + I` on macOS), to view + with :kbd:`F12` or :kbd:`Ctrl + Shift + I` (:kbd:`Cmd + Option + I` on macOS), to view **debug information** like JavaScript, engine, and WebGL errors. + If the shortcut doesn't work, it's because Godot actually captures the input. + You can still open the developer console by accessing the browser's menu. + +.. note:: + + Due to security concerns with ``SharedArrayBuffer`` due to various exploits, + the use of multiple threads for the Web platform has multiple drawbacks, + including requiring specific server-side headers and complete cross-origin isolation + (meaning no ads, nor third-party integrations on the website hosting your game). + + Since Godot 4.3, Godot supports exporting your game on a single thread, which + solves this issue. While it has some drawbacks on its own (it cannot use threads, and is + not as performant as the multi-threaded export), it doesn't require as much overhead to install. + It is also more compatible overall with stores like `itch.io ` or Web publishers like + `Poki `__ or `CrazyGames `__. The single-threaded export + works very well on macOS and iOS too, where it always had compatibility issues with multiple threads + exports. + + For these reasons, it is the preferred and now default way to export your games on the Web. + + For more information, see `this blog post about single-threaded Web export + `__. + .. seealso:: See the @@ -58,6 +84,27 @@ versions supporting WebGL 2.0. Note that Safari has several issues with WebGL 2.0 support that other browsers don't have, so we recommend using a Chromium-based browser or Firefox if possible. +Mobile considerations +--------------------- + +The Web export can run on mobile platforms with some caveats. While native +:ref:`Android ` and :ref:`iOS ` +exports will always perform better by a significant margin, the Web export +allows people to run your project without going through app stores. + +Remember that CPU and GPU performance is at a premium when running on mobile devices. +This is even more the case when running a project exported to Web (as it's +WebAssembly instead of native code). See :ref:`doc_performance` section of the +documentation for advice on optimizing your project. If your project runs on +platforms other than Web, you can use :ref:`doc_feature_tags` to apply +low-end-oriented settings when running the project exported to Web. + +To speed up loading times on mobile devices, you should also +:ref:`compile an optimized export template ` +with unused features disabled. Depending on the features used by your project, +this can reduce the size of the WebAssembly payload significantly, +making it faster to download and initialize (even when cached). + .. _doc_exporting_for_web_audio_playback: Audio playback @@ -232,6 +279,17 @@ player to click, tap or press a key/button to enable audio, for instance when di .. warning:: Access to microphone requires a :ref:`secure context `. +.. warning:: + + Since Godot 4.3, by default Web exports will use samples instead of streams + to play audio. + + This is due to the way browsers prefer to play audio and the lack of processing power + available when exporting Web games with the **Use Threads** export option off. + + Please note that audio effects aren't yet implemented for samples. + + Networking ~~~~~~~~~~ @@ -275,13 +333,6 @@ to remap them based on model/vendor/OS due to privacy considerations. .. warning:: Requires a :ref:`secure context `. -Boot splash is not displayed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The default HTML page does not display the boot splash while loading. However, -the image is exported as a PNG file, so :ref:`custom HTML pages ` -can display it. - .. _doc_exporting_for_web_serving_the_files: Serving the files @@ -293,8 +344,8 @@ used, see :ref:`doc_customizing_html5_shell`. .. warning:: - If either :ref:`thread support or extension support ` - are enabled, the exported project will require + Only when exporting with **Use Threads**, to ensure low audio latency and the + ability to use :ref:`class_Thread` in web exports, Godot 4 web exports use `SharedArrayBuffer `__. This requires a :ref:`secure context `, while also requiring the following CORS headers to be set when serving the files: @@ -325,9 +376,7 @@ The other exported files are served as they are, next to the ``.html`` file, names unchanged. The ``.wasm`` file is a binary WebAssembly module implementing the engine. The ``.pck`` file is the Godot main pack containing your game. The ``.js`` file contains start-up code and is used by the ``.html`` file to access -the engine. The ``.png`` file contains the boot splash image. It is not used in -the default HTML page, but is included for -:ref:`custom HTML pages `. +the engine. The ``.png`` file contains the boot splash image. The ``.pck`` file is binary, usually delivered with the MIME-type :mimetype:`application/octet-stream`. The ``.wasm`` file is delivered as diff --git a/tutorials/export/img/icon_export_settings.png b/tutorials/export/img/icon_export_settings.png deleted file mode 100644 index bcb29dfa2fd..00000000000 Binary files a/tutorials/export/img/icon_export_settings.png and /dev/null differ diff --git a/tutorials/export/img/icon_export_settings.webp b/tutorials/export/img/icon_export_settings.webp new file mode 100644 index 00000000000..aa1b22743ad Binary files /dev/null and b/tutorials/export/img/icon_export_settings.webp differ diff --git a/tutorials/export/img/icon_project_settings.png b/tutorials/export/img/icon_project_settings.png deleted file mode 100644 index 7ab9f3bbee5..00000000000 Binary files a/tutorials/export/img/icon_project_settings.png and /dev/null differ diff --git a/tutorials/export/img/icon_project_settings.webp b/tutorials/export/img/icon_project_settings.webp new file mode 100644 index 00000000000..2af40826898 Binary files /dev/null and b/tutorials/export/img/icon_project_settings.webp differ diff --git a/tutorials/export/img/icon_rcedit.png b/tutorials/export/img/icon_rcedit.png deleted file mode 100644 index 38511c29360..00000000000 Binary files a/tutorials/export/img/icon_rcedit.png and /dev/null differ diff --git a/tutorials/export/img/icon_rcedit.webp b/tutorials/export/img/icon_rcedit.webp new file mode 100644 index 00000000000..bdd6adeaf60 Binary files /dev/null and b/tutorials/export/img/icon_rcedit.webp differ diff --git a/tutorials/i18n/internationalizing_games.rst b/tutorials/i18n/internationalizing_games.rst index f5445d995e1..683622e2710 100644 --- a/tutorials/i18n/internationalizing_games.rst +++ b/tutorials/i18n/internationalizing_games.rst @@ -58,6 +58,44 @@ Select the resource to be remapped then add some alternatives for each locale. the current language, making it ideal for things like multiplayer chat where the text language may not match the client's language. +Automatically setting a language +-------------------------------- +It is recommended to default to the user's preferred language which can be obtained via :ref:`OS.get_locale_language() `. +If your game is not available in that language, it will fall back to the :ref:`Fallback ` +in **Project Settings > Internationalization > Locale**, or to ``en`` if empty. +Nevertheless letting players change the language in game is recommended for various reasons (e.g. translation quality or player preference). + +.. tabs:: + .. code-tab:: gdscript + + var language = "automatic" + # Load here language from the user settings file + if language == "automatic": + var preferred_language = OS.get_locale_language() + TranslationServer.set_locale(preferred_language) + else: + TranslationServer.set_locale(language) + +Locale vs. language +------------------- +A :ref:`locale ` is commonly a combination of a language with a region or country, but can also contain information like a script or a variant. + +Examples: + +- ``en``: English language +- ``en_GB``: English in Great Britain / British English +- ``en_US``: English in the USA / American English +- ``en_DE``: English in Germany + +Indie games generally only need to care about language, but read on for more information. + +Why locales exist can be illustrated through the USA and Great Britain. Both speak the same language (English), yet differ in many aspects: +- Spelling: E.g. gray (USA), grey (GB) +- Use of words: E.g. eggplant (USA), aubergine (GB) +- Units or currencies: E.g. feet/inches (USA), metres/cm (GB) + +It can get more complex however. Imagine you offer different content in Europe and in China (e.g. in an MMO). You will need to translate each of those content variations into many languages and store and load them accordingly. + Converting keys to text ----------------------- diff --git a/tutorials/inputs/controllers_gamepads_joysticks.rst b/tutorials/inputs/controllers_gamepads_joysticks.rst index 05ed81bd3fb..b541aa60dbc 100644 --- a/tutorials/inputs/controllers_gamepads_joysticks.rst +++ b/tutorials/inputs/controllers_gamepads_joysticks.rst @@ -3,9 +3,7 @@ Controllers, gamepads, and joysticks ==================================== -Godot supports hundreds of controller models thanks to the community-sourced -`SDL game controller database `__. - +Godot supports hundreds of controller models out of the box. Controllers are supported on Windows, macOS, Linux, Android, iOS, and HTML5. Note that more specialized devices such as steering wheels, rudder pedals and @@ -306,9 +304,9 @@ After updating the controller's firmware, unpair the controller and pair it agai with your PC if you are using the controller in wireless mode. If buttons are incorrectly mapped, this may be due to an erroneous mapping from -the `SDL game controller database `__. -You can contribute an updated mapping to be included in the next Godot version -by opening a pull request on the linked repository. +the SDL game controller database used by Godot or the +`Godot game controller database `__. +In this case, you will need to create a custom mapping for your controller. There are many ways to create mappings. One option is to use the mapping wizard in the `official Joypads demo `__. @@ -336,6 +334,10 @@ additional controller mappings, you can add them by calling :ref:`Input.add_joy_mapping() ` as early as possible in a script's ``_ready()`` function. +Once you are satisfied with the custom mapping, you can contribute it for +the next Godot version by opening a pull request on the +`Godot game controller database `__. + My controller works on a given platform, but not on another platform. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tutorials/inputs/inputevent.rst b/tutorials/inputs/inputevent.rst index 06ade4628ba..1dcab4d9bb7 100644 --- a/tutorials/inputs/inputevent.rst +++ b/tutorials/inputs/inputevent.rst @@ -123,8 +123,15 @@ and SubViewports. .. image:: img/input_event_scene_flow.webp -This order doesn't apply to :ref:`Control._gui_input() `, which uses -a different method based on event location or focused Control. +.. note:: + + This order doesn't apply to :ref:`Control._gui_input() `, which uses + a different method based on event location or focused Control. GUI **mouse** events also travel + up the scene tree, subject to the :ref:`Control.mouse_filter ` + restrictions described above. However, since these events target specific Controls, only direct ancestors of + the targeted Control node receive the event. GUI **keyboard and joypad** events *do not* travel + up the scene tree, and can only be handled by the Control that received them. Otherwise, they will be + propagated as non-GUI events through :ref:`Node._unhandled_input() `. Since Viewports don't send events to other :ref:`SubViewports `, one of the following methods has to be used: @@ -134,9 +141,6 @@ methods has to be used: :ref:`Node._input() ` or :ref:`Control._gui_input() `. 2. Implement event propagation based on the individual requirements. -GUI events also travel up the scene tree but, since these events target -specific Controls, only direct ancestors of the targeted Control node receive the event. - In accordance with Godot's node-based design, this enables specialized child nodes to handle and consume particular events, while their ancestors, and ultimately the scene root, can provide more diff --git a/tutorials/io/runtime_file_loading_and_saving.rst b/tutorials/io/runtime_file_loading_and_saving.rst index c2978f06fc8..eaabd78f98d 100644 --- a/tutorials/io/runtime_file_loading_and_saving.rst +++ b/tutorials/io/runtime_file_loading_and_saving.rst @@ -168,8 +168,8 @@ Example of loading an image and displaying it in a :ref:`class_TextureRect` node Audio/video files ----------------- -Godot supports loading Ogg Vorbis audio at runtime. Note that not *all* files -with an ``.ogg`` extension may be Ogg Vorbis files. Some may be Ogg Theora +Godot supports loading Ogg Vorbis, MP3, and WAV audio at runtime. Note that not *all* +files with an ``.ogg`` extension are Ogg Vorbis files. Some may be Ogg Theora videos, or contain Opus audio within an Ogg container. These files will **not** load correctly as audio files in Godot. @@ -211,17 +211,6 @@ Example of loading an Ogg Theora video file in a :ref:`class_VideoStreamPlayer` // before this property is set, so call `Play()` after setting `Stream`. GetNode("VideoStreamPlayer").Play(); -.. note:: - - Godot doesn't support runtime loading of MP3 or WAV files yet. Until this is - implemented, it's feasible to implement runtime WAV loading using a script - since :ref:`class_AudioStreamWAV`'s ``data`` property is exposed to - scripting. - - It's still possible to *save* WAV files using - :ref:`AudioStreamWAV.save_to_wav `, which is useful - for procedurally generated audio or microphone recordings. - .. _doc_runtime_file_loading_and_saving_3d_scenes: 3D scenes diff --git a/tutorials/migrating/upgrading_to_godot_4.rst b/tutorials/migrating/upgrading_to_godot_4.rst index fa6255647ed..c385e80850f 100644 --- a/tutorials/migrating/upgrading_to_godot_4.rst +++ b/tutorials/migrating/upgrading_to_godot_4.rst @@ -228,6 +228,10 @@ a ``3D`` suffix to the old name: +-----------------------------------------+-------------------------------------------+ | ARVRServer | XRServer | +-----------------------------------------+-------------------------------------------+ +| BoxShape | BoxShape3D | ++-----------------------------------------+-------------------------------------------+ +| CapsuleShape | CapsuleShape3D | ++-----------------------------------------+-------------------------------------------+ | CubeMesh | BoxMesh | +-----------------------------------------+-------------------------------------------+ | EditorSpatialGizmo | EditorNode3DGizmo | @@ -414,11 +418,20 @@ table to find its new name. - AcceptDialog's ``set_autowrap()`` is now ``set_autowrap_mode()``. - AnimationNode's ``process()`` is now ``_process()`` (note the leading underscore, which denotes a virtual method). +- AnimationPlayer's ``add_animation()`` is now ``add_animation_library()`` and now uses an :ref:`class_AnimationLibrary`. +- AnimationTree's ``set_process_mode()`` is now ``set_process_callback()``. +- Array's ``empty()`` is now ``is_empty()``. +- Array's ``invert()`` is now ``reverse()``. +- Array's ``remove()`` is now ``remove_at()``. - AStar2D and AStar3D's ``get_points()`` is now ``get_points_id()``. - BaseButton's ``set_event()`` is now ``set_shortcut()``. +- Camera2D's ``get_h_offset()`` is now ``get_drag_horizontal_offset()``. - Camera2D's ``get_v_offset()`` is now ``get_drag_vertical_offset()``. +- Camera2D's ``set_h_offset()`` is now ``set_drag_horizontal_offset()``. - Camera2D's ``set_v_offset()`` is now ``set_drag_vertical_offset()``. +- CanvasItem's ``raise()`` is now ``move_to_front()``. - CanvasItem's ``update()`` is now ``queue_redraw()``. +- Control's ``get_stylebox()`` is now ``get_theme_stylebox()``. - Control's ``set_tooltip()`` is now ``set_tooltip_text()``. - EditorNode3DGizmoPlugin's ``create_gizmo()`` is now ``_create_gizmo()`` (note the leading underscore, which denotes a virtual method). @@ -426,24 +439,35 @@ table to find its new name. - FileDialog's ``get_mode()`` is now ``get_file_mode()``. - FileDialog's ``set_mode()`` is now ``set_file_mode()``. - GraphNode's ``get_offset()`` is now ``get_position_offset()``. -- GridMap's ``world_to_map()`` is now ``local_to_map()``. - GridMap's ``map_to_world()`` is now ``map_to_local()``. +- GridMap's ``world_to_map()`` is now ``local_to_map()``. - Image's ``get_rect()`` is now ``get_region()``. +- ImmediateGeometry's ``set_normal()`` is now ``surface_set_normal()``. +- ImmediateMesh's ``set_color()`` is now ``surface_set_color()``. +- ImmediateMesh's ``set_uv()`` is now ``surface_set_uv()``. - ItemList's ``get_v_scroll()`` is now ``get_v_scroll_bar()``. - MultiPlayerAPI's ``get_network_connected_peers()`` is now ``get_peers()``. - MultiPlayerAPI's ``get_network_peer()`` is now ``get_peer()``. - MultiPlayerAPI's ``get_network_unique_id()`` is now ``get_unique_id()``. - MultiPlayerAPI's ``has_network_peer()`` is now ``has_multiplayer_peer()``. +- MultiplayerAPI's ``is_refusing_new_network_connections()`` is now ``is_refusing_new_connections()``. - PacketPeerUDP's ``is_listening()`` is now ``is_bound()``. - PacketPeerUDP's ``listen()`` is now ``bind()``. - ParticleProcessMaterial's ``set_flag()`` is now ``set_particle_flag()``. +- PhysicsTestMotionResult2D's ``get_motion()`` is now ``get_travel()``. +- RenderingServer's ``get_render_info()`` is now ``get_rendering_info()``. - ResourceFormatLoader's ``get_dependencies()`` is now ``_get_dependencies()`` (note the leading underscore, which denotes a virtual method). +- ResourceFormatLoader's ``load()`` is now ``_load()``. - SceneTree's ``change_scene()`` is now ``change_scene_to_file()``. - Shortcut's ``is_valid()`` is now ``has_valid_event()``. -- TileMap's ``world_to_map()`` is now ``local_to_map()``. - TileMap's ``map_to_world()`` is now ``map_to_local()``. +- TileMap's ``world_to_map()`` is now ``local_to_map()``. - Transform2D's ``xform()`` is ``mat * vec`` and ``xform_inv()`` is ``vec * mat``. +- XRPositionalTracker's ``get_name()`` is now ``get_tracker_name()``. +- XRPositionalTracker's ``get_type()`` is now ``get_tracker_type()``. +- XRPositionalTracker's ``_set_name()`` is now ``get_tracker_name()``. + **Properties** @@ -454,11 +478,29 @@ table to find its new name. and PathFollow3D's ``set_offset()`` and ``get_offset()`` must be renamed to ``set_progress()`` and ``get_progress()`` respectively. +- AudioServer's ``device`` is now ``output_device``. +- BaseButton's ``group`` is now ``button_group``. +- Camera3D's ``zfar`` is now ``far``. +- Camera3D's ``znear`` is now ``near`` - Control's ``margin`` is now ``offset``. +- InputEventMouseButton's ``doubleclick`` is now ``double_click``. +- InputEventWithModifiers's ``alt`` is now ``alt_pressed``. +- InputEventWithModifiers's ``command`` is now ``command_pressed``. +- InputEventWithModifiers's ``control`` is now ``ctrl_pressed``. +- InputEventWithModifiers's ``meta`` is now ``meta_pressed``. +- InputEventWithModifiers's ``shift`` is now ``shift_pressed``. - Label's ``percent_visible`` is now ``visible_ratio``. - MultiPlayerAPI's ``refuse_new_network_connections`` is now ``refuse_new_connections``. +- Node's ``filename`` is now ``scene_file_path``. +- PathFollow2D's ``rotate`` is now ``rotates``. - PathFollow2D and PathFollow3D's ``offset`` is now ``progress``. +- RectangleShape2D's ``extents`` is now ``size`` - TextureProgressBar's ``percent_visible`` is now ``show_percentage``. +- Theme's ``off`` is now ``unchecked``. +- Theme's ``ofs`` is now ``offset``. +- Theme's ``on`` is now ``checked``. +- Window's ``window_title`` is now ``title``. +- WorldMarginShape2D's ``d`` is now ``distance``. - The ``extents`` property on CSG nodes and VoxelGI will have to be replaced with ``size``, with the set value halved (as they're no longer half-extents). This also affects its setter/getter methods ``set_extents()`` and @@ -467,6 +509,7 @@ table to find its new name. ``Engine.is_editor_hint()`` *method*. This is because it's read-only, and properties in Godot are not used for read-only values. + **Enums** - CPUParticles2D's ``FLAG_MAX`` is now ``PARTICLE_FLAG_MAX``. @@ -660,6 +703,10 @@ converter doesn't support updating existing setups: +---------------------+-----------------------+ | | DynamicFontData | FontFile | | +---------------------+-----------------------+----------------------------------------------------------------------------+ +| ClippedCamera | Camera2D or Camera3D | Camera's pyramid shape was moved to :ref:'class_Camera3D'. | ++---------------------+-----------------------+ | +| InterpolatedCamera | Camera2D or Camera3D | | ++---------------------+-----------------------+----------------------------------------------------------------------------+ | Navigation2D | Node2D | Replaced by :ref:`other 2D Navigation nodes `. | +---------------------+-----------------------+----------------------------------------------------------------------------+ | Navigation3D | Node3D | Replaced by :ref:`other 3D Navigation nodes `. | diff --git a/tutorials/navigation/img/nav_link_debug_visuals.webp b/tutorials/navigation/img/nav_link_debug_visuals.webp new file mode 100644 index 00000000000..dfe01214714 Binary files /dev/null and b/tutorials/navigation/img/nav_link_debug_visuals.webp differ diff --git a/tutorials/navigation/navigation_using_navigationlinks.rst b/tutorials/navigation/navigation_using_navigationlinks.rst index c2dda415da9..e2a51a76d81 100644 --- a/tutorials/navigation/navigation_using_navigationlinks.rst +++ b/tutorials/navigation/navigation_using_navigationlinks.rst @@ -35,11 +35,12 @@ The polygon search radius can be configured globally in the ProjectSettings unde or set for each navigation **map** individually using the ``NavigationServer.map_set_link_connection_radius()`` function. Both ``start_position`` and ``end_position`` have debug markers in the Editor. -The visible radius of a position shows the polygon search radius. -All navigation mesh polygons inside are compared and the closest is picked for the edge connection. -If no valid polygon is found within the search radius the navigation link gets disabled. +The arrows indicate which direction the link can be travelled across, and the visible radius of +a position shows the polygon search radius. All navigation mesh polygons inside are compared and +the closest is picked for the edge connection. If no valid polygon is found within the search +radius the navigation link gets disabled. -.. image:: img/nav_link_debug_visuals.png +.. image:: img/nav_link_debug_visuals.webp The link debug visuals can be changed in the Editor :ref:`ProjectSettings` under ``debug/shapes/navigation``. The visibility of the debug can also be controlled in the Editor 3D Viewport gizmo menu. diff --git a/tutorials/performance/using_multiple_threads.rst b/tutorials/performance/using_multiple_threads.rst index b355fd49c0b..1943162e782 100644 --- a/tutorials/performance/using_multiple_threads.rst +++ b/tutorials/performance/using_multiple_threads.rst @@ -141,9 +141,17 @@ wait until the thread is done (if not done yet), then properly dispose of it. .. warning:: - Creating threads at runtime is slow on Windows and should be avoided to - prevent stuttering. Semaphores, explained later on this page, should be used - instead. + Creating threads is a slow operation, especially on Windows. To avoid + unnecessary performance overhead, make sure to create threads before heavy + processing is needed instead of creating threads just-in-time. + + For example, if you need multiple threads during gameplay, you can create + threads while the level is loading and only actually start processing with + them later on. + + Additionally, locking and unlocking of mutexes can also be an expensive + operation. Locking should be done carefully; avoid locking too often (or for + too long). Mutexes ------- diff --git a/tutorials/physics/img/physics_layer_names.png b/tutorials/physics/img/physics_layer_names.png deleted file mode 100644 index 583d81e4c1c..00000000000 Binary files a/tutorials/physics/img/physics_layer_names.png and /dev/null differ diff --git a/tutorials/physics/img/physics_layer_names.webp b/tutorials/physics/img/physics_layer_names.webp new file mode 100644 index 00000000000..841ba8239dd Binary files /dev/null and b/tutorials/physics/img/physics_layer_names.webp differ diff --git a/tutorials/physics/img/player_coll_shape.png b/tutorials/physics/img/player_coll_shape.png deleted file mode 100644 index 316f7064d1f..00000000000 Binary files a/tutorials/physics/img/player_coll_shape.png and /dev/null differ diff --git a/tutorials/physics/img/player_coll_shape.webp b/tutorials/physics/img/player_coll_shape.webp new file mode 100644 index 00000000000..7f3db95d5c3 Binary files /dev/null and b/tutorials/physics/img/player_coll_shape.webp differ diff --git a/tutorials/physics/img/player_collision_layers.png b/tutorials/physics/img/player_collision_layers.png deleted file mode 100644 index 14790e0c52f..00000000000 Binary files a/tutorials/physics/img/player_collision_layers.png and /dev/null differ diff --git a/tutorials/physics/img/player_collision_layers.webp b/tutorials/physics/img/player_collision_layers.webp new file mode 100644 index 00000000000..19720ce8469 Binary files /dev/null and b/tutorials/physics/img/player_collision_layers.webp differ diff --git a/tutorials/physics/img/player_collision_mask.png b/tutorials/physics/img/player_collision_mask.png deleted file mode 100644 index 1390a74dbb4..00000000000 Binary files a/tutorials/physics/img/player_collision_mask.png and /dev/null differ diff --git a/tutorials/physics/img/player_collision_mask.webp b/tutorials/physics/img/player_collision_mask.webp new file mode 100644 index 00000000000..85bb4a199e7 Binary files /dev/null and b/tutorials/physics/img/player_collision_mask.webp differ diff --git a/tutorials/physics/physics_introduction.rst b/tutorials/physics/physics_introduction.rst index fe42a3c6a52..981c7924f6b 100644 --- a/tutorials/physics/physics_introduction.rst +++ b/tutorials/physics/physics_introduction.rst @@ -78,7 +78,7 @@ These nodes allow you to draw the shape directly in the editor workspace. the ``Node2D`` scale handles. Scaling a shape can result in unexpected collision behavior. -.. image:: img/player_coll_shape.png +.. image:: img/player_coll_shape.webp Physics process callback ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -132,9 +132,9 @@ These properties can be configured via code, or by editing them in the Inspector Keeping track of what you're using each layer for can be difficult, so you may find it useful to assign names to the layers you're using. Names can -be assigned in **Project Settings > Layer Names**. +be assigned in **Project Settings > Layer Names > 2D Physics**. -.. image:: img/physics_layer_names.png +.. image:: img/physics_layer_names.webp GUI example ^^^^^^^^^^^ @@ -149,8 +149,8 @@ place each node type in its respective layer using the "Layer" property. Then set each node's "Mask" property by selecting the layers it should interact with. For example, the Player's settings would look like this: -.. image:: img/player_collision_layers.png -.. image:: img/player_collision_mask.png +.. image:: img/player_collision_layers.webp +.. image:: img/player_collision_mask.webp .. _doc_physics_introduction_collision_layer_code_example: diff --git a/tutorials/platform/web/customizing_html5_shell.rst b/tutorials/platform/web/customizing_html5_shell.rst index 8cc954b573e..06104e4724a 100644 --- a/tutorials/platform/web/customizing_html5_shell.rst +++ b/tutorials/platform/web/customizing_html5_shell.rst @@ -83,6 +83,20 @@ The following optional placeholders will enable some extra features in your cust :ref:`BG Color ` setting in **Project Settings > Application > Boot Splash**, converted to a hex color code. +- ``$GODOT_SPLASH_CLASSES``: + This placeholder provides a string of setting names and their values, which affect the splash screen. + This string is meant to be used as a set of CSS class names, which allows styling the splash image + based on the splash project settings. + The following settings from **Project Settings > Application > Boot Splash** are provided, + represented by the class names shown below depending on the setting's boolean value: + + - :ref:`Show Image `: + ``show-image--true``, ``show-image--false`` + - :ref:`Fullsize `: + ``fullsize--true``, ``fullsize--false`` + - :ref:`Use Filter `: + ``use-filter--true``, ``use-filter--false`` + When the custom page is ready, it can be selected in the export options under the *Html / Custom Html Shell* section. diff --git a/tutorials/plugins/running_code_in_the_editor.rst b/tutorials/plugins/running_code_in_the_editor.rst index 8f6c8638a8b..7688c6565e4 100644 --- a/tutorials/plugins/running_code_in_the_editor.rst +++ b/tutorials/plugins/running_code_in_the_editor.rst @@ -151,6 +151,10 @@ and open a script, and change it to this: Save the script and return to the editor. You should now see your object rotate. If you run the game, it will also rotate. +.. warning:: + You may need to restart the editor. This is a known bug found in all Godot 4 versions: + `GH-66381 `_. + .. image:: img/rotating_in_editor.gif .. note:: diff --git a/tutorials/scripting/c_sharp/c_sharp_exports.rst b/tutorials/scripting/c_sharp/c_sharp_exports.rst index a1985b199ab..b6a875a64b4 100644 --- a/tutorials/scripting/c_sharp/c_sharp_exports.rst +++ b/tutorials/scripting/c_sharp/c_sharp_exports.rst @@ -489,6 +489,39 @@ If you want to set an initial value, you must specify it explicitly: [Export(PropertyHint.Enum, "Rebecca,Mary,Leah")] public string CharacterName { get; set; } = "Rebecca"; + +Exporting inspector buttons with ``[ExportToolButton]`` +------------------------------------------------------- + +If you want to create a clickable button in the inspector, you can use the +``[ExportToolButton]`` attribute. This exports a Callable property or field as +a clickable button. Since this runs in the editor, usage of the :ref:`[Tool] +` attribute is required. When the button is +pressed, the callable is called: + +.. code-block:: csharp + + [Tool] + public partial class MyNode : Node + { + [ExportToolButton("Click me!")] + public Callable ClickMeButton => Callable.From(ClickMe); + + public void ClickMe() + { + GD.Print("Hello world!"); + } + } + +You can also set an icon for the button with a second argument. If specified, an +icon will be fetched via :ref:`GetThemeIcon() `, +from the ``"EditorIcons"`` theme type. + +.. code-block:: csharp + + [ExportToolButton("Click me!", Icon = "CharacterBody2D")] + public Callable ClickMeButton => Callable.From(ClickMe); + Exporting collections --------------------- diff --git a/tutorials/scripting/evaluating_expressions.rst b/tutorials/scripting/evaluating_expressions.rst index 4f29b907421..288905c3d78 100644 --- a/tutorials/scripting/evaluating_expressions.rst +++ b/tutorials/scripting/evaluating_expressions.rst @@ -8,6 +8,7 @@ Godot provides an :ref:`class_Expression` class you can use to evaluate expressi An expression can be: - A mathematical expression such as ``(2 + 4) * 16/4.0``. +- A boolean expression such as ``true && false``. - A built-in method call like ``deg_to_rad(90)``. - A method call on a user-provided script like ``update_health()``, if ``base_instance`` is set to a value other than ``null`` when calling @@ -47,6 +48,12 @@ The following operators are available: | Remainder (``%``) | Returns the remainder of an integer division (modulo). | | | The result will always have the sign of the dividend. | +------------------------+-------------------------------------------------------------------------------------+ +| Conjunction (``&&``) | Returns the result of a boolean AND. | ++------------------------+-------------------------------------------------------------------------------------+ +| Disjunction (``||``) | Returns the result of a boolean OR. | ++------------------------+-------------------------------------------------------------------------------------+ +| Negation (``!``) | Returns the result of a boolean NOT. | ++------------------------+-------------------------------------------------------------------------------------+ Spaces around operators are optional. Also, keep in mind the usual `order of operations `__ @@ -141,6 +148,11 @@ The script below demonstrates what the Expression class is capable of:: func _ready(): + # Constant boolean expression. + evaluate("true && false") + # Boolean expression with variables. + evaluate("!(a && b)", ["a", "b"], [true, false]) + # Constant mathexpression. evaluate("2 + 2") # Math expression with variables. @@ -181,6 +193,8 @@ The script below demonstrates what the Expression class is capable of:: The output from the script will be:: + false + true 4 160 1.5707963267949 diff --git a/tutorials/scripting/gdextension/gdextension_cpp_example.rst b/tutorials/scripting/gdextension/gdextension_cpp_example.rst index 4651869eeb8..844693d0158 100644 --- a/tutorials/scripting/gdextension/gdextension_cpp_example.rst +++ b/tutorials/scripting/gdextension/gdextension_cpp_example.rst @@ -25,7 +25,8 @@ There are a few prerequisites you'll need: - a copy of the `godot-cpp repository `__. -See also :ref:`Compiling ` as the build tools are identical +See also :ref:`Configuring an IDE ` +and :ref:`Compiling ` as the build tools are identical to the ones you need to compile Godot from source. You can download the `godot-cpp repository `__ from GitHub or let Git do the work for you. @@ -272,7 +273,7 @@ GDExtension plugin. return; } - GDREGISTER_CLASS(GDExample); + GDREGISTER_RUNTIME_CLASS(GDExample); } void uninitialize_example_module(ModuleInitializationLevel p_level) { @@ -298,7 +299,8 @@ The ``initialize_example_module`` and ``uninitialize_example_module`` functions called respectively when Godot loads our plugin and when it unloads it. All we're doing here is parse through the functions in our bindings module to initialize them, but you might have to set up more things depending on your -needs. We call the ``GDREGISTER_CLASS`` macro for each of our classes in our library. +needs. We call the ``GDREGISTER_RUNTIME_CLASS`` macro for each of our classes +in our library. This will make them run only in game, like the default for GDScript. The important function is the third function called ``example_library_init``. We first call a function in our bindings library that creates an initialization object. @@ -327,10 +329,11 @@ At last, we need the header file for the ``register_types.cpp`` named Compiling the plugin -------------------- -We cannot easily write by hand a ``SConstruct`` file that SCons would use for -building. For the purpose of this example, just use -:download:`this hardcoded SConstruct file ` we've -prepared. We'll cover a more customizable, detailed example on how to use these +To compile the project we need to define how SCons using should compile it +using a ``SConstruct`` file which references the one in ``godot-cpp``. +Writing it from scratch is outside the scope of this tutorial, but you can +:download:`the SConstruct file we prepared `. +We'll cover a more customizable, detailed example on how to use these build files in a subsequent tutorial. .. note:: @@ -414,7 +417,7 @@ loaded for each platform and the entry function for the module. It is called ``g } This file contains a ``configuration`` section that controls the entry function of the module. -You should also set the minimum compatible Godot version with ``compatability_minimum``, +You should also set the minimum compatible Godot version with ``compatibility_minimum``, which prevents older version of Godot from trying to load your extension. The ``reloadable`` flag enables automatic reloading of your extension by the editor every time you recompile it, without needing to restart the editor. This only works if you compile your extension in debug mode (default). @@ -465,7 +468,12 @@ We're going to assign the Godot logo to this node as our texture, disable the We're finally ready to run the project: -.. image:: img/gdextension_cpp_animated.gif +.. video:: img/gdextension_cpp_animated.webm + :alt: Screen recording of a game window, with Godot logo moving in the top-left corner + :autoplay: + :loop: + :muted: + :align: default Adding properties ----------------- diff --git a/tutorials/scripting/gdextension/gdextension_docs_system.rst b/tutorials/scripting/gdextension/gdextension_docs_system.rst index 046caba3824..575a901ef94 100644 --- a/tutorials/scripting/gdextension/gdextension_docs_system.rst +++ b/tutorials/scripting/gdextension/gdextension_docs_system.rst @@ -7,7 +7,7 @@ GDExtension documentation system Adding documentation for GDExtensions is only possible for Godot 4.3 and later. The support can be integrated into your project regardless because the snippet will check if you use the appropriate godot-cpp version. - If you set the ``compatability_minimum`` to 4.2 and you load a project with the extension through a 4.2 editor, the + If you set the ``compatibility_minimum`` to 4.2 and you load a project with the extension through a 4.2 editor, the documentation page for that class will be empty. The extension itself will still work. The GDExtension documentation system works in a similar manner to the built-in engine documentation. It uses a series of diff --git a/tutorials/scripting/gdextension/img/gdextension_cpp_animated.gif b/tutorials/scripting/gdextension/img/gdextension_cpp_animated.gif deleted file mode 100644 index 9a5488889fb..00000000000 Binary files a/tutorials/scripting/gdextension/img/gdextension_cpp_animated.gif and /dev/null differ diff --git a/tutorials/scripting/gdextension/img/gdextension_cpp_animated.webm b/tutorials/scripting/gdextension/img/gdextension_cpp_animated.webm new file mode 100644 index 00000000000..11b3e0ee307 Binary files /dev/null and b/tutorials/scripting/gdextension/img/gdextension_cpp_animated.webm differ diff --git a/tutorials/scripting/gdscript/gdscript_advanced.rst b/tutorials/scripting/gdscript/gdscript_advanced.rst index 8d3e8f3355f..764af895295 100644 --- a/tutorials/scripting/gdscript/gdscript_advanced.rst +++ b/tutorials/scripting/gdscript/gdscript_advanced.rst @@ -24,7 +24,6 @@ are that: - The language is easy to get started with. - Most code can be written and changed quickly and without hassle. -- Less code written means less errors & mistakes to fix. - The code is easy to read (little clutter). - No compilation is required to test. - Runtime is tiny. diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index 3fe52838c89..60fa034dfc9 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -184,17 +184,17 @@ in case you want to take a look under the hood. +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | super | Resolves the scope of the parent method. See `Inheritance`_. | +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ -| signal | Defines a signal. | +| signal | Defines a signal. See `Signals`_. | +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ -| func | Defines a function. | +| func | Defines a function. See `Functions`_. | +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | static | Defines a static function or a static member variable. | +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ -| const | Defines a constant. | +| const | Defines a constant. See `Constants`_. | +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ -| enum | Defines an enum. | +| enum | Defines an enum. See `Enums`_. | +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ -| var | Defines a variable. | +| var | Defines a variable. See `Variables`_. | +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | breakpoint | Editor helper for debugger breakpoints. Unlike breakpoints created by clicking in the gutter, ``breakpoint`` is stored in the script itself. | | | This makes it persistent across different machines when using version control. | @@ -890,6 +890,8 @@ native or user class, or enum. Nested array types (like ``Array[Array[int]]``) a The only exception was made for the ``Array`` (``Array[Variant]``) type, for user convenience and compatibility with old code. However, operations on untyped arrays are considered unsafe. +.. _doc_gdscript_packed_arrays: + Packed arrays ^^^^^^^^^^^^^ diff --git a/tutorials/scripting/gdscript/gdscript_exports.rst b/tutorials/scripting/gdscript/gdscript_exports.rst index a2ac8ec4a43..7a378f2ab66 100644 --- a/tutorials/scripting/gdscript/gdscript_exports.rst +++ b/tutorials/scripting/gdscript/gdscript_exports.rst @@ -99,19 +99,19 @@ annotation. Strings as paths ---------------- -String as a path to a file. +String as a path to a file. See :ref:`@export_file `. :: @export_file var f -String as a path to a directory. +String as a path to a directory. See :ref:`@export_dir `. :: @export_dir var f -String as a path to a file, custom filter provided as hint. +String as a path to a file, custom filter provided as hint. See again :ref:`@export_file `. :: @@ -120,20 +120,20 @@ String as a path to a file, custom filter provided as hint. Using paths in the global filesystem is also possible, but only in scripts in tool mode. -String as a path to a PNG file in the global filesystem. +String as a path to a PNG file in the global filesystem. See :ref:`@export_global_file `. :: @export_global_file("*.png") var tool_image -String as a path to a directory in the global filesystem. +String as a path to a directory in the global filesystem. See :ref:`@export_global_dir `. :: @export_global_dir var tool_dir The multiline annotation tells the editor to show a large input -field for editing over multiple lines. +field for editing over multiple lines. See :ref:`@export_multiline `. :: @@ -142,6 +142,8 @@ field for editing over multiple lines. Limiting editor input ranges ---------------------------- +See :ref:`@export_range ` for all of the following. + Allow integer values from 0 to 20. :: @@ -222,7 +224,7 @@ Floats with easing hint ----------------------- Display a visual representation of the ``ease()`` function -when editing. +when editing. See :ref:`@export_exp_easing `. :: @@ -237,7 +239,7 @@ Regular color given as red-green-blue-alpha value. @export var col: Color -Color given as red-green-blue value (alpha will always be 1). +Color given as red-green-blue value (alpha will always be 1). See :ref:`@export_color_no_alpha `. :: @@ -303,6 +305,8 @@ in conjunction with a :ref:`script in "tool" mode `. Exporting bit flags ------------------- +See :ref:`@export_flags `. + Integers used as bit flags can store multiple ``true``/``false`` (boolean) values in one property. By using the ``@export_flags`` annotation, they can be set from the editor:: @@ -341,6 +345,8 @@ If in doubt, use boolean variables instead. Exporting enums --------------- +See :ref:`@export_enum `. + Properties can be exported with a type hint referencing an enum to limit their values to the values of the enumeration. The editor will create a widget in the Inspector, enumerating the following as "Thing 1", "Thing 2", "Another Thing". The value will be stored as an integer. @@ -435,6 +441,8 @@ Other export variants can also be used when exporting arrays: ``@export_storage`` ------------------- +See :ref:`@export_storage `. + By default, exporting a property has two effects: 1. makes the property stored in the scene/resource file (:ref:`PROPERTY_USAGE_STORAGE `); diff --git a/tutorials/scripting/gdscript/gdscript_styleguide.rst b/tutorials/scripting/gdscript/gdscript_styleguide.rst index 9dd84ad05da..eb03cd7fed6 100644 --- a/tutorials/scripting/gdscript/gdscript_styleguide.rst +++ b/tutorials/scripting/gdscript/gdscript_styleguide.rst @@ -763,26 +763,38 @@ We suggest to organize GDScript code this way: :: - 01. @tool + 01. @tool, @icon, @static_unload 02. class_name 03. extends - 04. ## docstring + 04. ## doc comment 05. signals 06. enums 07. constants - 08. @export variables - 09. public variables - 10. private variables + 08. static variables + 09. @export variables + 10. remaining regular variables 11. @onready variables - 12. optional built-in virtual _init method - 13. optional built-in virtual _enter_tree() method - 14. built-in virtual _ready method - 15. remaining built-in virtual methods - 16. public methods - 17. private methods - 18. subclasses + 12. _static_init() + 13. remaining static methods + 14. overridden built-in virtual methods: + 1. _init() + 2. _enter_tree() + 3. _ready() + 4. _process() + 5. _physics_process() + 6. remaining virtual methods + 15. overridden custom methods + 16. remaining methods + 17. subclasses + +And put the class methods and variables in the following order depending on their access modifiers: + +:: + + 1. public + 2. private We optimized the order to make it easy to read the code from top to bottom, to help developers reading the code for the first time understand how it works, and @@ -803,9 +815,9 @@ Class declaration If the code is meant to run in the editor, place the ``@tool`` annotation on the first line of the script. -Follow with the ``class_name`` if necessary. You can turn a GDScript file into a -global type in your project using this feature. For more information, see -:ref:`doc_gdscript`. +Follow with the optional ``@icon`` then the ``class_name`` if necessary. You can turn a +GDScript file into a global type in your project using ``class_name``. For more +information, see :ref:`doc_gdscript`. Then, add the ``extends`` keyword if the class extends a built-in type. diff --git a/tutorials/scripting/nodes_and_scene_instances.rst b/tutorials/scripting/nodes_and_scene_instances.rst index e10571c0208..0b8a80c31ed 100644 --- a/tutorials/scripting/nodes_and_scene_instances.rst +++ b/tutorials/scripting/nodes_and_scene_instances.rst @@ -6,6 +6,10 @@ Nodes and scene instances This guide explains how to get nodes, create nodes, add them as a child, and instantiate scenes from code. +.. seealso:: + + Check the :ref:`doc_instancing` tutorial to learn about Godot's approach to scene instancing. + Getting nodes ------------- diff --git a/tutorials/scripting/scene_unique_nodes.rst b/tutorials/scripting/scene_unique_nodes.rst index 993b3fca163..97f50f721ab 100644 --- a/tutorials/scripting/scene_unique_nodes.rst +++ b/tutorials/scripting/scene_unique_nodes.rst @@ -18,6 +18,8 @@ the node's path is changed. Creation and usage ------------------ +There are two ways to create a scene unique node. + In the Scene tree dock, right-click on a node and select **Access as Unique Name** in the context menu. @@ -28,6 +30,9 @@ to its name in the scene tree: .. image:: img/percent.webp +You can also do this while renaming the node by adding "%" to the beginning of the name. +Once you confirm, the percent symbol will appear next to its name. + You can now use the node in your script. For example, you can reference it with a ``get_node()`` method call by typing the % symbol, followed by the node's name: diff --git a/tutorials/shaders/img/shader_create.png b/tutorials/shaders/img/shader_create.png deleted file mode 100644 index 7105da5f9aa..00000000000 Binary files a/tutorials/shaders/img/shader_create.png and /dev/null differ diff --git a/tutorials/shaders/img/shader_material_convert.png b/tutorials/shaders/img/shader_material_convert.png deleted file mode 100644 index 01c7745def9..00000000000 Binary files a/tutorials/shaders/img/shader_material_convert.png and /dev/null differ diff --git a/tutorials/shaders/img/shader_material_create.png b/tutorials/shaders/img/shader_material_create.png deleted file mode 100644 index 0aefd3fd539..00000000000 Binary files a/tutorials/shaders/img/shader_material_create.png and /dev/null differ diff --git a/tutorials/shaders/img/shader_material_editor.png b/tutorials/shaders/img/shader_material_editor.png deleted file mode 100644 index 40d652c33b5..00000000000 Binary files a/tutorials/shaders/img/shader_material_editor.png and /dev/null differ diff --git a/tutorials/shaders/img/visual_shader_code.png b/tutorials/shaders/img/visual_shader_code.png deleted file mode 100644 index 41125061089..00000000000 Binary files a/tutorials/shaders/img/visual_shader_code.png and /dev/null differ diff --git a/tutorials/shaders/img/visual_shader_editor.png b/tutorials/shaders/img/visual_shader_editor.png deleted file mode 100644 index 3f2a4703094..00000000000 Binary files a/tutorials/shaders/img/visual_shader_editor.png and /dev/null differ diff --git a/tutorials/shaders/img/visual_shader_editor2.webp b/tutorials/shaders/img/visual_shader_editor2.webp index 607a77281fc..0ed3c2f5645 100644 Binary files a/tutorials/shaders/img/visual_shader_editor2.webp and b/tutorials/shaders/img/visual_shader_editor2.webp differ diff --git a/tutorials/shaders/img/vs_meshemitter.webp b/tutorials/shaders/img/vs_meshemitter.webp new file mode 100644 index 00000000000..c06e2b3b138 Binary files /dev/null and b/tutorials/shaders/img/vs_meshemitter.webp differ diff --git a/tutorials/shaders/index.rst b/tutorials/shaders/index.rst index a1cfd205419..b4b1604322a 100644 --- a/tutorials/shaders/index.rst +++ b/tutorials/shaders/index.rst @@ -10,7 +10,6 @@ Shaders introduction_to_shaders shader_reference/index your_first_shader/index - shader_materials visual_shaders compute_shaders screen-reading_shaders diff --git a/tutorials/shaders/making_trees.rst b/tutorials/shaders/making_trees.rst index aa159455460..f416ee3f0e1 100644 --- a/tutorials/shaders/making_trees.rst +++ b/tutorials/shaders/making_trees.rst @@ -77,7 +77,7 @@ Finally, all that's left is the fragment shader: ALPHA = albedo_tex.a; METALLIC = 0.0; ROUGHNESS = 1.0; - TRANSMISSION = transmission.rgb; + SSS_TRANSMITTANCE_COLOR = transmission.rgba; } And this is pretty much it. diff --git a/tutorials/shaders/shader_materials.rst b/tutorials/shaders/shader_materials.rst deleted file mode 100644 index fb326634ee9..00000000000 --- a/tutorials/shaders/shader_materials.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. _doc_shader_materials: - -Shader materials -================ - -Introduction ------------- - -For the most common cases, Godot provides ready to use materials for -most types of shaders, such as :ref:`StandardMaterial3D `, -:ref:`CanvasItemMaterial ` and :ref:`ParticleProcessMaterial `. -They are flexible implementations that cover most use cases. - -Shader materials allow writing a custom shader directly, for maximum flexibility. -Examples of this are: - -- Create procedural textures. -- Create complex texture blending effects. -- Create animated materials, or materials that change over time. -- Create refractive effects or other advanced effects. -- Create special lighting shaders for more exotic materials. -- Animate vertices, like tree leaves or grass. -- Create custom particle code. -- And much more! - -Godot provides built-in functionality to make frequent operations -easier. Additionally, Godot's shader editor will detect errors as you -type, so you can see your edited shaders in real-time. It is also -possible to edit shaders using a visual, node-based graph editor. - -Creating a ShaderMaterial -------------------------- - -Create a new ShaderMaterial in some object of your choice. Go to the -"Material" property and create a ShaderMaterial. - -.. image:: img/shader_material_create.png - -Next, click on the shader material to see its properties. From here you -can create a shader or visual shader. Regular shaders use code to set -their properties while a visual shader uses a node based workflow. - -If you need to you can convert a visual shader to a text shader. -However you can't convert a text shader to a visual shader. - -Choose one of them and you can start editing your shader. - -.. image:: img/shader_create.png - -If you create a regular shader click on it and the shader editor will open. - -.. image:: img/shader_material_editor.png - -If you create a visual shader the visual shader editor will open automatically. - -.. image:: img/visual_shader_editor.png - -In the visual shader editor you can click a button and see what your visual -shader looks like as shader code. This can be useful if you're trying to -replicate a text shader as nodes, or it can be used as a preview for converting -your visual shader to a text shader. - -.. image:: img/visual_shader_code.png - -.. note:: - - To learn more about visual shaders, read :ref:`doc_visual_shaders`. - -Converting to ShaderMaterial ----------------------------- - -It is possible to convert from StandardMaterial3D, CanvasItemMaterial and -ParticleProcessMaterial to ShaderMaterial. To do so, go to the material properties -and select the convert option. - -.. image:: img/shader_material_convert.png - -.. note:: - - Using the convert option will turn the StandardMaterial3D into a ShaderMaterial - with a text shader, not a visual shader. diff --git a/tutorials/shaders/shader_reference/canvas_item_shader.rst b/tutorials/shaders/shader_reference/canvas_item_shader.rst index 74ea1a6449c..bd82d24124b 100644 --- a/tutorials/shaders/shader_reference/canvas_item_shader.rst +++ b/tutorials/shaders/shader_reference/canvas_item_shader.rst @@ -45,6 +45,10 @@ Values marked as ``in`` are read-only. Values marked as ``out`` can optionally b not necessarily contain sensible values. Values marked as ``inout`` provide a sensible default value, and can optionally be written to. Samplers cannot be written to so they are not marked. +Not all built-ins are available in all processing functions. To access a vertex +built-in from the ``fragment()`` function, you can use a :ref:`varying `. +The same applies for accessing fragment built-ins from the ``light()`` function. + Global built-ins ---------------- diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 57d776ccfce..3f61b4d04f0 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -102,7 +102,8 @@ Most GLSL ES 3.0 datatypes are supported: Comments ~~~~~~~~ -The shading language supports the same comment syntax as used in C# and C++: +The shading language supports the same comment syntax as used in C# and C++, +using ``//`` for single-line comments and ``/* */`` for multi-line comments: .. code-block:: glsl @@ -811,6 +812,7 @@ There are two possible interpolation qualifiers: | **smooth** | The value is interpolated in a perspective-correct fashion. This is the default.| +-------------------+---------------------------------------------------------------------------------+ +.. _doc_shading_language_uniforms: Uniforms -------- @@ -1121,7 +1123,9 @@ When using per-instance uniforms, there are some restrictions you should be awar Setting uniforms from code ~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can set uniforms from GDScript: +You can set uniforms from GDScript using the +:ref:`set_shader_parameter() ` +method: .. code-block:: gdscript @@ -1129,7 +1133,7 @@ You can set uniforms from GDScript: material.set_shader_parameter("colors", [Vector3(1, 0, 0), Vector3(0, 1, 0), Vector3(0, 0, 1)]) -.. note:: The first argument to ``set_shader_parameter`` is the name of the uniform +.. note:: The first argument to ``set_shader_parameter()`` is the name of the uniform in the shader. It must match *exactly* to the name of the uniform in the shader or else it will not be recognized. @@ -1222,13 +1226,12 @@ table of the corresponding types: | **samplerExternalOES** | **ExternalTexture** | Only supported in Compatibility/Android platform. | +------------------------+-------------------------+------------------------------------------------------------+ -.. note:: Be careful when setting shader uniforms from GDScript, no error will - be thrown if the type does not match. Your shader will just exhibit - undefined behavior. - -.. warning:: - As with the last note, no error will be thrown if the typing does not match while setting a shader uniform, this unintuitively includes setting a (GDscript) 64 bit int/float into a Godot shader language int/float (32 bit). This may lead to unintentional consequences in cases where high precision is required. - +.. note:: Be careful when setting shader uniforms from GDScript, since no error + will be thrown if the type does not match. Your shader will just exhibit + undefined behavior. Specifically, this includes setting a GDScript + int/float (64 bit) into a Godot shader language int/float (32 bit). + This may lead to unintended consequences in cases where high + precision is required. Uniform limits ~~~~~~~~~~~~~~ diff --git a/tutorials/shaders/shader_reference/spatial_shader.rst b/tutorials/shaders/shader_reference/spatial_shader.rst index 9bb37e4da94..ee4cb2f7876 100644 --- a/tutorials/shaders/shader_reference/spatial_shader.rst +++ b/tutorials/shaders/shader_reference/spatial_shader.rst @@ -23,6 +23,8 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR +-------------------------------+------------------------------------------------------------------------------------------------------+ | **blend_mul** | Multiplicative blend mode. | +-------------------------------+------------------------------------------------------------------------------------------------------+ +| **blend_premul_alpha** | Premultiplied alpha blend mode (fully transparent = add, fully opaque = mix). | ++-------------------------------+------------------------------------------------------------------------------------------------------+ | **depth_draw_opaque** | Only draw depth for opaque geometry (not transparent). | +-------------------------------+------------------------------------------------------------------------------------------------------+ | **depth_draw_always** | Always draw depth (opaque and transparent). | @@ -33,7 +35,7 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR +-------------------------------+------------------------------------------------------------------------------------------------------+ | **depth_test_disabled** | Disable depth testing. | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **sss_mode_skin** | Subsurface Scattering mode for skin. | +| **sss_mode_skin** | Subsurface Scattering mode for skin (optimizes visuals for human skin, e.g. boosted red channel). | +-------------------------------+------------------------------------------------------------------------------------------------------+ | **cull_back** | Cull back-faces (default). | +-------------------------------+------------------------------------------------------------------------------------------------------+ @@ -41,23 +43,25 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR +-------------------------------+------------------------------------------------------------------------------------------------------+ | **cull_disabled** | Culling disabled (double sided). | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **unshaded** | Result is just albedo. No lighting/shading happens in material. | +| **unshaded** | Result is just albedo. No lighting/shading happens in material, making it faster to render. | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **wireframe** | Geometry draws using lines (useful for troubleshooting). | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **wireframe** | Geometry draws using lines. | +| **debug_shadow_splits** | Directional shadows are drawn using different colors for each split (useful for troubleshooting). | +-------------------------------+------------------------------------------------------------------------------------------------------+ | **diffuse_burley** | Burley (Disney PBS) for diffuse (default). | +-------------------------------+------------------------------------------------------------------------------------------------------+ | **diffuse_lambert** | Lambert shading for diffuse. | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **diffuse_lambert_wrap** | Lambert wrapping (roughness dependent) for diffuse. | +| **diffuse_lambert_wrap** | Lambert-wrap shading (roughness-dependent) for diffuse. | +-------------------------------+------------------------------------------------------------------------------------------------------+ | **diffuse_toon** | Toon shading for diffuse. | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **specular_schlick_ggx** | Schlick-GGX for specular (default). | +| **specular_schlick_ggx** | Schlick-GGX for direct light specular lobes (default). | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **specular_toon** | Toon for specular. | +| **specular_toon** | Toon for direct light specular lobes. | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **specular_disabled** | Disable specular. | +| **specular_disabled** | Disable direct light specular lobes. Doesn't affect reflected light (use ``SPECULAR = 0.0`` instead).| +-------------------------------+------------------------------------------------------------------------------------------------------+ | **skip_vertex_transform** | ``VERTEX``, ``NORMAL``, ``TANGENT``, and ``BITANGENT`` | | | need to be transformed manually in the ``vertex()`` function. | @@ -65,9 +69,9 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR | **world_vertex_coords** | ``VERTEX``, ``NORMAL``, ``TANGENT``, and ``BITANGENT`` | | | are modified in world space instead of model space. | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **ensure_correct_normals** | Use when non-uniform scale is applied to mesh. | +| **ensure_correct_normals** | Use when non-uniform scale is applied to mesh *(note: currently unimplemented)*. | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **shadows_disabled** | Disable computing shadows in shader. | +| **shadows_disabled** | Disable computing shadows in shader. The shader will not cast shadows, but can still receive them. | +-------------------------------+------------------------------------------------------------------------------------------------------+ | **ambient_light_disabled** | Disable contribution from ambient light and radiance map. | +-------------------------------+------------------------------------------------------------------------------------------------------+ @@ -75,7 +79,7 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR | | non-shadowed areas are transparent. Useful for overlaying shadows onto | | | a camera feed in AR. | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **vertex_lighting** | Use vertex-based lighting. | +| **vertex_lighting** | Use vertex-based lighting instead of per-pixel lighting. | +-------------------------------+------------------------------------------------------------------------------------------------------+ | **particle_trails** | Enables the trails when used on particles geometry. | +-------------------------------+------------------------------------------------------------------------------------------------------+ @@ -83,7 +87,7 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR +-------------------------------+------------------------------------------------------------------------------------------------------+ | **alpha_to_coverage_and_one** | Alpha antialiasing mode, see `here `_ for more. | +-------------------------------+------------------------------------------------------------------------------------------------------+ -| **fog_disabled** | Disable receiving depth-based or volumetric fog. Useful for blend_add materials like particles. | +| **fog_disabled** | Disable receiving depth-based or volumetric fog. Useful for ``blend_add`` materials like particles. | +-------------------------------+------------------------------------------------------------------------------------------------------+ Built-ins @@ -93,6 +97,10 @@ Values marked as ``in`` are read-only. Values marked as ``out`` can optionally b not necessarily contain sensible values. Values marked as ``inout`` provide a sensible default value, and can optionally be written to. Samplers cannot be written to so they are not marked. +Not all built-ins are available in all processing functions. To access a vertex +built-in from the ``fragment()`` function, you can use a :ref:`varying `. +The same applies for accessing fragment built-ins from the ``light()`` function. + Global built-ins ---------------- @@ -129,7 +137,7 @@ Vertex built-ins ---------------- Vertex data (``VERTEX``, ``NORMAL``, ``TANGENT``, and ``BITANGENT``) are presented in model space -(also called local space). If not written to, these values will not be modified and be +(also called local space). If not written to, these values will not be modified and be passed through as they came, then transformed into view space to be used in ``fragment()``. They can optionally be presented in world space by using the ``world_vertex_coords`` render mode. @@ -283,7 +291,7 @@ these properties, and if you don't write to them, Godot will optimize away the c | | left. ``z`` specifies fragment depth. It is also used as the output value for the fragment depth | | | unless ``DEPTH`` is written to. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| in bool **FRONT_FACING** | ``true`` if current face is front facing. | +| in bool **FRONT_FACING** | ``true`` if current face is front facing, ``false`` otherwise. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | in vec3 **VIEW** | Normalized vector from fragment position to camera (in view space). This is the same for both | | | perspective and orthogonal cameras. | @@ -298,7 +306,9 @@ these properties, and if you don't write to them, Godot will optimize away the c +----------------------------------------+--------------------------------------------------------------------------------------------------+ | in mat4 **MODEL_MATRIX** | Model/local space to world space transform. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| in mat3 **MODEL_NORMAL_MATRIX** | | +| in mat3 **MODEL_NORMAL_MATRIX** | Model/local space to world space transform for normals. This is the same as ``MODEL_MATRIX`` | +| | by default unless the object is scaled non-uniformly, in which case this is set to | +| | ``transpose(inverse(mat3(MODEL_MATRIX)))``. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | in mat4 **VIEW_MATRIX** | World space to view space transform. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ @@ -325,7 +335,7 @@ these properties, and if you don't write to them, Godot will optimize away the c | inout vec3 **LIGHT_VERTEX** | A writable version of ``VERTEX`` that can be used to alter light and shadows. Writing to this | | | will not change the position of the fragment. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| in int **VIEW_INDEX** | The view that we are rendering. | +| in int **VIEW_INDEX** | The view that we are rendering. Used to distinguish between views in multiview/stereo rendering. | | | ``VIEW_MONO_LEFT`` (``0``) for Mono (not multiview) or | | | left eye, ``VIEW_RIGHT`` (``1``) for right eye. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ @@ -365,43 +375,58 @@ these properties, and if you don't write to them, Godot will optimize away the c +----------------------------------------+--------------------------------------------------------------------------------------------------+ | out float **ALPHA_SCISSOR_THRESHOLD** | If written to, values below a certain amount of alpha are discarded. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **ALPHA_HASH_SCALE** | | +| out float **ALPHA_HASH_SCALE** | Alpha hash scale when using the alpha hash transparency mode. Defaults to ``1.0``. | +| | Higher values result in more visible pixels in the dithering pattern. | ++----------------------------------------+--------------------------------------------------------------------------------------------------+ +| out float **ALPHA_ANTIALIASING_EDGE** | The threshold below which alpha to coverage antialiasing should be used. Defaults to ``0.0``. | +| | Requires the ``alpha_to_coverage`` render mode. Should be set to a value lower than | +| | ``ALPHA_SCISSOR_THRESHOLD`` to be effective. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **ALPHA_ANTIALIASING_EDGE** | | +| out vec2 **ALPHA_TEXTURE_COORDINATE** | The texture coordinate to use for alpha-to-coverge antialiasing. Requires the | +| | ``alpha_to_coverage`` render mode. Typically set to ``UV * vec2(albedo_texture_size)`` where | +| | ``albedo_texture_size`` is the size of the albedo texture in pixels. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out vec2 **ALPHA_TEXTURE_COORDINATE** | | +| out float **PREMUL_ALPHA_FACTOR** | Premultiplied alpha factor. Only effective if ``render_mode blend_premul_alpha;`` is used. | +| | This should be written to when using a *shaded* material with premultiplied alpha blending for | +| | interaction with lighting. This is not required for unshaded materials. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | out float **METALLIC** | Metallic (range of ``[0.0, 1.0]``). | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **SPECULAR** | Specular. Defaults to ``0.5``, best not to modify unless you want to change IOR. | +| out float **SPECULAR** | Specular (not physically accurate to change). Defaults to ``0.5``. ``0.0`` disables reflections. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | out float **ROUGHNESS** | Roughness (range of ``[0.0, 1.0]``). | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | out float **RIM** | Rim (range of ``[0.0, 1.0]``). If used, Godot calculates rim lighting. | +| | Rim size depends on ``ROUGHNESS``. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | out float **RIM_TINT** | Rim Tint, range of ``0.0`` (white) to ``1.0`` (albedo). If used, Godot calculates rim lighting. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **CLEARCOAT** | Small added specular blob. If used, Godot calculates Clearcoat. | +| out float **CLEARCOAT** | Small specular blob added on top of the existing one. If used, Godot calculates clearcoat. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **CLEARCOAT_GLOSS** | Gloss of Clearcoat. If used, Godot calculates Clearcoat. | +| out float **CLEARCOAT_GLOSS** | Gloss of clearcoat. If used, Godot calculates clearcoat. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | out float **ANISOTROPY** | For distorting the specular blob according to tangent space. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | out vec2 **ANISOTROPY_FLOW** | Distortion direction, use with flowmaps. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **SSS_STRENGTH** | Strength of Subsurface Scattering. If used, Subsurface Scattering will be applied to object. | +| out float **SSS_STRENGTH** | Strength of subsurface scattering. If used, subsurface scattering will be applied to the object. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out vec4 **SSS_TRANSMITTANCE_COLOR** | | +| out vec4 **SSS_TRANSMITTANCE_COLOR** | Color of subsurface scattering transmittance. If used, subsurface scattering transmittance | +| | will be applied to the object. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **SSS_TRANSMITTANCE_DEPTH** | | +| out float **SSS_TRANSMITTANCE_DEPTH** | Depth of subsurface scattering transmittance. Higher values allow the effect to reach deeper | +| | into the object. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **SSS_TRANSMITTANCE_BOOST** | | +| out float **SSS_TRANSMITTANCE_BOOST** | Boosts the subsurface scattering transmittance if set above ``0.0``. This makes the effect | +| | show up even on directly lit surfaces | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| inout vec3 **BACKLIGHT** | | +| inout vec3 **BACKLIGHT** | Color of backlighting (works like direct light, but it's received even if the normal | +| | is slightly facing away from the light). If used, backlighting will be applied to the object. | +| | Can be used as a cheaper approximation of subsurface scattering. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **AO** | Strength of Ambient Occlusion. For use with pre-baked AO. | +| out float **AO** | Strength of ambient occlusion. For use with pre-baked AO. | +----------------------------------------+--------------------------------------------------------------------------------------------------+ -| out float **AO_LIGHT_AFFECT** | How much AO affects lights (range of ``[0.0, 1.0]``, default ``0.0``). | +| out float **AO_LIGHT_AFFECT** | How much ambient occlusion affects direct light (range of ``[0.0, 1.0]``, default ``0.0``). | +----------------------------------------+--------------------------------------------------------------------------------------------------+ | out vec3 **EMISSION** | Emission color (can go over ``(1.0, 1.0, 1.0)`` for HDR). | +----------------------------------------+--------------------------------------------------------------------------------------------------+ @@ -424,7 +449,7 @@ Light built-ins --------------- Writing light processor functions is completely optional. You can skip the ``light()`` function by using -the ``unshaded`` render mode. If no light function is written, Godot will use the material properties +the ``unshaded`` render mode. If no light function is written, Godot will use the material properties written to in the ``fragment()`` function to calculate the lighting for you (subject to the render mode). The ``light()`` function is called for every light in every pixel. It is called within a loop for each light type. @@ -434,14 +459,14 @@ Below is an example of a custom ``light()`` function using a Lambertian lighting .. code-block:: glsl void light() { - DIFFUSE_LIGHT += clamp(dot(NORMAL, LIGHT), 0.0, 1.0) * ATTENUATION * LIGHT_COLOR; + DIFFUSE_LIGHT += clamp(dot(NORMAL, LIGHT), 0.0, 1.0) * ATTENUATION * LIGHT_COLOR / PI; } If you want the lights to add together, add the light contribution to ``DIFFUSE_LIGHT`` using ``+=``, rather than overwriting it. .. warning:: - The ``light()`` function won't be run if the ``vertex_lighting`` render mode is enabled, or if + The ``light()`` function won't be run if the ``vertex_lighting`` render mode is enabled, or if :ref:`Rendering > Quality > Shading > Force Vertex Shading` is enabled in the Project Settings. (It's enabled by default on mobile platforms.) diff --git a/tutorials/shaders/visual_shaders.rst b/tutorials/shaders/visual_shaders.rst index 7b1b32d85b7..e07cad01265 100644 --- a/tutorials/shaders/visual_shaders.rst +++ b/tutorials/shaders/visual_shaders.rst @@ -35,8 +35,9 @@ in the dropdown, then give it a name. .. image:: img/visual_shader_create2.webp Click on the visual shader you just created to open the Shader Editor. -The layout of the Shader Editor comprises two parts: -the upper toolbar and the graph itself. +The layout of the Shader Editor comprises four parts, a file list on +the right, the upper toolbar, the graph itself, and a material preview +on the right that can be toggled off .. image:: img/visual_shader_editor2.webp @@ -54,7 +55,8 @@ From left to right in the toolbar: nodes you have selected as efficiently and cleanly as possible. - The Manage Varyings button opens a dropdown that lets you add or remove a varying. -- The last icon shows the generated shader code corresponding to your graph. +- The show generated code button shows shader code corresponding to your graph. +- The last icon toggles the material preview on or off. .. note:: @@ -224,7 +226,22 @@ Switch node ~~~~~~~~~~~ The ``Switch`` node returns a vector if the boolean condition is ``true`` or -``false``. ``Boolean`` was introduced above. If you convert a vector to a true -boolean, all components of the vector should be above zero. +``false``. ``Boolean`` was introduced above. If you want to convert a vector +to a true boolean, all components of the vector should be non-zero. .. image:: img/vs_switch.webp + +Mesh Emitter +~~~~~~~~~~~~ + +The ``Mesh Emitter`` node is used for emitting particles from mesh vertices. This is +only available for shaders that are in ``Particles`` mode. + +Keep in mind that not all 3D objects are mesh files. a glTF file can't be dragged +and dropped into the graph. However, you can create an inherited scene from it, +save the mesh in that scene as it's own file, and use that. + +.. image:: img/vs_meshemitter.webp + +You can also drag and drop obj files into the graph editor to add the node +for that specific mesh, other mesh files will not work for this. \ No newline at end of file diff --git a/tutorials/shaders/your_first_shader/img/cos.png b/tutorials/shaders/your_first_shader/img/cos.png deleted file mode 100644 index d2c2e0fe6cd..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/cos.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/cos.webp b/tutorials/shaders/your_first_shader/img/cos.webp new file mode 100644 index 00000000000..9bbb7ebd96a Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/cos.webp differ diff --git a/tutorials/shaders/your_first_shader/img/cos4.png b/tutorials/shaders/your_first_shader/img/cos4.png deleted file mode 100644 index e21dcf627b5..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/cos4.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/cos4.webp b/tutorials/shaders/your_first_shader/img/cos4.webp new file mode 100644 index 00000000000..084f3060e22 Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/cos4.webp differ diff --git a/tutorials/shaders/your_first_shader/img/light.png b/tutorials/shaders/your_first_shader/img/light.png deleted file mode 100644 index fdf4924d94e..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/light.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/light.webp b/tutorials/shaders/your_first_shader/img/light.webp new file mode 100644 index 00000000000..61d8e4d65fc Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/light.webp differ diff --git a/tutorials/shaders/your_first_shader/img/noise-low.png b/tutorials/shaders/your_first_shader/img/noise-low.png deleted file mode 100644 index 87419a52ef9..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/noise-low.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/noise-low.webp b/tutorials/shaders/your_first_shader/img/noise-low.webp new file mode 100644 index 00000000000..87085d0816f Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/noise-low.webp differ diff --git a/tutorials/shaders/your_first_shader/img/noise-set.webp b/tutorials/shaders/your_first_shader/img/noise-set.webp index 6759f0cde8d..1f1bc5cfb14 100644 Binary files a/tutorials/shaders/your_first_shader/img/noise-set.webp and b/tutorials/shaders/your_first_shader/img/noise-set.webp differ diff --git a/tutorials/shaders/your_first_shader/img/noise.png b/tutorials/shaders/your_first_shader/img/noise.png deleted file mode 100644 index ee2f52268eb..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/noise.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/noise.webp b/tutorials/shaders/your_first_shader/img/noise.webp new file mode 100644 index 00000000000..89b31fa199c Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/noise.webp differ diff --git a/tutorials/shaders/your_first_shader/img/normal-set.webp b/tutorials/shaders/your_first_shader/img/normal-set.webp index 1058c19e9a3..375dd2a4b07 100644 Binary files a/tutorials/shaders/your_first_shader/img/normal-set.webp and b/tutorials/shaders/your_first_shader/img/normal-set.webp differ diff --git a/tutorials/shaders/your_first_shader/img/normal.png b/tutorials/shaders/your_first_shader/img/normal.png deleted file mode 100644 index eed99ac68a9..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/normal.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/normal.webp b/tutorials/shaders/your_first_shader/img/normal.webp new file mode 100644 index 00000000000..8ae1486006c Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/normal.webp differ diff --git a/tutorials/shaders/your_first_shader/img/normalmap.png b/tutorials/shaders/your_first_shader/img/normalmap.png deleted file mode 100644 index 182acc3a000..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/normalmap.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/normalmap.webp b/tutorials/shaders/your_first_shader/img/normalmap.webp new file mode 100644 index 00000000000..5904d1f42b0 Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/normalmap.webp differ diff --git a/tutorials/shaders/your_first_shader/img/normalmap2.png b/tutorials/shaders/your_first_shader/img/normalmap2.png deleted file mode 100644 index 15fade8d4f1..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/normalmap2.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/normalmap2.webp b/tutorials/shaders/your_first_shader/img/normalmap2.webp new file mode 100644 index 00000000000..f0350b65216 Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/normalmap2.webp differ diff --git a/tutorials/shaders/your_first_shader/img/plane-sub.png b/tutorials/shaders/your_first_shader/img/plane-sub.png deleted file mode 100644 index b1d412a6e3d..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/plane-sub.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/plane-sub.webp b/tutorials/shaders/your_first_shader/img/plane-sub.webp new file mode 100644 index 00000000000..c44937408f0 Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/plane-sub.webp differ diff --git a/tutorials/shaders/your_first_shader/img/plane.png b/tutorials/shaders/your_first_shader/img/plane.png deleted file mode 100644 index e7886dd8fc0..00000000000 Binary files a/tutorials/shaders/your_first_shader/img/plane.png and /dev/null differ diff --git a/tutorials/shaders/your_first_shader/img/plane.webp b/tutorials/shaders/your_first_shader/img/plane.webp new file mode 100644 index 00000000000..bff5a8319f9 Binary files /dev/null and b/tutorials/shaders/your_first_shader/img/plane.webp differ diff --git a/tutorials/shaders/your_first_shader/your_first_2d_shader.rst b/tutorials/shaders/your_first_shader/your_first_2d_shader.rst index 52bd37edd07..ed1d1e5befe 100644 --- a/tutorials/shaders/your_first_shader/your_first_2d_shader.rst +++ b/tutorials/shaders/your_first_shader/your_first_2d_shader.rst @@ -53,6 +53,14 @@ you are writing a CanvasItem Shader or a Spatial Shader and it previews the output of spatial shaders. So what you are seeing is the output of the default Spatial Shader. +.. note:: + Materials that inherit from the :ref:`class_Material` resource, such as :ref:`class_StandardMaterial3D` + and :ref:`class_ParticleProcessMaterial`, can be converted to a :ref:`class_ShaderMaterial` + and their existing properties will be converted to an accompanying text shader. + To do so, right-click on the material in the FileSystem dock and choose + **Convert to ShaderMaterial**. You can also do so by right-clicking on any + property holding a reference to the material in the inspector. + Click beside "Shader" and select "New Shader". Finally, click on the shader you just created and the shader editor will open. You are now ready to begin writing your first shader. diff --git a/tutorials/shaders/your_first_shader/your_first_3d_shader.rst b/tutorials/shaders/your_first_shader/your_first_3d_shader.rst index d9e468cd83c..1f6c96a0fcd 100644 --- a/tutorials/shaders/your_first_shader/your_first_3d_shader.rst +++ b/tutorials/shaders/your_first_shader/your_first_3d_shader.rst @@ -63,20 +63,21 @@ Setting up Add a new :ref:`MeshInstance3D ` node to your scene. -In the inspector tab beside "Mesh" click "[empty]" and select "New PlaneMesh". -Then click on the image of a plane that appears. +In the inspector tab, set the MeshInstance3D's **Mesh** property to a new +:ref:`PlaneMesh ` resource, by clicking on ```` and +choosing **New PlaneMesh**. Then expand the resource by clicking on the image of +a plane that appears. -This adds a :ref:`PlaneMesh ` to our scene. +This adds a plane to our scene. -Then, in the viewport, click in the upper left corner on the button that says -"Perspective". A menu will appear. In the middle of the menu are options for how -to display the scene. Select 'Display Wireframe'. +Then, in the viewport, click in the upper left corner on the **Perspective** button. +In the menu that appears, select **Display Wireframe**. This will allow you to see the triangles making up the plane. -.. image:: img/plane.png +.. image:: img/plane.webp -Now set ``Subdivide Width`` and ``Subdivide Depth`` of the :ref:`PlaneMesh ` to ``32``. +Now set **Subdivide Width** and **Subdivide Depth** of the :ref:`PlaneMesh ` to ``32``. .. image:: img/plane-sub-set.webp @@ -84,50 +85,48 @@ You can see that there are now many more triangles in the :ref:`MeshInstance3D`. This will give us more vertices to work with and thus allow us to add more detail. -.. image:: img/plane-sub.png +.. image:: img/plane-sub.webp :ref:`PrimitiveMeshes `, like PlaneMesh, only have one -surface, so instead of an array of materials there is only one. Click -beside "Material" where it says "[empty]" and select "New ShaderMaterial". -Then click the sphere that appears. +surface, so instead of an array of materials there is only one. Set the +**Material** to a new ShaderMaterial, then expand the material by clicking on +the sphere that appears. -Now click beside "Shader" where it says "[empty]" and select "New Shader". +.. note:: + Materials that inherit from the :ref:`class_Material` resource, such as :ref:`class_StandardMaterial3D` + and :ref:`class_ParticleProcessMaterial`, can be converted to a :ref:`class_ShaderMaterial` + and their existing properties will be converted to an accompanying text shader. + To do so, right-click on the material in the FileSystem dock and choose + **Convert to ShaderMaterial**. You can also do so by right-clicking on any + property holding a reference to the material in the inspector. -The shader editor should now pop up and you are ready to begin writing your -first Spatial shader! +Now set the material's **Shader** to a new Shader by clicking ```` and +select **New Shader...**. Leave the default settings, give your shader a name, +and click **Create**. + +Click on the shader in the inspector, and the shader editor should now pop up. You +are ready to begin writing your first Spatial shader! Shader magic ------------ .. image:: img/shader-editor.webp -The new shader is already generated with a ``shader_type`` -variable and the ``fragment()`` function. -The first thing Godot shaders need is a declaration -of what type of shader they are. -In this case the ``shader_type`` is set to ``spatial`` -because this is a spatial shader. +The new shader is already generated with a ``shader_type`` variable, the +``vertex()`` function, and the ``fragment()`` function. The first thing Godot +shaders need is a declaration of what type of shader they are. In this case the +``shader_type`` is set to ``spatial`` because this is a spatial shader. .. code-block:: glsl shader_type spatial; -For now ignore the ``fragment()`` function -and define the ``vertex()`` function. The ``vertex()`` function -determines where the vertices of your :ref:`MeshInstance3D` appear in -the final scene. We will be using it to offset the height of each vertex and -make our flat plane appear like a little terrain. - -We define the vertex shader like so: - -.. code-block:: glsl - - void vertex() { - - } +The ``vertex()`` function determines where the vertices of your :ref:`MeshInstance3D` +appear in the final scene. We will be using it to offset the height of each vertex +and make our flat plane appear like a little terrain. With nothing in the ``vertex()`` function, Godot will use its default vertex -shader. We can easily start to make changes by adding a single line: +shader. We can start to make changes by adding a single line: .. code-block:: glsl @@ -137,16 +136,16 @@ shader. We can easily start to make changes by adding a single line: Adding this line, you should get an image like the one below. -.. image:: img/cos.png +.. image:: img/cos.webp Okay, let's unpack this. The ``y`` value of the ``VERTEX`` is being increased. And we are passing the ``x`` and ``z`` components of the ``VERTEX`` as arguments -to ``cos`` and ``sin``; that gives us a wave-like appearance across the ``x`` -and ``z`` axes. +to :ref:`cos() ` and :ref:`sin() `; that gives +us a wave-like appearance across the ``x`` and ``z`` axes. -What we want to achieve is the look of little hills; after all. ``cos`` and -``sin`` already look kind of like hills. We do so by scaling the inputs to the -``cos`` and ``sin`` functions. +What we want to achieve is the look of little hills; after all. ``cos()`` and +``sin()`` already look kind of like hills. We do so by scaling the inputs to the +``cos()`` and ``sin()`` functions. .. code-block:: glsl @@ -154,7 +153,7 @@ What we want to achieve is the look of little hills; after all. ``cos`` and VERTEX.y += cos(VERTEX.x * 4.0) * sin(VERTEX.z * 4.0); } -.. image:: img/cos4.png +.. image:: img/cos4.webp This looks better, but it is still too spiky and repetitive, let's make it a little more interesting. @@ -177,30 +176,19 @@ shader, outside the ``vertex()`` function. uniform sampler2D noise; This will allow you to send a noise texture to the shader. Now look in the -inspector under your material. You should see a section called "Shader Params". -If you open it up, you'll see a section called "noise". - -Click beside it where it says "[empty]" and select "New NoiseTexture2D". Then in -your :ref:`NoiseTexture2D ` click beside where it says "Noise" and select "New -FastNoiseLite". +inspector under your material. You should see a section called **Shader Parameters**. +If you open it up, you'll see a parameter called "Noise". -.. note:: :ref:`FastNoiseLite ` is used by the NoiseTexture2D to - generate a heightmap. +Set this **Noise** parameter to a new :ref:`NoiseTexture2D `. +Then in your NoiseTexture2D, set its **Noise** property to a new +:ref:`FastNoiseLite `. The FastNoiseLite class is used by +the NoiseTexture2D to generate a heightmap. Once you set it up and should look like this. .. image:: img/noise-set.webp -Now, access the noise texture using the ``texture()`` function. ``texture()`` -takes a texture as the first argument and a ``vec2`` for the position on the -texture as the second argument. We use the ``x`` and ``z`` channels of -``VERTEX`` to determine where on the texture to look up. Note that the PlaneMesh -coordinates are within the [-1,1] range (for a size of 2), while the texture -coordinates are within [0,1], so to normalize we divide by the size of the -PlaneMesh by 2.0 and add 0.5. ``texture()`` returns a ``vec4`` of the ``r, g, b, -a`` channels at the position. Since the noise texture is grayscale, all of the -values are the same, so we can use any one of the channels as the height. In -this case we'll use the ``r``, or ``x`` channel. +Now, access the noise texture using the ``texture()`` function: .. code-block:: glsl @@ -209,14 +197,31 @@ this case we'll use the ``r``, or ``x`` channel. VERTEX.y += height; } -Note: ``xyzw`` is the same as ``rgba`` in GLSL, so instead of ``texture().x`` -above, we could use ``texture().r``. See the `OpenGL documentation -`_ for more -details. +:ref:`texture() ` takes a texture as the first argument and +a ``vec2`` for the position on the texture as the second argument. We use the +``x`` and ``z`` channels of ``VERTEX`` to determine where on the texture to look +up. + +Since the PlaneMesh coordinates are within the ``[-1.0, 1.0]`` range (for a size +of ``2.0``), while the texture coordinates are within ``[0.0, 1.0]``, to remap +the coordinates we divide by the size of the PlaneMesh by ``2.0`` and add +``0.5`` . + +``texture()`` returns a ``vec4`` of the ``r, g, b, a`` channels at the position. +Since the noise texture is grayscale, all of the values are the same, so we can +use any one of the channels as the height. In this case we'll use the ``r``, or +``x`` channel. + +.. note:: + + ``xyzw`` is the same as ``rgba`` in GLSL, so instead of ``texture().x`` + above, we could use ``texture().r``. See the `OpenGL documentation + `_ for more + details. Using this code you can see the texture creates random looking hills. -.. image:: img/noise.png +.. image:: img/noise.webp Right now it is too spiky, we want to soften the hills a bit. To do that, we will use a uniform. You already used a uniform above to pass in the noise @@ -225,7 +230,8 @@ texture, now let's learn how they work. Uniforms -------- -Uniform variables allow you to pass data from the game into the shader. They are +:ref:`Uniform variables ` allow you to pass data +from the game into the shader. They are very useful for controlling shader effects. Uniforms can be almost any datatype that can be used in the shader. To use a uniform, you declare it in your :ref:`Shader` using the keyword ``uniform``. @@ -239,11 +245,11 @@ Let's make a uniform that changes the height of the terrain. Godot lets you initialize a uniform with a value; here, ``height_scale`` is set to ``0.5``. You can set uniforms from GDScript by calling the function -``set_shader_parameter()`` on the material corresponding to the shader. The value -passed from GDScript takes precedence over the value used to initialize it in -the shader. +:ref:`set_shader_parameter() ` +on the material corresponding to the shader. The value passed from GDScript +takes precedence over the value used to initialize it in the shader. -:: +.. code-block:: gdscript # called from the MeshInstance3D mesh.material.set_shader_parameter("height_scale", 0.5) @@ -256,8 +262,8 @@ the shader. ``get_surface_material()`` or ``material_override``. Remember that the string passed into ``set_shader_parameter()`` must match the name -of the uniform variable in the :ref:`Shader`. You can use the -uniform variable anywhere inside your :ref:`Shader`. Here, we will +of the uniform variable in the shader. You can use the +uniform variable anywhere inside your shader. Here, we will use it to set the height value instead of arbitrarily multiplying by ``0.5``. .. code-block:: glsl @@ -266,7 +272,7 @@ use it to set the height value instead of arbitrarily multiplying by ``0.5``. Now it looks much better. -.. image:: img/noise-low.png +.. image:: img/noise-low.webp Using uniforms, we can even change the value every frame to animate the height of the terrain. Combined with :ref:`Tweens `, this can be @@ -275,18 +281,19 @@ especially useful for animations. Interacting with light ---------------------- -First, turn wireframe off. To do so, click in the upper-left of the Viewport -again, where it says "Perspective", and select "Display Normal". -Additionally in the 3D scene toolbar, turn off preview sunlight. +First, turn wireframe off. To do so, open the **Perspective** menu in the +upper-left of the viewport again, and select **Display Normal**. Additionally in +the 3D scene toolbar, turn off preview sunlight. -.. image:: img/normal.png +.. image:: img/normal.webp Note how the mesh color goes flat. This is because the lighting on it is flat. Let's add a light! -First, we will add an :ref:`OmniLight3D` to the scene. +First, we will add an :ref:`OmniLight3D` to the scene, and +drag it up so it is above the terrain. -.. image:: img/light.png +.. image:: img/light.webp You can see the light affecting the terrain, but it looks odd. The problem is the light is affecting the terrain as if it were a flat plane. This is because @@ -311,41 +318,31 @@ do that by passing in a second noise texture. uniform sampler2D normalmap; Set this second uniform texture to another :ref:`NoiseTexture2D ` with another -:ref:`FastNoiseLite `. But this time, check **As Normalmap**. +:ref:`FastNoiseLite `. But this time, check **As Normal Map**. .. image:: img/normal-set.webp -Now, because this is a normalmap and not a per-vertex normal, we are going to -assign it in the ``fragment()`` function. The ``fragment()`` function will be -explained in more detail in the next part of this tutorial. - -.. code-block:: glsl - - void fragment() { - } - When we have normals that correspond to a specific vertex we set ``NORMAL``, but if you have a normalmap that comes from a texture, set the normal using -``NORMAL_MAP``. This way Godot will handle the wrapping of texture around the -mesh automatically. +``NORMAL_MAP`` in the ``fragment()`` function. This way Godot will handle +wrapping the texture around the mesh automatically. Lastly, in order to ensure that we are reading from the same places on the noise texture and the normalmap texture, we are going to pass the ``VERTEX.xz`` position from the ``vertex()`` function to the ``fragment()`` function. We do -that with varyings. +that using a :ref:`varying `. -Above the ``vertex()`` define a ``vec2`` called ``tex_position``. And inside the -``vertex()`` function assign ``VERTEX.xz`` to ``tex_position``. +Above the ``vertex()`` define a ``varying vec2`` called ``tex_position``. And +inside the ``vertex()`` function assign ``VERTEX.xz`` to ``tex_position``. .. code-block:: glsl varying vec2 tex_position; void vertex() { - ... tex_position = VERTEX.xz / 2.0 + 0.5; float height = texture(noise, tex_position).x; - ... + VERTEX.y += height * height_scale; } And now we can access ``tex_position`` from the ``fragment()`` function. @@ -359,11 +356,14 @@ And now we can access ``tex_position`` from the ``fragment()`` function. With the normals in place the light now reacts to the height of the mesh dynamically. -.. image:: img/normalmap.png +.. image:: img/normalmap.webp We can even drag the light around and the lighting will update automatically. -.. image:: img/normalmap2.png +.. image:: img/normalmap2.webp + +Full code +--------- Here is the full code for this tutorial. You can see it is not very long as Godot handles most of the difficult stuff for you. diff --git a/tutorials/troubleshooting.rst b/tutorials/troubleshooting.rst index d3b1a819e33..24326fb7474 100644 --- a/tutorials/troubleshooting.rst +++ b/tutorials/troubleshooting.rst @@ -251,3 +251,12 @@ On Windows, this can also be due to :ref:`case sensitivity in your script with a different case than on the filesystem, loading will fail once you export the project. This is because the virtual PCK filesystem is case-sensitive, while Windows's filesystem is case-insensitive by default. + +The project crashes frequently or instantly after opening it from the project manager +------------------------------------------------------------------------------------- + +This could be caused by a number of things such as an editor plugin, GDExtension +addon, or something else. In this scenario it's recommended that you open the +project in recovery mode, and attempt to find and fix whatever is causing the +crashes. See the :ref:`Project Manager page ` for more +information. diff --git a/tutorials/ui/bbcode_in_richtextlabel.rst b/tutorials/ui/bbcode_in_richtextlabel.rst index 82efe33e5f4..8b7041f9a63 100644 --- a/tutorials/ui/bbcode_in_richtextlabel.rst +++ b/tutorials/ui/bbcode_in_richtextlabel.rst @@ -1015,12 +1015,13 @@ Rainbow .. image:: img/bbcode_in_richtextlabel_effect_rainbow.webp Rainbow gives the text a rainbow color that changes over time. Its tag format is -``[rainbow freq=1.0 sat=0.8 val=0.8]{text}[/rainbow]``. +``[rainbow freq=1.0 sat=0.8 val=0.8 speed=1.0]{text}[/rainbow]``. -``freq`` is the number of full rainbow cycles per second, ``sat`` is the -saturation of the rainbow, ``val`` is the value of the rainbow. A ``freq`` value -of ``0`` will pause the animation, while negative ``freq`` will play the -animation backwards. +``freq`` determines how many letters the rainbow extends over before it repeats itself, +``sat`` is the saturation of the rainbow, ``val`` is the value of the rainbow. ``speed`` +is the number of full rainbow cycles per second. A positive ``speed`` value will play +the animation forwards, a value of ``0`` will pause the animation, and a negative +``speed`` value will play the animation backwards. Font outlines are *not* affected by the rainbow effect (they keep their original color). Existing font colors are overridden by the rainbow effect. However, CanvasItem's diff --git a/tutorials/xr/img/openxr_settings.webp b/tutorials/xr/img/openxr_settings.webp index b6047feef51..fcd393b2901 100644 Binary files a/tutorials/xr/img/openxr_settings.webp and b/tutorials/xr/img/openxr_settings.webp differ diff --git a/tutorials/xr/img/xr_basic_scene.webp b/tutorials/xr/img/xr_basic_scene.webp new file mode 100644 index 00000000000..ab702e5fa50 Binary files /dev/null and b/tutorials/xr/img/xr_basic_scene.webp differ diff --git a/tutorials/xr/img/xr_left_hand.webp b/tutorials/xr/img/xr_left_hand.webp new file mode 100644 index 00000000000..ed00358378a Binary files /dev/null and b/tutorials/xr/img/xr_left_hand.webp differ diff --git a/tutorials/xr/img/xr_right_hand.webp b/tutorials/xr/img/xr_right_hand.webp new file mode 100644 index 00000000000..3f573ea8645 Binary files /dev/null and b/tutorials/xr/img/xr_right_hand.webp differ diff --git a/tutorials/xr/img/xr_shaders.webp b/tutorials/xr/img/xr_shaders.webp new file mode 100644 index 00000000000..cc145686250 Binary files /dev/null and b/tutorials/xr/img/xr_shaders.webp differ diff --git a/tutorials/xr/openxr_settings.rst b/tutorials/xr/openxr_settings.rst index 54833820d4a..ffa8cd67b81 100644 --- a/tutorials/xr/openxr_settings.rst +++ b/tutorials/xr/openxr_settings.rst @@ -7,7 +7,7 @@ OpenXR has its own set of settings that are applied when OpenXR starts. While it is possible for OpenXR extensions implemented through Godot plugins to add additional settings, we will only discuss the settings in the core of Godot here. -.. image:: img/openxr_settings.png +.. image:: img/openxr_settings.webp Enabled ------- diff --git a/tutorials/xr/setting_up_xr.rst b/tutorials/xr/setting_up_xr.rst index 431f3a2aa6d..c53eb7c12fb 100644 --- a/tutorials/xr/setting_up_xr.rst +++ b/tutorials/xr/setting_up_xr.rst @@ -28,30 +28,14 @@ There are three XR specific node types that you will find in nearly all XR appli There are other XR related nodes and there is much more to say about these three nodes, but we'll get into that later on. -Prerequisites for XR in Godot 4 -------------------------------- +Which Renderer to use +--------------------- -While in Godot 3 most things worked out of the box, Godot 4 needs a little more -setup. This is mainly due to the more advanced nature of the Vulkan renderer. -There are many rendering features in Vulkan the XR system uses that aren't -enabled by default. To turn them on, open up your project settings and tick -:ref:`XR > Shaders > Enabled `: - -.. image:: img/xr_shaders.png - -.. UPDATE: Not supported yet. When all or most post process effects work in -.. stereoscopic rendering, remove or update this note. - -.. warning:: - As Godot 4 is still in development, many post process effects have not yet been updated to support stereoscopic rendering. Using these will have adverse effects. - -.. UPDATE: Recommended renderer may change. If the Mobile renderer (or any other -.. renderer) is recommended for all XR projects, update this note. - -.. note:: - Godot 4 has 3 renderer options, Compatibility, Mobile, and Forward+. In the future XR desktop projects should use Forward+, and projects for standalone headsets - should use Mobile. Currently Compatibility is the recommended renderer for standalone headsets, and ironically Mobile is the recommended renderer for desktop. - This is based on current XR performance on the different devices with each renderer. +Godot has 3 renderer options for projects: Compatibility, Mobile, and Forward+. +The current recommendation is to use the Mobile renderer for any desktop VR project, +and use the Compatibility renderer for any project running on a standalone headset +like the Meta Quest 3. XR projects will run with the Forward+ renderer, but it isn't +well optimized for XR right now compared to the other two. OpenXR ------ @@ -60,27 +44,41 @@ OpenXR is a new industry standard that allows different XR platforms to present The Vulkan implementation of OpenXR is closely integrated with Vulkan, taking over part of the Vulkan system. This requires tight integration of certain core graphics features in the Vulkan renderer which are needed before the XR system is setup. This was one of the main deciding factors to include OpenXR as a core interface. -This also means OpenXR needs to be enabled when Godot starts in order to set things up correctly. The required setting can be found in your project settings: +This also means OpenXR needs to be enabled when Godot starts in order to set things +up correctly. Check the :ref:`Enabled` +setting in your project settings under **XR > OpenXR**. + +.. image:: img/openxr_settings.webp + +You can find several other settings related to OpenXR here as well. These can't be +changed while your application is running. The default settings will get us started, +but for more information on what's here see :ref:`doc_openxr_settings`. -.. image:: img/openxr_settings.png +You'll also need to go to **XR > Shaders** in the project settings and check the +:ref:`Enabled` +box to enable them. Once you've done that click the **Save & Restart** button. + +.. image:: img/xr_shaders.webp + +.. warning:: + Many post process effects have not yet been updated to support stereoscopic rendering. Using these will have adverse effects. -As setup is brought forward with OpenXR you can find several other settings related to OpenXR here as well. These can't be changed while your application is running. -The default settings will get us started and we will go into detail in another section of the documentation. Setting up the XR scene ----------------------- Every XR application needs at least an :ref:`XROrigin3D ` and an :ref:`XRCamera3D ` node. Most will have two :ref:`XRController3D `, one for the left hand and one for the right. Keep in mind that the camera and controller nodes should be children of the origin node. Add these nodes to a new scene and rename the controller nodes to ``LeftHand`` and ``RightHand``, your scene should look something like this: -.. image:: img/xr_basic_scene.png +.. image:: img/xr_basic_scene.webp -Next you need to configure the controllers, select the left hand and set it up as follows: +The warning icons are expected and should go away after you configure the +controllers. Select the left hand and set it up as follows: -.. image:: img/xr_left_hand.png +.. image:: img/xr_left_hand.webp And the right hand: -.. image:: img/xr_right_hand.png +.. image:: img/xr_right_hand.webp Right now all these nodes are on the floor, they will be positioned correctly in runtime. To help during development, it can be helpful to move the camera upwards so its ``y`` is set to ``1.7``, and move the controller nodes to ``-0.5, 1.0, -0.5`` and ``0.5, 1.0, -0.5`` for respectively the left and right hand. diff --git a/tutorials/xr/xr_action_map.rst b/tutorials/xr/xr_action_map.rst index 701e448e5d7..8aa6a16ccb3 100644 --- a/tutorials/xr/xr_action_map.rst +++ b/tutorials/xr/xr_action_map.rst @@ -17,7 +17,7 @@ and binding these to the actual inputs and outputs on your XR devices. As the XR action map is currently part of the OpenXR module, OpenXR needs to be enabled in your project settings to expose it: -.. image:: img/openxr_settings.png +.. image:: img/openxr_settings.webp You will then find the XR Action Map interface in the bottom of the screen: