From 8a6ad4c926b592e28a83a2ea8bbdf315a37b71f1 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Wed, 28 May 2025 00:43:34 +0200 Subject: [PATCH] Replace uses of shorthand codeblock syntax to avoid issues with localization Previously, many paragraphs in the documentation used `::` at the end of a line as a replacement for a single colon (and `::` on the following line). Due to this, the `::` was part of the extracted string for localization. Weblate also showed a warning about the trailing `::`, as it's not normally expected to be there. This change requires translators to revalidate all modified strings. However, considering many of those have broken code blocks due to translators replacing `::` with `:`, it can be a good idea. This also adds documentation writing guidelines for code blocks and admonitions. This commit does not modify existing admonitions in any way (as this would lead to a much larger diff, and require more localizable text to be revalidated by translators). --- about/complying_with_licenses.rst | 4 +- .../compiling/compiling_for_ios.rst | 8 +- .../compiling/compiling_for_linuxbsd.rst | 16 +- .../compiling/compiling_for_macos.rst | 32 ++- .../compiling/compiling_for_web.rst | 32 ++- .../compiling/compiling_for_windows.rst | 40 +++- .../compiling/compiling_with_dotnet.rst | 4 +- contributing/development/compiling/index.rst | 4 +- .../introduction_to_the_buildsystem.rst | 16 +- .../custom_modules_in_cpp.rst | 12 +- .../custom_resource_format_loaders.rst | 4 +- .../development/debugging/macos_debug.rst | 4 +- .../vulkan/vulkan_validation_layers.rst | 4 +- .../documentation/docs_image_guidelines.rst | 8 +- .../documentation/docs_writing_guidelines.rst | 56 ++++- .../editor_and_docs_localization.rst | 4 +- .../import_configuration.rst | 4 +- .../best_practices/project_organization.rst | 8 +- tutorials/export/exporting_projects.rst | 4 +- tutorials/i18n/pseudolocalization.rst | 4 +- tutorials/io/binary_serialization_api.rst | 4 +- .../migrating/upgrading_to_godot_4.1.rst | 4 +- tutorials/physics/physics_introduction.rst | 8 +- tutorials/platform/android/android_plugin.rst | 88 ++++---- tutorials/platform/ios/ios_plugin.rst | 4 +- .../scripting/evaluating_expressions.rst | 16 +- .../scripting/gdscript/gdscript_basics.rst | 212 +++++++++++++----- .../gdscript_documentation_comments.rst | 12 +- .../scripting/gdscript/gdscript_exports.rst | 24 +- .../scripting/gdscript/static_typing.rst | 92 ++++++-- .../shader_reference/shader_functions.rst | 44 +++- tutorials/ui/bbcode_in_richtextlabel.rst | 4 +- 32 files changed, 580 insertions(+), 200 deletions(-) diff --git a/about/complying_with_licenses.rst b/about/complying_with_licenses.rst index b0f6cb977..8f58eccfd 100644 --- a/about/complying_with_licenses.rst +++ b/about/complying_with_licenses.rst @@ -42,7 +42,9 @@ Requirements In the case of the MIT license, the only requirement is to include the license text somewhere in your game or derivative project. -This text reads as follows:: +This text reads as follows: + +:: This game uses Godot Engine, available under the following license: diff --git a/contributing/development/compiling/compiling_for_ios.rst b/contributing/development/compiling/compiling_for_ios.rst index 21fa461b3..1ad0d877f 100644 --- a/contributing/development/compiling/compiling_for_ios.rst +++ b/contributing/development/compiling/compiling_for_ios.rst @@ -24,7 +24,9 @@ Requirements from the `MoltenVK SDK `__. .. note:: If you have `Homebrew `_ installed, you can easily - install SCons using the following command:: + install SCons using the following command: + + :: brew install scons @@ -33,7 +35,9 @@ Requirements Similarly, if you have `MacPorts `_ installed, you can easily install SCons using the - following command:: + following command: + + :: sudo port install scons diff --git a/contributing/development/compiling/compiling_for_linuxbsd.rst b/contributing/development/compiling/compiling_for_linuxbsd.rst index df084095c..e618196b6 100644 --- a/contributing/development/compiling/compiling_for_linuxbsd.rst +++ b/contributing/development/compiling/compiling_for_linuxbsd.rst @@ -301,11 +301,15 @@ Running a headless/server build ------------------------------- To run in *headless* mode which provides editor functionality to export -projects in an automated manner, use the normal build:: +projects in an automated manner, use the normal build: + +:: scons platform=linuxbsd target=editor -And then use the ``--headless`` command line argument:: +And then use the ``--headless`` command line argument: + +:: ./bin/godot.linuxbsd.editor.x86_64 --headless @@ -468,7 +472,9 @@ the default GCC + GNU ld setup: - Clang tends to give more useful error messages compared to GCC. To do so, install Clang and the ``lld`` package from your distribution's package manager -then use the following SCons command:: +then use the following SCons command: + +:: scons platform=linuxbsd use_llvm=yes linker=lld @@ -478,7 +484,9 @@ created in the ``bin/`` folder. It's still recommended to use GCC for production builds as they can be compiled using link-time optimization, making the resulting binaries smaller and faster. -If this error occurs:: +If this error occurs: + +:: /usr/bin/ld: cannot find -l:libatomic.a: No such file or directory diff --git a/contributing/development/compiling/compiling_for_macos.rst b/contributing/development/compiling/compiling_for_macos.rst index 9f3af62ff..488e0c838 100644 --- a/contributing/development/compiling/compiling_for_macos.rst +++ b/contributing/development/compiling/compiling_for_macos.rst @@ -25,7 +25,9 @@ For compiling under macOS, the following is required: ``misc/scripts/install_vulkan_sdk_macos.sh`` within the Godot source repository. .. note:: If you have `Homebrew `_ installed, you can easily - install SCons using the following command:: + install SCons using the following command: + + :: brew install scons @@ -34,7 +36,9 @@ For compiling under macOS, the following is required: Similarly, if you have `MacPorts `_ installed, you can easily install SCons using the - following command:: + following command: + + :: sudo port install scons @@ -80,7 +84,9 @@ 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 command used to build editor: + +:: scons platform=macos arch=x86_64 scons platform=macos arch=arm64 generate_bundle=yes @@ -89,7 +95,9 @@ 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:: +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 @@ -117,11 +125,15 @@ Running a headless/server build ------------------------------- To run in *headless* mode which provides editor functionality to export -projects in an automated manner, use the normal build:: +projects in an automated manner, use the normal build: + +:: scons platform=macos target=editor -And then use the ``--headless`` command line argument:: +And then use the ``--headless`` command line argument: + +:: ./bin/godot.macos.editor.x86_64 --headless @@ -179,7 +191,9 @@ an *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both wer MoltenVK without having to recompile export templates. You can then zip the ``macos_template.app`` folder to reproduce the ``macos.zip`` -template from the official Godot distribution:: +template from the official Godot distribution: + +:: zip -r9 macos.zip macos_template.app @@ -208,7 +222,9 @@ repository/extracted the zip), e.g.:: export OSXCROSS_ROOT="$HOME/osxcross" -Now you can compile with SCons like you normally would:: +Now you can compile with SCons like you normally would: + +:: scons platform=macos diff --git a/contributing/development/compiling/compiling_for_web.rst b/contributing/development/compiling/compiling_for_web.rst index 099248dbb..a4c0f977e 100644 --- a/contributing/development/compiling/compiling_for_web.rst +++ b/contributing/development/compiling/compiling_for_web.rst @@ -34,7 +34,9 @@ and ``source ./emsdk_env.sh``/``emsdk_env.bat``. Open a terminal and navigate to the root directory of the engine source code. Then instruct SCons to build the Web platform. Specify ``target`` as -either ``template_release`` for a release build or ``template_debug`` for a debug build:: +either ``template_release`` for a release build or ``template_debug`` for a debug build: + +:: scons platform=web target=template_release scons platform=web target=template_debug @@ -42,13 +44,17 @@ either ``template_release`` for a release build or ``template_debug`` for a debu By default, the :ref:`JavaScriptBridge singleton ` will be built into the engine. Official export templates also have the JavaScript singleton enabled. Since ``eval()`` calls can be a security concern, the -``javascript_eval`` option can be used to build without the singleton:: +``javascript_eval`` option can be used to build without the singleton: + +:: scons platform=web target=template_release javascript_eval=no scons platform=web target=template_debug javascript_eval=no By default, WebWorker threads support is enabled. To disable it and only use a single thread, -the ``threads`` option can be used to build the web template without threads support:: +the ``threads`` option can be used to build the web template without threads support: + +:: scons platform=web target=template_release threads=no scons platform=web target=template_debug threads=no @@ -59,11 +65,15 @@ the resulting file will be placed in the ``bin`` subdirectory. Its name is for debug. Finally, rename the zip archive to ``web_release.zip`` for the -release template:: +release template: + +:: mv bin/godot.web.template_release.wasm32.zip bin/web_release.zip -And ``web_debug.zip`` for the debug template:: +And ``web_debug.zip`` for the debug template: + +:: mv bin/godot.web.template_debug.wasm32.zip bin/web_debug.zip @@ -75,7 +85,9 @@ performance and compatibility reasons. See the :ref:`export page ` for more info. You can build the export templates using the option ``dlink_enabled=yes`` -to enable GDExtension support:: +to enable GDExtension support: + +:: scons platform=web dlink_enabled=yes target=template_release scons platform=web dlink_enabled=yes target=template_debug @@ -84,7 +96,9 @@ Once finished, the resulting file will be placed in the ``bin`` subdirectory. Its name will have ``_dlink`` added. Finally, rename the zip archives to ``web_dlink_release.zip`` and -``web_dlink_release.zip`` for the release template:: +``web_dlink_release.zip`` for the release template: + +:: mv bin/godot.web.template_release.wasm32.dlink.zip bin/web_dlink_release.zip mv bin/godot.web.template_debug.wasm32.dlink.zip bin/web_dlink_debug.zip @@ -94,7 +108,9 @@ Building the editor It is also possible to build a version of the Godot editor that can run in the browser. The editor version is not recommended -over the native build. You can build the editor with:: +over the native build. You can build the editor with: + +:: scons platform=web target=editor diff --git a/contributing/development/compiling/compiling_for_windows.rst b/contributing/development/compiling/compiling_for_windows.rst index 0bb360998..9e595495f 100644 --- a/contributing/development/compiling/compiling_for_windows.rst +++ b/contributing/development/compiling/compiling_for_windows.rst @@ -38,13 +38,17 @@ For compiling under Windows, the following is required: Studio releases. .. note:: If you have `Scoop `_ installed, you can easily - install MinGW and other dependencies using the following command:: + install MinGW and other dependencies using the following command: + + :: scoop install python mingw Scons will still need to be installed via pip .. note:: If you have `MSYS2 `_ installed, you can easily - install MinGW and other dependencies using the following command:: + install MinGW and other dependencies using the following command: + + :: pacman -S mingw-w64-x86_64-python3-pip mingw-w64-x86_64-gcc \ mingw-w64-i686-python3-pip mingw-w64-i686-gcc make @@ -61,7 +65,9 @@ For compiling under Windows, the following is required: Setting up SCons ---------------- -To install SCons, open the command prompt and run the following command:: +To install SCons, open the command prompt and run the following command: + +:: python -m pip install scons @@ -205,7 +211,9 @@ optional PIX and Agility SDK components). which is needed to generate some files. 2. Clone the `godot-nir-static `_ directory and navigate to it. - 3. Run the following:: + 3. Run the following: + + :: git submodule update --init ./update_mesa.sh @@ -244,7 +252,9 @@ Optionally, you can compile with the following for additional features: developer mode in Windows; otherwise it won't be used. .. note:: If you want to use a PIX with MinGW build, navigate to PIX runtime - directory and use the following commands to generate import library:: + directory and use the following commands to generate import library: + + :: # For x86-64: gendef ./bin/x64/WinPixEventRuntime.dll @@ -300,7 +310,9 @@ To compile Godot with statically linked ANGLE: 1. Clone the `godot-angle-static `_ directory and navigate to it. - 2. Run the following command:: + 2. Run the following command: + + :: git submodule update --init ./update_angle.sh @@ -330,7 +342,9 @@ Folder-based editors don't require any particular setup to start working with Go codebase. To edit projects with Visual Studio they need to be set up as a solution. You can create a Visual Studio solution via SCons by running SCons with -the ``vsproj=yes`` parameter, like this:: +the ``vsproj=yes`` parameter, like this: + +:: scons platform=windows vsproj=yes @@ -373,7 +387,9 @@ The package names may differ based on your distribution, here are some known one +----------------+--------------------------------------------------------------+ Before attempting the compilation, SCons will check for -the following binaries in your ``PATH`` environment variable:: +the following binaries in your ``PATH`` environment variable: + +:: # for MinGW-w64 i686-w64-mingw32-gcc @@ -386,7 +402,9 @@ the following binaries in your ``PATH`` environment variable:: If the binaries are not located in the ``PATH`` (e.g. ``/usr/bin``), you can define the following environment variable to give a hint to -the build system:: +the build system: + +:: export MINGW_PREFIX="/path/to/mingw" @@ -452,7 +470,9 @@ following location, replacing ```` with the version identifier %APPDATA%\Godot\export_templates\\ -With the following names:: +With the following names: + +:: windows_debug_x86_32_console.exe windows_debug_x86_32.exe diff --git a/contributing/development/compiling/compiling_with_dotnet.rst b/contributing/development/compiling/compiling_with_dotnet.rst index d696519b2..069d6f455 100644 --- a/contributing/development/compiling/compiling_with_dotnet.rst +++ b/contributing/development/compiling/compiling_with_dotnet.rst @@ -33,7 +33,9 @@ These source files must be generated before building the managed libraries. They can be generated by any .NET-enabled Godot editor binary by running it with the parameters ``--headless --generate-mono-glue`` followed by the path to an output directory. -This path must be ``modules/mono/glue`` in the Godot directory:: +This path must be ``modules/mono/glue`` in the Godot directory: + +:: --headless --generate-mono-glue modules/mono/glue diff --git a/contributing/development/compiling/index.rst b/contributing/development/compiling/index.rst index 58a89b427..8ad227a1b 100644 --- a/contributing/development/compiling/index.rst +++ b/contributing/development/compiling/index.rst @@ -9,7 +9,9 @@ Building from source Godot prides itself on being very easy to build, by C++ projects' standards. :ref:`Godot uses the SCons build system `, and after the initial -setup compiling the engine for your current platform should be as easy as running:: +setup compiling the engine for your current platform should be as easy as running: + +:: scons diff --git a/contributing/development/compiling/introduction_to_the_buildsystem.rst b/contributing/development/compiling/introduction_to_the_buildsystem.rst index 9d9e104f4..f3edc60b2 100644 --- a/contributing/development/compiling/introduction_to_the_buildsystem.rst +++ b/contributing/development/compiling/introduction_to_the_buildsystem.rst @@ -8,18 +8,24 @@ Introduction to the buildsystem Godot is a primarily C++ project and it :ref:`uses the SCons build system. ` We love SCons for how maintainable and easy to set up it makes our buildsystem. And thanks to -that compiling Godot from source can be as simple as running:: +that compiling Godot from source can be as simple as running: + +:: scons This produces an editor build for your current platform, operating system, and architecture. You can change what gets built by specifying a target, a platform, and/or an architecture. -For example, to build an export template used for running exported games, you can run:: +For example, to build an export template used for running exported games, you can run: + +:: scons target=template_release If you plan to debug or develop the engine, then you might want to enable the ``dev_build`` -option to enable dev-only debugging code:: +option to enable dev-only debugging code: + +:: scons dev_build=yes @@ -90,7 +96,9 @@ Resulting binary ---------------- The resulting binaries will be placed in the ``bin/`` subdirectory, -generally with this naming convention:: +generally with this naming convention: + +:: godot..[.dev][.double].[.][.] diff --git a/contributing/development/core_and_modules/custom_modules_in_cpp.rst b/contributing/development/core_and_modules/custom_modules_in_cpp.rst index e01e826df..aab49f487 100644 --- a/contributing/development/core_and_modules/custom_modules_in_cpp.rst +++ b/contributing/development/core_and_modules/custom_modules_in_cpp.rst @@ -535,11 +535,15 @@ main ``doc/classes`` directory. .. tip:: You can use Git to check if you have missed some of your classes by checking the - untracked files with ``git status``. For example:: + untracked files with ``git status``. For example: + + :: git status - Example output:: + Example output: + + :: Untracked files: (use "git add ..." to include in what will be committed) @@ -561,9 +565,9 @@ to an another folder, and just copy over the files that you need. Run command: - :: +:: - bin/ --doctool . + bin/ --doctool . Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see that it contains a ``Summator.xml`` file, or any other classes, that you referenced diff --git a/contributing/development/core_and_modules/custom_resource_format_loaders.rst b/contributing/development/core_and_modules/custom_resource_format_loaders.rst index 98fb1cb29..66e1f6294 100644 --- a/contributing/development/core_and_modules/custom_resource_format_loaders.rst +++ b/contributing/development/core_and_modules/custom_resource_format_loaders.rst @@ -362,7 +362,9 @@ project's root folder: ] } -Then attach the following script to any node:: +Then attach the following script to any node: + +:: extends Node diff --git a/contributing/development/debugging/macos_debug.rst b/contributing/development/debugging/macos_debug.rst index babadb9df..7a6dff785 100644 --- a/contributing/development/debugging/macos_debug.rst +++ b/contributing/development/debugging/macos_debug.rst @@ -34,7 +34,9 @@ Create an ``editor.entitlements`` text file with the following contents: -Then use the following command to re-sign the editor:: +Then use the following command to re-sign the editor: + +:: codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements ./path/to/Godot.app diff --git a/contributing/development/debugging/vulkan/vulkan_validation_layers.rst b/contributing/development/debugging/vulkan/vulkan_validation_layers.rst index ad9b49260..eced5343f 100644 --- a/contributing/development/debugging/vulkan/vulkan_validation_layers.rst +++ b/contributing/development/debugging/vulkan/vulkan_validation_layers.rst @@ -164,7 +164,9 @@ Copy libraries Copy libraries from ``Vulkan-ValidationLayers/build-android/libs`` to ``godot/platform/android/java/app/libs/debug/vulkan_validation_layers``. -Your Godot source directory tree should look like on the example below:: +Your Godot source directory tree should look like on the example below: + +:: godot |-- platform diff --git a/contributing/documentation/docs_image_guidelines.rst b/contributing/documentation/docs_image_guidelines.rst index 05f30dd85..ceb39e906 100644 --- a/contributing/documentation/docs_image_guidelines.rst +++ b/contributing/documentation/docs_image_guidelines.rst @@ -160,7 +160,9 @@ All images are stored in folders named ``img`` next to the page they are used in To add your image, add it to the ``img`` folder that's in the same folder as the ``.rst`` file for the page (create it if it doesn't exist). In the ``.rst`` page, -images should be included with the following code snippet:: +images should be included with the following code snippet: + +:: .. image:: img/documentation_image.webp @@ -245,7 +247,9 @@ All videos are stored in folders named ``video`` next to the page they are used To add your video, add it to the ``video`` folder that's in the same folder as the ``.rst`` file for the page (create it if it doesn't exist). In the ``.rst`` page, -videos should be included with the following code snippet:: +videos should be included with the following code snippet: + +:: .. video:: video/csg_tools.webm :alt: Put a text description of the video here diff --git a/contributing/documentation/docs_writing_guidelines.rst b/contributing/documentation/docs_writing_guidelines.rst index e22829b90..01626d3c8 100644 --- a/contributing/documentation/docs_writing_guidelines.rst +++ b/contributing/documentation/docs_writing_guidelines.rst @@ -559,7 +559,7 @@ Emphasis Use either **bold style** or *italic style* to emphasize words or sentences. In most cases, either **bold** or *italics* is fine. Use whichever seems best, -or whatever the page already uses. +or whatever the page already uses. Prefer using **bold style** for simple emphasis. @@ -643,6 +643,58 @@ rendered, prefer splitting the setting name and the section when the link is lon - In the project settings under **Application > Run**, set :ref:`Max FPS` to ``60``. - In **Project Settings > Application > Run**, set :ref:`Max FPS` to ``60``. +Code blocks and adominitions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code blocks should use the ``::`` syntax on its own line. Do not use the short +form where it's at the end of a paragraph, as the trailing ``::`` would be included +in the localizable string otherwise. Weblate would show a warning due to the trailing ``::``, +and if the localized string does not end with ``::``, it would break the code block entirely +in the translated manual. + + +**Bad:** + +:: + + This is a code block:: + + The code block's contents. + +**Good:** + +:: + + This is a code block: + + :: + + The code block's contents. + +As for admonitions (note, warning, etc. blocks), you should write the admonition tag on its own line, +then the admonition's contents indented by 4 spaces. Do not write the first line of the contents +on the same line as the admonition tag. + +**Bad:** + +:: + + This is an admonition: + + .. note:: First line of the note's contents. + Second line of the note's contents. + +**Good:** + +:: + + This is an admonition: + + .. note:: + + First line of the note's contents. + Second line of the note's contents. + .. _doc_docs_writing_guidelines_manually_wrapping_lines: Manually wrapping lines @@ -759,6 +811,6 @@ Follow these guidelines for when to refer to a specific Godot version: - If the default approach to a problem is changed in a 4.x minor version, **do specify** the minor version in which a new default approach was added. For example, the change from ``TileMap`` to ``TileMapLayer`` in 4.3. -- If a feature was added in a 3.x major or minor version, **do not specify** when +- If a feature was added in a 3.x major or minor version, **do not specify** when the feature was added. These features are old enough that the exact version in which they were added is not relevant. diff --git a/contributing/documentation/editor_and_docs_localization.rst b/contributing/documentation/editor_and_docs_localization.rst index c52d30e50..e7d247b00 100644 --- a/contributing/documentation/editor_and_docs_localization.rst +++ b/contributing/documentation/editor_and_docs_localization.rst @@ -250,7 +250,9 @@ Online documentation (RST) The documentation translations originate from reStructuredText (RST) files, which also use their own markup syntax to style text, create internal and -external links, etc. Here are some examples:: +external links, etc. Here are some examples: + +:: # "development" is styled bold. # "Have a look here" is a link pointing to https://docs.godotengine.org/en/latest. diff --git a/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst index 845b60cce..7e4b03ebc 100644 --- a/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst +++ b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst @@ -478,7 +478,9 @@ script. For example: include all tracks in animations with names ending in ``"_Loop"``, but discard any tracks affecting a ``"Skeleton"`` which end in ``"Control"``, -unless they have ``"Arm"`` in their name:: +unless they have ``"Arm"`` in their name: + +:: @+*_Loop +* diff --git a/tutorials/best_practices/project_organization.rst b/tutorials/best_practices/project_organization.rst index 5a3e9927b..9eb806850 100644 --- a/tutorials/best_practices/project_organization.rst +++ b/tutorials/best_practices/project_organization.rst @@ -113,7 +113,9 @@ in general). On Windows 10, to further avoid mistakes related to case sensitivity, you can also make the project folder case-sensitive. After enabling the Windows -Subsystem for Linux feature, run the following command in a PowerShell window:: +Subsystem for Linux feature, run the following command in a PowerShell window: + +:: # To enable case-sensitivity: fsutil file setcasesensitiveinfo enable @@ -123,6 +125,8 @@ Subsystem for Linux feature, run the following command in a PowerShell window:: If you haven't enabled the Windows Subsystem for Linux, you can enter the following line in a PowerShell window *running as Administrator* then reboot -when asked:: +when asked: + +:: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux diff --git a/tutorials/export/exporting_projects.rst b/tutorials/export/exporting_projects.rst index d0d319730..8b5593377 100644 --- a/tutorials/export/exporting_projects.rst +++ b/tutorials/export/exporting_projects.rst @@ -248,7 +248,9 @@ depending on your needs. Due to a `known bug `__, when using a ZIP file as a pack file, the exported binary will not try to use it automatically. Therefore, you have to create a *launcher script* that - the player can double-click or run from a terminal to launch the project:: + the player can double-click or run from a terminal to launch the project: + + :: :: launch.bat (Windows) @echo off diff --git a/tutorials/i18n/pseudolocalization.rst b/tutorials/i18n/pseudolocalization.rst index a9ef607e4..07af4df13 100644 --- a/tutorials/i18n/pseudolocalization.rst +++ b/tutorials/i18n/pseudolocalization.rst @@ -79,7 +79,9 @@ and then calling :ref:`TranslationServer.reload_pseudolocalization() ` which reparses the pseudolocalization properties and reloads the pseudolocalization. The following code snippet shall turn on ``replace_with_accents`` and ``double_vowels`` properties -and then call ``reload_pseudolocalization()`` for the changes to get reflected:: +and then call ``reload_pseudolocalization()`` for the changes to get reflected: + +:: ProjectSettings.set_setting("internationalization/pseudolocalization/replace_with_accents", true) ProjectSettings.set_setting("internationalization/pseudolocalization/double_vowels", true) diff --git a/tutorials/io/binary_serialization_api.rst b/tutorials/io/binary_serialization_api.rst index 66b700116..09bd39bdb 100644 --- a/tutorials/io/binary_serialization_api.rst +++ b/tutorials/io/binary_serialization_api.rst @@ -34,7 +34,9 @@ little-endian-encoded. All packets have a 4-byte header representing an integer, specifying the type of data. The lowest value two bytes are used to determine the type, while the highest value -two bytes contain flags:: +two bytes contain flags: + +:: base_type = val & 0xFFFF; flags = val >> 16; diff --git a/tutorials/migrating/upgrading_to_godot_4.1.rst b/tutorials/migrating/upgrading_to_godot_4.1.rst index a48365430..50052147e 100644 --- a/tutorials/migrating/upgrading_to_godot_4.1.rst +++ b/tutorials/migrating/upgrading_to_godot_4.1.rst @@ -281,7 +281,9 @@ There are two small changes: #. The first argument changes from ``const GDExtensionInterface *p_interface`` to ``GDExtensionInterfaceGetProcAddress p_get_proc_address`` #. The constructor for the `init_obj` variable now receives ``p_get_proc_address`` as its first parameter -You also need to add an extra ``compatibility_minimum`` line to your ``.gdextension`` file, so that it looks something like:: +You also need to add an extra ``compatibility_minimum`` line to your ``.gdextension`` file, so that it looks something like: + +:: [configuration] diff --git a/tutorials/physics/physics_introduction.rst b/tutorials/physics/physics_introduction.rst index 981c7924f..67c2f14f0 100644 --- a/tutorials/physics/physics_introduction.rst +++ b/tutorials/physics/physics_introduction.rst @@ -163,7 +163,9 @@ can use binary, hexadecimal, or decimal notation for layer masks, depending on your preference. The code equivalent of the above example where layers 1, 3 and 4 were enabled -would be as follows:: +would be as follows: + +:: # Example: Setting mask value for enabling layers 1, 3 and 4 @@ -181,7 +183,9 @@ would be as follows:: pow(2, 1-1) + pow(2, 3-1) + pow(2, 4-1) You can also set bits independently by calling ``set_collision_layer_value(layer_number, value)`` -or ``set_collision_mask_value(layer_number, value)`` on any given :ref:`CollisionObject2D ` as follows:: +or ``set_collision_mask_value(layer_number, value)`` on any given :ref:`CollisionObject2D ` as follows: + +:: # Example: Setting mask value to enable layers 1, 3, and 4. diff --git a/tutorials/platform/android/android_plugin.rst b/tutorials/platform/android/android_plugin.rst index 61c906f3f..27cfa2da7 100644 --- a/tutorials/platform/android/android_plugin.rst +++ b/tutorials/platform/android/android_plugin.rst @@ -128,11 +128,13 @@ Use the following steps if you have a v1 Android plugin you want to migrate to v 2. Update the Godot Android library build dependency: - You can continue using the ``godot-lib...aar`` binary from `Godot's download page `_ if that's your preference. Make sure it's updated to the latest stable version. - - Or you can switch to the MavenCentral provided dependency:: + - Or you can switch to the MavenCentral provided dependency: - dependencies { - implementation("org.godotengine:godot:4.2.0.stable") - } +:: + + dependencies { + implementation("org.godotengine:godot:4.2.0.stable") + } 3. After updating the Godot Android library dependency, sync or build the plugin and resolve any compile errors: @@ -150,46 +152,48 @@ As mentioned, a v2 Android plugin is now provided to the Godot Editor as an ``Ed 2. Add the `tool script `_ for the export functionality within the plugin directory (e.g: in ``addons//``) - The created script must be a ``@tool`` script, or else it will not work properly - - The export tool script is used to configure the Android plugin and hook it within the Godot Editor's export process. It should look something like this:: + - The export tool script is used to configure the Android plugin and hook it within the Godot Editor's export process. It should look something like this: - @tool - extends EditorPlugin +:: - # A class member to hold the editor export plugin during its lifecycle. - var export_plugin : AndroidExportPlugin + @tool + extends EditorPlugin - func _enter_tree(): - # Initialization of the plugin goes here. - export_plugin = AndroidExportPlugin.new() - add_export_plugin(export_plugin) + # A class member to hold the editor export plugin during its lifecycle. + var export_plugin : AndroidExportPlugin + + func _enter_tree(): + # Initialization of the plugin goes here. + export_plugin = AndroidExportPlugin.new() + add_export_plugin(export_plugin) - func _exit_tree(): - # Clean-up of the plugin goes here. - remove_export_plugin(export_plugin) - export_plugin = null + func _exit_tree(): + # Clean-up of the plugin goes here. + remove_export_plugin(export_plugin) + export_plugin = null - class AndroidExportPlugin extends EditorExportPlugin: - # Plugin's name. - var _plugin_name = "" + class AndroidExportPlugin extends EditorExportPlugin: + # Plugin's name. + var _plugin_name = "" - # Specifies which platform is supported by the plugin. - func _supports_platform(platform): - if platform is EditorExportPlatformAndroid: - return true - return false + # Specifies which platform is supported by the plugin. + func _supports_platform(platform): + if platform is EditorExportPlatformAndroid: + return true + return false - # Return the paths of the plugin's AAR binaries relative to the 'addons' directory. - func _get_android_libraries(platform, debug): - if debug: - return PackedStringArray([""]) - else: - return PackedStringArray([""]) + # Return the paths of the plugin's AAR binaries relative to the 'addons' directory. + func _get_android_libraries(platform, debug): + if debug: + return PackedStringArray([""]) + else: + return PackedStringArray([""]) - # Return the plugin's name. - func _get_name(): - return _plugin_name + # Return the plugin's name. + func _get_name(): + return _plugin_name - Here are the set of `EditorExportPlugin APIs `_ most relevant to use in this tool script: @@ -206,7 +210,9 @@ As mentioned, a v2 Android plugin is now provided to the Godot Editor as an ``Ed to the app's manifest which are preserved when the Godot Editor is updated, resolving a long standing issue with v1 Android plugins. -3. Create a ``plugin.cfg``. This is an INI file with metadata about your plugin:: +3. Create a ``plugin.cfg``. This is an INI file with metadata about your plugin: + +:: [plugin] @@ -248,7 +254,9 @@ At build time, the contents of the ``export_scripts_template`` directory as well +--plugin.gdextension # GDExtension config file -Here is what the ``plugin.gdextension`` config file should look like:: +Here is what the ``plugin.gdextension`` config file should look like: + +:: [configuration] @@ -298,7 +306,9 @@ Using a v2 Android plugin 7. In the ``Android export preset``, scroll to ``Gradle Build`` and set ``Use Gradle Build`` to ``true`` -8. Update the project's scripts as needed to access the plugin's functionality. For example:: +8. Update the project's scripts as needed to access the plugin's functionality. For example: + +:: if Engine.has_singleton("MyPlugin"): var singleton = Engine.get_singleton("MyPlugin") @@ -332,7 +342,9 @@ Simplify access to the exposed Java / Kotlin APIs To make it easier to access the exposed Java / Kotlin APIs in the Godot Editor, it's recommended to provide one (or multiple) gdscript wrapper class(es) for your plugin users to interface with. -For example:: +For example: + +:: class_name PluginInterface extends Object diff --git a/tutorials/platform/ios/ios_plugin.rst b/tutorials/platform/ios/ios_plugin.rst index efc0ce876..8bf3cdc1c 100644 --- a/tutorials/platform/ios/ios_plugin.rst +++ b/tutorials/platform/ios/ios_plugin.rst @@ -80,7 +80,9 @@ To build an iOS plugin: - The configuration file extension must be ``gdip`` (e.g.: ``MyPlugin.gdip``). - - The configuration file format is as follow:: + - The configuration file format is as follow: + + :: [config] name="MyPlugin" diff --git a/tutorials/scripting/evaluating_expressions.rst b/tutorials/scripting/evaluating_expressions.rst index 288905c3d..bc8cc1f02 100644 --- a/tutorials/scripting/evaluating_expressions.rst +++ b/tutorials/scripting/evaluating_expressions.rst @@ -83,7 +83,9 @@ Passing variables to an expression You can pass variables to an expression. These variables will then become available in the expression's "context" and will be substituted when used -in the expression:: +in the expression: + +:: var expression = Expression.new() # Define the variable names first in the second parameter of `parse()`. @@ -105,7 +107,9 @@ expression has no base instance associated to it. When calling :ref:`Expression.execute() `, you can set the value of the ``base_instance`` parameter to a specific object -instance such as ``self``, another script instance or even a singleton:: +instance such as ``self``, another script instance or even a singleton: + +:: func double(number): return number * 2 @@ -141,7 +145,9 @@ Associating a base instance allows doing the following: Example script -------------- -The script below demonstrates what the Expression class is capable of:: +The script below demonstrates what the Expression class is capable of: + +:: const DAYS_IN_YEAR = 365 var script_member_variable = 1000 @@ -191,7 +197,9 @@ The script below demonstrates what the Expression class is capable of:: # The method's return value is also the expression's return value. return 0 -The output from the script will be:: +The output from the script will be: + +:: false true diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index 13d6d4586..b34aef579 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -372,7 +372,9 @@ There are also two constructs that look like literals, but actually are not: +---------------------------------+-------------------------------------------+ Integers and floats can have their numbers separated with ``_`` to make them more readable. -The following ways to write numbers are all valid:: +The following ways to write numbers are all valid: + +:: 12_345_678 # Equal to 12345678. 3.141_592_7 # Equal to 3.1415927. @@ -455,7 +457,9 @@ Every annotation starts with the ``@`` character and is specified by a name. A detailed description and example for each annotation can be found inside the :ref:`GDScript class reference `. -For instance, you can use it to export a value to the editor:: +For instance, you can use it to export a value to the editor: + +:: @export_range(1, 100, 1, "or_greater") var ranged_var: int = 50 @@ -463,7 +467,9 @@ For instance, you can use it to export a value to the editor:: For more information about exporting properties, read the :ref:`GDScript exports ` article. -Any constant expression compatible with the required argument type can be passed as an annotation argument value:: +Any constant expression compatible with the required argument type can be passed as an annotation argument value: + +:: const MAX_SPEED = 120.0 @@ -474,7 +480,9 @@ Annotations can be specified one per line or all in the same line. They affect the next statement that isn't an annotation. Annotations can have arguments sent between parentheses and separated by commas. -Both of these are the same:: +Both of these are the same: + +:: @annotation_a @annotation_b @@ -503,7 +511,9 @@ be obtained when a call to ``Node._ready()`` is made. This can get a little cumbersome, especially when nodes and external references pile up. For this, GDScript has the ``@onready`` annotation, that defers initialization of a member variable until ``_ready()`` is called. It -can replace the above code with a single line:: +can replace the above code with a single line: + +:: @onready var my_label = get_node("MyLabel") @@ -512,7 +522,9 @@ can replace the above code with a single line:: Applying ``@onready`` and any ``@export`` annotation to the same variable doesn't work as you might expect. The ``@onready`` annotation will cause the default value to be set after the ``@export`` takes effect and will - override it:: + override it: + + :: @export var a = "init_value_a" @onready @export var b = "init_value_b" @@ -958,7 +970,9 @@ identifier), and must be string literals. } To add a key to an existing dictionary, access it like an existing key and -assign to it:: +assign to it: + +:: var d = {} # Create an empty Dictionary. d.waiting = 14 # Add String "waiting" as a key and assign the value 14 to it. @@ -1053,7 +1067,9 @@ after the variable name, followed by the type. var my_node: Node = Sprite2D.new() If the variable is initialized within the declaration, the type can be inferred, so -it's possible to omit the type name:: +it's possible to omit the type name: + +:: var my_vector2 := Vector2() # 'my_vector2' is of type 'Vector2'. var my_node := Sprite2D.new() # 'my_node' is of type 'Sprite2D'. @@ -1103,7 +1119,9 @@ Member variables are initialized in the following order: You can specify a complex expression as a variable initializer, including function calls. Make sure the variables are initialized in the correct order, otherwise your values - may be overwritten. For example:: + may be overwritten. For example: + + :: var a: int = proxy("a", 1) var b: int = proxy("b", 2) @@ -1117,7 +1135,9 @@ Member variables are initialized in the following order: func _init() -> void: print(_data) - Will print:: + Will print: + + :: { "a": 1 } { "a": 1, "b": 2 } @@ -1129,7 +1149,9 @@ Member variables are initialized in the following order: Static variables ~~~~~~~~~~~~~~~~ -A class member variable can be declared static:: +A class member variable can be declared static: + +:: static var a @@ -1183,7 +1205,9 @@ and every instance have the same ``max_id`` value, because the variable is stati print(person1.max_id) # 2 print(person2.max_id) # 2 -Static variables can have type hints, setters and getters:: +Static variables can have type hints, setters and getters: + +:: static var balance: int = 0 @@ -1193,7 +1217,9 @@ Static variables can have type hints, setters and getters:: set(value): balance = -value -A base class static variable can also be accessed via a child class:: +A base class static variable can also be accessed via a child class: + +:: class A: static var x = 1 @@ -1262,7 +1288,9 @@ engine will raise an error. my_int = Vector2() as int # A Vector2 can't be converted to int, this will cause an error. Casting is also useful to have better type-safe variables when interacting with -the scene tree:: +the scene tree: + +:: # Will infer the variable to be of type Sprite2D. var my_sprite := $Character as Sprite2D @@ -1292,7 +1320,9 @@ We recommend using constants whenever a value is not meant to change. const H = A + 20 # Constant expression: 25 (`A` is a constant). Although the type of constants is inferred from the assigned value, it's also -possible to add explicit type specification:: +possible to add explicit type specification: + +:: const A: int = 5 const B: Vector2 = Vector2() @@ -1368,7 +1398,9 @@ function's first argument, unlike Python). A function can ``return`` at any point. The default return value is ``null``. -If a function contains only one line of code, it can be written on one line:: +If a function contains only one line of code, it can be written on one line: + +:: func square(a): return a * a @@ -1377,12 +1409,16 @@ If a function contains only one line of code, it can be written on one line:: func empty_function(): pass Functions can also have type specification for the arguments and for the return -value. Types for arguments can be added in a similar way to variables:: +value. Types for arguments can be added in a similar way to variables: + +:: func my_function(a: int, b: String): pass -If a function argument has a default value, it's possible to infer the type:: +If a function argument has a default value, it's possible to infer the type: + +:: func my_function(int_arg := 42, String_arg := "string"): pass @@ -1459,7 +1495,9 @@ Lambda functions can be named for debugging purposes (the name is displayed in t var lambda = func my_lambda(x): print(x) -You can specify type hints for lambda functions in the same way as for regular ones:: +You can specify type hints for lambda functions in the same way as for regular ones: + +:: var lambda := func (x: int) -> void: print(x) @@ -1470,7 +1508,9 @@ is required (you can't omit ``return``):: var lambda = func (x): return x ** 2 print(lambda.call(2)) # Prints `4`. -Lambda functions capture the local environment:: +Lambda functions capture the local environment: + +:: var x = 42 var lambda = func (): @@ -1480,7 +1520,9 @@ Lambda functions capture the local environment:: .. warning:: Local variables are captured by value once, when the lambda is created. - So they won't be updated in the lambda if reassigned in the outer function:: + So they won't be updated in the lambda if reassigned in the outer function: + + :: var x = 42 var lambda = func (): print(x) @@ -1489,7 +1531,9 @@ Lambda functions capture the local environment:: lambda.call() # Prints `42`. Also, a lambda cannot reassign an outer local variable. After exiting the lambda, - the variable will be unchanged, because the lambda capture implicitly shadows it:: + the variable will be unchanged, because the lambda capture implicitly shadows it: + + :: var x = 42 var lambda = func (): @@ -1500,7 +1544,9 @@ Lambda functions capture the local environment:: print(x) # Prints `42`. However, if you use pass-by-reference data types (arrays, dictionaries, and objects), - then the content changes are shared until you reassign the variable:: + then the content changes are shared until you reassign the variable: + + :: var a = [] var lambda = func (): @@ -1515,7 +1561,9 @@ Static functions ~~~~~~~~~~~~~~~~ A function can be declared static. When a function is static, it has no access to the instance member variables or ``self``. -A static function has access to static variables. Also static functions are useful to make libraries of helper functions:: +A static function has access to static variables. Also static functions are useful to make libraries of helper functions: + +:: static func sum2(a, b): return a + b @@ -1540,7 +1588,9 @@ statement too, though only calls are reasonable to use as statements since other Expressions return values that can be assigned to valid targets. Operands to some operator can be another expression. An assignment is not an expression and thus does not return any value. -Here are some examples of expressions:: +Here are some examples of expressions: + +:: 2 + 2 # Binary operation. -5 # Unary operation. @@ -1609,7 +1659,9 @@ nature of the tab-based indentation, ``elif`` can be used instead of else: statement(s) -Short statements can be written on the same line as the condition:: +Short statements can be written on the same line as the condition: + +:: if 1 + 1 == 2: return 2 + 2 else: @@ -1617,14 +1669,18 @@ Short statements can be written on the same line as the condition:: return x Sometimes, you might want to assign a different initial value based on a -boolean expression. In this case, ternary-if expressions come in handy:: +boolean expression. In this case, ternary-if expressions come in handy: + +:: var x = (value) if (expression) else (value) y += 3 if y < 10 else -1 Ternary-if expressions can be nested to handle more than 2 cases. When nesting ternary-if expressions, it is recommended to wrap the complete expression over -multiple lines to preserve readability:: +multiple lines to preserve readability: + +:: var count = 0 @@ -1646,7 +1702,9 @@ multiple lines to preserve readability:: print(fruit_alt) # banana You may also wish to check if a value is contained within something. You can -use an ``if`` statement combined with the ``in`` operator to accomplish this:: +use an ``if`` statement combined with the ``in`` operator to accomplish this: + +:: # Check if a letter is in a string. var text = "abc" @@ -1798,7 +1856,9 @@ The following pattern types are available: - Wildcard pattern This pattern matches everything. It's written as a single underscore. - It can be used as the equivalent of the ``default`` in a ``switch`` statement in other languages:: + It can be used as the equivalent of the ``default`` in a ``switch`` statement in other languages: + + :: match x: 1: @@ -1810,7 +1870,9 @@ The following pattern types are available: - Binding pattern A binding pattern introduces a new variable. Like the wildcard pattern, it matches everything - and also gives that value a name. - It's especially useful in array and dictionary patterns:: + It's especially useful in array and dictionary patterns: + + :: match x: 1: @@ -1935,7 +1997,9 @@ Registering named classes You can give your class a name to register it as a new type in Godot's editor. For that, you use the ``class_name`` keyword. You can optionally use the ``@icon`` annotation with a path to an image, to use it as an icon. Your -class will then appear with its new icon in the editor:: +class will then appear with its new icon in the editor: + +:: # item.gd @@ -1974,7 +2038,9 @@ Here's a class file example: print(ResourceLoader.load("res://character.gd")) print(Character) -If you want to use ``extends`` too, you can keep both on the same line:: +If you want to use ``extends`` too, you can keep both on the same line: + +:: class_name MyNode extends Node @@ -2094,7 +2160,9 @@ Inheritance uses the ``extends`` keyword:: :ref:`class_RefCounted`. To check if a given instance inherits from a given class, -the ``is`` keyword can be used:: +the ``is`` keyword can be used: + +:: # Cache the enemy class. const Enemy = preload("enemy.gd") @@ -2118,7 +2186,9 @@ call them, you can use ``super``:: super(x) # Calls the same function on the super class. If you need to call a different function from the super class, you can specify -the function name with the attribute operator:: +the function name with the attribute operator: + +:: func overriding(): return 0 # This overrides the method in the base class. @@ -2150,12 +2220,16 @@ The class constructor, called on class instantiation, is named ``_init``. If you want to call the base class constructor, you can also use the ``super`` syntax. Note that every class has an implicit constructor that is always called (defining the default values of class variables). ``super`` is used to call the -explicit constructor:: +explicit constructor: + +:: func _init(arg): super("some_default", arg) # Call the custom base constructor. -This is better explained through examples. Consider this scenario:: +This is better explained through examples. Consider this scenario: + +:: # state.gd (inherited class). var entity = null @@ -2200,7 +2274,9 @@ Static constructor ~~~~~~~~~~~~~~~~~~ A static constructor is a static function ``_static_init`` that is called automatically -when the class is loaded, after the static variables have been initialized:: +when the class is loaded, after the static variables have been initialized: + +:: static var my_static_var = 1 @@ -2244,7 +2320,9 @@ Classes as resources Classes stored as files are treated as :ref:`GDScripts `. They must be loaded from disk to access them in other classes. This is done using either the ``load`` or ``preload`` functions (see below). Instancing of a loaded -class resource is done by calling the ``new`` function on the class object:: +class resource is done by calling the ``new`` function on the class object: + +:: # Load the class resource when calling load(). var MyClass = load("myclass.gd") @@ -2303,7 +2381,9 @@ or you need to reuse the code across multiple properties (but you can't distingu var my_prop: get = get_my_prop, set = set_my_prop -This can also be done in the same line:: +This can also be done in the same line: + +:: var my_prop: get = get_my_prop, set = set_my_prop @@ -2322,7 +2402,9 @@ When a variable is initialized, the value of the initializer will be written dir Including if the ``@onready`` annotation is applied to the variable. Using the variable's name to set it inside its own setter or to get it inside its own getter will directly access the underlying member, -so it won't generate infinite recursion and saves you from explicitly declaring another variable:: +so it won't generate infinite recursion and saves you from explicitly declaring another variable: + +:: signal changed(new_value) var warns_when_changed = "some value": @@ -2332,7 +2414,9 @@ so it won't generate infinite recursion and saves you from explicitly declaring changed.emit(value) warns_when_changed = value -This also applies to the alternative syntax:: +This also applies to the alternative syntax: + +:: var my_prop: set = set_my_prop @@ -2342,7 +2426,9 @@ This also applies to the alternative syntax:: .. warning:: The exception does **not** propagate to other functions called in the setter/getter. - For example, the following code **will** cause an infinite recursion:: + For example, the following code **will** cause an infinite recursion: + +:: var my_prop: set(value): @@ -2360,7 +2446,9 @@ By default, scripts don't run inside the editor and only the exported properties can be changed. In some cases, it is desired that they do run inside the editor (as long as they don't execute game code or manually avoid doing so). For this, the ``@tool`` annotation exists and must be -placed at the top of the file:: +placed at the top of the file: + +:: @tool extends Button @@ -2454,7 +2542,9 @@ signals of nodes like :ref:`class_Button` or :ref:`class_RigidBody3D`. In the example below, we connect the ``health_depleted`` signal from a ``Character`` node to a ``Game`` node. When the ``Character`` node emits the -signal, the game node's ``_on_character_health_depleted`` is called:: +signal, the game node's ``_on_character_health_depleted`` is called: + +:: # game.gd @@ -2552,7 +2642,9 @@ Building on the example above, let's say we want to display a log of the damage taken by each character on the screen, like ``Player1 took 22 damage.``. The ``health_changed`` signal doesn't give us the name of the character that took damage. So when we connect the signal to the in-game console, we can add the -character's name using the bind method:: +character's name using the bind method: + +:: # game.gd @@ -2562,7 +2654,9 @@ character's name using the bind method:: character_node.health_changed.connect(battle_log_node._on_Character_health_changed.bind(character_node.name)) -Our ``BattleLog`` node receives each bound element as an extra argument:: +Our ``BattleLog`` node receives each bound element as an extra argument: + +:: # battle_log.gd @@ -2582,7 +2676,9 @@ which wait until a signal is emitted before continuing execution. Using the ``aw call to a function that is also a coroutine will immediately return the control to the caller. When the signal is emitted (or the called coroutine finishes), it will resume execution from the point on where it stopped. -For example, to stop execution until the user presses a button, you can do something like this:: +For example, to stop execution until the user presses a button, you can do something like this: + +:: func wait_confirmation(): print("Prompting user") @@ -2590,7 +2686,9 @@ For example, to stop execution until the user presses a button, you can do somet print("User confirmed") return true -In this case, the ``wait_confirmation`` becomes a coroutine, which means that the caller also needs to await it:: +In this case, the ``wait_confirmation`` becomes a coroutine, which means that the caller also needs to await it: + +:: func request_confirmation(): print("Will ask the user") @@ -2600,20 +2698,26 @@ In this case, the ``wait_confirmation`` becomes a coroutine, which means that th else: print("User cancelled") -Note that requesting a coroutine's return value without ``await`` will trigger an error:: +Note that requesting a coroutine's return value without ``await`` will trigger an error: + +:: func wrong(): var confirmed = wait_confirmation() # Will give an error. However, if you don't depend on the result, you can just call it asynchronously, which won't stop execution and won't -make the current function a coroutine:: +make the current function a coroutine: + +:: func okay(): wait_confirmation() print("This will be printed immediately, before the user press the button.") If you use await with an expression that isn't a signal nor a coroutine, the value will be returned immediately and the -function won't give the control back to the caller:: +function won't give the control back to the caller: + +:: func no_wait(): var x = await get_five() @@ -2622,7 +2726,9 @@ function won't give the control back to the caller:: func get_five(): return 5 -This also means that returning a signal from a function that isn't a coroutine will make the caller await that signal:: +This also means that returning a signal from a function that isn't a coroutine will make the caller await that signal: + +:: func get_signal(): return $Button.button_up diff --git a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst index 731e3d4b3..2c7902b40 100644 --- a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst +++ b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst @@ -45,7 +45,9 @@ Tags | | | ``@experimental: This class is unstable.`` | +-------------------+--------------------------------------------------------+ -For example:: +For example: + +:: extends Node2D ## A brief description of the class's role and functionality. @@ -98,13 +100,17 @@ Tags | | | ``@experimental: This method is incomplete.`` | +--------------+--------------------------------------------------+ -For example:: +For example: + +:: ## The description of the variable. ## @deprecated: Use [member other_var] instead. var my_var -Alternatively, you can use inline documentation comments:: +Alternatively, you can use inline documentation comments: + +:: signal my_signal ## My signal. diff --git a/tutorials/scripting/gdscript/gdscript_exports.rst b/tutorials/scripting/gdscript/gdscript_exports.rst index 85428b74d..4a4bb09af 100644 --- a/tutorials/scripting/gdscript/gdscript_exports.rst +++ b/tutorials/scripting/gdscript/gdscript_exports.rst @@ -310,7 +310,9 @@ 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:: +can be set from the editor: + +:: # Set any of the given flags from the editor. @export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0 @@ -320,18 +322,24 @@ has value 1, ``Water`` has value 2, ``Earth`` has value 4 and ``Wind`` corresponds to value 8. Usually, constants should be defined accordingly (e.g. ``const ELEMENT_WIND = 8`` and so on). -You can add explicit values using a colon:: +You can add explicit values using a colon: + +:: @export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0 Only power of 2 values are valid as bit flags options. The lowest allowed value is 1, as 0 means that nothing is selected. You can also add options that are a -combination of other flags:: +combination of other flags: + +:: @export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16") var spell_targets = 0 -Export annotations are also provided for the physics, render, and navigation layers defined in the project settings:: +Export annotations are also provided for the physics, render, and navigation layers defined in the project settings: + +:: @export_flags_2d_physics var layers_2d_physics @export_flags_2d_render var layers_2d_render @@ -367,7 +375,9 @@ of the selected option (i.e. ``0``, ``1``, or ``2``). @export_enum("Warrior", "Magician", "Thief") var character_class: int -You can add explicit values using a colon:: +You can add explicit values using a colon: + +:: @export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int @@ -377,7 +387,9 @@ If the type is String, the value will be stored as a string. @export_enum("Rebecca", "Mary", "Leah") var character_name: String -If you want to set an initial value, you must specify it explicitly:: +If you want to set an initial value, you must specify it explicitly: + +:: @export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca" diff --git a/tutorials/scripting/gdscript/static_typing.rst b/tutorials/scripting/gdscript/static_typing.rst index 931aeacce..1dad8e2eb 100644 --- a/tutorials/scripting/gdscript/static_typing.rst +++ b/tutorials/scripting/gdscript/static_typing.rst @@ -27,7 +27,9 @@ of your scripts. Imagine you're programming an inventory system. You code an ``Item`` class, then an ``Inventory``. To add items to the inventory, the people who work with your code should always pass an ``Item`` to the ``Inventory.add()`` method. -With types, you can enforce this:: +With types, you can enforce this: + +:: class_name Inventory @@ -78,14 +80,18 @@ How to use static typing To define the type of a variable, parameter, or constant, write a colon after the name, followed by its type. E.g. ``var health: int``. This forces the variable's type -to always stay the same:: +to always stay the same: + +:: var damage: float = 10.5 const MOVE_SPEED: float = 50.0 func sum(a: float = 0.0, b: float = 0.0) -> float: return a + b -Godot will try to infer types if you write a colon, but you omit the type:: +Godot will try to infer types if you write a colon, but you omit the type: + +:: var damage := 10.5 const MOVE_SPEED := 50.0 @@ -119,19 +125,25 @@ Here is a complete list of what can be used as a type hint: You can use any class, including your custom classes, as types. There are two ways to use them in scripts. The first method is to preload the script you want to use -as a type in a constant:: +as a type in a constant: + +:: const Rifle = preload("res://player/weapons/rifle.gd") var my_rifle: Rifle The second method is to use the ``class_name`` keyword when you create. -For the example above, your ``rifle.gd`` would look like this:: +For the example above, your ``rifle.gd`` would look like this: + +:: class_name Rifle extends Node2D If you use ``class_name``, Godot registers the ``Rifle`` type globally in the editor, -and you can use it anywhere, without having to preload it into a constant:: +and you can use it anywhere, without having to preload it into a constant: + +:: var my_rifle: Rifle @@ -139,19 +151,25 @@ Specify the return type of a function with the arrow ``->`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To define the return type of a function, write a dash and a right angle bracket ``->`` -after its declaration, followed by the return type:: +after its declaration, followed by the return type: + +:: func _process(delta: float) -> void: pass The type ``void`` means the function does not return anything. You can use any type, -as with variables:: +as with variables: + +:: func hit(damage: float) -> bool: health_points -= damage return health_points <= 0 -You can also use your own classes as return types:: +You can also use your own classes as return types: + +:: # Adds an item to the inventory and returns it. func add(reference: Item, amount: int) -> Item: @@ -221,7 +239,9 @@ and enums may be used as element types. Nested array types scores[0] = "lots" Since Godot 4.2, you can also specify a type for the loop variable in a ``for`` loop. -For instance, you can write:: +For instance, you can write: + +:: var names = ["John", "Marta", "Samantha", "Jimmy"] for name: String in names: @@ -353,7 +373,9 @@ green at the left of the script editor. .. note:: Safe lines do not always mean better or more reliable code. See the note above - about the ``as`` keyword. For example:: + about the ``as`` keyword. For example: + + :: @onready var node_1 := $Node1 as Type1 # Safe line. @onready var node_2: Type2 = $Node2 # Unsafe line. @@ -377,7 +399,9 @@ and for your peers. It's easier for everyone to work together if you follow the same guidelines, and faster to read and understand other people's code. Typed code takes a little more writing, but you get the benefits we discussed -above. Here's an example of the same, empty script, in a dynamic style:: +above. Here's an example of the same, empty script, in a dynamic style: + +:: extends Node @@ -389,7 +413,9 @@ above. Here's an example of the same, empty script, in a dynamic style:: func _process(delta): pass -And with static typing:: +And with static typing: + +:: extends Node @@ -403,12 +429,16 @@ And with static typing:: As you can see, you can also use types with the engine's virtual methods. Signal callbacks, like any methods, can also use types. Here's a ``body_entered`` -signal in a dynamic style:: +signal in a dynamic style: + +:: func _on_area_2d_body_entered(body): pass -And the same callback, with type hints:: +And the same callback, with type hints: + +:: func _on_area_entered(area: CollisionObject2D) -> void: pass @@ -446,7 +476,9 @@ In this example, we aim to set a property and call a method on an object that has a script attached with ``class_name MyScript`` and that ``extends Node2D``. If we have a reference to the object as a ``Node2D`` (for instance, as it was passed to us by the physics system), we can first check if the -property and method exist and then set and call them if they do:: +property and method exist and then set and call them if they do: + +:: if "some_property" in node_2d: node_2d.some_property = 20 # Produces UNSAFE_PROPERTY_ACCESS warning. @@ -459,7 +491,9 @@ However, this code will produce ``UNSAFE_PROPERTY_ACCESS`` and in the referenced type - in this case a ``Node2D``. To make these operations safe, you can first check if the object is of type ``MyScript`` using the ``is`` keyword and then declare a variable with the type ``MyScript`` on -which you can set its properties and call its methods:: +which you can set its properties and call its methods: + +:: if node_2d is MyScript: var my_script: MyScript = node_2d @@ -468,7 +502,9 @@ which you can set its properties and call its methods:: Alternatively, you can declare a variable and use the ``as`` operator to try to cast the object. You'll then want to check whether the cast was successful -by confirming that the variable was assigned:: +by confirming that the variable was assigned: + +:: var my_script := node_2d as MyScript if my_script != null: @@ -482,7 +518,9 @@ In this example, we would like the label connected to an object entering our collision area to show the area's name. Once the object enters the collision area, the physics system sends a signal with a ``Node2D`` object, and the most straightforward (but not statically typed) solution to do what we want could -be achieved like this:: +be achieved like this: + +:: func _on_body_entered(body: Node2D) -> void: body.label.text = name # Produces UNSAFE_PROPERTY_ACCESS warning. @@ -490,7 +528,9 @@ be achieved like this:: This piece of code produces an ``UNSAFE_PROPERTY_ACCESS`` warning because ``label`` is not defined in ``Node2D``. To solve this, we could first check if the ``label`` property exist and cast it to type ``Label`` before settings its text -property like so:: +property like so: + +:: func _on_body_entered(body: Node2D) -> void: if "label" in body: @@ -501,7 +541,9 @@ However, this produces an ``UNSAFE_CAST`` warning because ``body.label`` is of a ``Object.get()`` method which returns the object as a ``Variant`` value or returns ``null`` if the property doesn't exist. You can then determine whether the property contains an object of the right type using the ``is`` keyword, and -finally declare a statically typed variable with the object:: +finally declare a statically typed variable with the object: + +:: func _on_body_entered(body: Node2D) -> void: var label_variant: Variant = body.get("label") @@ -517,7 +559,9 @@ Cases where you can't specify types To wrap up this introduction, let's mention cases where you can't use type hints. This will trigger a **syntax error**. -1. You can't specify the type of individual elements in an array or a dictionary:: +1. You can't specify the type of individual elements in an array or a dictionary: + +:: var enemies: Array = [$Goblin: Enemy, $Zombie: Enemy] var character: Dictionary = { @@ -526,7 +570,9 @@ This will trigger a **syntax error**. inventory: Inventory = $Inventory, } -2. Nested types are not currently supported:: +2. Nested types are not currently supported: + +:: var teams: Array[Array[Character]] = [] diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index f3f2d11f5..6c272569b 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -1346,7 +1346,9 @@ Exponential and math function descriptions Performs smooth Hermite interpolation between ``0`` and ``1`` when a < c < b. This is useful in cases where a threshold function with a smooth transition is desired. - Smoothstep is equivalent to:: + Smoothstep is equivalent to: + + :: vec_type t; t = clamp((c - a) / (b - a), 0.0, 1.0); @@ -1751,7 +1753,9 @@ vec3 **refract**\ (\ vec3 I, vec3 N, float eta) :ref:`🔗` For a given incident vector ``I``, surface normal ``N`` and ratio of indices of refraction, ``eta``, refract returns the refraction vector, ``R``. - ``R`` is calculated as:: + ``R`` is calculated as: + + :: k = 1.0 - eta * eta * (1.0 - dot(N, I) * dot(N, I)); if (k < 0.0) @@ -2143,7 +2147,9 @@ bool **any**\ (\ |vec_bool_type| x) :ref:`🔗` Returns ``true`` if any element of a boolean vector is ``true``, ``false`` otherwise. - Functionally equivalent to:: + Functionally equivalent to: + + :: bool any(bvec x) { // bvec can be bvec2, bvec3 or bvec4 bool result = false; @@ -2177,7 +2183,9 @@ bool **all**\ (\ |vec_bool_type| x) :ref:`🔗` Returns ``true`` if all elements of a boolean vector are ``true``, ``false`` otherwise. - Functionally equivalent to:: + Functionally equivalent to: + + :: bool all(bvec x) // bvec can be bvec2, bvec3 or bvec4 { @@ -2594,7 +2602,9 @@ vec4 **textureLod**\ (\ samplerCubeArray s, vec4 p, float lod) :ref:`🔗` Converts each component of the normalized floating-point value v into 16-bit integer values and then packs the results into a 32-bit unsigned integer. - The conversion for component c of ``v`` to fixed-point is performed as follows:: + The conversion for component c of ``v`` to fixed-point is performed as follows: + + :: round(clamp(c, 0.0, 1.0) * 65535.0) @@ -3319,7 +3333,9 @@ uint **packSnorm2x16**\ (\ vec2 v) :ref:`🔗` Convert each component of the normalized floating-point value ``v`` into 16-bit integer values and then packs the results into a 32-bit unsigned integer. - The conversion for component c of ``v`` to fixed-point is performed as follows:: + The conversion for component c of ``v`` to fixed-point is performed as follows: + + :: round(clamp(c, -1.0, 1.0) * 32767.0) @@ -3379,7 +3395,9 @@ uint **packUnorm4x8**\ (\ vec4 v) :ref:`🔗` Converts each component of the normalized floating-point value ``v`` into 16-bit integer values and then packs the results into a 32-bit unsigned integer. - The conversion for component c of ``v`` to fixed-point is performed as follows:: + The conversion for component c of ``v`` to fixed-point is performed as follows: + + :: round(clamp(c, 0.0, 1.0) * 255.0) @@ -3440,7 +3458,9 @@ uint **packSnorm4x8**\ (\ vec4 v) :ref:`🔗` Convert each component of the normalized floating-point value ``v`` into 16-bit integer values and then packs the results into a 32-bit unsigned integer. - The conversion for component c of ``v`` to fixed-point is performed as follows:: + The conversion for component c of ``v`` to fixed-point is performed as follows: + + :: round(clamp(c, -1.0, 1.0) * 127.0) @@ -3954,7 +3974,9 @@ Bitwise function descriptions |componentwise| - Extracts ``x`` into a floating-point significand in the range ``[0.5, 1.0)`` and in integral exponent of two, such that:: + Extracts ``x`` into a floating-point significand in the range ``[0.5, 1.0)`` and in integral exponent of two, such that: + + :: x = significand * 2 ^ exponent diff --git a/tutorials/ui/bbcode_in_richtextlabel.rst b/tutorials/ui/bbcode_in_richtextlabel.rst index d7055dda5..164ffe99e 100644 --- a/tutorials/ui/bbcode_in_richtextlabel.rst +++ b/tutorials/ui/bbcode_in_richtextlabel.rst @@ -581,7 +581,9 @@ To handle clicked ``[url]`` tags, connect the ``RichTextLabel`` node's :ref:`meta_clicked ` signal to a script function. For example, the following method can be connected to ``meta_clicked`` to open -clicked URLs using the user's default web browser:: +clicked URLs using the user's default web browser: + +:: # This assumes RichTextLabel's `meta_clicked` signal was connected to # the function below using the signal connection dialog.