diff --git a/about/complying_with_licenses.md b/about/complying_with_licenses.md index 96c1dfb..55f56c2 100644 --- a/about/complying_with_licenses.md +++ b/about/complying_with_licenses.md @@ -16,7 +16,8 @@ distribute the software (and derivative projects, including games made with it). Your game or project can have a different license, but it still needs to comply with the original one. -.. warning:: +Warning: + In your project's credits screen, remember to also list third-party notices for assets you're using, such as textures, models, sounds, music and fonts. @@ -43,7 +44,8 @@ This text reads as follows: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -.. note:: +Note: + Your games do not need to be under the same license. You are free to release your Godot projects under any license and to create commercial games with @@ -114,7 +116,8 @@ Godot license: Portions of this software are copyright © ( year> The FreeType Project (www.freetype.org). All rights reserved. -.. note:: +Note: + ( year> should correspond to the value from the FreeType version used in your build. This information can be found in the editor by opening @@ -160,7 +163,8 @@ Keep in mind that Godot 2.x and 3.0 use `OpenSSL ( https://www.openssl.org )`_ 1 instead. This old OpenSSL version used the OpenSSL license, not the Apache 2 license as the latest version of OpenSSL currently uses (as of April 2022). -.. note:: +Note: + If you exported your project using a `custom build with specific modules disabled ( doc_optimizing_for_size )`, diff --git a/about/docs_changelog.md b/about/docs_changelog.md index a6c2384..a324690 100644 --- a/about/docs_changelog.md +++ b/about/docs_changelog.md @@ -8,7 +8,8 @@ includes many new tutorials, many fixes and updates for old tutorials, and many to the `class reference ( toc-class-ref )`. Below is a list of new tutorials added since version 3.1. -.. note:: This document only contains new tutorials so not all changes are reflected, +Note: + This document only contains new tutorials so not all changes are reflected, many tutorials have been substantially updated but are not reflected in this document. New tutorials since version 3.1 diff --git a/about/introduction.md b/about/introduction.md index a906a11..1f6c7cb 100644 --- a/about/introduction.md +++ b/about/introduction.md @@ -63,7 +63,8 @@ language and then compiled into a static website/offline document using the open source `Sphinx ( http://www.sphinx-doc.org )`_ and `ReadTheDocs ( https://readthedocs.org/ )`_ tools. -.. note:: You can contribute to Godot's documentation by opening issue tickets +Note: + You can contribute to Godot's documentation by opening issue tickets or sending patches via pull requests on its GitHub `source repository ( https://github.com/godotengine/godot-docs )`_, or translating it into your language on `Hosted Weblate diff --git a/about/list_of_features.md b/about/list_of_features.md index 5612cba..4d74ed2 100644 --- a/about/list_of_features.md +++ b/about/list_of_features.md @@ -5,7 +5,8 @@ List of features This page aims to list all features currently supported by Godot. -.. note:: +Note: + This page lists features supported by the current stable version of Godot (3.5). `More features ( https://docs.godotengine.org/en/latest/about/list_of_features.html )` @@ -281,7 +282,8 @@ Editor - Real-time occluder shapes (sphere and polygon). Not as effective as rooms and portals (and doesn't support gameplay notifications), but easier to set up. -.. note:: +Note: + Most of the effects listed above can be adjusted for better performance or to further improve quality. This can be helpful when using Godot for @@ -379,7 +381,8 @@ Scripting - Maintained D, Kotlin, Python, Nim, and Rust bindings provided by the community. -.. warning:: +Warning: + `Godot 4.0 will remove VisualScript from core entirely. ( https://godotengine.org/article/godot-4-will-discontinue-visual-scripting )` As a result, creating new projects using visual scripting in Godot is not recommended. @@ -646,7 +649,8 @@ Miscellaneous - Open developement process with `contributions welcome ( doc_ways_to_contribute )`. -.. seealso:: +See also: + The `Godot proposals repository ( https://github.com/godotengine/godot-proposals )` lists features that have been requested by the community and may be implemented diff --git a/about/release_policy.md b/about/release_policy.md index d4916ab..c156bdd 100644 --- a/about/release_policy.md +++ b/about/release_policy.md @@ -59,7 +59,8 @@ further developed for maintenance releases in a Git branch of the same name (for example patch updates for the 3.3 stable branch are developed in the `3.3` Git branch). -.. note:: +Note: + As mentioned in the introduction, Godot's release policy is evolving, and earlier Godot releases may not have followed the above rules to the letter. diff --git a/about/troubleshooting.md b/about/troubleshooting.md index cb6c93c..1932a73 100644 --- a/about/troubleshooting.md +++ b/about/troubleshooting.md @@ -5,7 +5,8 @@ Troubleshooting This page lists common issues encountered when using Godot and possible solutions. -.. seealso:: +See also: + See `doc_using_the_web_editor` for caveats specific to the HTML5 version of the Godot editor. diff --git a/community/contributing/bisecting_regressions.md b/community/contributing/bisecting_regressions.md index 31f2ab7..4e77e84 100644 --- a/community/contributing/bisecting_regressions.md +++ b/community/contributing/bisecting_regressions.md @@ -38,7 +38,8 @@ is roughly in the middle of all test builds available). If you can't reproduce the bug with Godot 3.2 beta 1, then try newer betas and RC builds. If you do manage to reproduce the bug with Godot 3.2 beta 1, then try older alpha builds. -.. warning:: +Warning: + For bisecting regressions, don't use patch releases such as Godot 3.1.2. Instead, use the minor version's first release like Godot 3.1. This is @@ -55,7 +56,8 @@ system offers a built-in command for this: `git bisect`. This makes the process semi-automated as you only have to build the engine, run it and try to reproduce the bug. -.. note:: +Note: + Before bisecting a regression, you need to set up a build environment to compile Godot from source. To do so, read the @@ -138,7 +140,8 @@ regression appeared. Write this commit hash as a comment to the GitHub issue you've bisected. This will help in solving the issue. Thanks again for contributing to Godot :) -.. note:: +Note: + You can read the full documentation on `git bisect` `here ( https://git-scm.com/docs/git-bisect )`. diff --git a/community/contributing/building_the_manual.md b/community/contributing/building_the_manual.md index 680c45c..771586b 100644 --- a/community/contributing/building_the_manual.md +++ b/community/contributing/building_the_manual.md @@ -21,7 +21,8 @@ install all these tools. It comes pre-installed with `Python ( https://www.python.org/ )`. Ensure that you install and use Python 3. Here are the commands to clone the repository and then install all requirements. -.. note:: You may need to write `python3 -m pip` (Unix) or `py -m pip` (Windows) instead of `pip3`. +Note: + You may need to write `python3 -m pip` (Unix) or `py -m pip` (Windows) instead of `pip3`. If both approaches fail, `check that you have pip3 installed ( https://pip.pypa.io/en/stable/installation/ )`. .. code:: sh @@ -69,7 +70,8 @@ In case you of a `MemoryError` or `EOFError`, you can remove the `classes/` folder and run `make` again. This will drop the class references from the final HTML documentation but will keep the rest intact. -.. note:: If you delete the `classes/` folder, do not use `git add .` when +Note: + If you delete the `classes/` folder, do not use `git add .` when working on a pull request or the whole `classes/` folder will be removed when you commit. See `#3157 ( https://github.com/godotengine/godot-docs/issues/3157 )` for more diff --git a/community/contributing/class_reference_writing_guidelines.md b/community/contributing/class_reference_writing_guidelines.md index e5cfc78..d83eccd 100644 --- a/community/contributing/class_reference_writing_guidelines.md +++ b/community/contributing/class_reference_writing_guidelines.md @@ -7,7 +7,8 @@ This page explains how to write the class reference. You will learn where to write new descriptions for the classes, methods, and properties for Godot's built-in node types. -.. seealso:: +See also: + To learn to submit your changes to the Godot project using the Git version control system, see `doc_updating_the_class_reference`. @@ -94,7 +95,8 @@ reference. The folder contains an XML file for each class. The XML lists the constants and methods you will find in the class reference. Godot generates and updates the XML automatically. -.. note:: For some modules in the engine's source code, you'll find the XML +Note: + For some modules in the engine's source code, you'll find the XML files in the `modules//doc_classes/` directory instead. Edit it using your favorite text editor. If you use a code editor, make sure diff --git a/community/contributing/code_style_guidelines.md b/community/contributing/code_style_guidelines.md index 06ebb97..f222065 100644 --- a/community/contributing/code_style_guidelines.md +++ b/community/contributing/code_style_guidelines.md @@ -33,7 +33,8 @@ not introducing trailing whitespace or space-based indentation, you should be fine. If you plan to contribute regularly however, we strongly advise that you setup clang-format locally to check and automatically fix all your commits. -.. warning:: Godot's code style should *not* be applied to third-party code, +Warning: + Godot's code style should *not* be applied to third-party code, i.e. that is included in Godot's source tree but was not written specifically for our project. Such code usually come from different upstream projects with their own style guides (or lack @@ -47,7 +48,8 @@ setup clang-format locally to check and automatically fix all your commits. `/* clang-format off */` and `/* clang-format on */` to tell clang-format to ignore a chunk of code. -.. seealso:: +See also: + These guidelines only cover code formatting. See `doc_cpp_usage_guidelines` for a list of language features that are permitted in pull requests. diff --git a/community/contributing/content_guidelines.md b/community/contributing/content_guidelines.md index be5c2d9..e117289 100644 --- a/community/contributing/content_guidelines.md +++ b/community/contributing/content_guidelines.md @@ -29,7 +29,8 @@ Writing complete and accessible documentation information about a feature and how it works, it doesn't exist to them. We should ensure that we cover everything Godot does. -.. note:: +Note: + When adding or updating an engine feature, the documentation team needs to know about it. Contributors should open an issue on the `godot-docs` repository @@ -46,7 +47,8 @@ guide to solving problems they encounter. For example, instead of writing the heading "Signals", consider writing "Reacting to changes with signals". The second title makes it clear what the purpose of signals is. -.. note:: +Note: + Long section titles lead to long entries in the side menu, which can make navigation cumbersome. Try to keep headings five words long or less. @@ -83,7 +85,8 @@ concept. What new terms did you need to learn? What confused you? What was the hardest to grasp? You will want users to review your work, and we recommend you practice explaining the feature before writing about it. -.. note:: +Note: + Having programming foundations is a pre-requisite to use a complex engine like Godot. Talking about variables, functions, or classes is acceptable. diff --git a/community/contributing/contributing_to_the_documentation.md b/community/contributing/contributing_to_the_documentation.md index de1be68..4634884 100644 --- a/community/contributing/contributing_to_the_documentation.md +++ b/community/contributing/contributing_to_the_documentation.md @@ -6,7 +6,8 @@ Contributing to the documentation This guide explains how to contribute to Godot's documentation, be it by writing or reviewing pages. -.. seealso:: +See also: + If you want to translate pages or the class reference from English to other languages, read `doc_editor_and_docs_localization`. @@ -19,12 +20,14 @@ files in the `godot-docs GitHub repository ( https://github.com/godotengine/godot-docs )`_. Modifying those pages in a pull request triggers a rebuild of the online documentation upon merging. -.. seealso:: For details on Git usage and the pull request workflow, please +See also: + For details on Git usage and the pull request workflow, please refer to the `doc_pr_workflow` page. Most of what it describes regarding the main godotengine/godot repository is also valid for the docs repository. -.. warning:: The class reference's source files are in the `Godot engine +Warning: + The class reference's source files are in the `Godot engine repository ( https://github.com/godotengine/godot )`_. We generate the `Godot API ( toc-class-ref )` section of this documentation from them. If you want to update the description of a class, its @@ -67,7 +70,8 @@ edited here.** They are automatically generated from Godot’s `XML class reference ( https://github.com/godotengine/godot/tree/master/doc/classes )`. See `doc_updating_the_class_reference` for details. -.. seealso:: To build the manual and test changes on your computer, see +See also: + To build the manual and test changes on your computer, see `doc_building_the_manual`. Editing pages online @@ -153,7 +157,9 @@ Sphinx uses specific reST comments to do specific operations, like defining the table of contents (`.. toctree::`) or cross-referencing pages. Check the `official Sphinx documentation ( https://www.sphinx-doc.org/en/stable/index.html )` for more details. To learn -how to use Sphinx directives like `.. note::` or `.. seealso::`, check out +how to use Sphinx directives like `Note: +` or `See also: +`, check out the `Sphinx directives documentation ( https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html )`. diff --git a/community/contributing/cpp_usage_guidelines.md b/community/contributing/cpp_usage_guidelines.md index ce77f35..7ca9843 100644 --- a/community/contributing/cpp_usage_guidelines.md +++ b/community/contributing/cpp_usage_guidelines.md @@ -22,7 +22,8 @@ To get your pull request merged, it needs to follow the C++ usage guidelines outlined here. Of course, you can use features not allowed here in your own C++ modules or GDNative scripts. -.. note:: +Note: + Prior to Godot 4.0, the C++ standard used throughout the codebase was C++03, with a handful of C++14 extensions. If you are contributing a pull request @@ -33,7 +34,8 @@ modules or GDNative scripts. generally favor small libraries instead of larger solutions. See also `doc_best_practices_for_engine_contributors`. -.. seealso:: +See also: + See `doc_code_style_guidelines` for formatting guidelines. @@ -60,7 +62,8 @@ This means that pull requests should **not** use `std::string`, can be used as an alternative (ask core developers first). - Use `Array` instead of `std::array`. -.. note:: +Note: + Godot also has a List datatype (which is a linked list). While List is already used in the codebase, it typically performs worse than other datatypes like Vector @@ -100,7 +103,8 @@ pull request. To follow the existing style, please use standard `#ifdef`-based include guards instead of `#pragma once` in new files. -.. seealso:: +See also: + See `doc_code_style_guidelines_header_includes` for guidelines on sorting includes in C++ and Objective-C files. diff --git a/community/contributing/docs_writing_guidelines.md b/community/contributing/docs_writing_guidelines.md index 6c0cf2e..066e6f7 100644 --- a/community/contributing/docs_writing_guidelines.md +++ b/community/contributing/docs_writing_guidelines.md @@ -26,13 +26,15 @@ There are 3 rules to describe classes: 2. Mention what methods return if it's useful 3. Use "if true" to describe booleans -.. note:: +Note: + A technical writer's job is to pack as much information as possible into the smallest and clearest sentences possible. These guidelines will help you work towards that goal. -.. seealso:: +See also: + See the `content guidelines ( doc_content_guidelines )` for information on the types of documentation you can write in the official documentation. @@ -535,6 +537,7 @@ heavier images, consider using a lossy compressor like `pngquant ( https://pngquant.org/ )`_. With it, almost no image quality is lost during compression. -.. note:: +Note: + The program pngquant must be installed locally as it's not available in Squoosh. diff --git a/community/contributing/documentation_guidelines.md b/community/contributing/documentation_guidelines.md index 7de4247..2483764 100644 --- a/community/contributing/documentation_guidelines.md +++ b/community/contributing/documentation_guidelines.md @@ -20,18 +20,21 @@ The HTML (or PDF and EPUB) documentation is generated from the .rst files in a pull request and getting it merged will trigger a rebuild of the online documentation. -.. seealso:: For details on Git usage and the pull request workflow, please +See also: + For details on Git usage and the pull request workflow, please refer to the `doc_pr_workflow` page. Most of what it describes regarding the main godotengine/godot repository is also valid for the docs repository. -.. warning:: The class reference's source files are in the `Godot engine repository +Warning: + The class reference's source files are in the `Godot engine repository ( https://github.com/godotengine/godot )`_. We generate the `Godot API ( toc-class-ref )` section of this documentation from them. If you want to update the description of a class, its methods, or properties, read `doc_updating_the_class_reference`. -.. warning:: If you want to edit the **API reference**, please note that it +Warning: + If you want to edit the **API reference**, please note that it should *not* be done in the godot-docs repository. Instead, you should edit the `doc/classes/*` XML files of Godot's main repository. These files are then later used to generate the diff --git a/community/contributing/editor_and_docs_localization.md b/community/contributing/editor_and_docs_localization.md index 225c21a..82ca118 100644 --- a/community/contributing/editor_and_docs_localization.md +++ b/community/contributing/editor_and_docs_localization.md @@ -54,7 +54,8 @@ as an example) to find the list of all languages: ![](img/l10n_01_language_list.png) -.. seealso:: +See also: + Feel free to consult Weblate's own documentation on the `translation workflow ( https://docs.weblate.org/en/latest/user/translating.html )` for @@ -190,7 +191,8 @@ used with the `location:` token, e.g. `location:nodes_and_scenes.rst`): ![](img/l10n_06_browse_by_location.png) -.. note:: +Note: + When a given source string is used in multiple source locations, they will all be concatenated into one. For example, the above @@ -243,7 +245,8 @@ The editor translations originate from C++ strings, and may use: Scene '%s' is currently being edited.↵ Changes will only take effect when reloaded. -.. note:: +Note: + Only logical order of the characters matters, in the right-to-left text, format specifiers may be displayed as `s%`. @@ -290,7 +293,8 @@ external links, etc. Here are some examples:: Save the scene. Click Scene -> Save, or press :kbd:`Ctrl + S` on Windows/Linux or :kbd:`Cmd + S` on macOS. -.. seealso:: +See also: + See Sphinx's `reStructured Text primer ( https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html )` for a quick overview of the markup language you may find in source strings. @@ -325,7 +329,8 @@ translate the name of the variable which holds the result (`red = ...`). Note also that in the XML, each line is a paragraph, so you should not add line breaks if they are not part of the original translation. -.. seealso:: +See also: + See our documentation for class reference writers for the `list of BBCode-like tags ( doc_class_reference_writing_guidelines_bbcode )` which are used @@ -348,7 +353,8 @@ Once you are done with a series of edits, use the "Upload translation" item in that same menu and select your file. Choose "Add as translation" for the file upload mode. -.. note:: +Note: + If a significant amount of time has passed between your download of the PO file and the upload of the edited version, there is a risk to overwrite the @@ -378,7 +384,8 @@ This part is not handled via Weblate, but directly on the `godot-docs-l10n ( https://github.com/godotengine/godot-docs-l10n )`_ Git repository where the documentation translations are synced from Weblate. -.. note:: +Note: + The workflow is not the most straightforward and requires some knowledge of Git. We plan to work on a simplified Web tool which could be used to manage diff --git a/community/contributing/pr_workflow.md b/community/contributing/pr_workflow.md index 84189cc..a448eb5 100644 --- a/community/contributing/pr_workflow.md +++ b/community/contributing/pr_workflow.md @@ -29,7 +29,8 @@ The `repository on GitHub ( https://github.com/godotengine/godot )`_ is a `Git ( https://git-scm.com )`_ code repository together with an embedded issue tracker and PR system. -.. note:: If you are contributing to the documentation, its repository can +Note: + If you are contributing to the documentation, its repository can be found `here ( https://github.com/godotengine/godot-docs )`_. The Git version control system is the tool used to keep track of successive @@ -42,7 +43,8 @@ contributions (although it's tolerated for small fixes or documentation changes) as it enforces one commit per file and per modification, which quickly leads to PRs with an unreadable Git history (especially after peer review). -.. seealso:: The first sections of Git's "Book" are a good introduction to +See also: + The first sections of Git's "Book" are a good introduction to the tool's philosophy and the various commands you need to master in your daily workflow. You can read them online on the `Git SCM ( https://git-scm.com/book/en/v2 )`_ website. @@ -87,7 +89,8 @@ repository (in Git speak, the *origin remote*). If you haven't already, download Git from `its website ( https://git-scm.com )`_ if you're using Windows or macOS, or install it through your package manager if you're using Linux. -.. note:: If you are on Windows, open Git Bash to type commands. macOS and Linux users +Note: + If you are on Windows, open Git Bash to type commands. macOS and Linux users can use their respective terminals. To clone your fork from GitHub, use the following command: @@ -96,7 +99,8 @@ To clone your fork from GitHub, use the following command: $ git clone https://github.com/USERNAME/godot -.. note:: In our examples, the "$" character denotes the command line prompt +Note: + In our examples, the "$" character denotes the command line prompt on typical UNIX shells. It is not part of the command and should not be typed. @@ -123,7 +127,8 @@ You only need to do the above steps once, as long as you keep that local `godot` folder (which you can move around if you want, the relevant metadata is hidden in its `.git` subfolder). -.. note:: *Branch it, pull it, code it, stage it, commit, push it, rebase +Note: + *Branch it, pull it, code it, stage it, commit, push it, rebase it... technologic.* This bad take on Daft Punk's *Technologic* shows the general @@ -218,7 +223,8 @@ we all do the first few times), you can abort the rebase with `git rebase --abor You will then be back to the original state of your branch before calling `git pull --rebase`. -.. note:: If you omit the `--rebase` argument, you will instead create a merge +Note: + If you omit the `--rebase` argument, you will instead create a merge commit which tells Git what to make of the two distinct branches. If any conflicts arise, they would be resolved all at once via this merge commit. @@ -454,7 +460,8 @@ upstream `master` branch, which you can do with: $ git rebase -i upstream/master -.. note:: Referencing branches in Git is a bit tricky due to the distinction +Note: + Referencing branches in Git is a bit tricky due to the distinction between remote and local branches. Here, `upstream/master` (with a `/`) is a local branch which has been pulled from the `upstream` remote's `master` branch. diff --git a/community/contributing/testing_pull_requests.md b/community/contributing/testing_pull_requests.md index e0a050d..a04ae0f 100644 --- a/community/contributing/testing_pull_requests.md +++ b/community/contributing/testing_pull_requests.md @@ -18,7 +18,8 @@ You can download pull request builds from GitHub Actions. Since only signed in users may download builds directly from GitHub Actions, the procedure varies depending on whether you have a GitHub account or not. -.. note:: +Note: + Due to a GitHub Actions limitation, builds are only available for 90 days after the pull request was last updated. If you still wish to try a diff --git a/community/contributing/updating_the_class_reference.md b/community/contributing/updating_the_class_reference.md index 71804fa..de33bad 100644 --- a/community/contributing/updating_the_class_reference.md +++ b/community/contributing/updating_the_class_reference.md @@ -17,7 +17,8 @@ the `godot-docs repository ( https://github.com/godotengine/godot-docs/ )`_ or comment on an existing issue. Doing so lets others know you're already taking care of a given class. -.. seealso:: +See also: + You can find the writing guidelines for the class reference `here ( doc_class_reference_writing_guidelines )`. @@ -30,7 +31,8 @@ taking care of a given class. This guide is also available as a `video tutorial on YouTube ( https://www.youtube.com/watch?v=5jeHXxeX-JY )`_. -.. seealso:: +See also: + Not sure which class to contribute to? Take a look at the class reference's completion status `here ( https://godotengine.github.io/doc-status/ )`_. @@ -39,15 +41,18 @@ You can find the source files for the class reference in Godot's GitHub repository: `doc/classes/ ( https://github.com/godotengine/godot/tree/master/doc/classes )`_. -.. note:: For some modules in the engine's source code, you'll find the XML +Note: + For some modules in the engine's source code, you'll find the XML files in the `modules/( module_name>/doc_classes/` directory instead. -.. warning:: Always edit the API reference through these source XML files. Do +Warning: + Always edit the API reference through these source XML files. Do not edit the generated `.rst` files `in the online documentation ( toc-class-ref )`, hosted in the `godot-docs ( https://github.com/godotengine/godot-docs )`_ repository. -.. warning:: +Warning: + Unless you make minor changes, like fixing a typo, we do not recommend using the GitHub web editor to edit the class reference's XML. diff --git a/community/contributing/ways_to_contribute.md b/community/contributing/ways_to_contribute.md index 3ce2595..7d722c1 100644 --- a/community/contributing/ways_to_contribute.md +++ b/community/contributing/ways_to_contribute.md @@ -88,7 +88,8 @@ A good place to start is by searching for issues tagged as `good first issue ( https://github.com/godotengine/godot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 )`_ on GitHub. -.. seealso:: Technical details about the PR workflow are outlined in a +See also: + Technical details about the PR workflow are outlined in a specific section, `doc_pr_workflow`. Details about the code style guidelines and the `clang-format` @@ -108,7 +109,8 @@ has a `proposal system ( https://github.com/godotengine/godot-proposals )`_. Its usage is encouraged to plan changes and discuss them with the community. Implementation details can also be discussed with other contributors on the `Godot Contributors Chat ( https://chat.godotengine.org/ )`_. -.. note:: Proposals are only required when working on an enhancement or a new feature. +Note: + Proposals are only required when working on an enhancement or a new feature. Bug reports are sufficient for fixing issues. Testing and reporting issues diff --git a/development/compiling/compiling_for_android.md b/development/compiling/compiling_for_android.md index c0ac135..cd412f9 100644 --- a/development/compiling/compiling_for_android.md +++ b/development/compiling/compiling_for_android.md @@ -4,7 +4,8 @@ Compiling for Android ===================== -.. seealso:: +See also: + This page describes how to compile Android export template binaries from source. If you're looking to export your project to Android instead, read `doc_exporting_for_android`. @@ -39,7 +40,8 @@ For compiling under Windows, Linux or macOS, the following is required: - You can download a build from `ojdkbuild ( https://github.com/ojdkbuild/ojdkbuild )`_. -.. seealso:: To get the Godot source code for compiling, see +See also: + To get the Godot source code for compiling, see `doc_getting_source`. For a general overview of SCons usage for Godot, see @@ -69,11 +71,13 @@ Setting up the buildsystem tools/bin/sdkmanager --sdk_root=( android_sdk_path> "platform-tools" "build-tools;30.0.3" "platforms;android-29" "cmdline-tools;latest" "cmake;3.10.2.4988404" -.. seealso:: To set the environment variable on Windows, press :kbd:`Windows + R`, type +See also: + To set the environment variable on Windows, press :kbd:`Windows + R`, type "control system", then click on **Advanced system settings** in the left pane, then click on **Environment variables** on the window that appears. -.. seealso:: To set the environment variable on Linux or macOS, use +See also: + To set the environment variable on Linux or macOS, use `export ANDROID_SDK_ROOT=/path/to/android-sdk` where `/path/to/android-sdk` points to the root of the SDK directories. diff --git a/development/compiling/compiling_for_ios.md b/development/compiling/compiling_for_ios.md index 643f8e8..33ba6db 100644 --- a/development/compiling/compiling_for_ios.md +++ b/development/compiling/compiling_for_ios.md @@ -4,7 +4,8 @@ Compiling for iOS ================= -.. seealso:: +See also: + This page describes how to compile iOS export template binaries from source. If you're looking to export your project to iOS instead, read `doc_exporting_for_ios`. @@ -17,7 +18,8 @@ Requirements to run `scons` in a terminal when installed). - Xcode 10.0 (or later) with the iOS (10.0) SDK and the command line tools. -.. seealso:: To get the Godot source code for compiling, see +See also: + To get the Godot source code for compiling, see `doc_getting_source`. For a general overview of SCons usage for Godot, see diff --git a/development/compiling/compiling_for_osx.md b/development/compiling/compiling_for_osx.md index c88f6a4..f357094 100644 --- a/development/compiling/compiling_for_osx.md +++ b/development/compiling/compiling_for_osx.md @@ -4,7 +4,8 @@ Compiling for macOS =================== -.. note:: +Note: + This page describes how to compile macOS editor and export template binaries from source. If you're looking to export your project to macOS instead, read `doc_exporting_for_macos`. @@ -20,7 +21,8 @@ For compiling under macOS, the following is required: (or the more lightweight Command Line Tools for Xcode). - *Optional* - `yasm ( https://yasm.tortall.net/ )`_ (for WebM SIMD optimizations). -.. note:: If you have `Homebrew ( https://brew.sh/ )`_ installed, you can easily +Note: + If you have `Homebrew ( https://brew.sh/ )`_ installed, you can easily install SCons and yasm using the following command:: brew install scons yasm @@ -34,7 +36,8 @@ For compiling under macOS, the following is required: sudo port install scons yasm -.. seealso:: To get the Godot source code for compiling, see +See also: + To get the Godot source code for compiling, see `doc_getting_source`. For a general overview of SCons usage for Godot, see @@ -62,7 +65,8 @@ If all goes well, the resulting binary executable will be placed in the runs without any dependencies. Executing it will bring up the project manager. -.. note:: If you want to use separate editor settings for your own Godot builds +Note: + If you want to use separate editor settings for your own Godot builds and official releases, you can enable `doc_data_paths_self_contained_mode` by creating a file called `._sc_` or `_sc_` in the `bin/` folder. diff --git a/development/compiling/compiling_for_uwp.md b/development/compiling/compiling_for_uwp.md index 739a32c..4b1d499 100644 --- a/development/compiling/compiling_for_uwp.md +++ b/development/compiling/compiling_for_uwp.md @@ -4,7 +4,8 @@ Compiling for Universal Windows Platform ======================================== -.. seealso:: +See also: + This page describes how to compile UWP export template binaries from source. If you're looking to export your project to UWP instead, read `doc_exporting_for_uwp`. @@ -20,7 +21,8 @@ Requirements `ms_master` (default) branch. Keep it in a path without spaces to avoid problems. -.. note:: The ANGLE repo by Microsoft has been discontinued and the +Note: + The ANGLE repo by Microsoft has been discontinued and the `ms_master` branch has been cleared out. As a temporary workaround however, it is still possible to @@ -30,7 +32,8 @@ Requirements This page will eventually be updated in the future to reflect the new build instructions. -.. seealso:: To get the Godot source code for compiling, see +See also: + To get the Godot source code for compiling, see `doc_getting_source`. For a general overview of SCons usage for Godot, see diff --git a/development/compiling/compiling_for_web.md b/development/compiling/compiling_for_web.md index c4cb203..65d9132 100644 --- a/development/compiling/compiling_for_web.md +++ b/development/compiling/compiling_for_web.md @@ -3,7 +3,8 @@ Compiling for the Web ===================== -.. seealso:: +See also: + This page describes how to compile HTML5 editor and export template binaries from source. If you're looking to export your project to HTML5 instead, read `doc_exporting_for_web`. @@ -18,7 +19,8 @@ To compile export templates for the Web, the following is required: - `Python 3.5+ ( https://www.python.org/ )`. - `SCons 3.0+ ( https://www.scons.org )` build system. -.. seealso:: To get the Godot source code for compiling, see +See also: + To get the Godot source code for compiling, see `doc_getting_source`. For a general overview of SCons usage for Godot, see diff --git a/development/compiling/compiling_for_windows.md b/development/compiling/compiling_for_windows.md index 05a0b89..ab2ee5d 100644 --- a/development/compiling/compiling_for_windows.md +++ b/development/compiling/compiling_for_windows.md @@ -4,7 +4,8 @@ Compiling for Windows ===================== -.. seealso:: +See also: + This page describes how to compile Windows editor and export template binaries from source. If you're looking to export your project to Windows instead, read `doc_exporting_for_windows`. @@ -25,12 +26,14 @@ For compiling under Windows, the following is required: - `SCons ( https://www.scons.org/ )`_ build system. Using the latest release is recommended, especially for proper support of recent Visual Studio releases. -.. note:: If you have `Scoop ( https://scoop.sh/ )`_ installed, you can easily +Note: + If you have `Scoop ( https://scoop.sh/ )`_ installed, you can easily install MinGW and other dependencies using the following command:: scoop install gcc python scons make -.. note:: If you have `MSYS2 ( https://www.msys2.org/ )`_ installed, you can easily +Note: + If you have `MSYS2 ( https://www.msys2.org/ )`_ installed, you can easily install MinGW and other dependencies using the following command:: pacman -S mingw-w64-x86_64-python3-pip mingw-w64-x86_64-gcc \ @@ -39,7 +42,8 @@ For compiling under Windows, the following is required: For each MSYS2 MinGW subsystem, you should then run `pip3 install scons` in its shell. -.. seealso:: To get the Godot source code for compiling, see +See also: + To get the Godot source code for compiling, see `doc_getting_source`. For a general overview of SCons usage for Godot, see @@ -95,7 +99,8 @@ Refer to `doc_getting_source` for detailed instructions. The tutorial will assume from now on that you placed the source code in `C:\godot`. -.. warning:: +Warning: + To prevent slowdowns caused by continuous virus scanning during compilation, add the Godot source folder to the list of exceptions in your antivirus @@ -141,7 +146,8 @@ In general, it is OK to have at least as many threads compiling Godot as you have cores in your CPU, if not one or two more. Feel free to add the `-j` option to any SCons command you see below. -.. note:: When compiling with multiple CPU threads, SCons may warn about +Note: + When compiling with multiple CPU threads, SCons may warn about pywin32 being missing. You can safely ignore this warning. If all goes well, the resulting binary executable will be placed in @@ -153,7 +159,8 @@ your CPU architecture, but this can be overridden using `bits=64` or This executable file contains the whole engine and runs without any dependencies. Running it will bring up the Project Manager. -.. note:: If you are compiling Godot for production use, then you can +Note: + If you are compiling Godot for production use, then you can make the final executable smaller and faster by adding the SCons option `target=release_debug`. @@ -162,7 +169,8 @@ dependencies. Running it will bring up the Project Manager. As link-time optimization is a memory-intensive process, this will require about 7 GB of available RAM while compiling. -.. note:: If you want to use separate editor settings for your own Godot builds +Note: + If you want to use separate editor settings for your own Godot builds and official releases, you can enable `doc_data_paths_self_contained_mode` by creating a file called `._sc_` or `_sc_` in the `bin/` folder. @@ -185,7 +193,8 @@ the `vsproj=yes` parameter, like this:: You will be able to open Godot's source in a Visual Studio solution now, and able to build Godot using Visual Studio's **Build** button. -.. seealso:: See `doc_configuring_an_ide_vs` for further details. +See also: + See `doc_configuring_an_ide_vs` for further details. Cross-compiling for Windows from other operating systems -------------------------------------------------------- diff --git a/development/compiling/compiling_for_x11.md b/development/compiling/compiling_for_x11.md index 14da218..41726c8 100644 --- a/development/compiling/compiling_for_x11.md +++ b/development/compiling/compiling_for_x11.md @@ -4,7 +4,8 @@ Compiling for X11 (Linux, \*BSD) ================================ -.. seealso:: +See also: + This page describes how to compile Linux editor and export template binaries from source. If you're looking to export your project to Linux instead, read `doc_exporting_for_linux`. @@ -30,7 +31,8 @@ required: - *Optional* - libudev (build with `udev=yes`). - *Optional* - yasm (for WebM SIMD optimizations). -.. seealso:: To get the Godot source code for compiling, see +See also: + To get the Godot source code for compiling, see `doc_getting_source`. For a general overview of SCons usage for Godot, see @@ -116,7 +118,8 @@ If all goes well, the resulting binary executable will be placed in the runs without any dependencies. Executing it will bring up the project manager. -.. note:: +Note: + If you wish to compile using Clang rather than GCC, use this command: @@ -127,7 +130,8 @@ manager. Using Clang appears to be a requirement for OpenBSD, otherwise fonts would not build. -.. note:: If you are compiling Godot for production use, then you can +Note: + If you are compiling Godot for production use, then you can make the final executable smaller and faster by adding the SCons option `target=release_debug`. @@ -136,7 +140,8 @@ manager. As link-time optimization is a memory-intensive process, this will require about 7 GB of available RAM while compiling. -.. note:: If you want to use separate editor settings for your own Godot builds +Note: + If you want to use separate editor settings for your own Godot builds and official releases, you can enable `doc_data_paths_self_contained_mode` by creating a file called `._sc_` or `_sc_` in the `bin/` folder. @@ -162,7 +167,8 @@ use:: Building export templates ------------------------- -.. warning:: Linux binaries usually won't run on distributions that are +Warning: + Linux binaries usually won't run on distributions that are older than the distribution they were built on. If you wish to distribute binaries that work on most distributions, you should build them on an old distribution such as Ubuntu 16.04. diff --git a/development/compiling/compiling_with_mono.md b/development/compiling/compiling_with_mono.md index 24809f3..b90c828 100644 --- a/development/compiling/compiling_with_mono.md +++ b/development/compiling/compiling_with_mono.md @@ -165,7 +165,8 @@ The data directory is a dependency for Godot binaries built with the Mono module enabled. It contains important files for the correct functioning of Godot. It must be distributed together with the Godot executable. -.. note:: The information below doesn't apply for Android, iOS and WASM, +Note: + The information below doesn't apply for Android, iOS and WASM, as there is no data directory for these platforms. Export templates diff --git a/development/compiling/compiling_with_script_encryption_key.md b/development/compiling/compiling_with_script_encryption_key.md index 1ad2d38..b3bf480 100644 --- a/development/compiling/compiling_with_script_encryption_key.md +++ b/development/compiling/compiling_with_script_encryption_key.md @@ -14,7 +14,8 @@ optimized and without symbols, it would take some effort to find it. For this to work, you need to build the export templates from source, with that same key. -.. warning:: +Warning: + This will **not** work if you use official, precompiled export templates. It is absolutely **required** to compile your own export templates to use diff --git a/development/compiling/introduction_to_the_buildsystem.md b/development/compiling/introduction_to_the_buildsystem.md index b6427fc..9dcc43c 100644 --- a/development/compiling/introduction_to_the_buildsystem.md +++ b/development/compiling/introduction_to_the_buildsystem.md @@ -201,13 +201,15 @@ directory paths containing such modules: scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules" -.. note:: +Note: + If there's any custom module with the exact directory name as a built-in module, the engine will only compile the custom one. This logic can be used to override built-in module implementations. -.. seealso:: +See also: + `doc_custom_modules_in_c++` @@ -256,7 +258,8 @@ source to initialize any SCons build options passed via the command line: You can also disable some of the builtin modules before compiling, saving some time it takes to build the engine. See `doc_optimizing_for_size` page for more details. -.. seealso:: +See also: + You can use the online `Godot build options generator ( https://godot-build-options-generator.github.io/ )` @@ -270,7 +273,8 @@ line option, both overriding the default build configuration: scons profile=path/to/custom.py -.. note:: Build options set from the file can be overridden by the command line +Note: + Build options set from the file can be overridden by the command line options. It's also possible to override the options conditionally: diff --git a/development/compiling/optimizing_for_size.md b/development/compiling/optimizing_for_size.md index c710b24..bffe857 100644 --- a/development/compiling/optimizing_for_size.md +++ b/development/compiling/optimizing_for_size.md @@ -42,7 +42,8 @@ The downside is that crash backtraces will no longer provide accurate informatio `C++ profilers ( doc_using_cpp_profilers )` will also no longer be able to display function names (this does not affect the built-in GDScript profiler). -.. note:: +Note: + The above command will not work on Windows binaries compiled with MSVC and platforms such as Android and HTML5. Instead, pass `debug_symbols=no` @@ -212,6 +213,7 @@ following: module_websocket_enabled = "no" module_xatlas_unwrap_enabled = "no" -.. seealso:: +See also: + `doc_overriding_build_options`. diff --git a/development/cpp/common_engine_methods_and_macros.md b/development/cpp/common_engine_methods_and_macros.md index 588d807..b8d93e7 100644 --- a/development/cpp/common_engine_methods_and_macros.md +++ b/development/cpp/common_engine_methods_and_macros.md @@ -92,7 +92,8 @@ To insert placeholders in localizable strings, wrap the localization macro in a String file_path = "example.txt"; vformat(TTR("Couldn't open \"%s\" for reading."), file_path); -.. note:: +Note: + When using `vformat()` and a translation macro together, always wrap the translation macro in `vformat()`, not the other way around. Otherwise, the @@ -135,7 +136,8 @@ use this snippet: This will print the time spent between the `begin` declaration and the `end` declaration. -.. note:: +Note: + You may have to `#include "core/os/os.h"` if it's not present already. @@ -175,13 +177,15 @@ Error macros Godot features many error macros to make error reporting more convenient. -.. warning:: +Warning: + Conditions in error macros work in the **opposite** way of GDScript's built-in `assert()` function. An error is reached if the condition inside evaluates to `true`, not `false`. -.. note:: +Note: + Only variants with custom messages are documented here, as these should always be used in new contributions. Make sure the custom message provided @@ -235,7 +239,8 @@ Godot features many error macros to make error reporting more convenient. CRASH_NOW_MSG("Can't predict the future! Aborting."); -.. seealso:: +See also: + See `core/error_macros.h ( https://github.com/godotengine/godot/blob/3.x/core/error_macros.h )` in Godot's codebase for more information about each error macro. diff --git a/development/cpp/configuring_an_ide/clion.md b/development/cpp/configuring_an_ide/clion.md index 25b5dec..5118998 100644 --- a/development/cpp/configuring_an_ide/clion.md +++ b/development/cpp/configuring_an_ide/clion.md @@ -65,7 +65,8 @@ You will first need to `compile godot yourself ( https://docs.godotengine.org/en You can now use the debugging tools from CLion. -.. note:: +Note: + If you run the binary without any arguments, you will only debug the project manager window. Don't forget to add the `--path path/to/your/godot/project` argument to debug a project. diff --git a/development/cpp/configuring_an_ide/qt_creator.md b/development/cpp/configuring_an_ide/qt_creator.md index 96e0fe1..a68cf9c 100644 --- a/development/cpp/configuring_an_ide/qt_creator.md +++ b/development/cpp/configuring_an_ide/qt_creator.md @@ -29,7 +29,8 @@ Importing the project :figclass: figure-w480 :align: center -.. note:: You can change this configuration later by right-clicking on your project +Note: + You can change this configuration later by right-clicking on your project and selecting the **Edit Files...** option. .. figure:: img/qtcreator-edit-files-menu.png) @@ -65,7 +66,8 @@ Importing the project :figclass: figure-w480 :align: center -.. note:: If the build fails with `Could not start process "scons"`, it can mean that `scons` +Note: + If the build fails with `Could not start process "scons"`, it can mean that `scons` is not in your `PATH` environment variable. In this case, you'll have to specify the full path to the SCons binary. diff --git a/development/cpp/configuring_an_ide/visual_studio.md b/development/cpp/configuring_an_ide/visual_studio.md index 05580f9..5b0b73f 100644 --- a/development/cpp/configuring_an_ide/visual_studio.md +++ b/development/cpp/configuring_an_ide/visual_studio.md @@ -20,7 +20,8 @@ with the solution file, it can be generated using SCons. or by using the **Open a project or solution** option inside of the Visual Studio. - Use the **Build** top menu to build the project. -.. warning:: Visual Studio must be configured with the C++ package. It can be selected +Warning: + Visual Studio must be configured with the C++ package. It can be selected in the intaller: .. figure:: img/vs_1_install_cpp_package.png) diff --git a/development/cpp/configuring_an_ide/visual_studio_code.md b/development/cpp/configuring_an_ide/visual_studio_code.md index d2368ad..a99c779 100644 --- a/development/cpp/configuring_an_ide/visual_studio_code.md +++ b/development/cpp/configuring_an_ide/visual_studio_code.md @@ -166,7 +166,8 @@ js Windows An example of a filled out `launch.json`. -.. note:: +Note: + Due to sporadic performance issues, it is recommended to use LLDB over GDB on Unix-based systems. Make sure that the `CodeLLDB extension ( https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb )`_ diff --git a/development/cpp/configuring_an_ide/xcode.md b/development/cpp/configuring_an_ide/xcode.md index ca53a9c..75db76d 100644 --- a/development/cpp/configuring_an_ide/xcode.md +++ b/development/cpp/configuring_an_ide/xcode.md @@ -43,7 +43,8 @@ Importing the project :figclass: figure-w480 :align: center -.. note:: Name it something so you know not to compile with this target (e.g. `GodotXcodeIndex`). +Note: + Name it something so you know not to compile with this target (e.g. `GodotXcodeIndex`). - For this target open the **Build Settings** tab and look for **Header Search Paths**. - Set **Header Search Paths** to the absolute path to the Godot root folder. You need to diff --git a/development/cpp/custom_modules_in_cpp.md b/development/cpp/custom_modules_in_cpp.md index b558b6b..09b5120 100644 --- a/development/cpp/custom_modules_in_cpp.md +++ b/development/cpp/custom_modules_in_cpp.md @@ -221,7 +221,8 @@ You can then zip it and share the module with everyone else. When building for every platform (instructions in the previous sections), your module will be included. -.. note:: There is a parameter limit of 5 in C++ modules for things such +Note: + There is a parameter limit of 5 in C++ modules for things such as subclasses. This can be raised to 13 by including the header file `core/method_bind_ext.gen.inc`. @@ -241,12 +242,14 @@ You can now use your newly created module from any script: The output will be `60`. -.. seealso:: The previous Summator example is great for small, custom modules, +See also: + The previous Summator example is great for small, custom modules, but what if you want to use a larger, external library? Refer to `doc_binding_to_external_libraries` for details about binding to external libraries. -.. warning:: If your module is meant to be accessed from the running project +Warning: + If your module is meant to be accessed from the running project (not just from the editor), you must also recompile every export template you plan to use, then specify the path to the custom template in each export preset. Otherwise, you'll get errors when @@ -294,21 +297,24 @@ modules, similar to the following: The build system shall detect all modules under the `../modules` directory and compile them accordingly, including our "summator" module. -.. warning:: +Warning: + Any path passed to `custom_modules` will be converted to an absolute path internally as a way to distinguish between custom and built-in modules. It means that things like generating module documentation may rely on a specific path structure on your machine. -.. seealso:: +See also: + `Introduction to the buildsystem - Custom modules build option ( doc_buildsystem_custom_modules )`. Improving the build system for development ------------------------------------------ -.. warning:: +Warning: + This shared library support is not designed to support distributing a module to other users without recompiling the engine. For that purpose, use @@ -375,7 +381,8 @@ during runtime with the `LD_LIBRARY_PATH` environment variable: export LD_LIBRARY_PATH="$PWD/bin/" ./bin/godot* -.. note:: +Note: + You have to `export` the environment variable. Otherwise, you won't be able to run your project from the editor. diff --git a/development/cpp/object_class.md b/development/cpp/object_class.md index ca55069..88ad023 100644 --- a/development/cpp/object_class.md +++ b/development/cpp/object_class.md @@ -3,7 +3,8 @@ Object class ============ -.. seealso:: +See also: + This page describes the C++ implementation of objects in Godot. Looking for the Object class reference? `Have a look here.` diff --git a/development/cpp/using_cpp_profilers.md b/development/cpp/using_cpp_profilers.md index 37ecdba..2c5e547 100644 --- a/development/cpp/using_cpp_profilers.md +++ b/development/cpp/using_cpp_profilers.md @@ -6,7 +6,8 @@ Using C++ profilers To optimize Godot's performance, you need to know what to optimize first. To this end, profilers are useful tools. -.. note:: +Note: + There is a built-in GDScript profiler in the editor, but using C++ profiler may be useful in cases where the GDScript profiler is not accurate enough @@ -40,7 +41,8 @@ compile binaries with the following SCons options: It is possible to run a profiler on less optimized builds (e.g. `target=debug` without LTO), but results will naturally be less representative of real world conditions. -.. warning:: +Warning: + Do *not* strip debugging symbols on the binaries using the `strip` command after compiling the binaries. Otherwise, you will no longer get useful @@ -55,7 +57,8 @@ This will exit Godot just after it finished starting. The `--quit` option works with `--editor`, `--project-manager` or `--path Save, or press :kbd:`Ctrl + S` on Windows/Linux or :kbd:`Cmd + S` on macOS. -.. note:: For this project, we will be following the Godot naming conventions. +Note: + For this project, we will be following the Godot naming conventions. - **GDScript**: Classes (nodes) use PascalCase, variables and functions use snake_case, and constants use ALL_CAPS (See diff --git a/getting_started/first_2d_game/03.coding_the_player.md b/getting_started/first_2d_game/03.coding_the_player.md index 629bffa..605d79e 100644 --- a/getting_started/first_2d_game/03.coding_the_player.md +++ b/getting_started/first_2d_game/03.coding_the_player.md @@ -15,12 +15,14 @@ Script" button: In the script settings window, you can leave the default settings alone. Just click "Create": -.. note:: If you're creating a C# script or other languages, select the language +Note: + If you're creating a C# script or other languages, select the language from the `language` drop down menu before hitting create. ![](img/attach_node_window.png) -.. note:: If this is your first time encountering GDScript, please read +Note: + If this is your first time encountering GDScript, please read `doc_scripting` before continuing. Start by declaring the member variables this object will need: @@ -90,7 +92,8 @@ Your input map tab should look like this: Click the "Close" button to close the project settings. -.. note:: +Note: + We only mapped one key to each input action, but you can map multiple keys, joystick buttons, or mouse buttons to the same input action. @@ -166,7 +169,8 @@ gdscript GDScript Click "Play Scene" (:kbd:`F6`, :kbd:`Cmd + R` on macOS) and confirm you can move the player around the screen in all directions. -.. warning:: If you get an error in the "Debugger" panel that says +Warning: + If you get an error in the "Debugger" panel that says `Attempt to call function 'play' in base 'null instance' on a null instance` @@ -198,7 +202,8 @@ gdscript GDScript $AnimatedSprite.flip_v = velocity.y > 0 ``` -.. Note:: The boolean assignments in the code above are a common shorthand for +Note: + The boolean assignments in the code above are a common shorthand for programmers. Since we're doing a comparison test (boolean) and also *assigning* a boolean value, we can do both at the same time. Consider this code versus the one-line boolean assignment above: @@ -277,7 +282,8 @@ Each time an enemy hits the player, the signal is going to be emitted. We need to disable the player's collision so that we don't trigger the `hit` signal more than once. -.. Note:: Disabling the area's collision shape can cause an error if it happens +Note: + Disabling the area's collision shape can cause an error if it happens in the middle of the engine's collision processing. Using `set_deferred()` tells Godot to wait to disable the shape until it's safe to do so. diff --git a/getting_started/first_2d_game/04.creating_the_enemy.md b/getting_started/first_2d_game/04.creating_the_enemy.md index c666ecd..eaf5b2f 100644 --- a/getting_started/first_2d_game/04.creating_the_enemy.md +++ b/getting_started/first_2d_game/04.creating_the_enemy.md @@ -84,7 +84,8 @@ We then need to pick a random number between `0` and `2` to select one of these names from the list (array indices start at `0`). `randi() % n` selects a random integer between `0` and `n-1`. -.. note:: You must use `randomize()` if you want your sequence of "random" +Note: + You must use `randomize()` if you want your sequence of "random" numbers to be different every time you run the scene. We're going to use `randomize()` in our `Main` scene, so we won't need it here. diff --git a/getting_started/first_2d_game/06.heads_up_display.md b/getting_started/first_2d_game/06.heads_up_display.md index 111ae9f..bb207ad 100644 --- a/getting_started/first_2d_game/06.heads_up_display.md +++ b/getting_started/first_2d_game/06.heads_up_display.md @@ -53,7 +53,8 @@ Once you've done this on the `ScoreLabel`, you can click the down arrow next to the Font property and choose "Copy", then "Paste" it in the same place on the other two Control nodes. -.. note:: **Anchors and Margins:** `Control` nodes have a position and size, +Note: + **Anchors and Margins:** `Control` nodes have a position and size, but they also have anchors and margins. Anchors define the origin - the reference point for the edges of the node. Margins update automatically when you move or resize a control node. They represent @@ -139,7 +140,8 @@ This function is called when the player loses. It will show "Game Over" for 2 seconds, then return to the title screen and, after a brief pause, show the "Start" button. -.. note:: When you need to pause for a brief time, an alternative to using a +Note: + When you need to pause for a brief time, an alternative to using a Timer node is to use the SceneTree's `create_timer()` function. This can be very useful to add delays such as in the above code, where we want to wait some time before showing the "Start" button. diff --git a/getting_started/first_2d_game/index.md b/getting_started/first_2d_game/index.md index ccb71c8..aef3bf0 100644 --- a/getting_started/first_2d_game/index.md +++ b/getting_started/first_2d_game/index.md @@ -12,7 +12,8 @@ game of your own, like the image below. You will learn how the Godot editor works, how to structure a project, and build a 2D game. -.. note:: This project is an introduction to the Godot engine. It assumes that +Note: + This project is an introduction to the Godot engine. It assumes that you have some programming experience already. If you're new to programming entirely, you should start here: `doc_scripting`. diff --git a/getting_started/first_3d_game/01.game_setup.md b/getting_started/first_3d_game/01.game_setup.md index 5e9e822..4c5db79 100644 --- a/getting_started/first_3d_game/01.game_setup.md +++ b/getting_started/first_3d_game/01.game_setup.md @@ -77,7 +77,8 @@ the Z axis. |image9| -.. note:: +Note: + In 3D, translation and size units are in meters. The box's total size is twice its extents: `60` by `60` meters on the ground plane and `2` @@ -110,7 +111,8 @@ and click and drag down on the Y axis. It's the green arrow in the move gizmo. |image13| -.. note:: +Note: + If you can't see the 3D object manipulator like on the image above, ensure the *Select Mode* is active in the toolbar above the view. @@ -122,7 +124,8 @@ viewport tells you how much you're translating the node. |image15| -.. note:: +Note: + Moving the *Ground* node down moves both children along with it. Ensure you move the *Ground* node, **not** the *MeshInstance* or the diff --git a/getting_started/first_3d_game/02.player_input.md b/getting_started/first_3d_game/02.player_input.md index 61a730b..f0ba25a 100644 --- a/getting_started/first_3d_game/02.player_input.md +++ b/getting_started/first_3d_game/02.player_input.md @@ -21,7 +21,8 @@ environment, but instead of being controlled by the physics engine, you dictate their movement. You will see how we use the node's unique features when we code the jump and squash mechanics. -.. seealso:: +See also: + To learn more about the different physics node types, see the `doc_physics_introduction`. @@ -40,7 +41,8 @@ This should instantiate the model as a child of *Pivot*. You can rename it to |image2| -.. note:: +Note: + The `.glb` files contain 3D scene data based on the open-source GLTF 2.0 specification. They're a modern and powerful alternative to a proprietary format diff --git a/getting_started/first_3d_game/03.player_movement_code.md b/getting_started/first_3d_game/03.player_movement_code.md index 61c320b..afc2764 100644 --- a/getting_started/first_3d_game/03.player_movement_code.md +++ b/getting_started/first_3d_game/03.player_movement_code.md @@ -34,7 +34,8 @@ These are common properties for a moving body. The `velocity` is a 3D vector combining a speed with a direction. Here, we define it as a property because we want to update and reuse its value across frames. -.. note:: +Note: + The values are quite different from 2D code because distances are in meters. While in 2D, a thousand units (pixels) may only correspond to half of your @@ -68,7 +69,8 @@ virtual function. Like `_process()`, it allows you to update the node every frame, but it's designed specifically for physics-related code like moving a kinematic or rigid body. -.. seealso:: +See also: + To learn more about the difference between `_process()` and `_physics_process()`, see `doc_idle_and_physics_processing`. @@ -103,7 +105,8 @@ In this case, we also get the *Pivot* node and call its `look_at()` method. This method takes a position in space to look at in global coordinates and the up direction. In this case, we can use the `Vector3.UP` constant. -.. note:: +Note: + A node's local coordinates, like `translation`, are relative to their parent. Global coordinates are relative to the world's main axes you can see diff --git a/getting_started/first_3d_game/04.mob_scene.md b/getting_started/first_3d_game/04.mob_scene.md index 0efd0bc..2edef3e 100644 --- a/getting_started/first_3d_game/04.mob_scene.md +++ b/getting_started/first_3d_game/04.mob_scene.md @@ -58,7 +58,8 @@ Once a monster leaves the screen, we don't need it anymore, so we can delete it. Godot has a node that detects when objects leave the screen, *VisibilityNotifier*, and we're going to use it to destroy our mobs. -.. note:: +Note: + When you keep instancing an object in games, there's a technique you can use to avoid the cost of creating and destroying instances all the time diff --git a/getting_started/first_3d_game/05.spawning_mobs.md b/getting_started/first_3d_game/05.spawning_mobs.md index dcc3b9d..58f90fd 100644 --- a/getting_started/first_3d_game/05.spawning_mobs.md +++ b/getting_started/first_3d_game/05.spawning_mobs.md @@ -126,7 +126,8 @@ the *Add Point* tool, the icon with the green "+" sign. |image16| -.. note:: You can hover any icon to see a tooltip describing the tool. +Note: + You can hover any icon to see a tooltip describing the tool. Click in the center of each cylinder to create a point. Then, click the *Close Curve* icon in the toolbar to close the path. If any point is a bit off, you can diff --git a/getting_started/first_3d_game/06.jump_and_squash.md b/getting_started/first_3d_game/06.jump_and_squash.md index a02522f..6225837 100644 --- a/getting_started/first_3d_game/06.jump_and_squash.md +++ b/getting_started/first_3d_game/06.jump_and_squash.md @@ -94,7 +94,8 @@ These settings mean the monsters will move through one another. If you want the monsters to collide with and slide against each other, turn on the "enemies" mask. -.. note:: +Note: + The mobs don't need to mask the "world" layer because they only move on the XZ plane. We don't apply any gravity to them by design. @@ -233,7 +234,8 @@ information about where and how the collision occurred. For example, we use its `collider` property to check if we collided with a "mob" by calling `is_in_group()` on it: `collision.collider.is_in_group("mob")`. -.. note:: +Note: + The method `is_in_group()` is available on every `Node( Node )`. diff --git a/getting_started/first_3d_game/08.score_and_replay.md b/getting_started/first_3d_game/08.score_and_replay.md index 088420a..019dfb9 100644 --- a/getting_started/first_3d_game/08.score_and_replay.md +++ b/getting_started/first_3d_game/08.score_and_replay.md @@ -57,7 +57,8 @@ of how all the built-in UI widgets will look with your theme resource. By default, a theme only has one property, the *Default Font*. -.. seealso:: +See also: + You can add more properties to the theme resource to design complex user interfaces, but that is beyond the scope of this series. To learn more about @@ -151,7 +152,8 @@ placeholder `%s`. When using this feature, Godot automatically converts values to text, which is convenient to output text in labels or using the `print()` function. -.. seealso:: +See also: + You can learn more about string formatting here: `doc_gdscript_printf`. @@ -160,7 +162,8 @@ increase. |image11| -.. note:: +Note: + In a complex game, you may want to completely separate your user interface from the game world. In that case, you would not keep track of the score on diff --git a/getting_started/first_3d_game/09.adding_animations.md b/getting_started/first_3d_game/09.adding_animations.md index a609147..3a779a5 100644 --- a/getting_started/first_3d_game/09.adding_animations.md +++ b/getting_started/first_3d_game/09.adding_animations.md @@ -105,7 +105,8 @@ seconds by dragging it on the timeline. |image14| -.. note:: +Note: + A lecture on the principles of animation is beyond the scope of this tutorial. Just note that you don't want to time and space everything evenly. @@ -159,7 +160,8 @@ Your animation should look something like this. |image21| -.. note:: +Note: + Animations update the properties of the animated nodes every frame, overriding initial values. If we directly animated the *Player* node, it diff --git a/getting_started/first_3d_game/index.md b/getting_started/first_3d_game/index.md index 1091185..f129b00 100644 --- a/getting_started/first_3d_game/index.md +++ b/getting_started/first_3d_game/index.md @@ -33,7 +33,8 @@ steps. If you're an experienced programmer, you can browse the complete demo's source code here: `Squash the Creep source code ( https://github.com/GDQuest/godot-3d-dodge-the-creeps/ )`. -.. note:: +Note: + You can follow this series without having done the 2D one. However, if you're new to game development, we recommend you to start with 2D. 3D game diff --git a/getting_started/introduction/first_look_at_the_editor.md b/getting_started/introduction/first_look_at_the_editor.md index 3862b83..558ecb2 100644 --- a/getting_started/introduction/first_look_at_the_editor.md +++ b/getting_started/introduction/first_look_at_the_editor.md @@ -12,7 +12,8 @@ First look at Godot's editor This page will give you a brief overview of Godot's interface. We're going to look at the different main screens and docks to help you situate yourself. -.. seealso:: For a comprehensive breakdown of the editor's interface and how to +See also: + For a comprehensive breakdown of the editor's interface and how to use it, see the `Editor manual ( toc-learn-editor )`. The Project manager @@ -109,7 +110,8 @@ options related to the 3D view. ![](img/editor_intro_3d_viewport_perspective.png) -.. note:: Read `doc_introduction_to_3d` for more detail about the **3D +Note: + Read `doc_introduction_to_3d` for more detail about the **3D main screen**. The **Script screen** is a complete code editor with a debugger, rich @@ -122,7 +124,8 @@ and assets to use in your projects. ![](img/editor_intro_workspace_assetlib.png) -.. seealso:: You can learn more about the asset library in +See also: + You can learn more about the asset library in `doc_what_is_assetlib`. Integrated class reference diff --git a/getting_started/introduction/godot_design_philosophy.md b/getting_started/introduction/godot_design_philosophy.md index 7a4d13e..b25c0aa 100644 --- a/getting_started/introduction/godot_design_philosophy.md +++ b/getting_started/introduction/godot_design_philosophy.md @@ -109,7 +109,8 @@ game code. See `The Godot editor is a Godot game`_ below. manage states and transitions visually.* -.. warning:: +Warning: + `Godot 4.0 will remove VisualScript from core entirely. ( https://godotengine.org/article/godot-4-will-discontinue-visual-scripting )` As a result, creating new projects using visual scripting in Godot is not recommended. @@ -136,7 +137,8 @@ On the other hand, an open codebase means you can **learn from and extend the engine** to your heart's content. You can also debug games easily, as Godot will print errors with a stack trace, even if they come from the engine itself. -.. note:: +Note: + This **does not affect the work you do with Godot** in any way: there's no strings attached to the engine or anything you make with it. @@ -177,7 +179,8 @@ in the editor. This lets you import and export plugins, create plugins like custom level editors, or create scripts with the same nodes and API you use in your projects. -.. note:: +Note: + The editor is fully written in C++ and is statically compiled into the binary. This means you can't import it as a typical project that would have a diff --git a/getting_started/introduction/introduction_to_godot.md b/getting_started/introduction/introduction_to_godot.md index 63aea1c..74c88b6 100644 --- a/getting_started/introduction/introduction_to_godot.md +++ b/getting_started/introduction/introduction_to_godot.md @@ -21,7 +21,8 @@ on desktop or mobile, as well as on the web. You can also create console games with it, although you either need strong programming skills or a developer to port the game for you. -.. note:: The Godot team can't provide an open-source console export due to the +Note: + The Godot team can't provide an open-source console export due to the licensing terms imposed by console manufacturers. Regardless of the engine you use, though, releasing games on consoles is always a lot of work. You can read more on that here: `doc_consoles`. @@ -87,7 +88,8 @@ Software Development Kits (SDK) in the engine. Of course, you can also directly add modules and features to the engine, as it's completely free and open-source. -.. seealso:: These are the five officially supported programming languages. The +See also: + These are the five officially supported programming languages. The community maintains support for many more. For more information, see `GDNative third-party bindings ( doc_what_is_gdnative_third_party_bindings )`. @@ -108,7 +110,8 @@ courseware`_ from Harvard University. It's a great free course that will teach you everything you need to know to be off to a good start. It will save you countless hours and hurdles learning any game engine afterward. -.. note:: In CS50, you will learn multiple programming languages. Don't be +Note: + In CS50, you will learn multiple programming languages. Don't be afraid of that: programming languages have many similarities. The skills you learn with one language transfer well to others. diff --git a/getting_started/introduction/key_concepts_overview.md b/getting_started/introduction/key_concepts_overview.md index 1d04e51..aecd280 100644 --- a/getting_started/introduction/key_concepts_overview.md +++ b/getting_started/introduction/key_concepts_overview.md @@ -43,7 +43,8 @@ nodes. It is made of a `KinematicBody2D` node named "Character", a `Sprite`, a `Camera2D`, and a `CollisionShape2D`. -.. note:: The node names end with "2D" because this is a 2D scene. Their 3D +Note: + The node names end with "2D" because this is a 2D scene. Their 3D counterpart have names that end with "3D". Notice how nodes and scenes look the same in the editor. When you save a tree of @@ -75,7 +76,8 @@ flexibility in how you structure your scenes. ![](img/key_concepts_signals.png) -.. note:: Signals are Godot's version of the *observer* pattern. You can read +Note: + Signals are Godot's version of the *observer* pattern. You can read more about it here: https://gameprogrammingpatterns.com/observer.html diff --git a/getting_started/introduction/learning_new_features.md b/getting_started/introduction/learning_new_features.md index 57f8185..42c24e2 100644 --- a/getting_started/introduction/learning_new_features.md +++ b/getting_started/introduction/learning_new_features.md @@ -51,7 +51,8 @@ A class reference's page tells you: 4. Links to manual pages further detailing the class. -.. note:: If the manual or class reference is missing or has insufficient +Note: + If the manual or class reference is missing or has insufficient information, please open an Issue in the official `godot-docs ( https://github.com/godotengine/godot-docs/issues )`_ GitHub repository to report it. diff --git a/getting_started/step_by_step/instancing.md b/getting_started/step_by_step/instancing.md index 9022c94..8d621a1 100644 --- a/getting_started/step_by_step/instancing.md +++ b/getting_started/step_by_step/instancing.md @@ -111,7 +111,8 @@ There is more to instances. With this feature, you can: and making a change to the Ball node there. Upon saving, all instances of the Ball in the project will see their values update. -.. note:: Changing a property on an instance always overrides values from the +Note: + Changing a property on an instance always overrides values from the corresponding packed scene. Let's try this. Open `Ball.tscn` and select the Ball node. In the Inspector on @@ -149,7 +150,8 @@ property to the value in the saved scene. Rerun the game and notice how this ball now falls much faster than the others. -.. note:: If you change a value on the `PhysicsMaterial` of one instance, it +Note: + If you change a value on the `PhysicsMaterial` of one instance, it will affect all the others. This is because `PhysicsMaterial` is a resource, and resources are shared between instances. To make a resource unique for one instance, right-click on it in the Inspector diff --git a/getting_started/step_by_step/nodes_and_scenes.md b/getting_started/step_by_step/nodes_and_scenes.md index 13024ee..434cfd2 100644 --- a/getting_started/step_by_step/nodes_and_scenes.md +++ b/getting_started/step_by_step/nodes_and_scenes.md @@ -143,7 +143,8 @@ button to save it as "Label.tscn". ![](img/nodes_and_scenes_11_save_scene_as.png) -.. note:: The Save Scene As dialog, like other file dialogs in the editor, only +Note: + The Save Scene As dialog, like other file dialogs in the editor, only allows you to save files inside the project. The `res://` path at the top of the window represents the project's root directory and stands for "resource path". For more information about file paths in @@ -155,7 +156,8 @@ The application should open in a new window and display the text "Hello World". Close the window or press :kbd:`F8` to quit the running scene. -.. note:: +Note: + If this doesn't immediately work and you have a hiDPI display on at least one of your monitors, go to Project -> Project Settings -> Display -> @@ -182,7 +184,8 @@ Label.tscn. The demo should run again. Moving forward, every time you run the project, Godot will use this scene as a starting point. -.. note:: The editor saves the main scene's path in a project.godot file in your +Note: + The editor saves the main scene's path in a project.godot file in your project's directory. While you can edit this text file directly to change project settings, you can also use the "Project -> Project Settings" window to do so. diff --git a/getting_started/step_by_step/scripting_first_script.md b/getting_started/step_by_step/scripting_first_script.md index c548bc2..6c610d9 100644 --- a/getting_started/step_by_step/scripting_first_script.md +++ b/getting_started/step_by_step/scripting_first_script.md @@ -25,10 +25,12 @@ The equivalent C# code has been included in another tab for convenience. ![](img/scripting_first_script_rotating_godot.gif) -.. seealso:: To learn more about GDScript, its keywords, and its syntax, head to +See also: + To learn more about GDScript, its keywords, and its syntax, head to the `GDScript reference( doc_gdscript )`. -.. seealso:: To learn more about C#, head to the `C# basics ( doc_c_sharp )` page. +See also: + To learn more about C#, head to the `C# basics ( doc_c_sharp )` page. Project setup ------------- @@ -59,7 +61,8 @@ and drag the file `icon.png)` from the FileSystem dock onto the Texture slot. ![](img/scripting_first_script_setting_texture.png) -.. note:: +Note: + You can create Sprite nodes automatically by dragging and dropping images on the viewport. @@ -101,14 +104,16 @@ our script will get access to all the properties and functions of the Sprite node, including classes it extends, like `Node2D`, `CanvasItem`, and `Node`. -.. note:: In GDScript, if you omit the line with the `extends` keyword, your +Note: + In GDScript, if you omit the line with the `extends` keyword, your class will implicitly extend `Reference`, which Godot uses to manage your application's memory. Inherited properties include the ones you can see in the Inspector dock, like our node's `texture`. -.. note:: +Note: + By default, the Inspector displays a node's properties in "Title Case", with capitalized words separated by a space. In GDScript code, these properties @@ -138,7 +143,8 @@ Let's break it down. The `func` keyword defines a new function named `_init()` on every object or node upon creating it in memory, if you define this function. -.. note:: GDScript is an indent-based language. The tab at the start of the line +Note: + GDScript is an indent-based language. The tab at the start of the line that says `print()` is necessary for the code to work. If you omit it or don't indent a line correctly, the editor will highlight it in red and display the following error message: "Indented block expected". @@ -171,7 +177,8 @@ but before functions. Every node instance with this script attached to it will have its own copy of the `speed` and `angular_speed` properties. -.. note:: Angles in Godot work in radians by default, +Note: + Angles in Godot work in radians by default, but you have built-in functions and properties available if you prefer to calculate angles in degrees instead. @@ -181,7 +188,8 @@ If you define it in any class that extends the Node class, like Sprite, Godot will call the function every frame and pass it an argument named `delta`, the time elapsed since the last frame. -.. note:: +Note: + Games work by rendering many images per second, each called a frame, and they do so in a loop. We measure the rate at which a game produces images in @@ -208,7 +216,8 @@ function's name and arguments it takes in parentheses. A colon ends the definition, and the indented blocks that follow are the function's content or instructions. -.. note:: Notice how `_process()`, like `_init()`, starts with a leading +Note: + Notice how `_process()`, like `_init()`, starts with a leading underscore. By convention, Godot's virtual functions, that is to say, built-in functions you can override to communicate with the engine, start with an underscore. @@ -260,7 +269,8 @@ Run the scene to see the Godot head run in circles. ![](img/scripting_first_script_rotating_godot.gif) -.. note:: Moving a node like that does not take into account colliding with +Note: + Moving a node like that does not take into account colliding with walls or the floor. In `doc_your_first_2d_game`, you will learn another approach to moving objects while detecting collisions. diff --git a/getting_started/step_by_step/scripting_languages.md b/getting_started/step_by_step/scripting_languages.md index 5579400..7703d7e 100644 --- a/getting_started/step_by_step/scripting_languages.md +++ b/getting_started/step_by_step/scripting_languages.md @@ -37,7 +37,8 @@ everything in GDScript or C#. It's your call. We provide this flexibility to answer the needs of different game projects and developers. -.. warning:: +Warning: + `Godot 4.0 will remove VisualScript from core entirely. ( https://godotengine.org/article/godot-4-will-discontinue-visual-scripting )` As a result, creating new projects using visual scripting in Godot is not recommended. @@ -94,7 +95,8 @@ GDScript looks like Python as you structure your code blocks using indentations, but it doesn't work the same way in practice. It's inspired by multiple languages, including Squirrel, Lua, and Python. -.. note:: +Note: + Why don't we use Python or Lua directly? @@ -121,7 +123,8 @@ thanks to a generous donation from Microsoft. C# offers a good tradeoff between performance and ease of use, although you should be aware of its garbage collector. -.. note:: You must use the Mono edition of the Godot editor to script in C#. You +Note: + You must use the Mono edition of the Godot editor to script in C#. You can download it on the Godot website's `download ( https://godotengine.org/download/ )`_ page. @@ -130,7 +133,8 @@ you can use any third-party .NET library or framework in Godot, as well as any Common Language Infrastructure-compliant programming language, such as F#, Boo, or ClojureCLR. However, C# is the only officially supported .NET option. -.. note:: GDScript code itself doesn't execute as fast as compiled C# or C++. +Note: + GDScript code itself doesn't execute as fast as compiled C# or C++. However, most script code calls functions written with fast algorithms in C++ code inside the engine. In many cases, writing gameplay logic in GDScript, C#, or C++ won't have a significant impact on @@ -139,7 +143,8 @@ or ClojureCLR. However, C# is the only officially supported .NET option. VisualScript ~~~~~~~~~~~~ -.. warning:: +Warning: + `Godot 4.0 will remove VisualScript from core entirely. ( https://godotengine.org/article/godot-4-will-discontinue-visual-scripting )` As a result, creating new projects using visual scripting in Godot is not recommended. @@ -163,7 +168,8 @@ While it provides all the basic building blocks you need to code complete games, we do not recommend to use VisualScript this way. Programming everything with it is slow compared to using other programming languages. -.. seealso:: +See also: + For more information, see `Getting started with VisualScript ( doc_getting_started_visual_script )`. diff --git a/getting_started/step_by_step/scripting_player_input.md b/getting_started/step_by_step/scripting_player_input.md index ea422f3..ae3d801 100644 --- a/getting_started/step_by_step/scripting_player_input.md +++ b/getting_started/step_by_step/scripting_player_input.md @@ -60,7 +60,8 @@ The two actions we use above, "ui_left" and "ui_right", are predefined in every Godot project. They respectively trigger when the player presses the left and right arrows on the keyboard or left and right on a gamepad's D-pad. -.. note:: You can see and edit input actions in your project by going to Project +Note: + You can see and edit input actions in your project by going to Project -> Project Settings and clicking on the Input Map tab. Finally, we use the `direction` as a multiplier when we update the node's diff --git a/getting_started/step_by_step/signals.md b/getting_started/step_by_step/signals.md index ca68bfd..085ad22 100644 --- a/getting_started/step_by_step/signals.md +++ b/getting_started/step_by_step/signals.md @@ -25,7 +25,8 @@ For example, you might have a life bar on the screen that represents the player’s health. When the player takes damage or uses a healing potion, you want the bar to reflect the change. To do so, in Godot, you would use signals. -.. note:: As mentioned in the introduction, signals are Godot's version of the +Note: + As mentioned in the introduction, signals are Godot's version of the observer pattern. You can learn more about it here: https://gameprogrammingpatterns.com/observer.html @@ -113,7 +114,8 @@ method, a function that Godot will call when the Button emits the signal. The editor generates one for you. By convention, we name these callback methods "_on_NodeName_signal_name". Here, it'll be "_on_Button_pressed". -.. note:: +Note: + When connecting signals via the editor's Node dock, you can use two modes. The simple one only allows you to connect to nodes that have a @@ -224,7 +226,8 @@ We need to do two operations to connect the nodes via code: 1. Get a reference to the Timer from the Sprite. 2. Call the Timer's `connect()` method. -.. note:: To connect to a signal via code, you need to call the `connect()` +Note: + To connect to a signal via code, you need to call the `connect()` method of the node you want to listen to. In this case, we want to listen to the Timer's "timeout" signal. @@ -315,7 +318,8 @@ gdscript GDScript Custom signals -------------- -.. note:: This section is a reference on how to define and use your own signals, +Note: + This section is a reference on how to define and use your own signals, and does not build upon the project created in previous lessons. You can define custom signals in a script. Say, for example, that you want to @@ -333,7 +337,8 @@ gdscript GDScript var health = 10 ``` -.. note:: As signals represent events that just occurred, we generally use an +Note: + As signals represent events that just occurred, we generally use an action verb in the past tense in their names. Your signals work the same way as built-in ones: they appear in the Node tab and @@ -363,7 +368,8 @@ gdscript GDScript signal health_changed(old_value, new_value) ``` -.. note:: +Note: + The signal arguments show up in the editor's node dock, and Godot can use them to generate callback functions for you. However, you can still emit any diff --git a/index.md b/index.md index c233f7d..c35d655 100644 --- a/index.md +++ b/index.md @@ -3,7 +3,8 @@ Godot Docs – *3.5* branch .. only:: not i18n - .. note:: Godot's documentation is available in various languages and versions. + Note: + Godot's documentation is available in various languages and versions. Expand the "Read the Docs" panel at the bottom of the sidebar to see the list. @@ -15,7 +16,8 @@ Godot Docs – *3.5* branch .. only:: i18n - .. note:: This documentation is translated from the `original English one + Note: + This documentation is translated from the `original English one ( https://docs.godotengine.org/en/latest )`_ by community members on `Weblate ( https://hosted.weblate.org/projects/godot-engine/godot-docs )`_. @@ -42,7 +44,8 @@ You can also `download an HTML copy ( https://nightly.link/godotengine/godot-doc for offline reading (updated every Monday). Extract the ZIP archive then open the top-level `index.html` in a web browser. -.. note:: Godot Engine is an open source project developed by a community of +Note: + Godot Engine is an open source project developed by a community of volunteers. The documentation team can always use your feedback and help to improve the tutorials and class reference. If you don't understand something, or cannot find what you diff --git a/tutorials/2d/2d_lights_and_shadows.md b/tutorials/2d/2d_lights_and_shadows.md index 1a35610..4f51a04 100644 --- a/tutorials/2d/2d_lights_and_shadows.md +++ b/tutorials/2d/2d_lights_and_shadows.md @@ -130,7 +130,8 @@ node, which is why we want the blob to be centered on its parent `Light`. ![](img/light_shadow_all_lights.png) -.. note:: The animations in the demo will not be covered here. See `doc_introduction_animation` +Note: + The animations in the demo will not be covered here. See `doc_introduction_animation` for information on creating animations. Right now the scene should look too bright. This is because all three lights are adding color to the scene. @@ -175,15 +176,18 @@ lines of the polygon can be seen: ![](img/light_shadow_cull_disabled.png) -.. note:: `Cull Mode` is set to `Disabled`. All three lines cast shadows. +Note: + `Cull Mode` is set to `Disabled`. All three lines cast shadows. ![](img/light_shadow_cull_clockwise.png) -.. note:: `Cull Mode` is set to `Clockwise`. Only the top and right lines cast shadows. +Note: + `Cull Mode` is set to `Clockwise`. Only the top and right lines cast shadows. ![](img/light_shadow_cull_counter_clockwise.png) -.. note:: `Cull Mode` is set to `Counter-Clockwise`. Only the bottom line casts a shadow. +Note: + `Cull Mode` is set to `Counter-Clockwise`. Only the bottom line casts a shadow. If `Closed` was set to `on` there would be an additional vertical line on the left which would cast a shadow as well. @@ -202,12 +206,14 @@ The demo uses PCF7. ![](img/light_shadow_normal.png) -.. note:: This is a shadow rendered with the demo's settings. `gradient length` is set +Note: + This is a shadow rendered with the demo's settings. `gradient length` is set to `1.3`, `filter smooth` is set to `11.1`, and `filter` is set to `PCF7`. ![](img/light_shadow_pcf13.png) -.. note:: `filter` is set to `PCF13`. Notice how the shadow becomes wider, this is because the +Note: + `filter` is set to `PCF13`. Notice how the shadow becomes wider, this is because the distance between samples is based on the variable `filter smooth`. In order to make use of filtering you need to set the `filter smooth` variable. @@ -217,14 +223,16 @@ forming between the samples. ![](img/light_shadow_filter30.png) -.. note:: `filter smooth` is set to `30`. +Note: + `filter smooth` is set to `30`. The different `Light` nodes in the demo use different values for filter smooth. Play around with it and see what you like. ![](img/light_shadow_filter0.png) -.. note:: `filter smooth` is set to `0`. +Note: + `filter smooth` is set to `0`. Lastly, there is the variable `gradient length`. For some smooth shadows it is preferable not to have the shadow start immediately on the object, as this produces a hard edge. The gradient length variable creates @@ -232,11 +240,13 @@ a smooth gradient to begin the shadow to reduce the effect of the hard edge. ![](img/light_shadow_grad0.png) -.. note:: `gradient length` is set to `0`. +Note: + `gradient length` is set to `0`. ![](img/light_shadow_grad10.png) -.. note:: `gradient length` is set to `10`. +Note: + `gradient length` is set to `10`. You will need to play around with the options a bit to find settings that suit your project. There is no right solution for everyone, which is why Godot provides so much flexibility. Just keep in mind that the higher `filter` diff --git a/tutorials/2d/2d_meshes.md b/tutorials/2d/2d_meshes.md index c23214c..ad270b8 100644 --- a/tutorials/2d/2d_meshes.md +++ b/tutorials/2d/2d_meshes.md @@ -10,7 +10,8 @@ In 3D, meshes are used to display the world. In 2D, they are rare as images are Godot's 2D engine is a pure two-dimensional engine, so it can't really display 3D meshes directly (although it can be done via `Viewport` and `ViewportTexture`). -.. seealso:: If you are interested in displaying 3D meshes on a 2D viewport, see the `doc_viewport_as_texture` tutorial. +See also: + If you are interested in displaying 3D meshes on a 2D viewport, see the `doc_viewport_as_texture` tutorial. 2D meshes are meshes that contain two-dimensional geometry (Z can be omitted or ignored) instead of 3D. You can experiment creating them yourself using `SurfaceTool` from code and displaying them in a `MeshInstance2D` node. diff --git a/tutorials/2d/2d_movement.md b/tutorials/2d/2d_movement.md index fb5bc74..9eaed59 100644 --- a/tutorials/2d/2d_movement.md +++ b/tutorials/2d/2d_movement.md @@ -75,7 +75,8 @@ its *length* to `1`, and multiply by the desired speed. .. tip:: If you've never used vector math before, or need a refresher, you can see an explanation of vector usage in Godot at `doc_vector_math`. -.. note:: +Note: + If the code above does nothing when you press the keys, double-check that you've set up input actions correctly as described in the diff --git a/tutorials/2d/2d_sprite_animation.md b/tutorials/2d/2d_sprite_animation.md index cedb4b7..ba80da2 100644 --- a/tutorials/2d/2d_sprite_animation.md +++ b/tutorials/2d/2d_sprite_animation.md @@ -16,7 +16,8 @@ animate a collection of individual images. Then we will animate a sprite sheet u with `AnimationPlayer` and the *Animation* property of `Sprite`. -.. note:: Art for the following examples by https://opengameart.org/users/ansimuz and by +Note: + Art for the following examples by https://opengameart.org/users/ansimuz and by https://opengameart.org/users/tgfcoder Individual images with AnimatedSprite @@ -36,7 +37,8 @@ with the following nodes: ![](img/2d_animation_tree1.png) -.. note:: The root node could also be `Area2D` or +Note: + The root node could also be `Area2D` or `RigidBody2D`. The animation will still be made in the same way. Once the animation is completed, you can assign a shape to the CollisionShape2D. See @@ -143,7 +145,8 @@ setting up your scene tree: ![](img/2d_animation_tree2.png) -.. note:: The root node could also be `Area2D` or +Note: + The root node could also be `Area2D` or `RigidBody2D`. The animation will still be made in the same way. Once the animation is completed, you can assign a shape to the CollisionShape2D. See @@ -204,7 +207,8 @@ gdscript GDScript _animation_player.stop() ``` -.. note:: If updating both an animation and a separate property at once +Note: + If updating both an animation and a separate property at once (for example, a platformer may update the sprite's `h_flip`/`v_flip` properties when a character turns while starting a 'turning' animation), it's important to keep in mind that `play()` isn't applied instantly. diff --git a/tutorials/2d/canvas_layers.md b/tutorials/2d/canvas_layers.md index 5a6338d..73f0fee 100644 --- a/tutorials/2d/canvas_layers.md +++ b/tutorials/2d/canvas_layers.md @@ -57,7 +57,8 @@ Here's a diagram of how it looks: CanvasLayers are independent of tree order, and they only depend on their layer number, so they can be instantiated when needed. -.. note:: CanvasLayers aren't necessary to control the drawing order of nodes. +Note: + CanvasLayers aren't necessary to control the drawing order of nodes. The standard way to ensuring that a node is correctly drawn 'in front' or 'behind' others is to manipulate the order of the nodes in the scene panel. Perhaps counterintuitively, the topmost nodes in the scene panel are drawn on *behind* lower ones in the viewport. 2d nodes also have a property for controlling their drawing order diff --git a/tutorials/2d/particle_systems_2d.md b/tutorials/2d/particle_systems_2d.md index 6b06cd3..63cf96b 100644 --- a/tutorials/2d/particle_systems_2d.md +++ b/tutorials/2d/particle_systems_2d.md @@ -356,5 +356,6 @@ Once you click "OK", the mask will be generated and set to the ParticlesMaterial All of the values within this section have been automatically generated by the "Load Emission Mask" menu, so they should generally be left alone. -.. note:: An image should not be added to `Point Texture` or `Color Texture` directly. +Note: + An image should not be added to `Point Texture` or `Color Texture` directly. The "Load Emission Mask" menu should always be used instead. diff --git a/tutorials/2d/using_tilemaps.md b/tutorials/2d/using_tilemaps.md index cfff501..cc13a91 100644 --- a/tutorials/2d/using_tilemaps.md +++ b/tutorials/2d/using_tilemaps.md @@ -239,7 +239,8 @@ adjacent to it is not "on". A total of 47 tiles would be needed to provide exactly one bitmask for each arrangement that this mode can test for. -.. note:: +Note: + Right-click an image and choose **Save image as…** to save it. diff --git a/tutorials/3d/3d_rendering_limitations.md b/tutorials/3d/3d_rendering_limitations.md index 101ebab..bf0c41d 100644 --- a/tutorials/3d/3d_rendering_limitations.md +++ b/tutorials/3d/3d_rendering_limitations.md @@ -3,7 +3,8 @@ 3D rendering limitations ======================== -.. seealso:: +See also: + In addition to the limitations below, mobile platforms have even more limitations on 3D rendering compared to desktop platforms. @@ -50,7 +51,8 @@ There are two main ways to alleviate banding: to be applied on your *materials*. This technique works even if your project is rendered in LDR, which means it will work when using the GLES2 renderer. -.. seealso:: +See also: + See `Banding in Games: A Noisy Rant ( http://loopit.dk/banding_in_games.pdf )` for more details about banding and ways to combat it. diff --git a/tutorials/3d/baked_lightmaps.md b/tutorials/3d/baked_lightmaps.md index 09ae8df..a5e7c08 100644 --- a/tutorials/3d/baked_lightmaps.md +++ b/tutorials/3d/baked_lightmaps.md @@ -73,7 +73,8 @@ final size of the lightmap texture (and, in consequence, the UV padding in the m The effect of setting this option is that all meshes within the scene will have their UV2 maps properly generated. -.. warning:: +Warning: + When reusing a mesh within a scene, keep in mind that UVs will be generated for the first instance found. If the mesh is re-used with different scales @@ -245,7 +246,8 @@ it is recommended to use lower quality settings at first. Then, once you are con with your scene's lighting setup, raise the quality settings and perform a "final" bake before exporting your project. -.. note:: +Note: + By default, the lightmap baker will use all the system's logical CPU cores to speed up baking. This can reduce system responsiveness. To preserve system diff --git a/tutorials/3d/csg_tools.md b/tutorials/3d/csg_tools.md index dda3228..baab92e 100644 --- a/tutorials/3d/csg_tools.md +++ b/tutorials/3d/csg_tools.md @@ -11,7 +11,8 @@ Level prototyping is one of the main uses of CSG in Godot. This technique allows users to create simple versions of most common shapes by combining primitives. Interior environments can be created by using inverted primitives. -.. note:: The CSG nodes in Godot are mainly intended for prototyping. There is +Note: + The CSG nodes in Godot are mainly intended for prototyping. There is no built-in support for UV mapping or editing 3D polygons (though extruded 2D polygons can be used with the CSGPolygon node). @@ -71,7 +72,8 @@ The `CSGPolygon` node extrude along a Polygon drawn in ![](img/csg_poly.png) -.. note:: The **Path** mode must be provided with a `Path` +Note: + The **Path** mode must be provided with a `Path` node to work. In the Path node, draw the path and the polygon in CSGPolygon will extrude along the given path. @@ -103,7 +105,8 @@ Every CSG node will first process its children nodes and their operations: union, intersection or subtraction, in tree order, and apply them to itself one after the other. -.. note:: In the interest of performance, make sure CSG geometry remains +Note: + In the interest of performance, make sure CSG geometry remains relatively simple, as complex meshes can take a while to process. If adding objects together (such as table and room objects), create them as separate CSG trees. Forcing too many objects in a single tree @@ -155,7 +158,8 @@ Adjust their placement to resemble a desk. ![](img/csg_desk.png) -.. note:: CSG nodes inside a CSGCombiner will only process their operation +Note: + CSG nodes inside a CSGCombiner will only process their operation within the combiner. Therefore, CSGCombiners are used to organize CSG nodes. @@ -185,7 +189,8 @@ spheres will cut a hole into the mattress. Try to re-parent the `pillow` node to the root `Spatial` node; the hole will disappear. -.. note:: This is to illustrate the effect of CSG processing order. +Note: + This is to illustrate the effect of CSG processing order. Since the root node is not a CSG node, the CSGCombiner nodes are the end of the operations; this shows the use of CSGCombiner to organize the CSG scene. @@ -256,7 +261,8 @@ nodes yet. Triplanar mapping is relatively slow, which usually restricts its usage to organic surfaces like terrain. Still, when prototyping, it can be used to quickly apply textures to CSG-based levels. -.. note:: If you need some textures for prototyping, Kenney made a +Note: + If you need some textures for prototyping, Kenney made a `set of CC0-licensed prototype textures ( https://kenney.nl/assets/prototype-textures )`. There are two ways to apply a material to a CSG node: diff --git a/tutorials/3d/gi_probes.md b/tutorials/3d/gi_probes.md index 507ec9e..59613af 100644 --- a/tutorials/3d/gi_probes.md +++ b/tutorials/3d/gi_probes.md @@ -6,7 +6,8 @@ Using GIProbe Introduction ------------ -.. note:: This feature is only available when using the GLES3 backend. +Note: + This feature is only available when using the GLES3 backend. `doc_baked_lightmaps` can be used as an alternative when using the GLES2 renderer. @@ -51,7 +52,8 @@ toolbar to begin the pre-baking process: ![](img/giprobe_bake.png) -.. warning:: +Warning: + Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a diff --git a/tutorials/3d/high_dynamic_range.md b/tutorials/3d/high_dynamic_range.md index 0bdd7b1..e19a4be 100644 --- a/tutorials/3d/high_dynamic_range.md +++ b/tutorials/3d/high_dynamic_range.md @@ -32,7 +32,8 @@ through a virtual camera. Here, our virtual camera would apply a particular camera rendering transform to the scene data, and the output would be ready for display on a particular display type. -.. note:: +Note: + Godot does not support high dynamic range *output* yet. It can only perform lighting in HDR and tonemap the result to a low dynamic range image. diff --git a/tutorials/3d/occluders.md b/tutorials/3d/occluders.md index da7c320..e381b4f 100644 --- a/tutorials/3d/occluders.md +++ b/tutorials/3d/occluders.md @@ -7,7 +7,8 @@ In addition to occlusion via `doc_rooms_and_portals`, Godot also has the ability Any object that is fully occluded by the shape (behind or in some cases inside) will be culled at runtime. They are designed to be simple to use and inexpensive at runtime, but the trade off is they may not be as effective at culling as `doc_rooms_and_portals`. Nevertheless they can still significantly boost performance in some situations. -.. note:: It is important to understand that geometric occluders work by testing the axis aligned bounding box (`AABB`) of the occludee against the occluder. The AABB must be *fully occluded* to be culled. The consequence of this is that smaller objects are more likely to be effectively culled than larger objects, and larger occluders tend to be much more effective than smaller ones. +Note: + It is important to understand that geometric occluders work by testing the axis aligned bounding box (`AABB`) of the occludee against the occluder. The AABB must be *fully occluded* to be culled. The consequence of this is that smaller objects are more likely to be effectively culled than larger objects, and larger occluders tend to be much more effective than smaller ones. A major advantage to Occluder nodes is that they are fully dynamic. For example if you place an occluder node as a child of a spaceship, it will move as you move the parent object. @@ -49,7 +50,8 @@ The polygon is a generalist occluder. It can be made to work well in almost all As with all geometric occluders, the key to success is to make them large. They do not have to match rendered geometry, and in many cases they will work better if you extend them past rendered geometry to make them as big as possible (without blocking legitimate lines of sight). The reason why they need to be large is that in general, they will only cull objects whose `AABB` is completely hidden by the polygon. For large objects to be culled, you will need large occluders. -.. note:: Like all occluders, polygons **can** overlap, and in many cases they will work better if you overlap them (they are more likely to cull objects on boundaries). +Note: + Like all occluders, polygons **can** overlap, and in many cases they will work better if you overlap them (they are more likely to cull objects on boundaries). Editing and details ~~~~~~~~~~~~~~~~~~~ @@ -82,7 +84,8 @@ The hole can be totally within the polygon (such as a window), abutting the edge - If the object to be culled is totally hidden by the polygon, it then looks to see whether it can be seen *through* the hole. If the object touches the hole, it is not culled, but if hidden by the polygon and not seen through the hole it is culled. -.. note:: Placing holes is usually far more convenient, and works faster and better at runtime, than creating lots of smaller OccluderShapePolygons. +Note: + Placing holes is usually far more convenient, and works faster and better at runtime, than creating lots of smaller OccluderShapePolygons. Hole Limits ^^^^^^^^^^^ diff --git a/tutorials/3d/portals/advanced_room_and_portal_usage.md b/tutorials/3d/portals/advanced_room_and_portal_usage.md index 13ee115..77c794c 100644 --- a/tutorials/3d/portals/advanced_room_and_portal_usage.md +++ b/tutorials/3d/portals/advanced_room_and_portal_usage.md @@ -97,7 +97,8 @@ The tent is a simple room inside a terrain room (which contains the ground, the ![](img/tent.png) -.. note:: To use internal rooms for buildings, it is usually a good idea to split the *interior* mesh of the building from the *exterior*. The exterior can be placed in the outer room (so it can be seen from outside, but not from the inside), and the interior should be placed in the interior room (so it only visible inside, or through the portal). +Note: + To use internal rooms for buildings, it is usually a good idea to split the *interior* mesh of the building from the *exterior*. The exterior can be placed in the outer room (so it can be seen from outside, but not from the inside), and the interior should be placed in the interior room (so it only visible inside, or through the portal). ![](img/tent_terrain.png) @@ -124,7 +125,8 @@ However, if we set this autoplace priority to `-1` for example, the autoplace wi This gives us a helpful extra bit of control for these kinds of situations, and makes the entire system much more flexible. -.. note:: As the default autoplace priority is `0`, you can't effectively force objects into RoomGroups with priority `0`. However there are plenty of priority values available so this should not be a problem in practice. +Note: + As the default autoplace priority is `0`, you can't effectively force objects into RoomGroups with priority `0`. However there are plenty of priority values available so this should not be a problem in practice. The final scene looks something like this, with houses instanced wherever you want them on a giant outer room. diff --git a/tutorials/3d/portals/first_steps_with_rooms_and_portals.md b/tutorials/3d/portals/first_steps_with_rooms_and_portals.md index 761be42..63d6f3e 100644 --- a/tutorials/3d/portals/first_steps_with_rooms_and_portals.md +++ b/tutorials/3d/portals/first_steps_with_rooms_and_portals.md @@ -15,7 +15,8 @@ This conversion must take place every time you want to activate the system. It d If you convert the level while the editor is running, the portal culling system will take over from the normal Godot frustum culling, potentially interfering with editor features. To get around this, you can turn portal culling on and off using either the **View Portal Culling** toggle in the **View** menu on the editor toolbar (which also has a keyboard shortcut) or the **Active** setting in the RoomManager node. -.. note:: To use the RoomManager, you have to tell it where the rooms are in your scene tree, or, more specifically, where the RoomList node is. This RoomList is the parent of your rooms - see below. If the RoomList is not set, conversion will fail, and you will see a warning dialog box. +Note: + To use the RoomManager, you have to tell it where the rooms are in your scene tree, or, more specifically, where the RoomList node is. This RoomList is the parent of your rooms - see below. If the RoomList is not set, conversion will fail, and you will see a warning dialog box. ![](img/room_manager.png) @@ -26,7 +27,8 @@ Before we create any rooms, we must first create a node to be the parent of all ![](img/roomlist_node.png) -.. note:: The roomlist is **not** a special node type – it can just be a regular Spatial. +Note: + The roomlist is **not** a special node type – it can just be a regular Spatial. You will need to assign the roomlist node in the RoomManager so that it knows where to find the rooms. @@ -111,7 +113,8 @@ There are two ways to specify which room the portal should link to: - Leave the **Linked Room** in the inspector blank. The system will attempt to *autolink* the portal to the nearest neighbour room during conversion. This works fine in most cases. - Explicitly specify the room by setting the **Linked Room** in the inspector. -.. note:: Portals are defined as a set of 2D points. This ensures that the polygon formed is in a single plane. The transform determines the portal orientation. The points must also form a *convex* polygon. This is enforced by validating the points you specify, ignoring any that do not form a convex shape. This makes editing easier while making it difficult to break the system. +Note: + Portals are defined as a set of 2D points. This ensures that the polygon formed is in a single plane. The transform determines the portal orientation. The points must also form a *convex* polygon. This is enforced by validating the points you specify, ignoring any that do not form a convex shape. This makes editing easier while making it difficult to break the system. Trying it out ~~~~~~~~~~~~~ diff --git a/tutorials/3d/portals/introduction_to_rooms_and_portals.md b/tutorials/3d/portals/introduction_to_rooms_and_portals.md index 9a30408..8fb0f2c 100644 --- a/tutorials/3d/portals/introduction_to_rooms_and_portals.md +++ b/tutorials/3d/portals/introduction_to_rooms_and_portals.md @@ -13,7 +13,8 @@ This allows several features: The trade off for these features is that we have to manually partition our level into rooms, and add portals between them. -.. note:: Godot portals should not be confused with those in the `game of the same name ( https://en.wikipedia.org/wiki/Portal_(video_game) )`. They do not warp space, they simply represent a window that the camera (or lights) can see through. +Note: + Godot portals should not be confused with those in the `game of the same name ( https://en.wikipedia.org/wiki/Portal_(video_game) )`. They do not warp space, they simply represent a window that the camera (or lights) can see through. Minimizing manual labour ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -31,6 +32,7 @@ In general, when it comes to medium and large-sized levels, it is better to do a Some caveats ^^^^^^^^^^^^ -.. note:: The portal system should be considered an **advanced feature** of Godot. You should not attempt to use rooms and portals until you are familiar with the Godot editor, and have successfully made at least a couple of test games. +Note: + The portal system should be considered an **advanced feature** of Godot. You should not attempt to use rooms and portals until you are familiar with the Godot editor, and have successfully made at least a couple of test games. It gives you great power as a game designer, but the trade off is that it requires a very technical approach to level design. It is aimed at producing professional-grade results, and assumes the user is prepared to put in the work for this. It is not intended to be used for all 3D games. Not all games will significantly benefit from portals, and it may require more time than a short game jam allows. diff --git a/tutorials/3d/procedural_geometry/arraymesh.md b/tutorials/3d/procedural_geometry/arraymesh.md index 21d72bc..2cadacd 100644 --- a/tutorials/3d/procedural_geometry/arraymesh.md +++ b/tutorials/3d/procedural_geometry/arraymesh.md @@ -128,7 +128,8 @@ gdscript GDScript mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, surface_array) # No blendshapes or compression used. ``` -.. note:: In this example, we used `Mesh.PRIMITIVE_TRIANGLES`, but you can use any primitive type +Note: + In this example, we used `Mesh.PRIMITIVE_TRIANGLES`, but you can use any primitive type available from mesh. Put together, the full code looks like: diff --git a/tutorials/3d/procedural_geometry/meshdatatool.md b/tutorials/3d/procedural_geometry/meshdatatool.md index 9eb1114..9b69e34 100644 --- a/tutorials/3d/procedural_geometry/meshdatatool.md +++ b/tutorials/3d/procedural_geometry/meshdatatool.md @@ -11,7 +11,8 @@ and tools to work with meshes than the ArrayMesh does. When the MeshDataTool is used, it calculates mesh data that is not available in ArrayMeshes such as faces and edges, which are necessary for certain mesh algorithms. If you do not need this extra information then it may be better to use an ArrayMesh. -.. note:: MeshDataTool can only be used on Meshes that use the PrimitiveType `Mesh.PRIMITIVE_TRIANGLES`. +Note: + MeshDataTool can only be used on Meshes that use the PrimitiveType `Mesh.PRIMITIVE_TRIANGLES`. We initialize the MeshDataTool from an ArrayMesh by calling `create_from_surface()`. If there is already data initialized in the MeshDataTool, calling `create_from_surface()` will clear it for you. Alternatively, you can call `clear()` yourself before re-using the MeshDataTool. diff --git a/tutorials/3d/spatial_material.md b/tutorials/3d/spatial_material.md index 23ca449..d38a146 100644 --- a/tutorials/3d/spatial_material.md +++ b/tutorials/3d/spatial_material.md @@ -226,7 +226,8 @@ Determines which side of the object is not drawn when backfaces are rendered: * **Front:** The front of the object is culled when not visible. * **Disabled:** Used for objects that are double-sided (no culling is performed). -.. note:: +Note: + By default, Blender has backface culling disabled on materials and will export materials to match how they render in Blender. This means that @@ -376,7 +377,8 @@ and wider compatibility. ![](img/spatial_material16.png) -.. note:: +Note: + Godot requires the normal map to use the X+, Y+ and Z+ coordinates, this is known as OpenGL style. If you've imported a material made to be used with @@ -418,7 +420,8 @@ right. ![](img/clearcoat_comparison.png) -.. note:: The effect will be more noticeable in Godot 4. +Note: + The effect will be more noticeable in Godot 4. Anisotropy ~~~~~~~~~~ diff --git a/tutorials/3d/using_gridmaps.md b/tutorials/3d/using_gridmaps.md index d477b26..3fd3277 100644 --- a/tutorials/3d/using_gridmaps.md +++ b/tutorials/3d/using_gridmaps.md @@ -73,7 +73,8 @@ To create the NavigationMesh from a MeshLibrary scene export, place a item. Add a valid NavigationMesh resource to the NavigationMeshInstance and some source geometry nodes below and bake the NavigationMesh. -.. note:: +Note: + With small grid cells it is often necessary to reduce the NavigationMesh properties for agent radius and region minimum size. @@ -83,7 +84,8 @@ geometry nodes below and bake the NavigationMesh. Nodes below the NavigationMeshInstance are ignored for the MeshLibrary scene export, so additional nodes can be added as source geometry just for baking the navmesh. -.. warning:: +Warning: + The baked cell size of the NavigationMesh must match the NavigationServer map cell size to properly merge the navigation meshes of different grid cells. diff --git a/tutorials/3d/using_multi_mesh_instance.md b/tutorials/3d/using_multi_mesh_instance.md index 0ac27a4..44dad67 100644 --- a/tutorials/3d/using_multi_mesh_instance.md +++ b/tutorials/3d/using_multi_mesh_instance.md @@ -36,7 +36,8 @@ the scene. Your scene tree would look like this: ![](img/multimesh_scene_tree.png) -.. note:: For simplicity's sake, this tutorial uses built-in primitives. +Note: + For simplicity's sake, this tutorial uses built-in primitives. Now you have everything ready. Select the MultiMeshInstance node and look at the toolbar, you should see an extra button called `MultiMesh` next to `View`. diff --git a/tutorials/animation/2d_skeletons.md b/tutorials/animation/2d_skeletons.md index 20c0c64..3764614 100644 --- a/tutorials/animation/2d_skeletons.md +++ b/tutorials/animation/2d_skeletons.md @@ -29,7 +29,8 @@ The following tutorial will, then, explain 2D skeletal deformations. Setup ----- -.. seealso:: +See also: + Before starting, we recommend you to go through the `doc_cutout_animation` tutorial to gain a general understanding of diff --git a/tutorials/animation/cutout_animation.md b/tutorials/animation/cutout_animation.md index 2bfd518..995d668 100644 --- a/tutorials/animation/cutout_animation.md +++ b/tutorials/animation/cutout_animation.md @@ -124,7 +124,8 @@ the hip node in the scene hierarchy), but then the left arm is no longer in its proper place in the hierarchy. This means it wouldn't be affected by the movement of the torso. We'll fix this problem with `RemoteTransform2D` nodes. -.. note:: You can also fix depth ordering problems by adjusting the Z property +Note: + You can also fix depth ordering problems by adjusting the Z property of any node inheriting from Node2D. RemoteTransform2D node diff --git a/tutorials/animation/introduction.md b/tutorials/animation/introduction.md index 6b910d4..322a679 100644 --- a/tutorials/animation/introduction.md +++ b/tutorials/animation/introduction.md @@ -113,7 +113,8 @@ its child. We will animate the sprite to move between two points on the screen. Our scene setup -.. warning:: +Warning: + AnimationPlayer inherits from Node instead of Node2D or Spatial, which means that the child nodes will not inherit the transform from the parent nodes diff --git a/tutorials/animation/playing_videos.md b/tutorials/animation/playing_videos.md index 5d3d0d4..e3eae53 100644 --- a/tutorials/animation/playing_videos.md +++ b/tutorials/animation/playing_videos.md @@ -21,7 +21,8 @@ WebM is supported in core in Godot 3.x, but support for it will be removed in 4. as it proved to be too buggy and difficult to maintain. Therefore, **using WebM is not recommended**. -.. note:: +Note: + You may find videos with an `.ogg` or `.ogx` extensions, which are generic extensions for data within an Ogg container. @@ -79,7 +80,8 @@ node to be a child of the AspectRatioContainer node. Make sure **Expand** is disabled on the VideoPlayer. Your video should now scale automatically to fit the whole screen while avoiding distortion. -.. seealso:: +See also: + See `doc_multiple_resolutions` for more tips on supporting multiple aspect ratios in your project. @@ -184,7 +186,8 @@ Here are example FFmpeg commands to convert a MP4 video to Ogg Theora. Since FFmpeg supports a lot of input formats, you should be able to use the commands below with almost any input video format (AVI, MOV, WebM, …). -.. note:: +Note: + Make sure your copy of FFmpeg is compiled with libtheora and libvorbis support. You can check this by running `ffmpeg` without any arguments, then looking diff --git a/tutorials/assets_pipeline/escn_exporter/index.md b/tutorials/assets_pipeline/escn_exporter/index.md index d9ab83e..b663a9a 100644 --- a/tutorials/assets_pipeline/escn_exporter/index.md +++ b/tutorials/assets_pipeline/escn_exporter/index.md @@ -1,7 +1,8 @@ Blender ESCN exporter ===================== -.. note:: This chapter relates to the Blender plugin called "Godot Blender Exporter", +Note: + This chapter relates to the Blender plugin called "Godot Blender Exporter", which can be downloaded here: https://github.com/godotengine/godot-blender-exporter This plugin can be used to export Blender scenes in a Godot-specific scene format diff --git a/tutorials/assets_pipeline/escn_exporter/lights.md b/tutorials/assets_pipeline/escn_exporter/lights.md index 90a2462..1920dc7 100644 --- a/tutorials/assets_pipeline/escn_exporter/lights.md +++ b/tutorials/assets_pipeline/escn_exporter/lights.md @@ -1,10 +1,12 @@ Lights ====== -.. warning:: +Warning: + By default, lamps in Blender have shadows enabled. This can cause performance issues in Godot. -.. warning:: +Warning: + Lamps are exported using their "Blender Render" settings. When Blender 2.8 is released, this will be removed and this part of the exporter will change. diff --git a/tutorials/assets_pipeline/escn_exporter/material.md b/tutorials/assets_pipeline/escn_exporter/material.md index 764a64a..5dfb1d1 100644 --- a/tutorials/assets_pipeline/escn_exporter/material.md +++ b/tutorials/assets_pipeline/escn_exporter/material.md @@ -45,7 +45,8 @@ difficulties in implementation, which are: - `group node` - shader nodes except `PrincipledBSDF`, `Diffuse`, `Glossy`, `Glass`, `add shader` and `mix shader` -.. warning:: +Warning: + If possible, try to use PrincipledBSDF node with GGX distribution as the output shader node, it is the only one guaranteed to be exactly correct. Others are just based on approximation. diff --git a/tutorials/assets_pipeline/escn_exporter/mesh.md b/tutorials/assets_pipeline/escn_exporter/mesh.md index 88bf947..f34bbe4 100644 --- a/tutorials/assets_pipeline/escn_exporter/mesh.md +++ b/tutorials/assets_pipeline/escn_exporter/mesh.md @@ -13,7 +13,8 @@ Exporting mesh shape key is supported, however exporting each shape key is almost like exporting the mesh again, so don't be surprised it takes a relatively long time. -.. warning:: +Warning: + A lot of modifiers are not compatible with shape keys (e.g. subsurface modifier), so if you found you have incorrect shape keys exported, try to disable :code:`Apply Modifiers` diff --git a/tutorials/assets_pipeline/escn_exporter/skeleton.md b/tutorials/assets_pipeline/escn_exporter/skeleton.md index aa4c370..a5ad120 100644 --- a/tutorials/assets_pipeline/escn_exporter/skeleton.md +++ b/tutorials/assets_pipeline/escn_exporter/skeleton.md @@ -9,7 +9,8 @@ Rest Bone Armature object in Blender is exported as a Skeleton node along with rest position (transform in Godot) of bones. -.. warning:: +Warning: + The three check boxes :code:`Inherit Rotation`, :code:`Inherit Scale`, :code:`Local Location` (colored in red) must be ticked when building armature in Blender, so that the exported bone transform be diff --git a/tutorials/assets_pipeline/exporting_3d_scenes.md b/tutorials/assets_pipeline/exporting_3d_scenes.md index e179562..e47d21c 100644 --- a/tutorials/assets_pipeline/exporting_3d_scenes.md +++ b/tutorials/assets_pipeline/exporting_3d_scenes.md @@ -12,7 +12,8 @@ export as a glTF binary (`.glb` file) or glTF embedded with textures such as a CSG mesh blockout for a level, export it to clean it up in a program such as Blender, and then bring it back into Godot. -.. note:: +Note: + Only Blender 2.83 and newer can import glTF files exported by Godot. diff --git a/tutorials/assets_pipeline/importing_images.md b/tutorials/assets_pipeline/importing_images.md index c00c1be..1bebf11 100644 --- a/tutorials/assets_pipeline/importing_images.md +++ b/tutorials/assets_pipeline/importing_images.md @@ -31,7 +31,8 @@ Godot can import the following image formats: - WebP files support transparency and can be compressed lossily or losslessly. The precision is limited to 8 bits per channel. -.. note:: +Note: + If you've compiled the Godot editor from source with specific modules disabled, some formats may not be available. @@ -120,7 +121,8 @@ reimported automatically. Note that RGTC compression affects the resulting normal map image. You will have to adjust custom shaders that use the normal map to take this into account. -.. note:: +Note: + Godot requires the normal map to use the X+, Y+ and Z+ coordinates, this is known as OpenGL style. If you've imported a material made to be used with @@ -172,7 +174,8 @@ sRGB Godot uses Linear colorspace when rendering 3D. Textures mapped to albedo or detail channels need to have this option turned on in order for colors to look correct. When set to **Detect** mode, the texture will be marked as sRGB when used in albedo channels. -.. warning:: +Warning: + Since the texture will have its data modified when sRGB is enabled, this means using the same texture in both 2D and 3D will make the texture diff --git a/tutorials/assets_pipeline/importing_scenes.md b/tutorials/assets_pipeline/importing_scenes.md index 3253958..6432c36 100644 --- a/tutorials/assets_pipeline/importing_scenes.md +++ b/tutorials/assets_pipeline/importing_scenes.md @@ -52,11 +52,13 @@ text based format and the binary data in a separate binary file. This can be use changes in a text based format. The second is you need the texture files separate from the material file. If you don't need either of those glTF binary files are fine. -.. warning:: +Warning: + Blend shape animations cannot be imported - they require manual animation within Godot. -.. note:: +Note: + Blender versions older than 3.2 do not export emissive textures with the glTF file. If your model uses one and you're using an older version of @@ -99,7 +101,8 @@ separately. Godot uses PBR (physically based rendering) for its materials, so if textures, they can work in Godot. This includes the `Substance suite ( https://www.substance3d.com/ )`, `ArmorPaint (open source) ( https://armorpaint.org/ )`, and `Material Maker (open source) ( https://github.com/RodZill4/material-maker )`. -.. note:: For more information on Godot's materials, see `doc_spatial_material`. +Note: + For more information on Godot's materials, see `doc_spatial_material`. Exporting considerations ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -214,7 +217,8 @@ most 3D DCCs don't have the same material options as those present in Godot. When materials are built-in, they will be lost each time the source scene is modified and re-imported. -.. note:: +Note: + Godot will not reimport materials that are stored in external files unless you remove the associated `.material` file before reimporting. @@ -287,7 +291,8 @@ Whether or not the mesh is used in baked lightmaps. - **Enable:** The mesh is used in baked lightmaps. - **Gen Lightmaps:** The mesh is used in baked lightmaps, and unwraps a second UV layer for lightmaps. -.. note:: For more information on light baking see `doc_baked_lightmaps`. +Note: + For more information on light baking see `doc_baked_lightmaps`. External Files ~~~~~~~~~~~~~~ @@ -423,7 +428,8 @@ To simplify this workflow, Godot offers several suffixes that can be added to the names of the objects in your 3D modelling software. When imported, Godot will detect suffixes in object names and will perform actions automatically. -.. note:: +Note: + All the suffixes described below are *case-sensitive*. @@ -477,13 +483,15 @@ When possible, **try to use a few primitive collision shapes** instead of triang mesh or convex shapes. Primitive shapes often have the best performance and reliability. -.. note:: +Note: + For better visibility in Blender's editor, you can set the "X-Ray" option on collision empties and set some distinct color for them in Blender's **User Preferences > Themes > 3D View > Empty**. -.. seealso:: +See also: + See `doc_collision_shapes_3d` for a comprehensive overview of collision shapes. diff --git a/tutorials/assets_pipeline/importing_translations.md b/tutorials/assets_pipeline/importing_translations.md index dbf2ec1..580a373 100644 --- a/tutorials/assets_pipeline/importing_translations.md +++ b/tutorials/assets_pipeline/importing_translations.md @@ -29,7 +29,8 @@ each string. This allows you to revise the text while it is being translated to other languages. The unique ID can be a number, a string, or a string with a number (it's just a unique string anyway). -.. note:: If you need a more powerful file format, Godot also supports +Note: + If you need a more powerful file format, Godot also supports loading translations written in the gettext `.po` format. See `doc_localization_using_gettext` for details. @@ -42,7 +43,8 @@ editors can export to this format, so the only requirement is that the files have a special arrangement. The CSV files **must** be saved with UTF-8 encoding without a `byte order mark ( https://en.wikipedia.org/wiki/Byte_order_mark )`. -.. warning:: +Warning: + By default, Microsoft Excel will always save CSV files with ANSI encoding rather than UTF-8. There is no built-in way to do this, but there are diff --git a/tutorials/audio/audio_buses.md b/tutorials/audio/audio_buses.md index 3b776ba..303bf75 100644 --- a/tutorials/audio/audio_buses.md +++ b/tutorials/audio/audio_buses.md @@ -79,7 +79,8 @@ AudioStream and select a target bus for playback: Finally, toggle the **Playing** property to **On** and sound will flow. -.. seealso:: +See also: + You may also be interested in reading about `doc_audio_streams` now. @@ -147,7 +148,8 @@ The compressor has many uses. For example: - It can accentuate transients by using a slower attack. This can make sound effects more punchy. -.. note:: +Note: + If your goal is to prevent a signal from exceeding a given amplitude altogether, rather than to reduce the dynamic range of the signal, diff --git a/tutorials/audio/audio_streams.md b/tutorials/audio/audio_streams.md index 1d81eec..d3af899 100644 --- a/tutorials/audio/audio_streams.md +++ b/tutorials/audio/audio_streams.md @@ -40,7 +40,8 @@ This is a variant of AudioStreamPlayer, but emits sound in a 2D positional environment. When close to the left of the screen, the panning will go left. When close to the right side, it will go right. -.. note:: +Note: + Area2Ds can be used to divert sound from any AudioStreamPlayer2Ds they contain to specific buses. This makes it possible to create buses with diff --git a/tutorials/best_practices/autoloads_versus_internal_nodes.md b/tutorials/best_practices/autoloads_versus_internal_nodes.md index 2de8a52..2965ec4 100644 --- a/tutorials/best_practices/autoloads_versus_internal_nodes.md +++ b/tutorials/best_practices/autoloads_versus_internal_nodes.md @@ -40,7 +40,8 @@ solves the problem in the short term but causes more problems: stored from the start, you can either have too few and face bugs, or too many and use more memory than you need. -.. note:: +Note: + About global access, the problem is that Any code anywhere could pass wrong data to the `Sound` autoload in our example. As a result, the domain to @@ -98,7 +99,8 @@ variable for their name generated in GDScript, allowing you to call them from any script file in your project. But now, you can use the `name` keyword instead to get auto-completion for a type in your entire project. -.. note:: +Note: + Autoload is not exactly a Singleton. Nothing prevents you from instantiating copies of an auto-loaded node. It is only a tool that makes a node load diff --git a/tutorials/best_practices/data_preferences.md b/tutorials/best_practices/data_preferences.md index 975bde3..2033a97 100644 --- a/tutorials/best_practices/data_preferences.md +++ b/tutorials/best_practices/data_preferences.md @@ -6,7 +6,8 @@ Data preferences Ever wondered whether one should approach problem X with data structure Y or Z? This article covers a variety of topics related to these dilemmas. -.. note:: +Note: + This article makes references to "[something]-time" operations. This terminology comes from algorithm analysis' @@ -49,7 +50,8 @@ Godot implements Array as a `Vector Manage Export Templates**: ![](img/export_template_menu.png) -.. note:: +Note: + If you've downloaded Godot from `Steam ( https://store.steampowered.com/app/404790/Godot_Engine/ )`, @@ -156,7 +158,8 @@ version that matches your version of Godot. ![](img/export_template_manager.png) -.. note:: +Note: + Export templates are bound to a specific Godot version. If you upgrade Godot, you must download templates that match the new version. @@ -197,14 +200,16 @@ folder. Choose a location *outside* of your project folder. Click **Save** and the engine will build the export files. -.. note:: +Note: + When exporting for macOS, if you export from a macOS computer, you'll end up with a `.dmg` file, while using Linux or Windows produces a `.zip`. In either case, the compressed file contains a macOS `.app` that you can double-click and run. -.. note:: +Note: + On Windows, if you want your exported executable to have a different icon than the default one, you need to change it manually. See @@ -256,7 +261,8 @@ on your device. To do this on the command line, use the following: adb install dodge.apk -.. note:: Your device may need to be in *developer mode*. Consult your +Note: + Your device may need to be in *developer mode*. Consult your device's documentation for details. If your system supports it, connecting a compatible Android device will cause @@ -269,7 +275,8 @@ Clicking this button builds the APK and copies it onto your device in one step. iOS ~~~ -.. note:: +Note: + To build your game for iOS, you must have a computer running macOS with Xcode installed. @@ -321,7 +328,8 @@ when you export the project. ![](img/export_web_export_with_debug_disabled.png) -.. note:: +Note: + While WebAssembly is supported in all major browsers, it is still an emerging technology and you may find some things that don't work. Make sure diff --git a/tutorials/export/exporting_for_android.md b/tutorials/export/exporting_for_android.md index dd52af4..1fdfc77 100644 --- a/tutorials/export/exporting_for_android.md +++ b/tutorials/export/exporting_for_android.md @@ -4,7 +4,8 @@ Exporting for Android ===================== -.. seealso:: +See also: + This page describes how to export a Godot project to Android. If you're looking to compile export template binaries from source instead, @@ -43,7 +44,8 @@ Download and install the Android SDK. sdkmanager --sdk_root= "platform-tools" "build-tools;30.0.3" "platforms;android-31" "cmdline-tools;latest" "cmake;3.10.2.4988404" "ndk;21.4.7075529" -.. note:: +Note: + If you are using Linux, **do not use an Android SDK provided by your distribution's repositories as it will often be outdated**. @@ -87,7 +89,8 @@ In that screen, 2 paths need to be set: Once that is configured, everything is ready to export to Android! -.. note:: +Note: + If you get an error saying *"Could not install to device."*, make sure you do not have an application with the same Android package name already @@ -108,7 +111,8 @@ There are two types of icons required by Godot: - **Main Icon:** The "classic" icon. This will be used on all Android versions up to Android 8 (Oreo), exclusive. Must be at least 192×192 px. - **Adaptive Icons:** Starting from Android 8 (inclusive), `Adaptive Icons ( https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive )`_ were introduced. Applications will need to include separate background and foreground icons to have a native look. The user's launcher application will control the icon's animation and masking. Must be at least 432×432 px. -.. seealso:: It's important to adhere to some rules when designing adaptive icons. `Google Design has provided a nice article ( https://medium.com/google-design/designing-adaptive-icons-515af294c783 )`_ that helps to understand those rules and some of the capabilities of adaptive icons. +See also: + It's important to adhere to some rules when designing adaptive icons. `Google Design has provided a nice article ( https://medium.com/google-design/designing-adaptive-icons-515af294c783 )`_ that helps to understand those rules and some of the capabilities of adaptive icons. .. caution:: The most important adaptive icon design rule is to have your icon critical elements inside the safe zone: a centered circle with a diameter of 66dp (264 pixels on `xxxhdpi`) to avoid being clipped by the launcher. diff --git a/tutorials/export/exporting_for_dedicated_servers.md b/tutorials/export/exporting_for_dedicated_servers.md index b261ae4..65530d5 100644 --- a/tutorials/export/exporting_for_dedicated_servers.md +++ b/tutorials/export/exporting_for_dedicated_servers.md @@ -53,13 +53,15 @@ final PCK file, so you can leave it as-is. See `doc_exporting_projects` for more information. -.. note:: +Note: + If you're exporting the project from a headless editor, call the headless editor with the `--export-pack` option while in the project folder to export only a PCK file. -.. note:: +Note: + The PCK file will include resources not normally needed by the server, such as textures and sounds. This means the PCK file will be larger than it could diff --git a/tutorials/export/exporting_for_ios.md b/tutorials/export/exporting_for_ios.md index 966ffdb..5776f94 100644 --- a/tutorials/export/exporting_for_ios.md +++ b/tutorials/export/exporting_for_ios.md @@ -3,7 +3,8 @@ Exporting for iOS ================= -.. seealso:: +See also: + This page describes how to export a Godot project to iOS. If you're looking to compile export template binaries from source instead, @@ -35,11 +36,13 @@ After you click **Export Project**, there are still two important options left: ![](img/ios_export_file.png) -.. note:: This tutorial uses **exported_xcode_project_name**, but you will use your +Note: + This tutorial uses **exported_xcode_project_name**, but you will use your project's name. When you see **exported_xcode_project_name** in the following steps, replace it with the name you used instead. -.. note:: Avoid using spaces when you choose your **exported_xcode_project_name** as +Note: + Avoid using spaces when you choose your **exported_xcode_project_name** as this can lead to corruption in your XCode project file. When the export completes, the output folder should look like this: @@ -63,7 +66,8 @@ In the following example: * **exported_xcode_project_name** is the name of the exported iOS application (as above). * **godot_project_to_export** is the name of the Godot project. -.. note:: **godot_project_to_export** must not be the same as **exported_xcode_project_name** +Note: + **godot_project_to_export** must not be the same as **exported_xcode_project_name** to prevent signing issues in Xcode. Steps to link a Godot project folder to Xcode diff --git a/tutorials/export/exporting_for_linux.md b/tutorials/export/exporting_for_linux.md index 6af027e..96f7e5b 100644 --- a/tutorials/export/exporting_for_linux.md +++ b/tutorials/export/exporting_for_linux.md @@ -3,7 +3,8 @@ Exporting for Linux =================== -.. seealso:: +See also: + This page describes how to export a Godot project to Linux. If you're looking to compile editor or export template binaries from source instead, diff --git a/tutorials/export/exporting_for_macos.md b/tutorials/export/exporting_for_macos.md index cb5d9a6..258a3e9 100644 --- a/tutorials/export/exporting_for_macos.md +++ b/tutorials/export/exporting_for_macos.md @@ -3,7 +3,8 @@ Exporting for macOS =================== -.. seealso:: +See also: + This page describes how to export a Godot project to macOS. If you're looking to compile editor or export template binaries from source instead, @@ -20,7 +21,8 @@ Requirements - Download the Godot export templates. Use the Godot menu: `Editor > Manage Export Templates`. - A valid and unique `Bundle identifier` should be set in the `Application` section of the export options. -.. warning:: +Warning: + Projects exported without code signing and notarization will be blocked by Gatekeeper if they are downloaded from unknown sources, see the `Running Godot apps on macOS ( doc_running_on_macos )` page for more information. @@ -69,7 +71,8 @@ Signing Options | Replace Existing Signature | Replaces existing signatures of the GDNative libraries and embedded helper executables. | +------------------------------+---------------------------------------------------------------------------------------------------+ -.. note:: +Note: + To notarize an app, you must enable the `Hardened Runtime` and `Timestamp`. @@ -95,7 +98,8 @@ Notarization Options See `Notarizing macOS Software Before Distribution ( https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution?language=objc )` for more info. -.. note:: +Note: + Notarization is supported when exporting from a computer running macOS, these options are hidden on other platforms. @@ -147,7 +151,8 @@ The App Sandbox restricts access to user data, networking and devices. Sandboxed apps can't access most of the file system, can't use custom file dialogs and execute binaries (using `OS.execute` and `OS.create_process`) outside the `.app` bundle. See `App Sandbox ( https://developer.apple.com/documentation/security/app_sandbox?language=objc )` for more info. -.. note:: +Note: + To distribute an app through the App Store, you must enable the App Sandbox. diff --git a/tutorials/export/exporting_for_uwp.md b/tutorials/export/exporting_for_uwp.md index 75016a5..2ee17b9 100644 --- a/tutorials/export/exporting_for_uwp.md +++ b/tutorials/export/exporting_for_uwp.md @@ -3,7 +3,8 @@ Exporting for Universal Windows Platform ======================================== -.. seealso:: +See also: + This page describes how to export a Godot project to UWP. If you're looking to compile export template binaries from source instead, @@ -97,6 +98,7 @@ double clicking the `.appx` file from Windows Explorer. It's also possible to install by using the `Add-AppxPackage` PowerShell cmdlet. -.. note:: If you want to update your already installed app, you must +Note: + If you want to update your already installed app, you must update the version number on the new package or first uninstall the previous package. diff --git a/tutorials/export/exporting_for_web.md b/tutorials/export/exporting_for_web.md index 925e248..d419950 100644 --- a/tutorials/export/exporting_for_web.md +++ b/tutorials/export/exporting_for_web.md @@ -3,7 +3,8 @@ Exporting for the Web ===================== -.. seealso:: +See also: + This page describes how to export a Godot project to HTML5. If you're looking to compile editor or export template binaries from source instead, @@ -81,7 +82,8 @@ JavaScript APIs, include CSS, or run JavaScript code. To customize the generated file, use the **Custom HTML shell** option. -.. warning:: **Export types** other then *Regular* are not yet supported by the +Warning: + **Export types** other then *Regular* are not yet supported by the C# version. Limitations @@ -136,7 +138,8 @@ As mentioned `above ( doc_javascript_export_options )` multi-threading is only available if the appropriate **Export Type** is set and support for it across browsers is still limited. -.. warning:: Requires a `secure context ( doc_javascript_secure_contexts )`. +Warning: + Requires a `secure context ( doc_javascript_secure_contexts )`. Browsers also require that the web page is served with specific `cross-origin isolation headers ( https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy )`. @@ -169,10 +172,12 @@ Audio Chrome restricts how websites may play audio. It may be necessary for the player to click or tap or press a key to enable audio. -.. seealso:: Google offers additional information about their `Web Audio autoplay +See also: + Google offers additional information about their `Web Audio autoplay policies ( https://sites.google.com/a/chromium.org/dev/audio-video/autoplay )`. -.. warning:: Access to microphone requires a +Warning: + Access to microphone requires a `secure context ( doc_javascript_secure_contexts )`. Networking @@ -202,7 +207,8 @@ browser supporting the `Clipboard API ( https://developer.mozilla.org/en-US/docs additionally, due to the API asynchronous nature might not be reliable when accessed from GDScript. -.. warning:: Requires a `secure context ( doc_javascript_secure_contexts )`. +Warning: + Requires a `secure context ( doc_javascript_secure_contexts )`. Gamepads ~~~~~~~~ @@ -213,7 +219,8 @@ sadly the `Gamepad API ( https://developer.mozilla.org/en-US/docs/Web/API/Gamepa does not provide a reliable way to detect the gamepad information necessary to remap them based on model/vendor/OS due to privacy considerations. -.. warning:: Requires a `secure context ( doc_javascript_secure_contexts )`. +Warning: + Requires a `secure context ( doc_javascript_secure_contexts )`. Boot splash is not displayed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tutorials/export/exporting_for_windows.md b/tutorials/export/exporting_for_windows.md index 469cb52..427cb5e 100644 --- a/tutorials/export/exporting_for_windows.md +++ b/tutorials/export/exporting_for_windows.md @@ -3,7 +3,8 @@ Exporting for Windows ===================== -.. seealso:: +See also: + This page describes how to export a Godot project to Windows. If you're looking to compile editor or export template binaries from source instead, @@ -24,7 +25,8 @@ Requirements - To enable code signing, you must have the `Windows 10 SDK` (on Windows) or `osslsigncode ( https://github.com/mtrojnar/osslsigncode )` (on any other OS) installed. - Download the Godot export templates. Use the Godot menu: `Editor > Manage Export Templates`. -.. warning:: +Warning: + If you export for Windows with embedded PCK files, you will not be able to sign the program as it will break. diff --git a/tutorials/export/exporting_pcks.md b/tutorials/export/exporting_pcks.md index 5e8504b..4bff6cd 100644 --- a/tutorials/export/exporting_pcks.md +++ b/tutorials/export/exporting_pcks.md @@ -64,7 +64,8 @@ Another method would be to `export from the command line ( doc_command_line_tuto If the output file ends with a PCK or ZIP file extension, then the export process will build that type of file for the chosen platform. -.. note:: +Note: + If one wishes to support mods for their game, they will need their users to create similarly exported files. Assuming the original game expects a @@ -105,7 +106,8 @@ gdscript GDScript var imported_scene = load("res://mod_scene.tscn") ``` -.. warning:: +Warning: + By default, if you import a file with the same file path/name as one you already have in your project, the imported one will replace it. This is something to watch out for when @@ -116,7 +118,8 @@ gdscript GDScript To opt out of this behavior, pass `false` as the second argument to `ProjectSettings.load_resource_pack()`. -.. note:: +Note: + For a C# project, you need to build the DLL and place it in the project directory first. Then, before loading the resource pack, you need to load its DLL as follows: `Assembly.LoadFile("mod.dll")` diff --git a/tutorials/export/exporting_projects.md b/tutorials/export/exporting_projects.md index 9932ca9..5a0f936 100644 --- a/tutorials/export/exporting_projects.md +++ b/tutorials/export/exporting_projects.md @@ -122,7 +122,8 @@ select every scene or resource you want to export. ![](img/expselected.png) -.. note:: +Note: + Files and folders whose name begin with a period will never be included in the exported project. This is done to prevent version control folders like @@ -177,7 +178,8 @@ the command: godot --path /path/to/project --export "Windows Desktop" some_name.exe -.. seealso:: +See also: + See `doc_command_line_tutorial` for more information about using Godot from the command line. @@ -203,7 +205,8 @@ depending on your needs. - Readable and writable using tools normally present on the user's operating system. This can be useful to make modding easier (see also `doc_exporting_pcks`). -.. warning:: +Warning: + 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 diff --git a/tutorials/export/feature_tags.md b/tutorials/export/feature_tags.md index 5e91303..652a4c9 100644 --- a/tutorials/export/feature_tags.md +++ b/tutorials/export/feature_tags.md @@ -86,7 +86,8 @@ Here is a list of most feature tags in Godot. Keep in mind they are **case-sensi | **pvrtc** | Textures using PVRTC compression are supported | +-----------------+--------------------------------------------------------+ -.. warning:: +Warning: + With the exception of texture compression feature tags, default feature tags are **immutable**. This means that they will *not* change depending on @@ -105,7 +106,8 @@ field in the *export preset* used to generate it: ![](img/feature_tags1.png) -.. note:: +Note: + Custom feature tags are only used when running the exported project (including with `doc_one-click_deploy`). They are **not used** when @@ -127,7 +129,8 @@ After overriding, a new field is added for this specific configuration: ![](img/feature_tags3.png) -.. note:: +Note: + When using the `project settings "override.cfg" functionality` diff --git a/tutorials/export/one-click_deploy.md b/tutorials/export/one-click_deploy.md index a7c068f..2d577a4 100644 --- a/tutorials/export/one-click_deploy.md +++ b/tutorials/export/one-click_deploy.md @@ -17,7 +17,8 @@ a USB device is connected to the computer and offer the user to automatically export, install and run the project (in debug mode) on the device. This feature is called *one-click deploy*. -.. note:: +Note: + One-click deploy is only available once you've added an export template marked as **Runnable** in the Export dialog. You can mark several export diff --git a/tutorials/export/running_on_macos.md b/tutorials/export/running_on_macos.md index aea9828..2822eb5 100644 --- a/tutorials/export/running_on_macos.md +++ b/tutorials/export/running_on_macos.md @@ -3,7 +3,8 @@ Running Godot apps on macOS =========================== -.. seealso:: +See also: + This page covers running Godot projects on macOS. If you haven't exported your project yet, read `doc_exporting_for_macos` first. @@ -15,7 +16,8 @@ Depending on the way a macOS app is signed and distributed, the following scenar App is signed, notarized and distributed via App Store ------------------------------------------------------ -.. note:: +Note: + App developers need to join the Apple Developer Program, and configure signing and notarization options during export, then upload the app to the App Store. @@ -24,7 +26,8 @@ The app should run out of the box, without extra user interaction required. App is signed, notarized and distributed outside App Store ---------------------------------------------------------- -.. note:: +Note: + App developers need to join the Apple Developer Program, and configure signing and notarization options during export, then distribute the app as ".DMG" or ".ZIP" archive. @@ -45,7 +48,8 @@ To allow third-party apps, open `System Preferences`, click `Security & Privacy` App is signed (including ad-hoc signatures) but not notarized ------------------------------------------------------------- -.. note:: +Note: + App developer used self-signed certificate or ad-hoc signing (default Godot behavior for exported project). @@ -72,7 +76,8 @@ To run this app, you can temporarily override Gatekeeper: App is not-signed, executable is linker-signed ---------------------------------------------- -.. note:: +Note: + App is built using official export templates, but it is not signed. @@ -93,7 +98,8 @@ To run this app, you should remove the quarantine extended file attribute manual Neither app nor executable is signed (relevant for Apple Silicon macs only) --------------------------------------------------------------------------- -.. note:: +Note: + App is built using custom export templates, compiled using OSXCross, and it is not signed at all. diff --git a/tutorials/i18n/internationalizing_games.md b/tutorials/i18n/internationalizing_games.md index afc4f0c..ca51ed3 100644 --- a/tutorials/i18n/internationalizing_games.md +++ b/tutorials/i18n/internationalizing_games.md @@ -22,7 +22,8 @@ them is already covered in the `doc_importing_translations` tutorial, so this one could be seen more like a follow-up to that one. -.. note:: We will be using the official demo as an example; you can +Note: + We will be using the official demo as an example; you can `download it from the Asset Library ( https://godotengine.org/asset-library/asset/134 )`_. Configuring the imported translation diff --git a/tutorials/i18n/localization_using_gettext.md b/tutorials/i18n/localization_using_gettext.md index 49a2ab8..540e3a0 100644 --- a/tutorials/i18n/localization_using_gettext.md +++ b/tutorials/i18n/localization_using_gettext.md @@ -7,7 +7,8 @@ In addition to `doc_importing_translations` in CSV format, Godot also supports loading translation files written in the GNU gettext format (text-based `.po` and compiled `.mo` since Godot 3.5). -.. note:: For an introduction to gettext, check out +Note: + For an introduction to gettext, check out `A Quick Gettext Tutorial ( https://www.labri.fr/perso/fleury/posts/programming/a-quick-gettext-tutorial.html )`_. It's written with C projects in mind, but much of the advice also applies to Godot (with the exception of `xgettext`). @@ -147,7 +148,8 @@ In **Translations**, click **Add…** then choose the `.po` or `.mo` file in the file dialog. The locale will be inferred from the `"Language: ( code>\n"` property in the messages file. -.. note:: See `doc_internationalizing_games` for more information on +Note: + See `doc_internationalizing_games` for more information on importing and testing translations in Godot. Updating message files to follow the PO template @@ -166,7 +168,8 @@ present in the PO template. This can be done automatically using the If you want to keep a backup of the original message file (which would be saved as `fr.po~` in this example), remove the `--backup=none` argument. -.. note:: +Note: + After running `msgmerge`, strings which were modified in the source language will have a "fuzzy" comment added before them in the `.po` file. This comment diff --git a/tutorials/inputs/controllers_gamepads_joysticks.md b/tutorials/inputs/controllers_gamepads_joysticks.md index 1cd8bc8..8e16f3f 100644 --- a/tutorials/inputs/controllers_gamepads_joysticks.md +++ b/tutorials/inputs/controllers_gamepads_joysticks.md @@ -32,7 +32,8 @@ specified key and controller inputs. Input actions are explained in detail on the `doc_inputevent` page. -.. note:: +Note: + Unlike keyboard input, supporting both mouse and controller input for an action (such as looking around in a first-person game) will require @@ -151,7 +152,8 @@ with the help of a `Timer` node. Troubleshooting --------------- -.. seealso:: +See also: + You can view a list of `known issues with controller support ( https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Atopic%3Ainput+gamepad )` diff --git a/tutorials/inputs/custom_mouse_cursor.md b/tutorials/inputs/custom_mouse_cursor.md index ed5609d..60b3f30 100644 --- a/tutorials/inputs/custom_mouse_cursor.md +++ b/tutorials/inputs/custom_mouse_cursor.md @@ -10,7 +10,8 @@ You might want to change the appearance of the mouse cursor in your game in orde Using project settings is a simpler (but more limited) way to customize the mouse cursor. The second way is more customizable, but involves scripting. -.. note:: +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 @@ -31,7 +32,8 @@ 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. +Note: + The custom image **must** be less than 256x256. Using a script -------------- @@ -58,7 +60,8 @@ gdscript GDScript Input.set_custom_mouse_cursor(beam, Input.CURSOR_IBEAM) ``` -.. note:: +Note: + Check `Input.set_custom_mouse_cursor()`. diff --git a/tutorials/inputs/handling_quit_requests.md b/tutorials/inputs/handling_quit_requests.md index 9f97fcd..2efd0b2 100644 --- a/tutorials/inputs/handling_quit_requests.md +++ b/tutorials/inputs/handling_quit_requests.md @@ -23,7 +23,8 @@ Pressing the Back button will exit the application if **Application > Config > Quit On Go Back** is checked in the Project Settings (which is the default). -.. note:: +Note: + `MainLoop.NOTIFICATION_WM_GO_BACK_REQUEST` isn't supported on iOS, as iOS devices don't have a physical Back button. diff --git a/tutorials/inputs/input_examples.md b/tutorials/inputs/input_examples.md index fe33dff..aaa8af7 100644 --- a/tutorials/inputs/input_examples.md +++ b/tutorials/inputs/input_examples.md @@ -13,7 +13,8 @@ turn those inputs into actions in your game. This document will show you some of the most common scenarios, which you can use as starting points for your own projects. -.. note:: For a detailed overview of how Godot's input event system works, +Note: + For a detailed overview of how Godot's input event system works, see `doc_inputevent`. Events versus polling @@ -153,7 +154,8 @@ gdscript GDScript .. tip:: See `@GlobalScope_KeyList ( enum_@GlobalScope_KeyList )` for a list of scancode constants. -.. warning:: +Warning: + Due to *keyboard ghosting*, not all key inputs may be registered at a given time if you press too many keys at once. Due to their location on the keyboard, diff --git a/tutorials/inputs/mouse_and_input_coordinates.md b/tutorials/inputs/mouse_and_input_coordinates.md index 19f0f90..e57d0be 100644 --- a/tutorials/inputs/mouse_and_input_coordinates.md +++ b/tutorials/inputs/mouse_and_input_coordinates.md @@ -48,4 +48,5 @@ gdscript GDScript get_viewport().get_mouse_position() ``` -.. note:: When the mouse mode is set to `Input.MOUSE_MODE_CAPTURED`, the `event.position` value from `InputEventMouseMotion` is the center of the screen. Use `event.relative` instead of `event.position` and `event.speed` to process mouse movement and position changes. +Note: + When the mouse mode is set to `Input.MOUSE_MODE_CAPTURED`, the `event.position` value from `InputEventMouseMotion` is the center of the screen. Use `event.relative` instead of `event.position` and `event.speed` to process mouse movement and position changes. diff --git a/tutorials/io/data_paths.md b/tutorials/io/data_paths.md index 226cf52..c8294ab 100644 --- a/tutorials/io/data_paths.md +++ b/tutorials/io/data_paths.md @@ -145,7 +145,8 @@ Godot complies with the `XDG Base Directory Specification on all platforms. You can override environment variables following the specification to change the editor and project data paths. -.. note:: If you use `Godot packaged as a Flatpak +Note: + If you use `Godot packaged as a Flatpak ( https://flathub.org/apps/details/org.godotengine.Godot )`, the editor data paths will be located in subfolders in `~/.var/app/org.godotengine.Godot/`. @@ -165,7 +166,8 @@ You can use it to create a portable installation of the editor. The `Steam release of Godot ( https://store.steampowered.com/app/404790/ )` uses self-contained mode by default. -.. note:: +Note: + Self-contained mode is not supported in exported projects yet. To read and write files relative to the executable path, use diff --git a/tutorials/io/saving_games.md b/tutorials/io/saving_games.md index af53731..344d9ac 100644 --- a/tutorials/io/saving_games.md +++ b/tutorials/io/saving_games.md @@ -12,7 +12,8 @@ Advanced save game systems should allow for additional information about an arbitrary number of objects. This will allow the save function to scale as the game grows more complex. -.. note:: +Note: + If you're looking to save user configuration, you can use the `ConfigFile` class for this purpose. diff --git a/tutorials/math/beziers_and_curves.md b/tutorials/math/beziers_and_curves.md index 6e3189c..c835e5b 100644 --- a/tutorials/math/beziers_and_curves.md +++ b/tutorials/math/beziers_and_curves.md @@ -120,7 +120,8 @@ The result will be a smooth curve interpolating between all four points: *(Image credit: Wikipedia)* -.. note:: Cubic Bezier interpolation works the same in 3D, just use `Vector3` +Note: + Cubic Bezier interpolation works the same in 3D, just use `Vector3` instead of `Vector2`. Adding control points diff --git a/tutorials/math/matrices_and_transforms.md b/tutorials/math/matrices_and_transforms.md index fe86fac..846ead3 100644 --- a/tutorials/math/matrices_and_transforms.md +++ b/tutorials/math/matrices_and_transforms.md @@ -18,12 +18,14 @@ and scale, so we will focus on how to represent those with matrices. Most of this guide focuses on 2D, using `Transform2D` and `Vector2`, but the way things work in 3D is very similar. -.. note:: As mentioned in the previous tutorial, it is important to +Note: + As mentioned in the previous tutorial, it is important to remember that in Godot, the Y axis points *down* in 2D. This is the opposite of how most schools teach linear algebra, with the Y axis pointing up. -.. note:: The convention is that the X axis is red, the Y axis is +Note: + The convention is that the X axis is red, the Y axis is green, and the Z axis is blue. This tutorial is color-coded to match these conventions, but we will also represent the origin vector with a blue color. @@ -89,7 +91,8 @@ a transformation matrix. To calculate the object's scale from an existing transformation matrix, you can use `length()` on each of the column vectors. -.. note:: In actual projects, you can use the `scaled()` +Note: + In actual projects, you can use the `scaled()` method to perform scaling. Rotating the transformation matrix @@ -129,12 +132,14 @@ hardest thing you need to know. ![](img/matrices_and_transforms/rotate2.png) -.. note:: Godot represents all rotations with radians, not degrees. +Note: + Godot represents all rotations with radians, not degrees. A full turn is `TAU` or `PI*2` radians, and a quarter turn of 90 degrees is `TAU/4` or `PI/2` radians. Working with `TAU` usually results in more readable code. -.. note:: Fun fact: In addition to Y being *down* in Godot, rotation +Note: + Fun fact: In addition to Y being *down* in Godot, rotation is represented clockwise. This means that all the math and trig functions behave the same as a Y-is-up CCW system, since these differences "cancel out". You can think of @@ -163,7 +168,8 @@ gdscript GDScript To calculate the object's rotation from an existing transformation matrix, you can use `atan2(t.x.y, t.x.x)`, where t is the Transform2D. -.. note:: In actual projects, you can use the `rotated()` +Note: + In actual projects, you can use the `rotated()` method to perform rotations. Basis of the transformation matrix @@ -213,7 +219,8 @@ method will translate the object *relative to its own rotation*. For example, an object rotated 90 degrees clockwise will move to the right when `translated()` with `Vector2.UP`. -.. note:: Godot's 2D uses coordinates based on pixels, so in actual +Note: + Godot's 2D uses coordinates based on pixels, so in actual projects you will want to translate by hundreds of units. Putting it all together @@ -250,7 +257,8 @@ gdscript GDScript Shearing the transformation matrix (advanced) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: If you are only looking for how to *use* transformation matrices, +Note: + If you are only looking for how to *use* transformation matrices, feel free to skip this section of the tutorial. This section explores an uncommonly used aspect of transformation matrices for the purpose of building an understanding of them. @@ -290,7 +298,8 @@ gdscript GDScript transform = t # Change the node's transform to what we just calculated. ``` -.. note:: You can't set the raw values of a Transform2D in the editor, +Note: + You can't set the raw values of a Transform2D in the editor, so you *must* use code if you want to shear the object. Due to the vectors no longer being perpendicular, the object has been @@ -318,7 +327,8 @@ Hopefully you now fully understand the how a transformation matrix affects the object, and the relationship between the basis vectors and how the object's "UV" or "intra-coordinates" have their world position changed. -.. note:: In Godot, all transform math is done relative to the parent node. +Note: + In Godot, all transform math is done relative to the parent node. When we refer to "world position", that would be relative to the node's parent instead, if the node had a parent. @@ -365,7 +375,8 @@ gdscript GDScript print(transform.xform_inv(Vector2(0, 100))) ``` -.. note:: If you know in advance that the transform is positioned at +Note: + If you know in advance that the transform is positioned at (0, 0), you can use the "basis_xform" or "basis_xform_inv" methods instead, which skip dealing with translation. @@ -390,7 +401,8 @@ gdscript GDScript For moving in 3D, you would need to replace "x" with "basis.x". -.. note:: In actual projects, you can use `translate_object_local` in 3D +Note: + In actual projects, you can use `translate_object_local` in 3D or `move_local_x` and `move_local_y` in 2D to do this. Applying transforms onto transforms @@ -457,7 +469,8 @@ gdscript GDScript transform = parent * child ``` -.. note:: When multiplying matrices, order matters! Don't mix them up. +Note: + When multiplying matrices, order matters! Don't mix them up. Lastly, applying the identity transform will always do nothing. @@ -521,12 +534,14 @@ this project which has colored lines and cubes to help visualize the `Basis` vectors and the origin in both 2D and 3D: https://github.com/godotengine/godot-demo-projects/tree/master/misc/matrix_transform -.. note:: Spatial's "Matrix" section in Godot 3.2's inspector +Note: + Spatial's "Matrix" section in Godot 3.2's inspector displays the matrix as transposed, with the columns horizontal and the rows vertical. This may be changed to be less confusing in a future release of Godot. -.. note:: You cannot edit Node2D's transform matrix directly in Godot 3.2's +Note: + You cannot edit Node2D's transform matrix directly in Godot 3.2's inspector. This may be changed in a future release of Godot. If you would like additional explanation, you should check out diff --git a/tutorials/math/random_number_generation.md b/tutorials/math/random_number_generation.md index fc532e2..82e5e37 100644 --- a/tutorials/math/random_number_generation.md +++ b/tutorials/math/random_number_generation.md @@ -11,7 +11,8 @@ After giving you a brief overview of useful functions that generate random numbers, you will learn how to get random elements from arrays, dictionaries, and how to use a noise generator in GDScript. -.. note:: +Note: + Computers cannot generate "true" random numbers. Instead, they rely on `pseudorandom number generators diff --git a/tutorials/math/vector_math.md b/tutorials/math/vector_math.md index 1974480..3f48eb7 100644 --- a/tutorials/math/vector_math.md +++ b/tutorials/math/vector_math.md @@ -12,7 +12,8 @@ their uses. Vectors have many applications in both 2D and 3D development and Godot uses them extensively. Developing a good understanding of vector math is essential to becoming a strong game developer. -.. note:: This tutorial is **not** a formal textbook on linear algebra. We +Note: + This tutorial is **not** a formal textbook on linear algebra. We will only be looking at how it is applied to game development. For a broader look at the mathematics, see https://www.khanacademy.org/math/linear-algebra @@ -26,7 +27,8 @@ as a pair of values such as `(4, 3)`. ![](img/vector_axis1.png) -.. note:: If you're new to computer graphics, it might seem odd that the +Note: + If you're new to computer graphics, it might seem odd that the positive `y` axis points **downwards** instead of upwards, as you probably learned in math class. However, this is common in most computer graphics applications. @@ -110,7 +112,8 @@ Note that adding `a + b` gives the same result as `b + a`. Scalar multiplication --------------------- -.. note:: Vectors represent both direction and magnitude. A value +Note: + Vectors represent both direction and magnitude. A value representing only magnitude is called a **scalar**. A vector can be multiplied by a **scalar**: @@ -124,7 +127,8 @@ gdscript GDScript ![](img/vector_mult1.png) -.. note:: Multiplying a vector by a scalar does not change its direction, +Note: + Multiplying a vector by a scalar does not change its direction, only its magnitude. This is how you **scale** a vector. Practical applications @@ -179,7 +183,8 @@ gdscript GDScript ``` -.. warning:: Because normalization involves dividing by the vector's length, +Warning: + Because normalization involves dividing by the vector's length, you cannot normalize a vector of length `0`. Attempting to do so will result in an error. @@ -308,7 +313,8 @@ gdscript GDScript var c = a.cross(b) ``` -.. note:: In the cross product, order matters. `a.cross(b)` does not +Note: + In the cross product, order matters. `a.cross(b)` does not give the same result as `b.cross(a)`. The resulting vectors point in **opposite** directions. diff --git a/tutorials/navigation/real_time_navigation_3d.md b/tutorials/navigation/real_time_navigation_3d.md index 298dd87..2b881be 100644 --- a/tutorials/navigation/real_time_navigation_3d.md +++ b/tutorials/navigation/real_time_navigation_3d.md @@ -35,7 +35,8 @@ button at the top of the inspector to generate it. ![](img/bake_navmesh.png) -.. note:: +Note: + It can also be generated at runtime using the `bake_navigation_region()` method of the navigation region node. diff --git a/tutorials/networking/high_level_multiplayer.md b/tutorials/networking/high_level_multiplayer.md index 9afb790..636b013 100644 --- a/tutorials/networking/high_level_multiplayer.md +++ b/tutorials/networking/high_level_multiplayer.md @@ -25,13 +25,15 @@ Because of the large difference in performance, it often makes sense to re-build In summary, you can use the low-level networking API for maximum control and implement everything on top of bare network protocols or use the high-level API based on `SceneTree` that does most of the heavy lifting behind the scenes in a generally optimized way. -.. note:: Most of Godot's supported platforms offer all or most of the mentioned high- and low-level networking +Note: + Most of Godot's supported platforms offer all or most of the mentioned high- and low-level networking features. As networking is always largely hardware and operating system dependent, however, some features may change or not be available on some target platforms. Most notably, the HTML5 platform currently offers WebSockets and WebRTC support but lacks some of the higher-level features, as well as raw access to low-level protocols like TCP and UDP. -.. note:: More about TCP/IP, UDP, and networking: +Note: + More about TCP/IP, UDP, and networking: https://gafferongames.com/post/udp_vs_tcp/ Gaffer On Games has a lot of useful articles about networking in Games @@ -42,7 +44,8 @@ In summary, you can use the low-level networking API for maximum control and imp see here for an example: https://github.com/PerduGames/gdnet3 -.. warning:: Adding networking to your game comes with some responsibility. +Warning: + Adding networking to your game comes with some responsibility. It can make your application vulnerable if done wrong and may lead to cheats or exploits. It may even allow an attacker to compromise the machines your application runs on and use your servers to send spam, attack others or steal your users data if they play your game. @@ -115,7 +118,8 @@ Terminating the networking feature: (Although it may make sense to send a message first to let the other peers know you're going away instead of letting the connection close or timeout, depending on your game.) -.. warning:: +Warning: + When exporting to Android, make sure to enable the `INTERNET` permission in the Android export preset before exporting the project or @@ -246,7 +250,8 @@ This keyword is one of many that allow a function to be called by a remote proce Each of them designate who can call the rpc, and optionally `sync` if the RPC can be called locally. -.. note:: If no rpc keywords are added, Godot will block any attempts to call functions remotely. +Note: + If no rpc keywords are added, Godot will block any attempts to call functions remotely. This makes security work a lot easier (so a client can't call a function to delete a file on another client's system). The `remote` keyword can be called by any peer, including the server and all clients. @@ -313,7 +318,8 @@ every peer and RPC will work great! Here is an example: rpc_id(1, "done_preconfiguring") -.. note:: Depending on when you execute pre_configure_game(), you may need to change any calls to `add_child()` +Note: + Depending on when you execute pre_configure_game(), you may need to change any calls to `add_child()` to be deferred via `call_deferred()`, as the SceneTree is locked while the scene is being created (e.g. when `_ready()` is being called). Synchronizing game start @@ -476,14 +482,16 @@ Once you've made a multiplayer game, you may want to export it to run it on a dedicated server with no GPU available. See `doc_exporting_for_dedicated_servers` for more information. -.. note:: +Note: + The code samples on this page aren't designed to run on a dedicated server. You'll have to modify them so the server isn't considered to be a player. You'll also have to modify the game starting mechanism so that the first player who joins can start the game. -.. note:: +Note: + The bomberman example here is largely for illustrational purposes, and does not do anything on the host-side to handle the case where a peer uses a custom client diff --git a/tutorials/networking/http_client_class.md b/tutorials/networking/http_client_class.md index 5e1b857..caf32ab 100644 --- a/tutorials/networking/http_client_class.md +++ b/tutorials/networking/http_client_class.md @@ -7,7 +7,8 @@ HTTP client class For a higher-level interface, you may want to take a look at `HTTPRequest` first, which has a tutorial available `here ( doc_http_request_class )`. -.. warning:: +Warning: + When exporting to Android, make sure to enable the `INTERNET` permission in the Android export preset before exporting the project or diff --git a/tutorials/networking/http_request_class.md b/tutorials/networking/http_request_class.md index 533e202..bd871ee 100644 --- a/tutorials/networking/http_request_class.md +++ b/tutorials/networking/http_request_class.md @@ -8,7 +8,8 @@ It is backed by the more low-level `HTTPClient`. For the sake of this example, we will create a simple UI with a button, that when pressed will start the HTTP request to the specified URL. -.. warning:: +Warning: + When exporting to Android, make sure to enable the `INTERNET` permission in the Android export preset before exporting the project or diff --git a/tutorials/networking/webrtc.md b/tutorials/networking/webrtc.md index e391fda..728e0f8 100644 --- a/tutorials/networking/webrtc.md +++ b/tutorials/networking/webrtc.md @@ -35,9 +35,11 @@ Using WebRTC in Godot WebRTC is implemented in Godot via two main classes `WebRTCPeerConnection` for more details. -.. note:: These classes are available automatically in HTML5, but **require an external GDNative plugin on native (non-HTML5) platforms**. Check out the `webrtc-native plugin repository ( https://github.com/godotengine/webrtc-native )` for instructions and to get the latest `release ( https://github.com/godotengine/webrtc-native/releases )`. +Note: + These classes are available automatically in HTML5, but **require an external GDNative plugin on native (non-HTML5) platforms**. Check out the `webrtc-native plugin repository ( https://github.com/godotengine/webrtc-native )` for instructions and to get the latest `release ( https://github.com/godotengine/webrtc-native/releases )`. + +Warning: -.. warning:: When exporting to Android, make sure to enable the `INTERNET` permission in the Android export preset before exporting the project or @@ -147,7 +149,8 @@ This example expands on the previous one, separating the peers in two different And now for the local signaling server: -.. note:: This local signaling server is supposed to be used as a `singleton ( doc_singletons_autoload )` to connect two peers in the same scene. +Note: + This local signaling server is supposed to be used as a `singleton ( doc_singletons_autoload )` to connect two peers in the same scene. :: diff --git a/tutorials/networking/websocket.md b/tutorials/networking/websocket.md index ceedeb1..6139a49 100644 --- a/tutorials/networking/websocket.md +++ b/tutorials/networking/websocket.md @@ -20,7 +20,8 @@ Using WebSocket in Godot WebSocket is implemented in Godot via three main classes `WebSocketClient` for more details. -.. warning:: +Warning: + When exporting to Android, make sure to enable the `INTERNET` permission in the Android export preset before exporting the project or diff --git a/tutorials/performance/batching.md b/tutorials/performance/batching.md index ad251e2..ac944fa 100644 --- a/tutorials/performance/batching.md +++ b/tutorials/performance/batching.md @@ -69,7 +69,8 @@ Batching will be broken by (amongst other things): - Change of material. - Change of primitive type (say, going from rectangles to lines). -.. note:: +Note: + For example, if you draw a series of sprites each with a different texture, there is no way they can be batched. @@ -95,7 +96,8 @@ In Godot, this back-to-front order is determined by: - The canvas layer. - `YSort` nodes. -.. note:: +Note: + You can group similar objects together for easier batching. While doing so is not a requirement on your part, think of it as an optional approach that diff --git a/tutorials/performance/cpu_optimization.md b/tutorials/performance/cpu_optimization.md index c69d8f1..cae91b1 100644 --- a/tutorials/performance/cpu_optimization.md +++ b/tutorials/performance/cpu_optimization.md @@ -34,7 +34,8 @@ After profiling, you can look back at the results for a frame. Results of a profile of one of the demo projects. -.. note:: We can see the cost of built-in processes such as physics and audio, +Note: + We can see the cost of built-in processes such as physics and audio, as well as seeing the cost of our own scripting functions at the bottom. @@ -61,7 +62,8 @@ You can use a number of third party profilers to do this including `Visual Studio ( https://visualstudio.microsoft.com/ )` and `Intel VTune ( https://software.intel.com/content/www/us/en/develop/tools/vtune-profiler.html )`. -.. note:: You will need to compile Godot from source to use a third-party profiler. +Note: + You will need to compile Godot from source to use a third-party profiler. This is required to obtain debugging symbols. You can also use a debug build, however, note that the results of profiling a debug build will be different to a release build, because debug builds are less diff --git a/tutorials/performance/gpu_optimization.md b/tutorials/performance/gpu_optimization.md index 4e8fb32..1767732 100644 --- a/tutorials/performance/gpu_optimization.md +++ b/tutorials/performance/gpu_optimization.md @@ -25,7 +25,8 @@ performance is by examining changes in the time spent rendering each frame. Draw calls, state changes, and APIs =================================== -.. note:: The following section is not relevant to end-users, but is useful to +Note: + The following section is not relevant to end-users, but is useful to provide background information that is relevant in later sections. Godot sends instructions to the GPU via a graphics API (OpenGL, OpenGL ES or @@ -213,7 +214,8 @@ more noticeable. As a warning, most Android devices do not support texture compression of textures with transparency (only opaque), so keep this in mind. -.. note:: +Note: + Even in 3D, "pixel art" textures should have VRAM compression disabled as it will negatively affect their appearance, without improving performance diff --git a/tutorials/performance/optimizing_3d_performance.md b/tutorials/performance/optimizing_3d_performance.md index 8639ed7..067b5c5 100644 --- a/tutorials/performance/optimizing_3d_performance.md +++ b/tutorials/performance/optimizing_3d_performance.md @@ -54,7 +54,8 @@ lights. See `doc_rooms_and_portals`. This is not a fully automatic system and it requires some manual setup. However, it potentially offers significant performance increases. -.. note:: +Note: + In some cases, you can adapt your level design to add more occlusion opportunities. For example, you can add more walls to prevent the player diff --git a/tutorials/performance/threads/using_multiple_threads.md b/tutorials/performance/threads/using_multiple_threads.md index 6b71227..05b1acd 100644 --- a/tutorials/performance/threads/using_multiple_threads.md +++ b/tutorials/performance/threads/using_multiple_threads.md @@ -11,10 +11,12 @@ from the main thread. Godot supports threads and provides many handy functions to use them. -.. note:: If using other languages (C#, C++), it may be easier to use the +Note: + If using other languages (C#, C++), it may be easier to use the threading classes they support. -.. warning:: +Warning: + Before using a built-in class in a thread, read `doc_thread_safe_apis` first to check whether it can be safely used in a thread. diff --git a/tutorials/performance/using_servers.md b/tutorials/performance/using_servers.md index 5173beb..c088388 100644 --- a/tutorials/performance/using_servers.md +++ b/tutorials/performance/using_servers.md @@ -52,7 +52,8 @@ Most Godot nodes and resources contain these RIDs from the servers internally, a be obtained with different functions. In fact, anything that inherits `Resource` can be directly casted to an RID. Not all resources contain an RID, though: in such cases, the RID will be empty. The resource can then be passed to server APIs as an RID. -.. Warning:: Resources are reference-counted (see `Reference`), and +Warning: + Resources are reference-counted (see `Reference`), and references to a resource's RID are *not* counted when determining whether the resource is still in use. Make sure to keep a reference to the resource outside the server, or else both it and its RID will be erased. diff --git a/tutorials/performance/vertex_animation/animating_thousands_of_fish.md b/tutorials/performance/vertex_animation/animating_thousands_of_fish.md index 3a999a0..2ef0b2e 100644 --- a/tutorials/performance/vertex_animation/animating_thousands_of_fish.md +++ b/tutorials/performance/vertex_animation/animating_thousands_of_fish.md @@ -24,7 +24,8 @@ Here is the fish we will be using for the example images, you can use any fish m ![](img/fish.png) -.. note:: The fish model in this tutorial is made by `QuaterniusDev ( http://quaternius.com )`_ and is +Note: + The fish model in this tutorial is made by `QuaterniusDev ( http://quaternius.com )`_ and is shared with a creative commons license. CC0 1.0 Universal (CC0 1.0) Public Domain Dedication https://creativecommons.org/publicdomain/zero/1.0/ @@ -227,7 +228,8 @@ to loop over all the instances and set their transform to a random position. Running this script will place the fish in random positions in a box around the position of the MultiMeshInstance. -.. note:: If performance is an issue for you, try running the scene with GLES2 or with fewer fish. +Note: + If performance is an issue for you, try running the scene with GLES2 or with fewer fish. Notice how all the fish are all in the same position in their swim cycle? It makes them look very robotic. The next step is to give each fish a different position in the swim cycle so the entire diff --git a/tutorials/performance/vertex_animation/controlling_thousands_of_fish.md b/tutorials/performance/vertex_animation/controlling_thousands_of_fish.md index d24ff45..2b346f1 100644 --- a/tutorials/performance/vertex_animation/controlling_thousands_of_fish.md +++ b/tutorials/performance/vertex_animation/controlling_thousands_of_fish.md @@ -11,7 +11,8 @@ To make each instance move in an interesting way, we will use a `Particles` node. Particles take advantage of GPU acceleration by computing and setting the per-instance information in a `Shader`. -.. note:: Particles are not available in GLES2, instead use `CPUParticles`, +Note: + Particles are not available in GLES2, instead use `CPUParticles`, which do the same thing as Particles, but do not benefit from GPU acceleration. First create a Particles node. Then, under "Draw Passes" set the Particle's "Draw Pass 1" to your diff --git a/tutorials/physics/collision_shapes_3d.md b/tutorials/physics/collision_shapes_3d.md index 0e7cc9f..7cb95de 100644 --- a/tutorials/physics/collision_shapes_3d.md +++ b/tutorials/physics/collision_shapes_3d.md @@ -17,7 +17,8 @@ You can define the shape of a `PhysicsBody` by adding one or more add a `Shape` *resource* to collision shape nodes in the Inspector dock. -.. note:: +Note: + When you add multiple collision shapes to a single PhysicsBody, you don't have to worry about them overlapping. They won't "collide" with each other. @@ -81,7 +82,8 @@ triangles. Concave shapes are the slowest option but are also the most accurate in Godot. **You can only use concave shapes within StaticBodies.** They will not work with KinematicBodies or RigidBodies unless the RigidBody's mode is Static. -.. note:: +Note: + Even though concave shapes offer the most accurate *collision*, contact reporting can be less precise than primitive shapes. @@ -106,7 +108,8 @@ editor exposes two options: - **Create Trimesh Collision Sibling** creates a CollisionShape node with a concave shape matching the mesh's geometry. -.. note:: +Note: + Suppose you need to make a RigidBody *slide* on a concave collision shape. In that case, you may notice that sometimes, the RigidBody will bump @@ -118,7 +121,8 @@ editor exposes two options: without any rotation. This way, the RigidBody should slide perfectly on the StaticBody. -.. seealso:: +See also: + Godot can generate collision shapes for your imported 3D scenes automatically. See `doc_importing_scenes_import_hints` in the diff --git a/tutorials/physics/interpolation/advanced_physics_interpolation.md b/tutorials/physics/interpolation/advanced_physics_interpolation.md index b28844d..6288261 100644 --- a/tutorials/physics/interpolation/advanced_physics_interpolation.md +++ b/tutorials/physics/interpolation/advanced_physics_interpolation.md @@ -52,7 +52,8 @@ We can do this using the `Spatial.get_global_transform_interpolated( Spatial_met .. important:: `get_global_transform_interpolated()` should only be used once or twice for special cases such as Cameras. It should **not** be used all over the place in your code (both for performance reasons, and to give correct gameplay). -.. note:: Aside from exceptions like the Camera, in most cases, your game logic should be in `_physics_process()`. In game logic you should be calling `get_global_transform()` or `get_transform()`, which will give the current physics transform (in global or local space respectively), which is usually what you will want for gameplay code. +Note: + Aside from exceptions like the Camera, in most cases, your game logic should be in `_physics_process()`. In game logic you should be calling `get_global_transform()` or `get_transform()`, which will give the current physics transform (in global or local space respectively), which is usually what you will want for gameplay code. Example manual Camera script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/tutorials/physics/interpolation/physics_interpolation_introduction.md b/tutorials/physics/interpolation/physics_interpolation_introduction.md index e6ab56d..858d6ac 100644 --- a/tutorials/physics/interpolation/physics_interpolation_introduction.md +++ b/tutorials/physics/interpolation/physics_interpolation_introduction.md @@ -59,7 +59,8 @@ The simplest way to achieve this is linear interpolation, or lerping, which you Let us consider only the position, and a situation where we know that the previous physics tick X coordinate was 10 units, and the current physics tick X coordinate is 30 units. -.. note:: Although the maths is explained here, you do not have to worry about the details, as this step will be performed for you. Under the hood, Godot may use more complex forms of interpolation, but linear interpolation is the easiest in terms of explanation. +Note: + Although the maths is explained here, you do not have to worry about the details, as this step will be performed for you. Under the hood, Godot may use more complex forms of interpolation, but linear interpolation is the easiest in terms of explanation. The physics interpolation fraction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -98,7 +99,8 @@ Let's break that down: - We know that after the full tick, the difference between the current tick and the previous tick will have been added (`x_curr - x_prev`) (which is 20 units). - The only thing we need to vary is the proportion of this difference we add, according to how far we are through the physics tick. -.. note:: Although this example interpolates the position, the same thing can be done with the rotation and scale of objects. It is not necessary to know the details as Godot will do all this for you. +Note: + Although this example interpolates the position, the same thing can be done with the rotation and scale of objects. It is not necessary to know the details as Godot will do all this for you. Smoothed transformations between physics ticks? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/tutorials/physics/interpolation/using_physics_interpolation.md b/tutorials/physics/interpolation/using_physics_interpolation.md index f56dde7..926aef4 100644 --- a/tutorials/physics/interpolation/using_physics_interpolation.md +++ b/tutorials/physics/interpolation/using_physics_interpolation.md @@ -24,7 +24,8 @@ The most fundamental requirement for physics interpolation (which you may be doi Setting the transform of objects only within physics ticks allows the automatic interpolation to deal with transforms *between* physics ticks, and ensures the game will run the same whatever machine it is run on. As a bonus, this also reduces CPU usage if the game is rendering at high FPS, since AI logic (for example) will no longer run on every rendered frame. -.. note:: If you attempt to set the transform of interpolated objects *outside* the physics tick, the calculations for the interpolated position will be incorrect, and you will get jitter. This jitter may not be visible on your machine, but it *will* occur for some players. For this reason, setting the transform of interpolated objects should be avoided outside of the physics tick. Godot will attempt to produce warnings in the editor if this case is detected. +Note: + If you attempt to set the transform of interpolated objects *outside* the physics tick, the calculations for the interpolated position will be incorrect, and you will get jitter. This jitter may not be visible on your machine, but it *will* occur for some players. For this reason, setting the transform of interpolated objects should be avoided outside of the physics tick. Godot will attempt to produce warnings in the editor if this case is detected. .. tip:: This is only a *soft-rule*. There are some occasions where you might want to teleport objects outside of the physics tick (for instance when starting a level, or respawning objects). Still, in general, you should be applying transforms from the physics tick. @@ -34,7 +35,8 @@ Ensure that all indirect movement happens during physics ticks Consider that in Godot, Nodes can be moved not just directly in your own scripts, but also by automatic methods such as tweening, animation, and navigation. All these methods should also have their timing set to operate on the physics tick rather than each frame ("idle"), **if** you are using them to move objects (*these methods can also be used to control properties that are not interpolated*). -.. note:: Also consider that nodes can be moved not just by moving themselves, but also by moving parent nodes in the `SceneTree( SceneTree )`. The movement of parents should therefore also only occur during physics ticks. +Note: + Also consider that nodes can be moved not just by moving themselves, but also by moving parent nodes in the `SceneTree( SceneTree )`. The movement of parents should therefore also only occur during physics ticks. Choose a physics tick rate ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -51,7 +53,8 @@ As a rough guide: "Add some delay to input","Good for first person games","Good for racing games" "Simple physics behaviour" -.. note:: You can always change the tick rate as you develop, it is as simple as changing the project setting. +Note: + You can always change the tick rate as you develop, it is as simple as changing the project setting. Call reset_physics_interpolation() when teleporting objects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/tutorials/physics/physics_introduction.md b/tutorials/physics/physics_introduction.md index 70aee1f..8af01de 100644 --- a/tutorials/physics/physics_introduction.md +++ b/tutorials/physics/physics_introduction.md @@ -19,7 +19,8 @@ In this guide, you will learn: - How each collision object works - When and why to choose one type over another -.. note:: This document's examples will use 2D objects. Every 2D physics object +Note: + This document's examples will use 2D objects. Every 2D physics object and collision shape has a direct equivalent in 3D and in most cases they work in much the same way. @@ -65,7 +66,8 @@ A physics body can hold any number of `Shape2D` objects as children. These shapes are used to define the object's collision bounds and to detect contact with other objects. -.. note:: In order to detect collisions, at least one `Shape2D` must be +Note: + In order to detect collisions, at least one `Shape2D` must be assigned to the object. The most common way to assign a shape is by adding a `CollisionShape2D` @@ -96,7 +98,8 @@ parameter, which is a floating-point number equal to the time passed in *seconds* since the last step. When using the default 60 Hz physics update rate, it will typically be equal to `0.01666...` (but not always, see below). -.. note:: +Note: + It's recommended to always use the `delta` parameter when relevant in your physics calculations, so that the game behaves correctly if you change the @@ -288,7 +291,8 @@ Note that we are not setting the `linear_velocity` or `angular_velocity` properties directly, but rather applying forces (`thrust` and `torque`) to the body and letting the physics engine calculate the resulting movement. -.. note:: When a rigid body goes to sleep, the `_integrate_forces()` +Note: + When a rigid body goes to sleep, the `_integrate_forces()` function will not be called. To override this behavior, you will need to keep the body awake by creating a collision, applying a force to it, or by disabling the `can_sleep` @@ -377,7 +381,8 @@ possible to code this response yourself after using `move_and_collide()`, `move_and_slide()` provides a convenient way to implement sliding movement without writing much code. -.. warning:: `move_and_slide()` automatically includes the timestep in its +Warning: + `move_and_slide()` automatically includes the timestep in its calculation, so you should **not** multiply the velocity vector by `delta`. diff --git a/tutorials/physics/ragdoll_system.md b/tutorials/physics/ragdoll_system.md index f54e7e5..d9ebe7e 100644 --- a/tutorials/physics/ragdoll_system.md +++ b/tutorials/physics/ragdoll_system.md @@ -10,7 +10,8 @@ Since version 3.1, Godot supports ragdoll physics. Ragdolls rely on physics simu In this tutorial, we will be using the Platformer3D demo to set up a ragdoll. -.. note:: You can download the Platformer3D demo on `GitHub ( https://github.com/godotengine/godot-demo-projects/tree/master/3d/platformer )`_ or using the `Asset Library ( https://godotengine.org/asset-library/asset/125 )`_. +Note: + You can download the Platformer3D demo on `GitHub ( https://github.com/godotengine/godot-demo-projects/tree/master/3d/platformer )`_ or using the `Asset Library ( https://godotengine.org/asset-library/asset/125 )`_. Setting up the ragdoll ---------------------- diff --git a/tutorials/physics/rigid_body.md b/tutorials/physics/rigid_body.md index e16f1bc..1247334 100644 --- a/tutorials/physics/rigid_body.md +++ b/tutorials/physics/rigid_body.md @@ -52,4 +52,5 @@ gdscript GDScript This method uses the rigid body's `set_angular_velocity()` method to rotate the body. It first calculates the difference between the current and desired angle and then adds the velocity needed to rotate by that amount in one frame's time. -.. note:: This script will not work with rigid bodies in *character mode* because then, the body's rotation is locked. In that case, you would have to rotate the attached mesh node instead using the standard Spatial methods. +Note: + This script will not work with rigid bodies in *character mode* because then, the body's rotation is locked. In that case, you would have to rotate the attached mesh node instead using the standard Spatial methods. diff --git a/tutorials/physics/soft_body.md b/tutorials/physics/soft_body.md index 103fa44..461c021 100644 --- a/tutorials/physics/soft_body.md +++ b/tutorials/physics/soft_body.md @@ -21,7 +21,8 @@ Set the parameters to obtain the type of soft body you aim for. Try to keep the ![](img/softbody_cube_menu.png) -.. note:: Handle some parameters with care, as some value can lead to strange results. For example, if the shape is not completely closed and you set pressure to more than 0, the softbody will fly around like a plastic bag under strong wind. +Note: + Handle some parameters with care, as some value can lead to strange results. For example, if the shape is not completely closed and you set pressure to more than 0, the softbody will fly around like a plastic bag under strong wind. Play the scene to view the simulation. @@ -32,7 +33,8 @@ Cloak simulation Let's make a cloak in the Platformer3D demo. -.. note:: You can download the Platformer3D demo on `GitHub ( https://github.com/godotengine/godot-demo-projects/tree/master/3d/platformer )`_ or `the Asset Library ( https://godotengine.org/asset-library/asset/125 )`_. +Note: + You can download the Platformer3D demo on `GitHub ( https://github.com/godotengine/godot-demo-projects/tree/master/3d/platformer )`_ or `the Asset Library ( https://godotengine.org/asset-library/asset/125 )`_. Open the `Player` scene, add a `SoftBody` node and assign a `PlaneMesh` to it. @@ -44,7 +46,8 @@ Open the `PlaneMesh` properties and set the size(x: 0.5 y: 1) then set `Subdivid Add a `BoneAttachment` node under the skeleton node and select the Neck bone to attach the cloak to the character skeleton. -.. note:: `BoneAttachment` node is to attach objects to a bone of a armature. The attached object will follow the bone's movement, weapon of a character can be attached this way. +Note: + `BoneAttachment` node is to attach objects to a bone of a armature. The attached object will follow the bone's movement, weapon of a character can be attached this way. ![](img/softbody_cloak_bone_attach.png) diff --git a/tutorials/physics/using_area_2d.md b/tutorials/physics/using_area_2d.md index a38f8b9..3748d85 100644 --- a/tutorials/physics/using_area_2d.md +++ b/tutorials/physics/using_area_2d.md @@ -12,7 +12,8 @@ You can avoid problems and simplify development if you understand how each of th works and what their pros and cons are. In this tutorial, we'll look at the `Area2D` node and show some examples of how it can be used. -.. note:: This document assumes you're familiar with Godot's various physics +Note: + This document assumes you're familiar with Godot's various physics bodies. Please read `doc_physics_introduction` first. What is an area? @@ -65,7 +66,8 @@ use `area_entered`. However, let's assume our player is a `KinematicBody2D` (and therefore a `CollisionObject2D` type), so we'll connect the `body_entered` signal. -.. note:: If you're not familiar with using signals, see `doc_signals` for +Note: + If you're not familiar with using signals, see `doc_signals` for an introduction. gdscript GDScript diff --git a/tutorials/physics/using_kinematic_body_2d.md b/tutorials/physics/using_kinematic_body_2d.md index ccdd6b9..19e158e 100644 --- a/tutorials/physics/using_kinematic_body_2d.md +++ b/tutorials/physics/using_kinematic_body_2d.md @@ -13,7 +13,8 @@ works and what their pros and cons are. In this tutorial, we'll look at the `KinematicBody2D` node and show some examples of how to use it. -.. note:: This document assumes you're familiar with Godot's various physics +Note: + This document assumes you're familiar with Godot's various physics bodies. Please read `doc_physics_introduction` first. What is a kinematic body? @@ -38,7 +39,8 @@ These methods move the body along a given vector and instantly stop if a collision is detected with another body. After a KinematicBody2D has collided, any *collision response* must be coded manually. -.. warning:: You should only do Kinematic body movement in the `_physics_process()` callback. +Warning: + You should only do Kinematic body movement in the `_physics_process()` callback. The two movement methods serve different purposes, and later in this tutorial, you'll see examples of how they work. @@ -131,7 +133,8 @@ gdscript GDScript print("I collided with ", collision.collider.name) ``` -.. note:: `get_slide_count()` only counts times the body has collided and changed direction. +Note: + `get_slide_count()` only counts times the body has collided and changed direction. See `KinematicCollision2D` for details on what collision data is returned. @@ -196,7 +199,8 @@ from the Filesystem dock to the *Texture* property of the `Sprite`). In the `CollisionShape2D`'s *Shape* property, select "New RectangleShape2D" and size the rectangle to fit over the sprite image. -.. note:: See `doc_2d_movement` for examples of implementing 2D movement schemes. +Note: + See `doc_2d_movement` for examples of implementing 2D movement schemes. Attach a script to the KinematicBody2D and add the following code: diff --git a/tutorials/platform/consoles.md b/tutorials/platform/consoles.md index bec16b9..8a64c87 100644 --- a/tutorials/platform/consoles.md +++ b/tutorials/platform/consoles.md @@ -45,7 +45,8 @@ officially supported are: However, it is still possible to port your games to consoles thanks to services provided by third-party companies. -.. note:: +Note: + In practice, the process is quite similar to Unity and Unreal Engine, except that you need to contact a third-party developer to handle the porting diff --git a/tutorials/platform/customizing_html5_shell.md b/tutorials/platform/customizing_html5_shell.md index 8868e15..670279c 100644 --- a/tutorials/platform/customizing_html5_shell.md +++ b/tutorials/platform/customizing_html5_shell.md @@ -133,7 +133,8 @@ This process is a bit more complex, but gives you full control over the engine s To load the engine manually the :js:meth:`Engine.load` static method must be called. As this method is static, multiple engine instances can be spawned if the share the same `wasm`. -.. note:: Multiple instances cannot be spawned by default, as the engine is immediately unloaded after it is initialized. +Note: + Multiple instances cannot be spawned by default, as the engine is immediately unloaded after it is initialized. To prevent this from happening see the :js:attr:`unloadAfterInit` override option. It is still possible to unload the engine manually afterwards by calling the :js:meth:`Engine.unload` static method. Unloading the engine frees browser memory by unloading files that are no longer needed once the instance is initialized. diff --git a/tutorials/platform/ios/ios_plugin.md b/tutorials/platform/ios/ios_plugin.md index 84e56b7..be9c2de 100644 --- a/tutorials/platform/ios/ios_plugin.md +++ b/tutorials/platform/ios/ios_plugin.md @@ -39,7 +39,8 @@ An iOS plugin can have the same functionality as a Godot module but provides mor Here are the steps to get a plugin's development started. We recommend using `Xcode ( https://developer.apple.com/develop/ )`_ as your development environment. -.. seealso:: The `Godot iOS Plugins ( https://github.com/godotengine/godot-ios-plugins )`_ Godot iOS plugins. +See also: + The `Godot iOS Plugins ( https://github.com/godotengine/godot-ios-plugins )`_ Godot iOS plugins. The `Godot iOS plugin template ( https://github.com/naithar/godot_ios_plugin )`_ gives you all the boilerplate you need to get your iOS plugin started. diff --git a/tutorials/platform/mobile_rendering_limitations.md b/tutorials/platform/mobile_rendering_limitations.md index 6b5213c..9820446 100644 --- a/tutorials/platform/mobile_rendering_limitations.md +++ b/tutorials/platform/mobile_rendering_limitations.md @@ -3,7 +3,8 @@ Mobile rendering limitations ============================ -.. seealso:: +See also: + The general `doc_3d_rendering_limitations` also apply to mobile platforms. @@ -63,7 +64,8 @@ project settings' values to match the mobile overrides. This way, you'll get a preview that is closer to the mobile appearance when running the project on a desktop platform (as well as within the editor). -.. warning:: +Warning: + Due to driver bugs, GLES3 support on Android and iOS can be poor, especially on old or low-end devices. Therefore, it is recommended to use the GLES2 diff --git a/tutorials/plugins/editor/import_plugins.md b/tutorials/plugins/editor/import_plugins.md index 6f44132..fff28cf 100644 --- a/tutorials/plugins/editor/import_plugins.md +++ b/tutorials/plugins/editor/import_plugins.md @@ -3,7 +3,8 @@ Import plugins ============== -.. note:: This tutorial assumes you already know how to make generic plugins. If +Note: + This tutorial assumes you already know how to make generic plugins. If in doubt, refer to the `doc_making_plugins` page. This also assumes you are acquainted with Godot's import system. @@ -160,7 +161,8 @@ property in the Inspector. In our case it's a `SpatialMaterial`, which can be applied to 3D objects. -.. note:: If you need to import different types from the same extension, you +Note: + If you need to import different types from the same extension, you have to create multiple import plugins. You can abstract the import code on another file to avoid duplication in this regard. @@ -264,7 +266,8 @@ value). In this example we use the `match` statement, but if you have lots of options and the presets only change the value you may want to create the array of options first and then change it based on the preset. -.. warning:: The `get_import_options` method is called even if you don't +Warning: + The `get_import_options` method is called even if you don't define presets (by making `get_preset_count` return zero). You have to return an array even it's empty, otherwise you can get errors. diff --git a/tutorials/plugins/editor/inspector_plugins.md b/tutorials/plugins/editor/inspector_plugins.md index 9099a1a..bf3fcc6 100644 --- a/tutorials/plugins/editor/inspector_plugins.md +++ b/tutorials/plugins/editor/inspector_plugins.md @@ -25,7 +25,8 @@ Setting up your plugin Create a new empty plugin to get started. -.. seealso:: See `doc_making_plugins` guide to set up your new plugin. +See also: + See `doc_making_plugins` guide to set up your new plugin. Let's assume you've called your plugin folder `my_inspector_plugin`. If so, you should end up with a new `addons/my_inspector_plugin` folder that contains @@ -38,7 +39,8 @@ the instance by calling `add_inspector_plugin()`. If the plugin is disabled, you should remove the instance you have added by calling `remove_inspector_plugin()`. -.. note:: Here, you are loading a script and not a packed scene. Therefore you +Note: + Here, you are loading a script and not a packed scene. Therefore you should use `new()` instead of `instance()`. gdscript GDScript @@ -72,7 +74,8 @@ To have any effect at all, the script must implement the `can_handle()` method. This function is called for each edited `Object` and must return `true` if this plugin should handle the object or its properties. -.. note:: This includes any `Resource` attached to the object. +Note: + This includes any `Resource` attached to the object. You can implement four other methods to add controls to the inspector at specific positions. The `parse_begin()` and `parse_end()` methods are called diff --git a/tutorials/plugins/editor/installing_plugins.md b/tutorials/plugins/editor/installing_plugins.md index 9a416a2..9338b48 100644 --- a/tutorials/plugins/editor/installing_plugins.md +++ b/tutorials/plugins/editor/installing_plugins.md @@ -19,7 +19,8 @@ To do so, click the **AssetLib** tab at the top of the editor: You can also find assets on code hosting websites such as GitHub. -.. note:: +Note: + Some repositories describe themselves as "plugins" but may not actually be *editor* plugins. This is especially the case for scripts that are intended diff --git a/tutorials/plugins/editor/making_plugins.md b/tutorials/plugins/editor/making_plugins.md index df13991..4ea574b 100644 --- a/tutorials/plugins/editor/making_plugins.md +++ b/tutorials/plugins/editor/making_plugins.md @@ -56,7 +56,8 @@ ini GDScript Activate now: No ``` -.. warning:: +Warning: + Unchecking the `Activate now?` option in C# is always required because, like every other C# script, the EditorPlugin script needs to be compiled which @@ -83,7 +84,8 @@ EditorPlugin script for you. The script has two requirements that you cannot change: it must be a `tool` script, or else it will not load properly in the editor, and it must inherit from `EditorPlugin`. -.. warning:: +Warning: + In addition to the EditorPlugin script, any other GDScript that your plugin uses must *also* be a tool. Any GDScript without `tool` imported into the editor @@ -126,7 +128,8 @@ sometimes it can be cumbersome, especially if you're using it in many projects. A good solution to this is to make a plugin that adds a node with a custom behavior. -.. warning:: +Warning: + Nodes added via an EditorPlugin are "CustomType" nodes. While they work with any scripting language, they have fewer features than diff --git a/tutorials/plugins/editor/spatial_gizmos.md b/tutorials/plugins/editor/spatial_gizmos.md index 8b6fe2f..b30d742 100644 --- a/tutorials/plugins/editor/spatial_gizmos.md +++ b/tutorials/plugins/editor/spatial_gizmos.md @@ -13,7 +13,8 @@ This tutorial will show you the two main approaches to defining your own custom gizmos. The first option works well for simple gizmos and creates less clutter in your plugin structure, while the second one will let you store some per-gizmo data. -.. note:: This tutorial assumes you already know how to make generic plugins. If +Note: + This tutorial assumes you already know how to make generic plugins. If in doubt, refer to the `doc_making_plugins` page. The EditorSpatialGizmoPlugin diff --git a/tutorials/plugins/running_code_in_the_editor.md b/tutorials/plugins/running_code_in_the_editor.md index 4f8800a..cb08287 100644 --- a/tutorials/plugins/running_code_in_the_editor.md +++ b/tutorials/plugins/running_code_in_the_editor.md @@ -66,7 +66,8 @@ gdscript GDScript # Code to execute both in editor and in game. ``` -.. note:: Modifications in editor are permanent. For example, in the following case, when we remove the script, the node will keep its rotation. Be careful to avoid making unwanted modifications. +Note: + Modifications in editor are permanent. For example, in the following case, when we remove the script, the node will keep its rotation. Be careful to avoid making unwanted modifications. Try it out ----------- @@ -87,7 +88,8 @@ Save the script and return to the editor. You should now see your object rotate. ![](img/rotating_in_editor.gif) -.. note:: If you don't see the changes, reload the scene (close it and open it again). +Note: + If you don't see the changes, reload the scene (close it and open it again). Now let's choose which code runs when. Modify your `_process()` function to look like this: @@ -129,7 +131,8 @@ gdscript GDScript ``` -.. note:: Code from other nodes doesn't run in the editor. Your access to other nodes is limited. You can access the tree and nodes, and their default properties, but you can't access user variables. If you want to do so, other nodes have to run in the editor too. AutoLoad nodes cannot be accessed in the editor at all. +Note: + Code from other nodes doesn't run in the editor. Your access to other nodes is limited. You can access the tree and nodes, and their default properties, but you can't access user variables. If you want to do so, other nodes have to run in the editor too. AutoLoad nodes cannot be accessed in the editor at all. Instancing scenes ----------------- @@ -171,4 +174,5 @@ gdscript GDScript node.set_owner(get_scene()) ``` -.. warning:: Using `tool` improperly can yield many errors. It is advised to first write the code how you want it, and only then add the `tool` keyword to the top. Also, make sure to separate code that runs in-editor from code that runs in-game. This way, you can find bugs more easily. +Warning: + Using `tool` improperly can yield many errors. It is advised to first write the code how you want it, and only then add the `tool` keyword to the top. Also, make sure to separate code that runs in-editor from code that runs in-game. This way, you can find bugs more easily. diff --git a/tutorials/rendering/jitter_stutter.md b/tutorials/rendering/jitter_stutter.md index 5d42078..c7fb6f4 100644 --- a/tutorials/rendering/jitter_stutter.md +++ b/tutorials/rendering/jitter_stutter.md @@ -40,7 +40,8 @@ time sources (one is processed in the physics step while another is processed in improvements to this, from allowing kinematic bodies to be animated in the regular _process loop, to further fixes in the frame timer. -.. note:: +Note: + You can use physics interpolation to mitigate physics-related jittering. See `lawnjelly's smoothing-addon ( https://github.com/lawnjelly/smoothing-addon )` diff --git a/tutorials/rendering/multiple_resolutions.md b/tutorials/rendering/multiple_resolutions.md index d402dd8..78d8c6f 100644 --- a/tutorials/rendering/multiple_resolutions.md +++ b/tutorials/rendering/multiple_resolutions.md @@ -67,7 +67,8 @@ that are different from this base size. Godot offers many ways to control how the viewport will be resized and stretched to different screen sizes. -.. note:: +Note: + Godot follows a modern approach to multiple resolutions. The engine will never change the monitor's resolution on its own. While changing the @@ -291,7 +292,8 @@ Desktop game - If using the `expand` stretch aspect, Configure Control nodes' anchors to snap to the correct corners using the **Layout** menu. -.. note:: +Note: + The `viewport` stretch mode provides low-resolution rendering that is then stretched to the final window size. If you are OK with sprites being able to @@ -356,7 +358,8 @@ Non-game application script's `_ready()` function. This prevents the user from resizing the application below a certain size, which could break the UI layout. -.. note:: +Note: + Godot doesn't support manually overriding the 2D scale factor yet, so it is not possible to have hiDPI support in non-game applications. Due to this, it @@ -379,7 +382,8 @@ Project Settings. **Allow Hidpi** is only effective on Windows and macOS. It's ignored on all other platforms. -.. note:: +Note: + The Godot editor itself is always marked as DPI-aware. Running the project from the editor will only be DPI-aware if **Allow Hidpi** is enabled in the diff --git a/tutorials/rendering/viewports.md b/tutorials/rendering/viewports.md index 1c9dfd7..77b5b96 100644 --- a/tutorials/rendering/viewports.md +++ b/tutorials/rendering/viewports.md @@ -182,7 +182,8 @@ If you know how the `Viewport` is going to be used, you can set its Usage to eit restrict how the `Viewport` is drawn to in accordance with your choice; default is 3D. The 2D usage mode is slightly faster and uses less memory compared to the 3D one. It's a good idea to set the `Viewport`'s Usage property to 2D if your viewport doesn't render anything in 3D. -.. note:: +Note: + If you need to render 3D shadows in the viewport, make sure to set the viewport's *Shadow Atlas Size* property to a value higher than 0. Otherwise, shadows won't be rendered. For reference, the Project Settings define it to 4096 by default. @@ -211,7 +212,8 @@ Overdraw draws the meshes semi-transparent with an additive blend so you can see Lastly, Wireframe draws the scene using only the edges of triangles in the meshes. -.. note:: +Note: + The effects of the Wireframe mode are only visible in the editor, not while the project is running. diff --git a/tutorials/scripting/creating_script_templates.md b/tutorials/scripting/creating_script_templates.md index fb125dc..c1cf8e3 100644 --- a/tutorials/scripting/creating_script_templates.md +++ b/tutorials/scripting/creating_script_templates.md @@ -49,7 +49,8 @@ out of templates, it's possible to create a template which can be recognized by that language according to template's file extension. For GDScript and C#, the extensions must be `gd` and `cs` respectively. -.. note:: The script templates have the same extension as the regular script +Note: + The script templates have the same extension as the regular script files. This may lead to an issue of a script parser treating those templates as actual scripts within a project. To avoid this, make sure to ignore the directory containing them by creating an empty `.gdignore` file. The directory won't be diff --git a/tutorials/scripting/cross_language_scripting.md b/tutorials/scripting/cross_language_scripting.md index 1bbed79..35e7c5e 100644 --- a/tutorials/scripting/cross_language_scripting.md +++ b/tutorials/scripting/cross_language_scripting.md @@ -52,7 +52,8 @@ with `new()`. var my_csharp_node = my_csharp_script.new() print(my_csharp_node.str2) # barbar -.. warning:: +Warning: + When creating `.cs` scripts, you should always keep in mind that the class Godot will use is the one named like the `.cs` file itself. If that class @@ -164,7 +165,8 @@ to said method. myGDScriptNode.Call("print_array", (object)new int[] { 1, 2, 3 }); // 1, 2, 3 // Note how the type of each array entry does not matter as long as it can be handled by the marshaller -.. warning:: +Warning: + As you can see, if the first argument of the called method is an array, you'll need to cast it as `object`. diff --git a/tutorials/scripting/debug/debugger_panel.md b/tutorials/scripting/debug/debugger_panel.md index 595508e..9679d8b 100644 --- a/tutorials/scripting/debug/debugger_panel.md +++ b/tutorials/scripting/debug/debugger_panel.md @@ -32,7 +32,8 @@ You can use the buttons in the top-right corner to: - **Break**. This button pauses the game's execution. - **Continue**. This button resumes the game after a breakpoint or pause. -.. warning:: +Warning: + Breakpoints won't break on code if it's `running in a thread ( doc_using_multiple_threads )`. diff --git a/tutorials/scripting/debug/overview_of_debugging_tools.md b/tutorials/scripting/debug/overview_of_debugging_tools.md index 5caa61e..e03395a 100644 --- a/tutorials/scripting/debug/overview_of_debugging_tools.md +++ b/tutorials/scripting/debug/overview_of_debugging_tools.md @@ -90,7 +90,8 @@ 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. -.. warning:: +Warning: + Breakpoints won't break on code if it's `running in a thread ( doc_using_multiple_threads )`. @@ -130,5 +131,6 @@ the nodes' parameters in the running project. ![](img/overview_remote.png) -.. note:: Some editor settings related to debugging can be found inside +Note: + Some editor settings related to debugging can be found inside the **Editor Settings**, under the **Network > Debug** and **Debugger** sections. diff --git a/tutorials/scripting/evaluating_expressions.md b/tutorials/scripting/evaluating_expressions.md index d398b48..7f3c1b3 100644 --- a/tutorials/scripting/evaluating_expressions.md +++ b/tutorials/scripting/evaluating_expressions.md @@ -13,7 +13,8 @@ An expression can be: if `base_instance` is set to a value other than `null` when calling `Expression.execute()`. -.. note:: +Note: + The Expression class is independent from GDScript. It's available even if you compile Godot with the GDScript module disabled. @@ -122,7 +123,8 @@ Associating a base instance allows doing the following: - Reference the instance's member variables (`var`) in the expression. - Call methods defined in the instance and use their return values in the expression. -.. warning:: +Warning: + Setting a base instance to a value other than `null` allows referencing constants, member variables, and calling all methods defined in the script diff --git a/tutorials/scripting/gdscript/gdscript_advanced.md b/tutorials/scripting/gdscript/gdscript_advanced.md index 9ad0cec..a4ec89e 100644 --- a/tutorials/scripting/gdscript/gdscript_advanced.md +++ b/tutorials/scripting/gdscript/gdscript_advanced.md @@ -170,7 +170,8 @@ that inherit `Reference` (the default if nothing is specified) will be freed when not used, but manual memory management is allowed too if inheriting manually from `Object`. -.. note:: +Note: + A value is **passed by value** when it is copied every time it's specified as a function parameter. One consequence of this is that the function cannot diff --git a/tutorials/scripting/gdscript/gdscript_basics.md b/tutorials/scripting/gdscript/gdscript_basics.md index ee1ba09..8c055a1 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.md +++ b/tutorials/scripting/gdscript/gdscript_basics.md @@ -16,7 +16,8 @@ flexibility for content creation and integration. History ~~~~~~~ -.. note:: +Note: + Documentation about GDScript's history has been moved to the `Frequently Asked Questions ( doc_faq_what_is_gdscript )`. @@ -564,7 +565,8 @@ assign to it:: # `d.test` is `d["test"]`. print(d[test]) -.. note:: +Note: + The bracket syntax can be used to access properties of any `Object`, not just Dictionaries. Keep in mind it will cause a @@ -687,7 +689,8 @@ possible to add explicit type specification:: Assigning a value of an incompatible type will raise an error. -.. note:: +Note: + Since arrays and dictionaries are passed by reference, constants are "flat". This means that if you declare a constant array or dictionary, it can still @@ -765,7 +768,8 @@ return early with the `return` keyword, but they can't return any value. func void_function() -> void: return # Can't return a value -.. note:: Non-void functions must **always** return a value, so if your code has +Note: + Non-void functions must **always** return a value, so if your code has branching statements (such as an `if`/`else` construct), all the possible paths must have a return. E.g., if you have a `return` inside an `if` block but not after it, the editor will raise an @@ -1095,7 +1099,8 @@ class will then appear with its new icon in the editor:: ![](img/class_name_editor_register_example.png) -.. warning:: +Warning: + If the script is located in the `res://addons/` directory, `name` will only cause the node to show up in the **Create New Node** dialog if @@ -1124,7 +1129,8 @@ Here's a class file example: print(Character) -.. note:: Godot's class syntax is compact: it can only contain member variables or +Note: + Godot's class syntax is compact: it can only contain member variables or functions. You can use static functions, but not static member variables. In the same way, the engine initializes variables every time you create an instance, and this includes arrays and dictionaries. This is in the spirit of thread @@ -1179,7 +1185,8 @@ in other languages):: func some_func(x): .some_func(x) # Calls the same function on the parent class. -.. note:: Default functions like `_init`, and most notifications such as +Note: + Default functions like `_init`, and most notifications such as `_enter_tree`, `_exit_tree`, `_process`, `_physics_process`, etc. are called in all parent classes automatically. There is no need to call them explicitly when overloading them. @@ -1289,7 +1296,8 @@ class resource is done by calling the `new` function on the class object:: Exports ~~~~~~~ -.. note:: +Note: + Documentation about exports has been moved to `doc_gdscript_exports`. @@ -1367,7 +1375,8 @@ placed at the top of the file:: See `doc_running_code_in_the_editor` for more information. -.. warning:: Be cautious when freeing nodes with `queue_free()` or `free()` +Warning: + Be cautious when freeing nodes with `queue_free()` or `free()` in a tool script (especially the script's owner itself). As tool scripts run their code in the editor, misusing them may lead to crashing the editor. @@ -1419,7 +1428,8 @@ to. To create custom signals for a class, use the `signal` keyword. # A signal named health_depleted. signal health_depleted -.. note:: +Note: + Signals are a `Callback ( https://en.wikipedia.org/wiki/Callback_(computer_programming) )`_ @@ -1490,7 +1500,8 @@ the `Object.connect()` method:: progress_bar.animate(old_value, new_value) ... -.. note:: +Note: + To use signals, your class has to extend the `Object` class or any type extending it like `Node`, `KinematicBody`, `Control`... diff --git a/tutorials/scripting/gdscript/gdscript_exports.md b/tutorials/scripting/gdscript/gdscript_exports.md index 9d33b84..6ef84b7 100644 --- a/tutorials/scripting/gdscript/gdscript_exports.md +++ b/tutorials/scripting/gdscript/gdscript_exports.md @@ -24,7 +24,8 @@ them visible and editable in the editor. This way, artists and game designers can modify values that later influence how the program runs. For this, a special export syntax is provided. -.. note:: +Note: + Exporting properties can also be done in other languages such as C#. The syntax varies depending on the language. @@ -230,10 +231,12 @@ handled and how they can be customized with `_get_property_list()` methods as described in `doc_accessing_data_or_logic_from_object`. -.. seealso:: For binding properties using the above methods in C++, see +See also: + For binding properties using the above methods in C++, see `doc_binding_properties_using_set_get_property_list`. -.. warning:: The script must operate in the `tool` mode so the above methods +Warning: + The script must operate in the `tool` mode so the above methods can work from within the editor. Properties @@ -261,7 +264,8 @@ how to make properties with advanced exports. * `type` is the type of the property from `Variant.Type`. -.. note:: The `float` type is called a real (`TYPE_REAL`) in the `Variant.Type` enum. +Note: + The `float` type is called a real (`TYPE_REAL`) in the `Variant.Type` enum. Attaching variables to properties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tutorials/scripting/gdscript/gdscript_styleguide.md b/tutorials/scripting/gdscript/gdscript_styleguide.md index 837097a..dde7b76 100644 --- a/tutorials/scripting/gdscript/gdscript_styleguide.md +++ b/tutorials/scripting/gdscript/gdscript_styleguide.md @@ -19,7 +19,8 @@ and ask fellow developers for insights. In general, keeping your code consistent in your projects and within your team is more important than following this guide to a tee. -.. note:: Godot's built-in script editor uses a lot of these conventions +Note: + Godot's built-in script editor uses a lot of these conventions by default. Let it help you. Here is a complete class example based on these guidelines: @@ -254,7 +255,8 @@ Surround functions and class definitions with two blank lines: Use one blank line inside functions to separate logical sections. -.. note:: We use a single line between classes and function definitions in the class reference and +Note: + We use a single line between classes and function definitions in the class reference and in short code snippets in this documentation. Line length @@ -409,7 +411,8 @@ This helps differentiate text comments from disabled code. #This is a comment. # print("This is disabled code") -.. note:: +Note: + In the script editor, to toggle the selected code commented, press :kbd:`Ctrl + K`. This feature adds a single # sign at the start @@ -708,7 +711,8 @@ variables, in that order. onready var gun = get_node("Gun") -.. note:: +Note: + The GDScript compiler evaluates onready variables right before the `_ready` callback. You can use that to cache node dependencies, that is to say, to get diff --git a/tutorials/scripting/gdscript/index.md b/tutorials/scripting/gdscript/index.md index 612f347..64e4e9a 100644 --- a/tutorials/scripting/gdscript/index.md +++ b/tutorials/scripting/gdscript/index.md @@ -13,7 +13,8 @@ GDScript warning_system gdscript_format_string -.. seealso:: +See also: + See `doc_gdscript_grammar` if you are interested in writing a third-party tool that interacts with GDScript, such as a linter or formatter. diff --git a/tutorials/scripting/gdscript/static_typing.md b/tutorials/scripting/gdscript/static_typing.md index 9532037..9fbcd54 100644 --- a/tutorials/scripting/gdscript/static_typing.md +++ b/tutorials/scripting/gdscript/static_typing.md @@ -15,7 +15,8 @@ or write code like you always did! Static types can be used on variables, constants, functions, parameters, and return types. -.. note:: +Note: + Typed GDScript is available since Godot 3.1. @@ -110,7 +111,8 @@ Currently you can use three types of… types: 3. Your own custom classes. Look at the new `name ( doc_gdscript_basics_class_name )` feature to register types in the editor. -.. note:: +Note: + You don't need to write type hints for constants, as Godot sets it automatically from the assigned value. But you can still do so to make the intent of your code clearer. @@ -174,7 +176,8 @@ As we're dealing with a custom type, if the `body` doesn't extend We can use this to check if the body is the player or not. We will also get full autocompletion on the player variable thanks to that cast. -.. note:: +Note: + If you try to cast with a built-in type and it fails, Godot will throw an error. @@ -207,7 +210,8 @@ green at the left of the script editor. Unsafe line (line 7) vs Safe Lines (line 6 and 8) -.. note:: +Note: + You can turn off safe lines or change their color in the editor settings. @@ -320,7 +324,8 @@ it's anything else, like an `Area2D`, or any node that doesn't extend Warning system -------------- -.. note:: +Note: + Documentation about the GDScript warning system has been moved to `doc_gdscript_warning_system`. diff --git a/tutorials/scripting/groups.md b/tutorials/scripting/groups.md index 2195cbc..776d7b9 100644 --- a/tutorials/scripting/groups.md +++ b/tutorials/scripting/groups.md @@ -63,7 +63,8 @@ It has three columns: The fields at the bottom allow you to add new groups or filter nodes in the second and third columns. -.. note:: Any node name that's greyed out means the node was added to the group +Note: + Any node name that's greyed out means the node was added to the group in a different scene and you cannot edit it here. This happens on scene instances in particular. diff --git a/tutorials/scripting/nodes_and_scene_instances.md b/tutorials/scripting/nodes_and_scene_instances.md index 6d02e45..abf5f56 100644 --- a/tutorials/scripting/nodes_and_scene_instances.md +++ b/tutorials/scripting/nodes_and_scene_instances.md @@ -65,7 +65,8 @@ gdscript GDScript tween = get_node("ShieldBar/Tween") ``` -.. note:: As with file paths, you can use ".." to get a parent node. The best +Note: + As with file paths, you can use ".." to get a parent node. The best practice is to avoid doing that though not to break encapsulation. You can also start the path with a forward slash to make it absolute, in which case your topmost node would be diff --git a/tutorials/scripting/overridable_functions.md b/tutorials/scripting/overridable_functions.md index 73fa7a0..145956e 100644 --- a/tutorials/scripting/overridable_functions.md +++ b/tutorials/scripting/overridable_functions.md @@ -8,7 +8,8 @@ every frame or on specific events, like when they enter the scene tree. This document presents the ones you'll use most often. -.. seealso:: Under the hood, these functions rely on Godot's low-level +See also: + Under the hood, these functions rely on Godot's low-level notifications system. To learn more about it, see `doc_godot_notifications`. @@ -24,7 +25,8 @@ Most of the time, you'll use `_ready()` instead. This function is called only once in a node's lifetime, after `_enter_tree()`. `_ready()` ensures that all children have entered the scene tree first, so you can safely call `get_node()` on it. -.. seealso:: To learn more about getting node references, read +See also: + To learn more about getting node references, read `doc_nodes_and_scene_instances`. Another related callback is `_exit_tree()`, which the engine calls every time diff --git a/tutorials/scripting/pausing_games.md b/tutorials/scripting/pausing_games.md index 1d60645..7125820 100644 --- a/tutorials/scripting/pausing_games.md +++ b/tutorials/scripting/pausing_games.md @@ -28,7 +28,8 @@ Doing this will cause two things. First, 2D and 3D physics will be stopped for all nodes. Second, the behavior of certain nodes will stop or start depending on their process mode. -.. note:: The physics servers can be made active while the game is +Note: + The physics servers can be made active while the game is paused by using their `set_active` methods. Process Modes diff --git a/tutorials/scripting/resources.md b/tutorials/scripting/resources.md index fd7eefe..f9b9604 100644 --- a/tutorials/scripting/resources.md +++ b/tutorials/scripting/resources.md @@ -61,7 +61,8 @@ The switch between built-in and external resources happens when you save the scene. In the example above, if you erase the path `"res://robi.png)"` and save, Godot will save the image inside the `.tscn` scene file. -.. note:: +Note: + Even if you save a built-in resource, when you instance a scene multiple times, the engine will only load one copy of it. @@ -204,7 +205,8 @@ gdscript GDScript print(stats.health) # Prints '10'. ``` -.. note:: +Note: + Resource scripts are similar to Unity's ScriptableObjects. The Inspector provides built-in support for custom resources. If desired though, users @@ -259,7 +261,8 @@ gdscript GDScript CurveTables are the same thing, except mapped to an Array of float values or a `Curve` resource object. -.. warning:: +Warning: + Beware that resource files (\*.tres/\*.res) will store the path of the script they use in the file. When loaded, they will fetch and load this script as an diff --git a/tutorials/scripting/singletons_autoload.md b/tutorials/scripting/singletons_autoload.md index e929536..2a4a9d7 100644 --- a/tutorials/scripting/singletons_autoload.md +++ b/tutorials/scripting/singletons_autoload.md @@ -35,7 +35,8 @@ Using this concept, you can create objects that: Autoloading nodes and scripts can give us these characteristics. -.. note:: +Note: + Godot won't make an AutoLoad a "true" singleton as per the singleton design pattern. It may still be instanced more than once by the user if desired. @@ -52,7 +53,8 @@ AutoLoad You can create an AutoLoad to load a scene or a script that inherits from `Node`. -.. note:: +Note: + When autoloading a script, a `Node` will be created and the script will be attached to it. This node will be added to the root viewport before any @@ -97,7 +99,8 @@ you'll see the autoloaded nodes appear: ![](img/autoload_runtime.png) -.. warning:: +Warning: + Autoloads must **not** be removed using `free()` or `queue_free()` at runtime, or the engine will crash. @@ -219,7 +222,8 @@ gdscript GDScript Run the project and test that you can switch between scenes by pressing the button. -.. note:: +Note: + When scenes are small, the transition is instantaneous. However, if your scenes are more complex, they may take a noticeable amount of time to appear. diff --git a/tutorials/shaders/advanced_postprocessing.md b/tutorials/shaders/advanced_postprocessing.md index f63b582..a88e19d 100644 --- a/tutorials/shaders/advanced_postprocessing.md +++ b/tutorials/shaders/advanced_postprocessing.md @@ -82,7 +82,8 @@ the uniform variable `DEPTH_TEXTURE`. float depth = texture(DEPTH_TEXTURE, SCREEN_UV).x; -.. note:: Similar to accessing the screen texture, accessing the depth texture is only +Note: + Similar to accessing the screen texture, accessing the depth texture is only possible when reading from the current viewport. The depth texture cannot be accessed from another viewport to which you have rendered. @@ -176,7 +177,8 @@ Now, attach a script to the MeshInstance and use the following code: # Create mesh from mesh_array: mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, mesh_array) -.. note:: The triangle is specified in normalized device coordinates. Recall, NDC run +Note: + The triangle is specified in normalized device coordinates. Recall, NDC run from `-1` to `1` in both the `x` and `y` directions. This makes the screen `2` units wide and `2` units tall. In order to cover the entire screen with a single triangle, use a triangle that is `4` units wide and `4` diff --git a/tutorials/shaders/custom_postprocessing.md b/tutorials/shaders/custom_postprocessing.md index 0ab61f4..5b8a254 100644 --- a/tutorials/shaders/custom_postprocessing.md +++ b/tutorials/shaders/custom_postprocessing.md @@ -17,7 +17,8 @@ The easiest way to implement a custom post-processing shader is to use Godot's b the screen texture. If you're not familiar with this, you should read the `Screen Reading Shaders Tutorial ( doc_screen-reading_shaders )` first. -.. note:: +Note: + As of the time of writing, Godot does not support rendering to multiple buffers at the same time. Your post-processing shader will not have access to normals or other render passes. You only have @@ -31,7 +32,8 @@ You will need a `Viewport` to render your scene to, and a scene to render your ( ViewportContainer )` to display your `Viewport` on the entire screen or inside another `Control` node. -.. note:: +Note: + Rendering using a `Viewport` gives you control over how the scene render, including the framerate, and you can use the @@ -50,7 +52,8 @@ your main scene. For this tutorial, we will use a field of random boxes: Add a new `ShaderMaterial` to the `ViewportContainer`, and assign a new shader resource to it. You can access your rendered `Viewport` with the built-in `TEXTURE` uniform. -.. note:: +Note: + You can choose not to use a `ViewportContainer`, but if you do so, you will need to create your own uniform in the shader and pass the `Viewport` texture in @@ -89,7 +92,8 @@ Copy the following code to your shader. The above code is a single pass edge det COLOR.xyz = col; } -.. note:: +Note: + The Sobel filter reads pixels in a 9x9 grid around the current pixel and adds them together, using weight. What makes it interesting is that it assigns weights to each pixel; +1 for each of the eight around the @@ -118,7 +122,8 @@ Godot will render the bottom `Viewport` node first. So if the order of the passe shaders, make sure that you assign the shader you want to apply first to the lowest `ViewportContainer` in the tree. -.. note:: +Note: + You can also render your Viewports separately without nesting them like this. You just need to use two Viewports and to render them one after the other. diff --git a/tutorials/shaders/introduction_to_shaders.md b/tutorials/shaders/introduction_to_shaders.md index 41da973..698213e 100644 --- a/tutorials/shaders/introduction_to_shaders.md +++ b/tutorials/shaders/introduction_to_shaders.md @@ -38,7 +38,8 @@ look like this. COLOR = some_color; } -.. note:: +Note: + The graphics card calls the `fragment()` function once or more for each pixel it has to draw. More on that below. @@ -62,7 +63,8 @@ In Godot, shaders are made up of three main functions: `vertex()`, 3. The `light()` function runs for every pixel and for every light. It takes variables from the `fragment()` function and from its previous runs. -.. warning:: +Warning: + The `light()` function won't run if the `vertex_lighting` render mode is enabled, or if **Rendering > Quality > Shading > Force Vertex Shading** is diff --git a/tutorials/shaders/screen-reading_shaders.md b/tutorials/shaders/screen-reading_shaders.md index dc5a338..99cfe5d 100644 --- a/tutorials/shaders/screen-reading_shaders.md +++ b/tutorials/shaders/screen-reading_shaders.md @@ -39,7 +39,8 @@ a chunk of the screen, it also does an efficient separatable gaussian blur to it This allows for not only reading from the screen, but reading from it with different amounts of blur at no cost. -.. note:: +Note: + Mipmaps are not generated in GLES2 due to poor performance and compatibility with older devices. diff --git a/tutorials/shaders/shader_materials.md b/tutorials/shaders/shader_materials.md index 2bb9aaf..633e4f3 100644 --- a/tutorials/shaders/shader_materials.md +++ b/tutorials/shaders/shader_materials.md @@ -62,7 +62,8 @@ your visual shader to a text shader. ![](img/visual_shader_code.png) -.. note:: +Note: + To learn more about visual shaders, read `doc_visual_shaders`. @@ -75,7 +76,8 @@ and select the convert option. ![](img/shader_material_convert.png) -.. note:: +Note: + Using the convert option will turn the SpatialMaterial into a ShaderMaterial with a text shader, not a visual shader. diff --git a/tutorials/shaders/shader_reference/canvas_item_shader.md b/tutorials/shaders/shader_reference/canvas_item_shader.md index ba2af70..41ffa9f 100644 --- a/tutorials/shaders/shader_reference/canvas_item_shader.md +++ b/tutorials/shaders/shader_reference/canvas_item_shader.md @@ -78,7 +78,8 @@ it manually with the following code: VERTEX = (EXTRA_MATRIX * (WORLD_MATRIX * vec4(VERTEX, 0.0, 1.0))).xy; } -.. note:: `WORLD_MATRIX` is actually a modelview matrix. It takes input in local space and transforms it +Note: + `WORLD_MATRIX` is actually a modelview matrix. It takes input in local space and transforms it into view space. In order to get the world space coordinates of a vertex, you have to pass in a custom uniform like so: diff --git a/tutorials/shaders/shader_reference/shading_language.md b/tutorials/shaders/shader_reference/shading_language.md index a3c9205..c70720d 100644 --- a/tutorials/shaders/shader_reference/shading_language.md +++ b/tutorials/shaders/shader_reference/shading_language.md @@ -251,7 +251,8 @@ Arrays also have a built-in function `.length()` (not to be confused with the bu // ... } -.. note:: +Note: + If you use an index below 0 or greater than array size - the shader will crash and break rendering. To prevent this, use `length()`, `if`, or `clamp()` functions to ensure the index is between 0 and the array's length. Always carefully test and check your code. If you pass a constant expression or a simple number, the editor will check its bounds to prevent this crash. @@ -372,7 +373,8 @@ Godot Shading language supports the most common types of flow control: Keep in mind that, in modern GPUs, an infinite loop can exist and can freeze your application (including editor). Godot can't protect you from this, so be careful not to make this mistake! -.. warning:: +Warning: + When exporting a GLES2 project to HTML5, WebGL 1.0 will be used. WebGL 1.0 doesn't support dynamic loops, so shaders using those won't work there. @@ -547,7 +549,8 @@ You can set uniforms in the editor in the material. Or you can set them through material.set_shader_param("some_value", some_value) -.. note:: The first argument to `set_shader_param` is the name of the uniform in the shader. It +Note: + The first argument to `set_shader_param` is the name of the uniform in the shader. It must match *exactly* to the name of the uniform in the shader or else it will not be recognized. Any GLSL type except for *void* can be a uniform. Additionally, Godot provides @@ -609,7 +612,8 @@ to shaders, Godot converts the type automatically. Below is a table of the corre | **Transform2D** | **mat4** | +-----------------+-----------+ -.. note:: Be careful when setting shader uniforms from GDScript, no error will be thrown if the +Note: + Be careful when setting shader uniforms from GDScript, no error will be thrown if the type does not match. Your shader will just exhibit undefined behavior. Uniforms can also be assigned default values: @@ -637,7 +641,8 @@ Built-in functions A large number of built-in functions are supported, conforming to GLSL ES 3.0. When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature is used, it can be scalar or vector. -.. note:: For a list of the functions that are not available in the GLES2 backend, please see the +Note: + For a list of the functions that are not available in the GLES2 backend, please see the `Differences between GLES2 and GLES3 doc ( doc_gles2_gles3_differences )`. +------------------------------------------------------------------------+---------------------------------------------------------------+ diff --git a/tutorials/shaders/shader_reference/spatial_shader.md b/tutorials/shaders/shader_reference/spatial_shader.md index 6dae977..fa7b386 100644 --- a/tutorials/shaders/shader_reference/spatial_shader.md +++ b/tutorials/shaders/shader_reference/spatial_shader.md @@ -188,7 +188,8 @@ shader, this value can be used as desired. | in vec4 **INSTANCE_CUSTOM** | Instance custom data (for particles, mostly). | +--------------------------------------+--------------------------------------------------------+ -.. note:: +Note: + `MODELVIEW_MATRIX` combines both the `WORLD_MATRIX` and `INV_CAMERA_MATRIX` and is better suited when floating point issues may arise. For example, if the object is very far away from the world origin, you may run into floating point issues when using the seperated `WORLD_MATRIX` and `INV_CAMERA_MATRIX`. @@ -294,7 +295,8 @@ these properties, and if you don't write to them, Godot will optimize away the c | in vec2 **POINT_COORD** | Point Coordinate for drawing points with POINT_SIZE. | +-----------------------------------+--------------------------------------------------------------------------------------------------+ -.. note:: +Note: + Shaders going through the transparent pipeline when `ALPHA` is written to may exhibit transparency sorting issues. Read the @@ -325,11 +327,13 @@ Below is an example of a custom light function using a Lambertian lighting model If you want the lights to add together, add the light contribution to `DIFFUSE_LIGHT` using `+=`, rather than overwriting it. -.. warning:: +Warning: + In GLES2, lights will always be added together even if you override `DIFFUSE_LIGHT` using `=`. This is due to lighting being computed in multiple passes (one for each light), unlike GLES3. -.. warning:: +Warning: + The `light()` function won't be run if the `vertex_lighting` render mode is enabled, or if @@ -389,7 +393,8 @@ If you want the lights to add together, add the light contribution to `DIFFUSE_L | out vec3 **SPECULAR_LIGHT** | Specular light result. | +-----------------------------------+-----------------------------------------------------+ -.. note:: +Note: + Shaders going through the transparent pipeline when `ALPHA` is written to may exhibit transparency sorting issues. Read the diff --git a/tutorials/shaders/shaders_style_guide.md b/tutorials/shaders/shaders_style_guide.md index 6b39f13..a24d2dd 100644 --- a/tutorials/shaders/shaders_style_guide.md +++ b/tutorials/shaders/shaders_style_guide.md @@ -20,7 +20,8 @@ and ask fellow developers for insights. In general, keeping your code consistent in your projects and within your team is more important than following this guide to a tee. -.. note:: Godot's built-in shader editor uses a lot of these conventions +Note: + Godot's built-in shader editor uses a lot of these conventions by default. Let it help you. Here is a complete shader example based on these guidelines: @@ -211,7 +212,8 @@ Don't use multiline comment syntax if your comment can fit on a single line: /* This is another comment. */ -.. note:: +Note: + In the shader editor, to make the selected code a comment (or uncomment it), press :kbd:`Ctrl + K`. This feature adds or removes `//` at the start of diff --git a/tutorials/shaders/using_viewport_as_texture.md b/tutorials/shaders/using_viewport_as_texture.md index 1016114..1c947da 100644 --- a/tutorials/shaders/using_viewport_as_texture.md +++ b/tutorials/shaders/using_viewport_as_texture.md @@ -12,7 +12,8 @@ of making a procedural planet like the one below: ![](img/planet_example.png) -.. note:: This tutorial does not cover how to code a dynamic atmosphere like the one this planet has. +Note: + This tutorial does not cover how to code a dynamic atmosphere like the one this planet has. This tutorial assumes you are familiar with how to set up a basic scene including: a `Camera`, a @@ -52,7 +53,8 @@ will ensure that the `ColorRect`. Next, we add a `Shader Material `New ShaderMaterial`). -.. note:: Basic familiarity with shading is recommended for this tutorial. However, even if you are new +Note: + Basic familiarity with shading is recommended for this tutorial. However, even if you are new to shaders, all the code will be provided, so you should have no problem following along. ColorRect > CanvasItem > Material > Material > click / Edit > ShaderMaterial > Shader > `New Shader` > click / Edit: @@ -122,7 +124,8 @@ have pinching at the poles. This pinching is due to the way Godot maps textures `SpatialMaterial`. It uses a projection technique called equirectangular projection, which translates a spherical map onto a 2D plane. -.. note:: If you are interested in a little extra information on the technique, we will be converting from +Note: + If you are interested in a little extra information on the technique, we will be converting from spherical coordinates into Cartesian coordinates. Spherical coordinates map the longitude and latitude of the sphere, while Cartesian coordinates are, for all intents and purposes, a vector from the center of the sphere to the point. @@ -178,7 +181,8 @@ to make the planet. We will be using this noise function directly from a `Shader dot(hash(i + vec3(1.0, 1.0, 1.0)), f - vec3(1.0, 1.0, 1.0)), u.x), u.y), u.z ); } -.. note:: All credit goes to the author, Inigo Quilez. It is published under the `MIT` licence. +Note: + All credit goes to the author, Inigo Quilez. It is published under the `MIT` licence. Now to use `noise`, add the following to the `fragment` function: @@ -189,7 +193,8 @@ Now to use `noise`, add the following to the `fragment` function: ![](img/planet_noise.png) -.. note:: In order to highlight the texture, we set the material to unshaded. +Note: + In order to highlight the texture, we set the material to unshaded. You can see now that the noise indeed wraps seamlessly around the sphere. Although this looks nothing like the planet you were promised. So let's move onto something more colorful. diff --git a/tutorials/shaders/your_first_shader/your_first_2d_shader.md b/tutorials/shaders/your_first_shader/your_first_2d_shader.md index 210b4b1..525837e 100644 --- a/tutorials/shaders/your_first_shader/your_first_2d_shader.md +++ b/tutorials/shaders/your_first_shader/your_first_2d_shader.md @@ -15,7 +15,8 @@ This tutorial will focus on the practical aspects of writing shader programs by walking you through the process of writing a shader with both vertex and fragment functions. This tutorial targets absolute beginners to shaders. -.. note:: If you have experience writing shaders and are just looking for an +Note: + If you have experience writing shaders and are just looking for an overview of how shaders work in Godot, see the `Shading Reference