diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e7413f86dbd..c71aee1916d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -19,6 +19,10 @@ jobs: - name: Style checks via pre-commit uses: pre-commit/action@v3.0.1 + - name: Custom RST checks (check-rst.sh) + run: | + bash ./_tools/check-rst.sh + - name: Get Python version id: pythonv run: | diff --git a/_tools/check-rst.sh b/_tools/check-rst.sh new file mode 100755 index 00000000000..3abb28cbc2a --- /dev/null +++ b/_tools/check-rst.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash + +set -uo pipefail + +output=$(grep -r -P '^(?!\s*\.\.).*\S::$' --include='*.rst' --exclude='docs_writing_guidelines.rst' .) +if [[ -n $output ]]; then + echo 'The shorthand codeblock syntax (trailing `::`) is not allowed.' + echo "$output" + exit 1 +fi diff --git a/contributing/development/code_style_guidelines.rst b/contributing/development/code_style_guidelines.rst index da7611e46b9..d9cedc62a7d 100644 --- a/contributing/development/code_style_guidelines.rst +++ b/contributing/development/code_style_guidelines.rst @@ -73,8 +73,8 @@ To set up: :: - pip install pre-commit - pre-commit install + pip install pre-commit + pre-commit install You can also run the hook manually with ``pre-commit run``. diff --git a/contributing/development/compiling/compiling_for_linuxbsd.rst b/contributing/development/compiling/compiling_for_linuxbsd.rst index e618196b6ee..fd6df4bd08b 100644 --- a/contributing/development/compiling/compiling_for_linuxbsd.rst +++ b/contributing/development/compiling/compiling_for_linuxbsd.rst @@ -314,12 +314,15 @@ And then use the ``--headless`` command line argument: ./bin/godot.linuxbsd.editor.x86_64 --headless To compile a debug *server* build which can be used with -:ref:`remote debugging tools `, use:: +:ref:`remote debugging tools `, use: + +:: scons platform=linuxbsd target=template_debug -To compile a *server* build which is optimized to run dedicated game servers, -use:: +To compile a *server* build which is optimized to run dedicated game servers, use: + +:: scons platform=linuxbsd target=template_release production=yes @@ -363,7 +366,7 @@ must be copied to: and named like this (even for \*BSD which is seen as "Linux/X11" by Godot): -:: +.. code:: text linux_debug.arm32 linux_debug.arm64 @@ -449,7 +452,7 @@ indicates to Clang the target architecture, and OS we want to build for. If all went well, you should now see a ``bin`` directory, and within it, a binary similar to the following: -:: +.. code:: text godot.linuxbsd.editor.rv64.llvm @@ -486,7 +489,7 @@ link-time optimization, making the resulting binaries smaller and faster. If this error occurs: -:: +.. code:: text /usr/bin/ld: cannot find -l:libatomic.a: No such file or directory @@ -517,7 +520,9 @@ repositories, so you will have to install its binaries manually. PATH="$HOME/.local/share/mold/bin:$PATH" - Open a new terminal (or run ``source "$HOME/.bash_profile"``), - then use the following SCons command when compiling Godot:: + then use the following SCons command when compiling Godot: + + :: scons platform=linuxbsd linker=mold diff --git a/contributing/development/compiling/compiling_for_macos.rst b/contributing/development/compiling/compiling_for_macos.rst index 488e0c83877..8b9f247eef5 100644 --- a/contributing/development/compiling/compiling_for_macos.rst +++ b/contributing/development/compiling/compiling_for_macos.rst @@ -53,11 +53,15 @@ Compiling Start a terminal, go to the root directory of the engine source code. -To compile for Intel (x86-64) powered Macs, use:: +To compile for Intel (x86-64) powered Macs, use: + +:: scons platform=macos arch=x86_64 -To compile for Apple Silicon (ARM64) powered Macs, use:: +To compile for Apple Silicon (ARM64) powered Macs, use: + +:: scons platform=macos arch=arm64 @@ -102,7 +106,9 @@ 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``:: +editor binary built with ``dev_build=yes``: + +:: cp -r misc/dist/macos_tools.app ./bin/Godot.app mkdir -p bin/Godot.app/Contents/MacOS @@ -116,7 +122,9 @@ editor binary built with ``dev_build=yes``:: for the MoltenVK Vulkan portability library. By default, it will be linked statically from your installation of the Vulkan SDK for macOS. You can also choose to link it dynamically by passing ``use_volk=yes`` and - including the dynamic library in your ``.app`` bundle:: + including the dynamic library in your ``.app`` bundle: + + :: mkdir -p .app/Contents/Frameworks cp /macOS/lib/libMoltenVK.dylib .app/Contents/Frameworks/libMoltenVK.dylib @@ -138,12 +146,15 @@ And then use the ``--headless`` command line argument: ./bin/godot.macos.editor.x86_64 --headless To compile a debug *server* build which can be used with -:ref:`remote debugging tools `, use:: +:ref:`remote debugging tools `, use: + +:: scons platform=macos target=template_debug -To compile a release *server* build which is optimized to run dedicated game servers, -use:: +To compile a release *server* build which is optimized to run dedicated game servers, use: + +:: scons platform=macos target=template_release production=yes @@ -157,17 +168,21 @@ the editor: ``target=template_release`` (release template) and Official templates are *Universal 2* binaries which support both ARM64 and Intel x86_64 architectures. -- To support ARM64 (Apple Silicon) + Intel x86_64:: +- To support ARM64 (Apple Silicon) + Intel x86_64: - scons platform=macos target=template_debug arch=arm64 - scons platform=macos target=template_release arch=arm64 - scons platform=macos target=template_debug arch=x86_64 - scons platform=macos target=template_release arch=x86_64 generate_bundle=yes + :: -- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware):: + scons platform=macos target=template_debug arch=arm64 + scons platform=macos target=template_release arch=arm64 + scons platform=macos target=template_debug arch=x86_64 + scons platform=macos target=template_release arch=x86_64 generate_bundle=yes - scons platform=macos target=template_debug arch=arm64 - scons platform=macos target=template_release arch=arm64 generate_bundle=yes +- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware): + + :: + + scons platform=macos target=template_debug arch=arm64 + scons platform=macos target=template_release arch=arm64 generate_bundle=yes To create an ``.app`` bundle like in the official builds, you need to use the template located in ``misc/dist/macos_template.app``. This process can be automated by using @@ -181,7 +196,9 @@ an *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both wer library. By default, it will be linked statically from your installation of the Vulkan SDK for macOS. You can also choose to link it dynamically by passing ``use_volk=yes`` and including the dynamic library in your ``.app`` - bundle:: + bundle: + + :: mkdir -p macos_template.app/Contents/Frameworks cp /macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib @@ -206,8 +223,9 @@ Windows using the Windows Subsystem for Linux). For that, you'll need to install as a target. First, follow the instructions to install it: Clone the `OSXCross repository `__ -somewhere on your machine (or download a ZIP file and extract it somewhere), -e.g.:: +somewhere on your machine (or download a ZIP file and extract it somewhere), e.g.: + +:: git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross" @@ -218,7 +236,9 @@ e.g.:: After that, you will need to define the ``OSXCROSS_ROOT`` as the path to the OSXCross installation (the same place where you cloned the -repository/extracted the zip), e.g.:: +repository/extracted the zip), e.g.: + +:: export OSXCROSS_ROOT="$HOME/osxcross" @@ -228,7 +248,9 @@ Now you can compile with SCons like you normally would: scons platform=macos -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:: +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 @@ -242,7 +264,7 @@ 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: -:: +.. code:: text ./core/typedefs.h:45:10: fatal error: 'cstdint' file not found 45 | #include diff --git a/contributing/development/compiling/compiling_for_windows.rst b/contributing/development/compiling/compiling_for_windows.rst index 9e595495f23..b560ea1af89 100644 --- a/contributing/development/compiling/compiling_for_windows.rst +++ b/contributing/development/compiling/compiling_for_windows.rst @@ -301,9 +301,11 @@ By default, Godot is built with dynamically linked ANGLE, you can use it by plac To compile Godot with statically linked ANGLE: - Download pre-built static libraries from `godot-angle-static library `_, and unzip them. -- When building Godot, add ``angle_libs={path}`` to tell SCons where to look for the ANGLE libraries:: +- When building Godot, add ``angle_libs={path}`` to tell SCons where to look for the ANGLE libraries: - scons platform=windows angle_libs=<...> + :: + + scons platform=windows angle_libs=<...> .. note:: You can optionally build the godot-angle-static libraries yourself with the following steps: @@ -414,7 +416,9 @@ Where ``/path/to/mingw`` is the path containing the ``bin`` directory where To make sure you are doing things correctly, executing the following in the shell should result in a working compiler (the version output may -differ based on your system):: +differ based on your system): + +:: ${MINGW_PREFIX}/bin/x86_64-w64-mingw32-gcc --version # x86_64-w64-mingw32-gcc (GCC) 13.2.0 @@ -432,15 +436,18 @@ Cross-compiling from some Ubuntu versions may lead to `this bug `_, due to a default configuration lacking support for POSIX threading. -You can change that configuration following those instructions, -for 64-bit:: +You can change that configuration following those instructions, for 64-bit: + +:: sudo update-alternatives --config x86_64-w64-mingw32-gcc sudo update-alternatives --config x86_64-w64-mingw32-g++ -And for 32-bit:: +And for 32-bit: + +:: sudo update-alternatives --config i686-w64-mingw32-gcc diff --git a/contributing/development/compiling/compiling_with_dotnet.rst b/contributing/development/compiling/compiling_with_dotnet.rst index 069d6f45554..045fc5103a4 100644 --- a/contributing/development/compiling/compiling_with_dotnet.rst +++ b/contributing/development/compiling/compiling_with_dotnet.rst @@ -64,7 +64,9 @@ Building the managed libraries ------------------------------ Once you have generated the .NET glue, you can build the managed libraries with -the ``build_assemblies.py`` script:: +the ``build_assemblies.py`` script: + +:: ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin diff --git a/contributing/development/compiling/getting_source.rst b/contributing/development/compiling/getting_source.rst index 030a9dbc7c7..7182407e4d3 100644 --- a/contributing/development/compiling/getting_source.rst +++ b/contributing/development/compiling/getting_source.rst @@ -40,7 +40,9 @@ and click on the link for the release you want. You can then download and extract the source from the download link on the page. With ``git``, you can also clone a stable release by specifying its branch or tag -after the ``--branch`` (or just ``-b``) argument:: +after the ``--branch`` (or just ``-b``) argument: + +:: # Clone the continuously maintained stable branch (`4.4` as of writing). git clone https://github.com/godotengine/godot.git -b 4.4 diff --git a/contributing/development/compiling/introduction_to_the_buildsystem.rst b/contributing/development/compiling/introduction_to_the_buildsystem.rst index f3edc60b2c8..311540d4769 100644 --- a/contributing/development/compiling/introduction_to_the_buildsystem.rst +++ b/contributing/development/compiling/introduction_to_the_buildsystem.rst @@ -52,7 +52,9 @@ SCons setup is configured to use all CPU threads but one (to keep the system res compilation). If you want to adjust how many CPU threads SCons will use, use the ``-j `` parameter to specify how many threads will be used for the build. -Example for using 4 threads:: +Example for using 4 threads: + +:: scons -j4 @@ -68,7 +70,9 @@ SCons is invoked by just calling ``scons``. If no platform is specified, SCons will detect the target platform automatically based on the host platform. It will then start building for the target platform right away. -To list the available target platforms, use ``scons platform=list``:: +To list the available target platforms, use ``scons platform=list``: + +.. code:: text scons platform=list scons: Reading SConscript files ... diff --git a/contributing/documentation/editor_and_docs_localization.rst b/contributing/documentation/editor_and_docs_localization.rst index e7d247b0007..cf1264afcf6 100644 --- a/contributing/documentation/editor_and_docs_localization.rst +++ b/contributing/documentation/editor_and_docs_localization.rst @@ -217,13 +217,15 @@ The editor translations originate from C++ strings, and may use: placed in your translation where necessary for it to be meaningful after substitution. You may need to refer to the source string location to understand what kind of content will be substituted if it's not clear from the - sentence. Example (``%s`` will be substituted with a file name or path):: + sentence. Example (``%s`` will be substituted with a file name or path): - # PO file: - "There is no '%s' file." + :: - # Weblate: - There is no '%s' file. + # PO file: + "There is no '%s' file." + + # Weblate: + There is no '%s' file. - **C escape characters** such as ``\n`` (line break) or ``\t`` (tabulation). In the Weblate editor, the ``\n`` characters are replaced by ``↵`` (return) and @@ -231,15 +233,17 @@ The editor translations originate from C++ strings, and may use: breaks in the same way as the original English string (Weblate will issue a warning if you don't). Line breaks might sometimes be used for vertical spacing, or manual wrapping of long lines which would otherwise be too long - especially in the editor translation). Example:: + especially in the editor translation). Example: + + :: - # PO file: - "Scene '%s' is currently being edited.\n" - "Changes will only take effect when reloaded." + # PO file: + "Scene '%s' is currently being edited.\n" + "Changes will only take effect when reloaded." - # Weblate: - Scene '%s' is currently being edited.↵ - Changes will only take effect when reloaded. + # Weblate: + Scene '%s' is currently being edited.↵ + Changes will only take effect when reloaded. .. note:: Only logical order of the characters matters, in the right-to-left text, format @@ -307,7 +311,9 @@ Some of the tags used are from the original BBCode (e.g. ``[b]Bold[/b]`` and ``[i]Italics[/i]``), while others are Godot-specific and used for advanced features such as inline code (e.g. ``[code]true[/code]``), linking to another class (e.g. ``[Node2D]``) or to a property in a given class (e.g. -``[member Node2D.position]``), or for multiline code blocks. Example:: +``[member Node2D.position]``), or for multiline code blocks. Example: + +:: Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1. [codeblock] diff --git a/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst index 7e4b03ebc5f..a85e4cf55a4 100644 --- a/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst +++ b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst @@ -454,14 +454,18 @@ match, with support for ``?`` and ``*`` wildcards (using The script must start with an animation filter statement (as denoted by the line beginning with an ``@``). For example, if we would like to apply filters to all -imported animations which have a name ending in ``"_Loop"``:: +imported animations which have a name ending in ``"_Loop"``: + +.. code:: text @+*_Loop Similarly, additional patterns can be added to the same line, separated by commas. Here is a modified example to additionally *include* all animations with names that begin with ``"Arm_Left"``, but also *exclude* all animations which -have names ending in ``"Attack"``:: +have names ending in ``"Attack"``: + +.. code:: text @+*_Loop, +Arm_Left*, -*Attack diff --git a/tutorials/export/exporting_for_dedicated_servers.rst b/tutorials/export/exporting_for_dedicated_servers.rst index d91d04d03e4..0c3c077ac65 100644 --- a/tutorials/export/exporting_for_dedicated_servers.rst +++ b/tutorials/export/exporting_for_dedicated_servers.rst @@ -3,6 +3,8 @@ Exporting for dedicated servers =============================== +.. highlight:: none + If you want to run a dedicated server for your project on a machine that doesn't have a GPU or display server available, you'll need to run Godot with the ``headless`` display server and ``Dummy`` :ref:`audio driver `. @@ -129,8 +131,6 @@ use **Keep** for that particular image. With the above options used, a PCK for the client (which exports all resources normally) will look as follows: -.. highlight:: none - :: . @@ -159,8 +159,6 @@ normally) will look as follows: The PCK's file structure for the server will look as follows: -.. highlight:: none - :: . diff --git a/tutorials/networking/websocket.rst b/tutorials/networking/websocket.rst index 0b17a57eddb..5bac8b53be1 100644 --- a/tutorials/networking/websocket.rst +++ b/tutorials/networking/websocket.rst @@ -99,9 +99,7 @@ This example will show you how to create a WebSocket connection to a remote serv This will print something similar to: -.. highlight:: none - -:: +.. code:: text Connecting to wss://echo.websocket.org... < Got text data from server: Request served by 7811941c69e658 @@ -113,8 +111,6 @@ Minimal server example This example will show you how to create a WebSocket server that listens for remote connections, and how to send and receive data. -.. highlight:: gdscript - :: extends Node @@ -178,9 +174,7 @@ This example will show you how to create a WebSocket server that listens for rem When a client connects, this will print something similar to this: -.. highlight:: none - -:: +.. code:: text Server started. + Peer 2 connected. diff --git a/tutorials/physics/physics_introduction.rst b/tutorials/physics/physics_introduction.rst index fe3ecad42b6..fe1a638acee 100644 --- a/tutorials/physics/physics_introduction.rst +++ b/tutorials/physics/physics_introduction.rst @@ -202,7 +202,9 @@ or ``set_collision_mask_value(layer_number, value)`` on any given :ref:`Collisio collider.set_collision_mask_value(3, true) collider.set_collision_mask_value(4, true) -Export annotations can be used to export bitmasks in the editor with a user-friendly GUI:: +Export annotations can be used to export bitmasks in the editor with a user-friendly GUI: + +:: @export_flags_2d_physics var layers_2d_physics diff --git a/tutorials/platform/android/android_plugin.rst b/tutorials/platform/android/android_plugin.rst index 27cfa2da753..1d6844af5b6 100644 --- a/tutorials/platform/android/android_plugin.rst +++ b/tutorials/platform/android/android_plugin.rst @@ -72,25 +72,31 @@ To provide further understanding, here is a break-down of the steps used to crea 1. Create an Android library module using `these instructions `_ -2. Add the Godot Android library as a dependency by updating the module's ``gradle`` `build file `_:: +2. Add the Godot Android library as a dependency by updating the module's ``gradle`` `build file `_: - dependencies { - implementation("org.godotengine:godot:4.2.0.stable") - } + .. code:: text + + dependencies { + implementation("org.godotengine:godot:4.2.0.stable") + } The Godot Android library is `hosted on MavenCentral `_, and updated for each release. 3. Create `GodotAndroidPlugin `_, an init class for the plugin extending `GodotPlugin `_. - - If the plugin exposes Kotlin or Java methods to be called from GDScript, they must be annotated with `@UsedByGodot `_. The name called from GDScript **must match the method name exactly**. There is **no** coercing ``snake_case`` to ``camelCase``. For example, from GDScript:: + - If the plugin exposes Kotlin or Java methods to be called from GDScript, they must be annotated with `@UsedByGodot `_. The name called from GDScript **must match the method name exactly**. There is **no** coercing ``snake_case`` to ``camelCase``. For example, from GDScript: + + :: - if Engine.has_singleton("MyPlugin"): - var singleton = Engine.get_singleton("MyPlugin") - print(singleton.myPluginFunction("World")) + if Engine.has_singleton("MyPlugin"): + var singleton = Engine.get_singleton("MyPlugin") + print(singleton.myPluginFunction("World")) - If the plugin uses `signals `_, the init class must return the set of signals used by overriding `GodotPlugin::getPluginSignals() `_. To emit signals, the plugin can use the `GodotPlugin::emitSignal(...) method `_. -4. Update the plugin ``AndroidManifest.xml`` `file `_ with the following meta-data:: +4. Update the plugin ``AndroidManifest.xml`` `file `_ with the following meta-data: + + .. code-block:: xml ` method:: + :ref:`Array.assign() ` method: + + :: var a: Array[Node2D] = [Node2D.new()] @@ -1248,7 +1250,9 @@ annotation if static variables don't store important data and can be reset. Currently, due to a bug, scripts are never freed, even if ``@static_unload`` annotation is used. Note that ``@static_unload`` applies to the entire script (including inner classes) -and must be placed at the top of the script, before ``class_name`` and ``extends``:: +and must be placed at the top of the script, before ``class_name`` and ``extends``: + +:: @static_unload class_name MyNode @@ -1424,7 +1428,9 @@ If a function argument has a default value, it's possible to infer the type: pass The return type of the function can be specified after the arguments list using -the arrow token (``->``):: +the arrow token (``->``): + +:: func my_int_function() -> int: return 0 @@ -1486,11 +1492,15 @@ This can be useful to create callables to pass around without polluting the clas var lambda = func (x): print(x) -To call the created lambda you can use the :ref:`call() ` method:: +To call the created lambda you can use the :ref:`call() ` method: + +:: lambda.call(42) # Prints `42`. -Lambda functions can be named for debugging purposes (the name is displayed in the Debugger):: +Lambda functions can be named for debugging purposes (the name is displayed in the Debugger): + +:: var lambda = func my_lambda(x): print(x) @@ -1503,7 +1513,9 @@ You can specify type hints for lambda functions in the same way as for regular o print(x) Note that if you want to return a value from a lambda function, an explicit ``return`` -is required (you can't omit ``return``):: +is required (you can't omit ``return``): + +:: var lambda = func (x): return x ** 2 print(lambda.call(2)) # Prints `4`. @@ -1832,7 +1844,9 @@ If a pattern matches, the first corresponding block will be executed. After that The following pattern types are available: - Literal pattern - Matches a `literal `_:: + Matches a `literal `_: + + :: match x: 1: @@ -1843,7 +1857,9 @@ The following pattern types are available: print("Oh snap! It's a string!") - Expression pattern - Matches a constant expression, an identifier, or an attribute access (``A.B``):: + Matches a constant expression, an identifier, or an attribute access (``A.B``): + + :: match typeof(x): TYPE_FLOAT: @@ -1950,7 +1966,9 @@ Unlike a pattern, a pattern guard can be an arbitrary expression. Only one branch can be executed per ``match``. Once a branch is chosen, the rest are not checked. If you want to use the same pattern for multiple branches or to prevent choosing a branch with too general pattern, -you can specify a pattern guard after the list of patterns with the ``when`` keyword:: +you can specify a pattern guard after the list of patterns with the ``when`` keyword: + +:: match point: [0, 0]: @@ -1978,7 +1996,9 @@ Classes By default, all script files are unnamed classes. In this case, you can only reference them using the file's path, using either a relative or an absolute -path. For example, if you name a script file ``character.gd``:: +path. For example, if you name a script file ``character.gd``: + +:: # Inherit from 'character.gd'. @@ -2143,7 +2163,9 @@ A class (stored as a file) can inherit from: Multiple inheritance is not allowed. -Inheritance uses the ``extends`` keyword:: +Inheritance uses the ``extends`` keyword: + +:: # Inherit/extend a globally available class. extends SomeClass @@ -2174,13 +2196,17 @@ the ``is`` keyword can be used: entity.apply_damage() To call a function in a *super class* (i.e. one ``extend``-ed in your current -class), use the ``super`` keyword:: +class), use the ``super`` keyword: + +:: super(args) This is especially useful because functions in extending classes replace functions with the same name in their super classes. If you still want to -call them, you can use ``super``:: +call them, you can use ``super``: + +:: func some_func(x): super(x) # Calls the same function on the super class. @@ -2263,12 +2289,14 @@ There are a few things to keep in mind here: in to ``idle.gd``. 4. If ``idle.gd``'s ``_init`` constructor takes 0 arguments, it still needs to pass some value to the ``state.gd`` base class, even if it does nothing. This brings us to the fact that you - can pass expressions to the base constructor as well, not just variables, e.g.:: + can pass expressions to the base constructor as well, not just variables, e.g.: - # idle.gd + :: - func _init(): - super(5) + # idle.gd + + func _init(): + super(5) Static constructor ~~~~~~~~~~~~~~~~~~ @@ -2356,7 +2384,9 @@ For this, GDScript provides a special syntax to define properties using the ``se keywords after a variable declaration. Then you can define a code block that will be executed when the variable is accessed or assigned. -Example:: +Example: + +:: var milliseconds: int = 0 var seconds: int: @@ -2376,7 +2406,9 @@ Alternative syntax ~~~~~~~~~~~~~~~~~~ Also there is another notation to use existing class functions if you want to split the code from the variable declaration -or you need to reuse the code across multiple properties (but you can't distinguish which property the setter/getter is being called for):: +or you need to reuse the code across multiple properties (but you can't distinguish which property the setter/getter is being called for): + +:: var my_prop: get = get_my_prop, set = set_my_prop @@ -2565,7 +2597,9 @@ interface separate from the player in our scene tree. In our ``character.gd`` script, we define a ``health_changed`` signal and emit it with :ref:`Signal.emit() `, and from a ``Game`` node higher up our scene tree, we connect it to the ``Lifebar`` using -the :ref:`Signal.connect() ` method:: +the :ref:`Signal.connect() ` method: + +:: # character.gd @@ -2618,8 +2652,9 @@ node in this case. This allows the ``Lifebar`` to react to health changes without coupling it to the ``Character`` node. -You can write optional argument names in parentheses after the signal's -definition:: +You can write optional argument names in parentheses after the signal's definition: + +:: # Defining a signal that forwards two arguments. signal health_changed(old_value, new_value) @@ -2760,7 +2795,8 @@ depending on whether the project is run in a debug build. When running a project from the editor, the project will be paused if an assertion error occurs. -You can optionally pass a custom error message to be shown if the assertion -fails:: +You can optionally pass a custom error message to be shown if the assertion fails: + +:: assert(enemy_power < 256, "Enemy is too powerful!") diff --git a/tutorials/scripting/gdscript/gdscript_styleguide.rst b/tutorials/scripting/gdscript/gdscript_styleguide.rst index 1db7a5cc65f..e8da34f3094 100644 --- a/tutorials/scripting/gdscript/gdscript_styleguide.rst +++ b/tutorials/scripting/gdscript/gdscript_styleguide.rst @@ -669,7 +669,9 @@ File names ~~~~~~~~~~ Use snake_case for file names. For named classes, convert the PascalCase class -name to snake_case:: +name to snake_case: + +:: # This file should be saved as `weapon.gd`. class_name Weapon diff --git a/tutorials/scripting/gdscript/static_typing.rst b/tutorials/scripting/gdscript/static_typing.rst index 1dad8e2eb2a..ca179be48ed 100644 --- a/tutorials/scripting/gdscript/static_typing.rst +++ b/tutorials/scripting/gdscript/static_typing.rst @@ -192,7 +192,9 @@ more specific (**subtype**) than the parent method. **Contravariance:** When you inherit a method, you can specify a parameter type that is less specific (**supertype**) than the parent method. -Example:: +Example: + +:: class_name Parent @@ -293,7 +295,9 @@ and not your ``PlayerController`` on the ``_on_body_entered`` callback. You can check if this ``PhysicsBody2D`` is your ``Player`` with the ``as`` keyword, and using the colon ``:`` again to force the variable to use this type. -This forces the variable to stick to the ``PlayerController`` type:: +This forces the variable to stick to the ``PlayerController`` type: + +:: func _on_body_entered(body: PhysicsBody2D) -> void: var player := body as PlayerController @@ -312,7 +316,9 @@ get full autocompletion on the player variable thanks to that cast. The ``as`` keyword silently casts the variable to ``null`` in case of a type mismatch at runtime, without an error/warning. While this may be convenient in some cases, it can also lead to bugs. Use the ``as`` keyword only if this - behavior is intended. A safer alternative is to use the ``is`` keyword:: + behavior is intended. A safer alternative is to use the ``is`` keyword: + + :: if not (body is PlayerController): push_error("Bug: body is not PlayerController.") @@ -323,12 +329,16 @@ get full autocompletion on the player variable thanks to that cast. player.damage() - You can also simplify the code by using the ``is not`` operator:: + You can also simplify the code by using the ``is not`` operator: + + :: if body is not PlayerController: push_error("Bug: body is not PlayerController") - Alternatively, you can use the ``assert()`` statement:: + Alternatively, you can use the ``assert()`` statement: + + :: assert(body is PlayerController, "Bug: body is not PlayerController.") diff --git a/tutorials/shaders/introduction_to_shaders.rst b/tutorials/shaders/introduction_to_shaders.rst index 9e7c840d3fb..f6691e11945 100644 --- a/tutorials/shaders/introduction_to_shaders.rst +++ b/tutorials/shaders/introduction_to_shaders.rst @@ -23,20 +23,22 @@ working with shaders, you need to code and think differently from other programming languages. Suppose you want to update all the pixels in a texture to a given color. In -GDScript, your code would use ``for`` loops:: +GDScript, your code would use ``for`` loops: - for x in range(width): - for y in range(height): - set_color(x, y, some_color) +:: + + for x in range(width): + for y in range(height): + set_color(x, y, some_color) Your code is already part of a loop in a shader, so the corresponding code would look like this. .. code-block:: glsl - void fragment() { - COLOR = some_color; - } + void fragment() { + COLOR = some_color; + } .. note:: diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 6c272569b6d..f9d29a71b76 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -1670,8 +1670,9 @@ float **dot**\ (\ |vec_type| a, |vec_type| b) :ref:`🔗` vec3 **cross**\ (\ vec3 a, vec3 b) :ref:`🔗` - Returns the cross product of two vectors. - i.e.:: + Returns the cross product of two vectors. i.e.: + + .. code-block:: glsl vec2( a.y * b.z - b.y * a.z, a.z * b.x - b.z * a.x, @@ -1755,7 +1756,7 @@ vec3 **refract**\ (\ vec3 I, vec3 N, float eta) :ref:`🔗` ``R`` is calculated as: - :: + .. code-block:: glsl k = 1.0 - eta * eta * (1.0 - dot(N, I) * dot(N, I)); if (k < 0.0)