godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-05 22:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #10969 from Calinou/code-block-avoid-shorthand-syntax

Browse Source 
Replace uses of shorthand codeblock syntax to avoid issues with localization
This commit is contained in:
Max Hilbrunner
2025-05-31 02:57:35 +02:00
committed by GitHub
parent 0027821302 8a6ad4c926
commit ff8419a095
32 changed files with 580 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
about/complying_with_licenses.rst
View File

@@ -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:

8
contributing/development/compiling/compiling_for_ios.rst
View File

@@ -24,7 +24,9 @@ Requirements
from the `MoltenVK SDK <https://github.com/KhronosGroup/MoltenVK#fetching-moltenvk-source-code>`__.
.. note:: If you have `Homebrew <https://brew.sh/>`_ 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 <https://www.macports.org/>`_
installed, you can easily install SCons using the
following command::
following command:
::
sudo port install scons

16
contributing/development/compiling/compiling_for_linuxbsd.rst
View File

@@ -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

32
contributing/development/compiling/compiling_for_macos.rst
View File

@@ -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 <https://brew.sh/>`_ 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 <https://www.macports.org/>`_
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

32
contributing/development/compiling/compiling_for_web.rst
View File

@@ -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 <doc_web_javascript_bridge>` 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 <doc_javascript_export_options>` 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

40
contributing/development/compiling/compiling_for_windows.rst
View File

@@ -38,13 +38,17 @@ For compiling under Windows, the following is required:
Studio releases.
.. note:: If you have `Scoop <https://scoop.sh/>`_ 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 <https://www.msys2.org/>`_ 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 <https://github.com/godotengine/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 <https://github.com/godotengine/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 ``<version>`` with the version identifier
%APPDATA%\Godot\export_templates\<version>\
With the following names::
With the following names:
::
windows_debug_x86_32_console.exe
windows_debug_x86_32.exe

4
contributing/development/compiling/compiling_with_dotnet.rst
View File

@@ -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:
::
<godot_binary> --headless --generate-mono-glue modules/mono/glue

4
contributing/development/compiling/index.rst
View File

@@ -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 <doc_faq_why_scons>`, 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

16
contributing/development/compiling/introduction_to_the_buildsystem.rst
View File

@@ -8,18 +8,24 @@ Introduction to the buildsystem
Godot is a primarily C++ project and it :ref:`uses the SCons build system. <doc_faq_why_scons>`
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.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]

12
contributing/development/core_and_modules/custom_modules_in_cpp.rst
View File

@@ -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 <file>..." 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/<godot_binary> --doctool .
bin/<godot_binary> --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

4
contributing/development/core_and_modules/custom_resource_format_loaders.rst
View File

@@ -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

4
contributing/development/debugging/macos_debug.rst
View File

@@ -34,7 +34,9 @@ Create an ``editor.entitlements`` text file with the following contents:
</dict>
</plist>
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

4
contributing/development/debugging/vulkan/vulkan_validation_layers.rst
View File

@@ -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

8
contributing/documentation/docs_image_guidelines.rst
View File

@@ -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

56
contributing/documentation/docs_writing_guidelines.rst
View File

@@ -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<class_ProjectSettings_property_application/run/max_fps>` to ``60``.
- In **Project Settings > Application > Run**, set :ref:`Max FPS<class_ProjectSettings_property_application/run/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.

4
contributing/documentation/editor_and_docs_localization.rst
View File

@@ -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.

4
tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst
View File

@@ -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
+*

8
tutorials/best_practices/project_organization.rst
View File

@@ -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 <path to project folder> 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

4
tutorials/export/exporting_projects.rst
View File

@@ -248,7 +248,9 @@ depending on your needs.
Due to a `known bug <https://github.com/godotengine/godot/pull/42123>`__,
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

4
tutorials/i18n/pseudolocalization.rst
View File

@@ -79,7 +79,9 @@ and then calling
:ref:`TranslationServer.reload_pseudolocalization() <class_TranslationServer_method_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)

4
tutorials/io/binary_serialization_api.rst
View File

@@ -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;

4
tutorials/migrating/upgrading_to_godot_4.1.rst
View File

@@ -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]

8
tutorials/physics/physics_introduction.rst
View File

@@ -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 <class_CollisionObject2D>` as follows::
or ``set_collision_mask_value(layer_number, value)`` on any given :ref:`CollisionObject2D <class_CollisionObject2D>` as follows:
::
# Example: Setting mask value to enable layers 1, 3, and 4.

88
tutorials/platform/android/android_plugin.rst
View File

@@ -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.<version>.<status>.aar`` binary from `Godot's download page <https://godotengine.org/download>`_ 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 <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/making_plugins.html#the-script-file>`_ for the export functionality within the plugin directory (e.g: in ``addons/<plugin_name>/``)
- 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 = "<plugin_name>"
class AndroidExportPlugin extends EditorExportPlugin:
# Plugin's name.
var _plugin_name = "<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(["<paths_to_debug_android_plugin_aar_binaries>"])
else:
return PackedStringArray(["<paths_to_release_android_plugin_aar_binaries>"])
# Return the paths of the plugin's AAR binaries relative to the 'addons' directory.
func _get_android_libraries(platform, debug):
if debug:
return PackedStringArray(["<paths_to_debug_android_plugin_aar_binaries>"])
else:
return PackedStringArray(["<paths_to_release_android_plugin_aar_binaries>"])
# 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 <https://docs.godotengine.org/en/stable/classes/class_editorexportplugin.html>`_ 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

4
tutorials/platform/ios/ios_plugin.rst
View File

@@ -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"

16
tutorials/scripting/evaluating_expressions.rst
View File

@@ -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() <class_Expression_method_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

212
tutorials/scripting/gdscript/gdscript_basics.rst
View File

@@ -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 <class_@GDScript>`.
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 <doc_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 <class_GDScript>`. 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

12
tutorials/scripting/gdscript/gdscript_documentation_comments.rst
View File

@@ -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.

24
tutorials/scripting/gdscript/gdscript_exports.rst
View File

@@ -310,7 +310,9 @@ See :ref:`@export_flags <class_@GDScript_annotation_@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"

92
tutorials/scripting/gdscript/static_typing.rst
View File

@@ -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]] = []

44
tutorials/shaders/shader_reference/shader_functions.rst
View File

@@ -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:`🔗<shader_func_refract>`
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:`🔗<shader_func_any>`
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:`🔗<shader_func_all>`
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:`🔗<shader
Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with
an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the
partial derivatives as follows::
partial derivatives as follows:
::
δu/δx=0, δv/δx=0, δw/δx=0
δu/δy=0, δv/δy=0, δw/δy=0
@@ -2815,7 +2825,9 @@ vec4 **textureGather**\ (\ samplerCube s, vec3 p [, int comps] ) :ref:`🔗<shad
Gathers four texels from a texture.
Returns the value::
Returns the value:
::
vec4(Sample_i0_j1(p, base).comps,
Sample_i1_j1(p, base).comps,
@@ -3258,7 +3270,9 @@ uint **packUnorm2x16**\ (\ vec2 v) :ref:`🔗<shader_func_packUnorm2x16>`
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:`🔗<shader_func_packSnorm2x16>`
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:`🔗<shader_func_packUnorm4x8>`
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:`🔗<shader_func_packSnorm4x8>`
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

4
tutorials/ui/bbcode_in_richtextlabel.rst
View File

@@ -581,7 +581,9 @@ To handle clicked ``[url]`` tags, connect the ``RichTextLabel`` node's
:ref:`meta_clicked <class_RichTextLabel_signal_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.