From 620e0aeb88ba46e6c6fe562a612a8e80cdd6e363 Mon Sep 17 00:00:00 2001 From: Max Hilbrunner Date: Tue, 10 Sep 2024 14:53:28 +0200 Subject: [PATCH] Manual backport of some fixes --- AUTHORS.md | 2 +- _static/css/custom.css | 31 +++++++++++++++++++ _static/js/custom.js | 17 ++++++++++ _tools/codespell-ignore.txt | 2 ++ about/faq.rst | 2 +- about/introduction.rst | 2 +- .../contributing_to_the_documentation.rst | 4 +-- .../contributing/documentation_guidelines.rst | 3 +- development/cpp/custom_audiostreams.rst | 4 +-- .../assets_pipeline/importing_images.rst | 2 +- tutorials/inputs/custom_mouse_cursor.rst | 25 ++++++++++----- .../plugins/running_code_in_the_editor.rst | 2 +- tutorials/scripting/debug/debugger_panel.rst | 20 ++++++++++-- .../debug/overview_of_debugging_tools.rst | 18 +++++++++++ .../gdnative/gdnative_cpp_example.rst | 22 ++++++------- .../scripting/gdscript/gdscript_basics.rst | 3 +- tutorials/scripting/resources.rst | 26 +++++++++------- .../shader_reference/shading_language.rst | 22 +++++++++++-- .../your_second_3d_shader.rst | 2 +- 19 files changed, 163 insertions(+), 46 deletions(-) diff --git a/AUTHORS.md b/AUTHORS.md index 71a5e0de1d2..8a87aeb6f6c 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -4,7 +4,7 @@ Godot Engine is developed by a community of voluntary contributors who contribute on all areas, including writing and maintaining the documentation. It is impossible to list them all; nevertheless, this file aims at listing -the writers who contributed significant patches to this CC-BY licensed +the writers who contributed significant patches to this CC BY licensed documentation on the `godot-docs` repository. GitHub usernames are indicated in parentheses, or as sole entry when no other diff --git a/_static/css/custom.css b/_static/css/custom.css index 6b89f28a9e4..fefd447f4b0 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -827,6 +827,7 @@ code, .highlight { background-color: var(--highlight-background-color); + tab-size: 4; } /* Emphasized lines */ @@ -1677,3 +1678,33 @@ p + .classref-constant { .wy-menu-vertical p.caption + ul.active { display: block; } + +/* Allow :abbr: tags' content to be displayed on mobile platforms by tapping the word */ +@media (hover: none), +(hover: on-demand), +(-moz-touch-enabled: 1), +(pointer:coarse) { + + /* Do not enable on desktop platforms to avoid doubling the tooltip */ + abbr[title] { + position: relative; + } + + abbr[title]:hover::after, + abbr[title]:focus::after { + content: attr(title); + + position: absolute; + left: 0; + bottom: -32px; + width: auto; + white-space: nowrap; + + background-color: #1e1e1e; + color: #fff; + border-radius: 3px; + box-shadow: 1px 1px 5px 0 rgba(0, 0, 0, 0.4); + font-size: 14px; + padding: 3px 5px; + } +} diff --git a/_static/js/custom.js b/_static/js/custom.js index 7479bb37d6e..65760f522a9 100644 --- a/_static/js/custom.js +++ b/_static/js/custom.js @@ -291,6 +291,23 @@ const registerOnScrollEvent = (function(){ } } + // Change indentation from spaces to tabs for codeblocks. + const codeBlocks = document.querySelectorAll('.rst-content div[class^="highlight"] pre'); + for (const codeBlock of codeBlocks) { + const classList = codeBlock.parentNode.parentNode.classList; + if (!classList.contains('highlight-gdscript') && !classList.contains('highlight-cpp')) { + // Only change indentation for GDScript and C++. + continue; + } + let html = codeBlock.innerHTML.replace(/^()?( {4})/gm, '\t'); + let html_old = ""; + while (html != html_old) { + html_old = html; + html = html.replace(/\t( {4})/gm, '\t\t') + } + codeBlock.innerHTML = html; + } + // See `godot_is_latest` in conf.py const isLatest = document.querySelector('meta[name=doc_is_latest]').content.toLowerCase() === 'true'; if (isLatest) { diff --git a/_tools/codespell-ignore.txt b/_tools/codespell-ignore.txt index afd220b7e6f..ddbe3cec378 100644 --- a/_tools/codespell-ignore.txt +++ b/_tools/codespell-ignore.txt @@ -7,3 +7,5 @@ uint subtile implementors thirdparty +inout +findn diff --git a/about/faq.rst b/about/faq.rst index 3ebf34951eb..30b8b32e836 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -17,7 +17,7 @@ In short: * You are free to modify, distribute, redistribute, and remix Godot to your heart's content, for any reason, both non-commercially and commercially. All the contents of this accompanying documentation are published under -the permissive Creative Commons Attribution 3.0 (`CC-BY 3.0 `_) license, with attribution +the permissive Creative Commons Attribution 3.0 (`CC BY 3.0 `_) license, with attribution to "Juan Linietsky, Ariel Manzur and the Godot Engine community." Logos and icons are generally under the same Creative Commons license. Note diff --git a/about/introduction.rst b/about/introduction.rst index 20509d4bb7a..2c1e85dfc15 100644 --- a/about/introduction.rst +++ b/about/introduction.rst @@ -70,7 +70,7 @@ open source `Sphinx `_ and `ReadTheDocs `_. All the contents are under the permissive Creative Commons Attribution 3.0 -(`CC-BY 3.0 `_) license, with +(`CC BY 3.0 `_) license, with attribution to "Juan Linietsky, Ariel Manzur and the Godot Engine community". Organization of the documentation diff --git a/community/contributing/contributing_to_the_documentation.rst b/community/contributing/contributing_to_the_documentation.rst index e5101a1c46f..071bcf45881 100644 --- a/community/contributing/contributing_to_the_documentation.rst +++ b/community/contributing/contributing_to_the_documentation.rst @@ -180,8 +180,8 @@ License ------- This documentation and every page it contains is published under the terms of -the `Creative Commons Attribution 3.0 license (CC-BY-3.0) -`_, with +the `Creative Commons Attribution 3.0 license (CC BY 3.0) +`_, with attribution to "Juan Linietsky, Ariel Manzur and the Godot community". By contributing to the documentation on the GitHub repository, you agree that diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index d5ceffb752a..6e6431e612c 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -135,7 +135,8 @@ License ------- This documentation and every page it contains is published under the terms of -the `Creative Commons Attribution 3.0 license (CC-BY-3.0) `_, with attribution to "Juan Linietsky, Ariel Manzur and the Godot community". +the `Creative Commons Attribution 3.0 license (CC BY 3.0) `_, +with attribution to "Juan Linietsky, Ariel Manzur and the Godot community". By contributing to the documentation on the GitHub repository, you agree that your changes are distributed under this license. diff --git a/development/cpp/custom_audiostreams.rst b/development/cpp/custom_audiostreams.rst index 33d9095ac68..7894a2eff67 100644 --- a/development/cpp/custom_audiostreams.rst +++ b/development/cpp/custom_audiostreams.rst @@ -23,7 +23,7 @@ References: ~~~~~~~~~~~ - `servers/audio/audio_stream.h `__ -- `scene/audio/audioplayer.cpp `__ +- `scene/audio/audio_stream_player.cpp `__ What for? --------- @@ -348,4 +348,4 @@ References: ~~~~~~~~~~~ - `core/math/audio_frame.h `__ - `servers/audio/audio_stream.h `__ -- `scene/audio/audioplayer.cpp `__ +- `scene/audio/audio_stream_player.cpp `__ diff --git a/tutorials/assets_pipeline/importing_images.rst b/tutorials/assets_pipeline/importing_images.rst index f0b5519fe58..f982ff65fd1 100644 --- a/tutorials/assets_pipeline/importing_images.rst +++ b/tutorials/assets_pipeline/importing_images.rst @@ -22,7 +22,7 @@ Godot can import the following image formats: - PNG (``.png``) - Precision is limited to 8 bits per channel upon importing (no HDR images). - Truevision Targa (``.tga``) -- SVG (``.svg``, ``.svgz``) +- SVG (``.svg``) - SVGs are rasterized using `NanoSVG `__ when importing them. Support is limited; complex vectors may not render correctly. For complex vectors, rendering them to PNGs using Inkscape is often a better solution. diff --git a/tutorials/inputs/custom_mouse_cursor.rst b/tutorials/inputs/custom_mouse_cursor.rst index c231d361045..388d74ae61e 100644 --- a/tutorials/inputs/custom_mouse_cursor.rst +++ b/tutorials/inputs/custom_mouse_cursor.rst @@ -3,7 +3,9 @@ Customizing the mouse cursor ============================ -You might want to change the appearance of the mouse cursor in your game in order to suit the overall design. There are two ways to customize the mouse cursor: +You might want to change the appearance of the mouse cursor in your game in +order to suit the overall design. There are two ways to customize the mouse +cursor: 1. Using project settings 2. Using a script @@ -13,8 +15,8 @@ Using project settings is a simpler (but more limited) way to customize the mous .. note:: You could display a "software" mouse cursor by hiding the mouse cursor and - moving a Sprite to the cursor position in a ``_process`` method, but this - will add at least one frame of latency compared to an "hardware" mouse + moving a Sprite2D to the cursor position in a ``_process()`` method, but + this will add at least one frame of latency compared to an "hardware" mouse cursor. Therefore, it's recommended to use the approach described here whenever possible. @@ -31,7 +33,12 @@ Open project settings, go to Display>Mouse Cursor. You will see Custom Image and Custom Image is the desired image that you would like to set as the mouse cursor. Custom Hotspot is the point in the image that you would like to use as the cursor's detection point. -.. note:: The custom image **must** be less than 256x256. +.. warning:: + + The custom image **must** be 256×256 pixels at most. To avoid rendering + issues, sizes lower than or equal to 128×128 are recommended. + + On the web platform, the maximum allowed cursor image size is 128×128. Using a script -------------- @@ -73,8 +80,10 @@ Create a Node and attach the following script. Input.SetCustomMouseCursor(beam, Input.CursorShape.Ibeam); } -.. note:: - Check :ref:`Input.set_custom_mouse_cursor() `. +.. seealso:: + + Check :ref:`Input.set_custom_mouse_cursor() `'s + documentation for more information on usage and platform-specific caveats. Demo project @@ -86,4 +95,6 @@ https://github.com/guilhermefelipecgs/custom_hardware_cursor Cursor list ----------- -As documented in the :ref:`Input ` class (see the **CursorShape** enum), there are multiple mouse cursors you can define. Which ones you want to use depends on your use case. +As documented in the :ref:`Input ` class (see the **CursorShape** +enum), there are multiple mouse cursors you can define. Which ones you want to +use depends on your use case. diff --git a/tutorials/plugins/running_code_in_the_editor.rst b/tutorials/plugins/running_code_in_the_editor.rst index 57f2454b85f..48ad1b4cf70 100644 --- a/tutorials/plugins/running_code_in_the_editor.rst +++ b/tutorials/plugins/running_code_in_the_editor.rst @@ -61,7 +61,7 @@ On the other hand, if you want to execute code only in game, simply negate the s // Code to execute when in game. } -Pieces of code do not have either of the 2 conditions above will run both in-editor and in-game. +Pieces of code that do not have either of the 2 conditions above will run both in-editor and in-game. Here is how a ``_process()`` function might look for you: diff --git a/tutorials/scripting/debug/debugger_panel.rst b/tutorials/scripting/debug/debugger_panel.rst index f4c074c4288..91bd2f538d9 100644 --- a/tutorials/scripting/debug/debugger_panel.rst +++ b/tutorials/scripting/debug/debugger_panel.rst @@ -17,8 +17,24 @@ The Debugger tab opens automatically when the GDScript compiler reaches a breakpoint in your code. It gives you a `stack trace `__, -information about the state of the object, and buttons to control -the program's execution. +information about the state of the object, and buttons to control the program's +execution. When the debugger breaks on a breakpoint, a green triangle arrow is +visible in the script editor's gutter. This arrow indicates the line of code the +debugger broke on. + +.. tip:: + + You can create a breakpoint by clicking the gutter in the left of the script + editor (on the left of the line numbers). When hovering this gutter, you + will see a transparent red dot appearing, which turns into an opaque red dot + after the breakpoint is placed by clicking. Click the red dot again to + remove the breakpoint. Breakpoints created this way persist across editor + restarts, even if the script wasn't saved when exiting the editor. + + You can also use the ``breakpoint`` keyword in GDScript to create a + breakpoint that is stored in the script itself. Unlike breakpoints created by + clicking in the gutter, this keyword-based breakpoint is persistent across + different machines when using version control. You can use the buttons in the top-right corner to: diff --git a/tutorials/scripting/debug/overview_of_debugging_tools.rst b/tutorials/scripting/debug/overview_of_debugging_tools.rst index 230ab572751..0ab4cbc9384 100644 --- a/tutorials/scripting/debug/overview_of_debugging_tools.rst +++ b/tutorials/scripting/debug/overview_of_debugging_tools.rst @@ -79,6 +79,20 @@ The script editor has its own set of debug tools for use with breakpoints and two options. The breakpoint tools can also be found in the **Debugger** tab of the debugger. +.. tip:: + + You can create a breakpoint by clicking the gutter in the left of the script + editor (on the left of the line numbers). When hovering this gutter, you + will see a transparent red dot appearing, which turns into an opaque red dot + after the breakpoint is placed by clicking. Click the red dot again to + remove the breakpoint. Breakpoints created this way persist across editor + restarts, even if the script wasn't saved when exiting the editor. + + You can also use the ``breakpoint`` keyword in GDScript to create a + breakpoint that is stored in the script itself. Unlike breakpoints created by + clicking in the gutter, this keyword-based breakpoint is persistent across + different machines when using version control. + .. image:: img/overview_script_editor.png The **Break** button causes a break in the script like a breakpoint would. @@ -90,6 +104,10 @@ The **Keep Debugger Open** option keeps the debugger open after a scene has been closed. And the **Debug with External Editor** option lets you debug your game with an external editor. +When the debugger breaks on a breakpoint, a green triangle arrow is visible in +the script editor's gutter. This arrow indicates the line of code the debugger +broke on. + .. warning:: Breakpoints won't break on code if it's diff --git a/tutorials/scripting/gdnative/gdnative_cpp_example.rst b/tutorials/scripting/gdnative/gdnative_cpp_example.rst index b5706ace7c1..aa03771569d 100644 --- a/tutorials/scripting/gdnative/gdnative_cpp_example.rst +++ b/tutorials/scripting/gdnative/gdnative_cpp_example.rst @@ -154,7 +154,7 @@ directories in your GDNative module. In the ``src`` folder, we'll start with creating our header file for the GDNative node we'll be creating. We will name it ``gdexample.h``: -.. code-block:: C++ +.. code-block:: cpp #ifndef GDEXAMPLE_H #define GDEXAMPLE_H @@ -212,7 +212,7 @@ our object. It has to exist even if you don't place any code in it. Let's implement our functions by creating our ``gdexample.cpp`` file: -.. code-block:: C++ +.. code-block:: cpp #include "gdexample.h" @@ -261,7 +261,7 @@ and source file like we've implemented ``GDExample`` up above. What we need now is a small bit of code that tells Godot about all the NativeScripts in our GDNative plugin. -.. code-block:: C++ +.. code-block:: cpp #include "gdexample.h" @@ -432,7 +432,7 @@ allows us to control the amplitude of our wave. In our ``gdexample.h`` file we simply need to add a member variable like so: -.. code-block:: C++ +.. code-block:: cpp ... private: @@ -443,7 +443,7 @@ In our ``gdexample.h`` file we simply need to add a member variable like so: In our ``gdexample.cpp`` file we need to make a number of changes, we will only show the methods we end up changing, don't remove the lines we're omitting: -.. code-block:: C++ +.. code-block:: cpp void GDExample::_register_methods() { register_method("_process", &GDExample::_process); @@ -486,7 +486,7 @@ Let's do the same but for the speed of our animation and use a setter and getter function. Our ``gdexample.h`` header file again only needs a few more lines of code: -.. code-block:: C++ +.. code-block:: cpp ... float amplitude; @@ -500,7 +500,7 @@ code: This requires a few more changes to our ``gdexample.cpp`` file, again we're only showing the methods that have changed so don't remove anything we're omitting: -.. code-block:: C++ +.. code-block:: cpp void GDExample::_register_methods() { register_method("_process", &GDExample::_process); @@ -565,7 +565,7 @@ would need to showcase a far more complete example. This is the required syntax: -.. code-block:: C++ +.. code-block:: cpp some_other_node->connect("the_signal", this, "my_method"); @@ -578,7 +578,7 @@ emit a signal every time a second has passed and pass the new location along. In our ``gdexample.h`` header file, we need to define a new member ``time_emit``: -.. code-block:: C++ +.. code-block:: cpp ... float time_passed; @@ -593,7 +593,7 @@ constructor. We'll look at the other 2 needed changes one by one. In our ``_register_methods`` method, we need to declare our signal. This is done as follows: -.. code-block:: C++ +.. code-block:: cpp void GDExample::_register_methods() { register_method("_process", &GDExample::_process); @@ -609,7 +609,7 @@ type of each parameter we'll send along with this signal. Next, we'll need to change our ``_process`` method: -.. code-block:: C++ +.. code-block:: cpp void GDExample::_process(float delta) { time_passed += speed * delta; diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index 9f1c1ffbb04..be35079b603 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -192,7 +192,8 @@ in case you want to take a look under the hood. +------------+---------------------------------------------------------------------------------------------------------------+ | setget | Defines setter and getter functions for a variable. | +------------+---------------------------------------------------------------------------------------------------------------+ -| breakpoint | Editor helper for debugger breakpoints. | +| breakpoint | Editor helper for debugger breakpoints. Unlike breakpoints created by clicking in the gutter, ``breakpoint`` | +| | is stored in the script itself. This makes it persistent across different machines when using version control.| +------------+---------------------------------------------------------------------------------------------------------------+ | preload | Preloads a class or variable. See `Classes as resources`_. | +------------+---------------------------------------------------------------------------------------------------------------+ diff --git a/tutorials/scripting/resources.rst b/tutorials/scripting/resources.rst index 7164405891d..f3c62e4c594 100644 --- a/tutorials/scripting/resources.rst +++ b/tutorials/scripting/resources.rst @@ -206,7 +206,7 @@ Let's see some examples. export(Resource) var sub_resource export(Array, String) var strings - # Make sure that every parameter has a default value. + # Make sure that every parameter has a default value. # Otherwise, there will be problems with creating and editing # your resource via the inspector. func _init(p_health = 0, p_sub_resource = null, p_strings = []): @@ -230,7 +230,7 @@ Let's see some examples. using Godot; namespace ExampleProject { - public class BotStats : Resource + public partial class BotStats : Resource { [Export] public int Health { get; set; } @@ -239,16 +239,20 @@ Let's see some examples. public Resource SubResource { get; set; } [Export] - public String[] Strings { get; set; } + public string[] Strings { get; set; } - // Make sure that every parameter has a default value. - // Otherwise, there will be problems with creating and editing - // your resource via the inspector. - public BotStats(int health = 0, Resource subResource = null, String[] strings = null) + // Make sure you provide a parameterless constructor. + // In C#, a parameterless constructor is different from a + // constructor with all default values. + // Without a parameterless constructor, Godot will have problems + // creating and editing your resource via the inspector. + public BotStats() : this(0, null, null) {} + + public BotStats(int health, Resource subResource, string[] strings) { Health = health; SubResource = subResource; - Strings = strings ?? new String[0]; + Strings = strings ?? Array.Empty(); } } } @@ -304,7 +308,7 @@ Let's see some examples. using System; using Godot; - public class BotStatsTable : Resource + public partial class BotStatsTable : Resource { private Godot.Dictionary _stats = new Godot.Dictionary(); @@ -357,9 +361,9 @@ Let's see some examples. using System; using Godot; - public class MyNode : Node + public partial class MyNode : Node { - public class MyResource : Resource + public partial class MyResource : Resource { [Export] public int Value { get; set; } = 5; diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 36d70c228be..f9c6607770d 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -380,7 +380,14 @@ Godot can't protect you from this, so be careful not to make this mistake! Discarding ---------- -Fragment and light functions can use the **discard** keyword. If used, the fragment is discarded and nothing is written. +Fragment and light functions can use the ``discard`` keyword. If used, the +fragment is discarded and nothing is written. + +Beware that ``discard`` has a performance cost when used, as it will prevent the +depth prepass from being effective on any surfaces using the shader. Also, a +discarded pixel still needs to be rendered in the vertex shader, which means a +shader that uses ``discard`` on all of its pixels is still more expensive to +render compared to not rendering any object in the first place. Functions --------- @@ -400,8 +407,9 @@ It is possible to define functions in a Godot shader. They use the following syn } -You can only use functions that have been defined above (higher in the editor) the function from which you are calling -them. +You can only use functions that have been defined above (higher in the editor) +the function from which you are calling them. Redefining a function that has +already been defined above (or is a built-in function name) will cause an error. Function arguments can have special qualifiers: @@ -417,6 +425,14 @@ Example below: result = a + b; } +.. note:: + + Unlike GLSL, Godot's shader language does **not** support function + overloading. This means that a function cannot be defined several times with + different argument types or numbers of arguments. As a workaround, use + different names for functions that accept a different number of arguments or + arguments of different types. + Varyings ~~~~~~~~ diff --git a/tutorials/shaders/your_first_shader/your_second_3d_shader.rst b/tutorials/shaders/your_first_shader/your_second_3d_shader.rst index fdaf42c3aca..3c0a0d42419 100644 --- a/tutorials/shaders/your_first_shader/your_second_3d_shader.rst +++ b/tutorials/shaders/your_first_shader/your_second_3d_shader.rst @@ -141,7 +141,7 @@ watery effect. .. image:: img/rim.png -In order to add fresnal reflectance, we will compute a fresnel term in our +In order to add fresnel reflectance, we will compute a fresnel term in our fragment shader. Here, we aren't going to use a real fresnel term for performance reasons. Instead, we'll approximate it using the dot product of the ``NORMAL`` and ``VIEW`` vectors. The ``NORMAL`` vector points away from the